# 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.