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.
26 KiB
Studio Core and Adapter Architecture Specification
Status
Active
Applies To
prometeu-studio-apiprometeu-studio-coreprometeu-studio-ui-javafxprometeu-studio-ui-javafx-2prometeu-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 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:
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
prometeu-studio-apiMUST contain toolkit-neutral contracts, commands, queries, DTOs, diagnostics, results, events, and operation contracts.prometeu-studio-coreMUST contain JavaFX-free application services, sessions, policies, orchestration, and Studio-owned use-case implementations.prometeu-studio-ui-javafxMUST contain visual workspaces, controls, dialogs, bindings, navigation, presentation projections, theme application, localization binding, and JavaFX-thread dispatch.prometeu-appMUST 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.
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.coreorp.studio.ui.javafxinternals.
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
ApplicationContextlookup.
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:
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 exclusivep.studio.coreroot;- 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.
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_ 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.