195 lines
12 KiB
Markdown
195 lines
12 KiB
Markdown
# 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.
|