asset manager load by asset id and slot index
This commit is contained in:
+48
@@ -0,0 +1,48 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user