prometeu-runtime/files/LOAD.md

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:

   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.