clean up

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

@@ -0,0 +1,59 @@
+---
+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.