279 lines
8.1 KiB
Markdown
279 lines
8.1 KiB
Markdown
# Studio-First Asset Services and Event Lane Decision
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Date
|
|
|
|
2026-03-11
|
|
|
|
## Context
|
|
|
|
This decision closes the architectural questions raised in [`01.6. CLI Surface and Mutating Operations Agenda`](../agendas/01.6.%20CLI%20Surface%20and%20Mutating%20Operations%20Agenda.md).
|
|
|
|
The original packer framing was CLI-oriented.
|
|
That is no longer the design center.
|
|
|
|
The current target is Studio integration:
|
|
|
|
- asset UI and packer behavior should evolve together;
|
|
- packer operations should exist as Studio-consumable services first;
|
|
- background asset activity should be observable in the UI through structured events;
|
|
- any future CLI should be an adapter over those services rather than the architecture driver.
|
|
|
|
## Decision
|
|
|
|
The packer adopts a `Studio-first services + structured event lane` model.
|
|
|
|
### 1. Primary integration model
|
|
|
|
Studio is the primary integration target.
|
|
|
|
Rules:
|
|
|
|
- service contracts are the normative operational surface;
|
|
- UI workflows are first-class design inputs;
|
|
- CLI is not the baseline architecture contract in the current phase;
|
|
- if a CLI exists later, it adapts these services rather than redefining them.
|
|
|
|
### 2. Core v1 services
|
|
|
|
The baseline Studio service surface includes:
|
|
|
|
- `init_workspace`
|
|
- `register_asset`
|
|
- `adopt_asset`
|
|
- `forget_asset`
|
|
- `remove_asset`
|
|
- `list_assets`
|
|
- `get_asset_details`
|
|
- `doctor`
|
|
- `build`
|
|
|
|
Later or optional capabilities may include:
|
|
|
|
- `watch`
|
|
- `gc`
|
|
- `quarantine`
|
|
- more advanced bulk refactor flows
|
|
|
|
### 3. Identifier expectations
|
|
|
|
For normal Studio-facing workflows, the preferred identifiers are:
|
|
|
|
- `asset_name`
|
|
- `asset_root`
|
|
- `asset_id` when already resolved internally
|
|
|
|
`asset_uuid` may still exist for migration or internal tooling purposes, but it is not required as the primary UX identifier for the baseline flow.
|
|
|
|
### 4. Read-only versus mutating services
|
|
|
|
The service contract must distinguish clearly between:
|
|
|
|
- read-only operations;
|
|
- registry mutations;
|
|
- workspace mutations.
|
|
|
|
Baseline interpretation:
|
|
|
|
- read-only:
|
|
- `list_assets`
|
|
- `get_asset_details`
|
|
- `doctor`
|
|
- registry mutations:
|
|
- `register_asset`
|
|
- `adopt_asset`
|
|
- `forget_asset`
|
|
- workspace mutations:
|
|
- `remove_asset`
|
|
- future quarantine/move/delete flows
|
|
|
|
This distinction is part of the service semantics and must be visible to the UI.
|
|
|
|
### 5. Preview/apply model
|
|
|
|
Sensitive mutating workflows use staged intent rather than immediate blind mutation.
|
|
|
|
Rules:
|
|
|
|
- operations with significant mutation potential should support analysis or preview before apply;
|
|
- broad, destructive, or relocational actions require explicit user confirmation;
|
|
- safe-fix flows should be modeled as services such as:
|
|
- analyze
|
|
- propose fixes
|
|
- apply safe fixes
|
|
|
|
This replaces CLI-centric flag thinking as the architectural baseline.
|
|
|
|
### 6. Structured service responses
|
|
|
|
Service responses must be structured for UI and automation.
|
|
|
|
At minimum, the model should support fields equivalent to:
|
|
|
|
- `status`
|
|
- `summary`
|
|
- `affected_assets`
|
|
- `diagnostics`
|
|
- `proposed_actions`
|
|
- `applied_actions`
|
|
- `blockers`
|
|
|
|
Human-readable strings may still exist, but they must not be the only contract the UI depends on.
|
|
|
|
### 7. `forget` versus `remove`
|
|
|
|
`forget_asset` and `remove_asset` remain distinct operations.
|
|
|
|
Meaning:
|
|
|
|
- `forget_asset` leaves the managed set without deleting authoring content;
|
|
- `remove_asset` expresses a stronger mutation intent and may affect workspace content depending on policy.
|
|
|
|
The UI must present this difference explicitly.
|
|
|
|
### 8. Adoption is core
|
|
|
|
`adopt_asset` is part of the baseline service set.
|
|
|
|
Rationale:
|
|
|
|
- orphan `asset.json` declarations are a normal part of the packer model;
|
|
- adoption is not an edge-case maintenance feature;
|
|
- Studio needs a first-class path from discovery to managed registration.
|
|
|
|
### 9. Asset workspace event lane
|
|
|
|
The system includes a dedicated asset workspace event lane for Studio integration.
|
|
|
|
This is an architectural event/reporting contract, not a commitment to one specific implementation primitive.
|
|
|
|
Responsibilities:
|
|
|
|
- observe relevant changes in the asset workspace and registry;
|
|
- trigger analysis, refresh, rebuild, or rescan workflows when appropriate;
|
|
- publish structured events for UI logging, status, and live refresh;
|
|
- avoid blocking the UI thread on asset work.
|
|
|
|
### 10. Mutation serialization
|
|
|
|
Mutating asset operations are serialized semantically.
|
|
|
|
Rules:
|
|
|
|
- the event lane and service model must not allow conflicting asset mutations to race arbitrarily;
|
|
- internal implementation may use controlled parallelism where safe;
|
|
- but the observable mutation model should behave as if sensitive workspace operations are serialized.
|
|
|
|
This keeps Studio state coherent and avoids hard-to-debug race conditions between watch, doctor, build, and explicit user actions.
|
|
|
|
### 11. Event model
|
|
|
|
The initial structured event set should include, at minimum:
|
|
|
|
- `asset_discovered`
|
|
- `asset_changed`
|
|
- `diagnostics_updated`
|
|
- `build_started`
|
|
- `build_finished`
|
|
- `cache_hit`
|
|
- `cache_miss`
|
|
- `preview_ready`
|
|
- `action_applied`
|
|
- `action_failed`
|
|
- `progress_updated`
|
|
|
|
`progress_updated` exists to support visible progress reporting such as progress bars and long-running asset activity feedback in the UI.
|
|
|
|
### 12. Event lane safety
|
|
|
|
The background event lane is not an autonomous mutation engine.
|
|
|
|
Rules:
|
|
|
|
- it may observe, analyze, report, and trigger safe refresh/rebuild behavior;
|
|
- it must not silently apply dangerous mutations;
|
|
- explicit user intent remains required for destructive, relocational, or adoption-related changes unless separately designed later.
|
|
|
|
### 13. Future CLI boundary
|
|
|
|
Any future CLI should remain a secondary adapter.
|
|
|
|
Rules:
|
|
|
|
- CLI should consume the same service semantics;
|
|
- CLI text output is not the canonical contract;
|
|
- if stable automation output is needed, it should be derived from the same structured response model used by Studio.
|
|
|
|
## Invariants and Constraints
|
|
|
|
The following invariants now apply:
|
|
|
|
1. Studio integration is the primary target.
|
|
2. Services are the normative operational surface.
|
|
3. UI and services are designed together.
|
|
4. CLI is deferred to adapter status.
|
|
5. Core asset operations are service-defined, not command-defined.
|
|
6. Sensitive mutations use preview/apply semantics where appropriate.
|
|
7. Structured responses are required for UI consumption.
|
|
8. `forget_asset` and `remove_asset` remain distinct.
|
|
9. Adoption is part of the baseline service model.
|
|
10. A dedicated asset event lane exists as an architectural integration surface.
|
|
11. Mutating asset workflows are serialized semantically.
|
|
12. Initial asset event reporting includes progress updates.
|
|
13. Background reporting does not authorize silent dangerous mutation.
|
|
|
|
## Explicit Non-Decisions
|
|
|
|
This decision does not yet define:
|
|
|
|
- the exact transport or IPC mechanism for services;
|
|
- the exact threading/runtime primitive used for the event lane;
|
|
- final visual design of Studio asset panels;
|
|
- detailed watch-mode orchestration beyond the baseline event model;
|
|
- a future CLI command grammar.
|
|
|
|
Those belong to later decisions and specs.
|
|
|
|
## Propagation Targets
|
|
|
|
This decision must propagate to:
|
|
|
|
- packer service operation spec;
|
|
- Studio asset workflow integration spec;
|
|
- mutation and confirmation policy spec;
|
|
- structured response contract spec;
|
|
- asset event/reporting integration spec;
|
|
- future implementation of the asset workspace event lane and progress reporting.
|
|
|
|
## Validation Notes
|
|
|
|
Example: safe inspection flow
|
|
|
|
- Studio requests `list_assets`
|
|
- service returns structured asset summaries
|
|
- event lane may emit `diagnostics_updated` or `asset_changed` as background state evolves
|
|
|
|
Example: staged mutation flow
|
|
|
|
- Studio requests doctor analysis
|
|
- service returns diagnostics plus proposed safe fixes
|
|
- user confirms apply
|
|
- service performs safe changes
|
|
- event lane emits `action_applied` and `progress_updated`
|
|
|
|
Example: background rebuild
|
|
|
|
- asset source changes
|
|
- event lane observes the change
|
|
- analysis/rebuild is triggered according to service policy
|
|
- UI receives `build_started`, `progress_updated`, and `build_finished`
|
|
|
|
Example: dangerous mutation boundary
|
|
|
|
- user has not confirmed quarantine or deletion
|
|
- background lane may report the issue and propose the action
|
|
- background lane must not perform the mutation by itself
|