implements PLN-0040 scene glyph spec and wire layout

This commit is contained in:
2026-04-24 10:57:48 +01:00
parent c52f196b7a
commit 26686c288c
6 changed files with 91 additions and 13 deletions
+13 -1
View File
@@ -579,7 +579,7 @@ Fault boundary:
| `gfx.draw_square` | `void` | no real operational failure path in v1 |
| `gfx.draw_text` | `void` | no real operational failure path in v1 |
| `gfx.clear_565` | `void` | no real operational failure path in v1 |
| `composer.bind_scene` | `status:int` | explicit orchestration-domain operational result |
| `composer.bind_scene` | `status:int` | status-returning API, but missing scene glyph dependencies are fatal runtime errors |
| `composer.unbind_scene` | `status:int` | explicit orchestration-domain operational result |
| `composer.set_camera` | `void` | no real operational failure path in v1 |
| `composer.emit_sprite` | `status:int` | explicit orchestration-domain operational rejection |
@@ -596,6 +596,18 @@ The public `gfx.*` primitive family remains valid in v1, but its stable operatio
This means callers MUST NOT rely on stable immediate writes to the working back buffer as the public contract for `gfx.draw_text(...)` or sibling primitives.
### 19.1.b Scene dependency fatal boundary
`composer.bind_scene` remains a status-returning syscall in the public ABI, but scene glyph dependency absence is outside the accepted passive operational-error model.
Rules:
- the target scene slot may still be rejected through ordinary status-returning behavior when the scene itself is unavailable;
- missing glyph dependencies referenced by a resident scene are not a passive `status:int` case;
- if scene activation discovers that a layer dependency cannot be resolved to a committed glyph asset, the machine MUST fail fatally and emit a clear log;
- if scene composition later discovers that a layer dependency can no longer be resolved, the machine MUST fail fatally and emit a clear log;
- runtime MUST NOT continue canonical scene composition after such a dependency failure.
### 19.2 `composer.emit_sprite`
`composer.emit_sprite` returns `status:int`.
+64 -7
View File
@@ -108,9 +108,9 @@ This table describes content identity and storage layout, not live residency.
`codec` does not define the bank-specific serialized layout itself. Specialized banks may still have normative decode rules even when `codec = NONE`.
### 4.1 `TILES` asset contract in v1
### 4.1 `GLYPH` asset contract in v1
For `BankType::TILES`, the v1 runtime-facing contract is:
For `BankType::GLYPH`, the v1 runtime-facing contract is:
- `codec = NONE`
- serialized pixels use packed `u4` palette indices
@@ -118,20 +118,20 @@ For `BankType::TILES`, the v1 runtime-facing contract is:
- `palette_count = 64`
- runtime materialization may expand pixel indices to one `u8` per pixel
For `TILES`, `NONE` means there is no additional generic codec layer beyond the bank contract itself.
For `GLYPH`, `NONE` means there is no additional generic codec layer beyond the bank contract itself.
For the current transition window:
- `RAW` is a legacy deprecated alias of `NONE`
- newly published material must use `NONE` as the canonical value
Even with `codec = NONE`, `TILES` still requires bank-specific decode from its serialized payload. The serialized byte layout therefore does not need to match the in-memory layout.
Even with `codec = NONE`, `GLYPH` still requires bank-specific decode from its serialized payload. The serialized byte layout therefore does not need to match the in-memory layout.
#### 4.1.1 Metadata Normalization
Following `DEC-0004`, the `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity.
Required effective metadata fields for `TILES` at the root level:
Required effective metadata fields for `GLYPH` at the root level:
- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32`
- `width`: total sheet width in pixels
@@ -143,7 +143,7 @@ Optional informative subtrees:
- `metadata.codec`: codec/compressor-specific configuration (for example dictionaries or compression flags).
- `metadata.pipeline`: informative metadata from the Studio build process (for example source hashes, timestamps, or tool versions).
Validation rules for `TILES` v1:
Validation rules for `GLYPH` v1:
- `palette_count` must be `64`
- `width * height` defines the number of logical indexed pixels in the decoded sheet
@@ -160,17 +160,74 @@ The tile-bank payload therefore separates serialized storage form from runtime m
- decoded pixel plane: expanded `u8` indices, one entry per pixel
- palette table: `64 * 16` colors in `RGB565`
For `TILES` v1:
For `GLYPH` v1:
- `size` must match `ceil(width * height / 2) + (palette_count * 16 * 2)`
- `decoded_size` must match `(width * height) + (palette_count * 16 * 2)`
### 4.2 `SCENE` asset contract in v1
For `BankType::SCENE`, the v1 runtime-facing contract is:
- `codec = NONE`
- payload magic is `SCNE`
- payload version is `1`
- layer count is fixed at `4`
- each layer carries its own glyph dependency
- the glyph dependency is serialized as canonical `AssetId` using signed 32-bit little-endian width
- the payload MUST describe cold asset dependencies only and MUST NOT encode runtime glyph slot topology
Even with `codec = NONE`, `SCENE` still has a bank-specific binary contract. The serialized layout is normative and distinct from any transient runtime residency state.
#### 4.2.1 Layer Header Layout
Each scene layer header is:
1. `flags: u8`
2. `glyph_asset_id: i32` (little-endian)
3. `tile_size: u8`
4. `reserved: u16`
5. `parallax_x: f32`
6. `parallax_y: f32`
7. `width: u32`
8. `height: u32`
9. `tile_count: u32`
10. `reserved: u32`
This makes the canonical per-layer header size `32` bytes.
Normative rules:
- `glyph_asset_id` MUST be interpreted as the cold identity of the glyph dependency for that layer;
- `glyph_asset_id` MUST NOT be interpreted as a runtime slot id;
- each layer MUST own exactly one glyph dependency reference;
- no shared dependency table exists in this contract;
- `tile_count` MUST equal `width * height`.
#### 4.2.2 Runtime Binding Semantics
`SCENE` assets do not own runtime residency.
Therefore:
- the runtime MUST resolve scene glyph dependencies through runtime-owned residency state;
- the runtime MUST maintain a runtime-owned mapping from committed glyph `AssetId` to glyph slot;
- scene bind and scene draw MUST consult runtime residency, not serialized slot topology;
- a missing scene glyph dependency is not a passive asset-status condition.
If a scene glyph dependency cannot be resolved:
- `bind_scene` MUST fail as a fatal machine error with clear logging;
- draw/composition MUST fail as a fatal machine error with clear logging;
- runtime MUST NOT continue scene composition after the missing dependency is detected.
## 5 Banks and Slots
The current runtime exposes bank types:
- `GLYPH`
- `SOUNDS`
- `SCENE`
Assets are loaded into explicit slots identified by slot index at the public ABI boundary.
@@ -229,6 +229,12 @@ For mutating composer operations:
- `set_camera` remains `void` in v1;
- no caller-provided sprite index or `active` flag is part of the canonical contract.
Fatal boundary clarification for `bind_scene`:
- `bind_scene` remains status-returning for ordinary orchestration-domain rejection such as unresolved target scene slot;
- missing glyph dependencies inside a resident scene are not accepted as passive `ComposerOpStatus` outcomes;
- if scene activation or later composition detects an unresolved scene glyph dependency, runtime MUST escalate that condition as a fatal machine error with clear logging.
## 7 Syscalls as Callable Entities (Not First-Class)
Syscalls behave like call sites, not like first-class guest values.