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`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)

Plans:

- [`../pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md`](../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-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md)
- [`../pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md`](../pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md)

Cross-domain references:

- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
- [`../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.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.