# 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 bus reference 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, this shared typed event bus reference is owned by the Studio `Container`. 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` ## 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.