fix(objectql,cli): the recomputeUndefinedOnEmpty refusal answers INVALID_FIELD / 400 — the code every axis naming a field already takes (#15064)

Contract-review patch round on PR #15708 (verdict 5550099353), items 1, 3, 4.

- `resolveRecomputeScope` stamps `code = 'INVALID_FIELD'`, `status = 400`
  and `field = unresolved[0]` beside `fields`, the shape of the engine's
  sibling producers (`assertProjectionHasNoDottedPaths`,
  `undeclaredWriteFieldErrors`). `FIELD_NOT_FOUND` / 404 had no producer in
  this repo; handing a never-emitted 404 its first producer for a condition
  the catalog already assigns to a 400 is the two-codes-one-condition drift
  ADR-0112 exists to prevent — and two of the refused shapes name a field
  that exists (a real non-summary field; a roll-up on an object `objects`
  left out), so this is an option value that could not be applied, not an
  addressed resource that was not found.
- Pins retargeted: `summary-backfill.test.ts` "REFUSES a name it cannot
  resolve" (six code/status assertions, now also `field`/`fields`) and
  `summary-nulls.test.ts` "a refused scope entry … reaches the --json error
  envelope" (`code`).
- `content/docs/api/error-catalog.mdx`: the `INVALID_FIELD` Cause gains the
  `recomputeUndefinedOnEmpty` / `--recompute-undefined-on-empty` axis; the
  `FIELD_NOT_FOUND` entry is untouched.
- `SummaryBackfillReport.nullRows` TSDoc counts the named min/max/avg holes.
- Option TSDoc, resolver docblock and the changeset paragraph updated
  wherever FIELD_NOT_FOUND / 404 was named.

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

Author: claude

.changeset/summary-backfill-recompute-undefined-on-empty.md

@@ -30,8 +30,10 @@ the fact gets a way to say it; the predicate and the default run do not move.
 - A name that resolves to no roll-up owned by an object the run walks — a typo,
   a plain field, or an object `objects` left out — is **refused before any row
   is read**, dry run or apply, with an ADR-0112 envelope (`code:
-  'FIELD_NOT_FOUND'`, `status: 404`). A silent no-op there would be the same
-  false all-clear this option exists to end.
+  'INVALID_FIELD'`, `status: 400` — the code every other axis that names a
+  field already answers; `field` names the first unresolved entry, `fields`
+  all of them). A silent no-op there would be the same false all-clear this
+  option exists to end.
 - `SummaryBackfillReport.recomputedUndefinedOnEmpty: string[]` — the complement
   of `skippedUndefinedOnEmpty`, same `object.field (fn)` spelling; `[]` on an
   unscoped run. `SummaryBackfillFieldOutcome.fn` widens from `'count' | 'sum'`

content/docs/api/error-catalog.mdx

@@ -75,7 +75,12 @@ reads those as field filters, so one naming no field could only match zero
 records and is rejected rather than answered with an empty page — plus every
 other read axis that names a field: `select`, `expand` (a real field that holds
 no reference gets its own message), `searchFields` (a real field outside the
-searchable set gets its own message), `groupBy`, and `aggregations[].field`.  
+searchable set gets its own message), `groupBy`, and `aggregations[].field`.
+Off the request path the same code answers `backfillSummaryNulls`'s
+`recomputeUndefinedOnEmpty` — `os migrate summary-nulls
+--recompute-undefined-on-empty object.field` — when an entry is not a roll-up
+owned by an object the run walks (a real non-summary field, or a roll-up on an
+object `--object` left out, gets its own message).  
 **Fix:** Check the object schema for valid field names. Use `os meta get object <name>` to inspect the object's fields. If the name was meant as a
 *parameter* rather than a field, use the real one — page size is `top` / `$top`
 / `limit`, not `pageSize` / `perPage`; the response's `error` names the

packages/cli/src/commands/migrate/summary-nulls.test.ts

@@ -129,9 +129,9 @@ describe('os migrate summary-nulls', () => {
     expect(options).toEqual({ apply: false, objects: undefined, recomputeUndefinedOnEmpty: undefined, maxRecordsPerObject: undefined });
   }, RUN_TIMEOUT);
 
-  it('a refused scope entry (FIELD_NOT_FOUND) reaches the --json error envelope with its code, and the command exits 1', async () => {
+  it('a refused scope entry (INVALID_FIELD) reaches the --json error envelope with its code, and the command exits 1', async () => {
     const refusal = Object.assign(new Error('[summary-backfill] recomputeUndefinedOnEmpty names 1 roll-up(s) this run cannot find: customer.nope.'), {
-      code: 'FIELD_NOT_FOUND', status: 404, fields: ['customer.nope'],
+      code: 'INVALID_FIELD', status: 400, field: 'customer.nope', fields: ['customer.nope'],
     });
     vi.mocked(backfillSummaryNulls).mockRejectedValue(refusal);
 
@@ -144,7 +144,7 @@ describe('os migrate summary-nulls', () => {
     expect((err as { oclif?: { exit?: number } }).oclif?.exit).toBe(1);
     const emitted = stdout.mock.calls.map((c: unknown[]) => String(c[0])).join('');
     const payload = JSON.parse(emitted);
-    expect(payload).toMatchObject({ code: 'FIELD_NOT_FOUND' });
+    expect(payload).toMatchObject({ code: 'INVALID_FIELD' });
     expect(payload.error).toContain('customer.nope');
   }, RUN_TIMEOUT);
 });

packages/objectql/src/summary-backfill.test.ts

@@ -534,7 +534,7 @@ describe('backfillSummaryNulls — pre-#6013 NULL roll-ups (#6063)', () => {
       expect(maxOutcome(report)).toBeUndefined();
     });
 
-    it('REFUSES a name it cannot resolve — FIELD_NOT_FOUND, 404 — before any row is read, on a dry run as on apply', async () => {
+    it('REFUSES a name it cannot resolve — INVALID_FIELD, 400, the code every axis naming a field answers — before any row is read, on a dry run as on apply', async () => {
       busyAndQuiet();
 
       const refusals: Array<[string[], Record<string, unknown>]> = [
@@ -548,8 +548,12 @@ describe('backfillSummaryNulls — pre-#6013 NULL roll-ups (#6063)', () => {
       for (const [named, rest] of refusals) {
         const err = await backfillSummaryNulls(engine, quietLogger, { ...rest, recomputeUndefinedOnEmpty: named }).catch((e) => e);
         expect(err, named.join(',')).toBeInstanceOf(Error);
-        expect(err.code, named.join(',')).toBe('FIELD_NOT_FOUND');
-        expect(err.status, named.join(',')).toBe(404);
+        expect(err.code, named.join(',')).toBe('INVALID_FIELD');
+        expect(err.status, named.join(',')).toBe(400);
+        // The engine's sibling producers' shape: `field` is the first entry
+        // that did not resolve, `fields` every one of them.
+        expect(err.field, named.join(',')).toBe(named[named.length - 1]);
+        expect(err.fields, named.join(',')).toEqual([named[named.length - 1]]);
         expect(err.message, named.join(',')).toContain(named[named.length - 1]);
       }
       // Refused BEFORE the walk: no write at all, and even the count/sum holes

packages/objectql/src/summary-backfill.ts

@@ -128,7 +128,10 @@ export interface SummaryBackfillReport {
   scannedObjects: string[];
   scannedRecords: number;
   fields: SummaryBackfillFieldOutcome[];
-  /** Parent rows found holding `NULL` in a `count`/`sum` roll-up. */
+  /** Parent rows found holding `NULL` in a roll-up this run fills — every
+   *  `count`/`sum`, plus the `min`/`max`/`avg` named in
+   *  `recomputeUndefinedOnEmpty` (there, a `NULL` whose recompute is the
+   *  empty-set reading is not a hole and is not counted). */
   nullRows: number;
   /** Values actually written (0 on a dry run). */
   filled: number;
@@ -186,9 +189,10 @@ export interface SummaryBackfillOptions {
    * value for it. Naming a `count`/`sum` is accepted and changes nothing —
    * those are in scope by default — so a caller can pass every column it just
    * declared without knowing the empty-set list. A name that resolves to no
-   * roll-up owned by an object this run walks is refused (`FIELD_NOT_FOUND`,
-   * 404) before any row is read. Omitted, the run is exactly the `count`/`sum`
-   * backfill it always was.
+   * roll-up owned by an object this run walks is refused (`INVALID_FIELD`,
+   * 400 — the code every other axis that names a field answers) before any
+   * row is read. Omitted, the run is exactly the `count`/`sum` backfill it
+   * always was.
    */
   recomputeUndefinedOnEmpty?: string[];
   /** Safety bound on parent rows read per object. */
@@ -252,9 +256,20 @@ function partitionDescriptors(
  * a roll-up, or an object `options.objects` left out of this run — is REFUSED
  * as a whole, with nothing written: the caller asserted a fact about a column
  * this run cannot see, and quietly walking the rest would hand back the
- * `filled: 0` false all-clear this option exists to end. `FIELD_NOT_FOUND`
- * (ADR-0112 standard catalog, 404) is the envelope: the named field is what
- * could not be found.
+ * `filled: 0` false all-clear this option exists to end.
+ *
+ * `INVALID_FIELD` / 400 is the envelope — not a new code, and not a 404. The
+ * engine's own rule for a field name that cannot be applied as written
+ * (`assertProjectionHasNoDottedPaths` for `select`,
+ * `undeclaredWriteFieldErrors` on a write, and `INVALID_SORT` beside them) is
+ * that ONE condition keeps ONE wire code however the caller reached it, so a
+ * host surfacing this error over HTTP answers the same envelope on both doors.
+ * Two of the shapes refused here name a field that EXISTS — a real non-summary
+ * field, or a roll-up on an object `objects` left out — so this is an option
+ * value that could not be applied, never an addressed resource that was not
+ * found (`FIELD_NOT_FOUND` has no producer in this repo, and gains none here).
+ * `field` carries the first unresolved entry and `fields` all of them, the
+ * sibling producers' shape (ADR-0112).
  */
 function resolveRecomputeScope(
   engine: SummaryBackfillEngine,
@@ -278,9 +293,10 @@ function resolveRecomputeScope(
         `${unresolved.join(', ')}. Each entry is spelled object.field and must name a summary field owned by one ` +
         `of the ${candidates.length} object(s) this run walks (an object left out by \`objects\` is not walked). ` +
         'Refused before any row was read; nothing was written.',
-    ) as Error & { code: string; status: number; fields: string[] };
-    err.code = 'FIELD_NOT_FOUND';
-    err.status = 404;
+    ) as Error & { code: string; status: number; field: string; fields: string[] };
+    err.code = 'INVALID_FIELD';
+    err.status = 400;
+    err.field = unresolved[0];
     err.fields = unresolved;
     throw err;
   }