clean up
This commit is contained in:
@@ -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
|
||||
-65
@@ -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
|
||||
-78
@@ -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
|
||||
-83
@@ -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
|
||||
-194
@@ -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.
|
||||
-74
@@ -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
|
||||
-73
@@ -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
|
||||
-71
@@ -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
|
||||
-73
@@ -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
|
||||
-98
@@ -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/**`
|
||||
|
||||
-101
@@ -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/**`
|
||||
|
||||
-77
@@ -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/**`
|
||||
-77
@@ -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
|
||||
-107
@@ -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/**`
|
||||
-93
@@ -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`
|
||||
-80
@@ -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`
|
||||
|
||||
-69
@@ -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`
|
||||
|
||||
-86
@@ -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`
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user