This commit is contained in:
2026-03-24 13:42:57 +00:00
parent d16a987949
commit 0e5e1669c2
98 changed files with 824 additions and 8449 deletions
@@ -1,63 +0,0 @@
# PR-01 Packer Project Bootstrap and Module Boundaries
Domain Owner: `docs/packer`
## Briefing
Create the standalone `prometeu-packer` project and establish the production module boundaries required by the packer specs.
This PR starts the implementation track without leaking packer behavior into Studio.
## Objective
Deliver a separate top-level `prometeu-packer` project with build wiring, package boundaries, test harness, and service-facing contracts that future PRs can implement incrementally.
## Dependencies
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
## Scope
- add `prometeu-packer` as a separate project in the repository build
- define the baseline package/module layout for:
- workspace and registry services
- declaration parsing and validation
- mutation preview/apply services
- build planning and artifact emission
- diagnostics and event reporting
- define the public service contracts that Studio may consume through adapters
- add baseline unit-test and fixture support for packer-only development
## Non-Goals
- no full workspace semantics yet
- no asset build emission yet
- no Studio UI changes beyond dependency wiring preparation
## Execution Method
1. Add `prometeu-packer` to Gradle settings and repository build wiring.
2. Create baseline package namespaces and service interfaces.
3. Establish a packer-owned test fixture layout for workspace samples and artifact assertions.
4. Keep Studio integration contract-based so Studio does not depend on filesystem internals.
## Acceptance Criteria
- `prometeu-packer` exists as a separate build target
- packer contracts compile without depending on Studio UI classes
- future PRs can add implementations without restructuring the project root
- packer test infrastructure is usable from the next PR onward
## Validation
- build graph includes `prometeu-packer`
- baseline compile test for public contracts
- fixture-loading smoke test in the new project
## Affected Artifacts
- `settings.gradle.kts`
- `prometeu-packer/**`
- repository build wiring
- cross-domain reference: Studio adapter call sites that will later consume packer services
@@ -1,60 +0,0 @@
# PR-02 Workspace Init, Registry, and Identity Foundation
Domain Owner: `docs/packer`
## Briefing
Implement the packer-owned workspace control model and registry authority in `prometeu-packer`.
This PR turns the identity and workspace rules into executable code.
## Objective
Deliver `init_workspace`, registry load/store, identity allocation, and asset-root resolution as the stable foundation for all later packer operations.
## Dependencies
- [`./PR-01-packer-project-bootstrap-and-module-boundaries.md`](./PR-01-packer-project-bootstrap-and-module-boundaries.md)
- [`../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)
## Scope
- implement `init_workspace`
- create and validate `assets/.prometeu/index.json`
- implement monotonic `asset_id` allocation and persisted allocator state
- model `asset_uuid` allocation and persistence
- implement root resolution utilities used by future read/write operations
- define structural registry errors and missing-root behavior
## Non-Goals
- no `asset.json` semantic validation beyond what registry ownership requires
- no Studio adapter yet
- no build artifacts yet
## Execution Method
1. Implement packer-owned registry models and codecs.
2. Add workspace bootstrap behavior for missing control directories.
3. Enforce identity invariants around `asset_id`, `asset_uuid`, and root uniqueness.
4. Expose internal services for lookup by `asset_id`, `asset_uuid`, and root path.
## Acceptance Criteria
- workspace initialization creates the minimum control structure deterministically
- registry state round-trips without losing allocator data
- duplicate or ambiguous identity-bearing entries fail clearly
- relocation can later update root location without changing identity fields
## Validation
- unit tests for registry round-trip and allocator monotonicity
- unit tests for duplicate-root and malformed-registry failures
- workspace-init fixture test
## Affected Artifacts
- `prometeu-packer/**`
- `assets/.prometeu/index.json` contract implementation
- packer fixture workspaces
@@ -1,65 +0,0 @@
# PR-03 Asset Declaration Parsing, Validation, and Details Contract
Domain Owner: `docs/packer`
## Briefing
Implement strict `asset.json` parsing and the packer-side details contract used by both tooling and Studio.
This PR converts the declaration spec into typed packer models and structured diagnostics.
## Objective
Deliver strict parse, schema/version checks, common field validation, and a `get_asset_details` response model that Studio can consume through an adapter.
## Dependencies
- [`./PR-02-workspace-init-registry-and-identity-foundation.md`](./PR-02-workspace-init-registry-and-identity-foundation.md)
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
## Scope
- parse and validate the common `asset.json` contract
- validate required baseline fields:
- `schema_version`
- `name`
- `type`
- `inputs`
- `output`
- `preload`
- emit structured diagnostics for parse, structural, and version errors
- define the packer `get_asset_details` response model
- preserve distinction between valid-orphan declarations and invalid declarations
## Non-Goals
- no full format-family payload encoding rules
- no workspace scan aggregation yet
- no mutation apply behavior yet
## Execution Method
1. Implement typed declaration models and strict decoding.
2. Add common semantic validation and diagnostic mapping.
3. Define details-response DTOs that preserve both declaration and diagnostic evidence.
4. Back the contract with representative valid and invalid fixtures.
## Acceptance Criteria
- invalid declarations fail with actionable structured diagnostics
- valid declarations produce stable typed models
- `get_asset_details` can expose declaration, inputs, output, preload, and diagnostics cleanly
- unsupported or malformed schema versions surface as explicit failures
## Validation
- fixture-driven parser tests
- semantic validation tests for required fields
- details-response tests for valid, orphan, and invalid declarations
## Affected Artifacts
- `prometeu-packer/**`
- packer declaration fixtures
- cross-domain reference: Studio asset details adapter inputs
@@ -1,61 +0,0 @@
# PR-04 Workspace Scan, List Assets, and Studio Read Adapter
Domain Owner: `docs/packer`
## Briefing
Implement the read-side operational surface that turns a filesystem workspace into a packer-owned asset snapshot.
This PR is the first explicit Studio integration step: Studio stops reading the workspace directly and starts consuming a packer response model through an adapter.
## Objective
Deliver `list_assets`, wire `get_asset_details` over real workspace scanning, and create the read adapter that maps packer responses to Studio workspace models.
## Dependencies
- [`./PR-03-asset-declaration-parsing-validation-and-details-contract.md`](./PR-03-asset-declaration-parsing-validation-and-details-contract.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)
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
## Scope
- implement workspace scanning for managed assets and orphan anchors
- implement `list_assets`
- finish real `get_asset_details` on top of packer services
- distinguish managed-world structural issues from workspace hygiene findings in read responses
- create the Studio read adapter from packer responses to the existing Studio asset workspace models
- replace filesystem-specific read code in Studio with the adapter-backed path
## Non-Goals
- no sensitive mutation apply flows yet
- no build pipeline yet
- no event lane yet
## Execution Method
1. Scan `assets/` for anchored roots and reconcile against the registry.
2. Produce a structured snapshot for list/details services.
3. Implement a Studio adapter that maps packer DTOs into the Studio read model without embedding packer logic in JavaFX.
4. Verify that Studio read behavior remains equivalent while packer becomes the source of truth.
## Acceptance Criteria
- `list_assets` returns managed and orphan assets coherently
- Studio navigator and details surfaces can run on packer-backed read responses
- registry authority remains visible in the mapped Studio state
- invalid declarations and missing roots surface through structured diagnostics
## Validation
- packer tests for scan reconciliation and orphan detection
- adapter tests for mapping list/details responses into Studio models
- Studio smoke validation using the packer-backed read path
## Affected Artifacts
- `prometeu-packer/**`
- `prometeu-studio/**` read adapters and service wiring
- test fixtures shared across packer and Studio integration tests
@@ -1,78 +0,0 @@
# PR-05 Sensitive Mutations, Preview/Apply, and Studio Write Adapter
Domain Owner: `docs/packer`
## Briefing
Implement the packer-owned preview/apply mutation services and route Studio staged mutations through a write adapter instead of local filesystem rules.
This PR is where the current Studio staged mutation UI starts executing real packer semantics.
## Objective
Deliver structured preview/apply services for `register_asset`, `adopt_asset`, `forget_asset`, `remove_asset`, quarantine, and relocation, plus the Studio adapter that maps packer mutation responses into the existing staged mutation UI.
## Dependencies
- [`./PR-04-workspace-scan-list-assets-and-studio-read-adapter.md`](./PR-04-workspace-scan-list-assets-and-studio-read-adapter.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)
- cross-domain reference: [`../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md`](../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md)
## Scope
- implement preview/apply service contracts for:
- `register_asset`
- `adopt_asset`
- `forget_asset`
- `remove_asset`
- `quarantine_asset`
- `relocate_asset`
- preserve explicit distinction between:
- registry mutations
- workspace mutations
- blockers
- warnings
- safe fixes
- implement mutation serialization rules so conflicting write flows do not race
- implement the baseline single-writer semantic lane per project for sensitive mutation apply
- create the Studio write adapter for staged mutation preview/apply
- replace filesystem-only Studio mutation execution with packer-backed services
## Non-Goals
- no doctor implementation yet
- no build artifact emission yet
- no generic cross-workspace mutation framework
## Execution Method
1. Implement staged intent models and preview/apply response types in the packer.
2. Implement mutation handlers on top of registry and workspace services.
3. Serialize final mutation apply within a project-scoped write lane while keeping preview generation outside the commit-critical section when safe.
4. Add a Studio adapter that converts packer mutation responses into the current staged preview model and forwards packer-native lifecycle events into the Studio event bus.
5. Retire duplicated mutation semantics from Studio once the adapter path is stable.
## Acceptance Criteria
- sensitive mutations run through packer preview/apply services
- Studio staged mutation UI no longer owns core mutation semantics
- relocation preserves `asset_id` and `asset_uuid`
- quarantine is explicit, previewable, and reversible in service semantics
- mutation failures remain actionable and structured
- conflicting mutation applies on the same project cannot commit concurrently
- mutation lifecycle can be surfaced to Studio without Studio inventing semantic outcomes
## Validation
- packer tests for each sensitive mutation preview/apply path
- packer concurrency tests for same-project conflicting writes
- adapter tests for mapping packer responses into Studio preview models
- adapter tests for forwarding packer mutation lifecycle events into Studio events
- Studio smoke validation for preview/apply against the packer-backed path
## Affected Artifacts
- `prometeu-packer/**`
- `prometeu-studio/**` mutation adapter and wiring
- mutation fixture workspaces
@@ -1,60 +0,0 @@
# PR-06 Doctor, Diagnostics, and Safe-Fix Baseline
Domain Owner: `docs/packer`
## Briefing
Implement the baseline doctor and diagnostics model for the production packer.
This PR is responsible for making the packer operationally useful beyond navigation and mutation flows.
## Objective
Deliver structured doctor execution with managed-world validation, expanded workspace hygiene scanning, and safe-fix preview/apply where baseline-safe.
## Dependencies
- [`./PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](./PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.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)
## Scope
- implement managed-world structural validation
- implement expanded workspace hygiene scanning
- classify diagnostics by severity and blocking behavior
- implement safe mechanical fix flows for baseline-safe cases only
- expose doctor responses in structured form for Studio and CI consumption
- define evidence and summaries suitable for Activity and inline diagnostics
## Non-Goals
- no silent destructive repair
- no speculative auto-healing of relocational or delete scenarios
- no final watch mode yet
## Execution Method
1. Implement diagnostic producers for registry, declaration, and workspace hygiene findings.
2. Implement doctor request modes and safe-fix eligibility checks.
3. Model doctor output as structured responses instead of terminal-only text.
4. Connect safe-fix preview/apply behavior to the same safety rules used by mutation flows.
## Acceptance Criteria
- blocking and non-blocking diagnostics are clearly separated
- doctor can report on both managed-world validity and broader hygiene issues
- safe fixes only exist where the operation is explicitly low-risk
- Studio and CI can consume the same doctor response model
## Validation
- fixture tests for structural errors and hygiene findings
- tests for safe-fix eligibility and refusal paths
- adapter tests for Studio diagnostic mapping
## Affected Artifacts
- `prometeu-packer/**`
- cross-domain reference: Studio diagnostics and activity consumers
- doctor fixtures and expected reports
@@ -1,62 +0,0 @@
# PR-07 Build Plan, Determinism, and Cache-Key Foundation
Domain Owner: `docs/packer`
## Briefing
Implement the deterministic planning layer that normalizes validated assets into a stable build plan before artifact emission.
This PR is the boundary between workspace semantics and runtime-facing artifact production.
## Objective
Deliver a deterministic build planner, canonical header model, preload derivation, and cache-key foundation that later emission and incremental work can trust.
## Dependencies
- [`./PR-06-doctor-diagnostics-and-safe-fix-baseline.md`](./PR-06-doctor-diagnostics-and-safe-fix-baseline.md)
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
## Scope
- validate build-eligible managed assets
- derive deterministic asset ordering by increasing `asset_id`
- build canonical header-side models for:
- `asset_table`
- `preload`
- define payload planning slots and offset planning inputs
- compute cache keys from validated effective inputs
- emit deterministic in-memory build plans before writing files
## Non-Goals
- no final `assets.pa` file emission yet
- no watch mode yet
- no format-family semantic expansion beyond what current specs already define
## Execution Method
1. Normalize validated managed assets into a stable build plan representation.
2. Implement canonical JSON serialization rules for header mirrors and planner assertions.
3. Compute cache keys only from validated effective inputs.
4. Add deterministic tests proving equivalent workspaces produce equivalent plans.
## Acceptance Criteria
- equivalent inputs produce equivalent build plans
- asset ordering is independent from filesystem traversal order
- preload derivation matches declaration state deterministically
- cache-key inputs are explicit and reproducible
## Validation
- determinism tests with reordered filesystem fixtures
- canonical-header serialization tests
- cache-key stability tests
## Affected Artifacts
- `prometeu-packer/**`
- build planning fixtures
- future dependency for `build` service and event lane
@@ -1,63 +0,0 @@
# PR-08 assets.pa and Companion Artifact Emission
Domain Owner: `docs/packer`
## Briefing
Implement writer-side artifact emission on top of the deterministic build planner.
This PR turns validated and planned build state into the published packer outputs.
## Objective
Deliver `build`, `assets.pa`, and the baseline companion artifacts with deterministic ordering and stable writer-side contracts.
## Dependencies
- [`./PR-07-build-plan-determinism-and-cache-key-foundation.md`](./PR-07-build-plan-determinism-and-cache-key-foundation.md)
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
## Scope
- implement the `build` service
- emit `assets.pa`
- emit:
- `build/asset_table.json`
- `build/preload.json`
- `build/asset_table_metadata.json`
- implement canonical header serialization and file writing
- implement payload-region offset materialization from the build plan
- expose build summaries and applied-artifact metadata for Studio and CI
## Non-Goals
- no cartridge assembly
- no shipper coupling
- no speculative layout optimization beyond deterministic packing
## Execution Method
1. Convert the build plan into emitted artifact bytes and companion files.
2. Preserve header authority and 1:1 mirror rules for companion JSON outputs.
3. Add golden fixtures for emitted headers and companion artifacts.
4. Keep runtime-facing semantics bounded to writer-side production rules already specified.
## Acceptance Criteria
- `build` produces `assets.pa` and companion artifacts deterministically
- companion JSON outputs mirror the runtime header where required
- emitted ordering and offsets follow the build plan contract
- repeated equivalent builds do not drift
## Validation
- golden tests for `assets.pa` envelope and header bytes
- golden tests for companion JSON mirrors
- repeated-build determinism tests
## Affected Artifacts
- `prometeu-packer/**`
- build output fixtures
- CI artifact assertions
@@ -1,83 +0,0 @@
# PR-09 Event Lane, Progress, and Studio Operational Integration
Domain Owner: `docs/packer`
## Briefing
Implement the packer event/reporting lane and bind the production packer service lifecycle into Studio operational surfaces.
This PR is where Studio stops inferring operational history locally and starts reflecting packer-native lifecycle events.
## Objective
Deliver the structured packer event lane, progress reporting, and adapter/wiring so Studio Activity, progress, and refresh behavior align with real packer execution.
## Dependencies
- [`./PR-08-assets-pa-and-companion-artifact-emission.md`](./PR-08-assets-pa-and-companion-artifact-emission.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- cross-domain reference: [`../../studio/specs/1. Studio Shell and Workspace Layout Specification.md`](../../studio/specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
## Scope
- implement the initial structured event set:
- `asset_discovered`
- `asset_changed`
- `diagnostics_updated`
- `build_started`
- `build_finished`
- `cache_hit`
- `cache_miss`
- `preview_ready`
- `action_applied`
- `action_failed`
- `progress_updated`
- define the baseline event envelope with fields equivalent to:
- `project_id`
- `operation_id`
- `sequence`
- `kind`
- `timestamp`
- `summary`
- `progress`
- `affected_assets`
- define event publishing hooks across scan, doctor, mutation, and build flows
- implement the Studio adapter from packer events to Studio event bus semantics
- align global Activity and progress behavior with packer-native lifecycle updates
## Non-Goals
- no final watch daemon
- no remote/shared cache orchestration
- no UI redesign
## Execution Method
1. Add event publication points to read, mutation, doctor, and build services.
2. Define a packer event sink abstraction so Studio is a consumer, not the owner, of the event model.
3. Preserve operation causality with stable `operation_id` plus monotonic per-operation `sequence`.
4. Map packer events into existing Studio Activity and progress surfaces through an adapter, with coalescing only for low-value repeated progress-like events.
5. Verify that long-running work does not block UI interaction and that terminal lifecycle events remain individually visible.
## Acceptance Criteria
- packer emits structured lifecycle events across core operations
- Studio Activity/progress can be driven from packer-native events
- mutation and build flows no longer require Studio-local event invention
- event ordering is coherent from the UI perspective
- same-operation event ordering is preserved through the Studio adapter
- adapters may remap event shapes, but do not invent causal relationships or semantic summaries absent from the packer event stream
## Validation
- packer event publication tests
- adapter tests from packer events to Studio events
- ordering/coalescing tests for progress-heavy operations and terminal lifecycle events
- Studio smoke validation for Activity and progress during packer-backed operations
## Affected Artifacts
- `prometeu-packer/**`
- `prometeu-studio/**` event adapter and wiring
- integration fixtures for long-running operations
@@ -1,70 +0,0 @@
# PR-10 Versioning, Migration, Trust, and Production Gates
Domain Owner: `docs/packer`
## Briefing
Finish the production track by hardening the packer against version skew, corrupted inputs, and unsupported artifacts, while installing CI and integration gates for the standalone project.
This PR closes the packer implementation wave with production readiness checks rather than new feature surface.
## Objective
Deliver explicit version checks, migration ownership behavior, trust-boundary enforcement, and production test gates for `prometeu-packer` and its Studio integration path.
## Dependencies
- [`./PR-09-event-lane-progress-and-studio-operational-integration.md`](./PR-09-event-lane-progress-and-studio-operational-integration.md)
- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
## Scope
- implement explicit version checking across:
- `asset.json`
- `index.json`
- packer-owned cache/control schemas
- `assets.pa` writer-side contract surfaces
- implement supported-window failure behavior and migration reporting
- enforce conservative trust checks before parse, validation, mutation, and build
- add CI gates and end-to-end fixtures for:
- read flows
- mutation preview/apply flows
- doctor
- build
- Studio adapter integration
- consolidate operational docs and production readiness notes for the packer project
## Non-Goals
- no plugin system
- no artifact signing strategy
- no remote registry or shared-cache product surface
## Execution Method
1. Add version and migration checks to all packer-owned artifact boundaries.
2. Make unsupported-version and migration failures explicit and structured.
3. Add end-to-end integration fixtures that exercise the standalone packer with the Studio adapter path.
4. Install repository gates so production regressions fail before merge.
## Acceptance Criteria
- unsupported versions fail early and clearly
- migration attempts and failures are visible to Studio and CI
- packer trust boundaries are enforced before unsafe work proceeds
- `prometeu-packer` has end-to-end production gates covering its declared service surface
## Validation
- version-compatibility and migration tests
- malformed/untrusted input hardening tests
- end-to-end integration tests across packer plus Studio adapter path
- CI execution proving the packer project is gated independently
## Affected Artifacts
- `prometeu-packer/**`
- repository CI/build configuration
- `prometeu-studio/**` integration gates where the adapter path is exercised
- packer learn/spec propagation targets after implementation
@@ -1,194 +0,0 @@
# 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.
@@ -1,74 +0,0 @@
# 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
@@ -1,73 +0,0 @@
# 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`
@@ -1,68 +0,0 @@
# 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/**`
@@ -1,70 +0,0 @@
# 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
@@ -1,71 +0,0 @@
# 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
@@ -1,73 +0,0 @@
# 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
@@ -1,66 +0,0 @@
# 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
@@ -1,98 +0,0 @@
# PR-19 API Surface Audit, Model Separation, and Public Read DTOs
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The current packer API still exposes some read payload types that are simultaneously acting as public transport objects and internal implementation models.
This is acceptable during early convergence, but it weakens the boundary between `prometeu-packer-api` and `prometeu-packer-v1`.
The next cleanup step is to make the API explicit about three different categories:
- domain contracts,
- request/response messages,
- public read DTOs.
At the same time, the internal implementation models used by `prometeu-packer-v1` should stop leaking through the API as if they were stable public models.
## Objective
Separate internal `v1` read models from public API read DTOs while preserving:
- request/response messages as immutable messages,
- domain contracts as domain contracts,
- exceptions as part of the public API,
- and Studio compatibility through explicit mapper-based conversion inside `prometeu-packer-v1`.
## 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)
- [`./PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md)
## Scope
- audit the current public packer API against real external consumption
- preserve public exceptions in the API even when only `v1` currently throws them
- preserve request/response records as request/response messages rather than renaming them as generic DTOs
- move the current mixed model/transport read types out of the API and into `prometeu-packer-v1`
- introduce public read DTOs in the API for the information Studio actually consumes
- add explicit mapper classes in `prometeu-packer-v1` to convert internal models into API DTOs
- keep the active service wave limited to `initWorkspace`, `listAssets`, `getAssetDetails`, and `createAsset`
## Non-Goals
- no new packer capabilities
- no write API redesign
- no doctor or build/pack reintroduction
- no reconcile observer work
- no semantic change to asset identity, registry ownership, or snapshot authority
## Execution Method
1. Classify the current API surface into:
- public domain contracts,
- public request/response messages,
- public read DTOs,
- internal implementation models.
2. Keep domain contracts in `prometeu-packer-api` without `DTO` suffixes.
3. Keep request/response types in `prometeu-packer-api` as immutable message records with `Request` and `Response` naming.
4. Move the current mixed read shapes now exposed as `PackerAssetSummary`, `PackerAssetDetails`, and `PackerAssetIdentity` into `prometeu-packer-v1` as internal models.
5. Introduce explicit public DTOs in the API for runtime-backed read payloads, such as:
- `PackerAssetSummaryDTO`
- `PackerAssetDetailsDTO`
- `PackerAssetIdentityDTO`
- `PackerCodecConfigurationFieldDTO`
- and `PackerDiagnosticDTO` if diagnostics remain part of public responses.
6. Add explicit mapper classes in `prometeu-packer-v1` to convert internal models into API DTOs before responses cross the module boundary.
7. Update response messages to carry the new DTO types instead of leaking `v1` models through the API.
8. Update Studio consumers to read from the new DTO types while preserving the same user-facing behavior.
## Acceptance Criteria
- the API surface is explicitly partitioned between domain contracts, request/response messages, and read DTOs
- request/response messages remain immutable message records and are not renamed as generic DTOs
- public exceptions remain in the API
- internal `v1` models are no longer exposed as if they were public API models
- Studio depends only on API contracts and DTOs, not on `v1` model semantics
- conversion from `v1` internal models to public API DTOs happens through explicit mapper code
- no behavior regression is introduced in `initWorkspace`, `listAssets`, `getAssetDetails`, or `createAsset`
## Validation
- compile-time audit proving `prometeu-studio` and `prometeu-app` consume only API contracts
- packer regression tests for read and write flows
- Studio regression tests for asset list, asset details, and add asset flows
- targeted tests for mapper coverage between internal models and public API DTOs
## Affected Artifacts
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**`
- `prometeu-studio/src/main/java/p/studio/**`
- `prometeu-studio/src/test/java/p/studio/**`
@@ -1,101 +0,0 @@
# PR-20 Asset Action Capabilities and Register-First Delivery
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The current `Assets` workspace still decides too much locally about which asset actions should appear and when they should be allowed.
That is the wrong long-term boundary.
The packer already owns asset semantics, registration state, build participation, and write execution. It should also own the capability decision for asset actions, while Studio remains a consumer that renders the actions exposed by the service.
This PR introduces a capability-based action contract driven by the packer, with `AssetAction.REGISTER` as the first delivered action end to end.
## Objective
Add a packer-owned asset action capability API and deliver the first action, `REGISTER`, through the full packer-to-Studio path.
## 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)
- [`./PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md)
- [`./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md`](./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md)
## Scope
- define a public packer action contract for asset capabilities
- let the packer decide which actions are available for a given asset at a given moment
- let Studio render the action section from packer-provided capabilities instead of local semantic rules
- keep the capability contract stable even if the packer later moves to FSM or another internal decision model
- deliver `AssetAction.REGISTER` as the first supported action end to end
- keep the service-only wave focused on active functionality
## Non-Goals
- no FSM implementation
- no full action family rollout in the first delivery
- no doctor/build/reconcile action surfaces
- no speculative future actions without packer support
- no frontend-local capability engine
## Execution Method
1. Add a public action capability contract in `prometeu-packer-api`, including:
- `AssetAction` enum
- capability response shape for asset actions
- request/response messages for reading action capabilities
2. Model the response so the packer can expose at least:
- `action`
- `enabled`
- `visible`
- optional `reason`
3. Add a runtime-backed read path in `prometeu-packer-v1` that resolves action capabilities from the current asset state.
4. Keep the internal decision logic inside the packer implementation. Studio must not reconstruct capability semantics.
5. Add a write path for `AssetAction.REGISTER`.
6. Expose `REGISTER` only when the asset capability resolver says it is allowed.
7. Render the `Actions` section in Studio from the returned capabilities.
8. Execute `REGISTER` from Studio through the packer write path and refresh the asset workspace after completion.
## Register-First Delivery Rules
The first delivered action is:
- `AssetAction.REGISTER`
Expected initial capability behavior:
- unregistered assets may expose `REGISTER`
- registered assets must not expose `REGISTER`
- Studio must only show the `Register` button when the packer returns that capability
Other future actions such as `MOVE`, `DELETE`, `INCLUDE_IN_BUILD`, `EXCLUDE_FROM_BUILD`, `ENABLE_PRELOAD`, `DISABLE_PRELOAD`, and `CHANGE_CONTRACT` are intentionally deferred from code delivery in this PR unless needed to support the contract shape.
## Acceptance Criteria
- the packer API exposes an asset action capability contract
- Studio reads action capabilities from the packer instead of deciding them locally
- the first delivered action is `AssetAction.REGISTER`
- `REGISTER` is available only for unregistered assets
- `REGISTER` is not shown for registered assets
- Studio can trigger `REGISTER` through the packer service path and refresh the workspace after success
- the capability contract remains valid if packer internals later migrate to FSM or another orchestration model
## Validation
- packer unit tests for capability resolution
- packer tests for `REGISTER` execution
- Studio tests or smoke tests proving that action buttons are rendered from service-provided capabilities
- end-to-end validation for unregistered asset -> register -> refresh -> registered asset
## Affected Artifacts
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**`
- `prometeu-studio/src/main/java/p/studio/**`
- `prometeu-studio/src/test/java/p/studio/**`
@@ -1,77 +0,0 @@
# PR-21 Point In-Memory Snapshot Updates After Write Commit
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The current write path still rebuilds the whole project runtime snapshot after a successful point write such as `REGISTER`.
That is too expensive for the runtime model we want.
Studio refresh on top of an already-updated in-memory snapshot is acceptable. Full filesystem rescan inside the packer after every point write is not.
This PR replaces the normal post-write `full refresh` path with point snapshot updates in memory, while keeping full reload available only as an explicit recovery fallback.
## Objective
Remove whole-project runtime rescan from the normal point write path and replace it with point in-memory snapshot updates after durable commit.
## 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)
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
- [`./PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md)
## Scope
- add explicit point snapshot update support to the runtime registry
- keep the write lane as the only owner of point runtime mutation after durable commit
- replace post-write `runtimeRegistry.refresh(project)` in the active write path with point snapshot patching
- deliver the first point patch for `REGISTER`
- keep Studio refresh behavior unchanged
## Non-Goals
- no background divergence detection
- no reconcile loop
- no change to Studio refresh semantics
- no broad event model redesign
- no speculative patch implementation for unused write actions
## Execution Method
1. Extend the runtime registry so it can update a loaded project snapshot by applying a point patch function inside the packer-owned write flow.
2. Keep full snapshot reload available as recovery fallback, but do not use it in the normal successful point write path.
3. Model a point patch for `REGISTER` that:
- appends the new registry entry to the in-memory registry view
- updates the matching runtime asset from unregistered to registered
- preserves the rest of the snapshot untouched
4. Apply the patch only after the durable disk commit succeeds.
5. Keep read services unchanged from the Studio point of view; they should continue reading from the runtime snapshot.
6. Keep Studio free to refresh list/details after write completion, because those reads now hit the already-updated in-memory snapshot.
7. Add regression coverage proving that `REGISTER` no longer depends on whole-project rescan to become visible to subsequent reads.
## Acceptance Criteria
- successful point writes no longer trigger whole-project runtime rescan in the normal path
- the runtime registry supports point in-memory snapshot updates after durable commit
- `REGISTER` updates the loaded project snapshot in place
- subsequent `listAssets`, `getAssetDetails`, and `getAssetActions` read the updated state from memory
- Studio refresh after `REGISTER` remains valid and does not require frontend-local state patching
- full reload remains available only as fallback or explicit recovery path
## Validation
- packer tests for point snapshot patching on `REGISTER`
- packer tests proving read-after-write coherence without full runtime rebuild
- regression tests for fallback safety when point patching cannot be applied
- Studio smoke validation confirming existing refresh behavior still works on top of the updated runtime snapshot
## Affected Artifacts
- `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-studio/src/main/java/p/studio/**`
@@ -1,77 +0,0 @@
# PR-22 Delete Asset Action Confirmation and Fs-First Manifest Removal
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The action capability contract introduced in `PR-20` needs its next real delivery beyond `REGISTER`.
`DELETE` must remove the asset from packer control without deleting the asset directory or its remaining files. The operation is filesystem-first: delete `asset.json`, update `index.json` when needed, and then apply a point snapshot update in memory.
Studio must require explicit confirmation before calling this write path.
## Objective
Deliver `AssetAction.DELETE` end to end with packer-owned capability resolution, Studio confirmation modal, filesystem-first manifest removal, and point runtime snapshot update.
## Dependencies
- [`./PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md)
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
## Scope
- extend the public action contract with `DELETE`
- expose `DELETE` capability from the packer for assets that currently own `asset.json`
- add a packer write path that deletes only `asset.json`
- remove any registered entry from `index.json`
- keep the asset directory and its non-manifest files on disk
- patch the loaded runtime snapshot in memory after successful delete
- add a Studio modal that requires typing the asset name before confirming deletion
## Non-Goals
- no recursive directory deletion
- no deletion of companion files or arbitrary asset contents
- no frontend-local action capability rules
- no bulk delete
## Execution Method
1. Extend the action enum and packer API with `DELETE` and its write message/response.
2. Add packer capability resolution for `DELETE` based on `asset.json` presence, independent from declaration validity.
3. Implement `deleteAsset` in the packer write lane.
4. Make the write path:
- resolve the asset
- delete `asset.json`
- remove the registry entry when the asset is registered
- keep the asset directory and any remaining files untouched
- patch the in-memory snapshot by removing the asset from runtime view
5. Add a Studio confirmation modal that requires the user to type the asset name exactly.
6. On success, let Studio refresh and clear the current selection.
## Acceptance Criteria
- `DELETE` is exposed through the packer action capability contract
- Studio renders `DELETE` only from packer-provided capabilities
- Studio requires asset-name confirmation before executing `DELETE`
- `DELETE` removes only `asset.json`
- registered assets are also removed from `index.json`
- the asset directory and remaining files stay on disk
- the runtime snapshot is updated in memory without whole-project reload in the normal path
## Validation
- packer tests for `DELETE` capability visibility
- packer tests for deleting registered and unregistered assets
- packer tests proving directory contents remain on disk after delete
- Studio compile/test validation for the confirmation modal and action wiring
## Affected Artifacts
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**`
- `prometeu-studio/src/main/java/p/studio/**`
- `prometeu-studio/src/main/resources/**`
@@ -1,101 +0,0 @@
# PR-23 Move Asset Action Wizard and Fs-First Relocation
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The action capability track already delivers `REGISTER` and `DELETE`.
The next operational action is `MOVE`, which must let the user relocate an asset root inside the project's `assets/` tree and optionally rename the asset directory in the same flow.
Studio should own the wizard and the interaction flow. The packer should own the validation semantics, the filesystem move, the registry update, and the point snapshot patch after durable commit.
## Objective
Deliver `AssetAction.MOVE` end to end with a Studio relocation wizard, packer-owned constraints, filesystem-first directory move, and minimal in-memory snapshot update.
## Dependencies
- [`./PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md)
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
- [`./PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md`](./PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md)
## Scope
- extend the public action contract and write messages for `MOVE`
- expose `MOVE` capability from the packer
- add a Studio wizard that collects:
- destination parent directory
- destination directory name
- derived target root inside `assets/`
- add a confirmation step before execution
- add an execution/waiting step with spinner while the move is running
- allow the wizard to work as both relocate and rename of the asset directory
- enforce packer constraints that:
- the target must stay inside the project's `assets/`
- the target root must not already contain `asset.json`
- perform the actual move in the filesystem inside the packer write lane
- update `index.json` and patch the runtime snapshot minimally after commit
## Non-Goals
- no move outside the project's `assets/`
- no directory merge behavior
- no recursive validation of non-manifest file contents
- no batch move
- no frontend-local move semantics
## Execution Method
1. Extend the action contract with `MOVE` and add write request/response messages for asset relocation.
2. Add packer capability resolution for `MOVE`.
3. Build a Studio wizard dedicated to move/rename, with:
- current asset root display
- destination parent picker constrained to `assets/`
- destination directory name field
- derived target root preview
- validation feedback
- confirmation step before submit
- waiting state with spinner after submit until the write result is known
4. Enforce these constraints in the packer:
- the target root must remain under `assets/`
- the target root must not already contain `asset.json`
5. Execute the move in the packer write lane by:
- moving the asset directory in the filesystem
- updating the registry entry root when the asset is registered
- preserving `asset_uuid`
6. Patch the runtime snapshot in memory after the move, without whole-project reload in the normal path.
7. Let Studio refresh and reselect the moved asset after success.
8. Keep the wizard open in waiting state while the move is running, then close only after success; on failure, leave the wizard recoverable with feedback.
## Acceptance Criteria
- `MOVE` is exposed through the packer action capability contract
- Studio opens a wizard for `MOVE`
- the wizard has an explicit confirmation step before execution
- the wizard enters a waiting state with spinner while the move is in flight
- the wizard lets the user relocate and/or rename the asset directory
- the move target cannot be outside the project's `assets/`
- the move target cannot already contain `asset.json`
- the packer performs the filesystem move
- `index.json` is updated when needed
- the runtime snapshot is patched minimally after success
- Studio refreshes and keeps the moved asset selected
## Validation
- packer tests for move capability visibility
- packer tests for successful relocate and successful rename
- packer tests for blockers when target is outside `assets/`
- packer tests for blockers when target already contains `asset.json`
- packer tests proving snapshot patching after move
- Studio smoke validation for wizard confirmation flow, waiting state, and post-move reselection
## Affected Artifacts
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**`
- `prometeu-studio/src/main/java/p/studio/**`
- `prometeu-studio/src/main/resources/**`
@@ -1,200 +0,0 @@
# PR-24 Asset File Cache Hydration and Walker Reuse
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The runtime loader already walks asset roots and produces `walkResult`, and `PackerWorkspacePaths` already reserves `assets/.prometeu/cache.json`.
What is still missing is the actual cache lifecycle:
- previous cache is not loaded before a walk;
- walkers do not receive prior file facts for comparison;
- `walkResult` does not become a durable cache artifact after the scan.
That leaves the current runtime path unable to reuse prior file knowledge such as `lastModified`, `size`, `fingerprint`, and family-specific probe metadata.
This PR introduces the first durable asset file cache flow for the runtime-backed packer wave.
It also tightens how walk output becomes part of the runtime snapshot and how diagnostics are split between normal aggregated surfaces and file-scoped UI-facing surfaces.
## Objective
Deliver an asset-scoped file cache stored in `assets/.prometeu/cache.json`, hydrated before the runtime walk and refreshed from the current `walkResult` after the walk completes, while also attaching the current `walkResult` to the runtime snapshot.
## 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)
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
## Scope
- define the durable schema for `assets/.prometeu/cache.json`
- store cache entries per asset and per discovered file, not as one flat global fingerprint bag
- restrict cache and internal file walk analysis to assets that are already registered and therefore have stable `asset_id`
- load prior cache state during runtime snapshot bootstrap and refresh
- pass prior asset-scoped cache entries into the asset walker
- let walkers compare current file observations against prior cached facts such as `lastModified`, `size`, `fingerprint`, and family-specific metadata
- treat the current `walkResult` as the source used to build the next durable cache state
- attach the current `walkResult` to the in-memory runtime snapshot for later query and UI use
- persist refreshed cache after a successful runtime load or write-path point patch that recomputes asset content
- keep cache miss, corruption, or version mismatch non-fatal for normal asset reads
- keep the Studio-visible asset query surface stable while the cache becomes an internal optimization and comparison input
- keep diagnostics out of the durable cache artifact
- sink general walk diagnostics into the normal asset/runtime diagnostics surface
- preserve file-scoped diagnostics as segregated walk output for UI consumers
## Non-Goals
- no remote/shared cache
- no final `build`/`pack` incremental pipeline
- no background watch service or external reconcile loop
- no silent reuse of stale cache entries when file identity no longer matches the current asset file
- no cache file per asset root; the baseline artifact remains the workspace-level `assets/.prometeu/cache.json`
- no UI contract that exposes raw cache internals directly to Studio
- no cache support for unregistered assets; registration remains the prerequisite for internal file analysis and durable cache ownership
## Execution Shape
`PR-24` should be treated as an umbrella execution plan, not as one direct implementation PR.
This work should be split into smaller follow-up PRs so cache persistence, walker reuse policy, and runtime snapshot integration can each land with narrow tests and isolated regressions.
## Execution Method
1. Introduce a packer-owned cache repository around `PackerWorkspacePaths.cachePath(project)`.
The repository must load, validate, and save one workspace cache artifact without leaking raw filesystem JSON handling into loaders or walkers.
2. Define a versioned durable cache model.
The baseline model should include:
- workspace-level schema/version fields
- asset-scoped entries keyed by stable `asset_id`
- file-scoped entries keyed by normalized relative path inside the asset root
- reusable file facts such as mime type, size, `lastModified`, content fingerprint, and family-specific probe metadata
- no persisted diagnostics; diagnostics remain runtime results produced by the current walk only
3. Extend walker inputs so previous cache is available during content probing.
The walker contract should receive the prior asset cache view together with the declaration and asset root, rather than forcing each concrete walker to reopen cache storage on its own.
Unregistered assets do not enter this flow; they must be registered first before internal file analysis and cache ownership apply.
4. Define cache comparison rules inside the walker layer.
Baseline rules:
- if current file `size` differs from cached `size`, cached data is invalid immediately
- if current file `lastModified` is after cached `lastModified`, cached data is invalid immediately
- content hash or fingerprint should be the last comparison step, used only when the cheaper checks do not already force invalidation and the policy still needs stronger confirmation
- if prior file facts remain valid under that ordered comparison policy, the walker may reuse prior metadata instead of recomputing everything
- if identity facts differ, the walker must treat the file as changed and emit fresh probe output
- missing prior cache is a normal cache miss, not an error
- corrupted or incompatible prior cache should surface diagnostics or operational logging as appropriate, then fall back to a cold walk
5. Promote `walkResult` from transient scan output to cache refresh input.
After a successful walk, the loader must convert only the cacheable portions of the current `walkResult` into the next durable asset cache entry set and merge it into the workspace cache model.
Persisted cache data must be limited to reusable probe facts and metadata, never diagnostics.
6. Attach walk output to the runtime snapshot.
The runtime snapshot should retain a dedicated runtime projection of the current walk output, not the raw probe objects themselves, so query services and Studio-facing adapters can access file-scoped probe metadata and file-scoped diagnostics without forcing a new filesystem walk.
The initial runtime posture should keep the full available file set and the subset that is currently build-eligible, plus bank-size measurement data needed by future fixed-size hardware bank checks.
The raw probe may still carry file bytes during the active walk, but the snapshot projection must strip byte payloads before retention.
The snapshot should keep inventory, probe metadata, build-candidate classification, and bank-size measurements, but not whole file contents or raw `PackerFileProbe` instances by default.
Later cleanup may reduce that retained surface, but the first implementation should prefer preserving available walk data rather than prematurely trimming it.
7. Split diagnostic sinks intentionally.
Baseline rule:
- asset-level or walk-level diagnostics that represent the normal operational truth of the asset should flow into the usual runtime/query diagnostics sink
- file-scoped diagnostics produced by probe processing should remain segregated per file inside the walk result projection
- Studio may consume those file-scoped diagnostics for detailed UI rendering, but that segregation must not be lost by collapsing everything into one flat diagnostics list
- none of those diagnostics are persisted in `cache.json`
8. Persist cache only at stable visibility points.
The normal runtime path should save refreshed cache after the loader finishes building a coherent snapshot.
Write-path flows that patch one asset in memory should update only the affected asset cache entry after durable commit and successful re-walk.
9. Keep runtime snapshot and cache ownership aligned.
Runtime snapshot data may retain the current walk output needed by query services, but the durable cache artifact remains a packer-owned operational store under `assets/.prometeu/cache.json`.
10. Emit observability only at meaningful boundaries.
The implementation may emit `cache_hit` and `cache_miss` events or counters, but adapters must not collapse cache behavior into fake asset-change semantics.
## Acceptance Criteria
- runtime load attempts to read `assets/.prometeu/cache.json` before walking assets
- prior asset-scoped cache entries are passed into walkers as comparison input
- cache entries are keyed by stable `asset_id`, not by asset path
- unregistered assets do not receive cache entries and do not undergo internal file analysis before registration
- walkers compare current files against prior facts using ordered checks where `size` invalidates first, `lastModified` invalidates next when the current value is newer, and fingerprint/hash remains the final expensive check
- the current walk output is attached to the in-memory runtime snapshot through a byte-free runtime projection, not through raw probe objects
- the runtime snapshot keeps enough walk data to expose available files, build-candidate files, and bank-size measurement data
- the runtime snapshot does not retain raw bytes for every discovered file by default
- normal asset/runtime diagnostics include the general walk diagnostics that should participate in the standard diagnostics surface
- file-scoped diagnostics remain segregated in the walk result projection for UI consumers
- the resulting `walkResult` is used to refresh the durable cache state
- successful runtime load writes a coherent updated cache artifact back to `assets/.prometeu/cache.json`
- missing, corrupted, or version-mismatched cache does not block snapshot load; the packer falls back to a cold walk
- point write flows that already patch one asset in memory can refresh only that asset's cache slice after commit instead of forcing full cache rebuild
- cache entries are isolated by asset and file path so one asset cannot accidentally reuse another asset's file facts
- persisted cache does not contain diagnostics from prior runs
- Studio list/details behavior remains stable and does not depend on direct cache awareness
## Tests
- loader tests for cold load when `cache.json` is absent
- loader tests for warm load when prior cache exists and matches current files
- loader tests for fallback when `cache.json` is malformed, unreadable, or schema-incompatible
- cache model tests proving asset cache lookup is aligned by `asset_id`
- walker tests proving changed `size` invalidates reuse immediately
- walker tests proving newer `lastModified` invalidates reuse immediately
- walker tests proving fingerprint/hash is evaluated only as the last comparison step when cheaper checks do not already invalidate reuse
- walker tests proving stable files can reuse prior metadata without changing query-visible results
- cache serialization tests proving diagnostics are never written to `cache.json`
- snapshot/query tests proving `walkResult` is attached to the runtime asset model
- tests proving general walk diagnostics sink into the normal diagnostics surface
- tests proving file-scoped diagnostics remain segregated per file for UI-facing consumers
- runtime registry tests for point cache refresh after write commit on one asset
- event or observability tests for `cache_hit` and `cache_miss` boundaries if those signals are emitted in this wave
## Risks and Recovery
- path-keyed cache would become unsafe during relocate flows, so the cache owner key must remain `asset_id`
- overly aggressive cache reuse can hide real content changes if comparison rules are under-specified
- saving cache at the wrong lifecycle point can publish partial truth that no coherent snapshot ever observed
- if one part of the cache flow proves unstable, recovery should disable cache hydration or persistence for that path and preserve the current cold-walk behavior until the narrower follow-up PR is corrected
## Affected Artifacts
- `docs/packer/pull-requests/**`
- `docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`
- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/PackerWorkspacePaths.java`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**`
- `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/repositories/**`
## Suggested Next Step
Derive smaller implementation PRs from `PR-24`:
1. cache model and repository
Scope:
- durable `cache.json` schema
- load/save repository
- `asset_id`-aligned cache lookup
- serialization tests proving diagnostics are excluded
2. walker contract and comparison policy
Scope:
- previous-cache input contract
- ordered invalidation checks by `size`, then newer `lastModified`, then fingerprint/hash
- file-scoped diagnostics preservation
3. runtime snapshot and loader integration
Scope:
- attach `walkResult` to runtime snapshot
- sink general diagnostics into the normal asset/runtime diagnostics surface
- refresh cache from the cacheable parts of `walkResult`
- point write-path refresh for one affected asset
@@ -1,76 +0,0 @@
# PR-25 Asset Cache Model and Repository
Domain Owner: `docs/packer`
## Briefing
`PR-24` defines the need for a durable asset file cache in `assets/.prometeu/cache.json`, but the first executable slice should stop at cache persistence itself.
Before walkers or runtime snapshot integration can reuse prior file facts safely, the packer needs a stable cache schema, explicit load/save ownership, and tests that prove the cache is keyed correctly and excludes non-cacheable data.
## Objective
Deliver the durable `cache.json` model and repository, keyed by stable `asset_id`, with no persisted diagnostics.
## Dependencies
- [`./PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md)
- [`./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)
## Scope
- define the durable schema for `assets/.prometeu/cache.json`
- key asset cache ownership by stable `asset_id`
- omit unregistered assets from durable cache ownership entirely
- key file cache entries by normalized relative path inside the asset root
- persist reusable probe facts only:
- `mimeType`
- `size`
- `lastModified`
- fingerprint/hash
- family-specific metadata
- exclude diagnostics from the durable cache artifact
- add a packer-owned repository for cache load/save and schema validation
## Non-Goals
- no walker contract changes yet
- no cache comparison or reuse policy yet
- no runtime snapshot model changes yet
- no Studio adapter changes
## Execution Method
1. Add cache model types under the packer runtime model layer.
2. Define one versioned workspace cache artifact for `assets/.prometeu/cache.json`.
3. Encode asset entries by `asset_id`, never by asset root path.
4. Encode file entries by normalized asset-relative path.
5. Add repository load/save behavior with safe fallback on missing or invalid cache files.
6. Prove by tests that diagnostics cannot be serialized into the durable cache artifact.
## Acceptance Criteria
- the packer has explicit model types for the durable cache artifact
- cache ownership is keyed by `asset_id`
- unregistered assets do not receive durable cache entries
- file cache entries are keyed by normalized relative file path
- repository load on absent cache returns a safe empty state
- malformed or schema-incompatible cache can be rejected cleanly without crashing the runtime load path
- diagnostics are not part of the serialized cache schema
## Validation
- schema serialization tests for workspace cache
- repository round-trip tests for valid cache content
- repository tests for absent cache file
- repository tests for malformed cache file
- cache model tests proving `asset_id`-aligned lookup
- serialization tests proving diagnostics are excluded from `cache.json`
## Affected Artifacts
- `docs/packer/pull-requests/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**`
@@ -1,71 +0,0 @@
# PR-26 Walker Cache Input and Comparison Policy
Domain Owner: `docs/packer`
## Briefing
Once the durable cache model exists, the next narrow step is to let walkers consume prior cached file facts without coupling them to cache storage.
This PR defines the cache-aware walker contract and the ordered invalidation policy that decides when prior metadata can be reused and when a fresh probe is mandatory.
## Objective
Deliver walker-side prior-cache input and a deterministic comparison policy ordered by `size`, then newer `lastModified`, then fingerprint/hash.
## Dependencies
- [`./PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md)
- [`./PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md)
## Scope
- extend walker inputs so they receive prior asset cache state
- keep walkers independent from cache repository I/O
- apply walker-side internal file analysis only to already-registered assets
- define ordered invalidation checks:
- changed `size` invalidates immediately
- newer `lastModified` invalidates immediately
- fingerprint/hash is evaluated last when stronger confirmation is still needed
- allow walkers to reuse prior metadata when cached facts remain valid
- preserve file-scoped diagnostics in walk output
## Non-Goals
- no runtime snapshot attachment yet
- no cache persistence integration in the loader yet
- no point write-path refresh yet
- no Studio UI contract changes
## Execution Method
1. Update walker contracts to accept prior asset cache input together with asset root and declaration.
2. Keep cache lookup outside concrete walkers; they should receive an already-resolved asset cache view.
3. Implement the ordered invalidation policy in the shared walker path.
4. Reuse prior metadata only when the ordered checks keep the cached entry valid.
5. Preserve file-scoped diagnostics in the resulting walk output for later runtime and UI consumption.
## Acceptance Criteria
- walkers receive prior asset cache entries as input
- the walker layer does not perform cache repository I/O directly
- unregistered assets are excluded from internal file analysis and cache-aware walker reuse
- changed `size` invalidates prior reuse immediately
- newer `lastModified` invalidates prior reuse immediately
- fingerprint/hash remains the final expensive comparison step
- stable files may reuse prior metadata without changing query-visible semantics
- file-scoped diagnostics remain segregated in walk output
## Validation
- walker tests proving changed `size` invalidates reuse
- walker tests proving newer `lastModified` invalidates reuse
- walker tests proving fingerprint/hash is only evaluated after cheaper checks do not already invalidate reuse
- walker tests proving stable files can reuse prior metadata
- tests proving file-scoped diagnostics remain attached to per-file walk output
## Affected Artifacts
- `docs/packer/pull-requests/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**`
@@ -1,88 +0,0 @@
# PR-27 Runtime WalkResult and Cache Integration
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
With cache persistence and walker reuse policy isolated, the final slice is to connect them to the runtime model.
This PR makes the runtime loader hydrate prior cache before the walk, attach the current `walkResult` to the in-memory snapshot, sink general diagnostics into the normal diagnostics surface, preserve file-scoped diagnostics for UI consumers, and refresh the durable cache from the cacheable portions of the current walk.
## Objective
Deliver runtime-side integration of prior cache hydration, `walkResult` snapshot attachment, diagnostics sink split, and refreshed cache persistence.
## Dependencies
- [`./PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md)
- [`./PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md)
- [`./PR-26-walker-cache-input-and-comparison-policy.md`](./PR-26-walker-cache-input-and-comparison-policy.md)
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
## Scope
- load prior `cache.json` during runtime snapshot bootstrap and refresh
- resolve prior cache by `asset_id` before invoking the walker
- attach a byte-free runtime projection of the current `walkResult` to the in-memory runtime asset model
- retain enough walk data in the runtime snapshot to inspect available files, build-candidate files, and bank-size measurement data
- avoid retaining raw file bytes for the full discovered file set in the runtime snapshot
- sink general walk diagnostics into the normal asset/runtime diagnostics surface
- preserve file-scoped diagnostics as segregated walk output for UI consumers
- refresh and persist cache from the cacheable portions of the current walk
- support point cache refresh for one affected asset after successful write commit and re-walk
## Non-Goals
- no new Studio feature surface beyond exposing already-owned file-scoped walk data
- no background reconcile observer
- no build/incremental pipeline work
## Execution Method
1. Load prior workspace cache at runtime bootstrap and on refresh.
2. Resolve the current asset cache slice by `asset_id` and pass it into the walker.
Assets without `asset_id` are outside this flow and should not receive internal file analysis or cache ownership.
3. Attach a dedicated runtime projection of the current `walkResult` to the runtime snapshot model.
The first implementation should keep the available file set, the build-candidate subset, and bank-size measurement data accessible from the snapshot instead of optimizing that shape away early.
The runtime projection should drop raw file bytes and should not retain raw `PackerFileProbe` objects unless a narrower later use case proves they are needed.
4. Route general walk diagnostics into the standard asset/runtime diagnostics sink.
5. Preserve file-scoped diagnostics inside the walk result projection used by later query/UI consumers.
6. Persist refreshed cache after coherent runtime load completes.
7. Reuse the same logic to refresh one asset cache slice after successful point write commit and re-walk.
## Acceptance Criteria
- runtime load reads prior cache before invoking walkers
- cache lookup passed to the walker is aligned by `asset_id`
- assets without `asset_id` are excluded from cache ownership and internal file analysis
- runtime assets retain a byte-free projection of the current walk output in memory
- runtime assets retain enough walk data to inspect available files, build-candidate files, and bank-size measurement data
- runtime snapshot retention excludes raw file bytes for the general discovered file set
- general walk diagnostics appear in the normal diagnostics surface
- file-scoped diagnostics remain segregated for detailed consumers
- refreshed cache written after runtime load contains only cacheable probe facts and metadata
- point write flows can refresh only one affected asset cache entry after commit
- missing, malformed, or incompatible cache falls back to cold walk without blocking runtime queries
## Validation
- loader tests for cold load without cache
- loader tests for warm load with cache hydration
- snapshot/query tests proving `walkResult` is attached to runtime assets
- diagnostics tests proving general sink aggregation and file-scoped segregation
- cache refresh tests proving the durable artifact is rebuilt from cacheable walk data only
- runtime registry tests for one-asset cache refresh after point write commit
## Affected Artifacts
- `docs/packer/pull-requests/**`
- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
- `prometeu-studio/**` query adapter coverage when file-scoped diagnostics become consumable
@@ -1,107 +0,0 @@
# PR-28 Pack Wizard Public Contracts: Summary, Validation, and Execution
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The Studio `Pack Wizard` decision is now closed on the host side.
That decision makes the intended boundary explicit:
- Studio is a shell;
- packer owns summary, validation, pack execution, progress, and result semantics;
- the Studio-facing flow depends on three distinct calls:
`summary`, `validation`, and `pack execution`.
This PR creates the packer-side public contracts needed for that flow.
Reference decision:
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
## Objective
Add public packer contracts for pack summary, pack validation, and pack execution so Studio can bind the wizard flow without inventing local semantics.
## Dependencies
- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
- [`./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md`](./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md)
- [`./PR-08-assets-pa-and-companion-artifact-emission.md`](./PR-08-assets-pa-and-companion-artifact-emission.md)
## Scope
- extend `PackerWorkspaceService` with three explicit public operations:
- pack summary
- pack validation
- pack execution
- add request/response messages for those operations in `prometeu-packer-api`
- add public DTOs required by those responses
- reuse existing API concepts wherever already adequate instead of cloning parallel concepts
- define result shapes that Studio can bind directly for:
- `Summary`
- `Validation`
- `Result`
- keep progress ownership aligned with the existing event-based packer operational model
## Non-Goals
- no full `prometeu-packer-v1` implementation of summary, validation, or pack execution in this PR
- no Studio wizard implementation in this PR
- no cancellation contract in the first wave
- no speculative build-session abstraction
- no duplication of existing diagnostics DTOs if current public DTOs already satisfy the need
## Execution Method
1. Audit current public API shapes in `prometeu-packer-api` and reuse existing patterns for request/result naming, status, diagnostics, and progress.
2. Extend `PackerWorkspaceService` with three explicit methods that match the Studio decision boundary.
3. Add request/result messages under `p.packer.messages` for:
- summary
- validation
- pack execution
4. Add focused DTOs under the public API for:
- pack summary aggregate
- pack validation aggregate
- pack validation per-asset entry
- emitted artifact summary
- final pack execution summary
5. Reuse existing public diagnostics DTOs for validation drill-down where possible.
6. Keep progress delivery on the existing event path instead of embedding a second progress protocol into result DTOs.
7. Keep naming aligned with the canonical artifact terminology `assets.pa`.
## Contract Direction
The new public surface should make these distinctions explicit:
1. summary is read-only preflight information about the current pack set;
2. validation is dry-run-like and non-emitting;
3. pack execution is the only operation that emits artifacts;
4. the pack set is the current `registered + included in build` set;
5. blocking diagnostics in that set make validation unsuccessful.
## Acceptance Criteria
- `PackerWorkspaceService` exposes three distinct public methods for summary, validation, and pack execution
- the public API includes request/result messages for all three operations
- public DTOs exist for the Studio wizard to render summary, validation, and final result
- existing public diagnostics DTOs are reused where appropriate instead of duplicated
- progress remains aligned with the packer event model rather than a new ad hoc progress response shape
- the contract language uses `assets.pa` as the canonical emitted artifact name
## Validation
- compile-level validation that `prometeu-packer-api` exposes the new methods and DTOs coherently
- public API review for naming and reuse consistency
- contract-focused tests if lightweight API tests already exist for public message shapes
- Studio-side binding review to confirm the API is sufficient without local semantic reconstruction
## Affected Artifacts
- `docs/packer/agendas/**`
- `docs/packer/pull-requests/**`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/PackerWorkspaceService.java`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/**`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/dtos/**`
@@ -1,93 +0,0 @@
# PR-29 Pack Wizard Contract Adjustments for Summary and Validation
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The first public contract wave for the `Pack Wizard` has already landed in `prometeu-packer-api`, but the newly accepted packer decision for `summary` and `validation` closes a more specific shape than the initial API slice.
In particular:
- `summary` is no longer aggregate-only;
- `summary` must expose a per-asset list for the active pack set;
- `validation` is primarily a per-asset blocking-diagnostics list;
- `validation` ordering is not a packer concern in the first wave;
- aggregate validation data is secondary, not the center of the contract.
This PR adjusts the public contracts so they match the accepted packer decision exactly.
Reference decision:
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
## Objective
Align the public `prometeu-packer-api` contract for `summary` and `validation` with the accepted decision before deeper implementation work continues.
## Dependencies
- [`./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
- cross-domain reference:
[`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
## Scope
- adjust the public summary DTOs to include:
- aggregate included asset count
- per-asset summary list
- adjust the public validation DTOs to make the per-asset blocking-diagnostics list the primary payload
- add or rename DTOs as needed for:
- per-asset summary entry
- per-asset validation entry
- keep `lastModified` present in both summary and validation item contracts
- preserve the `read-only` and `non-mutating` nature of summary and validation
- keep the Studio-facing API explicit and aligned with the accepted packer decision
## Non-Goals
- no runtime implementation of summary in `prometeu-packer-v1`
- no runtime implementation of validation in `prometeu-packer-v1`
- no `pack execution` contract changes unless strictly required by compile compatibility
- no Studio implementation work in this PR
## Execution Method
1. Revisit the current `summary` and `validation` public DTOs in `prometeu-packer-api`.
2. Expand the summary result shape so it carries:
- total included asset count
- per-asset summary entries
3. Expand or reshape validation so the returned per-asset entries expose:
- asset id
- asset name
- asset path
- `lastModified`
- blocking diagnostics
4. Keep validation aggregate data optional or secondary rather than the primary response focus.
5. Preserve defensive-copy and validation patterns already used by public API records.
6. Update Studio compile surfaces only as needed to keep the workspace consuming the revised contracts coherently.
## Acceptance Criteria
- the public summary contract matches the accepted decision shape
- the public validation contract matches the accepted decision shape
- `lastModified` exists in both per-asset summary and per-asset validation entries
- validation payloads carry blocking diagnostics only in the first wave
- compile succeeds across `prometeu-packer-api`, `prometeu-packer-v1`, and any directly affected Studio call sites
## Validation
- compile validation for `prometeu-packer-api`
- compile validation for `prometeu-packer-v1`
- compile validation for `prometeu-studio`
- lightweight API tests if public message-shape tests already exist
## Affected Artifacts
- `docs/packer/decisions/**`
- `docs/packer/pull-requests/**`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/PackerWorkspaceService.java`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/**`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/dtos/**`
- `prometeu-studio/**` compile-level consumers of the summary/validation contracts
@@ -1,83 +0,0 @@
# PR-30 Pack Wizard Summary Snapshot Query
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
With the public contracts aligned, the next step is to actually produce the pack-wizard `summary` from the packer runtime snapshot.
This is intentionally narrower than full pack execution.
The goal is to expose a fast preflight summary of the active pack set so the Studio wizard can open on packer-owned state instead of local UI heuristics.
Reference decision:
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
## Objective
Implement snapshot-backed `summary` for the pack wizard over the current `registered + included in build` set.
## Dependencies
- [`./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md)
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
- cross-domain reference:
[`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
## Scope
- implement `getPackWorkspaceSummary(...)` in `prometeu-packer-v1`
- resolve the active pack set from the runtime snapshot:
`registered + included in build`
- produce the aggregate included asset count
- produce the per-asset summary list with:
- asset id
- asset name
- asset family
- min artifact count
- max artifact count
- `lastModified`
- allow `lastModified = 0` in the first wave where the real value is not yet available
- keep the query fast and snapshot-backed
## Non-Goals
- no validation logic in this PR
- no pack execution logic in this PR
- no emitted-artifact preview in summary
- no inclusion of unregistered or excluded assets as explicit summary items
## Execution Method
1. Resolve the active runtime snapshot for the requested project.
2. Filter the snapshot to the active pack set:
registered assets included in build.
3. Derive one aggregate count from that filtered set.
4. Map each included asset into the public per-asset summary DTO.
5. Populate `minArtifactCount` and `maxArtifactCount` from the best currently available packer-owned summary facts.
6. Populate `lastModified` from packer-owned runtime or filesystem facts when available, otherwise `0`.
7. Return the summary result without performing deep validation or artifact planning.
## Acceptance Criteria
- `getPackWorkspaceSummary(...)` returns successfully from snapshot-backed state
- the returned set contains only `registered + included in build` assets
- the aggregate count matches the per-asset list size
- per-asset summary entries expose the fields required by the accepted decision
- the operation behaves as a fast read query rather than a deep recomputation path
## Validation
- packer unit tests for pack-set filtering
- packer unit tests for summary DTO mapping
- regression tests proving excluded and unregistered assets do not appear as summary items
- Studio smoke validation proving the wizard summary can render from packer-owned data
## Affected Artifacts
- `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-studio/**` wizard summary consumer surfaces if compile adaptation is needed
@@ -1,91 +0,0 @@
# PR-31 Pack Wizard Validation Snapshot Gate
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The `Pack Wizard` validation phase is not a generic workspace scan.
It is a pack-set-specific gate over the current `registered + included in build` snapshot state.
The accepted decision closes the first-wave semantics:
- validation is read-only and snapshot-backed;
- validation looks only at the active pack set;
- only `blocking` diagnostics fail validation;
- the primary payload is the per-asset blocking-diagnostics list.
This PR implements that gate in `prometeu-packer-v1`.
Reference decision:
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
## Objective
Implement snapshot-backed pack validation that returns per-asset blocking diagnostics for the active pack set and decides whether packing may proceed.
## Dependencies
- [`./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md)
- [`./PR-30-pack-wizard-summary-snapshot-query.md`](./PR-30-pack-wizard-summary-snapshot-query.md)
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
- cross-domain reference:
[`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
## Scope
- implement `validatePackWorkspace(...)` in `prometeu-packer-v1`
- evaluate only the current `registered + included in build` set from the runtime snapshot
- collect only `blocking` diagnostics for the first-wave validation payload
- return per-asset validation entries with:
- asset id
- asset name
- asset path
- `lastModified`
- blocking diagnostics
- make validation green when no blocking diagnostics are returned
- make validation red when any blocking diagnostics are returned
- keep aggregate validation data secondary to the per-asset list
## Non-Goals
- no pack execution in this PR
- no non-blocking diagnostics in the first-wave validation payload
- no packer-owned ordering contract for the returned validation list
- no deep-sync orchestration in this PR beyond using the current snapshot boundary
## Execution Method
1. Resolve the current runtime snapshot for the requested project.
2. Filter it to the active pack set:
`registered + included in build`.
3. Gather diagnostics relevant to each asset in that set.
4. Keep only diagnostics marked `blocking` for the first-wave validation response.
5. Map each asset with blockers into the public per-asset validation DTO.
6. Allow `lastModified = 0` temporarily where the real value is not yet available.
7. Return validation as green when the per-asset blocker list is empty and red otherwise.
## Acceptance Criteria
- `validatePackWorkspace(...)` evaluates only the active pack set
- only blocking diagnostics appear in the first-wave validation payload
- validation succeeds when no blocking diagnostics are present
- validation fails when any blocking diagnostics are present
- per-asset validation entries expose the fields required by the accepted decision
- Studio can stop before `Packing` using packer-owned validation alone
## Validation
- packer unit tests for pack-set filtering during validation
- packer unit tests proving non-blocking diagnostics do not fail the first-wave validation
- packer unit tests proving blocking diagnostics do fail validation
- DTO-mapping tests for per-asset validation entries
- Studio smoke validation proving the wizard blocks on returned blockers
## Affected Artifacts
- `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-studio/**` validation consumer surfaces if compile adaptation is needed
@@ -1,113 +0,0 @@
# PR-32 Palette Declarations with Explicit Index Contract
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`, `../runtime`
## Briefing
The current authoring shape for `asset.json.output.pipeline.palettes` is still too dependent on list order as semantic identity.
That is fragile:
- editorial reordering can silently change meaning;
- merges become harder to review safely;
- the packer has to infer identity from position instead of reading it explicitly.
The repository already depends on stable palette ordering for `tile bank` packing.
That ordering should therefore be explicit in the authoring contract.
## Decisions de Origem
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
- ongoing agenda:
[`../agendas/Tile Bank Packing Materialization Agenda.md`](../agendas/Tile%20Bank%20Packing%20Materialization%20Agenda.md)
## Objective
Replace list-position-defined palette identity with an explicit index-bearing declaration contract for `asset.json.output.pipeline.palettes`.
Recommended shape:
```json
"palettes": [
{
"index": 0,
"palette": { ... }
},
{
"index": 1,
"palette": { ... }
}
]
```
## Dependencies
- tile-bank materialization agenda in `docs/packer/agendas`
- runtime-side tile-bank consumer contract already aligned around stable palette ids
## Scope
- define the normative authoring shape for `output.pipeline.palettes`
- make `index` the semantic identity of each declared palette
- require packer normalization to sort by `index`, not by list position
- define diagnostics for duplicate, missing, invalid, or malformed palette entries
- prepare propagation into:
- packer specs
- parser/runtime-facing normalization code
- Studio editing surfaces if they expose palette management
## Non-Goals
- no immediate migration of `artifacts` in this PR
- no tile-bank payload implementation in this PR
- no runtime code changes in this PR
- no speculative keyed-object JSON contract for palettes in this wave
## Execution Method
1. Update the packer-side documentation/decision chain to make palette identity explicit.
2. Define `output.pipeline.palettes` as a list of records with:
- `index`
- `palette`
3. State that semantic ordering is ascending numeric `index`, never raw list position.
4. Define structural diagnostics:
- duplicate `index` => blocking
- negative or malformed `index` => blocking
- missing `palette` payload => blocking
- palette count above the runtime-facing v1 limit => blocking
5. Define whether index gaps are:
- blocking
- or warning/advisory
6. Prepare follow-up implementation PRs for parser, validation, and Studio surfaces.
## Contract Direction
First-wave packer contract direction:
1. `output.pipeline.palettes` remains a JSON array for authoring ergonomics;
2. each entry must declare an explicit `index`;
3. each entry must declare a `palette` object payload;
4. packer meaning comes from numeric `index`, not from the physical array position;
5. the runtime-facing `palette_id` consumed later by tile/sprite draw paths is the normalized numeric palette `index`.
## Acceptance Criteria
- the packer docs/spec path no longer relies on raw list order as palette identity
- the explicit-index palette shape is documented clearly enough for parser and Studio implementation
- duplicate or malformed palette indices are identified as structural diagnostics
- the contract leaves no ambiguity about whether sorting happens by array order or by `index`
## Validation
- editorial validation across packer agenda/decision/spec material
- parser-oriented review proving the contract is implementable without hidden heuristics
- Studio-facing review confirming the editing UX can preserve stable palette identity
## Affected Artifacts
- `docs/packer/agendas/**`
- `docs/packer/decisions/**`
- `docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`
- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`
- future parser/runtime materialization code under `prometeu-packer-v1`
@@ -1,80 +0,0 @@
# PR-33 Tile Bank Spec Propagation and Runtime Contract Alignment
Domain Owner: `docs/packer`
Cross-Domain Impact: `../runtime`, `docs/studio`
## Briefing
The `Tile Bank Packing Materialization Decision` is now closed.
Before more code lands, the normative spec path needs to be updated so implementation is not forced to infer format details from agendas and decisions.
This PR is editorial-first.
Its job is to propagate the accepted tile-bank producer contract into the relevant packer specs and to make the runtime alignment explicit.
## Objective
Update the normative spec corpus so `tile bank` v1 packing has one unambiguous producer contract.
## Dependencies
- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md)
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
## Scope
- propagate the accepted `tile bank` v1 contract into packer specs
- define canonical payload semantics for `TILES/indexed_v1`
- define metadata convergence shape for tile-bank runtime entries
- make runtime-aligned size and decoded-size formulas explicit
- document the fixed `256 x 256` target and row-major slot semantics
## Non-Goals
- no production code changes
- no walker refactor
- no payload emitter implementation
- no runtime implementation work
## Method
1. Update [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md).
2. Define `TILES/indexed_v1` producer semantics explicitly:
- `1 artifact = 1 tile`
- `tile_id = normalized artifacts[*].index`
- fixed `256 x 256` emitted sheet
- row-major placement
- packed `u4` pixel plane
- `64 * 16 * u16` RGB565 palette block
3. Document runtime entry derivation:
- `bank_type = TILES`
- `codec = NONE`
- `size = ceil(width * height / 2) + 2048`
- `decoded_size = (width * height) + 2048`
4. Document metadata normalization:
- `output.metadata -> metadata`
- `output.codec_configuration -> metadata.codec`
- `output.pipeline -> metadata.pipeline`
5. Cross-reference the runtime-side metadata normalization discussion without pretending it is already closed there.
## Acceptance Criteria
- the packer spec corpus contains one explicit producer contract for tile-bank v1
- the payload shape no longer needs to be reconstructed from agenda text
- size, decoded-size, palette count, and metadata shape are all normative
- the spec states what the producer emits because that is what the consumer requires
## Validation
- editorial review against the accepted decision
- consistency check against runtime specs and loader assumptions
- terminology review for `tile_id`, `palette_id`, `size`, `decoded_size`, and metadata segmentation
## Affected Artifacts
- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`
- possibly `docs/packer/specs/1. Domain and Artifact Boundary Specification.md`
- possibly `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`
@@ -1,75 +0,0 @@
# PR-34 Tile Bank Diagnostics and Validation Hardening
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The tile-bank decision closed the structural blockers and warnings that must exist before pack emission.
Those diagnostics belong in the walker/materialization path so they surface during validation and are naturally rerun by `packWorkspace(...)` when a fresh frozen snapshot is created.
This PR isolates that diagnostic work from payload emission.
## Objective
Add the accepted tile-bank diagnostics to the packer walk/materialization path and make validation consume them consistently.
## Dependencies
- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md)
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
- `PR-33` for normative spec propagation
## Scope
- add tile-bank structural blocking diagnostics
- add tile-bank warning diagnostics for fragile indices
- ensure those diagnostics live in the walker/materialization path
- ensure validation consumes them without special late pack-only logic
## Non-Goals
- no full payload emission yet
- no staging/promote pipeline yet
- no shipper behavior
- no future multi-tile-per-artifact support
## Method
1. Add blocking diagnostics for:
- duplicate `artifacts[*].index`
- gaps in normalized artifact indices
- fixed-sheet capacity overflow
- banks without declared palettes
- palette declaration count above `64`
- malformed palette declarations
- missing or invalid required tile-bank metadata
- failures to normalize artifacts into deterministic tile candidates
2. Add `WARNING` diagnostics for fragile tile indices across the full declared bank palette set.
3. Ensure diagnostics are attached at file/asset walk time so:
- `GetAssetDetails`
- `ValidatePackWorkspace`
- future pack rerun gate
all see the same structural findings.
4. Add tests that distinguish blocking failures from advisory warnings.
## Acceptance Criteria
- validation returns blocked tile-bank assets when any accepted blocker exists
- fragile-index findings are visible but do not block by themselves
- no tile-bank structural problem is discovered only during final byte emission
- the same diagnostic vocabulary is visible in details and validation paths
## Validation
- targeted service and walker tests
- validation-flow regression tests
- asset-details regression tests for warning and blocking surfaces
## Affected Artifacts
- `prometeu-packer-v1` tile-bank walker/materialization code
- `prometeu-packer-v1` validation/query services
- related tests under `prometeu-packer-v1/src/test`
@@ -1,69 +0,0 @@
# PR-35 Packing-Aware Walkers and Runtime Materialization Preparation
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
Pack execution now depends on a frozen in-memory execution snapshot, but the repository deliberately chose not to fork discovery into one runtime walker stack and one packing walker stack.
This PR prepares the existing walker/materialization path so it can serve both runtime reads and pack execution with explicit policy.
## Objective
Prepare walkers and runtime materialization for packing-aware projection without implementing final pack emission yet.
## Dependencies
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md)
- `PR-34` for diagnostics already present in the walk/materialization path
## Scope
- add optional content bytes to runtime walk projection
- introduce or finish the accepted materialization config/policy shape
- keep family walkers discovery-oriented
- enable packing-focused projection filtering over discovered probes
- make build-relevant content bytes available for packing snapshots only
## Non-Goals
- no final `packWorkspace(...)` implementation yet
- no staging/promotion yet
- no tile-bank payload bytes emitted yet
- no alternative walker stack
## Method
1. Add `Optional<byte[]>` support to `PackerRuntimeWalkFile`.
2. Ensure full probes can still carry bytes internally during discovery.
3. Materialize runtime projection using explicit config/policy:
- runtime mode suppresses optional bytes
- packing mode injects optional bytes
- projection filter keeps only build-relevant selected probes
4. Keep family walkers focused on relevance-by-family.
5. Add tests showing:
- runtime default projection does not retain bytes
- packing projection retains bytes only for relevant selected files
- the same discovery path serves both modes
## Acceptance Criteria
- the repository has one walker discovery path, not two divergent ones
- packing projection can freeze build-relevant bytes in memory
- runtime-backed reads do not become wasteful full-memory mirrors
- selected build inputs survive into runtime walk projection with optional bytes when packing mode is requested
## Validation
- targeted runtime materialization tests
- walker reuse regression tests
- cache integration review where relevant
## Affected Artifacts
- `prometeu-packer-v1` walker models
- `prometeu-packer-v1` runtime materializer/export path
- related tests under `prometeu-packer-v1/src/test`
@@ -1,86 +0,0 @@
# PR-36 Pack Workspace Execution with Frozen Snapshot and Staging
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`, `../runtime`
## Briefing
After specs, diagnostics, and packing-aware materialization are in place, the remaining step is the actual pack execution pipeline.
This PR implements `packWorkspace(...)` as the first end-to-end writer that:
- reruns the gate on a fresh execution snapshot;
- materializes build outputs from frozen in-memory inputs;
- stages outputs before promotion;
- and publishes coherent final artifacts to `build/`.
## Objective
Implement the first-wave `packWorkspace(...)` pipeline with frozen snapshot input, tile-bank payload emission, and staged publication.
## Dependencies
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md)
- `PR-33`
- `PR-34`
- `PR-35`
## Scope
- implement pack rerun gate on a fresh execution snapshot
- materialize tile-bank payload bytes from frozen in-memory inputs
- emit `assets.pa` and companion outputs in staging
- promote staged outputs into final `build/` locations only on coherent success
- return structured pack results for blocked, failed, and successful outcomes
## Non-Goals
- no shipper packaging or `.pbc` generation
- no remote or incremental build behavior
- no cancellation semantics
- no non-tile-bank payload families unless they are already trivial and fully decided
## Method
1. Create a fresh frozen execution snapshot for the current included-in-build set.
2. Rerun the pack validation gate on that snapshot before byte emission begins.
3. For tile banks:
- normalize selected artifacts into one row-major `256 x 256` sheet
- pack tile pixels as `u4`
- emit the `64 * 16 * 2` RGB565 palette block
- derive runtime entry metadata using the accepted segmentation contract
4. Emit staged outputs under `build/.staging/<operation-id>/`.
5. Promote staged outputs into:
- `build/assets.pa`
- `build/asset_table.json`
- `build/preload.json`
- `build/asset_table_metadata.json`
6. Return structured terminal results that distinguish:
- gate failure
- execution/materialization failure
- persistence/promotion failure
## Acceptance Criteria
- `packWorkspace(...)` never emits from live filesystem rereads after frozen snapshot creation
- gate rerun blocks stale-invalid projects even if validation was green earlier
- failed execution before promotion does not leave partial final build outputs visible as success
- successful execution publishes coherent final build outputs
- tile-bank payload bytes satisfy the accepted producer contract and runtime consumer assumptions
## Validation
- targeted `packWorkspace(...)` service tests
- tile-bank conformance tests from artifacts to emitted payload
- staging/promotion failure-path tests
- regression tests for blocked vs failed vs successful results
## Affected Artifacts
- `prometeu-packer-api` pack result contract
- `prometeu-packer-v1` pack execution service
- `prometeu-packer-v1` tile-bank payload materializer
- `prometeu-packer-v1` staging/promote pipeline
- related tests under `prometeu-packer-v1/src/test`
+8 -49
View File
@@ -2,6 +2,12 @@
This directory contains self-contained packer change proposals for review.
Current retained set:
- none
The previous execution wave has already been consolidated into [`../learn/`](../learn/) and propagated into [`../specs/`](../specs/).
## Purpose
A pull request document packages a packer change as an executable plan before final integration.
@@ -58,52 +64,5 @@ A pull request may plan code and spec consequences, but it must not replace a mi
## Production Sequence
The current production track for the standalone `prometeu-packer` project is:
1. [`PR-01-packer-project-bootstrap-and-module-boundaries.md`](./PR-01-packer-project-bootstrap-and-module-boundaries.md)
2. [`PR-02-workspace-init-registry-and-identity-foundation.md`](./PR-02-workspace-init-registry-and-identity-foundation.md)
3. [`PR-03-asset-declaration-parsing-validation-and-details-contract.md`](./PR-03-asset-declaration-parsing-validation-and-details-contract.md)
4. [`PR-04-workspace-scan-list-assets-and-studio-read-adapter.md`](./PR-04-workspace-scan-list-assets-and-studio-read-adapter.md)
5. [`PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](./PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md)
6. [`PR-06-doctor-diagnostics-and-safe-fix-baseline.md`](./PR-06-doctor-diagnostics-and-safe-fix-baseline.md)
7. [`PR-07-build-plan-determinism-and-cache-key-foundation.md`](./PR-07-build-plan-determinism-and-cache-key-foundation.md)
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)
19. [`PR-19-api-surface-audit-model-separation-and-public-read-dtos.md`](./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md)
20. [`PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md)
21. [`PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
22. [`PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md`](./PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md)
23. [`PR-23-move-asset-action-wizard-and-fs-first-relocation.md`](./PR-23-move-asset-action-wizard-and-fs-first-relocation.md)
24. [`PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md)
25. [`PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md)
26. [`PR-26-walker-cache-input-and-comparison-policy.md`](./PR-26-walker-cache-input-and-comparison-policy.md)
27. [`PR-27-runtime-walkresult-and-cache-integration.md`](./PR-27-runtime-walkresult-and-cache-integration.md)
28. [`PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
29. [`PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md)
30. [`PR-30-pack-wizard-summary-snapshot-query.md`](./PR-30-pack-wizard-summary-snapshot-query.md)
31. [`PR-31-pack-wizard-validation-snapshot-gate.md`](./PR-31-pack-wizard-validation-snapshot-gate.md)
32. [`PR-32-palette-declarations-with-explicit-index-contract.md`](./PR-32-palette-declarations-with-explicit-index-contract.md)
33. [`PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md`](./PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md)
34. [`PR-34-tile-bank-diagnostics-and-validation-hardening.md`](./PR-34-tile-bank-diagnostics-and-validation-hardening.md)
35. [`PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md`](./PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md)
36. [`PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md`](./PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.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-11 -> PR-12 -> PR-13 -> PR-14 -> PR-15 -> PR-16 -> PR-17 -> PR-18 -> PR-19 -> PR-20 -> PR-21 -> PR-22 -> PR-23 -> PR-24 -> PR-25 -> PR-26 -> PR-27 -> PR-28 -> PR-29 -> PR-30 -> PR-31 -> PR-32 -> PR-33 -> PR-34 -> PR-35 -> PR-36`
When a new execution wave starts, add only the PRs that still represent pending work.
Do not repopulate this directory with already-absorbed historical implementation slices.