asset workspace progress
This commit is contained in:
+175
@@ -0,0 +1,175 @@
|
||||
# Filesystem-First Operational Runtime and Reconcile Boundary Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-15
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Context
|
||||
|
||||
The current packer model already has the right core separation:
|
||||
|
||||
- `assets/.prometeu/index.json` is the authoritative registry/catalog for managed assets;
|
||||
- each asset root is anchored by `asset.json`;
|
||||
- `asset.json` is the authoring-side declaration of how that asset is packed;
|
||||
- Studio is meant to consume packer-owned operational semantics instead of recreating them locally.
|
||||
|
||||
What is still missing is a clear architectural decision for how the packer should behave operationally at runtime.
|
||||
|
||||
The repository now needs an answer to these questions:
|
||||
|
||||
1. should the packer remain a collection of direct filesystem services, recomputing state per request;
|
||||
2. should the packer become a pure database-style system that displaces the open filesystem workflow;
|
||||
3. or should it become a filesystem-first operational runtime that maintains an in-memory snapshot while preserving the workspace as the durable authoring surface.
|
||||
|
||||
The wrong answer here would create product friction.
|
||||
|
||||
If the packer behaves like a pure database, it will fight the real creative workflow where developers:
|
||||
|
||||
- edit files with their preferred tools;
|
||||
- move directories manually when needed;
|
||||
- inspect and version workspace files directly;
|
||||
- expect the Studio to help organize work, not imprison it.
|
||||
|
||||
At the same time, if the packer stays purely filesystem-per-call, it will remain too expensive, too incoherent under concurrent use, and too weak as the operational source of truth for Studio.
|
||||
|
||||
## Decision
|
||||
|
||||
The following direction is adopted:
|
||||
|
||||
1. `prometeu-packer` remains `filesystem-first`.
|
||||
2. The packer becomes a `project-scoped operational runtime`, not a pure database.
|
||||
3. The packer maintains an in-memory project snapshot for live operational reads and write coordination.
|
||||
4. The durable authoring workspace on disk remains the final persisted source of truth.
|
||||
5. The packer owns request/response read and write APIs over that runtime snapshot.
|
||||
6. Writes execute through a packer-owned project write lane and become durably visible only after commit succeeds.
|
||||
7. The packer will support background divergence detection between runtime snapshot and filesystem state.
|
||||
8. Divergence detection must surface reconcile state explicitly; it must not silently invent or hide semantic repairs.
|
||||
9. Studio remains a frontend consumer of packer responses, commands, and events.
|
||||
10. When embedded inside Studio, the packer runtime is bootstrapped with a typed event bus reference supplied by the Studio bootstrap container.
|
||||
|
||||
## Adopted Constraints
|
||||
|
||||
### 1. Filesystem-First Authority
|
||||
|
||||
- the asset workspace under `assets/` remains the authoring environment;
|
||||
- `asset.json` remains the asset-local declaration contract;
|
||||
- `assets/.prometeu/index.json` remains the authoritative registry/catalog for managed assets;
|
||||
- the packer runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring format.
|
||||
|
||||
### 2. Identity and Declaration Split
|
||||
|
||||
- `asset_id`, `included_in_build`, and registry-managed location tracking remain registry/catalog concerns;
|
||||
- `asset.json` remains primarily a declaration of the asset contract and packing inputs/outputs;
|
||||
- `asset.json` may carry the asset-local identity anchor needed for reconcile, specifically `asset_uuid`;
|
||||
- `asset.json` must not become a dumping ground for transient UI state, cache state, or catalog-derived bookkeeping that belongs in `index.json` or other packer-owned control files.
|
||||
|
||||
### 3. Snapshot-Backed Read Semantics
|
||||
|
||||
- normal read APIs should serve from a coherent in-memory project snapshot;
|
||||
- the packer must not require a full workspace recomputation for every normal read call once the runtime is active;
|
||||
- concurrent reads may proceed when they observe a coherent snapshot generation;
|
||||
- reads must not expose torn intermediate write state as committed truth.
|
||||
|
||||
### 4. Packer-Owned Write Execution
|
||||
|
||||
- write operations on one project are coordinated by the packer, not by caller timing;
|
||||
- the baseline policy remains a single-writer semantic lane per project;
|
||||
- write intent may compute previews before final commit when safe;
|
||||
- final apply/commit remains serialized per project;
|
||||
- successful durable commit defines post-write visibility.
|
||||
|
||||
### 5. Durable Commit Boundary
|
||||
|
||||
- the packer runtime may stage write changes in memory before disk commit;
|
||||
- partially applied intermediate state must not be presented as durably committed truth;
|
||||
- commit failure must leave the project in an explicitly diagnosable condition;
|
||||
- recovery and reconcile rules must be designed as packer behavior, not delegated to Studio guesswork.
|
||||
|
||||
### 6. Divergence Detection and Reconcile
|
||||
|
||||
- a future packer-owned background observation path may detect divergence between runtime snapshot and filesystem state;
|
||||
- this path exists to keep the runtime honest with respect to manual or external edits;
|
||||
- divergence must result in explicit runtime state such as stale, diverged, reconciling, or failed;
|
||||
- the packer must not silently rewrite user content just because divergence was observed;
|
||||
- reconcile is an explicit packer-owned behavior and must preserve causality in events and responses.
|
||||
|
||||
### 7. Studio Consumer Boundary
|
||||
|
||||
- Studio consumes packer read responses, write outcomes, and packer-native lifecycle events;
|
||||
- Studio may render stale/diverged/reconciling states, but must not invent packer-side reconcile semantics;
|
||||
- Studio must not become the owner of filesystem-vs-snapshot conflict resolution;
|
||||
- the Studio integration contract should remain command-oriented and event-driven.
|
||||
|
||||
### 8. Embedded Event Bus Bootstrap
|
||||
|
||||
- when the packer is embedded inside Studio, it must receive a typed event bus reference during bootstrap instead of creating an unrelated local event system;
|
||||
- that reference is used for packer event publication and any packer-side subscription/unsubscription behavior needed by the embedded runtime;
|
||||
- in Studio, the owner of that typed event bus reference is the application container;
|
||||
- the Studio `Container` must be initialized as part of Studio boot before packer-backed workspaces or adapters start consuming packer services.
|
||||
|
||||
## Why This Direction Was Chosen
|
||||
|
||||
- It preserves the developer's open creative workflow around normal files and directories.
|
||||
- It keeps the packer useful as an organizing and coordinating system instead of turning it into an opaque silo.
|
||||
- It allows fast and coherent reads for Studio and tooling.
|
||||
- It gives write coordination, commit visibility, and operational causality one owner.
|
||||
- It creates a realistic path toward future background divergence detection without pretending that the filesystem stopped mattering.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not define:
|
||||
|
||||
- the final class/module names of the packer runtime implementation;
|
||||
- the final executor/thread primitive used internally;
|
||||
- the exact event vocabulary for all future reconcile states;
|
||||
- the final automatic-vs-manual reconcile policy for each drift scenario;
|
||||
- a watch-service or daemon transport implementation;
|
||||
- remote or multi-process synchronization;
|
||||
- a pure database persistence model.
|
||||
|
||||
## Implications
|
||||
|
||||
- the packer runtime track must preserve `index.json` plus `asset.json` as the durable workspace artifacts;
|
||||
- `asset.json` should evolve carefully to support local identity anchoring without absorbing catalog-only fields;
|
||||
- the runtime snapshot should be described as an operational cache/projection with authority for live service behavior, not as a new authoring truth;
|
||||
- mutation, doctor, build, and read services should converge on the same runtime state model;
|
||||
- future drift detection work must be designed together with diagnostics, refresh, and reconcile surfaces in Studio.
|
||||
- embedded Studio wiring must preserve one container-owned typed event bus reference instead of fragmented packer-local bus ownership.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
Specs:
|
||||
|
||||
- [`../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)
|
||||
- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
|
||||
|
||||
Plans:
|
||||
|
||||
- [`../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md)
|
||||
|
||||
Cross-domain references:
|
||||
|
||||
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
Implementation surfaces:
|
||||
|
||||
- future packer project-runtime/bootstrap code
|
||||
- snapshot-backed read services
|
||||
- project write-lane and durable commit pipeline
|
||||
- drift detection and reconcile state reporting
|
||||
- Studio packer adapters for stale/diverged/reconciling operational states
|
||||
- Studio bootstrap/container wiring for the shared typed event bus reference
|
||||
|
||||
## Validation Notes
|
||||
|
||||
This decision is correctly implemented only when all of the following are true:
|
||||
|
||||
- developers may continue to inspect and edit asset workspace files directly;
|
||||
- packer reads are coherent without requiring full recomputation on each normal request;
|
||||
- same-project writes remain serialized by the packer;
|
||||
- Studio does not observe torn committed truth during write activity;
|
||||
- divergence between runtime snapshot and filesystem state can be detected and surfaced explicitly;
|
||||
- Studio remains a consumer of packer-owned reconcile and lifecycle semantics rather than inventing them.
|
||||
@@ -5,6 +5,7 @@ This directory contains packer decision records.
|
||||
Retained packer decision records:
|
||||
|
||||
- [`Concurrency, Observability, and Studio Adapter Boundary Decision.md`](./Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md)
|
||||
- [`Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](./Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md)
|
||||
|
||||
The first packer decision wave was already consolidated into:
|
||||
|
||||
|
||||
+194
@@ -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.
|
||||
+74
@@ -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
|
||||
+73
@@ -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
|
||||
+71
@@ -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
|
||||
+73
@@ -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
|
||||
@@ -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`
|
||||
|
||||
@@ -20,10 +20,11 @@ This specification consolidates the initial packer agenda and decision wave into
|
||||
2. One asset root contains exactly one anchor `asset.json`.
|
||||
3. `assets/.prometeu/index.json` is the authoritative registry of registered assets.
|
||||
4. `asset.json` is the authoritative asset-local declaration.
|
||||
5. An asset root absent from the registry is `unregistered`.
|
||||
6. `unregistered` assets are always `excluded` from build participation.
|
||||
7. Registered assets may be `included` or `excluded` from build participation without losing identity.
|
||||
8. The baseline build set includes registered assets whose registry entry is marked as build-included.
|
||||
5. `asset.json` must carry the stable `asset_uuid` identity anchor for that asset root.
|
||||
6. An asset root absent from the registry is `unregistered`.
|
||||
7. `unregistered` assets are always `excluded` from build participation.
|
||||
8. Registered assets may be `included` or `excluded` from build participation without losing identity.
|
||||
9. The baseline build set includes registered assets whose registry entry is marked as build-included.
|
||||
|
||||
## Identity Model
|
||||
|
||||
@@ -33,6 +34,12 @@ Each registered asset has:
|
||||
- `asset_uuid`: stable long-lived identity for migration/tooling scenarios
|
||||
- `included_in_build`: build participation flag persisted in the registry
|
||||
|
||||
Identity authority is intentionally split:
|
||||
|
||||
- `asset_uuid` is anchored locally in `asset.json`;
|
||||
- `asset_id` is allocated and persisted by the registry;
|
||||
- registry-managed location and build participation remain catalog concerns in `index.json`.
|
||||
|
||||
The following are not primary identity:
|
||||
|
||||
- `asset_name`
|
||||
@@ -41,6 +48,18 @@ The following are not primary identity:
|
||||
|
||||
`asset_name` may still be used by authoring and runtime-facing APIs as a logical reference label.
|
||||
|
||||
## Local Identity Anchor
|
||||
|
||||
`asset_uuid` is the stable asset-local identity anchor.
|
||||
|
||||
Rules:
|
||||
|
||||
- `asset_uuid` must be present in `asset.json`;
|
||||
- `asset_uuid` is stable across relocate and rename flows;
|
||||
- `asset_uuid` is not allocated from path shape or `asset_name`;
|
||||
- `asset_uuid` allows the packer to reconcile manual workspace changes with the registry/catalog model;
|
||||
- `asset_uuid` does not replace registry authority over `asset_id`, build participation, or managed root tracking.
|
||||
|
||||
## Relocation and Rename
|
||||
|
||||
Moving or renaming an asset root does not change identity.
|
||||
@@ -62,7 +81,8 @@ Rules:
|
||||
|
||||
- it is excluded from the build automatically;
|
||||
- it is diagnosable;
|
||||
- it becomes registered only through explicit flow.
|
||||
- it becomes registered only through explicit flow;
|
||||
- its local `asset_uuid` still matters for structural validation and future reconcile behavior.
|
||||
|
||||
## Build Participation
|
||||
|
||||
@@ -94,7 +114,21 @@ Examples:
|
||||
|
||||
- duplicate or ambiguous anchors under registered expectations;
|
||||
- manual copy that creates identity collision;
|
||||
- registered root missing anchor.
|
||||
- registered root missing anchor;
|
||||
- duplicate `asset_uuid` across different asset roots;
|
||||
- registry/catalog location that no longer matches the asset root carrying the expected `asset_uuid`;
|
||||
- `asset.json` missing or malformed in a root expected to preserve identity.
|
||||
|
||||
## Reconcile Expectations
|
||||
|
||||
The packer may need to reconcile registry/catalog state against the authoring workspace.
|
||||
|
||||
Rules:
|
||||
|
||||
- manual move or rename of an asset root must not imply identity loss by itself;
|
||||
- reconcile should prefer `asset_uuid` when matching a durable asset identity across changed paths;
|
||||
- path drift must not silently rebind one registered asset to another distinct `asset_uuid`;
|
||||
- unresolved identity drift remains diagnosable until explicit repair or successful reconcile.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
|
||||
@@ -13,6 +13,7 @@ This specification consolidates the initial packer agenda and decision wave into
|
||||
The common `asset.json` contract requires these top-level fields:
|
||||
|
||||
- `schema_version`
|
||||
- `asset_uuid`
|
||||
- `name`
|
||||
- `type`
|
||||
- `inputs`
|
||||
@@ -23,6 +24,19 @@ The common contract may also include:
|
||||
|
||||
- `build`
|
||||
|
||||
## Meaning of `asset_uuid`
|
||||
|
||||
`asset_uuid` is the stable asset-local identity anchor.
|
||||
|
||||
Rules:
|
||||
|
||||
- it is required;
|
||||
- it must be stable across relocate and rename flows;
|
||||
- it is not the project-local runtime artifact identity;
|
||||
- it is not a substitute for registry-owned `asset_id`;
|
||||
- it exists so the asset root can preserve identity even when path-based assumptions drift;
|
||||
- it must remain compatible with packer reconcile behavior and migration flows.
|
||||
|
||||
## Meaning of `name`
|
||||
|
||||
`name` is the logical asset reference label.
|
||||
@@ -90,6 +104,17 @@ Rules:
|
||||
- if a parameter affects the runtime-facing output contract, it belongs in `output.metadata`;
|
||||
- `build` must not hide runtime-relevant semantics.
|
||||
|
||||
## Operational State Exclusion
|
||||
|
||||
`asset.json` is a declaration artifact, not a catalog cache.
|
||||
|
||||
Rules:
|
||||
|
||||
- transient UI state must not be stored in `asset.json`;
|
||||
- registry-managed fields such as `asset_id` and `included_in_build` must not be duplicated into `asset.json`;
|
||||
- packer cache or snapshot bookkeeping must not be materialized into `asset.json` as normal operational state;
|
||||
- `asset.json` should remain focused on identity anchoring plus declared authoring/packing behavior.
|
||||
|
||||
## Preload
|
||||
|
||||
Each registered asset must declare preload intent explicitly.
|
||||
|
||||
@@ -44,6 +44,26 @@ Rules:
|
||||
|
||||
The normative operational surface is service-based.
|
||||
|
||||
The packer is a filesystem-first operational runtime.
|
||||
|
||||
Rules:
|
||||
|
||||
- the active project may maintain a coherent in-memory operational snapshot;
|
||||
- normal read requests should be served from that coherent snapshot when the runtime is active;
|
||||
- the runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring store;
|
||||
- the durable authoring workspace remains the persisted source of truth after successful commit.
|
||||
|
||||
### Embedded Bootstrap Rule
|
||||
|
||||
When the packer is embedded inside another host such as Studio, the host must bootstrap the packer integration explicitly.
|
||||
|
||||
Rules:
|
||||
|
||||
- the embedded packer runtime must receive a typed event bus reference from the host when shared host visibility is part of the integration contract;
|
||||
- that reference is the baseline path for packer publish/subscribe integration in the embedded host;
|
||||
- the embedded packer runtime must not quietly create a disconnected parallel event system when host integration expects shared operational visibility;
|
||||
- in Studio, this shared typed event bus reference is owned by the Studio `Container`.
|
||||
|
||||
Baseline core services:
|
||||
|
||||
- `init_workspace`
|
||||
@@ -66,6 +86,26 @@ Operations must distinguish:
|
||||
|
||||
This distinction is part of the service semantics and must be visible to the UI.
|
||||
|
||||
## Runtime State and Visibility
|
||||
|
||||
The packer runtime must make operational freshness explicit.
|
||||
|
||||
At minimum, the model should support states equivalent to:
|
||||
|
||||
- `healthy`
|
||||
- `stale`
|
||||
- `diverged`
|
||||
- `committing`
|
||||
- `reconciling`
|
||||
- `failed`
|
||||
|
||||
Rules:
|
||||
|
||||
- successful durable commit defines the visibility boundary for committed write state;
|
||||
- reads must not present torn in-progress writes as committed truth;
|
||||
- background divergence detection may move a project or asset view into stale/diverged/reconciling state;
|
||||
- Studio may render these states, but must not invent their semantics.
|
||||
|
||||
## Concurrency Model
|
||||
|
||||
The packer concurrency model is conservative and project-scoped.
|
||||
@@ -84,6 +124,13 @@ Rules:
|
||||
- build/write on the same project is serialized unless a future spec introduces an explicit transactional coordination model;
|
||||
- background observation may continue while a serialized write lane is active, but it must not publish misleading post-state before commit visibility.
|
||||
|
||||
### Write Ownership
|
||||
|
||||
- writes on one project execute through a packer-owned write lane;
|
||||
- caller timing must not define final write interleaving semantics;
|
||||
- preview generation may occur before the final commit section when safe;
|
||||
- apply/commit remains the packer-owned visibility boundary.
|
||||
|
||||
## Preview/Apply Model
|
||||
|
||||
Sensitive mutations use staged intent.
|
||||
@@ -102,6 +149,7 @@ At minimum, the model should support fields equivalent to:
|
||||
|
||||
- `status`
|
||||
- `summary`
|
||||
- `runtime_state`
|
||||
- `affected_assets`
|
||||
- `diagnostics`
|
||||
- `proposed_actions`
|
||||
@@ -118,6 +166,7 @@ Responsibilities:
|
||||
- report diagnostics/build/cache activity to the UI;
|
||||
- support live refresh and progress reporting;
|
||||
- avoid blocking the main UI thread.
|
||||
- surface operational freshness and reconcile transitions when they affect Studio-visible state.
|
||||
|
||||
### Initial Event Set
|
||||
|
||||
@@ -135,6 +184,8 @@ The initial structured event set includes:
|
||||
- `action_failed`
|
||||
- `progress_updated`
|
||||
|
||||
Additional runtime/reconcile state events may exist as the operational runtime evolves, but adapters must preserve their causal meaning instead of collapsing them into generic refresh noise.
|
||||
|
||||
### Mutation Serialization
|
||||
|
||||
Mutating asset workflows are serialized semantically.
|
||||
@@ -148,6 +199,7 @@ Rules:
|
||||
- preview generation may run outside the final commit section, but apply/commit remains serialized;
|
||||
- build and sensitive mutation apply must not interleave on the same project in a way that obscures final state;
|
||||
- cancellation or failure must leave the observable project state in a coherent post-operation condition.
|
||||
- divergence detection must not silently rewrite user-authored workspace content as if it were a normal mutation apply.
|
||||
|
||||
### Event Envelope
|
||||
|
||||
@@ -169,6 +221,7 @@ Rules:
|
||||
- `operation_id` is stable for the full lifecycle of one logical operation;
|
||||
- `sequence` is monotonic within one operation;
|
||||
- adapters may remap event shapes for UI consumption, but must not invent causal relationships not present in packer events.
|
||||
- embedded hosts should preserve the same typed event bus reference across packer bootstrap and adapter wiring so subscription and publication stay causally coherent.
|
||||
|
||||
### Event Ordering and Coalescing
|
||||
|
||||
|
||||
@@ -42,6 +42,7 @@ Rules:
|
||||
- migration may be automatic within the supported window;
|
||||
- unsupported versions fail clearly and early;
|
||||
- migration failures must be diagnosable in Studio and CI.
|
||||
- migration may need to preserve or repair identity-bearing fields such as `asset_uuid` without fabricating a different asset identity silently.
|
||||
|
||||
## Runtime Compatibility Boundary
|
||||
|
||||
@@ -73,6 +74,7 @@ Untrusted until validated:
|
||||
- hand-edited or legacy declarations;
|
||||
- imported external project content;
|
||||
- legacy packer artifacts and control data.
|
||||
- runtime snapshot observations that have not yet been reconciled against changed workspace files.
|
||||
|
||||
Trusted only after:
|
||||
|
||||
@@ -80,6 +82,7 @@ Trusted only after:
|
||||
- structural validation;
|
||||
- semantic validation;
|
||||
- version compatibility check.
|
||||
- reconcile or refresh when divergence between snapshot and filesystem has been detected.
|
||||
|
||||
## Plugin and Script Execution
|
||||
|
||||
@@ -102,6 +105,7 @@ At minimum, diagnostics should make clear:
|
||||
- the version found;
|
||||
- the supported range or expectation;
|
||||
- whether migration was attempted;
|
||||
- whether identity-bearing fields or registry/catalog alignment were implicated;
|
||||
- whether manual action is required;
|
||||
- whether the failure blocks build or Studio workflow.
|
||||
|
||||
|
||||
+117
@@ -0,0 +1,117 @@
|
||||
# PR-08 Assets Workspace Panel Package Boundaries and Local Subscriptions
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The current `Assets` workspace still keeps too much control logic concentrated in top-level workspace-area classes.
|
||||
|
||||
That leaves package boundaries flatter than they should be and still weakens the intended Studio model:
|
||||
|
||||
- every panel should own its own workspace-bus subscriptions;
|
||||
- `AssetWorkspace` should stay as composition root and orchestration layer;
|
||||
- the asset list should live in its own package area;
|
||||
- the full right-hand details side should be split into package-owned panels with direct lifecycle-managed subscriptions.
|
||||
|
||||
This refactor is a structural follow-up to the `PR-07` family.
|
||||
|
||||
It does not redefine the event-driven direction; it completes it by enforcing package topology and subscription ownership at the panel level.
|
||||
|
||||
## Objective
|
||||
|
||||
Reorganize the `Assets` workspace into explicit package areas so that every list or details panel consumes the workspace event bus directly and subscribes only to the state it needs.
|
||||
|
||||
After this PR:
|
||||
|
||||
- `AssetWorkspace` composes package-scoped controls instead of hosting panel logic directly;
|
||||
- all asset-list controls live under an `asset list` package area;
|
||||
- the right-hand details side is organized under `details/...` package areas;
|
||||
- `summary`, `actions`, `contract`, `preview`, and `diagnostics` each manage their own subscriptions;
|
||||
- the package layout itself teaches the correct Studio workspace architecture.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
- [`./PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
- [`./PR-07e-assets-refactor-cleanup-and-regression-coverage.md`](./PR-07e-assets-refactor-cleanup-and-regression-coverage.md)
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- create an `asset list` package area under the `Assets` workspace implementation
|
||||
- move the asset-list host and asset-list item control into that package area
|
||||
- require both asset-list host and asset-list item to receive `StudioWorkspaceEventBus`
|
||||
- require both asset-list host and asset-list item to own their own lifecycle-managed subscriptions
|
||||
- create a `details` package area for the full right-hand side of the workspace
|
||||
- split details internals into package-owned subareas such as:
|
||||
- `details/summary`
|
||||
- `details/actions`
|
||||
- `details/contract`
|
||||
- `details/preview`
|
||||
- `details/diagnostics`
|
||||
- require each details panel to subscribe directly to the event stream it consumes
|
||||
- reduce coordinator-style pass-through logic where a child panel can consume the workspace bus directly
|
||||
- keep shared details support code only where it removes real duplication without re-centralizing subscriptions
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no new mutation semantics
|
||||
- no new global event-bus abstraction
|
||||
- no visual redesign of the workspace
|
||||
- no cross-workspace extraction unless a primitive is already justified by this refactor
|
||||
- no return to top-level refresh orchestration as the normal update model
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the target package topology.
|
||||
The package tree should reflect workspace areas, not arbitrary implementation convenience.
|
||||
|
||||
2. Move asset-list code into a dedicated package area.
|
||||
The list host and list item should be colocated and should consume the workspace bus directly.
|
||||
|
||||
3. Normalize asset-list subscriptions.
|
||||
The asset-list host should subscribe to list-level projection state.
|
||||
The asset-list item should subscribe to item-local concerns such as selection and asset patch events.
|
||||
|
||||
4. Move the full right-hand details side into a dedicated `details` package area.
|
||||
The top-level details host should stay thin and should mount panel controls by workspace area.
|
||||
|
||||
5. Split details panels by concern.
|
||||
`summary`, `actions`, `contract`, `preview`, and `diagnostics` should each live in package-owned subareas and subscribe for themselves.
|
||||
|
||||
6. Remove parent-owned update routing where it is only forwarding state to children.
|
||||
If a child panel can subscribe to the workspace bus safely, it should do so directly.
|
||||
|
||||
7. Re-check constructor contracts.
|
||||
Every event-consuming panel should receive the `StudioWorkspaceEventBus` explicitly, plus only the interaction ports it truly needs.
|
||||
|
||||
8. Clean naming and file layout.
|
||||
Class names, package names, and placement should make the `Assets` workspace structure obvious to a new maintainer.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- there is a dedicated package area for the asset list inside the `Assets` workspace
|
||||
- asset-list host and asset-list item both receive `StudioWorkspaceEventBus`
|
||||
- asset-list host and asset-list item both subscribe directly to the events they need
|
||||
- there is a dedicated `details` package area for the right-hand workspace side
|
||||
- `summary`, `actions`, `contract`, `preview`, and `diagnostics` each live in their own package-owned area
|
||||
- each details panel owns its own lifecycle-managed subscriptions
|
||||
- `AssetWorkspace` no longer acts as the effective subscriber for panel-internal state
|
||||
- package structure and constructor boundaries make the lifecycle model explicit
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for lifecycle subscribe/unsubscribe on moved controls
|
||||
- unit tests or focused integration tests proving list item and details panels react from their own subscriptions
|
||||
- regression validation that asset selection and local patch flows still update without workspace-wide refresh
|
||||
- package-level review that no event-consuming panel is left without direct bus access
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` moved into list/details package areas
|
||||
- asset-list controls under a dedicated list package
|
||||
- details controls under `details/...` packages
|
||||
- tests for workspace lifecycle and subscription ownership
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md` if package/lifecycle wording needs tightening after the refactor
|
||||
@@ -0,0 +1,164 @@
|
||||
# PR-09 Asset Move Action and Relocate Wizard
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Adicionar a action `Move` na área de actions do asset selecionado e conectá-la a um wizard de relocação explícita.
|
||||
|
||||
O usuário deve escolher o destino do asset e revisar um resumo antes da execução.
|
||||
Depois da confirmação, o Studio não move diretórios localmente.
|
||||
Ele apenas envia um comando de relocação para o packer, que passa a ser o owner completo da mudança:
|
||||
|
||||
- atualiza o estado interno necessário;
|
||||
- move o diretório do asset dentro da árvore `assets` do projeto;
|
||||
- emite eventos operacionais até a conclusão.
|
||||
|
||||
Este plano também fecha uma regra operacional que precisa existir nas duas pontas:
|
||||
|
||||
- o diretório destino final do asset não pode já ser um root de asset;
|
||||
- portanto, o root destino não pode conter `asset.json`.
|
||||
|
||||
Após a confirmação do resumo, o modal deve entrar em estado de espera com spinner, escutando o evento operacional do packer.
|
||||
Quando a operação terminar:
|
||||
|
||||
- sucesso: o Studio dispara refresh, fecha o modal e reposiciona a seleção;
|
||||
- falha: o modal sai do estado de espera e mostra a falha sem fechar silenciosamente.
|
||||
|
||||
## Objective
|
||||
|
||||
Entregar um fluxo de `Move` que seja explícito, previsível e compatível com o modelo em que o packer executa a mutação real e o Studio apenas comanda e observa.
|
||||
|
||||
Após este PR:
|
||||
|
||||
- a seção `Actions` do selected asset expõe `Move`;
|
||||
- clicar em `Move` abre um wizard dedicado;
|
||||
- o wizard coleta o parent de destino e o nome final do diretório;
|
||||
- o wizard mostra um passo final de resumo antes do comando final;
|
||||
- o Studio não aceita um destino cujo root já contenha `asset.json`;
|
||||
- o packer também rejeita esse destino como regra de segurança e conformance;
|
||||
- a confirmação final envia um comando de relocation para o packer via API;
|
||||
- o modal entra em espera com spinner até receber o evento terminal da operação;
|
||||
- o refresh estrutural só ocorre depois do evento de conclusão do packer.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
- [`./PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md)
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- cross-domain reference: [`../../packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](../../packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md)
|
||||
- cross-domain reference: [`../../packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md`](../../packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- adicionar a action `Move` na seção `Actions` do details
|
||||
- introduzir um `Relocate Wizard` efetivamente utilizável pelo selected asset atual
|
||||
- coletar destino por:
|
||||
- parent directory
|
||||
- destination name
|
||||
- target root derivado
|
||||
- mostrar passo final de resumo antes da confirmação
|
||||
- enviar um comando `RELOCATE_ASSET` com `targetRoot` explícito para o packer
|
||||
- abrir estado modal de espera com spinner após confirmação
|
||||
- correlacionar a operação via `operationId`
|
||||
- escutar o evento operacional do packer até `ACTION_APPLIED` ou `ACTION_FAILED`
|
||||
- publicar structural sync explícito apenas após conclusão bem-sucedida
|
||||
- validar no Studio que `targetRoot/asset.json` não exista
|
||||
- validar no packer que `targetRoot/asset.json` não exista, mesmo se o Studio falhar em bloquear antes
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- não redesenhar o mutation preview panel inteiro
|
||||
- não introduzir rename inline fora do wizard
|
||||
- não adicionar batch move
|
||||
- não redefinir semântica de identidade do asset
|
||||
- não permitir fallback para target automático quando o usuário iniciou `Move`
|
||||
- não mover diretórios diretamente pelo Studio fora do comando ao packer
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Expor `Move` na seção `Actions`.
|
||||
O botão deve existir apenas quando houver asset selecionado e deve abrir o wizard a partir do `AssetReference` atual.
|
||||
|
||||
2. Implementar o wizard de relocação como fluxo explícito de destino.
|
||||
O wizard deve reutilizar a linguagem já existente de `relocateWizard` e coletar:
|
||||
- root atual
|
||||
- diretório parent de destino
|
||||
- nome final do diretório
|
||||
- target root calculado
|
||||
|
||||
3. Adicionar validação local de destino.
|
||||
O wizard deve bloquear avanço/confirmação quando:
|
||||
- o target root for igual ao root atual;
|
||||
- o target root sair da área válida esperada;
|
||||
- o target root já contiver `asset.json`.
|
||||
|
||||
4. Adicionar passo final de resumo.
|
||||
Antes do comando final, o usuário deve ver um resumo do:
|
||||
- asset atual
|
||||
- root atual
|
||||
- parent de destino
|
||||
- nome final
|
||||
- target root resultante
|
||||
|
||||
5. Integrar o wizard ao fluxo de comando assíncrono do packer.
|
||||
A saída do wizard deve virar `PackerMutationRequest(RELOCATE_ASSET, ..., targetRoot)`, sem usar target automático.
|
||||
Depois do `OK`, o Studio inicia a operação, captura o `operationId` retornado e coloca o modal em estado de espera.
|
||||
|
||||
6. Esperar conclusão por evento, não por refresh cego.
|
||||
O modal deve escutar `StudioPackerOperationEvent` correlacionado por `operationId`.
|
||||
Regras:
|
||||
- `ACTION_APPLIED`: disparar refresh estrutural, fechar modal e reselecionar o asset relocado;
|
||||
- `ACTION_FAILED`: sair do spinner, manter modal aberto e mostrar a falha;
|
||||
- eventos intermediários como `PROGRESS_UPDATED` podem atualizar a mensagem/estado visual, mas não fecham o modal.
|
||||
|
||||
7. Endurecer a regra no packer.
|
||||
O preview/apply de relocation deve recusar destino cujo root já contenha `asset.json`, produzindo blocker claro e estável.
|
||||
|
||||
8. Orquestrar o pós-conclusão como mudança estrutural.
|
||||
Relocation bem-sucedida deve acionar sync estrutural explícito e reposicionar a seleção para o asset movido no novo root.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `Move` aparece na seção `Actions` do asset selecionado
|
||||
- clicar em `Move` abre wizard dedicado em vez de mutação imediata
|
||||
- o wizard exige destino explícito escolhido pelo usuário
|
||||
- existe passo final de resumo antes da conclusão
|
||||
- `targetRoot/asset.json` bloqueia o fluxo já no Studio
|
||||
- o packer também bloqueia `targetRoot/asset.json` como regra de segurança
|
||||
- o `OK` final envia o comando ao packer e coloca o modal em espera com spinner
|
||||
- o modal só fecha depois de `ACTION_APPLIED` para a mesma operação
|
||||
- falha operacional não fecha o modal silenciosamente
|
||||
- sucesso operacional executa structural sync explícito
|
||||
- a seleção final aponta para o asset já movido, não para o root antigo
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests para validação de target root no wizard
|
||||
- unit tests para derivação de `targetRoot` a partir de parent + destination name
|
||||
- unit tests para correlação `operationId -> modal state`
|
||||
- unit tests para sucesso/falha dirigidos por `StudioPackerOperationEvent`
|
||||
- unit tests para publication/orchestration de relocation como structural sync
|
||||
- packer tests para blocker quando `targetRoot/asset.json` já existe
|
||||
- smoke test de UI para:
|
||||
- abrir `Move`
|
||||
- editar destino
|
||||
- ver resumo final
|
||||
- bloquear destino inválido
|
||||
- confirmar operação
|
||||
- ver spinner de espera
|
||||
- fechar no evento de sucesso
|
||||
- manter aberto no evento de falha
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md` se a regra de destino inválido precisar ser tornada mais explícita
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/actions/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/wizards/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` mutation orchestration wiring
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- `prometeu-studio/src/main/resources/i18n/messages.properties`
|
||||
- `prometeu-packer/src/main/java/p/packer/mutations/...`
|
||||
- testes de Studio para wizard/flow
|
||||
- testes de packer para relocation target validation
|
||||
@@ -48,12 +48,16 @@ The current Studio execution queue is:
|
||||
8. [`PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
9. [`PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md)
|
||||
10. [`PR-07e-assets-refactor-cleanup-and-regression-coverage.md`](./PR-07e-assets-refactor-cleanup-and-regression-coverage.md)
|
||||
11. [`PR-06-project-scoped-studio-state-and-activity-persistence.md`](./PR-06-project-scoped-studio-state-and-activity-persistence.md)
|
||||
11. [`PR-08-assets-workspace-panel-package-boundaries-and-local-subscriptions.md`](./PR-08-assets-workspace-panel-package-boundaries-and-local-subscriptions.md)
|
||||
12. [`PR-06-project-scoped-studio-state-and-activity-persistence.md`](./PR-06-project-scoped-studio-state-and-activity-persistence.md)
|
||||
|
||||
The `PR-07` family is a corrective refactor pass for the current `Assets` implementation.
|
||||
It exists to replace the refresh-heavy direction with lifecycle-managed, event-driven ownership.
|
||||
It also establishes the intended Studio-wide workspace framework, with `Assets` as the first consumer and proof point.
|
||||
|
||||
`PR-08` is the package-topology and subscription-ownership follow-up for that same direction.
|
||||
It enforces list/details package boundaries and requires every panel to consume the workspace bus directly.
|
||||
|
||||
Recommended execution order:
|
||||
|
||||
`PR-05a -> PR-05b -> PR-05c -> PR-05d -> PR-05e -> PR-07a -> PR-07b -> PR-07c -> PR-07d -> PR-07e -> PR-06`
|
||||
`PR-05a -> PR-05b -> PR-05c -> PR-05d -> PR-05e -> PR-07a -> PR-07b -> PR-07c -> PR-07d -> PR-07e -> PR-08 -> PR-06`
|
||||
|
||||
@@ -73,6 +73,14 @@ Propagation rules:
|
||||
- propagation is workspace to global;
|
||||
- global-to-workspace rebroadcast is not baseline behavior.
|
||||
|
||||
The global Studio bus is backed by a typed event bus reference owned by the Studio application container.
|
||||
|
||||
Container rules:
|
||||
|
||||
- the Studio `Container` owns the global typed event bus reference used by `StudioEventBus`;
|
||||
- host-integrated services that need shared Studio operational visibility should receive that container-owned typed event bus reference during bootstrap instead of allocating disconnected local buses;
|
||||
- the `Container` must be initialized during Studio boot before packer-backed integration services, workspaces, or adapters begin use.
|
||||
|
||||
This topology exists so callers do not need to duplicate publication decisions manually.
|
||||
|
||||
## Event Categories
|
||||
|
||||
@@ -49,7 +49,10 @@ The workspace must assume:
|
||||
- unregistered assets remain visible but excluded from builds;
|
||||
- assets may aggregate many internal inputs;
|
||||
- runtime-facing output contract data exists for each asset;
|
||||
- diagnostics, activity, progress, and staged mutation responses are available from Studio-facing services.
|
||||
- diagnostics, activity, progress, and staged mutation responses are available from Studio-facing services;
|
||||
- packer-facing operational freshness may surface states such as `healthy`, `stale`, `diverged`, `reconciling`, or `failed`.
|
||||
|
||||
Packer-backed operational events consumed by this workspace are expected to enter Studio through the container-owned typed event bus path rather than through workspace-local ad hoc bus creation.
|
||||
|
||||
## Workspace Model
|
||||
|
||||
@@ -66,7 +69,8 @@ The workspace must help the user understand:
|
||||
- where the asset root lives;
|
||||
- which internal inputs belong to that asset;
|
||||
- what the asset declares toward the runtime-facing contract;
|
||||
- which operations are safe, staged, blocked, or destructive.
|
||||
- which operations are safe, staged, blocked, or destructive;
|
||||
- whether the current view reflects healthy, stale, diverged, or reconciling packer state.
|
||||
|
||||
The `Assets` workspace is also the first concrete consumer of the Studio event-driven workspace framework.
|
||||
|
||||
@@ -170,6 +174,7 @@ Rules:
|
||||
- The navigator must define explicit `no assets` state.
|
||||
- The navigator must define explicit `no results` state.
|
||||
- The navigator must define explicit `workspace error` state.
|
||||
- The workspace must define explicit operational freshness states when packer runtime divergence is surfaced.
|
||||
- Unregistered assets must appear in the same navigator flow as registered assets.
|
||||
- Unregistered styling must communicate `present but not yet registered`, not `broken`.
|
||||
|
||||
@@ -241,6 +246,7 @@ Rules:
|
||||
- Actions that target the selected asset must appear beside `Summary`, not in the navigator area.
|
||||
- Safe and routine actions must be visually separated from sensitive mutations.
|
||||
- Hidden or automatic repair behavior is not allowed in the selected-asset view.
|
||||
- If packer surfaces stale/diverged/reconciling state, the selected-asset view may expose explicit refresh or reconcile-oriented actions, but it must not invent repair semantics locally.
|
||||
|
||||
## Action Rules
|
||||
|
||||
@@ -334,6 +340,7 @@ Navigator-level `Doctor` and `Pack`, plus asset-level `Include In Build` and suc
|
||||
- `preview_ready` should surface in global `Activity`.
|
||||
- `action_applied` should surface in global `Activity`.
|
||||
- `action_failed` should surface in global `Activity`.
|
||||
- reconcile or divergence state transitions should remain visible when they affect current workspace truth.
|
||||
- The preview itself remains a workspace-local review surface.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
Reference in New Issue
Block a user