Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/docs/packer/learn/runtime-ownership-and-studio-boundary.md
bQUARKz 0e5e1669c2
clean up
2026-03-24 13:42:57 +00:00

3.6 KiB
Raw Blame History

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