added packer PRs
This commit is contained in:
parent
edf3e6d3ec
commit
839c7d244f
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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.
|
||||||
@ -2,7 +2,9 @@
|
|||||||
|
|
||||||
This directory contains packer decision records.
|
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:
|
The first packer decision wave was already consolidated into:
|
||||||
|
|
||||||
|
|||||||
@ -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
|
||||||
@ -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
|
||||||
@ -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
|
||||||
@ -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
|
## Review Rule
|
||||||
|
|
||||||
A pull request may plan code and spec consequences, but it must not replace a missing decision record.
|
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`
|
||||||
|
|||||||
@ -66,6 +66,24 @@ Operations must distinguish:
|
|||||||
|
|
||||||
This distinction is part of the service semantics and must be visible to the UI.
|
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
|
## Preview/Apply Model
|
||||||
|
|
||||||
Sensitive mutations use staged intent.
|
Sensitive mutations use staged intent.
|
||||||
@ -126,6 +144,40 @@ Rules:
|
|||||||
- background observation and reporting may be continuous;
|
- background observation and reporting may be continuous;
|
||||||
- conflicting sensitive mutations must not race arbitrarily;
|
- conflicting sensitive mutations must not race arbitrarily;
|
||||||
- observable mutation behavior remains coherent from the UI perspective.
|
- 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
|
## Incremental and Watch Integration
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user