prometeu-runtime/files/Hard Reset FE API.md

Phase 03 – Rigid Frontend API & PBS Leak Containment (Junie PR Templates)

Goal: finish Phase 03 with JVM-like discipline by making the Backend (BE) the source of truth and forcing the PBS Frontend (FE) to implement a strict, minimal, canonical contract (frontend-api).

Strategy: surgical PRs that (1) stop PBS types from leaking, (2) replace stringy protocols with canonical models, and (3) make imports/exports/overloads deterministic across deps.

Notes / Operating Rules (for Junie)

1. BE is the source of truth: frontend-api defines canonical models; FE conforms.
2. No string protocols across layers. Strings may exist only as display/debug.
3. No FE implementation imports from other FE implementations.
4. No BE imports PBS modules (hard boundary).
5. Overload resolution is signature-based (arity alone is not valid).

---

PR-03.06 — Deterministic overload resolution across deps (arity is not enough)

Title

Implement deterministic overload selection using canonical signature matching

Briefing / Context

We currently try to disambiguate overloads by arity as a fallback. That’s not sufficient (same arity, different types). For Phase 03 “professional grade”, overload resolution must be deterministic and match by full signature.

Target

• Imported method call selects overload by:

  1. resolve callee symbol → candidate set
  2. typecheck args → determine expected param types
  3. choose exact match
  4. otherwise E_OVERLOAD_NOT_FOUND or E_OVERLOAD_AMBIGUOUS deterministically

Scope

• PBS FE typechecker must provide enough info to compute signature selection.
• Resolver must expose all overload candidates for an imported ImportRef item.
• Lowering uses canonical fn key and selected SigId.

Checklist

• Ensure imported service methods are actually present in imported symbol arena.
• Ensure candidates include (owner, name, sig) not just name.
• Implement exact-match algorithm.
• Implement deterministic ambiguity ordering for diagnostics.

Tests

• Add golden regression reproducing Log.debug failure:

  • dep exports service Log { debug(string) }
  • root imports Log and calls Log.debug("x")

• Add tests for:

  • ambiguous same signature
  • not found

Risk

Medium/High. Needs clean integration across resolver/typechecker/lowering.

---

PR-03.07 — Phase 03 cleanup: remove legacy compatibility branches and document boundary

Title

Remove legacy string protocol branches and document FE/BE boundary rules

Briefing / Context

After canonical models are in place, we must delete compatibility code paths (alias/module, svc: prefixes, prefix matching, etc.) to prevent regressions.

Target

• No legacy synthetic module path support.
• No string prefix matching for overloads.
• Documentation: “BE owns the contract; FE implements it.”

Scope

• Delete dead code.
• Add docs/phase-03-frontend-api.md (or in-crate docs) summarizing invariants.
• Add CI/lints to prevent BE from importing PBS modules.

Checklist

• Remove legacy branches.
• Add boundary docs.
• Add lint/CI guard.

Tests

• Full workspace tests.
• Golden tests.

Risk

Low/Medium. Mostly deletion + docs, but could expose hidden dependencies.