pr6.1
This commit is contained in:
+186
@@ -0,0 +1,186 @@
|
||||
# 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.
|
||||
+303
@@ -0,0 +1,303 @@
|
||||
# PR-6.2 — Closure Capture Materialization
|
||||
|
||||
## Briefing
|
||||
|
||||
Closures must capture values from the current stack frame into a heap-allocated environment.
|
||||
|
||||
This PR defines:
|
||||
|
||||
* How captured values are materialized.
|
||||
* How the environment layout is constructed.
|
||||
|
||||
No CALL_CLOSURE yet.
|
||||
|
||||
---
|
||||
|
||||
## Target
|
||||
|
||||
Define bytecode semantics for closure creation:
|
||||
|
||||
Introduce instruction (placeholder name):
|
||||
|
||||
`MAKE_CLOSURE fn_id, capture_count`
|
||||
|
||||
Semantics:
|
||||
|
||||
* Pop `capture_count` values from stack (top-first).
|
||||
* Allocate closure object with those values stored in-order.
|
||||
* Push resulting `HeapRef` to stack.
|
||||
|
||||
---
|
||||
|
||||
## Work Items
|
||||
|
||||
1. Define new opcode `MAKE_CLOSURE`.
|
||||
2. Implement stack semantics.
|
||||
3. Ensure captured values are copied (not borrowed).
|
||||
4. Update interpreter to support opcode.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
* [ ] MAKE_CLOSURE opcode exists.
|
||||
* [ ] Stack pops correct number of values.
|
||||
* [ ] Closure allocated correctly.
|
||||
* [ ] Closure ref pushed to stack.
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
1. Create closure capturing 0 values.
|
||||
2. Create closure capturing 2 values.
|
||||
3. Validate env order correctness.
|
||||
|
||||
---
|
||||
|
||||
## Junie Instructions
|
||||
|
||||
You MAY:
|
||||
|
||||
* Add opcode.
|
||||
* Modify interpreter dispatch.
|
||||
* Add tests.
|
||||
|
||||
You MUST NOT:
|
||||
|
||||
* Implement CALL_CLOSURE yet.
|
||||
* Modify GC behavior.
|
||||
* Change verifier in this PR.
|
||||
|
||||
If capture order semantics unclear, STOP and ask.
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done
|
||||
|
||||
Closures can be created with captured environment and exist as heap values.
|
||||
|
||||
---
|
||||
|
||||
# PR-6.3 — CALL_CLOSURE Instruction
|
||||
|
||||
## Briefing
|
||||
|
||||
Closures must be invokable at runtime. This PR introduces dynamic invocation semantics for closures.
|
||||
|
||||
---
|
||||
|
||||
## Target
|
||||
|
||||
Introduce opcode:
|
||||
|
||||
`CALL_CLOSURE arg_count`
|
||||
|
||||
Semantics:
|
||||
|
||||
* Stack layout before call:
|
||||
|
||||
```
|
||||
[... args..., closure_ref]
|
||||
```
|
||||
* Pop closure_ref.
|
||||
* Validate it is ObjectKind::Closure.
|
||||
* Pop `arg_count` arguments.
|
||||
* Create new call frame:
|
||||
|
||||
* Locals initialized with captured env first (design choice below).
|
||||
* Arguments appended after captures.
|
||||
* Jump to function entry (fn_id).
|
||||
|
||||
---
|
||||
|
||||
## Work Items
|
||||
|
||||
1. Add `CALL_CLOSURE` opcode.
|
||||
2. Validate closure_ref type.
|
||||
3. Integrate into call frame creation logic.
|
||||
4. Respect function signature for ret_slots.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
* [ ] CALL_CLOSURE implemented.
|
||||
* [ ] Correct stack consumption.
|
||||
* [ ] Correct frame initialization.
|
||||
* [ ] Error on non-closure value.
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
1. Simple closure returning constant.
|
||||
2. Closure capturing value and using it.
|
||||
3. Error when calling non-closure.
|
||||
|
||||
---
|
||||
|
||||
## Junie Instructions
|
||||
|
||||
You MAY:
|
||||
|
||||
* Add opcode and dispatch.
|
||||
* Modify call frame initialization.
|
||||
* Add tests.
|
||||
|
||||
You MUST NOT:
|
||||
|
||||
* Redesign stack model.
|
||||
* Introduce coroutine behavior here.
|
||||
* Change GC.
|
||||
|
||||
If frame layout decision is ambiguous, STOP and ask before choosing ordering.
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done
|
||||
|
||||
Closures can be invoked dynamically and execute correctly.
|
||||
|
||||
---
|
||||
|
||||
# PR-6.4 — GC Traversal for Closures
|
||||
|
||||
## Briefing
|
||||
|
||||
Closures introduce heap-to-heap references through their captured environments.
|
||||
|
||||
The GC must traverse:
|
||||
|
||||
closure -> env -> inner HeapRefs
|
||||
|
||||
This PR updates the GC mark phase to correctly traverse closure environments.
|
||||
|
||||
---
|
||||
|
||||
## Target
|
||||
|
||||
Extend GC mark logic:
|
||||
|
||||
* When encountering ObjectKind::Closure:
|
||||
|
||||
* Iterate over env values.
|
||||
* If a value contains HeapRef → mark referenced object.
|
||||
|
||||
---
|
||||
|
||||
## Work Items
|
||||
|
||||
1. Update mark traversal switch for Closure.
|
||||
2. Ensure no panics on malformed env.
|
||||
3. Add tests for nested closure references.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
* [ ] GC marks env HeapRefs.
|
||||
* [ ] No regression in existing GC tests.
|
||||
* [ ] Nested closures retained correctly.
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
1. Closure capturing another closure.
|
||||
2. Closure capturing heap object.
|
||||
3. Unreferenced closure collected.
|
||||
|
||||
---
|
||||
|
||||
## Junie Instructions
|
||||
|
||||
You MAY:
|
||||
|
||||
* Modify mark traversal.
|
||||
* Add GC tests.
|
||||
|
||||
You MUST NOT:
|
||||
|
||||
* Implement compaction.
|
||||
* Change sweep policy.
|
||||
|
||||
If unsure whether env values may contain non-heap values, ask before assuming.
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done
|
||||
|
||||
GC correctly traverses closure environments.
|
||||
|
||||
---
|
||||
|
||||
# PR-6.5 — Verifier Support for Closures
|
||||
|
||||
## Briefing
|
||||
|
||||
The verifier must understand closure values as a distinct type and validate dynamic calls safely.
|
||||
|
||||
Closures are heap objects but semantically represent callable values.
|
||||
|
||||
---
|
||||
|
||||
## Target
|
||||
|
||||
Extend verifier to:
|
||||
|
||||
* Introduce a stack type: `ClosureValue`.
|
||||
* Validate MAKE_CLOSURE stack effects.
|
||||
* Validate CALL_CLOSURE argument counts.
|
||||
* Validate ret_slots against function signature.
|
||||
|
||||
---
|
||||
|
||||
## Work Items
|
||||
|
||||
1. Add closure type to verifier type lattice.
|
||||
2. Define stack transitions for MAKE_CLOSURE.
|
||||
3. Define stack transitions for CALL_CLOSURE.
|
||||
4. Ensure deterministic failure on misuse.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
* [ ] Verifier understands closure values.
|
||||
* [ ] Invalid CALL_CLOSURE rejected.
|
||||
* [ ] ret_slots validated.
|
||||
* [ ] All tests pass.
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
1. Valid closure call passes verification.
|
||||
2. CALL_CLOSURE with wrong arg count fails.
|
||||
3. CALL_CLOSURE on non-closure fails.
|
||||
|
||||
---
|
||||
|
||||
## Junie Instructions
|
||||
|
||||
You MAY:
|
||||
|
||||
* Extend verifier type model.
|
||||
* Add tests.
|
||||
|
||||
You MUST NOT:
|
||||
|
||||
* Weaken verification rules.
|
||||
* Introduce runtime-only checks instead of verifier checks.
|
||||
|
||||
If closure typing conflicts with current stack model, STOP and ask.
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done
|
||||
|
||||
Verifier fully supports closure creation and invocation.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,12 +1,3 @@
|
||||
6 — Closures (first-class user functions)
|
||||
|
||||
6.1. Definir objeto Closure no heap: fn_id + env (captures) + metadata mínima.
|
||||
6.2. Definir como capturas são materializadas (layout do env e como o bytecode cria closures).
|
||||
6.3. Implementar instruções/semântica para criar closure e para CALL_CLOSURE.
|
||||
6.4. Atualizar GC traversal: closure → env → heap refs internos.
|
||||
6.5. Atualizar verifier: tipo “closure value”, validação de call sites, ret_slots.
|
||||
6.6. Testes: closure simples, closure capturando, closure retornando outra closure.
|
||||
|
||||
7 — Coroutines (único modelo de concorrência, cooperativo)
|
||||
|
||||
7.1. Definir objeto Coroutine no heap: stack/frames próprios, status, wake time, mailbox/queue se existir.
|
||||
|
||||
Reference in New Issue
Block a user