prometeu-studio/docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md

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.

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.

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.