---
id: LSN-0023
ticket: pbs-low-level-asset-manager-surface
title: LowAssets Runtime-Aligned SDK Surface
created: 2026-03-27
tags: [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.