@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# A comment that names a test file by NAME must name a file that exists.
+#
+# Several load-bearing comments in this repo delegate a guarantee to a test in ANOTHER
+# package — "the two are now compared by codegen-ts's `secondary-index-name-parity.test.ts`
+# rather than by a claim in a comment" — which is exactly the right thing to write, because
+# it replaces an assertion a reader has to trust with one they can go run.
+#
+# The coupling is a bare filename across a package boundary, so nothing connects the two.
+# Rename or delete the test and every reference to it keeps reading as a live guarantee
+# while pointing at nothing, which is strictly worse than never having made the promise:
+# the comment still tells the next reader the case is covered.
+#
+# The check is deliberately narrow. It looks only at BACKTICKED `<name>.test.ts` mentions —
+# the convention these comments already use — so ordinary prose about testing cannot trip
+# it, and it resolves by BASENAME anywhere under the TS tree rather than by path, so moving
+# a test between directories (which breaks no promise) does not fail it. Renaming one does.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+fail=0
+# The pathspecs are SHELL globs, deliberately unquoted. Quoting them hands git a literal
+# `*` pathspec, which matches nothing here and yields an empty result — and because git grep
+# exits 1 on no matches, under `set -euo pipefail` that aborted the assignment and the whole
+# script exited 1 having printed NOTHING. A check that fails silently and a check that passes
+# are equally useless; `|| true` keeps "no references at all" a legitimate, reported outcome.
+refs=$(git grep -ohE '`[a-zA-Z0-9._-]+\.test\.ts`' -- \
+         server/typescript/packages/*/src server/typescript/packages/*/test 2>/dev/null \
+       | tr -d '`' | sort -u || true)
+
+count=0
+while read -r f; do
+  [ -z "$f" ] && continue
+  count=$((count + 1))
+  if [ -z "$(find server/typescript -name "$f" -print -quit)" ]; then
+    fail=1
+    printf '  ✖ a comment names `%s`, and no such file exists.\n' "$f" >&2
+    printf '    Referenced from:\n' >&2
+    git grep -n -- "$f" -- server/typescript/packages/*/src server/typescript/packages/*/test \
+      | sed 's/^/      /' >&2 || true
+    printf '    Restore the name, or update every reference — a comment that delegates a\n' >&2
+    printf '    guarantee to a file that is gone still reads as a guarantee.\n' >&2
+  fi
+done <<< "$refs"
+
+if [ "$fail" -ne 0 ]; then exit 1; fi
+echo "test-file references: $count named, all resolve"
@@ -173,6 +173,15 @@ gate_script_name_hooks() { node scripts/check-script-name-hooks.mjs; }
 # sentence stops being true. This checks the wiring itself.
 gate_no_magic_coverage() { scripts/check-no-magic-gate-coverage.sh; }
 
+# ── a comment that names a test file must name one that exists ────────────────
+# Several load-bearing comments delegate a guarantee to a test in ANOTHER package ("the two
+# are now compared by codegen-ts's `secondary-index-name-parity.test.ts` rather than by a
+# claim in a comment"), which is the right thing to write — it replaces an assertion the
+# reader must trust with one they can run. The coupling is a bare filename across a package
+# boundary, so a rename leaves every reference reading as a live guarantee while pointing at
+# nothing: worse than never promising, because the comment still says the case is covered.
+gate_test_references() { scripts/check-test-references.sh; }
+
 # ── release hygiene: no pre-release version may be committed ──────────────────
 # scripts/prerelease.mjs bumps every version declaration in place and restores them on
 # exit; a crashed run (or a hand-run sed) can leave an -rc.N behind. That is not cosmetic:
@@ -548,6 +557,7 @@ if want gates; then step    "publish-set parity"               gate_publish_set;
 if want gates; then step    "no committed pre-release version" gate_no_prerelease_versions; fi
 if want gates; then step    "script-name hook collisions"      gate_script_name_hooks;      fi
 if want gates; then step    "no-magic gate wired (5 ports)"    gate_no_magic_coverage;      fi
+if want gates; then step    "test-file references resolve"     gate_test_references;        fi
 if want gates; then step    "metamodel-version bump"           gate_metamodel_version;      fi
 if want gates; then step_if bun "peer-range bounds"            gate_peer_ranges;            fi
 if want gates; then step_if bun "shipped doc examples load"    gate_doc_examples;           fi
 
@@ -7,6 +7,7 @@ import { MetaObject, MetaField, MetaIndex, isMetaObject, stripPackage } from "@m
 import {
   FIELD_SUBTYPE_LONG,
   IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION,
+  IDENTITY_ATTR_EXPR, IDENTITY_ATTR_USING, IDENTITY_ATTR_ORDERS, IDENTITY_ATTR_WHERE,
   GENERATION_INCREMENT, GENERATION_UUID,
   FIELD_ATTR_AUTO_SET,
   FIELD_ATTR_OBJECT_REF,
@@ -235,10 +236,78 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     callbackEntries.push(buildCompositeKeyCallback(pkFieldNames, importModule));
   }
 
+  /**
+   * One index callback entry, for BOTH `identity.secondary` (unique) and `index.lookup`
+   * (non-unique). The two shapes differ only in that boolean, and migrate treats their
+   * physical attributes identically — `@expr`/`@using`/`@orders`/`@where` are registered on
+   * both by the same provider — so they are emitted by ONE function here. They used to be
+   * two near-identical loops, which is how the physical attributes came to be honoured by
+   * neither: a rule written twice is a rule that can be forgotten twice.
+   *
+   * What was missing is a SHAPE divergence, not a naming one (the names were reconciled
+   * separately). An `@expr`-only index emitted NOTHING at all here, because both loops
+   * required a non-empty `@fields` — while migrate emits it, keying off `@expr`. And
+   * `@where` never reached this file, so a PARTIAL unique index read as a FULLY unique one
+   * in the generated schema: `drizzle-kit push` would propose replacing the database's
+   * partial index with a total one, and any diff written from generated source disagreed
+   * with the database over a difference that was not real. Same class as the sqlite
+   * emitter dropping these in 0.15.21.
+   */
+  const indexEntry = (
+    node: { name: string; attr: (n: string) => unknown },
+    fieldNames: string[],
+    unique: boolean,
+  ): Code | undefined => {
+    const str = (n: string): string | undefined => {
+      const raw = node.attr(n);
+      return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : undefined;
+    };
+    const expr = str(IDENTITY_ATTR_EXPR);
+    // An expression index keys off @expr; a plain one needs @fields. Mirrors migrate's
+    // `if (fieldNames.length === 0 && expr === undefined) continue`.
+    if (fieldNames.length === 0 && expr === undefined) return undefined;
+
+    const sqlSym = imp("sql@drizzle-orm");
+    const indexSym = imp(`${unique ? "uniqueIndex" : "index"}@${importModule}`);
+
+    // @orders is positional against @fields; migrate only serializes it when at least one
+    // entry is `desc`, because an all-ascending array must be indistinguishable from no
+    // orders at all for diff stability. Match that exactly or the two disagree on a
+    // no-op.
+    const ordersRaw = node.attr(IDENTITY_ATTR_ORDERS);
+    const orders = Array.isArray(ordersRaw)
+      ? fieldNames.map((_, i) => (ordersRaw[i] === "desc" ? "desc" : "asc"))
+      : [];
+    const anyDesc = orders.some((o) => o === "desc");
+    const colRefs = fieldNames.map((f, i) =>
+      anyDesc ? `table.${f}.${orders[i] === "desc" ? "desc" : "asc"}()` : `table.${f}`);
+
+    // sqlite's `.on()` accepts only columns — no SQL — so an expression index is not
+    // expressible there. It is skipped rather than emitted wrong; migrate still creates it,
+    // and a Drizzle declaration that silently indexed a COLUMN instead of the expression
+    // would be a worse answer than an absent one.
+    if (expr !== undefined && dialect === "sqlite") return undefined;
+
+    // @using selects the access method and takes the columns itself, so it REPLACES .on().
+    // Postgres-only: SQLite has no USING clause. migrate omits a `btree` value as the
+    // default, and so does this — emitting it would be a spurious difference.
+    const using = dialect === "sqlite" ? undefined : str(IDENTITY_ATTR_USING);
+    const target: Code =
+      expr !== undefined ? code`${sqlSym}\`${expr}\``
+      : code`${colRefs.join(", ")}`;
+    const head: Code =
+      using !== undefined && using !== "btree"
+        ? code`${indexSym}(${JSON.stringify(node.name)}).using(${JSON.stringify(using)}, ${target})`
+        : code`${indexSym}(${JSON.stringify(node.name)}).on(${target})`;
+
+    // @where — the partial-index predicate, available on both dialects.
+    const where = str(IDENTITY_ATTR_WHERE);
+    return where === undefined ? head : code`${head}.where(${sqlSym}\`${where}\`)`;
+  };
+
   // identity.secondary — always unique (uniqueness is in the type, no boolean).
   for (const sec of secondaryIdentities) {
     const fields = sec.attr(IDENTITY_ATTR_FIELDS) as string[] | undefined;
-    if (!Array.isArray(fields) || fields.length === 0) continue;
     // The identity's OWN name, which is what migrate puts in the database
     // (`expected-schema.ts`, secondary-identity pass) and what `index.lookup` three
     // blocks below already emits. This used to compose `idx_<table>_<col>...` by running
@@ -248,21 +317,16 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     // over a field NAME cannot see `@column`, so a declared physical column was invisible
     // to it. Gated by `secondary-index-name-parity.test.ts`, whose fixture is de-blinded
     // against exactly that second defect.
-    const indexName = sec.name;
-    const indexSym = imp(`uniqueIndex@${importModule}`);
-    // Use the callback param `table` (not the outer varName) so TS doesn't see
+    // Column refs use the callback param `table` (not the outer varName) so TS does not see
     // the table referencing itself inside its own initializer (TS7022/TS7024).
-    const cols = fields.map((f) => `table.${f}`).join(", ");
-    callbackEntries.push(code`${indexSym}(${JSON.stringify(indexName)}).on(${cols})`);
+    const entry = indexEntry(sec, Array.isArray(fields) ? fields : [], /* unique */ true);
+    if (entry !== undefined) callbackEntries.push(entry);
   }
 
   // index.lookup — always non-unique. Use MetaIndex.fields() per ADR-0039.
   for (const lookup of obj.lookupIndexes()) {
-    const fields = lookup.fields();
-    if (fields.length === 0) continue;
-    const indexSym = imp(`index@${importModule}`);
-    const cols = fields.map((f) => `table.${f}`).join(", ");
-    callbackEntries.push(code`${indexSym}(${JSON.stringify(lookup.name)}).on(${cols})`);
+    const entry = indexEntry(lookup, lookup.fields(), /* unique */ false);
+    if (entry !== undefined) callbackEntries.push(entry);
   }
 
   // Emit table-level CHECK constraints for enum fields. Both halves are composed by
 
@@ -98,7 +98,7 @@ describe("renderDrizzleSchema — index.lookup emits non-unique index", () => {
     expect(out).toContain('"orders_customer_placed_idx"');
   });
 
-  test("index.lookup emits .on(table.customerId, table.placedAt)", () => {
+  test("index.lookup emits .on(table.customerId.asc(), table.placedAt.desc()) — @orders honoured", () => {
     const order = makeOrderWithLookupIndex();
     const root = makeRoot([order]);
     const ctx = makeRenderContext({
@@ -110,7 +110,72 @@ describe("renderDrizzleSchema — index.lookup emits non-unique index", () => {
       relationMap: buildRelationMap(root),
     });
     const out = renderDrizzleSchema(root.findObject("Order")!, ctx).toString();
-    expect(out).toMatch(/\.on\(table\.customerId,\s*table\.placedAt\)/);
+    // The fixture's own comment says "customerId + placedAt DESC" and it sets
+    // @orders ["asc","desc"], yet this assertion used to require the direction to be
+    // ABSENT — pinning the defect rather than the intent. migrate emits the DESC, so the
+    // generated schema declared a differently-ordered index than the database has.
+    expect(out).toMatch(/\.on\(table\.customerId\.asc\(\),\s*table\.placedAt\.desc\(\)\)/);
+  });
+
+  // The physical escapes (@expr / @where / @using) reached migrate and never reached this
+  // file at all, which is a SHAPE divergence rather than a naming one: a PARTIAL unique index
+  // read as a fully unique one in the generated schema, and an @expr-only index emitted
+  // nothing whatsoever because both loops required a non-empty @fields. `drizzle-kit push`
+  // would then propose replacing the database's index with the wrong one.
+  test("@where emits a partial index — a partial UNIQUE must not read as a total one", () => {
+    const user = makeUserWithSecondary();
+    const sec = user.children().find((c) => c.name === "idx_email")!;
+    sec.setAttr("where", "deleted_at IS NULL");
+    const root = makeRoot([user]);
+    const ctx = makeRenderContext({
+      dialect: "postgres", loadedRoot: root, outDir: "/x", dbImport: "~/db",
+      pkMap: buildPkMap(root), relationMap: buildRelationMap(root),
+    });
+    const out = renderDrizzleSchema(root.findObject("User")!, ctx).toString();
+    expect(out).toMatch(/\.where\(sql`deleted_at IS NULL`\)/);
+  });
+
+  test("@expr emits an expression index, which used to emit NOTHING", () => {
+    const user = makeUserWithSecondary();
+    const sec = user.children().find((c) => c.name === "idx_email")!;
+    // An expression index keys off @expr, not @fields — migrate emits it on @expr alone.
+    sec.setAttr("fields", []);
+    sec.setAttr("expr", "lower(email)");
+    const root = makeRoot([user]);
+    const ctx = makeRenderContext({
+      dialect: "postgres", loadedRoot: root, outDir: "/x", dbImport: "~/db",
+      pkMap: buildPkMap(root), relationMap: buildRelationMap(root),
+    });
+    const out = renderDrizzleSchema(root.findObject("User")!, ctx).toString();
+    expect(out).toContain('uniqueIndex("idx_email")');
+    expect(out).toMatch(/\.on\(sql`lower\(email\)`\)/);
+  });
+
+  test("@using selects the access method and replaces .on()", () => {
+    const user = makeUserWithSecondary();
+    const sec = user.children().find((c) => c.name === "idx_email")!;
+    sec.setAttr("using", "gin");
+    const root = makeRoot([user]);
+    const ctx = makeRenderContext({
+      dialect: "postgres", loadedRoot: root, outDir: "/x", dbImport: "~/db",
+      pkMap: buildPkMap(root), relationMap: buildRelationMap(root),
+    });
+    const out = renderDrizzleSchema(root.findObject("User")!, ctx).toString();
+    expect(out).toMatch(/\.using\("gin", table\.email\)/);
+  });
+
+  test("@using btree is omitted — migrate treats it as the default, so emitting it would differ", () => {
+    const user = makeUserWithSecondary();
+    const sec = user.children().find((c) => c.name === "idx_email")!;
+    sec.setAttr("using", "btree");
+    const root = makeRoot([user]);
+    const ctx = makeRenderContext({
+      dialect: "postgres", loadedRoot: root, outDir: "/x", dbImport: "~/db",
+      pkMap: buildPkMap(root), relationMap: buildRelationMap(root),
+    });
+    const out = renderDrizzleSchema(root.findObject("User")!, ctx).toString();
+    expect(out).not.toContain(".using(");
+    expect(out).toMatch(/\.on\(table\.email\)/);
   });
 
   test("index.lookup does NOT add .unique() to the indexed columns", () => {