asset workspace progress

This commit is contained in:
2026-03-24 13:42:44 +00:00
parent 4c8190cc31
commit 59e1ad5ecf
286 changed files with 7156 additions and 8898 deletions
@@ -0,0 +1,194 @@
# 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.
@@ -0,0 +1,74 @@
# PR-12 Cleanup and Unused Surface Removal Before the Runtime Service Wave
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
Before introducing the runtime service wave, the current packer code should be reduced and cleaned so the next PRs are not built on top of contradictory seams.
The current code still mixes:
- implicit concrete instantiation inside services;
- filesystem-per-call orchestration;
- service boundaries that do not match the desired runtime model;
- inactive or out-of-scope capabilities that are not part of the immediate Studio-driven service wave.
This PR creates the cleanup baseline.
## Objective
Remove unused/out-of-scope packer surfaces, align code with the current specs, and prepare a smaller active service boundary for the runtime implementation track.
## Dependencies
- [`./PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](./PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md)
- [`../decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](../decisions/Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md)
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
## Scope
- align `asset.json` handling with the current spec baseline, including `asset_uuid`
- remove inactive `doctor`, `build/pack`, and reconcile-oriented implementation paths from the active runtime-service wave
- remove concrete default instantiation patterns that hide composition ownership
- simplify the active service surface to what the current Studio integration actually needs
- remove code that is not being used for the immediate service-only wave
- correct service contract seams that currently mix read-oriented and mutation-oriented responsibilities in contradictory ways
## Non-Goals
- no runtime snapshot yet
- no write lane yet
- no Studio adapter redesign yet
- no reintroduction of doctor/build/reconcile in this wave
## Execution Method
1. Align manifest/declaration code with the current spec baseline.
2. Remove inactive service paths that are not part of the current Studio-driven runtime wave.
3. Eliminate implicit composition where services instantiate concrete collaborators by default.
4. Correct active service contracts so the remaining surface matches the Studio-facing runtime plan.
5. Leave the repository with one smaller active surface that the runtime work can replace cleanly.
## Acceptance Criteria
- `asset_uuid` is no longer missing from the active declaration path
- inactive `doctor`, `build/pack`, and reconcile implementation paths are removed from the active wave
- concrete service composition is no longer hidden behind broad default constructors in the active path
- contradictory active service contracts are corrected before runtime work starts
- the remaining active surface is focused on the service capabilities the Studio currently needs
## Validation
- declaration/parser tests for the manifest baseline
- cleanup tests confirming out-of-scope service paths are no longer part of the active surface
- regression tests confirming the remaining active service surface still works
- smoke validation that Studio-facing packer usage still boots after the cleanup
## Affected Artifacts
- `prometeu-packer/src/main/java/p/packer/**`
- `prometeu-packer/src/test/java/p/packer/**`
- `prometeu-studio/**` only where the active service surface changes
@@ -0,0 +1,73 @@
# PR-13 Embedded Bootstrap, Container-Owned Event Bus, and Packer Composition Root
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
After the cleanup baseline, the next step is to make embedded Studio bootstrap explicit and introduce one composition root for the packer.
This is where the Studio `Container` becomes a contract plus global holder, while the concrete embedded boot and `prometeu-packer-v1` wiring move into the application layer.
## Objective
Deliver the embedded bootstrap contract, explicit `PackerEventSink` wiring, and an explicit `prometeu-packer-api` to `prometeu-packer-v1` composition root for Studio embedding.
## Dependencies
- [`./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- cross-domain reference: [`../../studio/specs/2. Studio UI Foundations Specification.md`](../../studio/specs/2.%20Studio%20UI%20Foundations%20Specification.md)
## Scope
- define the embedded packer bootstrap contract
- define the packer composition root for the active service wave inside the application layer
- keep `prometeu-studio` bound only to `prometeu-packer-api`
- wire the Studio `Container` contract/holder as the owner of the shared typed event bus reference used by the host-side `PackerEventSink` bridge
- ensure application boot installs a `Container` implementation before packer-backed use begins
- make the active embedded runtime entrypoint explicit enough that future capabilities do not depend on hidden constructors or side boot paths
## Non-Goals
- no runtime snapshot yet
- no read migration yet
- no write lane yet
- no alternate bootstrap retained for inactive `doctor`, `build/pack`, or reconcile paths
## Execution Method
1. Define the explicit packer bootstrap/composition entrypoint.
2. Make the host-provided `PackerEventSink` an explicit dependency for Studio embedding.
3. Refactor Studio `Container` into a contract plus installed global holder.
4. Move concrete packer wiring to the application layer that chooses `prometeu-packer-v1`.
5. Remove remaining ambiguity around packer-local versus container-owned event visibility by bridging `PackerEventSink` into the host bus at the application layer.
5. Remove remaining embedded bootstrap variants that only exist to keep inactive service surfaces alive.
## Acceptance Criteria
- the active packer wave has one explicit composition root
- `prometeu-studio` depends only on `prometeu-packer-api`
- the application layer installs the `Container` implementation and chooses `prometeu-packer-v1`
- Studio `Container` owns the shared typed event bus reference through its installed implementation
- the packer composition root receives an explicit `PackerEventSink` rather than reaching directly into host event bus types
- packer-backed work starts only after `Container.install(...)`
- packer publication uses `PackerEventSink`, and the application layer bridges that sink into the container-owned path when embedded in Studio
- no public `PackerEventSink.noop()`-style default is treated as acceptable production bootstrap behavior
- hidden bootstrap paths that only support inactive service surfaces are removed
## Validation
- bootstrap tests for the packer composition root
- Studio boot tests for `Container.install(...)`
- integration tests for packer event visibility through the host bridge into the container-owned path
## Affected Artifacts
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**`
- `prometeu-studio/src/main/java/p/studio/Container.java`
- `prometeu-studio/src/main/java/p/studio/events/**`
- `prometeu-app/src/main/java/p/studio/App.java`
- `prometeu-app/src/main/java/p/studio/AppContainer.java`
@@ -0,0 +1,68 @@
# PR-14 Project Runtime Core, Snapshot Model, and Lifecycle
Domain Owner: `docs/packer`
## Briefing
With cleanup and bootstrap in place, the packer can now introduce the actual project runtime.
This PR adds the runtime boundary, snapshot state model, bootstrap/load behavior, and disposal lifecycle that later query and command services will use.
## Objective
Deliver the project-scoped runtime core and one coherent in-memory snapshot model for the active service wave.
## Dependencies
- [`./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md)
- [`./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)
- [`../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)
## Scope
- add the project runtime abstraction
- define snapshot content and generation ownership only for the active service wave
- define runtime bootstrap/load and disposal behavior
- isolate filesystem repositories behind the runtime boundary
- keep snapshot scope limited to the data needed by the active Studio-facing service path
- keep the runtime implementation inside `prometeu-packer-v1` while preserving the external contract in `prometeu-packer-api`
## Non-Goals
- no Studio adapter work yet
- no doctor/build/reconcile functionality
- no full query migration yet
- no write lane yet
- no speculative snapshot fields for capabilities that are not part of the active wave
## Execution Method
1. Introduce project runtime state/container types.
2. Load registry plus asset declarations into the runtime snapshot.
3. Define runtime generation, refresh, and disposal rules.
4. Keep the runtime state minimal and aligned with the currently used service surface.
5. Make later query/command work depend on this runtime boundary rather than direct filesystem scans.
## Acceptance Criteria
- one coherent runtime exists per active project
- runtime bootstrap/load is explicit and testable
- runtime disposal is explicit
- filesystem repositories are isolated behind the runtime boundary
- runtime state is limited to what the active Studio service wave actually consumes
## Validation
- runtime bootstrap tests
- snapshot generation tests
- lifecycle tests for bootstrap, refresh, and disposal
## Affected Artifacts
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**`
@@ -0,0 +1,70 @@
# PR-15 Snapshot-Backed Asset Query Services
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The first functional runtime-backed service wave should focus on queries.
This PR moves the asset query surface used by Studio onto the runtime snapshot and defines coherent query behavior without expanding into doctor/build/reconcile.
## Objective
Deliver snapshot-backed query services for the currently used asset-management surface.
## Dependencies
- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
## Scope
- migrate `init_workspace`
- migrate `list_assets`
- migrate `get_asset_details`
- keep the query path coherent through the runtime snapshot
- preserve the packer-owned summary/details contract used by Studio
- remove leftover query orchestration that only existed to feed inactive `doctor`, `build/pack`, or reconcile flows
- preserve the modular boundary where `prometeu-studio` consumes only `prometeu-packer-api`
## Non-Goals
- no command/write lane yet
- no mutation apply yet
- no doctor/build/reconcile
## Execution Method
1. Route the active query APIs through the runtime snapshot.
2. Preserve coherent results across repeated query use.
3. Remove repeated recomputation from the active query path.
4. Remove active query seams that only support deferred capabilities.
5. Keep Studio-facing response semantics stable.
## Acceptance Criteria
- active asset queries are served from the runtime snapshot
- normal query use no longer depends on full filesystem recomputation
- Studio-facing details/listing semantics remain stable
- no doctor/build/reconcile behavior is introduced by this PR
- unused query seams kept only for deferred capabilities are removed from the active path
## Validation
- regression tests for `init_workspace`
- regression tests for `list_assets`
- regression tests for `get_asset_details`
- Studio smoke validation for list/details loading
## Affected Artifacts
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**`
- `prometeu-studio/**` query adapter coverage
@@ -0,0 +1,71 @@
# PR-16 Write Lane, Command Completion, and Used Write Services
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
After queries are runtime-backed, the next step is the minimal command surface actually used by Studio.
This PR introduces the project write lane, synchronous command completion semantics, and the write services currently needed by Studio, without reintroducing doctor, build, or reconcile work.
## Objective
Deliver the write lane plus only the write/command surface currently exercised by the Studio `Assets` workspace on top of the runtime model.
## Dependencies
- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
- [`../decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md`](../decisions/Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
## Scope
- implement the project-scoped write lane
- define durable visibility after successful commit
- define request/response command semantics with optional `Future`-based completion
- implement only the write surface currently used by Studio `Assets`
- preserve causal lifecycle events for command execution
- reintroduce command/write support in `prometeu-packer-v1` without collapsing the `prometeu-packer-api` boundary
## Non-Goals
- no doctor
- no build/pack
- no background reconcile observer
## Execution Method
1. Add the runtime-backed write lane.
2. Define synchronous command response plus optional `Future` completion semantics.
3. Reintroduce only the currently used write services onto the runtime.
4. Remove command surfaces that remain out of scope for the active Studio service wave.
5. Preserve asynchronous lifecycle events as observability, not as the primary command contract.
## Acceptance Criteria
- same-project commands are serialized by the packer
- committed state becomes visible only after successful durable commit
- synchronous command APIs may expose `Future` completion directly
- the write services currently used by Studio run on the runtime-backed path
- no doctor/build/reconcile behavior is introduced by this PR
- deferred command surfaces are not kept alive in the active implementation by placeholder adapters
## Validation
- write-lane concurrency tests
- commit failure/recovery tests
- command completion tests for response plus `Future`
- write regression tests for the active Studio write surface
- negative validation proving `doctor`, `build/pack`, and reconcile command paths are not part of the active wave
## Affected Artifacts
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**`
- `prometeu-studio/**` command integration coverage
@@ -0,0 +1,73 @@
# PR-17 Studio Runtime Adapter and Assets Workspace Consumption
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
Once the active query and command surface is runtime-backed, Studio should consume that path as a frontend without recreating packer semantics.
This PR hardens the Studio adapters and the `Assets` workspace consumption path for the service-only wave while preserving the modular split between `prometeu-packer-api`, `prometeu-packer-v1`, `prometeu-studio`, and `prometeu-app`.
## Objective
Deliver the Studio-side adapter and `Assets` workspace integration for the active runtime-backed service surface.
## Dependencies
- [`./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)
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
- cross-domain reference: [`../../studio/specs/2. Studio UI Foundations Specification.md`](../../studio/specs/2.%20Studio%20UI%20Foundations%20Specification.md)
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
## Scope
- adapt Studio to consume runtime-backed packer queries and commands
- preserve `request/response` as the primary integration model
- consume packer lifecycle events through the host bridge from `PackerEventSink` into the container-owned typed event bus path
- keep the `Assets` workspace aligned with the active service-only wave
- remove adapter branches that only exist for inactive `doctor`, `build/pack`, or reconcile usage
- keep `prometeu-studio` bound only to `prometeu-packer-api`
- let `prometeu-app` remain responsible for installing the concrete `Container` implementation, applying the `p.packer.Packer` entrypoint from `prometeu-packer-v1`, and bridging `PackerEventSink` into the host bus
## Non-Goals
- no doctor UI
- no pack/build UI
- no reconcile-state UI beyond what the current service wave actually exposes
## Execution Method
1. Update the Studio adapter layer to consume the runtime-backed service path.
2. Preserve translational mapping only.
3. Validate that `prometeu-studio` does not depend on `prometeu-packer-v1` classes directly.
4. Validate command submission plus event-driven lifecycle visibility through the host `PackerEventSink` bridge and shared bus path.
4. Remove adapter branches that only keep deferred capabilities artificially wired.
5. Keep the `Assets` workspace focused on the currently active service surface.
## Acceptance Criteria
- Studio remains a consumer of packer runtime semantics
- `Assets` workspace list/details/actions run through the active runtime-backed service path
- command submission plus event observation are coherent end to end
- no inactive doctor/build/reconcile surfaces are reintroduced
- Studio adapters no longer preserve dead branches for deferred capability families
- `prometeu-studio` depends only on `prometeu-packer-api`
- `prometeu-app` is the layer that binds the concrete `Container` implementation and the `p.packer.Packer` entrypoint from `prometeu-packer-v1`
- Studio consumes packer lifecycle visibility through a host-provided `PackerEventSink` bridge rather than by exposing host bus types inside packer contracts
## Validation
- Studio adapter tests
- `Assets` workspace smoke tests
- end-to-end tests for list/details/write flows used by Studio
## Affected Artifacts
- `prometeu-studio/src/main/java/p/studio/**`
- `prometeu-studio/src/test/java/p/studio/**`
- `prometeu-app/src/main/java/p/studio/**`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` integration-facing contracts
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` embedded runtime implementation surfaces
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**` embedded runtime event surfaces
@@ -0,0 +1,66 @@
# PR-18 Legacy Service Retirement and Regression Hardening
Domain Owner: `docs/packer`
## Briefing
After the active service-only wave is fully running through the runtime path, the repository should not keep duplicated legacy orchestration around as a competing semantic track.
This PR retires the superseded legacy paths and hardens regression coverage around the smaller active service surface.
It also closes the cleanup promise from `PR-12` by ensuring no unused packer capability families survive just because they existed before the runtime service wave.
## Objective
Remove superseded legacy service paths and strengthen regression protection for the runtime-backed service wave.
## Dependencies
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
## Scope
- retire duplicated filesystem-per-call paths superseded by the active runtime-backed service wave
- remove temporary shims that were tolerated only during the migration window
- harden regression coverage around the remaining active service surface
- remove leftover inactive `doctor`, `build/pack`, and reconcile code that no longer belongs to the service-only wave
- preserve the `prometeu-packer-api` surface as the stable consumer contract while retiring legacy implementation paths in `prometeu-packer-v1`
## Non-Goals
- no doctor reintroduction
- no build/pack reintroduction
- no reconcile observer work
- no new architecture decisions
## Execution Method
1. Remove superseded legacy paths.
2. Remove temporary migration shims once the runtime-backed path is complete.
3. Simplify the active service composition around the runtime boundary.
4. Strengthen regression coverage around the remaining service wave.
5. Verify no split-brain semantics remain between active and legacy paths.
## Acceptance Criteria
- superseded legacy paths are removed
- the active runtime-backed service wave is the only semantic path for the currently used functionality
- regression coverage protects the reduced active surface
- no inactive capability family survives in code solely as speculative future support
## Validation
- full active-service regression suite
- Studio embedding regression suite
- targeted tests proving no disagreement remains between active and legacy paths
## Affected Artifacts
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**`
- integration fixtures
+16 -1
View File
@@ -70,7 +70,22 @@ The current production track for the standalone `prometeu-packer` project is:
8. [`PR-08-assets-pa-and-companion-artifact-emission.md`](./PR-08-assets-pa-and-companion-artifact-emission.md)
9. [`PR-09-event-lane-progress-and-studio-operational-integration.md`](./PR-09-event-lane-progress-and-studio-operational-integration.md)
10. [`PR-10-versioning-migration-trust-and-production-gates.md`](./PR-10-versioning-migration-trust-and-production-gates.md)
11. [`PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](./PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md)
12. [`PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md)
13. [`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)
14. [`PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
15. [`PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
16. [`PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
17. [`PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
18. [`PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md)
Current wave discipline from `PR-11` onward:
- cleanup and active-surface reduction happen before runtime implementation;
- the wave is service-first and Studio-driven;
- `doctor`, `build/pack`, and background reconcile are explicitly deferred;
- code that is not used by the active service wave should be removed instead of preserved speculatively.
Recommended dependency chain:
`PR-01 -> PR-02 -> PR-03 -> PR-04 -> PR-05 -> PR-06 -> PR-07 -> PR-08 -> PR-09 -> PR-10`
`PR-01 -> PR-02 -> PR-03 -> PR-04 -> PR-05 -> PR-06 -> PR-07 -> PR-08 -> PR-09 -> PR-10 -> PR-11 -> PR-12 -> PR-13 -> PR-14 -> PR-15 -> PR-16 -> PR-17 -> PR-18`