diff --git a/docs/packer/decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md b/docs/packer/decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md new file mode 100644 index 00000000..3c2e0a53 --- /dev/null +++ b/docs/packer/decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md @@ -0,0 +1,130 @@ +# Concurrency, Observability, and Studio Adapter Boundary Decision + +Status: Accepted +Date: 2026-03-11 +Domain Owner: `docs/packer` +Cross-Domain Impact: `docs/studio` + +## Context + +The production `prometeu-packer` track introduces two architectural seams that must not remain implicit: + +1. the packer will become the operational source of truth for asset summaries, diagnostics, mutation previews, and build lifecycle state; +2. Studio will consume that operational model through adapters instead of reconstructing packer semantics locally; +3. the event and concurrency model must stay coherent when the packer is integrated into the Studio `Assets` workspace and shell. + +Without an explicit decision, the repository risks drifting into duplicated semantics: + +- Studio deriving packer-facing summaries from filesystem heuristics; +- Studio inventing lifecycle meaning not present in packer events; +- concurrent mutation or build behavior becoming observable in inconsistent ways. + +## Decision + +The following direction is adopted: + +1. `prometeu-packer` is the semantic owner of asset operational state. +2. Studio is a consumer and remapper of packer responses and events, not a competing source of packer truth. +3. The baseline packer write policy is a `single-writer semantic lane per project`. +4. Packer observability is packer-native and causality-preserving. +5. Studio adapters may reshape packer data for UI presentation, but may not invent packer semantics, causal relationships, or final outcomes absent from packer responses/events. + +## Adopted Constraints + +### 1. Summary and Response Authority + +- asset `summary`, `details`, `diagnostics`, `preview`, and build/mutation lifecycle state originate in the packer; +- Studio may use packer responses directly or remap them into view models; +- Studio must not define an alternative packer summary model from direct filesystem inspection once the packer-backed path exists; +- UI-oriented phrasing or grouping is allowed only as a remapping of packer-owned semantics. + +### 2. Concurrency Model + +- coordination is project-scoped; +- unrelated projects are not forced into one global execution lane; +- `read/read` may run concurrently when reads observe a coherent snapshot; +- `read/write` must not expose torn intermediate state; +- `write/write` on the same project is serialized; +- `build/write` on the same project is serialized unless a future explicit transactional model supersedes this baseline; +- preview generation may run outside the final commit-critical section when safe, but final apply/commit remains serialized. + +### 3. Event and Observability Model + +- the packer emits the authoritative event stream for asset operations; +- each logical operation must carry a stable `operation_id`; +- events within one operation must carry monotonic `sequence`; +- baseline event payloads must preserve fields equivalent to: + - `project_id` + - `operation_id` + - `sequence` + - `kind` + - `timestamp` + - `summary` + - `progress` when applicable + - `affected_assets` when applicable +- event ordering must remain causally coherent for one operation; +- progress-like low-value repetition may be coalesced by sinks/adapters; +- terminal lifecycle markers must remain individually observable. + +### 4. Studio Adapter Boundary + +- Studio adapts packer events into the existing Studio event bus and workspace models; +- Studio may convert packer-native envelopes into Studio-native event types for shell/workspace consumption; +- that adapter layer must remain translational, not semantic-authoritative; +- Activity, progress, and staged mutation surfaces in Studio must reflect packer-native lifecycle, not replace it. + +## Why This Direction Was Chosen + +- It prevents split-brain semantics between packer and Studio. +- It keeps packer behavior testable outside JavaFX. +- It allows Studio UI iteration without moving domain rules into the UI layer. +- It gives concurrency and observability one owner, which is necessary for deterministic mutation and build behavior. + +## Explicit Non-Decisions + +This decision does not define: + +- the final internal threading primitives or executor topology of `prometeu-packer`; +- a watch daemon or continuous background worker model; +- remote/shared cache coordination; +- cross-project scheduling policy beyond allowing separate projects to coordinate independently; +- final event transport beyond the local adapter/event sink model currently planned. + +## Implications + +- read adapters belong in the packer integration track, not in Studio-local filesystem services; +- mutation preview/apply semantics belong in packer services and only map into Studio staged UI models; +- Studio Activity and progress integration must preserve packer causality metadata, even if the UI renders a simplified form; +- tests must verify both same-project write serialization and event ordering through the Studio adapter path. + +## Propagation Targets + +Specs: + +- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) + +Plans: + +- [`../pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md`](../pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md) +- [`../pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](../pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md) +- [`../pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md`](../pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md) + +Cross-domain references: + +- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) +- [`../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md`](../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md) + +Implementation surfaces: + +- future `prometeu-packer` service contracts and event sink abstractions +- Studio packer read/write/event adapters +- Studio Activity/progress mapping code + +## Validation Notes + +The decision is correctly implemented only when all of the following are true: + +- the same packer operation can be replayed and observed without Studio inventing hidden state; +- conflicting writes on one project cannot commit concurrently; +- Activity/progress in Studio can be driven from packer-native events alone; +- Studio summaries are either direct packer outputs or remapped packer outputs, never independent semantic recomputation. diff --git a/docs/packer/decisions/README.md b/docs/packer/decisions/README.md index ff2ef279..2b29b47a 100644 --- a/docs/packer/decisions/README.md +++ b/docs/packer/decisions/README.md @@ -2,7 +2,9 @@ This directory contains packer decision records. -There are currently no retained packer decision records. +Retained packer decision records: + +- [`Concurrency, Observability, and Studio Adapter Boundary Decision.md`](./Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md) The first packer decision wave was already consolidated into: diff --git a/docs/packer/pull-requests/PR-01-packer-project-bootstrap-and-module-boundaries.md b/docs/packer/pull-requests/PR-01-packer-project-bootstrap-and-module-boundaries.md new file mode 100644 index 00000000..1976df9e --- /dev/null +++ b/docs/packer/pull-requests/PR-01-packer-project-bootstrap-and-module-boundaries.md @@ -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 diff --git a/docs/packer/pull-requests/PR-02-workspace-init-registry-and-identity-foundation.md b/docs/packer/pull-requests/PR-02-workspace-init-registry-and-identity-foundation.md new file mode 100644 index 00000000..a2fa88fc --- /dev/null +++ b/docs/packer/pull-requests/PR-02-workspace-init-registry-and-identity-foundation.md @@ -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 diff --git a/docs/packer/pull-requests/PR-03-asset-declaration-parsing-validation-and-details-contract.md b/docs/packer/pull-requests/PR-03-asset-declaration-parsing-validation-and-details-contract.md new file mode 100644 index 00000000..c48ca4d7 --- /dev/null +++ b/docs/packer/pull-requests/PR-03-asset-declaration-parsing-validation-and-details-contract.md @@ -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 diff --git a/docs/packer/pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md b/docs/packer/pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md new file mode 100644 index 00000000..ec849a9b --- /dev/null +++ b/docs/packer/pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md @@ -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 diff --git a/docs/packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md b/docs/packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md new file mode 100644 index 00000000..8a0d4f30 --- /dev/null +++ b/docs/packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md @@ -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 diff --git a/docs/packer/pull-requests/PR-06-doctor-diagnostics-and-safe-fix-baseline.md b/docs/packer/pull-requests/PR-06-doctor-diagnostics-and-safe-fix-baseline.md new file mode 100644 index 00000000..6271ec7a --- /dev/null +++ b/docs/packer/pull-requests/PR-06-doctor-diagnostics-and-safe-fix-baseline.md @@ -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 diff --git a/docs/packer/pull-requests/PR-07-build-plan-determinism-and-cache-key-foundation.md b/docs/packer/pull-requests/PR-07-build-plan-determinism-and-cache-key-foundation.md new file mode 100644 index 00000000..5da2383e --- /dev/null +++ b/docs/packer/pull-requests/PR-07-build-plan-determinism-and-cache-key-foundation.md @@ -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 diff --git a/docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md b/docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md new file mode 100644 index 00000000..6e1702ca --- /dev/null +++ b/docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md @@ -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 diff --git a/docs/packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md b/docs/packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md new file mode 100644 index 00000000..fb2ca9b8 --- /dev/null +++ b/docs/packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md @@ -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 diff --git a/docs/packer/pull-requests/PR-10-versioning-migration-trust-and-production-gates.md b/docs/packer/pull-requests/PR-10-versioning-migration-trust-and-production-gates.md new file mode 100644 index 00000000..6dd89c01 --- /dev/null +++ b/docs/packer/pull-requests/PR-10-versioning-migration-trust-and-production-gates.md @@ -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 diff --git a/docs/packer/pull-requests/README.md b/docs/packer/pull-requests/README.md index 2d6358af..6c3d0b79 100644 --- a/docs/packer/pull-requests/README.md +++ b/docs/packer/pull-requests/README.md @@ -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` diff --git a/docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md b/docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md index 69290121..b712da6b 100644 --- a/docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md +++ b/docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md @@ -66,6 +66,24 @@ Operations must distinguish: This distinction is part of the service semantics and must be visible to the UI. +## Concurrency Model + +The packer concurrency model is conservative and project-scoped. + +Rules: + +- observable correctness takes priority over speculative parallelism; +- operations are coordinated per project workspace, not globally across unrelated projects; +- Studio is a consumer of packer coordination results, not the owner of packer concurrency policy. + +### Baseline Operation Matrix + +- read/read may run concurrently when each read observes a coherent snapshot; +- read/write must not expose torn intermediate state to consumers; +- write/write on the same project is serialized; +- build/write on the same project is serialized unless a future spec introduces an explicit transactional coordination model; +- background observation may continue while a serialized write lane is active, but it must not publish misleading post-state before commit visibility. + ## Preview/Apply Model Sensitive mutations use staged intent. @@ -126,6 +144,40 @@ Rules: - background observation and reporting may be continuous; - conflicting sensitive mutations must not race arbitrarily; - observable mutation behavior remains coherent from the UI perspective. +- the baseline write policy is a single-writer semantic lane per project; +- preview generation may run outside the final commit section, but apply/commit remains serialized; +- build and sensitive mutation apply must not interleave on the same project in a way that obscures final state; +- cancellation or failure must leave the observable project state in a coherent post-operation condition. + +### Event Envelope + +Packer events must be structured enough for adapters to preserve causality and user-facing meaning. + +At minimum, each event must carry fields equivalent to: + +- `project_id` or workspace identity +- `operation_id` +- `sequence` +- `kind` +- `timestamp` +- `summary` +- `progress` when applicable +- `affected_assets` when applicable + +Rules: + +- `operation_id` is stable for the full lifecycle of one logical operation; +- `sequence` is monotonic within one operation; +- adapters may remap event shapes for UI consumption, but must not invent causal relationships not present in packer events. + +### Event Ordering and Coalescing + +Rules: + +- events emitted for one operation must be observable in causal order; +- repeated progress updates may be coalesced by adapters or sinks; +- lifecycle boundaries such as preview-ready, apply-success, apply-failure, build-started, and build-finished must remain individually observable; +- low-value repeated observation events must not drown out actionable failures or terminal state. ## Incremental and Watch Integration