clean up
This commit is contained in:
-130
@@ -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.
|
||||
-175
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user