Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

Details

Reviewed-on: #12
Co-authored-by: bQUARKz <bquarkz@gmail.com>
Co-committed-by: bQUARKz <bquarkz@gmail.com>

2026-04-10 05:31:57 +00:00

6.6 KiB

Raw Blame History

ticket

title

created

Asset Management Mental Model

Status: pedagogical Companion specs:

Origin decisions:

PROMETEU treats assets as a self-contained cart artifact, not as metadata scattered across manifest.json, the loader, and the runtime.

One Runtime Artifact

The right mental model is:

manifest.json identifies the cart and its capabilities;
assets.pa carries the runtime-facing asset contract;
the runtime consumes that contract without depending on auxiliary tooling artifacts.

That avoids mixing:

cart editorial metadata;
internal packer details;
runtime loading policy.

Why `assets.pa` Owns The Asset Contract

assets.pa puts into the same binary:

a fixed prelude to locate the header;
a JSON header that is easy to inspect;
the cold binary payload of the assets.

That split exists to preserve two properties at the same time:

fixed cost to open and validate the artifact;
a readable header that is simple to debug.

The important point is not the format by itself. The important point is that the runtime finds everything it needs for assets behind one stable boundary.

`preload` Is Not `asset_table`

Both live in the header, but they serve different roles:

asset_table is the live asset-resolution index for the entire execution;
preload is only a boot-time instruction for initial residency.

A short way to think about it:

asset_table stays;
preload passes.

That prevents the runtime from treating preload as permanent metadata when, in practice, it is only an initial loading impulse.

Payload-Relative Thinking

AssetEntry offsets are relative to the start of the payload, not to the start of the whole file.

That choice preserves the semantics of the asset domain:

AssetEntry describes where content sits inside the cold-byte region;
the outer envelope can evolve without contaminating each entry with container details.

The runtime only needs to resolve:

payload_base + entry.offset

Slice-First Loading

The correct loading mental model is not:

ROM -> load the whole assets.pa into RAM -> look up asset

The correct flow is:

ROM -> open_slice -> CODEX/decode -> Bank

or, when the codec requires it:

ROM -> open_slice -> temporary blob -> CODEX/decode -> Bank

That matters because PROMETEU was designed for low-cost hardware. Keeping the whole payload resident as a baseline wastes memory, couples IO to a monolithic blob, and weakens the runtime's real boundary.

`OP_MODE` Belongs To The Runtime

The cart describes the asset. The runtime decides how to consume the slice.

In v1, that decision comes from the codec/CODEX:

some assets can be read directly from the limited view;
others require temporary materialization before decode.

The key point is to separate:

the asset storage contract;
the generic codec layer, when one exists;
the operational strategy for reading and decode.

Specialized Banks vs Generic Banks

The current asset model works better if you do not treat every bank as equally generic.

Some banks are specialized:

GLYPH
SOUNDS

For these, the bank contract already carries most of the important format rules. That means:

serialized layout belongs primarily to the bank contract;
metadata validation belongs primarily to the bank contract;
codec may be absent or minimal.

Other banks may be more generic in the future, such as a BLOB-style bank.

For those, codec can do more real work and describe a broader generic transformation pipeline for the payload.

That is the right hierarchy:

specialized bank first;
generic codec layer second.

Not the other way around.

Why `NONE` Matters

The move from RAW to NONE is not just a rename. It fixes the mental model.

RAW encouraged the wrong intuition that the bytes were somehow already "raw" in the runtime sense. But for specialized banks that is often false.

NONE is better because it says only this:

there is no additional generic codec layer.

It does not say:

there is no bank-specific decode;
there is no transformation before residency;
serialized bytes and resident memory are identical.

Serialized Form Is Not Resident Form

One of the most important asset-management lessons in the current runtime is that codec = NONE does not mean "bitwise identical to in-memory layout".

The glyph-bank path is the concrete example:

there is no additional generic codec layer for the asset;
the serialized payload stores indexed pixels as packed 4bpp;
the palette table remains serialized as RGB565 little-endian;
the runtime expands pixels into one u8 index per pixel after decode.

That is exactly why codec and bank contract must stay separate in the mental model:

codec may be absent;
the bank-specific decode may still be real and mandatory.

That is why AssetEntry.size and AssetEntry.decoded_size must be thought of as different concepts:

size is transport cost inside assets.pa;
decoded_size is resident-bank cost after materialization.

If those two numbers are treated as interchangeable, telemetry, budgets, and validation all become misleading.

Glyph Banks Teach The Real Boundary

Glyph banks are useful because they show the real separation of concerns:

assets.pa defines the serialized envelope and metadata needed to reconstruct the bank;
the runtime validates that metadata against the expected v1 contract;
the resident GlyphBank is a runtime object, not a direct view over the cold bytes.

This is the right PROMETEU mental model:

cartridge asset bytes are transport;
bank objects are execution state.

Why This Fits PROMETEU

This model fits the project well because:

it reduces dependence on metadata scattered through manifest.json;
it separates packer, shipper, and runtime more cleanly;
it allows early failure when Capability::Asset requires assets.pa;
it preserves a runtime that can run on desktop and on low-cost dedicated hardware.

When thinking about assets in PROMETEU, think less in terms of "a manifest with attachments" and more in terms of "a cart with an asset artifact that explains itself".

6.6 KiB Raw Blame History