This commit is contained in:
2026-03-24 13:40:33 +00:00
parent 2ba8507284
commit a4cc1487c4
8 changed files with 48 additions and 126 deletions
+7 -116
View File
@@ -4,112 +4,13 @@
>
> 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)
## PR-03.03 — Canonical import syntax → `ImportRef` (no dual styles)
### Title
Define single canonical import model and parse PBS imports into `ImportRef`
### Briefing / Context
We currently support multiple synthetic import path styles (`"alias/module"` and `"@alias:module"`). This amplifies ambiguity and is a root cause of mismatch in imported service method overloads.
We want **one** canonical representation:
* PBS syntax: `import { Test } from "@sdk:input/testing"`
* Canonical model: `ImportRef { project: "sdk", module: "input/testing", item: "Test" }`
### Target
* PBS FE produces a list of canonical `ImportRef`.
* BE consumes only `ImportRef`.
* Remove support for dual synthetic path style in the BE pipeline.
### Scope
* In PBS FE:
* Parse `@<alias>:<module_path>` into `ImportRef`.
* Validate module path normalization.
* Validate that `item` is a single symbol name (service/struct/host/contract/etc).
* In BE:
* Replace “synthetic path generation” with canonical module lookup using `(alias, module_path)`.
### Out of scope
* Export naming canonicalization (PR-03.04/03.05).
### Checklist
* [ ] Implement import parser → `ImportRef`.
* [ ] Remove `alias/module` synthetic path support.
* [ ] Update resolver/module-provider lookup to accept `(alias, module_path)`.
* [ ] Add diagnostics for invalid import string.
### Tests
* Unit tests in PBS FE for:
* valid: `"@sdk:input/testing"`
* invalid forms
* normalization edge cases (leading `/`, `./`, `\\` on Windows paths)
* Integration test (golden-style) compiling a small project importing a service.
### Risk
Medium. Changes import resolution plumbing.
---
## PR-03.04 — Canonical function identity: `CanonicalFnKey` (JVM-like)
### Title
Introduce canonical function identity for exports/import calls (no string prefix matching)
### Briefing / Context
Phase 03 currently tries to match overloads using `name#sigN` strings + prefix logic + origin checks. This breaks easily and is exactly what produced `E_OVERLOAD_NOT_FOUND` for `Log.debug`.
We need a **canonical function key** that is not “string protocol”:
* `CanonicalFnKey { owner: Option<ItemName>, name: ItemName, sig: SigId }`
* Free fn: `owner=None, name=foo, sig=...`
* Service method: `owner=Some(Log), name=debug, sig=...`
### Target
* BE uses `CanonicalFnKey` for export surface and import relocation.
* FE supplies `owner/name` and produces/requests signatures deterministically.
### Scope
* Add `CanonicalFnKey` to `frontend-api`.
* Update VM import call instruction payload to carry canonical pieces:
* `ImportCall { dep_alias, module_path, fn_key: CanonicalFnKey, arg_count }`
* (or equivalent)
* Eliminate string matching / prefix matching for overload selection.
### Checklist
* [ ] Define `CanonicalFnKey` and helpers.
* [ ] Update IR / bytecode instruction structures if needed.
* [ ] Update lowering call sites.
* [ ] Ensure debug info keeps readable names (owner.name).
### Tests
* Unit: canonical formatting for debug name `Log.debug`.
* Integration: two overloads of `Log.debug` across deps resolved by exact signature.
### Risk
High-ish. Touches instruction encoding and matching logic.
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).
---
@@ -240,14 +141,4 @@ After canonical models are in place, we must delete compatibility code paths (`a
### Risk
Low/Medium. Mostly deletion + docs, but could expose hidden dependencies.
---
# 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).
Low/Medium. Mostly deletion + docs, but could expose hidden dependencies.