implement PBS low-level asset host surface

This commit is contained in:
2026-03-27 16:13:20 +00:00
parent 6150493e95
commit bd0b1924c2
14 changed files with 841 additions and 2 deletions
@@ -93,6 +93,13 @@ Rules:
Source-level owners such as `Gfx` are SDK-facing aliases.
They are not loader-facing identities.
For the current low-level asset surface:
- the canonical PBS owner name is `LowAssets`,
- the canonical runtime module remains `asset`,
- the canonical capability remains `asset`,
- the canonical load identity is `("asset", "load", 1)`.
## 6. Relationship to `declare host`
`declare host` is a reserved SDK/toolchain surface used to expose host-backed APIs to source programs.
@@ -129,6 +136,25 @@ but the PBX-facing declaration is canonical, for example:
("gfx", "draw_pixel", 1)
```
The same rule applies to the low-level asset surface.
For example, the PBS-facing declaration:
```pbs
declare host LowAssets {
[Host(module = "asset", name = "load", version = 1)]
[Capability(name = "asset")]
fn load(asset_id: int, slot: int) -> (status: int, loading_handle: int);
}
```
maps to the canonical runtime identity:
```text
("asset", "load", 1)
```
The loader MUST NOT derive runtime identity from the source owner spelling `LowAssets`.
## 7. PBX Host Binding Section
### 7.1 Temporary section contract
@@ -243,6 +269,13 @@ Rules:
- successful resolution yields numeric syscall identifiers and associated metadata,
- the resolved metadata is authoritative for capability gating and later runtime verification.
For the current asset runtime surface, the canonical registry entries include:
- `("asset", "load", 1)` with `arg_slots = 2` and `ret_slots = 2`,
- `("asset", "status", 1)` with `arg_slots = 1` and `ret_slots = 1`,
- `("asset", "commit", 1)` with `arg_slots = 1` and `ret_slots = 1`,
- `("asset", "cancel", 1)` with `arg_slots = 1` and `ret_slots = 1`.
## 10. Pre-Load Callsite Form
The compiler emits host-backed call sites in pre-load form as:
@@ -106,6 +106,9 @@ The current nominal capability set is:
These names are the normative manifest-facing representation.
For the low-level PBS asset host surface, the capability spelling MUST remain `asset` in the singular.
PBS SDK owner names such as `LowAssets` do not change the manifest/runtime capability spelling.
## 6. Relationship to Runtime `CapFlags`
The runtime may continue to represent capabilities internally as a bitflag set.
@@ -128,6 +131,8 @@ Canonical mapping:
- `asset` -> `ASSET`
- `bank` -> `BANK`
For asset host bindings, PBS declarations MUST use `[Capability(name = "asset")]` so that host admission, PBX host binding metadata, and cartridge capability checks all converge on the same runtime flag.
This means the recommended runtime design is:
1. deserialize `capabilities` into a nominal enum or equivalent validated representation,
@@ -59,6 +59,9 @@ prometeu-compiler/frontends/prometeu-frontend-pbs/
gfx/
main.pbs
mod.barrel
asset/
main.pbs
mod.barrel
audio/
main.pbs
mod.barrel
@@ -82,6 +85,7 @@ The compiler must treat the physical layout as a logical stdlib environment.
Required mapping:
- `stdlib/<N>/sdk/gfx` -> `@sdk:gfx`
- `stdlib/<N>/sdk/asset` -> `@sdk:asset`
- `stdlib/<N>/sdk/audio` -> `@sdk:audio`
- `stdlib/<N>/core/math` -> `@core:math`
- `stdlib/<N>/core/math/vector` -> `@core:math/vector`
@@ -204,6 +208,16 @@ declare host Gfx {
}
```
or:
```pbs
declare host LowAssets {
[Host(module = "asset", name = "load", version = 1)]
[Capability(name = "asset")]
fn load(asset_id: int, slot: int) -> (status: int, loading_handle: int);
}
```
Rules:
- the parser reads the attribute as part of the interface module source,
@@ -211,6 +225,14 @@ Rules:
- the compiler stores the extracted metadata in its interface graph,
- the raw attribute surface is not treated as a runtime object,
- later lowering stages may consume the extracted metadata to produce PBX host-binding declarations.
- stdlib line `1` MUST expose the low-level asset interface module at `@sdk:asset`,
- that module MUST declare `LowAssets`,
- that module MUST use runtime module `asset` and capability `asset`,
- that module MUST use the runtime-aligned 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`
## 10. Resources as an Implementation Strategy