TML-2841: coordinate-addressing project scaffold — poly variant resolution by namespace coordinate

[tensordreams]

Unblocked 2026-06-12. TML-2816 merged as #720 (additive namespace-aware surface) and #778 (always-qualified sql/orm builder + per-facade db projection). The plan in this PR has been re-anchored to the post-merge codebase; S1 implementation can start.

What

Scaffolds the sql-orm-client coordinate addressing project (projects/sql-orm-coordinate-addressing/): migrate the ORM off its remaining namespace-flat resolution onto the ADR 221 entity coordinate (plane, namespaceId, entityKind, entityName).

Origin: the TML-2683 review surfaced that polymorphic variant resolution is namespace-flat (TML-2841); investigation showed the pin was module-wide, so the operator promoted it to a three-slice project:

1. TML-2841 — polymorphism resolution by coordinate (the irreducible core: a poly base in namespace A with a variant in namespace B; PolymorphismInfo/VariantColumnRef carry {namespace, table}).
2. TML-2845 — cross-namespace polymorphic .include() + relation-road coverage (re-scoped, see below).
3. TML-2846 — retire the last defaulting remnant + grep gate + multi-namespace project-DoD integration pass (re-scoped, see below).

Relationship to TML-2816 (#720 / #778, merged)

TML-2816 delivered the namespace-scoped front door (modelsOf(contract, namespaceId), the multi-namespace throw retired from the collection layer), coordinate-keyed metadata caches, collection-level namespace context, and relation/include namespace threading (rel.to.namespace → toNamespace/relatedNamespaceId through the include builders, decode path, and M:N junction), plus an end-to-end PGlite multi-namespace fixture.

Consequences, recorded in the re-anchored plan.md:

• S1 (TML-2841) is unblocked and sharper: per-namespace-scoped lookups make cross-namespace variant resolution wrong-by-construction — variants are looked up only in the base's namespace (resolvePolymorphismInfo), and bare variant table strings are bound in the base's namespace (buildMtiJoins). This is the gap the project closes on top of TML-2816.
• S2 (TML-2845) lost its original core to TML-2816: always-qualified sql/orm builder + per-facade db projection #778 (relation/include threading landed there); it narrows to the cross-namespace polymorphic include plus integration coverage on the already-landed relation road.
• S3 (TML-2846) narrows to the residue: the orm.ts createCollectionRegistry defaulting remnant, the MTI two-table write, straggler bare-name surfaces, the grep gate, and the project-DoD integration pass.

Contents

projects/sql-orm-coordinate-addressing/spec.md (purpose, non-goals, cross-cutting requirements, project DoD) + plan.md (slice composition, sequencing rationale — loud failure is retired only when resolution is actually correct). Docs only; no code.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 155f2168-4dcd-48e0-8db8-a3e9bf9c3ab7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tml-2841-sql-orm-polymorphic-variant-resolution-is-namespace-flat

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[tensordreams]

Reviewed both docs locally (the plan can't be read on GitHub — see below). Content-wise this is a strong scaffold: the spec's code citations check out (domainModelsAtDefaultNamespace does throw on multi-namespace contracts in domain-namespace-access.ts, the ADR 221 helpers exist and return coordinates as described), the re-anchoring note against #720/TML-2816 is clear about what each slice consumes vs. dissolves, the slice sequencing rationale (front-door throw retired last, in S3, because it's load-bearing) is sound, and the risks section honestly captures the alias-collision and interpreter-materializer limitations.

One fix needed before merge:

projects/sql-orm-coordinate-addressing/plan.md contains a literal NUL byte (0x00) on line 7, inside the cache-key example — the text reads `${ns}<NUL>${model}` where the two-character escape sequence \0 (or a printable separator like @) was presumably intended. The raw NUL makes git and GitHub classify the whole file as binary, so the plan renders as "Binary file not shown" in the PR diff and is unreviewable/un-commentable in the UI (which is also why this review has no inline comments on it). Please replace the raw byte with the literal characters \0 so the file diffs as text.