prometeu-runtime/docs/specs/pbs/files/PRs para Junie.md

PR-13 — Build Plan v0: deterministic compilation order

Why: We need a stable, reproducible pipeline: compile dependencies first, then the root project.

Scope

• Implement prometeu_compiler::build::plan:

  • Input: ResolvedGraph
  • Output: BuildPlan with topologically sorted build steps

• Each BuildStep MUST include:

  • 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

• BuildPlan { steps: Vec<BuildStep> }

Tests

• topo ordering stable across runs
• sources ordering stable regardless of filesystem order

Acceptance

• 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 requires a well-defined intermediate representation per project.

Scope

• Define CompiledModule (compiler output, NOT 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: BuildStep) -> Result<CompiledModule, CompileError>

Tests

• compile root-only project into a valid CompiledModule

Acceptance

• Compiler can emit a deterministic, linkable object module per project.

---

PR-15 — Link Orchestration v0 inside prometeu_compiler

Why: The compiler must emit a single closed-world executable blob.

Scope

• Move all link responsibilities to prometeu_compiler:

  • 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 opcodes to final func_id
  • merge constant pools deterministically
  • emit final PBS v0 image

Deliverables

• link(modules) -> Result<ProgramImage, LinkError>

• LinkError variants:

  • unresolved import
  • duplicate export
  • incompatible symbol signature (if available)

Tests

• archive-pbs/test01 as integration test:

  • root depends on a lib
  • root calls into lib
  • final blob runs successfully in VM

Acceptance

• Compiler emits a single executable blob; VM performs no linking.

---

PR-16 — VM Boundary Cleanup: remove linker behavior from runtime

Why: Runtime must be dumb and deterministic.

Scope

• Audit prometeu_core and prometeu_bytecode:

  • VM loads PBS v0 module
  • VM verifies (optional) and executes

• Remove or disable any linker-like behavior in runtime:

  • no dependency resolution
  • no symbol lookup by name
  • no module graph assumptions

Deliverables

• VM init path uses:

  • BytecodeLoader::load() → (code, const_pool, functions)
  • verifier as an execution gate

Tests

• runtime loads and executes compiler-produced blob

Acceptance

• Linking is fully compiler-owned.

---

PR-17 — Diagnostics UX: dependency graph and resolution trace

Why: Dependency failures must be explainable.

Scope

• Add compiler diagnostics output:

  • resolved dependency graph
  • alias → project mapping
  • explanation of conflicts or failures

• Add CLI/API flag:

  • --explain-deps

Deliverables

• human-readable resolution trace

Tests

• snapshot tests for diagnostics output (best-effort)

Acceptance

• Users can debug dependency and linking issues without guesswork.

---

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.
• Prefer explicit errors over silent fallback.
• Treat archive-pbs/test01 as the north-star integration scenario.
• No background work: every PR must include tests proving behavior.