prometeu-studio/docs/packer/specs/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 managed-world errors;
• advisory workspace hygiene diagnostics.

Rules:

• structural managed-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:

• managed-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;
• orphan anchors are diagnosable, not build-active.

Studio-First Service Surface

The normative operational surface is service-based.

Baseline core services:

• init_workspace
• register_asset
• adopt_asset
• forget_asset
• 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.

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.

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;
• forget_asset and remove_asset remain distinct operations.

Structured Responses

Service responses must be structured.

At minimum, the model should support fields equivalent to:

• status
• summary
• 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.

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

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.

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.

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.