fix(spec): the $search auto field set's lead ORDERS the set, it must not admit one (#4483)

`autoDefaultFields` filtered every field through three exclusions
(`SEARCH_AUTO_EXCLUDED_FIELDS`, `hidden`, unsearchable type) and then
prepended the display/name/title field on an EXISTENCE check alone — so the
exclusions did not hold for whichever field happened to lead, and the module's
own "system / audit / heavy fields never auto-included" invariant was false.

Not a contrived shape: ADR-0079's `provisionPrimary(schema, { synthesize:
false })` designates `nameField` at registration, and on a table whose only
textual column IS the primary key (system tables, junction tables, append-only
logs) it designates `id`. `$search` then expanded to `{ id: { $contains: term } }`
— a substring scan over the primary key, returning a narrow and semantically
wrong row set.

It loosened a second layer too: `resolveSearchFieldResolution` is also the
#4254 REST ingress gate's arbiter for "would the engine actually scan this
field", so with `id` in `allowed` a `$searchFields=id` override was ACCEPTED
rather than refused.

The lead's job is to put the primary title FIRST, never to admit it, so it is
now chosen from the already-filtered set. An excluded / hidden / unsearchable
display field simply does not lead and the set is unchanged; an eligible one
still leads, so the ordering intent is intact.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017gEHJN2NFpS9VMeURvakgD

Author: claude

packages/spec/src/data/search-fields.test.ts

@@ -0,0 +1,120 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import {
+  resolveSearchFieldResolution,
+  resolveSearchFields,
+  SEARCH_AUTO_EXCLUDED_FIELDS,
+} from './search-fields';
+
+// ---------------------------------------------------------------------------
+// [#4483] The auto-default's "lead" field ORDERS the set; it must not ADMIT one.
+//
+// `autoDefaultFields` filters every field through three exclusions, then used to
+// prepend the display/name/title field on an EXISTENCE check alone — so the
+// exclusions did not hold for whichever field happened to lead. The regression
+// this pins is not hypothetical: ADR-0079 designates `nameField` at
+// registration, and on a table whose only textual column is the primary key it
+// designates `id`, turning `$search` into a substring scan over the PK.
+// ---------------------------------------------------------------------------
+describe('[#4483] $search auto field set — lead orders, never admits', () => {
+  const pkOnly = {
+    id: { type: 'text' },
+    amount: { type: 'number' },
+  };
+
+  it('excludes `id` with no display field (the already-correct baseline)', () => {
+    expect(resolveSearchFieldResolution({ fields: pkOnly })).toEqual({
+      allowed: [],
+      source: 'auto',
+    });
+  });
+
+  it('a displayField on the exclusion list does NOT re-enter the set', () => {
+    // Pre-#4483 this returned `{ allowed: ['id'] }`.
+    expect(resolveSearchFieldResolution({ fields: pkOnly, displayField: 'id' })).toEqual({
+      allowed: [],
+      source: 'auto',
+    });
+  });
+
+  it('every SEARCH_AUTO_EXCLUDED_FIELDS member stays out even as displayField', () => {
+    for (const excluded of SEARCH_AUTO_EXCLUDED_FIELDS) {
+      const { allowed } = resolveSearchFieldResolution({
+        fields: { [excluded]: { type: 'text' }, title: { type: 'text' } },
+        displayField: excluded,
+      });
+      expect(allowed, `'${excluded}' leaked into the auto set as displayField`).toEqual(['title']);
+    }
+  });
+
+  it('a hidden display field does not lead and does not enter', () => {
+    const { allowed } = resolveSearchFieldResolution({
+      fields: { name: { type: 'text', hidden: true }, subject: { type: 'text' } },
+      displayField: 'name',
+    });
+    expect(allowed).toEqual(['subject']);
+  });
+
+  it('a display field of an unsearchable TYPE does not enter', () => {
+    const { allowed } = resolveSearchFieldResolution({
+      fields: { avatar: { type: 'image' }, subject: { type: 'text' } },
+      displayField: 'avatar',
+    });
+    expect(allowed).toEqual(['subject']);
+  });
+
+  it('the `name` / `title` bypasses are gated by the same predicate', () => {
+    // Both exist but are unsearchable — neither may lead nor enter.
+    const { allowed } = resolveSearchFieldResolution({
+      fields: {
+        name: { type: 'json' },
+        title: { type: 'vector' },
+        subject: { type: 'text' },
+      },
+    });
+    expect(allowed).toEqual(['subject']);
+  });
+
+  it('an ELIGIBLE display field still leads — the ordering intent is intact', () => {
+    const { allowed } = resolveSearchFieldResolution({
+      fields: {
+        code: { type: 'text' },
+        subject: { type: 'text' },
+        stage: { type: 'select' },
+      },
+      displayField: 'subject',
+    });
+    expect(allowed[0]).toBe('subject');
+    expect(new Set(allowed)).toEqual(new Set(['subject', 'code', 'stage']));
+  });
+
+  it('falls back to `name`, then `title`, for the lead position', () => {
+    expect(
+      resolveSearchFieldResolution({
+        fields: { code: { type: 'text' }, name: { type: 'text' } },
+      }).allowed[0],
+    ).toBe('name');
+    expect(
+      resolveSearchFieldResolution({
+        fields: { code: { type: 'text' }, title: { type: 'text' } },
+      }).allowed[0],
+    ).toBe('title');
+  });
+
+  it('a declared `searchableFields` list is unaffected by the lead rule', () => {
+    // `declared` is the author's explicit choice and bypasses the auto-default
+    // entirely — including its exclusions. Pinned so the fix is not read as
+    // narrowing the declared path too.
+    expect(
+      resolveSearchFieldResolution({ fields: pkOnly, searchableFields: ['id'], displayField: 'id' }),
+    ).toEqual({ allowed: ['id'], source: 'declared' });
+  });
+
+  it('the #4254 ingress gate no longer admits `$searchFields=id`', () => {
+    // `resolveSearchFields` intersects the override with `allowed`; with `id`
+    // out of `allowed` the override matches nothing and cannot widen the scan.
+    expect(resolveSearchFields({ fields: pkOnly, displayField: 'id', requestedFields: 'id' }))
+      .toEqual([]);
+  });
+});

packages/spec/src/data/search-fields.ts

@@ -72,10 +72,32 @@ function autoDefaultFields(fields: Record<string, SearchFieldMeta>, displayField
     if (SEARCH_AUTO_EXCLUDED_TYPES.has(t)) return false;
     return SEARCHABLE_TEXTUAL_TYPES.has(t) || SEARCHABLE_ENUM_TYPES.has(t);
   });
-  // Lead with the display/name field when present.
-  const lead = displayField && fields[displayField] ? displayField
-    : fields.name ? 'name'
-    : fields.title ? 'title'
+  // Lead with the display/name field — ORDERING ONLY (#4483).
+  //
+  // `lead` used to be picked by EXISTENCE (`fields[displayField]`), then
+  // prepended unconditionally, so it re-entered the set after the three
+  // exclusions above had already rejected it. That made
+  // `SEARCH_AUTO_EXCLUDED_FIELDS` — whose contract is "never auto-included" —
+  // untrue for whichever field happened to be the display field, and the case
+  // is not contrived: ADR-0079's `provisionPrimary(schema, { synthesize: false })`
+  // designates `nameField` at registration, and on a table whose only textual
+  // column IS the primary key (system tables, junction tables, append-only
+  // logs) it designates `id`. `$search` then expanded to
+  // `{ id: { $contains: <term> } }` — a substring scan over the primary key.
+  //
+  // It also loosened the #4254 REST ingress gate one layer up, which asks this
+  // same resolution whether a `$searchFields` override names a field the engine
+  // would actually scan: with `id` in `allowed`, `$searchFields=id` was
+  // ACCEPTED instead of refused.
+  //
+  // The lead's job is to put the primary title FIRST, never to admit it, so it
+  // is now chosen from `names` — the already-filtered set. A display field that
+  // is excluded, hidden or of an unsearchable type simply does not lead, and
+  // the set is unchanged.
+  const eligible = (f: string | undefined): f is string => !!f && names.includes(f);
+  const lead = eligible(displayField) ? displayField
+    : eligible('name') ? 'name'
+    : eligible('title') ? 'title'
     : undefined;
   if (!lead) return names;
   return [lead, ...names.filter((f) => f !== lead)];