This commit is contained in:
2026-03-24 13:42:57 +00:00
parent d16a987949
commit 0e5e1669c2
98 changed files with 824 additions and 8449 deletions
@@ -1,130 +0,0 @@
# 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.
@@ -1,175 +0,0 @@
# Filesystem-First Operational Runtime and Reconcile Boundary Decision
Status: Accepted
Date: 2026-03-15
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Context
The current packer model already has the right core separation:
- `assets/.prometeu/index.json` is the authoritative registry/catalog for managed assets;
- each asset root is anchored by `asset.json`;
- `asset.json` is the authoring-side declaration of how that asset is packed;
- Studio is meant to consume packer-owned operational semantics instead of recreating them locally.
What is still missing is a clear architectural decision for how the packer should behave operationally at runtime.
The repository now needs an answer to these questions:
1. should the packer remain a collection of direct filesystem services, recomputing state per request;
2. should the packer become a pure database-style system that displaces the open filesystem workflow;
3. or should it become a filesystem-first operational runtime that maintains an in-memory snapshot while preserving the workspace as the durable authoring surface.
The wrong answer here would create product friction.
If the packer behaves like a pure database, it will fight the real creative workflow where developers:
- edit files with their preferred tools;
- move directories manually when needed;
- inspect and version workspace files directly;
- expect the Studio to help organize work, not imprison it.
At the same time, if the packer stays purely filesystem-per-call, it will remain too expensive, too incoherent under concurrent use, and too weak as the operational source of truth for Studio.
## Decision
The following direction is adopted:
1. `prometeu-packer` remains `filesystem-first`.
2. The packer becomes a `project-scoped operational runtime`, not a pure database.
3. The packer maintains an in-memory project snapshot for live operational reads and write coordination.
4. The durable authoring workspace on disk remains the final persisted source of truth.
5. The packer owns request/response read and write APIs over that runtime snapshot.
6. Writes execute through a packer-owned project write lane and become durably visible only after commit succeeds.
7. The packer will support background divergence detection between runtime snapshot and filesystem state.
8. Divergence detection must surface reconcile state explicitly; it must not silently invent or hide semantic repairs.
9. Studio remains a frontend consumer of packer responses, commands, and events.
10. When embedded inside Studio, the packer runtime is bootstrapped with a typed event bus reference supplied by the Studio bootstrap container.
## Adopted Constraints
### 1. Filesystem-First Authority
- the asset workspace under `assets/` remains the authoring environment;
- `asset.json` remains the asset-local declaration contract;
- `assets/.prometeu/index.json` remains the authoritative registry/catalog for managed assets;
- the packer runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring format.
### 2. Identity and Declaration Split
- `asset_id`, `included_in_build`, and registry-managed location tracking remain registry/catalog concerns;
- `asset.json` remains primarily a declaration of the asset contract and packing inputs/outputs;
- `asset.json` may carry the asset-local identity anchor needed for reconcile, specifically `asset_uuid`;
- `asset.json` must not become a dumping ground for transient UI state, cache state, or catalog-derived bookkeeping that belongs in `index.json` or other packer-owned control files.
### 3. Snapshot-Backed Read Semantics
- normal read APIs should serve from a coherent in-memory project snapshot;
- the packer must not require a full workspace recomputation for every normal read call once the runtime is active;
- concurrent reads may proceed when they observe a coherent snapshot generation;
- reads must not expose torn intermediate write state as committed truth.
### 4. Packer-Owned Write Execution
- write operations on one project are coordinated by the packer, not by caller timing;
- the baseline policy remains a single-writer semantic lane per project;
- write intent may compute previews before final commit when safe;
- final apply/commit remains serialized per project;
- successful durable commit defines post-write visibility.
### 5. Durable Commit Boundary
- the packer runtime may stage write changes in memory before disk commit;
- partially applied intermediate state must not be presented as durably committed truth;
- commit failure must leave the project in an explicitly diagnosable condition;
- recovery and reconcile rules must be designed as packer behavior, not delegated to Studio guesswork.
### 6. Divergence Detection and Reconcile
- a future packer-owned background observation path may detect divergence between runtime snapshot and filesystem state;
- this path exists to keep the runtime honest with respect to manual or external edits;
- divergence must result in explicit runtime state such as stale, diverged, reconciling, or failed;
- the packer must not silently rewrite user content just because divergence was observed;
- reconcile is an explicit packer-owned behavior and must preserve causality in events and responses.
### 7. Studio Consumer Boundary
- Studio consumes packer read responses, write outcomes, and packer-native lifecycle events;
- Studio may render stale/diverged/reconciling states, but must not invent packer-side reconcile semantics;
- Studio must not become the owner of filesystem-vs-snapshot conflict resolution;
- the Studio integration contract should remain command-oriented and event-driven.
### 8. Embedded Event Bus Bootstrap
- when the packer is embedded inside Studio, it must receive a typed event bus reference during bootstrap instead of creating an unrelated local event system;
- that reference is used for packer event publication and any packer-side subscription/unsubscription behavior needed by the embedded runtime;
- in Studio, the owner of that typed event bus reference is the application container;
- the Studio `Container` must be initialized as part of Studio boot before packer-backed workspaces or adapters start consuming packer services.
## Why This Direction Was Chosen
- It preserves the developer's open creative workflow around normal files and directories.
- It keeps the packer useful as an organizing and coordinating system instead of turning it into an opaque silo.
- It allows fast and coherent reads for Studio and tooling.
- It gives write coordination, commit visibility, and operational causality one owner.
- It creates a realistic path toward future background divergence detection without pretending that the filesystem stopped mattering.
## Explicit Non-Decisions
This decision does not define:
- the final class/module names of the packer runtime implementation;
- the final executor/thread primitive used internally;
- the exact event vocabulary for all future reconcile states;
- the final automatic-vs-manual reconcile policy for each drift scenario;
- a watch-service or daemon transport implementation;
- remote or multi-process synchronization;
- a pure database persistence model.
## Implications
- the packer runtime track must preserve `index.json` plus `asset.json` as the durable workspace artifacts;
- `asset.json` should evolve carefully to support local identity anchoring without absorbing catalog-only fields;
- the runtime snapshot should be described as an operational cache/projection with authority for live service behavior, not as a new authoring truth;
- mutation, doctor, build, and read services should converge on the same runtime state model;
- future drift detection work must be designed together with diagnostics, refresh, and reconcile surfaces in Studio.
- embedded Studio wiring must preserve one container-owned typed event bus reference instead of fragmented packer-local bus ownership.
## Propagation Targets
Specs:
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
Plans:
- [`../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md)
Cross-domain references:
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
Implementation surfaces:
- future packer project-runtime/bootstrap code
- snapshot-backed read services
- project write-lane and durable commit pipeline
- drift detection and reconcile state reporting
- Studio packer adapters for stale/diverged/reconciling operational states
- Studio bootstrap/container wiring for the shared typed event bus reference
## Validation Notes
This decision is correctly implemented only when all of the following are true:
- developers may continue to inspect and edit asset workspace files directly;
- packer reads are coherent without requiring full recomputation on each normal request;
- same-project writes remain serialized by the packer;
- Studio does not observe torn committed truth during write activity;
- divergence between runtime snapshot and filesystem state can be detected and surfaced explicitly;
- Studio remains a consumer of packer-owned reconcile and lifecycle semantics rather than inventing them.
@@ -1,146 +0,0 @@
# Metadata Convergence to AssetEntry.metadata Decision
Status: Accepted
Date: 2026-03-17
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/vm-arch`, runtime asset consumers
## Context
The packer asset contract currently has multiple metadata-producing sources with different responsibilities:
- asset-level runtime contract metadata (authoring declaration);
- codec-related metadata (codec configuration/effective codec parameters);
- pipeline-derived metadata generated during build materialization (for example, indexed ranges for packed samples).
At runtime, consumers read one metadata sink from the asset table: `AssetEntry.metadata`.
Without an explicit decision, the system risks inconsistent behavior and documentation drift:
- metadata spread across sources without deterministic merge semantics;
- ambiguity between storage-layout fields (`AssetEntry.offset`/`AssetEntry.size`) and pipeline-internal indexing data (`offset`/`length` per sample);
- Studio, packer, and runtime docs diverging on where runtime consumers should read final values.
## Decision
The following direction is adopted:
1. All runtime-consumable metadata must converge to a single sink: `AssetEntry.metadata`.
2. Source segmentation in `asset.json` is allowed for authoring clarity, but build materialization must normalize these sources into that single sink.
3. Metadata normalization must be deterministic and testable.
4. `AssetEntry.offset` and `AssetEntry.size` remain payload slicing fields and are not reinterpreted as pipeline-internal indexing metadata.
5. Pipeline indexing metadata (for example, audio per-`sample_id` ranges) must live inside `AssetEntry.metadata` under explicit keys.
## Adopted Constraints
### 1. Source Segmentation vs Runtime Sink
- authoring sources may remain segmented (asset metadata, codec metadata, pipeline metadata);
- runtime consumers must read effective values from `AssetEntry.metadata`;
- packer build output is responsible for normalization.
### 2. Deterministic Convergence
- normalization must produce the same `AssetEntry.metadata` for the same effective declaration and build inputs;
- metadata key collisions between independent sources must be rejected with a build-time error unless explicitly specified by family/format contract;
- normalization order and collision policy must be documented by packer specs.
### 3. Audio Indexing Semantics
For multi-sample audio banks, sample indexing metadata belongs to `AssetEntry.metadata`, keyed by `sample_id`.
Illustrative shape:
```json
{
"metadata": {
"sample_rate": 22050,
"channels": 1,
"samples": {
"1": { "offset": 0, "length": 100 }
},
"codec": {
"parity": 10
}
}
}
```
This decision accepts either nested codec metadata (for example `metadata.codec.*`) or a flat equivalent only when the family/format spec declares that shape explicitly.
### 4. Offset Ambiguity Guardrail
- `AssetEntry.offset`/`AssetEntry.size` describe where one packed asset payload is stored in `assets.pa`;
- `metadata.samples[*].offset`/`metadata.samples[*].length` describe internal layout/indexing inside that asset's runtime payload contract;
- documentation and tests must keep these meanings separate.
## Why This Direction Was Chosen
- It keeps runtime consumption simple: one metadata sink.
- It preserves authoring ergonomics: source metadata can stay segmented by concern.
- It avoids semantic duplication between packer and runtime consumers.
- It creates a clear path for bank-like assets (tiles/audio) that require indexed internal metadata.
## Explicit Non-Decisions
This decision does not define:
- the final complete metadata schema for every asset family;
- the final canonical codec metadata shape (`nested` vs `flat`) for all formats;
- multi-sample audio runtime loading implementation details;
- exact binary container/header layout for audio banks.
## Implications
- packer specs must define normalization semantics and collision policy;
- packer build/materialization must emit normalized metadata into `AssetEntry.metadata`;
- runtime-facing docs must state that effective metadata is read from `AssetEntry.metadata`;
- tests must cover convergence correctness and ambiguity boundaries for offset semantics.
## Propagation Targets
Specs:
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- [`../../vm-arch/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md)
Plans:
- next packer PR/plan that introduces metadata normalization and multi-source merge validation
Code:
- packer asset declaration/materialization pipeline
- asset table emission path (`AssetEntry.metadata` payload)
Tests:
- normalization unit tests (source merge determinism)
- collision/ambiguity tests for offset semantics
- regression tests for runtime-readable metadata shape
Docs:
- packer specs and learn artifacts covering metadata source-to-sink flow
- runtime asset-management documentation referencing `AssetEntry.metadata` as sink
## References
Related specs:
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
Related agendas:
- no formal agenda artifact yet for this specific topic; this decision consolidates current packer/runtime alignment discussion.
## Validation Notes
This decision is correctly implemented only when all of the following are true:
- runtime consumers can read final effective metadata exclusively from `AssetEntry.metadata`;
- segmented metadata sources in authoring inputs converge deterministically during packing;
- offset semantics remain unambiguous between asset-table payload slicing and pipeline-internal indexing;
- documentation across packer and runtime-facing domains is consistent about this source-to-sink contract.
@@ -1,218 +0,0 @@
# Pack Wizard Pack Execution Semantics Decision
Status: Accepted
Date: 2026-03-20
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Context
The Studio-side `Pack Wizard` flow is already closed as a shell over packer-owned operations.
On the packer side, the repository also already closed the first-wave `summary` and `validation` contracts.
What remained open was the execution contract for the actual pack operation:
- how `packWorkspace(...)` should behave when Studio enters `Packing` and `Result`;
- how the packer should avoid filesystem drift while packing;
- how final artifact visibility should be protected during emission;
- and how the operation should report success, blocking failure, and execution failure without pushing semantic reconstruction into Studio.
The agenda that closed this discussion is:
- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
Relevant upstream references are:
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.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)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
## Decision
The first-wave packer execution contract for the `Pack Wizard` adopts the following direction:
1. `packWorkspace(...)` is one packer-owned public operation.
2. It executes through the project-scoped serialized write lane.
3. It must rerun a packer-owned gate check before artifact emission begins.
4. It must pack from one frozen execution snapshot rather than from live filesystem rereads.
5. It must stage emitted outputs before promotion to final `build/` locations.
6. It publishes final build artifacts to `build/` only after a coherent success point is reached.
7. It remains the only first-wave operation that emits build artifacts for the Studio `Pack Wizard`.
## Adopted Constraints
### 1. Execution Boundary
- `packWorkspace(...)` evaluates the active pack set as `registered + included in build`;
- it runs under the same packer-owned project write serialization model already adopted for same-project writes and build operations;
- it must not trust Studio call ordering as if that were a correctness guarantee;
- a failing pack gate returns a terminal result without publishing final build artifacts.
### 2. Frozen Execution Snapshot
- pack execution must not reread live workspace files once execution materialization begins;
- the packer must create a frozen pack-execution snapshot before payload materialization starts;
- that frozen snapshot is derived from the current runtime snapshot and packer-owned walk/materialization path;
- file content bytes are required only for build-relevant inputs:
- registered assets included in build;
- artifact files that actually participate in the current build output;
- non-build assets and non-selected artifact files do not need in-memory content in the pack-execution snapshot.
### 3. Runtime Walk Projection Shape
- the existing runtime walk projection model remains the baseline;
- `PackerRuntimeWalkFile` gains optional content bytes instead of introducing a second snapshot model in the first wave;
- optional content bytes remain absent in normal runtime-backed projection and become present only in packing-focused projection.
### 4. Materialization Policy Shape
The adopted first-wave shape is:
```java
public record PackerRuntimeMaterializationConfig(
PackerWalkMode mode,
Predicate<PackerProbeResult> projectionFilter) {
public static PackerRuntimeMaterializationConfig runtimeDefault() {
return new PackerRuntimeMaterializationConfig(PackerWalkMode.RUNTIME, probe -> true);
}
public static PackerRuntimeMaterializationConfig packingBuild() {
return new PackerRuntimeMaterializationConfig(
PackerWalkMode.PACKING,
PackerProbePolicies::isIncludedInCurrentBuild);
}
}
```
With this contract:
- `PackerWalkMode.RUNTIME` suppresses optional content bytes during export to runtime walk projection;
- `PackerWalkMode.PACKING` injects optional content bytes during export to runtime walk projection;
- `projectionFilter` decides which discovered probe results survive into `PackerRuntimeWalkFile`;
- the first-wave packing filter keeps only current-build probe results.
### 5. Walker Boundary
- family walkers remain family-oriented discovery mechanisms;
- they may continue to produce full file probes with bytes available during probe processing;
- the runtime-versus-packing variation happens during export/materialization into runtime walk projection;
- packing-specific selection is one additional projection/materialization policy layer over the discovered probe results;
- first-wave pack execution must not fork the repository into one discovery model for runtime and another discovery model for packing.
### 6. Staging and Promotion Boundary
- pack execution stages outputs under `build/.staging/<operation-id>/`;
- `<operation-id>` is one random 20-character alphanumeric identifier;
- if a staging directory collision occurs for that identifier, the packer may overwrite that staging directory in the first wave;
- staged outputs are non-authoritative until promotion;
- promotion into final `build/` locations happens only after the operation reaches a coherent success point;
- if emission fails before promotion, final `build/` outputs must remain unchanged from the caller's point of view.
### 7. Build Publication Boundary
- the canonical runtime-facing output is `build/assets.pa`;
- the baseline companion outputs are:
- `build/asset_table.json`
- `build/preload.json`
- `build/asset_table_metadata.json`
- `packWorkspace(...)` stops at build artifact publication;
- shipper behavior remains outside this operation and is mentioned only as a future consumer boundary.
### 8. Result and Failure Semantics
The final pack result must distinguish at least:
1. validation gate failure before emission;
2. execution or materialization failure during pack generation;
3. persistence or promotion failure while making outputs final.
The first-wave result summary must expose at least:
- final status;
- whether execution actually began or stopped at gate failure;
- canonical build-relative reference to `assets.pa`;
- build-relative companion artifact references when emitted;
- total packed asset count;
- elapsed time in milliseconds.
### 9. Minimum Structural Conformance
The first-wave pack execution is not successful unless the emitted outputs satisfy the already adopted baseline structural guarantees:
- `asset_table` ordering is deterministic by increasing `asset_id`;
- header serialization is canonical;
- offsets are relative to `payload_offset`;
- preload entries are resolved by `asset_id`;
- invalid preload references or preload slot clashes fail the operation rather than being deferred to host guesswork.
## Why This Direction Was Chosen
- It preserves packer ownership of build semantics while keeping Studio as an honest shell.
- It prevents filesystem drift during execution without turning the general runtime snapshot into a wasteful full-memory mirror.
- It aligns build visibility with the same commit-oriented operational model already adopted elsewhere in the packer runtime.
- It keeps the first-wave implementation on known terrain by reusing current walker/materialization structure instead of inventing a second discovery stack.
- It gives the Studio enough structured outcome information to render `Packing` and `Result` without semantic reconstruction.
## Explicit Non-Decisions
This decision does not yet define:
- the format-specific payload materialization rules for each asset output format;
- the canonical payload contract for `tile bank`, `sound bank`, or other family-specific outputs;
- the final event kind vocabulary for pack execution progress beyond requiring causality-preserving observable lifecycle;
- cancellation semantics;
- future incremental or remote build behavior;
- shipper packaging rules, cartridge manifest generation, or final packaged cartridge layout.
## Implications
- `packWorkspace(...)` can no longer be implemented as a direct live-filesystem read/write shortcut;
- runtime walk projection and materialization code must gain explicit packing-aware export policy;
- `PackerRuntimeWalkFile` must support optional content bytes;
- pack execution implementation must include frozen-input creation, staging, promotion, and structured terminal outcomes;
- format-specific packing discussions must now happen as follow-up decisions rather than being guessed inside the generic execution path.
## Propagation Targets
Specs:
- [`../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)
Plans:
- [`../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
- [`../pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](../pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md)
- future packer PR for pack execution, staging, and result semantics
Cross-domain references:
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
- [`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
Follow-up agenda references:
- [`../agendas/Tile Bank Packing Materialization Agenda.md`](../agendas/Tile%20Bank%20Packing%20Materialization%20Agenda.md)
Implementation surfaces:
- `prometeu-packer-api` pack execution result contract
- `prometeu-packer-v1` runtime materialization/export policy
- `prometeu-packer-v1` frozen execution snapshot creation
- `prometeu-packer-v1` staging and promote pipeline
- Studio `Pack Wizard` packing/result bindings
## Validation Notes
This decision is correctly implemented only when all of the following are true:
- `packWorkspace(...)` does not depend on live filesystem rereads after frozen execution materialization begins;
- only build-relevant selected inputs carry frozen content bytes into the packing path;
- normal runtime-backed reads do not retain optional content bytes by default;
- failed execution before promotion does not leave partial final `build/` artifacts presented as success;
- successful pack publication produces `build/assets.pa` and the expected companion outputs coherently;
- Studio can distinguish blocked, failed, and successful pack outcomes from packer-owned results alone.
@@ -1,174 +0,0 @@
# Pack Wizard Summary and Validation Contracts Decision
Status: Accepted
Date: 2026-03-20
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Context
The Studio `Pack Wizard` flow is now closed on the host side as a shell over packer-owned operations.
That decision already fixed the outer boundary:
- Studio is the shell;
- packer owns summary, validation, pack execution, progress, and result semantics;
- the wizard flow is phase-based;
- the active pack set is the current `registered + included in build` set.
On the packer side, the first remaining need is to close the public contract for `summary` and `validation` before the repository moves deeper into pack execution semantics.
This decision consolidates the `summary` and `validation` part of the packer-side discussion from:
- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
The main question is not whether Studio should have these phases.
That is already settled.
The question is what the packer must expose as the authoritative public contract for those phases.
## Decision
The packer public contract for the `Pack Wizard` first wave adopts the following direction:
1. `summary` and `validation` are distinct packer operations;
2. both operations are read-only and non-mutating;
3. both operations evaluate the same pack set:
`registered + included in build`;
4. both operations are packer-owned and snapshot-backed;
5. Studio consumes these packer responses and must not reconstruct equivalent semantics locally.
## Adopted Constraints
### 1. Summary Boundary
- `summary` is a fast snapshot-backed preflight view;
- `summary` must return from packer-owned snapshot state, not from a deep recomputation pass;
- `summary` is not a build preview and must not imply that artifacts were emitted;
- `summary` must not anticipate companion artifacts or emitted artifact details in the first wave;
- `summary` must not include unregistered assets or excluded assets as explicit summary items.
### 2. Summary Shape
The first-wave `summary` contract contains:
1. one aggregate count for the active pack set;
2. one per-asset list for the active pack set.
The aggregate is intentionally minimal in the first wave:
- total included asset count is sufficient.
Each per-asset summary entry must expose:
- `assetId`
- `assetName`
- `assetFamily`
- `minArtifactCount`
- `maxArtifactCount`
- `lastModified`
`lastModified` is required in the public contract even if early implementations temporarily expose `0` until the real value is fully available per asset.
The per-asset summary list is the intended payload for Studio-side graphical occupancy presentation.
The aggregate remains deliberately small.
### 3. Validation Boundary
- `validation` evaluates the same active pack set as `summary`;
- `validation` is read-only and non-mutating;
- `validation` is snapshot-backed;
- `validation` may internally reuse deep-inspection or reconcile-grade logic where needed;
- a future Studio flow may add an explicit deep-sync step before validation, but validation itself still evaluates the packer snapshot boundary.
### 4. Validation Failure Rule
Only diagnostics marked `blocking` fail validation in the first wave.
The rule is:
- if no blocking diagnostics are returned for the active pack set, validation is green;
- if any blocking diagnostics are returned for the active pack set, validation is red and packing must not begin.
Warnings and non-blocking diagnostics are not part of the first-wave validation gate contract.
### 5. Validation Shape
The primary validation payload is the per-asset diagnostics list.
Aggregate validation data may still exist, but it is secondary.
The Studio may derive aggregate visual summaries from the per-asset list if useful.
Each per-asset validation entry must expose:
- `assetId`
- `assetName`
- `assetPath`
- `lastModified`
- `diagnostics`
In the first wave, `diagnostics` in this contract means blocking diagnostics only.
Ordering is not a packer responsibility in the first-wave validation payload.
The Studio may sort the returned list as needed for presentation.
## Why This Direction Was Chosen
- It keeps `summary` and `validation` aligned with the existing request/result API style instead of inventing a special build-session protocol too early.
- It keeps ownership where it belongs: the packer remains the source of truth for pack-set semantics and validation outcomes.
- It gives Studio enough structured data to render the preflight and validation phases without recreating packer meaning.
- It keeps the first-wave contract intentionally narrow so the repository can close `summary` and `validation` without prematurely locking the heavier `pack execution` semantics.
- It gives the Studio enough per-asset detail to show useful occupancy and blocker views while keeping ordering and higher-level UI grouping on the host side.
## Explicit Non-Decisions
This decision does not yet define:
- the final `pack execution` request/result contract;
- emitted artifact reporting rules beyond what is already upstream in packer artifact specs;
- the final event vocabulary for pack progress;
- whether future validation payloads should include non-blocking diagnostics;
- the final source for real `lastModified` values in every asset case;
- runtime-ingestion and cartridge-facing conformance gates for actual artifact emission.
## Implications
- the current public API work for pack summary must expand beyond aggregate-only shape;
- the current public API work for validation must expand beyond generic aggregate-first DTOs;
- Studio `Pack Wizard` binding should evolve toward the per-asset summary and per-asset validation payloads defined here;
- `summary` and `validation` can now be implemented independently of the heavier pack execution discussion;
- the next packer discussion wave should focus primarily on execution semantics, artifact emission guarantees, and runtime/cartridge ingestion conformance.
## Propagation Targets
Specs:
- [`../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)
Plans:
- [`../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
Cross-domain references:
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
- [`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
Implementation surfaces:
- `prometeu-packer-api` summary and validation request/result DTOs
- snapshot-backed pack summary query logic
- snapshot-backed pack validation logic
- Studio pack wizard summary and validation bindings
## Validation Notes
This decision is correctly implemented only when all of the following are true:
- `summary` returns quickly from packer-owned snapshot state;
- Studio does not reconstruct pack summary from navigator rows or local UI state;
- `summary` returns only active pack-set items, not excluded or unregistered items;
- `validation` returns blocking-diagnostic information per asset for the same active pack set;
- a returned validation payload with any blocking diagnostics stops the wizard before pack execution;
- the Studio may reorder the returned lists without changing packer semantics.
+4 -9
View File
@@ -1,17 +1,12 @@
# Packer Decisions
This directory contains packer decision records.
This directory contains packer decision records that still need propagation.
Retained packer decision records:
Current retained set:
- [`Concurrency, Observability, and Studio Adapter Boundary Decision.md`](./Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md)
- [`Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](./Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md)
- [`Metadata Convergence to AssetEntry.metadata Decision.md`](./Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md)
- [`Pack Wizard Summary and Validation Contracts Decision.md`](./Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
- [`Pack Wizard Pack Execution Semantics Decision.md`](./Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
- [`Tile Bank Packing Materialization Decision.md`](./Tile%20Bank%20Packing%20Materialization%20Decision.md)
- none
The first packer decision wave was already consolidated into:
The current packer decision wave has already been consolidated into:
- normative specifications under [`../specs/`](../specs/)
- didactic material under [`../learn/`](../learn/)
@@ -1,211 +0,0 @@
# Tile Bank Packing Materialization Decision
Status: Accepted
Date: 2026-03-20
Domain Owner: `docs/packer`
Cross-Domain Impact: `../runtime`, `docs/studio`
## Context
The packer execution contract for `packWorkspace(...)` is already closed.
What remained open for `tile bank` was the format-specific producer contract:
- which selected files become part of the packed asset;
- how those files become the canonical `TILES/indexed_v1` payload;
- how `AssetEntry` fields are derived for runtime consumption;
- how bank palettes are declared and normalized;
- which diagnostics block the build for this format.
The agenda that closed this discussion is:
- [`../agendas/Tile Bank Packing Materialization Agenda.md`](../agendas/Tile%20Bank%20Packing%20Materialization%20Agenda.md)
Relevant upstream references are:
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- [`../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md`](../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md)
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
- [`../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md`](../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md)
## Decision
The first-wave packer materialization contract for `tile bank` adopts the following direction:
1. `TILES/indexed_v1` emits one canonical payload per asset.
2. `1 artifact = 1 tile` in the first wave.
3. Artifacts are ordered by normalized `artifacts[*].index`.
4. Tile placement is row-major in one fixed `256 x 256` sheet.
5. `tile_id` is the linear row-major slot and therefore matches the normalized artifact index.
6. Tile pixels are serialized as packed `u4` indices.
7. Bank palettes are serialized as `RGB565` `u16` values.
8. Palette declarations use explicit semantic identity through `{ index, palette }`.
9. `AssetEntry.metadata` keeps required runtime fields readable at the root while preserving segmented codec and pipeline subtrees.
10. Format-structural diagnostics are raised in the walker/materialization path and therefore participate in validation before pack execution reruns the gate.
## Adopted Constraints
### 1. Canonical Payload Shape
- the payload is produced from build-selected artifacts only;
- the payload is the canonical bank sheet raster, not a concatenation of per-artifact binary fragments;
- for `TILES/indexed_v1`, the serialized payload shape is:
1. packed `u4` pixel indices for the full emitted sheet;
2. one palette block of `64 * 16 * 2` bytes;
- palettes are always materialized to `RGB565` during pack emission;
- the producer-side payload contract is aligned to what the runtime loader already requires.
### 2. Artifact-to-Tile Contract
- `1 artifact = 1 tile` in v1;
- artifacts are normalized by `artifacts[*].index`;
- `tile_id = artifacts[*].index` after normalization;
- the canonical emitted sheet is always `256 x 256`;
- placement is row-major within that fixed sheet.
Resulting tile capacities:
- `tile_size = 8` -> `32 x 32 = 1024` tiles
- `tile_size = 16` -> `16 x 16 = 256` tiles
- `tile_size = 32` -> `8 x 8 = 64` tiles
### 3. Runtime Entry Contract
Each emitted `tile bank` runtime entry must populate:
- `asset_id`
- `asset_name`
- `bank_type = TILES`
- `offset`
- `size`
- `decoded_size`
- `codec = NONE`
- `metadata`
For v1:
- `size = ceil(width * height / 2) + 2048`
- `decoded_size = (width * height) + 2048`
- `width = 256`
- `height = 256`
- `palette_count = 64`
### 4. Palette Contract
- bank palettes are declared in `asset.json.output.pipeline.palettes`;
- each palette declaration must use explicit shape `{ index, palette }`;
- semantic ordering is ascending numeric `index`, never raw array position;
- palette ids are the normalized declared `index` values;
- any tile in the bank may be rendered with any palette in the bank;
- palette choice is a runtime draw-time concern and is not embedded per tile in the packed payload.
### 5. Metadata Normalization Contract
`AssetEntry.metadata` keeps runtime-required fields readable while preserving authoring segmentation:
- `asset.json.output.metadata` -> `AssetEntry.metadata`
- `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec`
- `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline`
For tile-bank v1 this means:
- `tile_size`, `width`, `height`, and `palette_count` remain directly readable at the metadata root;
- codec-specific data is nested under `metadata.codec`;
- pipeline-derived data is nested under `metadata.pipeline`.
This packer decision intentionally aligns with the runtime-side follow-up agenda rather than flattening everything into one ambiguous map.
### 6. Diagnostics and Failure Semantics
The following conditions are blocking for tile-bank v1:
- duplicate `artifacts[*].index`
- gaps in normalized `artifacts[*].index`
- fixed-sheet capacity overflow
- bank without declared palettes
- palette declaration count above `64`
- malformed palette declarations
- missing or invalid required format metadata
- any failure to normalize artifacts into one deterministic payload
The following condition is warning-only in the first wave:
- fragile tile indices, meaning tile indices that are not safely represented across the full declared bank palette set
### 7. Walker and Validation Boundary
- family walkers remain discovery-oriented;
- tile-bank structural diagnostics must be produced in the walker/materialization path;
- validation consumes those diagnostics naturally;
- pack execution reruns the validation gate on a newly created frozen execution snapshot before materialization begins.
## Why This Direction Was Chosen
- It matches the runtime consumer contract instead of inventing a producer-local interpretation.
- It keeps `tile bank` payload semantics explicit and deterministic.
- It avoids embedding per-artifact or per-draw palette assignment into the packed bytes.
- It preserves stable palette identity through explicit `index` declarations.
- It keeps validation early without weakening the pack-time rerun gate.
- It gives the runtime a metadata shape that is readable and still semantically segmented.
## Explicit Non-Decisions
This decision does not yet define:
- future support for `1 artifact -> many tiles`;
- non-`256 x 256` tile-bank targets;
- alternative tile-bank codecs beyond `NONE`;
- future palette compaction or palette-id remapping strategies;
- the runtime-side final decision for general `AssetEntry.metadata` normalization helpers;
- future sprite or tilemap semantic adjustments unrelated to packer-owned payload production.
## Implications
- tile-bank packing implementation must materialize a full sheet raster rather than artifact fragments;
- tile-bank payload generation must pack `u4` indices explicitly in the packer;
- palette declarations and palette overhauling flows must preserve explicit palette `index`;
- runtime-entry metadata emission must preserve both root-required fields and segmented nested maps;
- tile-bank validation logic belongs in the walker/materialization path and must be reused by pack execution gate reruns.
## Propagation Targets
Specs:
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
Plans:
- [`../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md`](../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md)
- future packer PR for tile-bank payload materialization
- future packer PR for tile-bank validation diagnostics
Cross-domain references:
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
- [`../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md`](../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md)
- [`../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md`](../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md)
Implementation surfaces:
- `prometeu-packer-v1` tile-bank payload materializer
- `prometeu-packer-v1` tile-bank diagnostics in walker/materialization path
- `prometeu-packer-v1` metadata convergence for `AssetEntry`
- Studio tile-bank authoring and inspection surfaces that expose palettes or bank composition
## Validation Notes
This decision is correctly implemented only when all of the following are true:
- artifact normalization produces one deterministic row-major `256 x 256` bank sheet;
- emitted tile ids match normalized artifact indices;
- emitted pixel bytes are packed as `u4`;
- emitted palette bytes are `RGB565` `u16`;
- palette declarations are read and written by explicit `index`;
- runtime-required metadata fields remain readable at the root;
- codec and pipeline metadata survive under `metadata.codec` and `metadata.pipeline`;
- structural blockers are visible during validation and are rerun by pack execution before emission.