Match type filters through re-export spellings via canonical code refs

[lukemelia]

What this does

A filter.type/on code ref that names a type through a re-exporting module — the canonical example being base FileDef addressed via its documented file-api module, which re-exports it from card-api — silently matched nothing. Index rows stamp types with the canonical (defining-module) key from identifyCard, so only the canonical spelling ever joined the membership keys: filtering on base FileDef returned zero rows while concrete subtype filters matched, making the base-type filter a silent dead end.

Two halves, kept in agreement:

• Query engine: each type condition's ref now resolves through the definition lookup, and the compiled types membership predicates union the canonical ref's spelling-tolerant keys (RRI / real-URL / virtual-alias) with the as-given ref's. Because the definition lookup is async, the type condition becomes a deferred expression node resolved in pass 1, alongside the existing deferred kinds. A ref whose definition doesn't resolve keeps only its spelling-based keys and matches nothing, exactly as before.
• Host search resource: the same rewrite is applied (via the loader + identifyCard) before client-side matching — the matcher compares refs against identifyCard of an instance's class, so an uncanonicalized re-export spelling would strip the server's correct results during live reconciliation. Until the rewrite settles for the active filter, or when a ref doesn't resolve, the search stays a server-only passthrough so the two evaluations can't disagree.

The shared walker (runtime-common/query-canonicalization.ts) rewrites type/on refs through any/every/not without mutating the input tree, and single-flights duplicate ref spellings by memoizing the in-flight promise — sibling nodes are walked concurrently, so a value-memo would double-resolve.

Test plan

• packages/realm-server/tests/search-entries-engine-test.ts: a pure base-FileDef filter matches every file row across subtypes, and the file-api re-export spelling matches the same rows as the canonical card-api spelling (36/36 pass locally).
• packages/host/tests/unit/query-canonicalization-test.ts: rewrite of top-level and nested refs, input-tree immutability, unresolvable refs marking the result incomplete, and duplicate refs resolving once (8/8 pass locally via the dev test page).
• Typechecks pass across runtime-common, realm-server, and host.

🤖 Generated with Claude Code

[github-actions]

Preview deployments

• Host staging preview

• Host production preview

Host Test Results

    1 files      1 suites   1h 13m 58s ⏱️
2 172 tests 2 164 ✅ 8 💤 0 ❌
2 181 runs  2 173 ✅ 8 💤 0 ❌

Results for commit b1ea516.

Realm Server Test Results

    1 files  ±0      1 suites  ±0   15m 22s ⏱️ +5s
2 176 tests ±0  2 176 ✅ ±0  0 💤 ±0  0 ❌ ±0 
2 256 runs  ±0  2 256 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit 2a58eb1. ± Comparison against earlier commit 7921aea.

[lukemelia]

[Claude Code 🤖] Review focus: the two-sided canonical-ref contract — that the server's types-membership compile and the host's client-side matcher agree on what a re-export spelling matches, and that the new deferred type-condition node composes exactly as the inline any() it replaces.

Bottom line: the design is correct — I found no correctness defect in the compiled SQL or in the server/matcher agreement. Two non-blocking findings: a stale-source race in the host's async canonicalization, and a swallow-all error path in typeKeysFor. Details inline. No blocking issues.

What lands right.

• The mechanism checks out end-to-end. Index rows stamp types via identifyCard (the defining-module ref — makeDefinition in host/app/routes/module.ts sets codeRef = identifyCard(cardOrFieldDef)). The matcher's instanceIsType walks the instance's prototype chain comparing identifyCard(klass) through codeRefEquals, which tolerates URL-spelling variance (RRI / real-URL / virtual-alias) but not module-identity variance. So a raw file-api/FileDef filter makes instanceIsType return false and the reconciler strips the server's correct rows. Canonicalizing the filter's refs to the card-api defining-module ref on both sides is exactly the right fix, and doing it upstream in search.ts rather than inside the matcher keeps that single call site as the only consumer needing it (verified: search.ts is the only non-test caller of matchInstanceAgainstFilter / isClientEvaluable).
• The deferred type-condition node is structurally equivalent to the old inline path. filterCondition still wraps this.typeCondition(ref) (now [typeConditionNode]) through every/any, whose addExplicitParens parenthesizes the single-element array; pass 1 splices handleTypeCondition's any(keys.map(typesContains)) — the same token shape the old code emitted — inside those parens. All three type-key sites (handleTypeCondition, hasFileType, hasInstanceType) route through typeKeysFor, so no twin is left on the old inline path.
• typeKeysFor mutating internalKeysFor's return with .push is safe — internalKeysFor returns a fresh .map(...) array per call.
• The canonicalization walker's single-flight memo is correct: canonicalRef runs memo.has / memo.set synchronously before its first await, so concurrent sibling walks can't both miss (the duplicate refs resolve once test pins it), and the per-node { ...node } shallow clone keeps the input tree immutable (also pinned).

Recommendations.

1. Guard the host .then against a stale filter so an out-of-order loader.import resolution can't stickily disable client reconciliation — see the loadCanonicalizedFilter thread. (non-blocking)
2. Consider distinguishing "definition not found" from a transient lookup failure in typeKeysFor, so a valid re-export ref doesn't silently under-match under load — see the typeKeysFor thread. (non-blocking)

Adjacent, out of scope. The realm test-results status comment reports realm-server tests as ±0 against the base even though this PR adds two tests to search-entries-engine-test.ts — most likely a status-comment/base-comparison artifact rather than the tests not running, but worth a glance to confirm they executed in CI.