@@ -6,7 +6,7 @@ Purpose: Define the normative shell structure of the Studio UI.
## Authority and Precedence
This specification consolidates the accepted Studio shell decision into normative form.
This specification consolidates the accepted Studio shell decision into normative form. DEC-0060 adds DEV and project-scoped automation authority; its detailed behavior is owned by the [DEV and Automation Specification](10.%20DEV%20and%20Automation%20Specification.md).
## Normative Inputs
@@ -46,10 +46,13 @@ The baseline workspace set includes:
- Asset Management;
- Debugger/Profiler;
- DEV, for granting/reclaiming project control and observing external-agent automation;
- Shipper, temporarily represented by the current `BuilderWorkspace`.
`BuilderWorkspace` is transitional and must not be treated as a long-term architectural reference for the final shipping surface.
DEV MUST remain separate from human Debug and MUST NOT offer chat or manual Play/input for the headless session. Selecting, hiding or switching away from DEV MUST NOT grant or release project authority. The shell's always-visible run surface remains visible, but conflicting manual actions MUST be unavailable while project control is ceded, including while waiting for an agent. Services MUST enforce the same exclusion; shell bindings alone are insufficient.
## Workspace Architecture Model
The shell-level workspace host exists to mount independently authored workspaces under one Studio contract.
MUST, MUST NOT and MAY express requirements, prohibitions and permissions.
Implementation MUST NOT weaken this accepted baseline; substantive ambiguity
requires explicit decision review rather than a guessed implementation rule.
## 1. Shared Services and Protocol Boundaries
JavaFX and MCP MUST consume the same neutral API/Core authority, sessions,
operations and orchestration. Neither adapter MAY simulate UI actions or
implement a parallel permission/build/pack/execution system.
| Boundary | Owner and responsibility |
| --- | --- |
| Studio API | Plain-Java contracts, identities, snapshots, typed outcomes, diagnostics and ports; no toolkit, framework or concrete wire DTOs |
| Studio Core | Project/session authority, guards, operations, build/pack/runtime coordination and ordered cleanup; testable without JavaFX or Spring |
| JavaFX DEV | Human grant/reclaim actions, presentation, localization, canvas, subscriptions and FX-thread projection |
| Application/infrastructure | MCP HTTP transport, process supervision, runtime JSONL translation, existing project LSP client, lifecycle and packaging |
MCP Streamable HTTP, runtime JSONL/stdio, and human Debug/DevTools MUST remain
distinct protocols with distinct lifecycles. A native Rust/Java binding is not
the chosen runtime boundary. Compiler, LSP, Packer and runtime semantics MUST
NOT be reimplemented in Studio.
The functional dependency graph in spec 9 MUST remain unchanged. Services
requiring guards MUST receive shared authority through neutral contracts and
composition, not depend on concrete session implementations or UI state.
## 2. Project Authority and Control States
Authority MUST belong to an open project session, not a tab, focused window,
HTTP connection or UI component. The agent MUST supply a project root; Studio
MUST validate it against an open project and use explicit project identity.
Window focus MUST NOT implicitly select a call's target.
Connection authentication, human project grant and task control identity MUST
be separate checks. At most one task MAY own a project's grant. Acquisition
without a prior human grant MUST fail. A task identity MUST be required for
authorized work and MUST NOT be reusable for another project or revoked task.
| State | Admission and permitted behavior | Exit |
| --- | --- | --- |
| Manual control | Human editing/Debug; grant only with no active Debug or conflicting managed work, and successful document handoff | Human grant enters waiting |
| Waiting for agent | Grant already blocks conflicting manual work; authenticated agent can acquire; human can reclaim without an agent connection | Acquisition enters working; reclaim enters returning |
| Agent working | One acquired task uses its valid identity; developer can inspect, navigate and reclaim | Explicit task release or human revoke enters returning |
| Returning control | Prior authority is invalid; stop managed work and refresh documents; manual conflicting actions remain blocked | Manual control only after cleanup/handoff |
Grant and acquisition MUST be enforced atomically with conflicting operation
admission. Concurrent acquisition MUST NOT create two owners. Project-local
authority MUST NOT become a global Studio lock.
Human Debug active MUST prevent grant. From grant onward, including waiting
and silence, Studio MUST prevent manual editing, Debug, build and other
conflicting project mutation. Guards MUST apply at service entry points as
well as UI bindings. Navigation, inspection and monitoring remain available.
An operation finishing, failing compilation, raising a guest fault or losing
its runtime session MUST NOT release task authority. Silence, client
disconnection and waiting MUST NOT cause expiration or automatic resumption.
There is no heartbeat or silence timeout in this baseline.
## 3. Grant and Saved-Document Handoff
Grant MUST cover Studio-owned unsaved buffers/drafts, including dirty asset
editing surfaces; it MUST NOT assume that source files are the only editable
project content.
If such content is dirty, DEV MUST offer **Save all and grant** or **Cancel**.
Grant MUST follow successful saves; user cancellation or save failure MUST NOT
cede control. Clean projects do not require a code snapshot, clean Git tree or
commit. Document participants MUST use neutral handoff contracts without moving
presentation buffers or JavaFX types into Core.
The agent edits the actual project folder with native external tools. Build
MUST use saved files, and the existing project LSP client MUST synchronize
saved content before semantic queries. Studio MUST NOT claim to save external
unsaved buffers or protect against concurrent external writes.
On authority return, Studio MUST refresh open documents from disk and MUST NOT
reapply stale buffers over agent changes. Revocation/cancellation MUST preserve
edits already made. There is no later Apply/merge step or Studio-owned code
rollback. Review, integrity, Git commits and recovery remain developer duties.
SDK/external libraries MUST be consultable but MUST NOT be edited by the
game-authoring task. Editable local libraries MUST be inside project scope.
Unsupported capabilities or required SDK changes MUST be reported as limitations,
not silently implemented outside that scope. This does not prohibit the runtime
engineering delivery that prepared this integration.
## 4. Return, Revocation and Closure
Explicit release and human reclaim MUST follow this order:
1. Invalidate task authority and reject new or delayed calls under the old identity.
2. Cancel/stop managed work and shut down owned runtime processes.
3. Refresh open documents from saved project content, without stale writeback.
4. Release conflicting manual operations and present manual control.
Late completions MUST NOT resurrect a revoked task or restore its authority.
Cleanup MUST NOT advertise manual control before managed work is stopped and
document refresh is complete. Diagnostics MUST distinguish cleanup failure from
a successful return; operation outcome and authorization state are not the same.
Reclaim MUST also work while waiting for an agent or after an operation failure.
Another task MUST require a new human grant. Closing/hiding/switching DEV MUST
NOT release control. Closing the project or Studio MUST revoke authority and
stop managed processes before teardown of their providers/executors. Reopening
MUST start in manual control, even when restoring DEV as the selected workspace.
Studio cannot stop direct writes by the external coding client. The UI and
connection instructions MUST tell the developer to stop that client separately;
reclaim is not an operating-system filesystem lock or a rollback guarantee.
## 5. DEV Workspace Contract
DEV MUST expose:
- **Grant control to AI** (`Ceder controle à IA`) and **Interrupt and reclaim control** (`Interromper e retomar controle`);
- the four control states, project identity, current managed operation and diagnostics;
- a canonical-image canvas with session/build/logical-frame/render-frame identity and stale status;
- a short history of Studio calls, not an independent code history;
- **Copy MCP configuration**, plus short connection/use instructions when the real MCP composition is available.
Actions MUST reflect shared service authority. DEV MUST NOT own a duplicate
lock or release authority when disposing visual subscriptions. Presentation
updates MUST follow the existing FX-thread, theme, localization and workspace
lifecycle rules.
DEV MUST NOT contain chat, provider settings, manual headless Play/input or
concurrent human control of the agent's execution. Human play/testing remains
in Debug with its existing host/protocol/lifecycle, subject to symmetric guards.
“Agent working” means the task has been acquired; it is not a claim to observe
all external edits, reasoning or conversation.
Without a real composed MCP endpoint, configuration copy MUST be unavailable
rather than produce a fabricated endpoint or token. Test doubles MAY supply
operations/captures to isolated tests, never masquerade as product execution.
## 6. Operations and Lost Responses
Automation MUST reuse the neutral operation executor/handle boundary: stable
| Operations | Query, lookup by client request identity and cancel | Valid project/task identity |
MCP capture responses MUST expose image content plus structured metadata;
clients MUST NOT need to parse logs or fetch a temporary file to obtain pixels.
Generic shell, generic file editing, Git, publication and out-of-project changes
MUST NOT be exposed as shortcuts around these specialized services. Studio
grant does not override the external client's own permission policy or require
a new human confirmation for every authorized Studio operation.
## 9. Project Language Context and References
The project manifest MUST be authoritative for primary language and dependencies;
there is no parallel AI-only language configuration. PBS is the project-creation
default, not a fallback for an unknown declared language. Installed compiler/LSP
integrations MUST advertise their actual capabilities; unknown versions or
capabilities MUST be reported as unknown, not invented.
Context MUST include:
- explicit project identity/root;
- language list and primary designation, with separately identified known language/compiler/SDK versions;
- source extensions/scope and actual LSP/build capabilities;
- references, examples, libraries and editable versus read-only roots.
A one-entry PBS list is valid; extensibility does not require another language
or a multilingual compiler. LSP MUST use the existing project server and support
project/library navigation through the diagnostics, definitions, references,
symbols and other queries/refactorings it actually supports. It MUST NOT
advertise nonexistent features or apply edits outside authorized scope.
The matching language/SDK distribution MUST ship indexed local quickstart,
syntax, semantics, examples and SDK reference material. Consultation MUST work
without Studio/compiler checkouts. MCP MUST read references by identifier with
pagination, not arbitrary paths. Documentation ownership remains with its
language/SDK/library owner; packaging does not create parallel language semantics.
Connection guidance MUST describe: connect → consult current project/languages/
references → acquire after human grant → work using saved files and validate
through LSP/build → release. The agent need not know PBS in advance. Missing
documentation or unsupported language MUST appear as explicit limitations;
static copied instructions MUST NOT substitute for current project context.
## 10. Delivery Phases and Conformance Gates
The accepted slicing is runtime → DEV/shared services → MCP → integration.
No intermediate phase constitutes complete delivery of this specification.
| Phase / plan steps | Required gate and limit |
| --- | --- |
| Runtime, 01–07 | Independent process client proves external contract, deterministic execution, canonical pixels, limits/failures and installed CLI; no Studio/AI dependency |
| DEV/shared services, 08–14 | Neutral authority/operations and document handoff first, then DEV; test grant/reclaim, Debug exclusion, dirty buffers, revocation/closure, late calls and FX lifecycle; desktop navigation smoke; doubles only in tests, no fake product endpoint |
| MCP, 15–21 | Automated MCP client proves authenticated discovery, real configuration, unauthorized rejection, exclusive acquisition, context/references, operations/deduplication, revocation and image contracts; no model required for this gate |
| Integration, 22–28 | Real runtime/LSP/build and an external coding client prove edit → build/pack → boot/input/advance → matching agent/DEV image → release; corrective loops and cleanup preserve manual Debug |
Cross-phase conformance MUST prove API/Core neutrality, the unchanged Modulith
- Additional language implementation, persistent operation recovery or automatic task resumption.
- Integrated discussion-framework agendas/decisions/plans in the product; those are future work, not this runtime/DEV/MCP contract.
## Exit Criteria
Implementation is conformant only when all phase gates hold and:
1. Human grant, task acquisition, operation outcome and authority return are distinct and tested.
2. Service-level guards prevent conflicting manual work from grant through cleanup without blocking read-only navigation globally.
3. Save failure prevents grant; successful return refreshes documents without overwriting agent edits.
4. Revoke invalidates old calls first, works while waiting and preserves edits; project/application closure cleans owned processes and never restores authority.
5. DEV and the agent see the same canonical image with explicit build/session/frame correlation and stale labeling.
6. Local transport authentication does not bypass project/task authorization or scope restrictions.
7. Lost operation responses cannot duplicate execution; runtime crash cannot trigger replay or implicit authority release.
8. Language context and indexed local references reflect real installed support and work without source checkouts.
9. Manual Debug, architecture boundaries, packaging and real-client integration pass their regression gates.
@@ -79,6 +79,8 @@ The main session-restoration store MUST NOT include:
- heavy operational output;
- recomputable results that do not represent session restoration state.
Under DEC-0060, automation grants, task/control identities, active runtime sessions and the task-local operation/deduplication registry MUST NOT be persisted or restored through `.studio/state.json` or `.studio/setup.json`. Reopening a project MUST start under manual control. Restoring DEV as the selected workspace is presentation restoration, not permission to resume work. MCP connection credentials MUST NOT be stored in versioned files; they are regenerated on Studio restart. See the [DEV and Automation Specification](10.%20DEV%20and%20Automation%20Specification.md).
`Project-local activity` and project-local setup may still live under `.studio/`, but they are separate persistence concerns and not part of the main session-restoration store defined here.
@@ -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;
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 |
| 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;
5. [`8. Project-Local Studio State Specification.md`](8.%20Project-Local%20Studio%20State%20Specification.md)
6. [`9. Studio Core and Adapter Architecture Specification.md`](9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md)
7. [`10. DEV and Automation Specification.md`](10.%20DEV%20and%20Automation%20Specification.md)
## Reading Order
@@ -66,7 +67,8 @@ Recommended order:
3. components module policy;
4. assets workspace behavior;
5. project-local Studio state behavior;
6. Studio Core, adapter, composition, and external integration boundaries.
6. Studio Core, adapter, composition, and external integration boundaries;
7. DEV authority, document handoff, automation operations/captures and phased integration gates.
## Current Wave Notes
@@ -74,9 +76,9 @@ The embedded Studio code-editor stack was removed by `DEC-0031`.
Normative reminders:
- the active Studio workspace corpus is `Assets`, `Debug`, and `Shipper`;
- the accepted Studio workspace corpus is `Assets`, `Debug`, `Shipper`, and `DEV`; the DEV implementation follows DEC-0060's phased delivery;
- project-local Studio session state remains normative and is owned by `StudioProjectSession`;
-any future external-editor backend or replacement language-service architecture requires a new accepted decision before new Studio specs are introduced.
- the Studio backend is exposed through neutral API contracts shared by the JavaFX adapter and future non-visual adapters;
- Spring Boot is a non-web composition root, while Spring Modulith verifies the JavaFX-free `p.studio.core` boundary;
-DEC-0060 authorizes an external coding agent using native file tools and the existing project LSP through MCP; it does not reinstate the embedded editor or authorize a replacement language-service architecture;
- the Studio backend is exposed through neutral API contracts shared by JavaFX and the local MCP adapter, without duplicated authority or orchestration;
- Spring Boot remains the desktop composition root with the narrow DEC-0060 local MCP HTTP exception; Spring Modulith still verifies the JavaFX-free `p.studio.core` boundary;
-`p.studio.Container`, `AppContainer`, and the mixed `prometeu-studio` module are not valid final architecture.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.