# Runtime Ownership and Studio Boundary

## Original Problem

Once the packer stopped being just a set of direct filesystem helpers, the repository needed a clear answer for three things:

1. who owns operational asset semantics;
2. how concurrent reads and writes stay coherent;
3. how Studio consumes packer state without duplicating domain logic.

Without that boundary, the system would drift into split-brain behavior between packer services and Studio UI code.

## Consolidated Decision

The packer is the semantic owner of operational asset state.
Studio is a consumer of packer responses, commands, and events.

The stable boundary is:

- filesystem-first authoring workspace;
- project-scoped runtime snapshot for reads;
- single-writer semantic lane per project for commit-bearing operations;
- packer-native observability with causal ordering;
- Studio adapters that translate for presentation but do not invent semantics.

## Final Model

### 1. Filesystem-First Runtime

- the workspace on disk remains the durable source of truth;
- the runtime snapshot is an operational projection used for coherent reads and write coordination;
- divergence between runtime state and filesystem state must become explicit packer state, not silent repair.

### 2. Concurrency Model

- `read/read` may run concurrently when both observe one coherent snapshot;
- `read/write` must not expose torn intermediate state;
- `write/write` on the same project is serialized;
- build-bearing operations share the same project-scoped coordination story.

### 3. Event Ownership

- packer events are authoritative for lifecycle, progress, and outcomes;
- each logical operation carries stable causality through `operation_id` and monotonic `sequence`;
- sinks may coalesce noisy progress updates, but terminal lifecycle events remain observable.

### 4. Studio Adapter Rule

- Studio may remap packer data into workspace and shell view models;
- Studio must not recreate packer summaries, mutation semantics, or reconcile semantics from local heuristics;
- adapter code is translational, not semantic-authoritative.

## Examples

### Example: Mutation preview in Studio

The preview may be rendered in Studio-specific components, but the semantic meaning of:

- blockers,
- warnings,
- registry mutations,
- filesystem mutations,
- final apply outcome

must still come from the packer.

### Example: Activity and progress

If the UI shows a simplified progress bar or activity feed, that is fine.
What is not fine is for Studio to infer a successful final outcome without a packer-native terminal event or response.

## Common Pitfalls and Anti-Patterns

- Rebuilding packer summaries from navigator rows or local filesystem scans.
- Treating adapter code as a second owner of mutation or reconcile rules.
- Hiding divergence by silently refreshing state without surfacing the transition.
- Allowing same-project writes to race because the caller "already validated" earlier.
- Collapsing event causality into UI-local state that cannot be replayed or tested outside Studio.

## References

- Specs:
  - [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
  - [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- Cross-domain:
  - [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
- Related learn:
  - [`./foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md)