# 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`

## 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.
