prometeu-studio/discussion/workflow/plans/PLN-0004-pbs-low-level-asset-manager-surface.md

id	ticket	title	status	created	completed	tags
PLN-0004	pbs-low-level-asset-manager-surface	Implement DEC-0004 PBS Low-Level Asset Manager Surface	done	2026-03-27	2026-03-27	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.