added specs for linkage model
This commit is contained in:
@@ -1,23 +1,10 @@
|
||||
# VM PR Plan — PBS v0 Executable (Industrial Baseline)
|
||||
# PRs for Junie — Compiler Dependency Resolution & Linking Pipeline
|
||||
|
||||
> **Goal:** make *all PBS v0 functionality* executable on the VM with **deterministic semantics**, **closed stack/locals contract**, **stable ABI**, and **integration-grade tests**.
|
||||
>
|
||||
> **Non-goal:** new language features. If something must be reworked to achieve industrial quality, it *must* be reworked.
|
||||
> Goal: Move dependency resolution + linking orchestration into **prometeu_compiler** so that the compiler produces a **single fully-linked bytecode blob**, and the VM/runtime only **loads + executes**.
|
||||
|
||||
---
|
||||
## Non-goals (for this PR set)
|
||||
|
||||
## Guiding invariants (apply to every PR)
|
||||
|
||||
### VM invariants
|
||||
|
||||
1. **Every opcode has an explicit stack effect**: `pop_n → push_m` (in *slots*, not “values”).
|
||||
2. **Frames are explicit**: params/locals/operand stack are separate or formally delimited.
|
||||
3. **No implicit behavior**: if it isn’t encoded in bytecode or runtime state, it doesn’t exist.
|
||||
4. **Deterministic traps** only (no UB): trap includes `trap_code`, `pc`, `opcode`, and (if present) `span`.
|
||||
5. **Bytecode stability**: versioned format; opcodes are immutable once marked v0.
|
||||
|
||||
### Compiler/VM boundary invariants
|
||||
|
||||
1. **Types map to slot counts** deterministically (including flattened SAFE structs and multi-slot returns).
|
||||
2. **Calling convention is frozen**: param order, return slots, caller/callee responsibilities.
|
||||
3. **Imports are compile/link-time only**; VM runs a fully-linked program image.
|
||||
* No lockfile format (yet)
|
||||
* No registry (yet)
|
||||
* No advanced SAT solver: first iteration is deterministic and pragmatic
|
||||
* No incremental compilation (yet)
|
||||
@@ -1,34 +1,337 @@
|
||||
## PR-12 — VM test harness: stepper, trace, and property tests
|
||||
## PR-09 — Add `prometeu.json` manifest parser + schema validation
|
||||
|
||||
**Why:** Industrial quality means test tooling, not just “it runs”.
|
||||
**Why:** Dependency resolution cannot exist without a stable project manifest.
|
||||
|
||||
### Scope
|
||||
|
||||
* Add `VmRunner` test harness:
|
||||
* Implement `prometeu_compiler::manifest` module:
|
||||
|
||||
* step limit
|
||||
* deterministic trace of stack deltas
|
||||
* snapshot of locals
|
||||
* Add property tests (lightweight):
|
||||
* `Manifest` struct mirroring the spec fields:
|
||||
|
||||
* stack never underflows in verified programs
|
||||
* verified programs never jump out of bounds
|
||||
* `name`, `version`, `kind`
|
||||
* `dependencies: HashMap<Alias, DependencySpec>`
|
||||
* Support `DependencySpec` variants:
|
||||
|
||||
* `path`
|
||||
* `git` (+ optional `version`)
|
||||
* Validate:
|
||||
|
||||
* required fields present
|
||||
* dependency entry must specify exactly one source (`path` or `git`)
|
||||
* dependency aliases must be unique
|
||||
* basic name rules (non-empty, no whitespace)
|
||||
|
||||
### Deliverables
|
||||
|
||||
* `load_manifest(project_root) -> Result<Manifest, ManifestError>`
|
||||
* Diagnostic errors with file path + JSON pointer (or best-effort context)
|
||||
|
||||
### Tests
|
||||
|
||||
* parse minimal manifest
|
||||
* missing name/version errors
|
||||
* invalid dependency shape errors
|
||||
|
||||
### Acceptance
|
||||
|
||||
* Debugging is fast, and regressions are caught.
|
||||
* Compiler can reliably load + validate `prometeu.json`.
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done (DoD) for PBS v0 “minimum executable”
|
||||
## PR-10 — Dependency Resolver v0: build a resolved project graph
|
||||
|
||||
A single canonical cartridge runs end-to-end:
|
||||
**Why:** We need a deterministic **module graph** from manifest(s) before compiling.
|
||||
|
||||
* `let` declarations (locals)
|
||||
* arithmetic (+, -, *, /, %, comparisons)
|
||||
* `if/else` control flow
|
||||
* `when` expression (if present in lowering)
|
||||
* function calls with params + returns (including `void`)
|
||||
* multiple return slots (flattened structs / hardware value types)
|
||||
* host syscalls (e.g., `GfxClear565`, `InputPadSnapshot`, `InputTouchSnapshot`)
|
||||
* deterministic traps (OOB bounded, invalid local, invalid call target, stack underflow)
|
||||
### Scope
|
||||
|
||||
* Implement `prometeu_compiler::deps::resolver`:
|
||||
|
||||
* Input: root project dir
|
||||
* Output: `ResolvedGraph`
|
||||
* Graph nodes:
|
||||
|
||||
* project identity: `{name, version}`
|
||||
* local alias name (the key used by the parent)
|
||||
* root path in filesystem (after fetch/resolve)
|
||||
* manifest loaded for each node
|
||||
* Resolution rules (v0):
|
||||
|
||||
* DFS/stack walk from root
|
||||
* cycle detection
|
||||
* collision handling:
|
||||
|
||||
* If the same (project name) appears with incompatible versions, error
|
||||
* aliasing:
|
||||
|
||||
* alias is local to the edge, but graph also stores the underlying project identity
|
||||
|
||||
### Deliverables
|
||||
|
||||
* `resolve_graph(root_dir) -> Result<ResolvedGraph, ResolveError>`
|
||||
* `ResolveError` variants:
|
||||
|
||||
* cycle detected (show chain)
|
||||
* missing dependency (path not found / git not fetchable)
|
||||
* version conflict (same project name, incompatible constraints)
|
||||
* name collision (two distinct projects claiming same name)
|
||||
|
||||
### Tests
|
||||
|
||||
* simple root -> dep path graph
|
||||
* cycle detection
|
||||
* alias rename does not change project identity
|
||||
|
||||
### Acceptance
|
||||
|
||||
* Compiler can produce a stable, deterministic dependency graph.
|
||||
|
||||
---
|
||||
|
||||
## PR-11 — Dependency Fetching v0: local cache layout + git/path fetch
|
||||
|
||||
**Why:** Graph resolution needs a concrete directory for each dependency.
|
||||
|
||||
### Scope
|
||||
|
||||
* Implement `prometeu_compiler::deps::fetch`:
|
||||
|
||||
* `fetch_path(dep, base_dir) -> ProjectDir`
|
||||
* `fetch_git(dep, cache_dir) -> ProjectDir`
|
||||
* Define a cache layout:
|
||||
|
||||
* `~/.prometeu/cache/git/<hash>/...` (or configurable)
|
||||
* the dependency is *materialized* as a directory containing `prometeu.json`
|
||||
* For git deps (v0):
|
||||
|
||||
* accept `git` URL + optional `version`
|
||||
* support `version: "latest"` as default
|
||||
* implementation can pin to HEAD for now (but must expose in diagnostics)
|
||||
|
||||
### Deliverables
|
||||
|
||||
* Config option: `PROMETEU_CACHE_DIR` override
|
||||
* Errors:
|
||||
|
||||
* clone failed
|
||||
* missing manifest in fetched project
|
||||
|
||||
### Tests
|
||||
|
||||
* path fetch resolves relative paths
|
||||
* cache path generation deterministic
|
||||
|
||||
### Acceptance
|
||||
|
||||
* Resolver can rely on fetcher to produce directories.
|
||||
|
||||
---
|
||||
|
||||
## PR-12 — Module Discovery v0: find PBS sources per project
|
||||
|
||||
**Why:** Once deps are resolved, the compiler must discover compilation units.
|
||||
|
||||
### Scope
|
||||
|
||||
* Define a convention (v0):
|
||||
|
||||
* `src/**/*.pbs` are source files
|
||||
* `src/main.pbs` for `kind=app` (entry)
|
||||
* Implement `prometeu_compiler::sources::discover(project_dir)`:
|
||||
|
||||
* returns ordered list of source files
|
||||
* Enforce:
|
||||
|
||||
* `kind=app` must have `src/main.pbs`
|
||||
* `kind=lib` must not require `main`
|
||||
|
||||
### Deliverables
|
||||
|
||||
* `ProjectSources { main: Option<Path>, files: Vec<Path> }`
|
||||
|
||||
### Tests
|
||||
|
||||
* app requires main
|
||||
* lib without main accepted
|
||||
|
||||
### Acceptance
|
||||
|
||||
* Compiler can list sources for every node in the graph.
|
||||
|
||||
---
|
||||
|
||||
## PR-13 — Build Plan v0: deterministic compilation order
|
||||
|
||||
**Why:** We need a stable pipeline: compile deps first, then root.
|
||||
|
||||
### Scope
|
||||
|
||||
* Implement `prometeu_compiler::build::plan`:
|
||||
|
||||
* Input: `ResolvedGraph`
|
||||
* Output: topologically sorted build steps
|
||||
* Each step contains:
|
||||
|
||||
* project identity
|
||||
* project dir
|
||||
* sources list
|
||||
* dependency edge map (alias -> resolved project)
|
||||
|
||||
### Deliverables
|
||||
|
||||
* `BuildPlan { steps: Vec<BuildStep> }`
|
||||
|
||||
### Tests
|
||||
|
||||
* topo ordering stable across runs
|
||||
|
||||
### Acceptance
|
||||
|
||||
* BuildPlan is deterministic and includes all info needed to compile.
|
||||
|
||||
---
|
||||
|
||||
## PR-14 — Compiler Output Format v0: emit per-project object module (intermediate)
|
||||
|
||||
**Why:** Linking needs an intermediate representation (IR/object) per project.
|
||||
|
||||
### Scope
|
||||
|
||||
* Define `CompiledModule` (compiler output) containing:
|
||||
|
||||
* `module_name` (project name)
|
||||
* `exports` (functions/symbols)
|
||||
* `imports` (symbol refs by (dep-alias, symbol))
|
||||
* `const_pool` fragment
|
||||
* `code` fragment
|
||||
* `function_metas` fragment
|
||||
* This is **not** the final VM blob.
|
||||
|
||||
### Deliverables
|
||||
|
||||
* `compile_project(step) -> Result<CompiledModule, CompileError>`
|
||||
|
||||
### Tests
|
||||
|
||||
* compile root-only project to `CompiledModule`
|
||||
|
||||
### Acceptance
|
||||
|
||||
* Compiler can produce a linkable unit per project.
|
||||
|
||||
---
|
||||
|
||||
## PR-15 — Link Orchestration v0 inside `prometeu_compiler`
|
||||
|
||||
**Why:** The compiler must produce the final closed-world blob.
|
||||
|
||||
### Scope
|
||||
|
||||
* Move “link pipeline” responsibility to `prometeu_compiler`:
|
||||
|
||||
* Input: `Vec<CompiledModule>` in build order
|
||||
* Output: `ProgramImage` (single bytecode blob)
|
||||
* Define linker responsibilities (v0):
|
||||
|
||||
* resolve imports to exports across modules
|
||||
* assign final `FunctionTable` indices
|
||||
* patch CALL targets to `func_id`
|
||||
* merge const pools deterministically
|
||||
* emit the final PBS v0 module image
|
||||
|
||||
### Deliverables
|
||||
|
||||
* `link(modules) -> Result<ProgramImage, LinkError>`
|
||||
* `LinkError`:
|
||||
|
||||
* unresolved import
|
||||
* duplicate export
|
||||
* incompatible symbol signatures (if available)
|
||||
|
||||
### Tests
|
||||
|
||||
* `archive-pbs/test01` becomes an integration test:
|
||||
|
||||
* root depends on a lib
|
||||
* root calls into lib
|
||||
* output blob runs in VM
|
||||
|
||||
### Acceptance
|
||||
|
||||
* Compiler emits a single executable blob; VM only loads it.
|
||||
|
||||
---
|
||||
|
||||
## PR-16 — VM Boundary Cleanup: remove linker behavior from runtime
|
||||
|
||||
**Why:** Runtime should be dumb: no dependency resolution, no linking.
|
||||
|
||||
### Scope
|
||||
|
||||
* Audit `prometeu_core` + `prometeu_bytecode`:
|
||||
|
||||
* VM loads PBS v0 module
|
||||
* VM verifies (optional) and executes
|
||||
* Remove/disable any linker-like logic in runtime:
|
||||
|
||||
* no search for func idx by address beyond function table
|
||||
* no module graph assumptions
|
||||
|
||||
### Deliverables
|
||||
|
||||
* VM init uses:
|
||||
|
||||
* `BytecodeLoader::load()` => `(code, const_pool, functions)`
|
||||
* verifier as a gate
|
||||
|
||||
### Tests
|
||||
|
||||
* runtime loads compiler-produced blob
|
||||
|
||||
### Acceptance
|
||||
|
||||
* Linking is fully compiler-owned.
|
||||
|
||||
---
|
||||
|
||||
## PR-17 — Diagnostics UX: show dependency graph + resolution trace
|
||||
|
||||
**Why:** When deps fail, we need actionable feedback.
|
||||
|
||||
### Scope
|
||||
|
||||
* Add CLI output (or compiler API output) showing:
|
||||
|
||||
* resolved graph
|
||||
* alias mapping
|
||||
* where a conflict occurred
|
||||
* Add `--explain-deps` mode (or equivalent)
|
||||
|
||||
### Deliverables
|
||||
|
||||
* human-readable resolution trace
|
||||
|
||||
### Tests
|
||||
|
||||
* snapshot tests for error messages (best-effort)
|
||||
|
||||
### Acceptance
|
||||
|
||||
* Users can debug dependency issues without guessing.
|
||||
|
||||
---
|
||||
|
||||
## Suggested execution order
|
||||
|
||||
1. PR-09 → PR-10 → PR-11
|
||||
2. PR-12 → PR-13
|
||||
3. PR-14 → PR-15
|
||||
4. PR-16 → PR-17
|
||||
|
||||
---
|
||||
|
||||
## Notes for Junie
|
||||
|
||||
* Keep all “v0” decisions simple and deterministic.
|
||||
* Favor explicit errors over silent fallback.
|
||||
* Treat `archive-pbs/test01` as the north-star integration scenario.
|
||||
* No background tasks: every PR must include tests proving the behavior.
|
||||
|
||||
Reference in New Issue
Block a user