195 lines
8.7 KiB
Markdown
195 lines
8.7 KiB
Markdown
---
|
|
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.
|