fix(spec): QuerySchema declares the search contract ADR-0061 actually serves

The first CI run of the #3899 request-schema gate rejected the dogfood
search proof's own wire shape: `{ search: 'retail', searchFields:
['industry'] }` answered 400. The schema was the wrong half — QuerySchema
declared only the structured FullTextSearchSchema form while ADR-0061 D1
("the client sends only the query text"), the engine executor
(search-filter.ts), and the search-conformance ledger all serve the bare
string plus the validated `searchFields` narrowing.

- `search` becomes `string | FullTextSearch` (string is the canonical
  Tier-1 spelling; the object form keeps the declared Tier-2 knobs)
- `searchFields` is formally declared (the ADR's own P1 item), noted as
  server-intersected — can only narrow, never widen
- rest request-schema gate pins the ADR-0061 wire shape as a positive
  case so entry validation can never 400 it again
- regenerated: references docs + authorable-surface (adds
  `data/Query:searchFields`); all 8 artifact gates green

spec suite 7145 green; both previously-failing dogfood files pass
locally (showcase-search 4/4, two-factor-lockout 5/5 — the 2FA pair does
not reproduce here and is green on main @ 5d21a48's identical job).

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

Author: claude

content/docs/references/api/contract.mdx

@@ -149,7 +149,8 @@ const result = ApiError.parse(data);
 | **object** | `string` | ✅ | Object name (e.g. account) |
 | **fields** | `string[]` | optional | Fields to retrieve — field names, optionally dotted to reach through a relationship (`owner.name`). Related *records* are selected with `expand`, not from inside this list. |
 | **where** | `any` | optional | Filtering criteria (WHERE) |
-| **search** | `{ query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }` | optional | Full-text search configuration ($search parameter) |
+| **search** | `string \| { query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }` | optional | Full-text search — the query text (canonical, ADR-0061 D1), or a structured FullTextSearch configuration |
+| **searchFields** | `string[]` | optional | Narrow the search to these fields (server-intersected with the allowed searchable set — can only narrow, never widen; ADR-0061 D1) |
 | **orderBy** | `{ field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | Sorting instructions (ORDER BY) |
 | **limit** | `number` | optional | Max records to return (LIMIT) |
 | **offset** | `number` | optional | Records to skip (OFFSET) |
@@ -161,7 +162,7 @@ const result = ApiError.parse(data);
 | **having** | `any` | optional | HAVING — filter over the AGGREGATED rows (aggregation aliases + groupBy projections); applied engine-side after aggregation |
 | **windowFunctions** | `any` | optional | [REMOVED] `query.windowFunctions` was removed in @objectstack/spec 18 (#4286, ADR-0049) — `find()` never applied it: no engine or driver read the key on the query path, so every OVER clause it declared was silently dropped. Delete the key. Window functions are a SQL-driver capability behind `SqlDriver.findWithWindowFunctions(object, query)` (embedder-level; not on the `IDataDriver` contract or the REST surface); request-level analytics are `aggregations` + `groupBy`. |
 | **distinct** | `any` | optional | [REMOVED] `query.distinct` was removed in @objectstack/spec 18 (#4286, ADR-0049 / ADR-0078) — no driver ever rendered SELECT DISTINCT; the flag's only observable effect was MIS-WIRED: the REST list path treated a distinct query as not countable and silently degraded `total`/`hasMore` to a page-local estimate while still returning duplicate rows. Delete the key; `QueryBuilder.distinct()` was removed with it, and the count suppression is gone (`total` is truthful again). For unique values of one column use the SQL/memory drivers' `distinct(object, field)` door; for unique combinations, `groupBy`; for a deduplicated count, the `count_distinct` aggregation. |
-| **expand** | `Record<string, { object: string; fields?: string[]; where?: any; search?: object; … }>` | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select (`fields`) and filter (`where`, AND-merged with the batch $in), plus further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3; per-parent `limit`/`offset`/`orderBy` are NOT applied on this path. |
+| **expand** | `Record<string, { object: string; fields?: string[]; where?: any; search?: string \| { query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }; … }>` | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select (`fields`) and filter (`where`, AND-merged with the batch $in), plus further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3; per-parent `limit`/`offset`/`orderBy` are NOT applied on this path. |
 
 
 ---

content/docs/references/api/protocol.mdx

@@ -529,7 +529,7 @@ const result = AiAgentCapabilities.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **object** | `string` | ✅ | The unique machine name of the object to query (e.g. "account"). |
-| **query** | `{ object: string; fields?: string[]; where?: any; search?: object; … }` | optional | Structured query definition (filter, sort, select, pagination). |
+| **query** | `{ object: string; fields?: string[]; where?: any; search?: string \| { query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }; … }` | optional | Structured query definition (filter, sort, select, pagination). |
 
 
 ---

content/docs/references/data/data-engine.mdx

@@ -548,7 +548,7 @@ QueryAST-aligned query options for IDataEngine.find() operations
 | **top** | `number` | optional |  |
 | **cursor** | `any` | optional | [REMOVED] `query.cursor` was removed in @objectstack/spec 18 (#4286, ADR-0049) — no driver ever implemented keyset pagination, so the cursor was accepted and ignored and every page came back identical (a caller looping "until hasMore is false" never terminates). Delete the key; `QueryBuilder.cursor()` was removed with it. Express the keyset as an ordinary `where` predicate on your sort key — `where: { created_at: { $gt: last.created_at } }` with the matching `orderBy` — which every driver executes with canonicalised comparands. A first-class cursor, if ever built, will be a response-minted opaque token, not this caller-built record. |
 | **search** | `{ query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }` | optional |  |
-| **expand** | `Record<string, { object: string; fields?: string[]; where?: any; search?: object; … }>` | optional |  |
+| **expand** | `Record<string, { object: string; fields?: string[]; where?: any; search?: string \| { query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }; … }>` | optional |  |
 | **distinct** | `any` | optional | [REMOVED] `query.distinct` was removed in @objectstack/spec 18 (#4286, ADR-0049 / ADR-0078) — no driver ever rendered SELECT DISTINCT; the flag's only observable effect was MIS-WIRED: the REST list path treated a distinct query as not countable and silently degraded `total`/`hasMore` to a page-local estimate while still returning duplicate rows. Delete the key; `QueryBuilder.distinct()` was removed with it, and the count suppression is gone (`total` is truthful again). For unique values of one column use the SQL/memory drivers' `distinct(object, field)` door; for unique combinations, `groupBy`; for a deduplicated count, the `count_distinct` aggregation. |
 
 

content/docs/references/data/mapping.mdx

@@ -52,7 +52,7 @@ const result = FieldMapping.parse(data);
 | **fieldMapping** | `{ source: string \| string[]; target: string \| string[]; transform: Enum<'none' \| 'constant' \| 'lookup' \| 'split' \| 'join' \| 'javascript' \| 'map'>; params?: object }[]` | ✅ |  |
 | **mode** | `Enum<'insert' \| 'update' \| 'upsert'>` | ✅ |  |
 | **upsertKey** | `string[]` | optional | Fields to match for upsert (e.g. email) |
-| **extractQuery** | `{ object: string; fields?: string[]; where?: any; search?: object; … }` | optional | Query to run for export only |
+| **extractQuery** | `{ object: string; fields?: string[]; where?: any; search?: string \| { query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }; … }` | optional | Query to run for export only |
 | **errorPolicy** | `Enum<'skip' \| 'abort' \| 'retry'>` | ✅ |  |
 | **batchSize** | `number` | ✅ |  |
 

content/docs/references/data/query.mdx

@@ -126,7 +126,8 @@ Type: `string`
 | **object** | `string` | ✅ | Object name (e.g. account) |
 | **fields** | `string[]` | optional | Fields to retrieve — field names, optionally dotted to reach through a relationship (`owner.name`). Related *records* are selected with `expand`, not from inside this list. |
 | **where** | `any` | optional | Filtering criteria (WHERE) |
-| **search** | `{ query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }` | optional | Full-text search configuration ($search parameter) |
+| **search** | `string \| { query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }` | optional | Full-text search — the query text (canonical, ADR-0061 D1), or a structured FullTextSearch configuration |
+| **searchFields** | `string[]` | optional | Narrow the search to these fields (server-intersected with the allowed searchable set — can only narrow, never widen; ADR-0061 D1) |
 | **orderBy** | `{ field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | Sorting instructions (ORDER BY) |
 | **limit** | `number` | optional | Max records to return (LIMIT) |
 | **offset** | `number` | optional | Records to skip (OFFSET) |

packages/rest/src/request-schema-gate.conformance.test.ts

@@ -181,6 +181,20 @@ describe('#3899 ④ — rest routes with a declared requestSchema reject violati
     }
   });
 
+  it('the ADR-0061 search wire contract stays valid: { search: string, searchFields: [...] }', async () => {
+    // The first CI run of this gate rejected exactly this body: QuerySchema
+    // declared only the structured `FullTextSearchSchema` form while the
+    // executor and the ADR-0061 dogfood proof (`showcase-search.dogfood
+    // .test.ts`) served the bare string + `searchFields`. The schema was the
+    // wrong half — fixed there; pinned here so entry validation can never
+    // again 400 the contract the conformance ledger declares enforced.
+    const ctx = setup();
+    const res = await drive(ctx.rest, 'POST', '/api/v1/data/:object/query',
+      { search: 'retail', searchFields: ['industry'] }, PARAMS);
+    expect(res.statusCode, JSON.stringify(res.body)).toBe(200);
+    expect(ctx.findData).toHaveBeenCalledTimes(1);
+  });
+
   for (const gateCase of CASES) {
     const [method, path] = gateCase.route.split(' ') as [string, string];
     describe(gateCase.route, () => {

packages/spec/authorable-surface.json

@@ -3737,6 +3737,7 @@
     "data/Query:offset",
     "data/Query:orderBy",
     "data/Query:search",
+    "data/Query:searchFields",
     "data/Query:top",
     "data/Query:where",
     "data/Query:windowFunctions [RETIRED]",

packages/spec/src/data/query.zod.ts

@@ -343,10 +343,34 @@ const BaseQuerySchema = z.object({
 
   /** Where Clause (Filtering) */
   where: FilterConditionSchema.optional().describe('Filtering criteria (WHERE)'),
-  
-  /** Full-Text Search */
-  search: FullTextSearchSchema.optional().describe('Full-text search configuration ($search parameter)'),
-  
+
+  /**
+   * Full-Text Search.
+   *
+   * The bare string IS the canonical Tier-1 contract (ADR-0061 D1: "the
+   * client sends only the query text; the server resolves which fields to
+   * search from object metadata") — it is what every surface sends and what
+   * the dogfood HTTP proof (`showcase-search.dogfood.test.ts`) pins. The
+   * structured `FullTextSearchSchema` form remains for the declared Tier-2
+   * knobs. The union is schema-side drift REPAIR, not a new dialect: the
+   * schema declared only the object form while the executor and the ADR's own
+   * conformance ledger served the string — surfaced the moment #3899 started
+   * validating request bodies against this schema.
+   */
+  search: z.union([z.string(), FullTextSearchSchema]).optional()
+    .describe('Full-text search — the query text (canonical, ADR-0061 D1), or a structured FullTextSearch configuration'),
+
+  /**
+   * Per-query narrowing of the searchable field set (ADR-0061 D1).
+   * Server-validated: intersected with the object's allowed searchable
+   * fields — it can only narrow, never widen. Formalized here per the ADR's
+   * P1 ("formalize `$searchFields`"); the enforcement site is
+   * `objectql/src/search-filter.ts` `resolveSearchFields`, proven at the
+   * HTTP level by `showcase-search.dogfood.test.ts`.
+   */
+  searchFields: z.array(z.string()).optional()
+    .describe('Narrow the search to these fields (server-intersected with the allowed searchable set — can only narrow, never widen; ADR-0061 D1)'),
+
   /** Order By Clause (Sorting) */
   orderBy: z.array(SortNodeSchema).optional().describe('Sorting instructions (ORDER BY)'),