objectstack-ai
diff --git a/‎.changeset/16786-scoped-updatebyid-answer.md‎
Lines changed: 24 additions & 0 deletions b/‎.changeset/16786-scoped-updatebyid-answer.md‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎packages/spec/src/contracts/scoped-context.test.ts‎
Lines changed: 91 additions & 0 deletions b/‎packages/spec/src/contracts/scoped-context.test.ts‎
Lines changed: 91 additions & 0 deletions
diff --git a/‎packages/spec/src/contracts/scoped-context.ts‎
Lines changed: 30 additions & 2 deletions b/‎packages/spec/src/contracts/scoped-context.ts‎
Lines changed: 30 additions & 2 deletions
@@ -0,0 +1,24 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `IScopedObjectRepository.updateById` declares its answer — the record or `null`, not `any` (#16786)
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing, shipped as `minor` under the launch-window convention (the one PR #15280 used for `SqlDriver.update()` and the `TursoDriver.update()` override, PR #14434 before it on `@objectstack/driver-memory`, and PR #17255 for this card's `objectql` half, which was re-graded from `patch` to `minor` mid-round for exactly this reason).
+
+`updateById(id, data)` declared `Promise<any>` — the last wide member of a contract whose siblings answer what they mean. It now declares `Promise<Record<string, any> | null>`: the written record, or `null` when the id matched nothing.
+
+The declaration is what every layer under it already says, measured rather than inherited:
+
+- the engine door it forwards to, `IDataEngine.update`, declares `Promise<Record<string, any> | number | null>`;
+- that door's by-id exit calls `IDataDriver.update(object, id, data)`, which declares exactly `Promise<Record<string, unknown> | null>`;
+- `packages/objectql`'s `ObjectRepository.updateById` declared `Promise<any>` to MATCH this member rather than independently of it, and PR #17255 said so in its own docblock when it deliberately left this half open.
+
+The `number` limb `update` carries — the affected-row COUNT a predicate write resolves — is **not** declared here, and that is a measurement too: the implementation binds both the payload id and a pure-id `where` and never declares `multi`, so the shared update dispatch answers `by-id` for every call this signature admits. A falsy id (`0`, `''`) is a REFUSAL, not a `null`: it identifies no row, so the dispatch rejects and the call throws.
+
+Ruling A on #16231 settled the rule — #15823's `find()` narrowing extends to the sibling doors — and enumerated `scoped-context.ts:148` / `:164`, not this member. It is narrowed because the measurement says the declaration was wider than every implementation and wider than the door it forwards to, ⛔ not because a ruling named it.
+
+A hook or service that assigned the result into a record slot, or read a field off it, through an `IScopedObjectRepository`-typed door now separates the `null` arm first. No runtime behaviour changes. The in-repo census through the interface-typed door is the contract's own suites, which already answer the narrow shape.
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing authorable moves. No metadata key, no authored property, no config field, no accepted request shape and no stored artifact changes spelling or shape: the edit is one declared RETURN TYPE on a TypeScript interface plus its docblock, so `objectstack migrate meta` has nothing to rewrite, `spec-changes.json` has nothing to project and the upgrade guide has no row to gain. What the change asks for is addressed to a TYPESCRIPT CONSUMER and delivered by the compiler at their own call site, which is the audience the ADR-0087 ledger explicitly does not serve.
+     `type-surface-only` is the category built for this class of change and it is NOT claimed here, because it is unavailable — measured, not assumed. Its predicate 2 (`no-spec-diff`) is false by construction: the narrowed symbol LIVES in `packages/spec`, so any diff that moves it touches that package. Its predicate 3 (`no-metadata-surface-diff`) is false for the same file, `packages/spec/src/contracts/**` being an ADR-0087 shape surface by the gate's own classifier. Two of the four predicates cannot hold for any edit to this symbol, so the category is out of reach on the merits rather than on a resolution defect. The **BREAKING** banner above is carried rather than dropped — that erosion is what #13080 was filed about. -->
@@ -289,6 +289,97 @@ describe('[#5945] the evidence bar is enforced, not just documented', () => {
   });
 });
 
+describe('[#16786] `updateById` DECLARES its answer, and the declaration is enforced', () => {
+  /**
+   * The remainder of #16786, after PR #17255 landed the `objectql` half.
+   *
+   * ## Why a probe and not an `@ts-expect-error`
+   *
+   * The same reason the module header above gives: a directive is satisfied by
+   * ANY error on the next line. The sibling pin on `IDataEngine`
+   * (`data-engine.test.ts`, #16231) can use directives because it leans on
+   * TS2578 — widening a member back makes the directive UNUSED, which is
+   * itself an error — but that mechanism is only read by
+   * `check:test-typecheck`, a gate OUTSIDE this suite. These probes fail in
+   * vitest itself.
+   *
+   * ## The failure this pin exists to catch, measured rather than assumed
+   *
+   * Reverting the member to `Promise<any>` does NOT redden the `legal-*`
+   * probes above: `legal-updateById` discards the result, and `any` compiles
+   * everywhere a narrow type does. It reddens exactly the first case below,
+   * and it reddens it by reporting NOTHING — an absent diagnostic IS the `any`
+   * reading. That is why the assertion is `toContain`, on a probe whose legal
+   * twin must stay clean: a harness that resolved nothing would report an
+   * empty string for BOTH, so the clean twin is the anti-vacuity control and
+   * `harness-self-test` is the "can this harness report at all" control.
+   *
+   * ## And why the diagnostic must NAME the shape
+   *
+   * The header records a phantom check caught only by running the reversal: a
+   * code-only assertion survived the revert because a DIFFERENT type produced
+   * the same code. So the assertion names `Record<string, any> | null` — the
+   * declared answer. `any` cannot produce that text, and neither can the
+   * `update` sibling's wider `Record<string, any> | number | null`, so a
+   * copy-paste of the wrong sibling's shape is caught too.
+   */
+  it('the answer cannot enter a record slot unnarrowed, and the null-checked read compiles', () => {
+    const results = compileProbes({
+      // The whole point of the declaration: a by-id update that matched no row
+      // answers `null`, and before this the call site was handed `any` and
+      // never asked.
+      'rejects-unnarrowed-updateById':
+        hook("const row: Record<string, any> = await ctx.api!.object('task').updateById('t1', { status: 'done' });"),
+      // Anti-vacuity twin: the CORRECT spelling must still compile clean, so
+      // the narrowing is a real answer shape and not a blanket refusal.
+      'legal-updateById-null-checked': hook([
+        "const row = await ctx.api!.object('task').updateById('t1', { status: 'done' });",
+        'if (row !== null) {',
+        '  const seen: unknown = row.status;',
+        '  void seen;',
+        '}',
+      ].join('\n')),
+      'harness-self-test': hook("const x: number = ctx.api?.object('user');"),
+    });
+
+    expect(render(results.get('harness-self-test')!), 'the harness must be able to report an error')
+      .toContain('TS2322');
+
+    const refused = render(results.get('rejects-unnarrowed-updateById')!);
+    // An EMPTY string here is the `Promise<any>` reading — this is the leg that
+    // goes red on a revert.
+    expect(refused, 'an unnarrowed record slot must be refused').toContain('TS2322');
+    expect(refused, 'the refusal must name the DECLARED answer shape, not merely error')
+      .toContain('Record<string, any> | null');
+    // ⛔ Not the `update` sibling's shape: `updateById` never reaches the
+    // predicate exit, so the affected-row count limb must not be declared here.
+    expect(refused, 'the count limb belongs to `update`, not to `updateById`')
+      .not.toContain('number | null');
+
+    expect(render(results.get('legal-updateById-null-checked')!), 'the null-checked read must compile clean')
+      .toBe('');
+  });
+
+  /**
+   * The runtime half, so the contract is implementable at the narrowed shape
+   * in BOTH directions — a record and the `null` a by-id miss resolves.
+   */
+  it('is implementable at the declared shape, null limb included', async () => {
+    const rows: Record<string, any>[] = [{ id: 'p1', status: 'open' }];
+    const repo: Pick<IScopedObjectRepository, 'updateById'> = {
+      updateById: async (id, data) => {
+        const found = rows.find((r) => r.id === id);
+        if (!found) return null;
+        Object.assign(found, data);
+        return found;
+      },
+    };
+
+    expect(await repo.updateById('p1', { status: 'filled' })).toEqual({ id: 'p1', status: 'filled' });
+    expect(await repo.updateById('nope', { status: 'filled' })).toBeNull();
+  });
+});
+
 describe('[#5945] IScopedContext is implementable', () => {
   it('accepts a minimal implementation', async () => {
     const rows = [{ id: 'c1', stage: 'hired', position_id: 'p1' }];
 
@@ -111,6 +111,19 @@
  * `IDataEngine`'s — `find` stays `Promise<any[]>`, and since #16231 `findOne`
  * and `update` carry the same declared answer shapes their `IDataEngine`
  * counterparts do — and nothing here claims to be the query schema.
+ *
+ * [#16786] `updateById` joins them. Ruling A on #16231 settled the RULE —
+ * #15823's `find()` narrowing extends to the sibling doors — and enumerated
+ * `:148` / `:164`; this member is a door of that family the enumeration
+ * missed, so the reason it narrows is the MEASUREMENT, not the enumeration:
+ * `Promise<any>` was wider than the engine door it forwards to
+ * (`IDataEngine.update`, `Promise<Record<string, any> | number | null>`),
+ * wider than that door's by-id driver exit (`IDataDriver.update`,
+ * `Promise<Record<string, unknown> | null>`), and wider than what every
+ * implementation in the repository returns. `packages/objectql`'s
+ * `ObjectRepository.updateById` declared `Promise<any>` to MATCH this member,
+ * not independently of it — PR #17255 said so in its own docblock — so this
+ * is the half that was left open, not a second one.
  */
 
 import type { EngineTransactionInfo, EngineTransactionOptions } from './objectql-engine.js';
@@ -164,8 +177,23 @@ export interface IScopedObjectRepository {
      */
     update(data: any, options?: Record<string, unknown>): Promise<Record<string, any> | number | null>;
 
-    /** Update a single record by id — the id travels as the first argument. */
-    updateById(id: string | number, data: any): Promise<any>;
+    /**
+     * Update a single record by id — the id travels as the first argument.
+     *
+     * Answers the written record, or `null` when the id matched nothing. This
+     * is the `update` by-id exit and nothing else: the implementation binds
+     * both the payload id and a pure-id `where` and never declares `multi`, so
+     * `resolveEngineUpdateDispatch` returns `by-id` for every call this
+     * signature admits, and the `number` limb `update` carries — the
+     * affected-row COUNT a predicate write resolves (#4639) — is unreachable
+     * from here. One door down, `IDataDriver.update(object, id, data)` declares
+     * exactly `Promise<Record<string, unknown> | null>`.
+     *
+     * ⚠️ A falsy id is not a narrower answer, it is a REFUSAL: `0` and `''`
+     * identify no row, so the dispatch rejects and the call throws rather than
+     * resolving `null`.
+     */
+    updateById(id: string | number, data: any): Promise<Record<string, any> | null>;
 }
 
 /**