[PERF] Runtime Introspection Syscalls

This commit is contained in:
2026-04-19 08:37:21 +01:00
parent e895b01b8f
commit aaf4dff69d
11 changed files with 361 additions and 71 deletions
+31 -26
View File
@@ -110,44 +110,44 @@ This table describes content identity and storage layout, not live residency.
### 4.1 `TILES` asset contract in v1
Para `BankType::TILES`, o contrato v1 voltado para o runtime é:
For `BankType::TILES`, the v1 runtime-facing contract is:
- `codec = NONE`
- pixels serializados usam índices de paleta `u4` empacotados
- paletas serializadas usam `RGB565` (`u16`, little-endian)
- serialized pixels use packed `u4` palette indices
- serialized palettes use `RGB565` (`u16`, little-endian)
- `palette_count = 64`
- a materialização em runtime pode expandir índices de pixel para um `u8` por pixel
- runtime materialization may expand pixel indices to one `u8` per pixel
`NONE` para `TILES` significa que não há camada de codec genérica adicional além do próprio contrato do banco.
For `TILES`, `NONE` means there is no additional generic codec layer beyond the bank contract itself.
Para a janela de transição atual:
For the current transition window:
- `RAW` é um alias legado e depreciado de `NONE`
- novos materiais publicados devem usar `NONE` como valor canônico
- `RAW` is a legacy deprecated alias of `NONE`
- newly published material must use `NONE` as the canonical value
Mesmo com `codec = NONE`, `TILES` ainda requer decode específico de banco a partir de seu payload serializado. O layout de bytes serializados não precisa, portanto, ser idêntico ao layout em memória.
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.
#### 4.1.1 Metadata Normalization
Seguindo a `DEC-0004`, o campo `AssetEntry.metadata` deve ser estruturado de forma segmentada para evitar ambiguidades.
Following `DEC-0004`, the `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity.
Campos de metadados obrigatórios (efetivos) para `TILES` no nível raiz:
Required effective metadata fields for `TILES` at the root level:
- `tile_size`: aresta do tile em pixels; valores válidos são `8`, `16`, ou `32`
- `width`: largura total da folha do banco em pixels
- `height`: altura total da folha do banco em pixels
- `palette_count`: número de paletas serializadas para o banco
- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32`
- `width`: total sheet width in pixels
- `height`: total sheet height in pixels
- `palette_count`: number of serialized palettes for the bank
Subárvores opcionais e informativas:
Optional informative subtrees:
- `metadata.codec`: Configuração específica do codec/compressor (ex: dicionários, flags de compressão).
- `metadata.pipeline`: Metadados informativos do processo de build do Studio (ex: source hashes, timestamps, tool versions).
- `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).
Regras de validação para `TILES` v1:
Validation rules for `TILES` v1:
- `palette_count` deve ser `64`
- `width * height` define o número de pixels indexados lógicos na folha decodificada
- metadados adicionais podem existir, mas o contrato do runtime não deve depender deles para reconstruir o banco em memória (exceto se definidos na raiz como campos efetivos).
- `palette_count` must be `64`
- `width * height` defines the number of logical indexed pixels in the decoded sheet
- extra metadata may exist, but the runtime contract must not depend on it to reconstruct the in-memory bank unless that data is defined at the root as an effective field.
#### 4.1.2 Payload Layout
@@ -202,7 +202,8 @@ Rules:
- the visible contract MUST NOT expose byte-oriented bank occupancy as the canonical summary;
- canonical bank names are `GLYPH` and `SOUNDS`;
- detailed occupancy inspection remains slot-based through slot references, not bank byte totals;
- detailed occupancy inspection remains host-owned and slot-based through slot references, not bank byte totals;
- public runtime specs MUST NOT treat `bank.slot_info` or JSON bank inspection payloads as the long-term guest ABI after `DEC-0009`;
- any residual byte accounting MAY exist internally, but it is not part of the visible bank telemetry contract.
## 6 Load Lifecycle
@@ -255,9 +256,9 @@ Therefore:
- shutting down a cartridge can release bank residency independently of VM heap behavior.
- the runtime must not keep the full `assets.pa` payload resident in RAM as a baseline requirement.
## 8 Bank Telemetry
## 8 Bank Telemetry and Inspection Boundary
The runtime surfaces bank and slot statistics such as:
The runtime may maintain bank and slot statistics such as:
- total bytes;
- used bytes;
@@ -266,7 +267,11 @@ The runtime surfaces bank and slot statistics such as:
- slot occupancy;
- resident asset identity per slot.
These metrics support debugging, telemetry, and certification-oriented inspection.
These metrics support host-owned debugging, telemetry, and certification-oriented inspection.
Only bounded operational summaries belong to the public runtime contract.
Detailed per-slot inspection is valid for host tooling and runtime internals, but it must not be treated as a general guest-visible debug convenience API.
## 9 Preload