Files
prometeu-studio/docs/specs/studio/9. Studio Core and Adapter Architecture Specification.md
T
bquarkz 71fb80efc3
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit
feat(studio): ship JavaFX 2 Play and delegate integration tooling
Launch the JavaFX 2 project shell on Java 25 with an interactive viewport,
managed Play lifecycle and project mutation guards. Preserve headless/MCP and
save compatibility, and qualify exact runtime executable bundles.
Separate unit JaCoCo gates from opt-in integration suites and use the internal
Pong fixture for the headless visual pilot.
Move maintenance and native conformance tools into tooling; retain the VS Code
extension and update current navigation links.

Validation: tooling make verify passed, including 1064 Studio unit tests,
JaCoCo thresholds and 22 headless integration tests.
2026-11-19 17:32:03 +00:00

370 lines
26 KiB
Markdown

# Studio Core and Adapter Architecture Specification
## Status
Active
## Applies To
- `prometeu-studio-api`
- `prometeu-studio-core`
- `prometeu-studio-ui-javafx`
- `prometeu-studio-ui-javafx-2`
- `prometeu-app`
- integrations with compiler, Packer, LSP, and the runtime
## Purpose
Define the physical and functional boundary that makes the Studio consumable by interchangeable human and automation adapters without coupling application behavior to JavaFX, Spring, or a specific external provider.
## Authority and Precedence
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 <── local MCP adapter <── external coding agent
│
▼
Studio Core
▲
│
application/infrastructure adapters
```
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
1. `prometeu-studio-api` MUST contain toolkit-neutral contracts, commands, queries, DTOs, diagnostics, results, events, and operation contracts.
2. `prometeu-studio-core` MUST contain JavaFX-free application services, sessions, policies, orchestration, and Studio-owned use-case implementations.
3. `prometeu-studio-ui-javafx` MUST contain visual workspaces, controls, dialogs, bindings, navigation, presentation projections, theme application, localization binding, and JavaFX-thread dispatch.
4. `prometeu-app` MUST contain the desktop entry point, Spring composition, concrete integration adapters, lifecycle, and packaging.
Gradle is the physical classpath boundary. Spring Modulith verifies the functional modules rooted exclusively at `p.studio.core`; it does not replace the Gradle modules.
The normal app composes UI2 through neutral API services; the previous adapter
remains for compatibility qualification. Interactive execution adds neutral
pause/resume, input, stable frame leases and ownership queries. Core owns exclusive
admission through preparation and confirmed teardown. Binary TCP framing, native
process ownership and IO workers belong to the app adapter, independently of the
deterministic headless gateway. `openForPlay` defers editor/agent infrastructure;
the existing session path and automation contracts remain. See specification
[14](14.%20Integrated%20Play%20Specification.md).
The legacy mixed `prometeu-studio` module and the static `p.studio.Container` service locator MUST NOT exist in the final architecture.
## API Neutrality
The public Studio API MUST be plain Java and MUST NOT depend on:
- JavaFX;
- Spring Framework, Spring Boot, or Spring Modulith;
- 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.
Public contracts MUST NOT expose `Stage`, `Scene`, `Node`, JavaFX properties, controls, `Task`, `ApplicationContext`, Spring events, or provider-specific implementation types.
Expected failures MUST use domain status, diagnostics, and typed results. A universal `Result<T>` abstraction MUST NOT be introduced.
## Core Rules
Core classes MUST be POJOs with constructor injection and MUST remain testable without a Spring context.
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;
- obtain dependencies from a static holder or `ApplicationContext` lookup.
The functional core modules are:
- `project`: project identity, catalog, creation, paths, setup, and restoration state;
- `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, 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:
```text
assets --> project
shipper --> project
runtime --> project
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.
JavaFX controls and dialogs MUST be constructed by UI factories or composition roots. They MUST NOT become Spring singletons by default.
Presentation-only drafts and projections MAY remain in the JavaFX module. Rules that determine project, asset, build, runtime, or semantic outcomes MUST live behind neutral API contracts and core services.
The JavaFX module MUST NOT directly invoke compiler implementations, `p.packer`, LSP implementations, runtime implementations, or filesystem orchestration.
## Spring Composition
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 fresh grant-published project credential, validate project/session scope and Origin, and stop with Studio. Connection authentication MUST NOT grant project/task authority. Credentials MUST NOT be stored in versioned files. Restart requires a fresh human grant, while the stable client configuration remains unchanged.
This exception does not authorize a web UI, remote binding, general-purpose web application, accounts or OAuth. DEC-0061 explicitly adds the Studio-owned stdio mode and local client preparation. 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.
The desktop entry point MUST retain the JavaFX composition root and close it before closing the Spring context. Closing that root MUST be idempotent and MUST close any active or asynchronously opening project session, execution surface, loading window, project window, and launcher window before provider beans and executors are destroyed.
Spring Modulith verification MUST use `p.studio.core` as its exclusive application root and MUST run as an architecture gate.
## External Integration Rule
An integration MUST use the provider's public API directly when that API is stable, neutral, use-case oriented, and safe to compose and test. A redundant gateway that merely mirrors such an API MUST NOT be created.
A narrow consumer-owned gateway MUST be used when the available integration is concrete, static, infrastructure-oriented, unstable, excessively broad, or leaks lifecycle and implementation details. Its implementation belongs in `prometeu-app` or another explicit infrastructure adapter.
| Studio consumer | Provider | Required boundary |
| --- | --- | --- |
| `assets` | `p.packer` | Stable public Packer API directly; narrow assets-owned gateway only when necessary |
| `shipper` | compiler and `p.packer` | Stable public APIs or a narrow shipper-owned compiler gateway |
| `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.
## Commands, Events, and Operations
Commands and queries requiring an immediate response MUST use direct service calls. In-process events MAY communicate facts that require no response, and each application event MUST be owned by the functional module that owns the fact.
Selection, navigation, attach/detach, and visual lifecycle events remain UI-local.
Long-running build, pack, runtime, and execution work MUST expose a neutral operation contract with stable identity, observable snapshot, standard-Java asynchronous completion, cancellation, updates, and a typed result.
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
Runtime observations and control observations are neutral immutable API values.
The process adapter validates native state, fault, media and error payloads; Core
retains project/task/operation/request correlation and authorization independently.
Neither JavaFX nor MCP may infer native phases, fabricate unknown progress or
implement recovery by replaying commands. Passive observation getters MUST perform
no native IO and MUST be safe to read while the authority monitor is held.
An operation-final observation MUST remain unchanged by a later state query,
reset, rebuild or shutdown. A separate current-session observation carries the
latest known facts. Every retained native snapshot carries its own source and
observation time, so an earlier state is not mislabeled as a later observation.
Failed follow-up inspection MUST retain the original native cause and record the
missing observation separately. Runtime wire codecs remain in application adapters; the
API supplies plain Java values and the JavaFX adapter presents those values.
Observation updates MUST serialize with process-loss invalidation: late native
progress/state cannot resurrect a lost process. Inspection admission MUST serialize
with shutdown; unavailable inspection during closing is reported without sending
a competing native query.
Diagnostic defaults and immutable value trees belong to the neutral Studio API.
Studio's bounded diagnostic aggregation belongs to the existing Core shipper
module; it MUST preserve whole-issue/count/UTF-8 budgets and producer fields.
Project-bound diagnostic source reads belong to the existing Core project module,
through `DiagnosticSources` exposed by the project session. JavaFX only presents
values and requests read-only navigation through that port; it MUST NOT perform
filesystem admission, read source bytes or serialize diagnostic wire payloads.
The architecture is conformant only when all of the following hold together:
- 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 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
- 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;
- introducing microservices or durable event infrastructure.
## Integrated MCP Connection Boundary (DEC-0061)
The same Studio application artifact MUST support `mcp --project` over stdio
before desktop composition. It connects to the existing loopback HTTP adapter;
it MUST NOT implement separate authority, operations, language services or runtime
semantics. Offline catalog loading does not initialize the desktop graph.
API exposes neutral preparation/readiness and connection-publication lifecycle
ports. Core orchestrates save, publication commit/abort, grant, revocation and
shutdown through those ports. Application infrastructure owns credentials, file
locks/atomic discovery, HTTP identity checks, TOML preparation and managed
installation/runtime packaging. JavaFX consumes neutral status and actions only.
Filesystem publication MUST NOT run under a long-held authority monitor.
## Animation integration contract
Glyph-bank animation authoring, generated-source navigation, strict task-scoped MCP tools and preview use the shared animation service and validation contract. UI/MCP preserve project authority, expected revisions, conflict/cancellation/revocation and document handoff. Persist only the canonical animation sidecar; keep generated PBS read-only and neutral services independent of JavaFX/transports.
See the [complete animation contract](12.%20Animation%20Authoring%20Specification.md).
## Explained diagnostic values and producer boundaries
StudioDiagnostic MUST carry the canonical logical issue through immutable JSON-compatible values. Studio API/Core MUST NOT depend on compiler AST/IR classes, PBS, LSP4j, transport objects or Throwable serialization. Existing code/severity/message constructors remain compatible.
| Field group | Contract |
| --- | --- |
| Identity | issueId identifies one producer event within analysisId. The same event keeps its ID in standard LSP data, complementary analysis, MCP and UI. Repeated events remain distinct. |
| Producer and rule | producer has component, owner and languageId; code is the original producer code. codeOrigin marks producer versus studio-adapter. templateId/templateParameters remain separate from message. checkId identifies the detector independently of a shared code. |
| Classification | severity, phase, stageId and failureKind preserve the producer's classification. Detection phase MUST NOT become an inferred cause. |
| Explanation | explanation has id, summary, rule and availability. Text is deterministic and owner-maintained, never generated by an LLM at query time. Unknown checks report unavailable explanation. |
| Evidence | facts, semanticContext, origin, related, suggestedChecks and limitations retain observed values and their availability. Suggested checks are investigations, not automatic source edits. |
semanticContext contains availability (available/partial/unavailable/not-applicable) and facts. Each fact is {value,availability,reason}, where availability is available/not-recorded/unavailable/not-applicable. An observed null is available; missing observations MUST NOT be represented as an observed null. Declared types, expression types and actual resolution constraints are separate concepts.
Origins keep UTF-8 byte spans, UTF-16 ranges and qualified IRVM coordinates separate. Convert a span only using matching captured source bytes. Missing origins, generated code, mixed input revisions and unavailable source text MUST NOT produce a fabricated zero range. Function context belongs in related context when no instruction source is recorded. Detection and context are not causal attribution.
The app compiler gateway translates complete warnings and BuildException payloads into neutral output or CompilerBuildFailure. Core MUST NOT catch compiler-domain exceptions directly. Packer adaptation preserves severity/category/blocking/evidencePath and asset identity; PACKER_<CATEGORY> is explicitly an adapter code. Asset ID MUST NOT be interpreted as a bank ID.
A shared public view contains issues, summary and context. Detail projection is limited to 1024 whole issues and 1 MiB of UTF-8 JSON issues. At a boundary, include a whole prefix, report partial detail coverage and LIMIT_EXCEEDED with budgets/total count, and retain full authoritative counts/evaluation separately. No issue field may be silently cut. UI and MCP consume this same view; underlying producer results remain complete.
Conformance: DiagnosticPayloadTest, StructuredShipperTest, StructuredDiagnosticsIntegrationTest and the compiler attribution/conversion regressions.
## Visual evidence service boundaries
The Studio API MUST expose neutral artifact, RGBA8, comparison, bounded reading,
publication and baseline-revision values and storage/codec ports. Core MUST own
comparison and task/operation orchestration; concrete filesystem, PNG and wire
codecs belong to application adapters. JavaFX MUST present the shared result.
Persistence MUST resolve a terminated operation by operationId/clientRequestId
and copy exactly its retained runtimeResult.capture. It MUST NOT call advance or
capture again. Publication requests MUST deduplicate by request identity and full
parameters; changed parameters MUST conflict. A lost response MUST be recoverable
from retained publication identity without guest replay. Mutations MUST use the
existing project worker or human manual lease; no second runner is introduced.
Comparison MUST expand PNG samples losslessly to RGBA8 without gamma/perceptual
correction or resize. Coordinates are top-left; ROI/masks are half-open rectangles
validated against original dimensions without clipping. Masks exclude their union
inside the ROI, counting overlaps once. An empty compared region is invalid. Alpha
policy MUST be explicit compare/ignore, and RGB MUST be compared even at zero
alpha. Defaults are exact: channel limit zero, differing-pixel allowance zero.
Tolerant comparison declares an integer channel limit 0..255 and nonnegative
allowed differing-pixel count. A pixel differs when any compared channel exceeds
that limit; the maximum channel error records the observed error before tolerance.
Dimension mismatch MUST be an explicit comparison rejection, distinct from invalid
parameters, decode, storage and authority errors. Reports MUST retain normalized
parameters, both original byte hashes, expected/actual/diff IDs, verdict, compared
and differing-pixel counts, maximum error and original-coordinate difference
bounds (null without differences). The diff MUST distinguish excluded pixels
(transparent black), compared pixels within tolerance (opaque green), and differing
pixels (opaque red/yellow). It MUST retain original image dimensions/coordinates.
## Shared isolated guest test service
Target selection MUST propagate through the existing project/API/compiler/shipper
services and resolver; the host test service MUST reuse existing task authority,
operationId/clientRequestId deduplication, cancellation and worker termination.
It MUST NOT introduce another resolver, runner authority, guest ABI or larger
budgets. Test-only support and ordinary PBS visibility MUST preserve production
source/barrel bytes and identity. Usable test builds MUST be exclusive and immutable
per target/build, retaining effective source/configuration/dependency/asset hashes.
The application adapter MUST validate negotiated log_read before executing a test
guest. It translates typed native get_logs records to neutral log pages with lossless
uint64 session/epoch/cursor/retention information. Core MUST accumulate tagged
versioned events, validate ordering/catalogue/duplicates/loss, and produce the same
case/assertion/checkpoint/run result for all adapters. It MUST read logs after each
bounded frame block and at completion/failure when available, without automatic
advance replay or destructive draining. Timeout, cancellation, native failure and
explicit suite completion MUST remain distinct; cancelled results are final only
after actual worker termination. Checkpoint references retain original evidence
identity from the shared visual service. The project Tests workspace and task MCP
tools consume one shared service. Manual runs hold the existing execution lease;
task runs use the existing automation worker. A retained manual test runtime blocks
grant/production execution until explicit cleanup. A provider correction requires
its own scoped authorization before runtime writes/builds.
## Shared asset authoring, revisions and capacity
The neutral API owns immutable batch requests/previews/results, revision and
conflict values, affected references/rebinds, generated-output ownership graphs,
producer diagnostics and separate content/global budget values. Core owns shared
authority admission and orchestration over existing asset, composition, metadata,
animation and packer services. Packer owns the project write lane and atomic
recoverable publication. App adapters own canonical file authorization,
serialization and distributed runtime-profile loading/identity verification.
JavaFX and MCP render the same API projection.
Human mutations MUST enter the existing manual guard; task mutations MUST enter
the existing current-task/project worker and recheck revocation at execution.
Inspection remains available under its read authority. Preview does not commit.
Commit is explicit, revision-checked and deduplicated by project/task/request ID
and full parameters. Identical retries return the retained result; changed
parameters conflict. Knowing a batch/request ID cannot restore revoked access.
All shared readers, including build and animation readers, participate in packer
publication exclusion/recovery; an MCP wrapper cannot bypass this boundary.
The application distributes capacity profiles by contract version, runtime
version and exact verified executable digest, together with qualification
evidence for every bank type it explicitly qualifies. The first profile covers
glyph and scene only; sound qualification is deferred. There is no runtime-family fallback
or ordinary-build access to runtime checkout sources. Missing, malformed or
mismatched qualification is unknown. Core's one budget/preflight projection is
consumed by shipper, headless and desktop execution. Unqualified builds may be
produced, explicitly marked unknown; managed execution requires the matching
qualified profile and valid effective budget.
The final packer preload list is authoritative. Runtime selection/input changes
invalidate earlier qualification and require rechecking. Build provenance MUST
include the profile and input revision actually checked. A known excess MUST
fail before cartridge publication, retaining the previous valid output.
### Guest producer continuity and native retention
Every structured guest event payload MUST include a zero-based contiguous integer
ordinal; suite_end MUST include eventCount counting all unique events including
itself. Retries with the same event identity/content are idempotent. Missing or
inconsistent ordinals/final counts fail as infrastructure errors, even if native
sequences remain contiguous. Native overflow records historical eviction; only
unread gap or actual continuity loss causes a retention failure. Preserve the
overflow observation separately.
Encoded guest messages MUST fit 256 UTF-8 bytes and stay within the unchanged
10 messages/application/frame budget, including ordinary application logs. The
runner drains every pending native page before another bounded advance. Native
continuity alone cannot detect events dropped before ring insertion. No new guest
ABI, formatting facility or increased execution/logging budget is introduced.