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