fix(rest,spec): type-check the transport declaration's consumers, keep the id out of customer prose

Two CI reds, both this branch's own:

- `packages/rest` `typecheck` was never run: its `test` script covers only the `local` vitest project, and the type check is a separate script. The test layer held four errors, every one of them the declared `FindDataRequest['query'].where` INPUT union gaining the `FilterArray` arm the door already serves. Narrowed at the three read sites -- by REFUSING the other arm, not by casting past it -- and pinned the JSON-encoded filter string as the refusal the transport table deliberately makes it.

- `check:doc-authoring` refused an internal issue id inside `.describe()` prose, which is printed at the customer and resolves to nothing there. Moved to an adjacent `//` comment; regenerated the two reference pages the sentence projects into.

Claude-Session: https://claude.ai/code/session_01LvwGppdonww4zGLWZo5rho
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

content/docs/references/api/protocol.mdx

@@ -875,7 +875,7 @@ Enable package response
 | :--- | :--- | :--- | :--- |
 | **object** | `string` | ✅ | Object name (e.g. account) |
 | **fields** | `string[]` | optional | Fields to retrieve — names of the queried object's OWN columns. A dotted path (`owner.name`) is not a projection: no driver resolves one, and the ingress refuses it with `400 INVALID_FIELD`. Related data is read with `expand`, whose nested QueryAST both filters (`where`) and selects (`fields`) the related record's columns. The projection must RETAIN the foreign-key column: `fields: ['title']` with `expand: 'project_id'` resolves nothing, because the relation is carried by that key — add `'project_id'` and it works. Where the value is wanted on the queried object itself, denormalise it onto that object (a stored field, written when the source changes), the same remedy the sort axis prescribes. |
-| **where** | `[string, string, any] \| [string, string] \| [string, object, ...object[]] \| object[] \| Record<string, any> \| any` | optional | Filtering criteria (WHERE) — a filter condition, or the input-only `FilterArray` sugar (`['status', '=', 'open']`), which is lowered through `parseFilterAST` before the query is produced (#5158 ruling C). |
+| **where** | `[string, string, any] \| [string, string] \| [string, object, ...object[]] \| object[] \| Record<string, any> \| any` | optional | Filtering criteria (WHERE) — a filter condition, or the input-only `FilterArray` sugar (`['status', '=', 'open']`), which is lowered through `parseFilterAST` before the query is produced. |
 | **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) |

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

@@ -1280,7 +1280,7 @@ Transport spellings of the QueryAST slots — folded to canonical keys at the bo
 | :--- | :--- | :--- | :--- |
 | **object** | `string` | ✅ | Object name (e.g. account) |
 | **fields** | `string[]` | optional | Fields to retrieve — names of the queried object's OWN columns. A dotted path (`owner.name`) is not a projection: no driver resolves one, and the ingress refuses it with `400 INVALID_FIELD`. Related data is read with `expand`, whose nested QueryAST both filters (`where`) and selects (`fields`) the related record's columns. The projection must RETAIN the foreign-key column: `fields: ['title']` with `expand: 'project_id'` resolves nothing, because the relation is carried by that key — add `'project_id'` and it works. Where the value is wanted on the queried object itself, denormalise it onto that object (a stored field, written when the source changes), the same remedy the sort axis prescribes. |
-| **where** | `[string, string, any] \| [string, string] \| [string, object, ...object[]] \| object[] \| Record<string, any> \| any` | optional | Filtering criteria (WHERE) — a filter condition, or the input-only `FilterArray` sugar (`['status', '=', 'open']`), which is lowered through `parseFilterAST` before the query is produced (#5158 ruling C). |
+| **where** | `[string, string, any] \| [string, string] \| [string, object, ...object[]] \| object[] \| Record<string, any> \| any` | optional | Filtering criteria (WHERE) — a filter condition, or the input-only `FilterArray` sugar (`['status', '=', 'open']`), which is lowered through `parseFilterAST` before the query is produced. |
 | **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) |

packages/rest/src/import-runner-bulk.test.ts

@@ -23,6 +23,23 @@ type FindArgs = Parameters<ImportProtocolLike['findData']>[0];
 type CreateArgs = Parameters<ImportProtocolLike['createData']>[0];
 import type { ExportFieldMeta } from './export-format.js';
 
+/**
+ * The CANONICAL object `where` out of the slot's declared input union.
+ *
+ * `FindDataRequest['query'].where` admits the input-only `FilterArray` sugar as
+ * well, because the transport door serves it on every spelling of that slot.
+ * `runImport` builds only the object form, so this narrows by REFUSING the
+ * other arm rather than by casting past it: a runner that started emitting the
+ * array sugar fails here loudly instead of type-checking into silence.
+ */
+function canonicalWhere(args: FindArgs): Record<string, any> {
+  const where = args.query?.where;
+  if (where == null || Array.isArray(where)) {
+    throw new Error(`runImport must send a canonical object \`where\`; got ${JSON.stringify(where)}`);
+  }
+  return where;
+}
+
 const metaMap = new Map<string, ExportFieldMeta>([
   ['name', { name: 'name', type: 'text' }],
 ]);
@@ -162,7 +179,7 @@ describe('runImport — bulk create batching (framework#2678)', () => {
     // Row 1 ('existing') matches an existing record → update; the rest are creates.
     // [#16638] Reads the CANONICAL `where` the runner sends, not `$filter`.
     const findData = vi.fn(async (args: FindArgs) =>
-      (args.query!.where!.name === 'existing' ? [{ id: 'existing_id', name: 'existing' }] : []));
+      (canonicalWhere(args).name === 'existing' ? [{ id: 'existing_id', name: 'existing' }] : []));
     const p: ImportProtocolLike = { findData, createData: vi.fn(), updateData, createManyData };
 
     const summary = await runImport({

packages/rest/src/import-runner-idempotency.test.ts

@@ -187,8 +187,15 @@ describe('runImport — idempotent retry with natural keys (framework#3149)', ()
     expectEveryProbeNarrowed(findData.mock.calls, appliedFilters);
     const probes = findData.mock.calls.map(([a]) => a.query!);
     expect(probes).toHaveLength(1);
-    expect(Object.keys(probes[0].where!)).toEqual(['id']);
-    expect([...(probes[0].where!.id as { $in: string[] }).$in].sort()).toEqual(store.map((r) => r.id).sort());
+    // The slot's declared INPUT also admits the `FilterArray` sugar the
+    // transport door serves; the runner builds only the object form, so the
+    // other arm is REFUSED here rather than cast past.
+    const probeWhere = probes[0].where;
+    if (probeWhere == null || Array.isArray(probeWhere)) {
+      throw new Error(`the recheck must send a canonical object \`where\`; got ${JSON.stringify(probeWhere)}`);
+    }
+    expect(Object.keys(probeWhere)).toEqual(['id']);
+    expect([...(probeWhere.id as { $in: string[] }).$in].sort()).toEqual(store.map((r) => r.id).sort());
     expect(probes[0].limit).toBe(store.length);
   });
 

packages/rest/src/rest-server-canonical-query-ast.test.ts

@@ -394,7 +394,7 @@ describe('[#16337] §2 the declared `FindDataRequest[\'query\']` contract', () =
         // the AST. So these three are assignments, not `@ts-expect-error`s.
         const dollarTop: Query = { object: 'x', $top: 5 };
         const dollarFilter: Query = { object: 'x', $filter: { id: '1' } };
-        const wireFilters: Query = { object: 'x', filters: '{"id":"1"}' };
+        const wireFilters: Query = { object: 'x', filters: { id: '1' } };
         // ⭐ …and a bag mixing the two spellings, which is what a boundary that
         // merges a caller's parameters with its own actually assembles.
         const mixed: Query = { object: 'x', where: { status: 'queued' }, $top: 5 };
@@ -417,7 +417,9 @@ describe('[#16337] §2 the declared `FindDataRequest[\'query\']` contract', () =
         const noObject: Query = { limit: 1 };
         // @ts-expect-error `$sort` is not a spelling the transport table names — declaring the dialect did not open `$*`
         const unnamedDollar: Query = { object: 'x', $sort: 'name' };
-        expect([dollarTop, dollarFilter, wireFilters, mixed, wireSelect, wireSort, recordSort, commaExpand, noObject, unnamedDollar]).toHaveLength(10);
+        // @ts-expect-error a JSON-ENCODED filter string is declared on NO filter spelling — lowering one means running a second parser beside the door's, which is the one thing the transport declaration refuses to do
+        const jsonEncodedFilter: Query = { object: 'x', filters: '{"id":"1"}' };
+        expect([dollarTop, dollarFilter, wireFilters, mixed, wireSelect, wireSort, recordSort, commaExpand, noObject, unnamedDollar, jsonEncodedFilter]).toHaveLength(11);
     });
 });
 
@@ -472,7 +474,11 @@ describe('[#16952] §2 the declared `ImportProtocolLike` parameter contract', ()
         // ⭐ The whole point: leave the parameter unannotated and the contract
         // types it. This is the shape `plugin-auth`'s hand-written implementor
         // could not have while the declaration said `any`.
-        const probes: Array<Record<string, unknown> | undefined> = [];
+        // Typed FROM the declaration, like every alias in this block — the slot
+        // admits the `FilterArray` sugar as well as the object form, and a
+        // hand-written `Record<string, unknown>` here would be a fourth
+        // restatement of the dialect, which is what this section exists to stop.
+        const probes: Array<Query['where']> = [];
         const p: ImportProtocolLike = {
             findData: async (args) => { probes.push(args.query?.where); return { records: [] }; },
             createData: async (args) => ({ id: String(args.data.name) }),

packages/spec/src/data/data-engine.zod.ts

@@ -1191,10 +1191,13 @@ export const QueryWithTransportSchema = lazySchema(
     .extend({
       ...(QueryTransportParamsSchema as unknown as z.ZodObject<z.ZodRawShape>).shape,
       expand: describedCanonicalExpand(),
+      // The lowering sink the sentence below names is the one maintainer
+      // ruling C on #5158 fixed. The id lives in this comment and not in the
+      // prose, which is printed AT the customer, where it resolves to nothing.
       where: TransportFilterValueSchema.optional().describe(
         'Filtering criteria (WHERE) — a filter condition, or the input-only `FilterArray` '
         + "sugar (`['status', '=', 'open']`), which is lowered through `parseFilterAST` "
-        + 'before the query is produced (#5158 ruling C).'
+        + 'before the query is produced.'
       ),
     })
     .transform((bag, ctx) => foldQueryTransportBag(bag as Record<string, unknown>, ctx)),