205 lines
5.8 KiB
Markdown
205 lines
5.8 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.
|
|
|
|
## 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.
|