This commit is contained in:
Nilton Constantino
2026-02-02 13:54:01 +00:00
parent 99d3dc38a1
commit 6732111328
15 changed files with 571 additions and 167 deletions
+79 -88
View File
@@ -1,52 +1,31 @@
## 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.
**Why:** We need a stable, reproducible pipeline: compile dependencies first, then the root project.
### Scope
* Implement `prometeu_compiler::build::plan`:
* Input: `ResolvedGraph`
* Output: topologically sorted build steps
* Each step contains:
* **Input:** `ResolvedGraph`
* **Output:** `BuildPlan` with topologically sorted build steps
* Each `BuildStep` MUST include:
* project identity
* project dir
* sources list
* dependency edge map (alias -> resolved project)
* `project_id` — canonical project identity (`prometeu.json.name`)
* `project_dir` — absolute or normalized path
* `target` — `main` or `test`
* `sources` — ordered list of `.pbs` source files (from `src/<target>/modules`)
* `deps` — dependency edge map: `alias -> ProjectId`
### Determinism Rules (MANDATORY)
* Topological sort must be stable:
* when multiple nodes have indegree 0, choose by lexicographic `project_id`
* `sources` list must be:
* discovered only under `src/<target>/modules`
* sorted lexicographically by normalized relative path
* `deps` must be stored/exported in deterministic order (e.g. `BTreeMap`)
### Deliverables
@@ -55,109 +34,118 @@
### Tests
* topo ordering stable across runs
* sources ordering stable regardless of filesystem order
### Acceptance
* BuildPlan is deterministic and includes all info needed to compile.
* BuildPlan is deterministic and contains all information needed to compile without further graph traversal.
---
## PR-14 — Compiler Output Format v0: emit per-project object module (intermediate)
**Why:** Linking needs an intermediate representation (IR/object) per project.
**Why:** Linking requires a well-defined intermediate representation per project.
### Scope
* Define `CompiledModule` (compiler output) containing:
* Define `CompiledModule` (compiler output, **NOT** final VM blob):
* `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.
* `project_id` — canonical project name
* `target` — `main` or `test`
* `exports` — exported symbols (`pub`) indexed by `(module_path, symbol_name, kind)`
* `imports` — symbol references as:
* `(dep_alias, module_path, symbol_name)`
* `const_pool` — constant pool fragment
* `code` — bytecode fragment
* `function_metas` — local function metadata fragment
* No linking or address patching occurs here.
### Deliverables
* `compile_project(step) -> Result<CompiledModule, CompileError>`
* `compile_project(step: BuildStep) -> Result<CompiledModule, CompileError>`
### Tests
* compile root-only project to `CompiledModule`
* compile root-only project into a valid `CompiledModule`
### Acceptance
* Compiler can produce a linkable unit per project.
* Compiler can emit a deterministic, linkable object module per project.
---
## PR-15 — Link Orchestration v0 inside `prometeu_compiler`
**Why:** The compiler must produce the final closed-world blob.
**Why:** The compiler must emit a single closed-world executable blob.
### Scope
* Move “link pipeline” responsibility to `prometeu_compiler`:
* Move all link responsibilities to `prometeu_compiler`:
* Input: `Vec<CompiledModule>` in build order
* Output: `ProgramImage` (single bytecode blob)
* Define linker responsibilities (v0):
* **Input:** `Vec<CompiledModule>` (in build-plan order)
* **Output:** `ProgramImage` (single PBS v0 bytecode blob)
* Linker responsibilities (v0):
* resolve imports to exports across modules
* validate symbol visibility (`pub` only)
* assign final `FunctionTable` indices
* patch CALL targets to `func_id`
* merge const pools deterministically
* emit the final PBS v0 module image
* patch `CALL` opcodes to final `func_id`
* merge constant pools deterministically
* emit final PBS v0 image
### Deliverables
* `link(modules) -> Result<ProgramImage, LinkError>`
* `LinkError`:
* `LinkError` variants:
* unresolved import
* duplicate export
* incompatible symbol signatures (if available)
* incompatible symbol signature (if available)
### Tests
* `archive-pbs/test01` becomes an integration test:
* `archive-pbs/test01` as integration test:
* root depends on a lib
* root calls into lib
* output blob runs in VM
* final blob runs successfully in VM
### Acceptance
* Compiler emits a single executable blob; VM only loads it.
* Compiler emits a single executable blob; VM performs no linking.
---
## PR-16 — VM Boundary Cleanup: remove linker behavior from runtime
**Why:** Runtime should be dumb: no dependency resolution, no linking.
**Why:** Runtime must be dumb and deterministic.
### Scope
* Audit `prometeu_core` + `prometeu_bytecode`:
* Audit `prometeu_core` and `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
* Remove or disable any linker-like behavior in runtime:
* no dependency resolution
* no symbol lookup by name
* no module graph assumptions
### Deliverables
* VM init uses:
* VM init path uses:
* `BytecodeLoader::load()` => `(code, const_pool, functions)`
* verifier as a gate
* `BytecodeLoader::load()` → `(code, const_pool, functions)`
* verifier as an execution gate
### Tests
* runtime loads compiler-produced blob
* runtime loads and executes compiler-produced blob
### Acceptance
@@ -165,18 +153,21 @@
---
## PR-17 — Diagnostics UX: show dependency graph + resolution trace
## PR-17 — Diagnostics UX: dependency graph and resolution trace
**Why:** When deps fail, we need actionable feedback.
**Why:** Dependency failures must be explainable.
### Scope
* Add CLI output (or compiler API output) showing:
* Add compiler diagnostics output:
* resolved graph
* alias mapping
* where a conflict occurred
* Add `--explain-deps` mode (or equivalent)
* resolved dependency graph
* alias → project mapping
* explanation of conflicts or failures
* Add CLI/API flag:
* `--explain-deps`
### Deliverables
@@ -184,15 +175,15 @@
### Tests
* snapshot tests for error messages (best-effort)
* snapshot tests for diagnostics output (best-effort)
### Acceptance
* Users can debug dependency issues without guessing.
* Users can debug dependency and linking issues without guesswork.
---
## Suggested execution order
## Suggested Execution Order
1. PR-09 → PR-10 → PR-11
2. PR-12 → PR-13
@@ -203,7 +194,7 @@
## Notes for Junie
* Keep all “v0” decisions simple and deterministic.
* Favor explicit errors over silent fallback.
* Keep all v0 decisions simple and deterministic.
* Prefer 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.
* No background work: every PR must include tests proving behavior.