prometeu-runtime/discussion/lessons/DSC-0018-asset-load-asset-id-int-contract/LSN-0019-asset-load-id-abi-convergence.md

id	ticket	title	created	tags
LSN-0019	asset-load-asset-id-int-contract	Asset Load ABI Must Converge with Asset Table Identity	2026-03-27	asset runtime abi

Context

The runtime had already converged on numeric asset identity in the cartridge model:

• AssetId was i32;
• preload used { asset_id, slot };
• cartridge bootstrap validated preload entries against asset_table by asset_id.

The remaining inconsistency was the public runtime syscall surface. asset.load still accepted a string identifier plus an explicit asset kind, forcing the runtime to keep a name_to_id translation path alive even though asset_table already carried canonical identity and bank classification.

Key Decisions

Asset Load Asset ID Int Contract

What: asset.load now uses the canonical runtime form asset.load(asset_id, slot). The public ABI no longer accepts string asset names or an explicit asset_type argument.

Why: Once asset_table exists, asset kind is derivable from asset_id. Keeping asset_type in the ABI only duplicates information and creates a second place for disagreement. Keeping string names in the load path also preserves a shadow identity model that the runtime no longer needs.

Trade-offs: This is a hard cut with no compatibility layer. Legacy producers that still emit name-based asset loads must update, but the runtime stays simpler and the contract becomes unambiguous.

Patterns and Algorithms

• Treat asset_table as the single source of truth for operational asset identity.
• Infer internal bank-qualified slot routing from the resolved AssetEntry rather than from caller-supplied ABI fields.
• Keep human-readable names as metadata and telemetry only, not as runtime lookup keys.

Pitfalls

• If preload, loader validation, and on-demand runtime loading use different identity forms, the system develops a split contract that is easy to document incorrectly and hard to evolve safely.
• ABI migrations that leave dual support for both names and IDs tend to preserve ambiguity longer than intended.
• Removing a public parameter such as asset_type may also remove previously observable error states, so tests and specs must be updated together.

Takeaways

• When a cartridge-wide identity table already exists, public runtime surfaces should use that identity directly.
• Derivable ABI fields should not remain public inputs once the derivation source is canonical.
• Asset preload and on-demand asset load should follow the same identity model end to end.