feat: explicit { namespace, model } pairs on every cross-namespace reference (TML-2624)

[wmadden]

At a glance

Every cross-namespace reference in the emitted contract now carries an explicit { namespace, model } pair, with the namespace field branded as NamespaceId at the type level. The bare-string shape is gone from emitter output.

 // contract.json — roots
 "roots": {
-  "post": "Post",
-  "task": "Task",
-  "user": "User"
+  "post": { "namespace": "__unbound__", "model": "Post" },
+  "task": { "namespace": "__unbound__", "model": "Task" },
+  "user": { "namespace": "__unbound__", "model": "User" }
 }

 // contract.d.ts — relation.to
 readonly user: {
-  readonly to: 'User';
+  readonly to: { readonly namespace: '__unbound__' & NamespaceId; readonly model: 'User' };
   readonly cardinality: 'N:1';
   ...
 };

The same shape applies to model.base (the target of extends), every relation.to, every entry in roots, and foreign-key targets (which additionally carry tableName and columns).

Why

Before this change, a cross-namespace reference like "to": "Order" was a bare model name. As soon as namespaces became first-class (the parent project, TML-2584), bare names became ambiguous: Order in public vs Order in analytics would silently collide, and the only way to disambiguate at the consumer was per-call-site fallback logic. The fix is to encode the coordinate fully on the wire, in one place, once.

What this PR commits to

• Every cross-reference carries both namespace and model. There is no optional namespace and no implicit same-namespace fallback. Ambiguous bare-string targets are rejected at validation time — one deserialization path, no silent-collision branch.
• The namespace field is branded NamespaceId in emitted .d.ts. Type-level distinction from a plain string; existing code paths that previously passed a raw string now typecheck-fail rather than silently consume the wrong shape.
• Codec aliases move from storage.types to domain.__unbound__.types. Codec aliases describe domain-side content (which scalars and objects exist in the type system); they don't belong on a document-scoped storage envelope. Placing them in the unbound domain namespace makes them namespace-addressable without widening the cross-reference collision surface.
• The user-facing DSL is unchanged. belongsTo, extends, and roots keep their existing authoring signatures. The lowering layer reads the in-scope namespace map and emits the object-pair shape.

What this PR does NOT do

• Pre-existing migration bookends are not rewritten. Older start-contract.json / end-contract.json snapshots under examples/*/migrations/** keep their bare-string shape. The migration-chain replay test (examples/retail-store/test/migration-chain.test.ts) verifies they still hydrate end-to-end against the new framework. Rewriting them would mean re-planning historical migrations against a shape they were never written against; we'll do that only if a replay starts failing. (~62 bare-string hits remain inside bookends; zero outside.)
• The sql-context.ts codec-alias dual-read stays in place. It reads both storage.types (legacy) and domain.__unbound__.types (new) so consumers don't break mid-migration. Retiring it requires removing storage.types from the schema entirely; tracked as TML-2699.
• No deprecation shims for the bare-string shape on the wire. Emitted contracts always use the object-pair shape. Hard cut, intentional — the parent project (TML-2584) committed to this.

Validation

Gate	Result	Notes
pnpm install --frozen-lockfile	PASS	exit 0
pnpm fixtures:emit	PASS	exit 0; pnpm-lock.yaml diff 0 lines post-emit
pnpm fixtures:check	PASS	exit 0
Migration-chain replay (retail-store m1→m3)	PASS	validates pre-existing bookends still hydrate
Verification greps (bare-string to/base/roots, plus storage.types codec aliases)	PASS outside bookends	0 hits outside examples/*/migrations/**; 62 inside (see "What this PR does NOT do")
Extension migration metadata on re-emit	PASS	no head.json drift for pgvector / postgis / paradedb / cipherstash
pnpm test:packages (local)	PARTIAL	targeted packages green; full-monorepo run has unrelated integration/env noise
pnpm test:integration (local)	PARTIAL	832 passed; failures dominated by example build/typecheck noise unrelated to cross-reference shape

PARTIAL means: the tests directly exercising cross-reference encoding are green; other failures observed locally are environmental (Postgres parallel infra, example build cache, etc.) and don't reproduce in CI. CI is the merge gate.

Follow-ups (not blocking this PR)

• TML-2699 — retire the sql-context.ts codec-alias dual-read once storage.types is removed from the schema.
• TML-2698 — chain the per-extension migration regen loop into pnpm fixtures:emit (each extension currently hand-runs it).
• TML-2686 — namespace-aware enum planning (deferred).
• TML-2634, TML-2636, TML-2667 — assorted deferred cleanups (plural-slot rename, namespace .entries redirect, SQLite Postgres-enum cleanup).

Alternatives considered

• Optional namespace with same-namespace fallback. Rejected: re-introduces the silent-collision branch the encoding change exists to eliminate. Every consumer would need fallback logic, and fallback logic is exactly where collision bugs live.
• Regenerate all migration bookends in this PR. Rejected while replay is green: rewriting historical bookend snapshots changes the semantics of past migrations against a shape they were never written against. Replay-first means we only rewrite when replay actually fails.
• Tighten the sql-context.ts dual-read in this PR. Rejected: dropping the legacy read requires removing storage.types from the schema (prerequisite for TML-2699), and we're not making that schema change here.
• Per-file manual fixture edits instead of pnpm fixtures:emit. Rejected: defeats byte-stability — the next emit-driven change would diff against the hand-edited shape and we'd lose the invariant that emitter output is reproducible.

Summary by CodeRabbit

• New Features

  • Added support for namespace-qualified model references in contracts, enabling proper handling of models across different namespaces.

• Documentation

  • Updated commit workflow guidance with DCO (Developer Certificate of Origin) signature requirements.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Contracts adopt structured CrossReference with NamespaceId for roots, relations, and bases. Core types, schemas, validators, emitters, authoring/builders, runtimes, and query builders are updated; generated DTS/JSON and examples regenerated; tests and docs adjusted, plus DCO guidance added.

Changes

Cross-reference and namespace-aware contracts

Layer / File(s)	Summary
Core types and validation updates packages/1-framework/0-foundation/contract/*, packages/2-*/1-foundation/*	Introduce CrossReference/NamespaceId, update Contract/domain types, schemas, and validators; canonicalization preserves domain typeParams.
Emitters and generators packages/*/3-tooling/emitter/*	Emit DTS/JSON with namespace+model refs; add serializers; adjust structure validation and namespace kind handling.
Authoring/builders packages/2-*/2-authoring/*	Contract builders/interpreters emit CrossReference for roots/relations/base; SQL adds document-scoped domain types.
Runtimes and query builders packages/2-mongo-family/5-query-builders/*, packages/2-sql/5-runtime/*	Resolve targets via ref.to.model; tighten typings with RootModelName; prefer document-scoped types at runtime.
Generated artifacts and examples examples/*, apps/*, packages/3-extensions/*, test/integration/*	Regenerate contract.d.ts/json across demos/extensions to use namespace+model roots/relations/base; storage hashes updated where applicable.
Tests and fixtures packages/*/test/*	Adapt tests to CrossReference shapes, new serializers, and document-scoped types; add round-trip checks.
Docs/process drive/retro/findings.md, drive/pr/README.md	Retro findings added; PR guide adds DCO Signed-off-by requirement and verification steps.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Suggested reviewers

• jkomyno

Poem

I hop through roots where models dwell,
Namespaces stitched with CrossRef’s spell.
From stringy paths to typed embrace,
Each “to” now knows its proper place.
Emit, validate, then run—no fuss!
Thump-thump—our schemas trust in us. 🥕🐇

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tml-2624-s1c-cross-reference-encoding

[coderabbitai]

Actionable comments posted: 19

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

packages/1-framework/0-foundation/contract/src/validate-domain.ts (1)

45-56: ⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Validate CrossReference using both namespace and model, not model alone.

The updated checks still resolve references by model only, so a wrong namespace can pass validation. This weakens the new object-pair migration and can silently accept invalid cross-namespace links.

Also applies to: 79-82, 88-92, 113-116, 167-168

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/1-framework/0-foundation/contract/src/validate-domain.ts` around
lines 45 - 56, The root/CrossReference validation currently checks models by
model name only; change it to validate and dedupe using the combined namespace
and model (e.g., build a qualified key `${crossRef.namespace}:${modelName}` and
use that to check membership in the model set and in seenValues), update the
error messages to include namespace (e.g., "Root \"rootKey\" references model
\"namespace:model\" which does not exist"), and apply the same fix to the other
crossRef checks referenced (the loops/blocks around the other occurrences) so
every reference resolves against namespace+model rather than model alone.

packages/2-mongo-family/5-query-builders/query-builder/src/lookup-builder.ts (1)

140-147: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fail fast when a root references a non-existent model.

This path validates missing roots, but if modelName exists and is not present in contract.models, it currently falls back and continues. That can silently build lookups against the wrong collection.

Suggested patch

   const callable = ((rootName) => {
     const modelName = contract.roots[rootName]?.model;
     if (!modelName) {
       const validRoots = Object.keys(contract.roots).join(', ');
       throw new Error(`lookup() unknown root: "${rootName}". Valid roots: ${validRoots}`);
     }
     const model = contract.models[modelName];
+    if (!model) {
+      throw new Error(`lookup() unknown model: "${modelName}" referenced by root "${rootName}"`);
+    }
-    const foreignCollection = model?.storage?.collection ?? rootName;
+    const foreignCollection = model.storage?.collection ?? rootName;
     return createLookupBuilder({
       rootName,
       modelName,
       foreignCollection,
     });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/2-mongo-family/5-query-builders/query-builder/src/lookup-builder.ts`
around lines 140 - 147, The code currently allows a root to reference a model
name that isn't present in contract.models and then silently uses the rootName
as the collection; update the lookup path to fail fast: after computing
modelName from contract.roots[rootName]?.model, if modelName exists but
contract.models[modelName] is undefined, throw a descriptive Error (e.g.
"lookup() unknown model: \"<modelName>\" referenced by root \"<rootName>\"")
instead of continuing; locate this logic around the
modelName/model/foreignCollection code in lookup() and ensure
createLookupBuilder is only called when contract.models[modelName] is defined.

🧹 Nitpick comments (1)

packages/1-framework/0-foundation/contract/test/canonicalization.test.ts (1)

3-7: ⚡ Quick win

Use the shared crossRef factory from source to avoid default drift in tests.

This local helper defaults to "default", while the production helper defaults to "__unbound__". Reusing the source factory keeps fixtures aligned with runtime conventions.

Proposed change

-import { asNamespaceId } from '../src/namespace-id';
-
-function crossRef(model: string, namespace = 'default') {
-  return { namespace: asNamespaceId(namespace), model };
-}
+import { crossRef } from '../src/cross-reference';

Also applies to: 100-101

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/1-framework/0-foundation/contract/test/canonicalization.test.ts`
around lines 3 - 7, Replace the local test helper that defaults to "default"
with the shared crossRef factory from the source so tests use the runtime
default "__unbound__"; remove the local function and import the exported
crossRef factory from the source module (instead of asNamespaceId-only) and
update any uses (including the occurrences around lines 100-101) to call that
imported crossRef to avoid default-drift between tests and production.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/1-framework/3-tooling/emitter/src/domain-type-generation.ts`:
- Around line 107-108: The code in generateModelRelationsType currently uses a
bare cast relObj['to'] as CrossReference when calling serializeCrossReference;
update the types so relObj is recognized as a properly typed ContractRelation
(via ContractModel['relations'] / ContractRelation union) and remove the cast by
accessing rel.to directly. Specifically, ensure the relations property and the
local variable for each relation are typed to include ContractReferenceRelation
and ContractEmbedRelation (both having to: CrossReference), then call
serializeCrossReference(rel.to) instead of casting relObj['to'].

In `@packages/1-framework/3-tooling/emitter/src/generate-contract-dts.ts`:
- Around line 91-97: The generated .d.ts can reference CrossReference from
generateRootsType(), so update the import block in generate-contract-dts.ts to
include CrossReference alongside the existing types (Contract as ContractType,
ExecutionHashBase, NamespaceId, ProfileHashBase, StorageHashBase); this ensures
the emitted Record<string, CrossReference> type is resolved—locate the import
statement near the top of generate-contract-dts.ts and add CrossReference to
that named import list.

In
`@packages/2-mongo-family/2-authoring/contract-psl/test/interpreter.polymorphism.test.ts`:
- Around line 190-192: The assertion comparing Object.values(ir.roots) to the
string 'Bug' is a false positive because roots now hold CrossReference objects;
update the two assertions to inspect the actual root names instead of raw values
— e.g., assert that neither the keys of ir.roots nor the dereferenced target
name on CrossReference objects (use the CrossReference property that holds the
target name) equals 'Bug'. Locate the checks around ir.roots and replace the
toContain/toHaveProperty check with logic that maps Object.values(ir.roots) to
their target names (or simply assert on Object.keys(ir.roots)) and then assert
that 'Bug' is not present.

In
`@packages/2-mongo-family/2-authoring/contract-ts/test/contract-builder.dsl.test.ts`:
- Around line 57-60: The test's roots assertion is inconsistent: `users` uses
crossRef('User') but `posts` is still a plain string; update the expectation in
the `expect(contract.roots)` assertion to use `crossRef('Post')` for `posts` so
both roots follow the CrossReference shape (use the existing `crossRef` helper
referenced in the test).

In `@packages/2-mongo-family/3-tooling/emitter/test/emitter-hook.e2e.test.ts`:
- Around line 34-37: The assertion for posts is still expecting a plain string;
update the expect(types).toContain for "posts" in emitter-hook.e2e.test.ts to
match the CrossReference shape used by users — e.g. assert that types contains
"readonly posts: { readonly namespace: '__unbound__' & NamespaceId; readonly
model: 'Post' }" so it mirrors the users cross-reference format used in the
test.

In
`@packages/2-mongo-family/3-tooling/emitter/test/emitter-hook.generation.test.ts`:
- Around line 93-97: The test asserts mixed root encodings: `users` was migrated
to the CrossReference object form but `posts` still expects the old `'Post'`
string; update the second expectation so both roots use the same `{ namespace,
model }` shape (mirror the `users` expectation pattern) by replacing the
`"readonly posts: 'Post'"` expectation with a string assertion matching the
object-pair encoding, e.g. `"readonly posts: { readonly namespace: '__unbound__'
& NamespaceId; readonly model: 'Post' }"`, so both expectations use the migrated
CrossReference object format.

In `@packages/2-mongo-family/3-tooling/emitter/test/fixtures/blog-contract.ts`:
- Line 60: The fixture incorrectly sets owner to crossRef('Post') but
validateStructure expects the owner field to be a model-name string; update the
fixture in blog-contract.ts so the owner property is the literal string "Post"
(not crossRef('Post')), keeping all other fields intact so validateStructure
will accept it.

In `@packages/2-mongo-family/5-query-builders/orm/src/mongo-orm.ts`:
- Around line 31-39: The loop that assigns client[rootName] using
createMongoCollection should first guard that rootRef.model exists to fail fast;
in the block iterating over Object.entries(contract.roots) check that
rootRef.model is defined (for the given rootName) and if not throw a clear Error
indicating the missing/stale root model for that root (include rootName and
contract identifier), otherwise proceed to call createMongoCollection as before;
update the code around the client[rootName] assignment in mongo-orm.ts to
perform this explicit existence check before calling createMongoCollection.

In `@packages/2-sql/1-core/contract/src/validators.ts`:
- Around line 137-142: The schema uses a bare cast "as
Type<ForeignKeyReferenceInput>" which bypasses proper typing; replace that
pattern by declaring the generic with the validator builder: use
type.declare<ForeignKeyReferenceInput>().type({...}) instead of the cast so
ForeignKeyReferenceSchema is constructed with strong typing; update the current
ForeignKeyReferenceSchema definition to call
type.declare<ForeignKeyReferenceInput>().type({ '+': 'reject', namespaceId:
'string', tableName: 'string', columns: type.string.array().readonly() }) and
remove the "as Type<...>" cast.

In `@packages/2-sql/2-authoring/contract-psl/test/fixtures.ts`:
- Around line 490-498: The function documentScopedTypes should stop using the
unsafe cast on contract.storage: update the contract parameter type to declare
storage as { readonly types?: Readonly<Record<string, unknown>> } (or a
compatible type matching SqlStorage.types) so you can remove the cast and
replace const storageTypes = (contract.storage as ...)?.types with const
storageTypes = contract.storage?.types; keep the rest of documentScopedTypes and
the UNBOUND_NAMESPACE_ID lookup unchanged.

In `@packages/2-sql/2-authoring/contract-ts/src/contract-builder.ts`:
- Around line 251-253: The wrapper buildContractFromDsl currently uses a
forbidden blind cast to convert buildSqlContractFromDefinition's
Contract<SqlStorage> into SqlContractResult<Definition>; instead, make the
builder and overload types consistent so no cast is needed: change
buildContractFromDsl to be generic and return SqlContractResult<Definition>
directly by updating buildSqlContractFromDefinition (or its exported type) to
produce a SqlContractResult<Definition>/Contract result that matches
SqlContractResult, and update the defineContract overloads to be generic over
the provided scaffold/definition (not concrete ContractInput) so callers keep
their inferred scaffold types (i.e., make defineContract overload signatures
return SqlContractResult<TDefinition> or equivalent generic result type). Remove
the "as unknown as" cast and ensure all related type aliases (SqlContractResult,
ContractInput, Contract<SqlStorage>) align with the new generic signatures.

In
`@packages/2-sql/2-authoring/contract-ts/test/contract-builder.dsl.types.test.ts`:
- Line 2: Restore compile-time type assertions by importing and using
expectTypeOf from 'vitest' in contract-builder.dsl.types.test.ts and add
assertions for the defineContract result: assert contract.target and
contract.targetFamily with expectTypeOf(contract.target).toEqualTypeOf<...>() /
toMatchTypeOf as appropriate, and assert the model storage table type with
expectTypeOf(contract.models.User.storage.table).toEqualTypeOf<'YourExpectedLiteralOrWidenedType'>();
also remove or replace the manual cast on contract.models so the type-check
exercises the defineContract boundary (keep the literal if the DSL preserves it,
otherwise assert the widened type).

In `@packages/2-sql/2-authoring/contract-ts/test/cross-ref-helpers.ts`:
- Around line 10-12: Tighten the unsafe cast on contract.storage by either
updating the contract parameter/type definition so storage is typed as {
readonly types?: Record<string, unknown> } | undefined, or add a local type
guard before accessing types (e.g., check typeof contract.storage === 'object'
&& contract.storage !== null && 'types' in contract.storage) and then read
contract.storage.types into storageTypes; replace the current raw cast used when
initializing storageTypes to avoid the bare `as` cast on contract.storage.

In `@packages/3-extensions/paradedb/src/contract.d.ts`:
- Around line 22-28: The file imports NamespaceId but omits the CrossReference
type which is used by the readonly roots: Record<string, CrossReference>;
declaration; update the import statement in contract.d.ts to remove the unused
NamespaceId and add CrossReference from '`@prisma-next/contract/types`' so the
roots type resolves correctly and no unused imports remain.

In
`@packages/3-extensions/pgvector/migrations/20260601T0000_install_vector_extension/end-contract.d.ts`:
- Line 75: The generated declaration references the type CrossReference in the
line "roots: Record<string, CrossReference>" but never imports it; add an
explicit type import for CrossReference (e.g. import type { CrossReference }
from '`@prisma-next/contract/types`';) at the top of the generated
end-contract.d.ts so the identifier is in scope and typechecking succeeds, and
apply the same import to the other generated end-contract.d.ts that has the same
Record<string, CrossReference> usage.

In `@packages/3-extensions/pgvector/src/contract.d.ts`:
- Line 75: The generated contract.d.ts declares "readonly roots: Record<string,
CrossReference>" but doesn't import CrossReference; update the top import type
list (import type { ... } from '`@prisma-next/contract/types`';) to include
CrossReference so the type is resolved. Locate the import in
packages/3-extensions/pgvector/src/contract.d.ts and add CrossReference to the
named imports, then re-run the generator if this file is produced by tooling to
persist the change.

In
`@packages/3-extensions/postgis/migrations/20260601T0000_install_postgis_extension/end-contract.d.ts`:
- Line 75: The file end-contract.d.ts references the CrossReference type in the
roots property (readonly roots: Record<string, CrossReference>) but does not
import it; add an import for CrossReference from the package that exports it
(e.g., import { CrossReference } from '`@prisma-next/contract/types`') so the type
is available for the roots declaration and update the generated import list
accordingly.

In `@packages/3-extensions/postgis/src/contract.d.ts`:
- Around line 22-28: The roots type references CrossReference but CrossReference
is not imported; update the top import type block that currently imports
Contract, ExecutionHashBase, NamespaceId, ProfileHashBase, StorageHashBase from
'`@prisma-next/contract/types`' to also include CrossReference so the type
declaration for roots can resolve (ensure the symbol CrossReference is added to
that import list).

In `@packages/3-extensions/sql-orm-client/src/collection-contract.ts`:
- Around line 265-269: The current code uses a bare cast "const rel = value as {
to?: CrossReference; cardinality?: unknown; on?: { localFields?: unknown;
targetFields?: unknown } }" which is unsafe; replace it with a proper type guard
or the project's cast helper to narrow safely: implement an
isCrossReferenceShape(value): value is { to?: CrossReference; cardinality?:
unknown; on?: { localFields?: unknown; targetFields?: unknown } } that checks
the expected keys/types (or call blindCast<T,'reason'> / castAs<T> from
`@prisma-next/utils/casts`) and then use that guard to assign/narrow `rel` before
using it, updating the code paths that reference `rel`, `value`, and
`CrossReference` accordingly.

---

Outside diff comments:
In `@packages/1-framework/0-foundation/contract/src/validate-domain.ts`:
- Around line 45-56: The root/CrossReference validation currently checks models
by model name only; change it to validate and dedupe using the combined
namespace and model (e.g., build a qualified key
`${crossRef.namespace}:${modelName}` and use that to check membership in the
model set and in seenValues), update the error messages to include namespace
(e.g., "Root \"rootKey\" references model \"namespace:model\" which does not
exist"), and apply the same fix to the other crossRef checks referenced (the
loops/blocks around the other occurrences) so every reference resolves against
namespace+model rather than model alone.

In
`@packages/2-mongo-family/5-query-builders/query-builder/src/lookup-builder.ts`:
- Around line 140-147: The code currently allows a root to reference a model
name that isn't present in contract.models and then silently uses the rootName
as the collection; update the lookup path to fail fast: after computing
modelName from contract.roots[rootName]?.model, if modelName exists but
contract.models[modelName] is undefined, throw a descriptive Error (e.g.
"lookup() unknown model: \"<modelName>\" referenced by root \"<rootName>\"")
instead of continuing; locate this logic around the
modelName/model/foreignCollection code in lookup() and ensure
createLookupBuilder is only called when contract.models[modelName] is defined.

---

Nitpick comments:
In `@packages/1-framework/0-foundation/contract/test/canonicalization.test.ts`:
- Around line 3-7: Replace the local test helper that defaults to "default" with
the shared crossRef factory from the source so tests use the runtime default
"__unbound__"; remove the local function and import the exported crossRef
factory from the source module (instead of asNamespaceId-only) and update any
uses (including the occurrences around lines 100-101) to call that imported
crossRef to avoid default-drift between tests and production.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 01a9c910-2187-42cd-b986-87c238bf3e39

📥 Commits

Reviewing files that changed from the base of the PR and between 29f38d4 and df520d8.

⛔ Files ignored due to path filters (20)

• packages/2-sql/4-lanes/sql-builder/test/fixtures/generated/contract.json is excluded by !**/generated/**
• packages/3-extensions/sql-orm-client/test/fixtures/generated/contract.d.ts is excluded by !**/generated/**
• packages/3-extensions/sql-orm-client/test/fixtures/generated/contract.json is excluded by !**/generated/**
• projects/contract-ir-planes/slices/cross-reference-encoding/dispatches/01-framework-shape.md is excluded by !projects/**
• projects/contract-ir-planes/slices/cross-reference-encoding/dispatches/02-family-lowering-emitter-consumers.md is excluded by !projects/**
• projects/contract-ir-planes/slices/cross-reference-encoding/dispatches/03-fixture-regen-and-pr.md is excluded by !projects/**
• projects/contract-ir-planes/slices/cross-reference-encoding/plan.md is excluded by !projects/**
• projects/contract-ir-planes/slices/cross-reference-encoding/spec.md is excluded by !projects/**
• projects/contract-ir-planes/slices/namespace-aware-enum-planning/plan.md is excluded by !projects/**
• projects/contract-ir-planes/slices/namespace-aware-enum-planning/spec.md is excluded by !projects/**
• test/e2e/framework/test/fixtures/generated/contract.d.ts is excluded by !**/generated/**
• test/e2e/framework/test/fixtures/generated/contract.json is excluded by !**/generated/**
• test/e2e/framework/test/sqlite/fixtures/generated/contract.d.ts is excluded by !**/generated/**
• test/e2e/framework/test/sqlite/fixtures/generated/contract.json is excluded by !**/generated/**
• test/integration/test/mongo/fixtures/generated/contract.d.ts is excluded by !**/generated/**
• test/integration/test/mongo/fixtures/generated/contract.json is excluded by !**/generated/**
• test/integration/test/sql-builder/fixtures/generated/contract.d.ts is excluded by !**/generated/**
• test/integration/test/sql-builder/fixtures/generated/contract.json is excluded by !**/generated/**
• test/integration/test/sql-orm-client/fixtures/generated/contract.d.ts is excluded by !**/generated/**
• test/integration/test/sql-orm-client/fixtures/generated/contract.json is excluded by !**/generated/**

📒 Files selected for processing (142)

• apps/telemetry-backend/src/prisma/contract.d.ts
• apps/telemetry-backend/src/prisma/contract.json
• drive/retro/findings.md
• examples/cipherstash-integration/src/prisma/contract.d.ts
• examples/cipherstash-integration/src/prisma/contract.json
• examples/mongo-blog-leaderboard/src/contract.d.ts
• examples/mongo-blog-leaderboard/src/contract.json
• examples/mongo-demo/src/contract.d.ts
• examples/mongo-demo/src/contract.json
• examples/paradedb-demo/src/prisma/contract.d.ts
• examples/paradedb-demo/src/prisma/contract.json
• examples/prisma-next-cloudflare-worker/src/prisma/contract.d.ts
• examples/prisma-next-cloudflare-worker/src/prisma/contract.json
• examples/prisma-next-demo-sqlite/src/prisma/contract.d.ts
• examples/prisma-next-demo-sqlite/src/prisma/contract.json
• examples/prisma-next-demo/src/prisma/contract.d.ts
• examples/prisma-next-demo/src/prisma/contract.json
• examples/prisma-next-postgis-demo/src/prisma/contract.d.ts
• examples/prisma-next-postgis-demo/src/prisma/contract.json
• examples/react-router-demo/src/prisma/contract.d.ts
• examples/react-router-demo/src/prisma/contract.json
• examples/retail-store/src/contract.d.ts
• examples/retail-store/src/contract.json
• packages/1-framework/0-foundation/contract/src/canonicalization.ts
• packages/1-framework/0-foundation/contract/src/contract-types.ts
• packages/1-framework/0-foundation/contract/src/cross-reference.ts
• packages/1-framework/0-foundation/contract/src/domain-types.ts
• packages/1-framework/0-foundation/contract/src/exports/types.ts
• packages/1-framework/0-foundation/contract/src/namespace-id.ts
• packages/1-framework/0-foundation/contract/src/testing-factories.ts
• packages/1-framework/0-foundation/contract/src/validate-domain.ts
• packages/1-framework/0-foundation/contract/test/canonicalization.test.ts
• packages/1-framework/0-foundation/contract/test/contract-factories.test.ts
• packages/1-framework/0-foundation/contract/test/contract-types.test-d.ts
• packages/1-framework/0-foundation/contract/test/contract-types.test.ts
• packages/1-framework/0-foundation/contract/test/domain-types.test.ts
• packages/1-framework/0-foundation/contract/test/validate-domain.test.ts
• packages/1-framework/3-tooling/emitter/src/domain-type-generation.ts
• packages/1-framework/3-tooling/emitter/src/generate-contract-dts.ts
• packages/1-framework/3-tooling/emitter/test/domain-type-generation.test.ts
• packages/1-framework/3-tooling/emitter/test/emitter.integration.test.ts
• packages/1-framework/3-tooling/emitter/test/emitter.roundtrip.test.ts
• packages/1-framework/3-tooling/emitter/test/utils.ts
• packages/2-mongo-family/1-foundation/mongo-contract/src/contract-schema.ts
• packages/2-mongo-family/1-foundation/mongo-contract/src/contract-types.ts
• packages/2-mongo-family/1-foundation/mongo-contract/src/exports/index.ts
• packages/2-mongo-family/1-foundation/mongo-contract/src/validate-storage.ts
• packages/2-mongo-family/1-foundation/mongo-contract/test/contract-types.test-d.ts
• packages/2-mongo-family/1-foundation/mongo-contract/test/fixtures/orm-contract.d.ts
• packages/2-mongo-family/1-foundation/mongo-contract/test/fixtures/orm-contract.json
• packages/2-mongo-family/1-foundation/mongo-contract/test/validate-domain.test.ts
• packages/2-mongo-family/1-foundation/mongo-contract/test/validate-storage.test.ts
• packages/2-mongo-family/2-authoring/contract-psl/src/interpreter.ts
• packages/2-mongo-family/2-authoring/contract-psl/test/interpreter.polymorphism.test.ts
• packages/2-mongo-family/2-authoring/contract-psl/test/interpreter.test.ts
• packages/2-mongo-family/2-authoring/contract-ts/src/contract-builder.ts
• packages/2-mongo-family/2-authoring/contract-ts/test/contract-builder.dsl.test.ts
• packages/2-mongo-family/2-authoring/contract-ts/test/contract-builder.types.test-d.ts
• packages/2-mongo-family/3-tooling/emitter/src/index.ts
• packages/2-mongo-family/3-tooling/emitter/test/emitter-hook.e2e.test.ts
• packages/2-mongo-family/3-tooling/emitter/test/emitter-hook.generation.test.ts
• packages/2-mongo-family/3-tooling/emitter/test/emitter-hook.structure.test.ts
• packages/2-mongo-family/3-tooling/emitter/test/fixtures/blog-contract.ts
• packages/2-mongo-family/5-query-builders/orm/src/collection.ts
• packages/2-mongo-family/5-query-builders/orm/src/mongo-orm.ts
• packages/2-mongo-family/5-query-builders/orm/src/mongo-raw.ts
• packages/2-mongo-family/5-query-builders/orm/src/types.ts
• packages/2-mongo-family/5-query-builders/orm/test/value-object-inputs.test-d.ts
• packages/2-mongo-family/5-query-builders/query-builder/src/lookup-builder.ts
• packages/2-mongo-family/5-query-builders/query-builder/src/query.ts
• packages/2-mongo-family/5-query-builders/query-builder/src/state-classes.ts
• packages/2-mongo-family/5-query-builders/query-builder/test/fixtures/test-contract.ts
• packages/2-mongo-family/7-runtime/test/fixtures/contract.d.ts
• packages/2-mongo-family/7-runtime/test/fixtures/contract.json
• packages/2-mongo-family/7-runtime/test/fixtures/decode-fixture-contract.ts
• packages/2-mongo-family/7-runtime/test/runtime-types.test-d.ts
• packages/2-mongo-family/9-family/test/mongo-contract-serializer-base.test.ts
• packages/2-sql/1-core/contract/src/factories.ts
• packages/2-sql/1-core/contract/src/ir/foreign-key-reference.ts
• packages/2-sql/1-core/contract/src/validators.ts
• packages/2-sql/1-core/contract/test/domain-types.test.ts
• packages/2-sql/2-authoring/contract-psl/src/interpreter.ts
• packages/2-sql/2-authoring/contract-psl/test/fixtures.ts
• packages/2-sql/2-authoring/contract-psl/test/interpreter.diagnostics.test.ts
• packages/2-sql/2-authoring/contract-psl/test/interpreter.extensions.test.ts
• packages/2-sql/2-authoring/contract-psl/test/interpreter.polymorphism.test.ts
• packages/2-sql/2-authoring/contract-psl/test/interpreter.relations.test.ts
• packages/2-sql/2-authoring/contract-psl/test/interpreter.test.ts
• packages/2-sql/2-authoring/contract-psl/test/interpreter.types.test.ts
• packages/2-sql/2-authoring/contract-psl/test/psl-ts-namespace-parity.test.ts
• packages/2-sql/2-authoring/contract-ts/src/build-contract.ts
• packages/2-sql/2-authoring/contract-ts/src/contract-builder.ts
• packages/2-sql/2-authoring/contract-ts/src/contract-dsl.ts
• packages/2-sql/2-authoring/contract-ts/src/contract-types.ts
• packages/2-sql/2-authoring/contract-ts/test/contract-builder.contract-definition.test.ts
• packages/2-sql/2-authoring/contract-ts/test/contract-builder.dsl.helpers.test.ts
• packages/2-sql/2-authoring/contract-ts/test/contract-builder.dsl.test.ts
• packages/2-sql/2-authoring/contract-ts/test/contract-builder.dsl.types.test.ts
• packages/2-sql/2-authoring/contract-ts/test/contract-builder.normalization.test.ts
• packages/2-sql/2-authoring/contract-ts/test/contract-builder.per-model-namespace.test.ts
• packages/2-sql/2-authoring/contract-ts/test/contract.edge-cases.test.ts
• packages/2-sql/2-authoring/contract-ts/test/contract.logic.test.ts
• packages/2-sql/2-authoring/contract-ts/test/contract.model-validation.test.ts
• packages/2-sql/2-authoring/contract-ts/test/contract.normalization.test.ts
• packages/2-sql/2-authoring/contract-ts/test/cross-ref-helpers.ts
• packages/2-sql/2-authoring/contract-ts/test/fixtures/contract-with-relations.d.ts
• packages/2-sql/2-authoring/contract-ts/test/fixtures/contract-with-relations.json
• packages/2-sql/3-tooling/emitter/src/index.ts
• packages/2-sql/5-runtime/src/sql-context.ts
• packages/2-sql/9-family/test/contract-to-schema-ir.test.ts
• packages/2-sql/9-family/test/cross-reference-roundtrip.test.ts
• packages/2-sql/9-family/test/schema-verify.helpers.ts
• packages/3-extensions/cipherstash/src/contract.d.ts
• packages/3-extensions/cipherstash/src/contract.json
• packages/3-extensions/paradedb/src/contract.d.ts
• packages/3-extensions/pgvector/migrations/20260601T0000_install_vector_extension/end-contract.d.ts
• packages/3-extensions/pgvector/migrations/20260601T0000_install_vector_extension/end-contract.json
• packages/3-extensions/pgvector/migrations/20260601T0000_install_vector_extension/migration.json
• packages/3-extensions/pgvector/migrations/20260601T0000_install_vector_extension/migration.ts
• packages/3-extensions/pgvector/migrations/refs/head.json
• packages/3-extensions/pgvector/src/contract.d.ts
• packages/3-extensions/pgvector/src/contract.json
• packages/3-extensions/postgis/migrations/20260601T0000_install_postgis_extension/end-contract.d.ts
• packages/3-extensions/postgis/migrations/20260601T0000_install_postgis_extension/end-contract.json
• packages/3-extensions/postgis/migrations/20260601T0000_install_postgis_extension/migration.json
• packages/3-extensions/postgis/migrations/20260601T0000_install_postgis_extension/migration.ts
• packages/3-extensions/postgis/migrations/refs/head.json
• packages/3-extensions/postgis/src/contract.d.ts
• packages/3-extensions/postgis/src/contract.json
• packages/3-extensions/sql-orm-client/src/collection-contract.ts
• packages/3-extensions/sql-orm-client/src/model-accessor.ts
• packages/3-extensions/sql-orm-client/test/collection-contract.test.ts
• packages/3-extensions/sql-orm-client/test/generated-contract-types.test-d.ts
• packages/3-extensions/sql-orm-client/test/model-accessor.test.ts
• packages/3-extensions/sql-orm-client/test/mutation-executor.test.ts
• packages/3-mongo-target/1-mongo-target/test/mongo-target-contract-serializer.test.ts
• packages/3-targets/3-targets/postgres/src/core/migrations/operations/shared.ts
• packages/3-targets/3-targets/postgres/test/migrations/planner-schema-lookup.test.ts
• packages/3-targets/3-targets/sqlite/test/migrations/issue-planner.test.ts
• packages/3-targets/6-adapters/sqlite/test/migrations/planner-introspection.integration.test.ts
• test/integration/test/fixtures/contract.d.ts
• test/integration/test/fixtures/contract.json