---
id: PLN-0004
ticket: pbs-low-level-asset-manager-surface
title: Implement DEC-0004 PBS Low-Level Asset Manager Surface
status: done
created: 2026-03-27
completed: 2026-03-27
tags: [compiler, pbs, runtime, asset-manager, host-abi, stdlib, asset]
---

## Objective

Propagate `DEC-0004` into PBS normative docs, stdlib interface resources, and compiler-facing tests so the workspace exposes a canonical low-level `LowAssets` host surface aligned with the current runtime asset ABI.

## Background

`DEC-0004` locked the v1 low-level PBS asset surface to:

- `declare host LowAssets`
- runtime module `asset`
- capability `asset`
- raw `int` parameters and returns for `asset_id`, `slot`, `handle`, and status values
- runtime syscall identities:
  - `asset.load(asset_id, slot) -> (status, handle)`
  - `asset.status(handle) -> status`
  - `asset.commit(handle) -> status`
  - `asset.cancel(handle) -> status`

The repository already ships comparable SDK interface modules for:

- `@sdk:log`
- `@sdk:gfx`
- `@sdk:input`

The repository does not yet ship `@sdk:asset`, and current PBS specs do not yet normatively pin `LowAssets` as the canonical low-level asset host owner.

## Scope

### Included
- Update PBS specs to include the low-level `LowAssets` asset host surface and its runtime alignment.
- Add a new stdlib interface module for `@sdk:asset`.
- Add compiler and stdlib-loading tests that pin the new interface module, reserved metadata, and import resolution behavior.
- Verify that the declared host ABI matches the runtime contract from `../runtime`.

### Excluded
- Any author-facing `Assets` facade or `Addressable` lowering design from `DSC-0006`.
- Nominal wrapper types such as `AssetId`, `Handle`, or `SlotIndex`.
- Enumized status surfaces for asset operations.
- `bank.info` and `bank.slot_info` surfaces.
- Runtime changes in `../runtime`.

## Execution Steps

### Step 1 - Propagate The Decision Into PBS Specs

**What:**
Update the normative PBS documentation so the low-level asset host surface is described explicitly and consistently with `DEC-0004`.

**How:**
Add or revise sections that state:

- the canonical owner name is `LowAssets`;
- the host bindings use `module = "asset"` and `Capability(name = "asset")`;
- the required members are `load`, `status`, `commit`, and `cancel`;
- `load` uses `asset_id` and `slot`, not `asset_name` or `bank_type`;
- the v1 surface uses raw `int` values;
- any future symbolic surface lowers into this low-level contract.

Prioritize the spec surfaces that already define host ABI, stdlib packaging, and runtime capability mapping.

**File(s):**
- `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/specs/compiler-languages/pbs/8. Stdlib Environment Packaging and Loading Specification.md`
- `docs/specs/compiler-languages/pbs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
- optional cross-reference if needed: `docs/specs/compiler/18. Standard Library Surface Specification.md`

### Step 2 - Add The `@sdk:asset` Interface Module

**What:**
Create the stdlib interface resources for the new low-level asset surface.

**How:**
Add a new directory under the existing stdlib SDK layout mirroring the established `log` and `gfx` pattern:

- `main.pbs` declares `LowAssets`;
- `mod.barrel` exports the low-level host owner;
- all members use canonical reserved metadata;
- signatures match the runtime ABI exactly:
  - `fn load(asset_id: int, slot: int) -> (status: int, loading_handle: int);`
  - `fn status(loading_handle: int) -> int;`
  - `fn commit(loading_handle: int) -> int;`
  - `fn cancel(loading_handle: int) -> int;`

Do not introduce a `declare service Assets` wrapper in this plan.

**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/sdk/asset/main.pbs`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/sdk/asset/mod.barrel`

### Step 3 - Pin Interface Semantics And Metadata Extraction

**What:**
Extend frontend tests so the reserved metadata and interface-module semantics recognize the new asset surface.

**How:**
Add or update tests to cover:

- parsing and semantic acceptance of `LowAssets` in `SourceKind.SDK_INTERFACE`;
- extraction of `[Host(...)]` and `[Capability(...)]` metadata for the new members;
- ABI slot counts for `load/status/commit/cancel`;
- rejection of incorrect legacy asset ABI shapes if they are declared as canonical.

Reuse the same testing style already used for `LowLog` and `LowGfx`.

**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/PbsInterfaceModuleSemanticsTest.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUSdkInterfaceConformanceTest.java`

### Step 4 - Pin Stdlib Loading And Import Resolution

**What:**
Verify that the compiler stdlib environment exposes `@sdk:asset` and that programs can import the surface through the normal interface-module loader path.

**How:**
Add or update tests that:

- resolve `@sdk:asset` through the stdlib loader;
- import `LowAssets` from `@sdk:asset`;
- ensure the imported surface compiles under the same reserved-host rules used by existing SDK modules;
- confirm capability and host identities survive the loading pipeline.

**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/stdlib/InterfaceModuleLoaderTest.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUStdlibCompileTest.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java`

### Step 5 - Cross-Check Runtime ABI Alignment

**What:**
Validate that the PBS declarations and tests remain aligned with the runtime ABI actually published by `../runtime`.

**How:**
Before closing implementation, verify against the runtime sources currently present in the sibling workspace:

- `module = "asset"`
- `Capability(name = "asset")`
- `load` uses `arg_slots = 2`, `ret_slots = 2`
- `status`, `commit`, and `cancel` use `arg_slots = 1`, `ret_slots = 1`

If the runtime changes again before implementation lands, update the PBS work in the same change or stop and reopen the decision if the semantic contract changed.

**File(s):**
- `../runtime/crates/console/prometeu-hal/src/syscalls/domains/asset.rs`
- `../runtime/docs/specs/runtime/15-asset-management.md`
- `../runtime/docs/specs/runtime/16-host-abi-and-syscalls.md`

## Test Requirements

### Unit Tests
- Interface-module semantics tests for `LowAssets` reserved metadata and signature acceptance.
- Frontend compiler tests for metadata extraction and ABI slot shape.
- Stdlib loader tests for `@sdk:asset` module discovery and barrel export resolution.

### Integration Tests
- Frontend phase tests that compile a small source importing `LowAssets` from `@sdk:asset`.
- Conformance-style tests that assert the canonical host identities and capability spelling survive compile-time validation.

### Manual Verification
- Inspect generated stdlib resource files for exact `Host` and `Capability` spellings.
- Re-run the targeted PBS frontend test suite covering stdlib loading, interface semantics, and reserved host metadata.
- Re-check the sibling runtime contract immediately before merge if implementation does not happen in the same working session.

## Acceptance Criteria

- [ ] PBS specs state that the canonical low-level asset owner is `LowAssets`.
- [ ] PBS specs state that capability spelling is `asset`, not `assets`.
- [ ] PBS specs state that `asset.load` uses `asset_id` and `slot`, not `asset_name` or `bank_type`.
- [ ] The stdlib environment exposes `@sdk:asset` with `declare host LowAssets`.
- [ ] `LowAssets.load/status/commit/cancel` signatures match the runtime ABI from `../runtime`.
- [ ] Compiler tests pin the reserved metadata, signature shapes, and import path for the new surface.
- [ ] No new higher-level `Assets` facade is introduced as part of this plan.

## Dependencies

- `DEC-0004-pbs-low-level-asset-manager-surface`
- Current runtime ABI as published in `../runtime`
- Existing stdlib interface loader and SDK resource layout in `prometeu-compiler/frontends/prometeu-frontend-pbs`

## Risks

- The sibling runtime may continue evolving, causing PBS docs or tests to drift if implementation is delayed.
- Introducing `@sdk:asset` may reveal hidden assumptions in stdlib packaging or SDK import tests that currently only cover `log`, `gfx`, and `input`.
- Because v1 keeps raw `int`, the first implementation may encourage accidental misuse of `asset_id`, `slot`, and `handle` in user-facing code if a higher-level wrapper is added too quickly later.