prometeu-studio/docs/packer/decisions/006-studio-first-asset-services-and-event-lane-decision.md

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.

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