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

PR-09 — Add prometeu.json manifest parser + schema validation

Why: Dependency resolution cannot exist without a stable project manifest.

Scope

• Implement prometeu_compiler::manifest module:

  • Manifest struct mirroring the spec fields:

    • 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

• Compiler can reliably load + validate prometeu.json.

---

PR-10 — Dependency Resolver v0: build a resolved project graph

Why: We need a deterministic module graph from manifest(s) before compiling.

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.