prometeu-studio/discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md

id	ticket	title	created	tags
LSN-0023	pbs-low-level-asset-manager-surface	LowAssets Runtime-Aligned SDK Surface	2026-03-27	compiler pbs runtime asset-manager host-abi stdlib asset

Context

PBS needed a canonical low-level asset host surface that matched the runtime ABI already published by ../runtime. Without that surface, a future author-facing asset API would have no stable lowering target, and the SDK would remain inconsistent with existing host-backed areas such as log and gfx.

Key Decisions

Lock LowAssets As The PBS Low-Level Owner

What: PBS now exposes the runtime asset host ABI through declare host LowAssets in @sdk:asset.

Why: The runtime contract had already converged on asset.load, asset.status, asset.commit, and asset.cancel, so PBS needed one canonical editorial owner that maps to those same operational identities.

Trade-offs: LowAssets is a source-level naming choice only. It improves SDK readability, but engineers must remember that runtime identity still comes from module, name, version, and capability metadata, not from the PBS owner name.

Keep Runtime Identity Singular And ABI-Faithful

What: The canonical bindings remain module = "asset" and Capability(name = "asset"), with the v1 signatures:

• load(asset_id: int, slot: int) -> (status: int, loading_handle: int)
• status(loading_handle: int) -> int
• commit(loading_handle: int) -> int
• cancel(loading_handle: int) -> int

Why: The runtime registry and cartridge capability map already use singular asset, and the low-level SDK surface must not drift from that published ABI.

Trade-offs: This leaves v1 with raw int values for asset_id, slot, handle, and status. That is less type-safe than nominal wrappers, but it avoids inventing editorial types before the lowering contract is stable.

Patterns and Algorithms

• Separate editorial source ownership from runtime operational identity. LowAssets is the PBS owner, while ("asset", method, 1) and capability asset remain the executable contract.
• Introduce new host-backed SDK modules by mirroring the established stdlib pattern: main.pbs declares the host owner and mod.barrel exports it.
• Pin the surface in three places at once: normative specs, stdlib resources, and compiler tests. This prevents drift between documentation, packaged SDK modules, and host-binding validation.

Pitfalls

• Do not derive runtime identity from the PBS owner name. LowAssets does not imply module assets or capability assets.
• Do not reintroduce the retired name-based load path. The low-level contract is asset_id + slot, not asset_name, bank_type, or other symbolic references.
• Do not add a higher-level Assets facade in the same change unless a separate decision explicitly closes that API shape.

Takeaways

• @sdk:asset is the canonical low-level PBS entrypoint for runtime asset syscalls.
• The stable lowering target is singular runtime asset, even though the source owner is pluralized as LowAssets.
• Future ergonomic asset APIs should lower into this raw host-backed surface instead of bypassing it.