# Diagnostics, Operations, and Studio Integration Specification Status: Draft Scope: Diagnostics, service operations, and Studio-facing event/reporting model Purpose: Define how the packer exposes safe operational behavior to Studio and tooling. ## Authority and Precedence This specification consolidates the initial packer agenda and decision wave into normative form. ## Diagnostics Model Diagnostics are divided into: - structural registered-world errors; - advisory workspace hygiene diagnostics. Rules: - structural registered-world errors block builds; - hygiene findings do not block baseline builds by default; - workspace scanning is broader than build validation. ## Doctor Model Baseline doctor behavior: - registered-world validation by default; - broader workspace hygiene scanning in expanded workspace mode; - safe mechanical fix application only for baseline fix flows. Unsafe automatic mutation is out of scope for baseline doctor behavior. ## Safety and Consent Rules: - destructive or relocational mutations require explicit consent; - quarantine is explicit and reversible; - duplicate content detection is advisory, not structurally invalid by itself; - unregistered asset roots are diagnosable and remain excluded from builds. ## Studio-First Service Surface The normative operational surface is service-based. The packer is a filesystem-first operational runtime. Rules: - the active project may maintain a coherent in-memory operational snapshot; - normal read requests should be served from that coherent snapshot when the runtime is active; - the runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring store; - the durable authoring workspace remains the persisted source of truth after successful commit. - backend consumers may derive smaller frontend-facing compile surfaces from the runtime snapshot without exposing the raw snapshot as a frontend contract. ### Embedded Bootstrap Rule When the packer is embedded inside another host such as Studio, the host must bootstrap the packer integration explicitly. Rules: - the embedded packer runtime must receive a typed event sink or adapter from the host when shared host visibility is part of the integration contract; - that reference is the baseline path for packer publish/subscribe integration in the embedded host; - the embedded packer runtime must not quietly create a disconnected parallel event system when host integration expects shared operational visibility; - in Studio, bootstrap, shutdown, and event adaptation are owned by the `prometeu-app` composition root; - the embedded integration must not use `p.studio.Container`, Spring context lookup, or another static service locator. ### Studio Dependency Rule The dependency direction is always Studio to Packer. Rules: - Studio Core may consume stable public contracts from `prometeu-packer-api` directly; - a Studio-owned gateway is required only when an integration is concrete, static, infrastructure-oriented, unstable, excessively broad, or leaks provider lifecycle details; - such a gateway must expose only the capabilities required by its consuming Studio module; - gateway implementations and Packer bootstrap belong in `prometeu-app` or another explicit infrastructure adapter; - the JavaFX adapter must consume neutral Studio API contracts and must not call Packer directly; - Packer must not depend on `p.studio` and must not publish Studio UI events as part of its domain contract. Baseline core services: - `init_workspace` - `register_asset` - `include_asset_in_build` - `exclude_asset_from_build` - `remove_asset` - `list_assets` - `get_asset_details` - `doctor` - `build` ## Operation Classes Operations must distinguish: - read-only operations; - registry mutations; - workspace mutations. This distinction is part of the service semantics and must be visible to the UI. ## Runtime State and Visibility The packer runtime must make operational freshness explicit. At minimum, the model should support states equivalent to: - `healthy` - `stale` - `diverged` - `committing` - `reconciling` - `failed` Rules: - successful durable commit defines the visibility boundary for committed write state; - reads must not present torn in-progress writes as committed truth; - background divergence detection may move a project or asset view into stale/diverged/reconciling state; - Studio may render these states, but must not invent their semantics. ## Concurrency Model The packer concurrency model is conservative and project-scoped. Rules: - observable correctness takes priority over speculative parallelism; - operations are coordinated per project workspace, not globally across unrelated projects; - Studio is a consumer of packer coordination results, not the owner of packer concurrency policy. ### Baseline Operation Matrix - read/read may run concurrently when each read observes a coherent snapshot; - read/write must not expose torn intermediate state to consumers; - write/write on the same project is serialized; - build/write on the same project is serialized unless a future spec introduces an explicit transactional coordination model; - background observation may continue while a serialized write lane is active, but it must not publish misleading post-state before commit visibility. ### Write Ownership - writes on one project execute through a packer-owned write lane; - caller timing must not define final write interleaving semantics; - preview generation may occur before the final commit section when safe; - apply/commit remains the packer-owned visibility boundary. ## Preview/Apply Model Sensitive mutations use staged intent. Rules: - preview or analysis precedes broad mutation where appropriate; - safe-fix flows are modeled as services, not merely terminal flags; - `exclude_asset_from_build` and `remove_asset` remain distinct operations. ## Structured Responses Service responses must be structured. At minimum, the model should support fields equivalent to: - `status` - `summary` - `runtime_state` - `affected_assets` - `diagnostics` - `proposed_actions` - `applied_actions` - `blockers` ## Scene Bank Studio Integration Boundary Scene Bank publication is a split workflow across Studio and packer. Rules: - Studio owns canonical scene validation and projection of the canonical Scene Bank request; - packer owns compilation of the canonical Scene Bank request into runtime `SCENE` output; - packer must report structural diagnostics against the canonical Scene Bank request artifact when that artifact is missing, malformed, or inconsistent with the locked format rules; - packer must not report editor-file parsing diagnostics as if `TMX` or `TSX` were direct runtime build inputs. ### Request Boundary Visibility Rules: - the Studio-to-packer handoff for Scene Bank publication must be a canonical request artifact or equivalent request surface derived from canonical Studio scene state; - if external compatibility files change without corresponding Studio import/update, packer must continue to treat the canonical request boundary as authoritative rather than silently reparsing editor files; - future supported editors may replace or coexist with Tiled-backed interoperability only if Studio continues to emit the same canonical request boundary. ## Asset Event Lane The system includes a dedicated asset workspace event/reporting lane. Responsibilities: - observe relevant asset and registry changes; - report diagnostics/build/cache activity to the UI; - support live refresh and progress reporting; - avoid blocking the main UI thread. - surface operational freshness and reconcile transitions when they affect Studio-visible state. ### Initial Event Set The initial structured event set includes: - `asset_discovered` - `asset_changed` - `diagnostics_updated` - `build_started` - `build_finished` - `cache_hit` - `cache_miss` - `preview_ready` - `action_applied` - `action_failed` - `progress_updated` Additional runtime/reconcile state events may exist as the operational runtime evolves, but adapters must preserve their causal meaning instead of collapsing them into generic refresh noise. ### Mutation Serialization Mutating asset workflows are serialized semantically. Rules: - background observation and reporting may be continuous; - conflicting sensitive mutations must not race arbitrarily; - observable mutation behavior remains coherent from the UI perspective. - the baseline write policy is a single-writer semantic lane per project; - preview generation may run outside the final commit section, but apply/commit remains serialized; - build and sensitive mutation apply must not interleave on the same project in a way that obscures final state; - cancellation or failure must leave the observable project state in a coherent post-operation condition. - divergence detection must not silently rewrite user-authored workspace content as if it were a normal mutation apply. ### Event Envelope Packer events must be structured enough for adapters to preserve causality and user-facing meaning. At minimum, each event must carry fields equivalent to: - `project_id` or workspace identity - `operation_id` - `sequence` - `kind` - `timestamp` - `summary` - `progress` when applicable - `affected_assets` when applicable Rules: - `operation_id` is stable for the full lifecycle of one logical operation; - `sequence` is monotonic within one operation; - adapters may remap event shapes for UI consumption, but must not invent causal relationships not present in packer events. - embedded hosts should preserve the same typed event bus reference across packer bootstrap and adapter wiring so subscription and publication stay causally coherent. ## Compile-Surface Integration Boundary The packer snapshot is not itself the normative frontend compile contract. Rules: - the backend may derive a smaller frontend-facing compile surface from packer-owned state; - for asset references, that smaller surface may contain only `Addressable(address, asset_id)` entries; - Studio and compiler frontends may consume the derived surface through backend-owned contracts; - consumers must not treat the raw packer snapshot as the stable frontend API boundary. ### Event Ordering and Coalescing Rules: - events emitted for one operation must be observable in causal order; - repeated progress updates may be coalesced by adapters or sinks; - lifecycle boundaries such as preview-ready, apply-success, apply-failure, build-started, and build-finished must remain individually observable; - low-value repeated observation events must not drown out actionable failures or terminal state. ## Incremental and Watch Integration Incremental behavior is an optimization only. Rules: - full and incremental builds must be observably equivalent; - watch mode is optional in the baseline contract; - watch does not authorize silent dangerous mutation. ## Non-Goals - final visual design of Studio asset panels - future CLI grammar - remote/shared cache orchestration ## Exit Criteria This specification is complete enough when: - Studio-facing operational semantics are explicit; - safety/preview/apply behavior is clear; - event/reporting integration has a stable baseline. ## Asset batch outcomes and lossless diagnostics Batch preview/result values MUST distinguish ready, no-op, stale conflict, rejected rebind, cancelled before commit, committed and recovered outcomes. Preview lists all affected assets/files, expected revision, proposed actions, reference/ownership changes and available producer diagnostics. Durable staging and journal recovery precede publication; shared readers do not observe partial batches. A query after commit/response loss returns applied truth, even when cancellation arrives later. Preserve producer and code, assetRoot/path, bank type, missing/duplicate indices, affected references and available used/required/limit facts through packer, Studio shipper, MCP and FE. Do not discard structured detail and later parse prose to recreate it. Unavailable producer facts remain unavailable. Diagnostic identity and budget results MUST agree across adapters. The shared budget projection separates per-bank content from existing, build-included, final-preload and potential dynamic residency. Known overflow diagnostics identify responsible slots/AssetIds/paths and qualified profile; unknown qualification has an explicit reason. Service and actual Assets UI qualification are separate gates, alongside recovery, no-op/append identity, explicit rebind and installed positive/negative capacity checks.