89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# 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)
|