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.

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.

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.