---
id: LSN-0019
ticket: asset-load-asset-id-int-contract
title: Asset Load ABI Must Converge with Asset Table Identity
created: 2026-03-27
tags: [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.