implement PBS low-level asset host surface
This commit is contained in:
+33
@@ -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:
|
||||
|
||||
+5
@@ -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,
|
||||
|
||||
+22
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user