144 lines
4.5 KiB
Markdown
144 lines
4.5 KiB
Markdown
# 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.05 — Canonical export surface: `ExportItem` (no `svc:` / no `name#sig` strings)
|
||
|
||
### Title
|
||
|
||
Replace stringy export naming with canonical `ExportItem` model
|
||
|
||
### Briefing / Context
|
||
|
||
Exports are currently keyed by `(module_path, symbol_name string, kind)` where symbol_name embeds `#sig` and/or owner names. This is fragile and couples FE naming to BE behavior.
|
||
|
||
### Target
|
||
|
||
* BE export map keys are canonical:
|
||
|
||
* `ExportItem::Type { name }`
|
||
* `ExportItem::Service { name }`
|
||
* `ExportItem::Function { fn_key: CanonicalFnKey }`
|
||
* Export surface remains stable even if we later change display formatting.
|
||
|
||
### Scope
|
||
|
||
* Update compiled module export structures.
|
||
* Update dependency symbol synthesis to use canonical export items.
|
||
* Update linker relocation labels to reference canonical export items.
|
||
|
||
### Checklist
|
||
|
||
* [ ] Introduce `ExportItem` and migrate ExportKey.
|
||
* [ ] Update dependency export synthesis.
|
||
* [ ] Update linker/import label format (if used) to canonical encoding.
|
||
* [ ] Ensure backward compatibility is explicitly NOT required for Phase 03.
|
||
|
||
### Tests
|
||
|
||
* Unit: exporting a service method yields `ExportItem::Function { owner=Log, name=debug, sig=... }`.
|
||
* Integration: build root + dep, link, run golden.
|
||
|
||
### Risk
|
||
|
||
High. Touches serialization and linking labels.
|
||
|
||
---
|
||
|
||
## 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. |