153 lines
3.6 KiB
Markdown
153 lines
3.6 KiB
Markdown
# 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.
|