258 lines
8.4 KiB
Markdown
258 lines
8.4 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 registered-world errors;
|
|
- advisory workspace hygiene diagnostics.
|
|
|
|
Rules:
|
|
|
|
- structural registered-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:
|
|
|
|
- registered-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;
|
|
- unregistered asset roots are diagnosable and remain excluded from builds.
|
|
|
|
## Studio-First Service Surface
|
|
|
|
The normative operational surface is service-based.
|
|
|
|
The packer is a filesystem-first operational runtime.
|
|
|
|
Rules:
|
|
|
|
- the active project may maintain a coherent in-memory operational snapshot;
|
|
- normal read requests should be served from that coherent snapshot when the runtime is active;
|
|
- the runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring store;
|
|
- the durable authoring workspace remains the persisted source of truth after successful commit.
|
|
|
|
### Embedded Bootstrap Rule
|
|
|
|
When the packer is embedded inside another host such as Studio, the host must bootstrap the packer integration explicitly.
|
|
|
|
Rules:
|
|
|
|
- the embedded packer runtime must receive a typed event bus reference from the host when shared host visibility is part of the integration contract;
|
|
- that reference is the baseline path for packer publish/subscribe integration in the embedded host;
|
|
- the embedded packer runtime must not quietly create a disconnected parallel event system when host integration expects shared operational visibility;
|
|
- in Studio, this shared typed event bus reference is owned by the Studio `Container`.
|
|
|
|
Baseline core services:
|
|
|
|
- `init_workspace`
|
|
- `register_asset`
|
|
- `include_asset_in_build`
|
|
- `exclude_asset_from_build`
|
|
- `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.
|
|
|
|
## Runtime State and Visibility
|
|
|
|
The packer runtime must make operational freshness explicit.
|
|
|
|
At minimum, the model should support states equivalent to:
|
|
|
|
- `healthy`
|
|
- `stale`
|
|
- `diverged`
|
|
- `committing`
|
|
- `reconciling`
|
|
- `failed`
|
|
|
|
Rules:
|
|
|
|
- successful durable commit defines the visibility boundary for committed write state;
|
|
- reads must not present torn in-progress writes as committed truth;
|
|
- background divergence detection may move a project or asset view into stale/diverged/reconciling state;
|
|
- Studio may render these states, but must not invent their semantics.
|
|
|
|
## 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.
|
|
|
|
### Write Ownership
|
|
|
|
- writes on one project execute through a packer-owned write lane;
|
|
- caller timing must not define final write interleaving semantics;
|
|
- preview generation may occur before the final commit section when safe;
|
|
- apply/commit remains the packer-owned visibility boundary.
|
|
|
|
## 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;
|
|
- `exclude_asset_from_build` and `remove_asset` remain distinct operations.
|
|
|
|
## Structured Responses
|
|
|
|
Service responses must be structured.
|
|
|
|
At minimum, the model should support fields equivalent to:
|
|
|
|
- `status`
|
|
- `summary`
|
|
- `runtime_state`
|
|
- `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.
|
|
- surface operational freshness and reconcile transitions when they affect Studio-visible state.
|
|
|
|
### 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`
|
|
|
|
Additional runtime/reconcile state events may exist as the operational runtime evolves, but adapters must preserve their causal meaning instead of collapsing them into generic refresh noise.
|
|
|
|
### 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.
|
|
- divergence detection must not silently rewrite user-authored workspace content as if it were a normal mutation apply.
|
|
|
|
### 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.
|
|
- embedded hosts should preserve the same typed event bus reference across packer bootstrap and adapter wiring so subscription and publication stay causally coherent.
|
|
|
|
### 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.
|