prometeu-studio/docs/packer/decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md

Concurrency, Observability, and Studio Adapter Boundary Decision

Status: Accepted Date: 2026-03-11 Domain Owner: docs/packer Cross-Domain Impact: docs/studio

Context

The production prometeu-packer track introduces two architectural seams that must not remain implicit:

1. the packer will become the operational source of truth for asset summaries, diagnostics, mutation previews, and build lifecycle state;
2. Studio will consume that operational model through adapters instead of reconstructing packer semantics locally;
3. the event and concurrency model must stay coherent when the packer is integrated into the Studio Assets workspace and shell.

Without an explicit decision, the repository risks drifting into duplicated semantics:

• Studio deriving packer-facing summaries from filesystem heuristics;
• Studio inventing lifecycle meaning not present in packer events;
• concurrent mutation or build behavior becoming observable in inconsistent ways.

Decision

The following direction is adopted:

1. prometeu-packer is the semantic owner of asset operational state.
2. Studio is a consumer and remapper of packer responses and events, not a competing source of packer truth.
3. The baseline packer write policy is a single-writer semantic lane per project.
4. Packer observability is packer-native and causality-preserving.
5. Studio adapters may reshape packer data for UI presentation, but may not invent packer semantics, causal relationships, or final outcomes absent from packer responses/events.

Adopted Constraints

1. Summary and Response Authority

• asset summary, details, diagnostics, preview, and build/mutation lifecycle state originate in the packer;
• Studio may use packer responses directly or remap them into view models;
• Studio must not define an alternative packer summary model from direct filesystem inspection once the packer-backed path exists;
• UI-oriented phrasing or grouping is allowed only as a remapping of packer-owned semantics.

2. Concurrency Model

• coordination is project-scoped;
• unrelated projects are not forced into one global execution lane;
• read/read may run concurrently when reads observe a coherent snapshot;
• read/write must not expose torn intermediate state;
• write/write on the same project is serialized;
• build/write on the same project is serialized unless a future explicit transactional model supersedes this baseline;
• preview generation may run outside the final commit-critical section when safe, but final apply/commit remains serialized.

3. Event and Observability Model

• the packer emits the authoritative event stream for asset operations;
• each logical operation must carry a stable operation_id;
• events within one operation must carry monotonic sequence;
• baseline event payloads must preserve fields equivalent to:
  • project_id
  • operation_id
  • sequence
  • kind
  • timestamp
  • summary
  • progress when applicable
  • affected_assets when applicable
• event ordering must remain causally coherent for one operation;
• progress-like low-value repetition may be coalesced by sinks/adapters;
• terminal lifecycle markers must remain individually observable.

4. Studio Adapter Boundary

• Studio adapts packer events into the existing Studio event bus and workspace models;
• Studio may convert packer-native envelopes into Studio-native event types for shell/workspace consumption;
• that adapter layer must remain translational, not semantic-authoritative;
• Activity, progress, and staged mutation surfaces in Studio must reflect packer-native lifecycle, not replace it.

Why This Direction Was Chosen

• It prevents split-brain semantics between packer and Studio.
• It keeps packer behavior testable outside JavaFX.
• It allows Studio UI iteration without moving domain rules into the UI layer.
• It gives concurrency and observability one owner, which is necessary for deterministic mutation and build behavior.

Explicit Non-Decisions

This decision does not define:

• the final internal threading primitives or executor topology of prometeu-packer;
• a watch daemon or continuous background worker model;
• remote/shared cache coordination;
• cross-project scheduling policy beyond allowing separate projects to coordinate independently;
• final event transport beyond the local adapter/event sink model currently planned.

Implications

• read adapters belong in the packer integration track, not in Studio-local filesystem services;
• mutation preview/apply semantics belong in packer services and only map into Studio staged UI models;
• Studio Activity and progress integration must preserve packer causality metadata, even if the UI renders a simplified form;
• tests must verify both same-project write serialization and event ordering through the Studio adapter path.

Propagation Targets

Specs:

• ../specs/5. Diagnostics, Operations, and Studio Integration Specification.md

Plans:

• ../pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md
• ../pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md
• ../pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md

Cross-domain references:

• ../../studio/specs/4. Assets Workspace Specification.md
• ../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md

Implementation surfaces:

• future prometeu-packer service contracts and event sink abstractions
• Studio packer read/write/event adapters
• Studio Activity/progress mapping code

Validation Notes

The decision is correctly implemented only when all of the following are true:

• the same packer operation can be replayed and observed without Studio inventing hidden state;
• conflicting writes on one project cannot commit concurrently;
• Activity/progress in Studio can be driven from packer-native events alone;
• Studio summaries are either direct packer outputs or remapped packer outputs, never independent semantic recomputation.