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 is grounded in:

• 004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md
• 005-incremental-build-cache-and-watch-model-decision.md
• 006-studio-first-asset-services-and-event-lane-decision.md

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.