implement DEV workspace and project automation authority

This commit is contained in:
2026-09-29 07:09:37 +01:00
parent 0ddf3ef70d
commit e3c3b2cbb7
62 changed files with 2180 additions and 354 deletions
@@ -18,14 +18,16 @@ Define the physical and functional boundary that makes the Studio consumable by
## Authority and Precedence
This specification implements `DEC-0059` and is the normative architecture reference for the Studio split. More specific domain specs may refine behavior, but they MUST preserve the dependency direction defined here.
This specification implements `DEC-0059` and the accepted `DEC-0060` AI-first baseline. It is the normative architecture reference for the Studio split. DEC-0060 adds shared automation services and the narrowly scoped local MCP server exception below; it does not replace the module boundaries or dependency direction.
The [DEV and Automation Specification](10.%20DEV%20and%20Automation%20Specification.md) defines project authority, document handoff, operations, captures and delivery gates. More specific domain specs MUST preserve the dependency direction defined here. Normative requirements describe the target contract, not a claim that every delivery phase is already implemented.
## Architectural Model
The Studio is a set of project and tooling services consumed by adapters:
```text
JavaFX UI ──> Studio API <── future non-visual adapters
JavaFX UI ──> Studio API <── local MCP adapter <── external coding agent
│
▼
Studio Core
@@ -34,7 +36,7 @@ JavaFX UI ──> Studio API <── future non-visual adapters
application/infrastructure adapters
```
JavaFX is the current human adapter. A future agent surface is not part of this specification, but MUST be able to consume the same neutral services instead of simulating UI interaction.
JavaFX is the human adapter; DEV is its authorization and observation workspace. The local MCP adapter exposes the same neutral services to an external coding agent. Neither adapter MAY simulate the other adapter's UI or duplicate project authority, build/pack or execution orchestration. The external client owns the agent, chat, model/provider credentials and coding loop.
## Physical Modules
@@ -53,7 +55,8 @@ The public Studio API MUST be plain Java and MUST NOT depend on:
- JavaFX;
- Spring Framework, Spring Boot, or Spring Modulith;
- AI, MCP, or provider SDKs;
- HTTP, AI, MCP, or provider SDKs;
- concrete runtime-wire or MCP transport DTOs;
- concrete compiler, Packer, LSP, or runtime implementations;
- `p.studio.core` or `p.studio.ui.javafx` internals.
@@ -68,6 +71,7 @@ Core classes MUST be POJOs with constructor injection and MUST remain testable w
The core module MUST NOT:
- depend on JavaFX or UI packages;
- depend on HTTP/MCP SDKs, Spring, or concrete external protocol DTOs;
- call `Platform.runLater`;
- perform navigation or workspace selection;
- use presentation severity or visual state as domain semantics;
@@ -76,11 +80,11 @@ The core module MUST NOT:
The functional core modules are:
- `project`: project identity, catalog, creation, paths, setup, and restoration state;
- `session`: open-project lifecycle, ordered cleanup, execution ownership, and the LSP lifecycle port;
- `session`: open-project lifecycle, project-scoped automation authority, document handoff, ordered cleanup, execution ownership, and the LSP lifecycle port;
- `assets`: Studio-owned asset projections, metadata, policies, non-visual sessions, validation, and workflow orchestration;
- `shipper`: build/pack coordination, manifest generation, artifacts, and neutral logs/results;
- `runtime`: runtime settings, handshake, process/client lifecycle, and technical logs;
- `execution`: play/stop state, cancellation, shutdown, and orchestration of shipper and runtime.
- `runtime`: runtime settings, handshake, process/client lifecycle, canonical capture contracts, and technical logs; human Debug and headless automation retain distinct protocol/lifecycle boundaries;
- `execution`: play/stop and automation operation state, cancellation, shutdown, and orchestration of shipper and runtime.
The functional dependency direction MUST remain:
@@ -92,6 +96,10 @@ execution --> project, shipper, runtime
session --> project, execution, LSP port
```
Session-owned authority lifetime MUST NOT introduce reverse functional dependencies from `assets`, `shipper`, `runtime` or `execution` to the concrete `session` module. Service entry points MUST receive the shared authority through neutral contracts and composition, not reach into JavaFX or concrete session implementations. Document-handoff participants likewise use neutral contracts; their presentation buffers remain adapter-owned.
Manual Debug and project mutation MUST enforce the same project authority as automation. Disabled UI buttons alone are not authorization. Grant, acquisition, operation completion and authority return MUST remain distinct lifecycle facts.
## JavaFX Adapter Rules
The JavaFX module MUST depend on Studio API contracts rather than core or provider implementations. It owns visual state, UI events, navigation, FX-thread transitions, CSS, fonts, locale bindings, and lifecycle of visual objects.
@@ -104,7 +112,11 @@ The JavaFX module MUST NOT directly invoke compiler implementations, `p.packer`,
## Spring Composition
Spring Boot MUST be used only by `prometeu-app` as a non-web composition and lifecycle mechanism. The application MUST start with `WebApplicationType.NONE` or an equivalent guarantee and MUST NOT introduce Spring Web, WebFlux, Data, AI, durable events, or a web server without a later accepted decision.
Spring Boot MUST be used only by `prometeu-app` for desktop composition and lifecycle. `WebApplicationType.NONE` remains a valid composition mode with an explicitly managed local HTTP adapter. Conformance MUST NOT impose an unconditional absence of a web server that would forbid the DEC-0060 MCP exception.
The sole accepted HTTP-server use is an in-process MCP Streamable HTTP endpoint at `127.0.0.1:<OS-assigned-port>/mcp`. The application/infrastructure adapter MUST own its transport dependencies and lifecycle. It MUST require a random per-Studio-start token, validate Origin and reject unexpected origins, and stop with Studio. Connection authentication MUST NOT grant project/task authority. The token MUST NOT be stored in versioned files, and restart requires refreshed client configuration.
This exception does not authorize a web UI, remote binding, general-purpose web application, accounts, OAuth, or a stdio MCP bridge. HTTP/MCP dependencies MUST NOT enter API/Core or the JavaFX adapter. Spring Data, Spring AI and durable event infrastructure remain outside the accepted architecture.
Spring configuration MAY create core services, infrastructure adapters, and a JavaFX composition factory. It MUST NOT use field injection, context lookup, broad service bags, or a replacement static container.
@@ -125,6 +137,9 @@ A narrow consumer-owned gateway MUST be used when the available integration is c
| `session` | LSP | Neutral session-owned lifecycle port |
| `runtime` | external runtime/process | Narrow runtime-owned gateway |
| JavaFX UI | Studio | Studio API only |
| MCP adapter | Studio | Studio API only; transport DTO translation belongs to infrastructure |
The headless gateway MUST start `prometeu headless --stdio` from the configured runtime installation and map the runtime-owned JSONL contract to neutral results. It MUST NOT reuse the human DevTools connection, introduce a native Rust/Java binding, search/download another runtime, or redefine firmware/VM semantics. Runtime process supervision and the existing project LSP client belong to application/infrastructure adapters, not UI controls.
`p.packer` remains an autonomous domain and MUST NOT depend on any `p.studio` package. Studio MUST NOT copy or assume ownership of Packer semantics.
@@ -138,21 +153,27 @@ Long-running build, pack, runtime, and execution work MUST expose a neutral oper
Core services MUST submit such work through the neutral `OperationExecutor` port. `prometeu-app` owns the executor-backed implementation and its thread lifecycle; JavaFX consumes `OperationHandle` completion and snapshots and performs only the required FX-thread projection.
Automation MUST reuse this operation boundary. Task authority is separate from operation success, guest fault, infrastructure failure or cancellation. Revocation MUST invalidate task authority before stopping managed work, refreshing open documents and releasing manual control. Closing the project or application MUST perform that cleanup; changing the active workspace MUST NOT.
Build and advance admission MUST return a promptly queryable operation identity. Task-scoped, in-memory `clientRequestId` deduplication MUST live behind the shared services, not in a second MCP orchestrator. Runtime `requestId` is wire correlation and MUST NOT be treated as that deduplication mechanism. Late calls/results MUST NOT restore revoked authority.
## Conformance Gates
The architecture is conformant only when all of the following hold together:
- API and core compile without JavaFX or Spring dependencies;
- API and core compile without JavaFX, Spring, HTTP/MCP SDKs or concrete transport DTO dependencies;
- UI has no dependency on core or concrete external providers;
- `ApplicationModules.verify()` succeeds for the exclusive `p.studio.core` root;
- the application boots and shuts down in non-web mode;
- the desktop application boots and shuts down with no web exposure other than the authorized loopback MCP endpoint, whose transport is lifecycle-managed by the app;
- MCP and JavaFX consume shared authorization and operations; grant/Debug exclusion and cleanup are enforced in services;
- `Container`, `AppContainer`, compatibility allowlists, and the mixed module are absent;
- unit, integration, architecture, packaging, and desktop smoke tests pass;
- no service locator or context lookup replaces the removed static container.
## Non-Goals
- creating an agent or MCP module;
- embedding an agent, chat or provider adapter;
- adding a second orchestration/authorization implementation inside MCP;
- replacing JavaFX with a web UI;
- migrating the Studio to Rust, Electron, Tauri, or a parallel rewrite;
- redesigning compiler, Packer, LSP, or runtime semantics;