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
+5 -1
View File
@@ -52,4 +52,8 @@ Start here:
1. [`mental-model-packer.md`](./mental-model-packer.md)
2. [`mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
3. [`mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)
3. [`foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md)
4. [`runtime-ownership-and-studio-boundary.md`](./runtime-ownership-and-studio-boundary.md)
5. [`mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)
6. [`pack-wizard-summary-validation-and-pack-execution.md`](./pack-wizard-summary-validation-and-pack-execution.md)
7. [`tile-bank-packing-contract.md`](./tile-bank-packing-contract.md)
@@ -0,0 +1,91 @@
# Foundations: Workspace, Runtime, and Build
## Original Problem
The packer domain accumulated a long implementation wave covering workspace control, asset identity, scanning, mutations, diagnostics, deterministic planning, runtime snapshots, and cache reuse.
The historical PR chain was useful while the repository was converging, but it stopped being a good onboarding surface:
- too much knowledge was spread across execution slices;
- too much reasoning depended on chronological reconstruction;
- too little of that knowledge was available as one stable mental model.
## Consolidated Decision
The stable packer foundation is:
1. the workspace stays open and filesystem-first;
2. `assets/.prometeu/index.json` owns managed identity and inclusion state;
3. each asset root is anchored by `asset.json`;
4. the packer runtime serves coherent snapshot-backed reads;
5. writes are coordinated by the packer and become visible after durable commit;
6. build outputs are derived deterministically from validated, packer-owned state.
## Final Model
### 1. Workspace and Identity
- `asset_id` is the stable managed identifier used for ordering, inclusion, and runtime-facing tables;
- `asset_uuid` is the local identity anchor that helps reconcile the same logical asset across path movement;
- `asset_name` is the logical human-facing identifier and is not a substitute for managed identity;
- `asset.json` describes authoring intent, not registry-owned bookkeeping.
### 2. Read and Write Authority
- normal reads come from a coherent runtime snapshot rather than from ad hoc filesystem scans;
- the filesystem still matters because it remains the durable authoring surface;
- writes flow through packer-owned preview/apply semantics and one project-scoped serialized lane.
### 3. Deterministic Build Path
- only validated managed assets enter the build path;
- asset ordering is deterministic by increasing `asset_id`;
- runtime-facing artifacts are emitted from canonical packer-owned planning and materialization rules;
- companion artifacts mirror build authority rather than define parallel truth.
### 4. Runtime Snapshot Evolution
The later runtime wave refined the first foundation:
- runtime state became explicitly project-scoped;
- snapshot updates happen after successful write commit;
- query services read from that runtime state;
- cache layers exist to accelerate the same ownership model, not to bypass it.
## Examples
### Example: Why relocation does not create a new asset
If an asset root moves on disk, the packer should preserve the managed identity when the move is a relocation of the same logical asset.
That is why:
- the registry owns stable managed identity;
- path is mutable operational state;
- relocation updates root tracking without inventing a new `asset_id`.
### Example: Why filesystem order cannot define build order
Two equivalent workspaces may be traversed in different directory order.
The build must still emit the same `asset_table` and payload layout.
That is why deterministic ordering is tied to managed identity, not traversal order.
## Common Pitfalls and Anti-Patterns
- Treating `asset_name` as if it were a stable runtime identifier.
- Moving registry-owned fields into `asset.json`.
- Recomputing semantic read models directly from Studio-side filesystem heuristics.
- Letting build order depend on traversal order, cache insertion order, or UI ordering.
- Treating cache state as semantic authority instead of as an optimization.
## References
- Specs:
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../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)
- Related learn:
- [`./mental-model-packer.md`](./mental-model-packer.md)
- [`./mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
@@ -24,10 +24,6 @@ The accepted direction is:
4. collisions require explicit contract rules or must fail build;
5. `AssetEntry.offset`/`AssetEntry.size` keep payload slicing semantics and do not replace internal pipeline indexing.
Decision reference:
- [`../decisions/Metadata Convergence to AssetEntry.metadata Decision.md`](../decisions/Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md)
## Final Model
Think in two layers:
@@ -77,6 +73,6 @@ In this model:
## References
- Decision: [`../decisions/Metadata Convergence to AssetEntry.metadata Decision.md`](../decisions/Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md)
- Spec: [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- Spec: [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- Spec: [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- Related learn: [`./tile-bank-packing-contract.md`](./tile-bank-packing-contract.md)
@@ -0,0 +1,118 @@
# Pack Wizard: Summary, Validation, and Pack Execution
## Original Problem
The Studio-side wizard was already accepted as a shell over packer-owned operations, but the packer side still needed one coherent story for:
1. what `summary` means;
2. what `validation` means;
3. how `packWorkspace(...)` executes without trusting stale UI state or live filesystem rereads.
The historical agenda, decisions, and PRs solved this in slices.
This document keeps the final model in one place.
## Consolidated Decision
The first-wave `Pack Wizard` contract is phase-based and fully packer-owned:
1. `summary` is a fast snapshot-backed preflight view;
2. `validation` is a snapshot-backed gate over the same active pack set;
3. `packWorkspace(...)` is the only artifact-emitting wizard operation;
4. execution reruns the gate on a fresh frozen snapshot;
5. outputs are staged before promotion into final `build/` locations.
The active pack set is always:
`registered + included in build`
## Final Model
### 1. Summary
`summary` is not a build preview.
It is a quick packer-owned view of the current active pack set.
First-wave payload:
- total included asset count;
- one per-asset list with:
- `assetId`
- `assetName`
- `assetFamily`
- `minArtifactCount`
- `maxArtifactCount`
- `lastModified`
### 2. Validation
`validation` evaluates the same pack set as `summary`, but its job is to answer a different question:
Can packing begin?
First-wave rule:
- only `blocking` diagnostics fail validation;
- warnings are visible elsewhere, but they are not part of the first validation gate contract.
Primary payload:
- one per-asset list containing only assets with blocking diagnostics.
### 3. Pack Execution
`packWorkspace(...)` is a write-lane operation.
It does not trust that earlier summary or validation responses are still current.
The first-wave execution path is:
1. create a fresh execution snapshot;
2. rerun the gate on that snapshot;
3. materialize outputs from frozen in-memory inputs;
4. write to `build/.staging/<operation-id>/`;
5. promote to final `build/` outputs only after coherent success.
### 4. Result Semantics
The final result must distinguish:
- gate failure before emission;
- execution/materialization failure;
- persistence/promotion failure;
- successful publication.
Studio should be able to render `Packing` and `Result` from packer-owned outcome semantics alone.
## Examples
### Example: Why green validation is not enough
Validation may have been green a few seconds earlier.
If the workspace changes before pack execution begins, the packer still must rerun the gate on a fresh frozen snapshot.
That protects the operation from:
- stale UI assumptions;
- filesystem drift;
- accidental emission from no-longer-valid inputs.
### Example: Why summary excludes unregistered assets
The wizard is a pack-set workflow, not a generic workspace inspection screen.
Unregistered or excluded assets may matter to other tooling, but they are not explicit summary items in the first-wave wizard contract.
## Common Pitfalls and Anti-Patterns
- Treating `summary` as if it were an emitted-artifact preview.
- Running validation over a broader set than `registered + included in build`.
- Letting non-blocking warnings fail the first-wave validation gate.
- Reading live filesystem bytes after frozen execution materialization has started.
- Publishing final `build/` outputs before the operation has reached a coherent success point.
## References
- 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)
- Cross-domain:
- [`../../studio/learn/pack-wizard-shell.md`](../../studio/learn/pack-wizard-shell.md)
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
@@ -0,0 +1,88 @@
# Runtime Ownership and Studio Boundary
## Original Problem
Once the packer stopped being just a set of direct filesystem helpers, the repository needed a clear answer for three things:
1. who owns operational asset semantics;
2. how concurrent reads and writes stay coherent;
3. how Studio consumes packer state without duplicating domain logic.
Without that boundary, the system would drift into split-brain behavior between packer services and Studio UI code.
## Consolidated Decision
The packer is the semantic owner of operational asset state.
Studio is a consumer of packer responses, commands, and events.
The stable boundary is:
- filesystem-first authoring workspace;
- project-scoped runtime snapshot for reads;
- single-writer semantic lane per project for commit-bearing operations;
- packer-native observability with causal ordering;
- Studio adapters that translate for presentation but do not invent semantics.
## Final Model
### 1. Filesystem-First Runtime
- the workspace on disk remains the durable source of truth;
- the runtime snapshot is an operational projection used for coherent reads and write coordination;
- divergence between runtime state and filesystem state must become explicit packer state, not silent repair.
### 2. Concurrency Model
- `read/read` may run concurrently when both observe one coherent snapshot;
- `read/write` must not expose torn intermediate state;
- `write/write` on the same project is serialized;
- build-bearing operations share the same project-scoped coordination story.
### 3. Event Ownership
- packer events are authoritative for lifecycle, progress, and outcomes;
- each logical operation carries stable causality through `operation_id` and monotonic `sequence`;
- sinks may coalesce noisy progress updates, but terminal lifecycle events remain observable.
### 4. Studio Adapter Rule
- Studio may remap packer data into workspace and shell view models;
- Studio must not recreate packer summaries, mutation semantics, or reconcile semantics from local heuristics;
- adapter code is translational, not semantic-authoritative.
## Examples
### Example: Mutation preview in Studio
The preview may be rendered in Studio-specific components, but the semantic meaning of:
- blockers,
- warnings,
- registry mutations,
- filesystem mutations,
- final apply outcome
must still come from the packer.
### Example: Activity and progress
If the UI shows a simplified progress bar or activity feed, that is fine.
What is not fine is for Studio to infer a successful final outcome without a packer-native terminal event or response.
## Common Pitfalls and Anti-Patterns
- Rebuilding packer summaries from navigator rows or local filesystem scans.
- Treating adapter code as a second owner of mutation or reconcile rules.
- Hiding divergence by silently refreshing state without surfacing the transition.
- Allowing same-project writes to race because the caller "already validated" earlier.
- Collapsing event causality into UI-local state that cannot be replayed or tested outside Studio.
## References
- Specs:
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- Cross-domain:
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
- Related learn:
- [`./foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md)
@@ -0,0 +1,116 @@
# Tile Bank Packing Contract
## Original Problem
After the generic pack execution boundary was closed, `tile bank` still lacked one explicit producer contract.
The repository needed to settle:
1. how selected tile artifacts become one packed payload;
2. how palette identity is declared and normalized;
3. which runtime fields are derived for `AssetEntry`;
4. which structural problems block packing before byte emission.
## Consolidated Decision
The first-wave `tile bank` producer contract is:
1. one canonical `TILES/indexed_v1` payload per asset;
2. `1 artifact = 1 tile`;
3. artifacts are normalized by explicit `artifacts[*].index`;
4. the emitted sheet is fixed at `256 x 256` and row-major;
5. tile pixels are packed `u4`;
6. bank palettes are emitted as `RGB565` `u16`;
7. palette declarations use explicit `{ index, palette }`;
8. structural diagnostics are produced early in walker/materialization and therefore participate in validation.
## Final Model
### 1. Payload Shape
The payload is not a concatenation of artifact-local binaries.
It is one canonical bank raster:
1. packed `u4` pixel indices for the full sheet;
2. one `64 * 16 * 2` palette block.
### 2. Artifact and Tile Identity
- artifacts are normalized by ascending declared `index`;
- `tile_id` matches the normalized artifact index;
- placement is row-major in the fixed sheet;
- v1 capacities depend on `tile_size`:
- `8 -> 1024`
- `16 -> 256`
- `32 -> 64`
### 3. Palette Contract
- palette identity is semantic, not positional;
- ordering is ascending numeric `index`, never raw list order;
- any tile may be rendered with any bank palette at runtime;
- palette selection is a draw-time concern, not an embedded per-tile payload field.
### 4. Metadata Contract
`AssetEntry.metadata` keeps runtime-required fields readable at the root while preserving segmented subtrees:
- `output.metadata -> metadata`
- `output.codec_configuration -> metadata.codec`
- `output.pipeline -> metadata.pipeline`
For tile banks, that means root readability for values such as:
- `tile_size`
- `width`
- `height`
- `palette_count`
### 5. Validation Boundary
Tile-bank structural issues belong in the walker/materialization path, not in a late pack-only surprise phase.
Blocking conditions include:
- duplicate artifact indices;
- gaps in normalized artifact indices;
- fixed-sheet overflow;
- missing palettes;
- palette count above `64`;
- malformed palette declarations;
- missing required metadata;
- normalization failure.
Fragile tile indices are warnings in the first wave, not blockers by themselves.
## Examples
### Example: Why palette index must be explicit
If palette identity depends on array position, a harmless editorial reorder can silently change runtime meaning.
Using `{ index, palette }` makes semantic identity reviewable and stable.
### Example: Why validation must see tile-bank structure early
If duplicate artifact indices are discovered only during final byte emission, the wizard reaches `Packing` too late.
The correct behavior is for validation to surface the blocker before emission begins, and for pack execution to rerun that same gate on a fresh execution snapshot.
## Common Pitfalls and Anti-Patterns
- Treating artifact declaration order as semantic tile identity.
- Packing per-artifact fragments instead of one canonical sheet.
- Embedding palette choice per tile in the packed payload.
- Flattening all metadata into one ambiguous map.
- Discovering tile-bank blockers only during late byte emission.
## References
- 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)
- Cross-domain:
- [`../../../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)
- Related learn:
- [`./mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)