added packer PRs
This commit is contained in:
@@ -0,0 +1,63 @@
|
||||
# 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
|
||||
@@ -0,0 +1,60 @@
|
||||
# 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
@@ -0,0 +1,65 @@
|
||||
# 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
|
||||
@@ -0,0 +1,61 @@
|
||||
# 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
@@ -0,0 +1,78 @@
|
||||
# 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
|
||||
@@ -0,0 +1,60 @@
|
||||
# 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
|
||||
@@ -0,0 +1,62 @@
|
||||
# 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
|
||||
@@ -0,0 +1,63 @@
|
||||
# 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
@@ -0,0 +1,83 @@
|
||||
# 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
|
||||
@@ -0,0 +1,70 @@
|
||||
# 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
|
||||
@@ -55,3 +55,22 @@ Recommended additional sections:
|
||||
## Review Rule
|
||||
|
||||
A pull request may plan code and spec consequences, but it must not replace a missing decision record.
|
||||
|
||||
## 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)
|
||||
|
||||
Recommended dependency chain:
|
||||
|
||||
`PR-01 -> PR-02 -> PR-03 -> PR-04 -> PR-05 -> PR-06 -> PR-07 -> PR-08 -> PR-09 -> PR-10`
|
||||
|
||||
Reference in New Issue
Block a user