# PR-11 Packer Runtime Restructure, Snapshot Authority, and Durable Commit

Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`

## Briefing

The current `prometeu-packer` production track established the packer as the semantic owner of asset state, write semantics, diagnostics, and operational events.

The next architectural step is to restructure the packer so it behaves like a filesystem-first project-scoped operational runtime for the service surface the Studio actually uses today, rather than a collection of filesystem-per-call services:

- reads should come from a coherent in-memory snapshot;
- writes should execute through a packer-owned write path;
- state transitions should be coordinated by the packer, not by incidental caller sequencing;
- durable visibility should be defined by commit to disk, not by partially observed intermediate filesystem state;
- Studio should remain a frontend consumer of packer-owned read/write/event contracts.

This is a service-first re-architecture program, not a cosmetic refactor.
The likely outcome is a substantial internal rewrite of the packer service layer while preserving and tightening the external semantic contract already defined by the packer specs.

The current wave is intentionally narrow:

- build only the embedded service runtime needed by Studio asset management;
- remove unused or out-of-scope capabilities from the active code path instead of carrying them forward speculatively;
- reintroduce `doctor`, `build/pack`, and background reconcile only when a later concrete service need justifies them.

This PR is an umbrella planning artifact only.
It does not authorize direct implementation work by itself.

## Objective

Define and execute a family of packer PRs that turns the packer into a project-scoped runtime with:

- explicit read and write APIs;
- a coherent in-memory project snapshot;
- packer-owned threading for state write coordination;
- durable commit to workspace files as the persistence boundary;
- causality-preserving events for Studio and other tooling consumers;
- an aggressively reduced active surface focused on the service capabilities currently consumed by Studio.

Communication model baseline:

- request/response is the primary contract for queries and commands;
- events are the primary contract for asynchronous lifecycle, progress, divergence, and terminal operation reporting;
- synchronous command entrypoints may return a `Future` directly when the caller needs an operation handle for later completion;
- long-running command completion may still be observed through causality-preserving events correlated to that operation;
- the packer should not use events as a replacement for normal query/command response semantics.

## Dependencies

- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
- [`../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)
- [`../decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md`](../decisions/Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md)
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)

Decision baseline already in place:

- [`../decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](../decisions/Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md)

This PR is the umbrella execution plan for that direction.
It is not a substitute for that decision record and it is not itself an implementation PR.

## Scope

- lock the architectural target and implementation decomposition for the runtime-restructure wave
- perform cleanup and active-surface reduction before runtime work begins
- define a packer-internal project runtime model that owns one coherent state snapshot per active project
- define packer-owned read APIs that serve data from the runtime snapshot instead of recomputing the full model from disk for each call
- define a packer-owned write lane that executes on packer-controlled threading rather than caller-controlled sequencing
- define the durable commit model from in-memory state to workspace files under `assets/` and `assets/.prometeu/`
- define snapshot refresh/bootstrap/recovery behavior
- define embedded-host bootstrap rules for supplying the explicit `PackerEventSink` used by packer event publication, with host-side bridging to any shared typed event bus
- define the query/command versus event boundary for Studio integration
- define how synchronous command entrypoints expose `Future`-based completion to callers that need direct operation handles
- migrate only the service surface currently used by Studio asset management onto the runtime model
- remove or retire implementation paths that are not used by that active service wave
- preserve Studio as a consumer of packer responses and events, not an owner of packer semantics
- retire the current filesystem-per-call service style once the runtime-backed path is stable

## Non-Goals

- no direct code implementation inside `PR-11`
- no direct rollout of one monolithic runtime rewrite under one follow-up change
- no redesign of Studio workspace UX
- no remote daemon or IPC transport in this wave
- no distributed or multi-process transactional protocol
- no final watch-service design for external filesystem edits
- no `doctor` implementation in this wave
- no `build/pack` implementation in this wave
- no background reconcile implementation in this wave
- no silent semantic changes to asset identity, registry authority, or write behavior already defined in packer specs
- no replacement of the packer event model with Studio-local orchestration

## Execution Method

This work must be executed as a family of follow-up PRs.
`PR-11` freezes the target architecture and the decomposition logic, but implementation starts only in later PR documents.

The follow-up implementation PR family is:

1. [`PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md)
2. [`PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md`](./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md)
3. [`PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
4. [`PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
5. [`PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
6. [`PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
7. [`PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md)

Each follow-up PR should remain granular enough to:

- have a narrow acceptance surface;
- carry its own tests and rollback story;
- avoid mixing cleanup, bootstrap, runtime-core, UI-adapter, and deferred capability concerns in one code change.

Wave discipline for all follow-up PRs:

- remove code that is not used by the active Studio-facing service wave instead of preserving speculative extension points;
- do not reintroduce `doctor`, `build/pack`, or background reconcile as placeholders;
- add capabilities later only when the active Studio integration requires them.

Deferred from the current wave:

- `doctor`
- `build/pack`
- background reconcile/diff observer

Those capabilities should be reintroduced only when the active service wave needs them.

## Acceptance Criteria

- `PR-11` remains an umbrella plan rather than a direct implementation vehicle
- the follow-up implementation family is clear enough that later PRs can be opened without reopening the architecture debate
- the packer has an explicit project-scoped runtime authority model
- read operations observe coherent snapshot state
- write operations are executed through packer-owned coordination on packer-controlled threading
- durable visibility is defined by successful commit, not by partially observed intermediate filesystem state
- same-project write conflicts cannot commit concurrently
- same-project read/write interaction does not expose torn committed truth
- asset identity, registry authority, and write semantics remain consistent with existing packer specs
- the active implementation surface contains only the service capabilities currently used by Studio
- unused or out-of-scope legacy capability paths are removed instead of lingering in parallel
- Studio consumes packer read/write/event APIs as a frontend consumer and does not regain semantic ownership
- request/response remains the primary query/command contract while events remain the asynchronous observability contract
- synchronous command APIs may expose `Future` completion directly without collapsing the event lane into ad hoc RPC polling
- event ordering and `operation_id` causality remain valid through the restructured runtime
- the packer keeps `PackerEventSink` as its publication boundary instead of depending directly on host event bus types
- embedded hosts may bridge `PackerEventSink` into a container-owned typed event bus, but the packer API must not normalize a silent `noop` default as production bootstrap behavior

## Validation

- snapshot bootstrap tests for projects with valid, invalid, and partially broken asset workspaces
- read coherence tests under concurrent read pressure
- write serialization tests for same-project conflicting writes
- failure and recovery tests for interrupted durable commit paths
- write-path regression tests on top of the runtime core for the commands currently used by Studio
- cleanup validation proving that inactive `doctor`, `build/pack`, and background reconcile implementation paths are no longer part of the active wave
- event ordering and terminal lifecycle tests through the Studio adapter path
- Studio smoke validation for:
  - asset listing
  - details loading
  - staged writes
  - relocation
  - refresh after packer-owned operations
- bootstrap validation that Studio initializes the container-owned typed event bus before packer-backed runtime use

## Risks and Rollback

- this program may expose that the current service boundaries are too filesystem-centric to preserve cleanly
- removing out-of-scope capabilities now may require later reintroduction work when those capabilities become necessary again
- external filesystem edits during runtime lifetime are not fully solved by this plan and must not be hidden as if they were
- if runtime-backed services prove too invasive, rollback should preserve the current stable service contracts while isolating the runtime work behind new internal packages until the migration is complete

## Affected Artifacts

- `docs/packer/decisions/**`
- `docs/packer/pull-requests/**`
- `docs/packer/decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`
- `docs/packer/specs/1. Domain and Artifact Boundary Specification.md`
- `docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`
- `docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`
- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`
- `docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md`
- `docs/studio/specs/2. Studio UI Foundations Specification.md`
- `docs/studio/specs/4. Assets Workspace Specification.md`
- `prometeu-packer/src/main/java/p/packer/**`
- `prometeu-packer/src/test/java/p/packer/**`
- `prometeu-studio/**` integration adapter and smoke coverage

## Suggested Next Step

Do not start code execution directly from this plan.

The next correct step is to derive granular implementation PRs from `PR-11`, each scoped to one execution front of the runtime-restructure wave.