187 lines
5.1 KiB
Markdown
187 lines
5.1 KiB
Markdown
# PR-6 — PBX Declared Syscalls Section (Load-Time Resolution Integration)
|
|
|
|
## Briefing
|
|
|
|
Chapter 16 requires that cartridges declare required syscalls using canonical identities `(module, name, version)` and that these be resolved at load time before the VM begins execution.
|
|
|
|
Until now, resolution has existed only as an API (PR5.3.2). The PBX on-disk format currently does not carry declared syscalls, and the loader cannot enforce load-time resolution deterministically.
|
|
|
|
This PR introduces a minimal, production-grade PBX section for **declared syscalls only** and integrates it into the PBX load sequence.
|
|
|
|
**Scope note (important):**
|
|
|
|
* PBX contains **program + syscall metadata** only.
|
|
* Assets (`asset_table`, `preload`, etc.) are explicitly **out of scope** for this PR and will be handled later via `asset.pa`.
|
|
|
|
After this PR:
|
|
|
|
* `program.pbx` contains a `SYSC` (declared syscalls) section.
|
|
* The PBX loader parses `SYSC` and resolves identities at load time.
|
|
* Load fails deterministically if resolution fails.
|
|
* The VM continues to execute `SYSCALL <id>` only.
|
|
|
|
No backward compatibility. No fallback to external manifests in production.
|
|
|
|
---
|
|
|
|
## Target
|
|
|
|
1. Define a minimal PBX section for declared syscalls.
|
|
2. Extend the PBX parser/loader to read this section.
|
|
3. Integrate `resolve_program_syscalls()` into PBX load.
|
|
4. Enforce load-time failure on unknown or unauthorized syscalls.
|
|
5. Keep VM runtime strictly numeric.
|
|
|
|
---
|
|
|
|
## PBX Section Format (Authoritative for This PR)
|
|
|
|
Add a new PBX chunk:
|
|
|
|
* Chunk ID: `SYSC`
|
|
|
|
Binary layout:
|
|
|
|
```
|
|
u32 count
|
|
repeat count times:
|
|
u16 module_len
|
|
[module_len bytes UTF-8]
|
|
u16 name_len
|
|
[name_len bytes UTF-8]
|
|
u16 version
|
|
```
|
|
|
|
Rules:
|
|
|
|
* UTF-8 strings only.
|
|
* No string table in this PR (keep it minimal).
|
|
* This section is REQUIRED for PBX v0 after this PR.
|
|
* If absent → load error.
|
|
* Duplicate `(module,name,version)` entries → load error.
|
|
|
|
**Out of scope:** Any asset-related metadata. Do not add `ASSET_TABLE`, `PRELOAD`, or anything similar to PBX in this PR.
|
|
|
|
---
|
|
|
|
## Load Sequence (After PR-6)
|
|
|
|
1. Parse PBX header and TOC.
|
|
2. Parse `SYSC` section into `Vec<SyscallIdentity>`.
|
|
3. Call:
|
|
|
|
```rust
|
|
resolve_program_syscalls(&declared, vm.capabilities)
|
|
```
|
|
4. If resolution fails → abort load deterministically.
|
|
5. Store resolved syscalls inside VM (or a `LoadedProgram` struct).
|
|
6. Start VM execution.
|
|
|
|
No runtime name resolution allowed.
|
|
|
|
---
|
|
|
|
## Work Items
|
|
|
|
### 1) PBX Parser / Loader Extension
|
|
|
|
* Add support for `SYSC` chunk in the PBX parser/loader.
|
|
* Return `declared_syscalls: Vec<SyscallIdentity>` as part of `ProgramImage` (or equivalent).
|
|
* If `SYSC` is missing → return load error.
|
|
|
|
### 2) Load-Time Resolver Integration
|
|
|
|
* In the PBX load path:
|
|
|
|
* Parse declared syscalls.
|
|
* Resolve using `prometeu_hal::syscalls::resolve_program_syscalls`.
|
|
* Enforce capability checks at load time.
|
|
* If resolution fails → load fails (no runtime fallback).
|
|
|
|
* Do NOT modify VM execution core beyond storing the resolved mapping.
|
|
|
|
### 3) VM State Storage
|
|
|
|
* Add or finalize storage for resolved syscalls (if not already present).
|
|
* VM must NOT use canonical strings at runtime.
|
|
* VM runtime continues to execute only numeric IDs.
|
|
|
|
### 4) Error Handling
|
|
|
|
PBX load must fail deterministically if:
|
|
|
|
* Unknown `(module,name,version)`.
|
|
* Capability mismatch.
|
|
* Duplicate identities in `SYSC`.
|
|
* `SYSC` chunk is missing.
|
|
* Malformed `SYSC` payload (lengths/UTF-8).
|
|
|
|
Errors must be explicit and deterministic.
|
|
|
|
---
|
|
|
|
## Acceptance Checklist
|
|
|
|
* [ ] PBX format supports `SYSC` chunk.
|
|
* [ ] Loader parses declared syscalls from PBX.
|
|
* [ ] Resolver runs during PBX load (before VM execution).
|
|
* [ ] Load fails on unknown syscall.
|
|
* [ ] Load fails on capability violation.
|
|
* [ ] Load fails when `SYSC` chunk is missing.
|
|
* [ ] No runtime name resolution exists.
|
|
* [ ] `cargo test` passes.
|
|
|
|
---
|
|
|
|
## Tests
|
|
|
|
Add tests covering:
|
|
|
|
1. Valid PBX with one syscall identity → loads successfully.
|
|
2. PBX with unknown syscall identity → load error.
|
|
3. PBX with capability violation → load error.
|
|
4. PBX without `SYSC` section → load error.
|
|
5. PBX with duplicate identity entries → load error.
|
|
6. PBX with malformed `SYSC` payload (bad lengths/invalid UTF-8) → load error.
|
|
|
|
Tests must construct minimal synthetic PBX images in-memory.
|
|
|
|
Do NOT rely on external files.
|
|
|
|
---
|
|
|
|
## Junie Instructions
|
|
|
|
You MAY:
|
|
|
|
* Extend PBX parser/loader to support `SYSC`.
|
|
* Integrate the resolver into the PBX load path.
|
|
* Add deterministic tests for load-time resolution.
|
|
|
|
You MUST NOT:
|
|
|
|
* Add backward compatibility paths.
|
|
* Add fallback to JSON manifests.
|
|
* Add any asset-table or preload metadata to PBX.
|
|
* Change VM runtime dispatch logic.
|
|
* Modify syscall numeric IDs.
|
|
|
|
If PBX container format details (header/TOC/chunk reading) are unclear:
|
|
|
|
* STOP.
|
|
* Ask for clarification before inventing new unrelated chunk structures.
|
|
|
|
No assumptions beyond the `SYSC` layout defined above.
|
|
|
|
---
|
|
|
|
## Definition of Done
|
|
|
|
After this PR:
|
|
|
|
* Syscall resolution is fully load-time for PBX.
|
|
* PBX is authoritative for declared syscalls.
|
|
* VM executes only numeric syscalls.
|
|
* No legacy or dev fallback exists in the production load path.
|
|
* No asset responsibilities are added to PBX.
|