feat(driver-sql,driver-turso): update() publishes the contract's Record<string, unknown> | null, not any (#15280)

`SqlDriver.update()` was written out with an explicit `Promise<any>` while it
has always answered a missing id with `null`; `IDataDriver.update()` declares
`Promise<Record<string, unknown> | null>` and an explicit `any` satisfies that
structurally, so the published `.d.ts` read `any` and no caller holding the
class was asked to narrow. The annotation is now the contract's, on `update()`
and on its protected rotation-path producer `rotatedUpdateById()`.

`TursoDriver` overrides the door rather than inheriting it, with its own
explicit `Promise<any>`; its override is narrowed the same way and carries its
own changeset. `SqliteWasmDriver` inherits: its emitted `.d.ts` declares no
`update` member (measured), so it carries a pin and no changeset.

Type-level pins (`IsAny` = false, `Equals` the contract shape) live in each of
the three packages' own tsc programs; each was measured red (2 x TS2322)
against the pre-change annotation and green after.

The narrowing surfaced six sites in driver-turso's own tests that read fields
off an `update()` result after asserting `not.toBeNull()`; they now narrow
through vitest's `assert()` (an assertion signature), not a `!` or a cast.


Claude-Session: https://claude.ai/code/session_01ARYe3yQTQCUFm5qPYNgKaJ

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/driver-sql-update-declared-null.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/driver-sql': minor
+---
+
+feat(driver-sql): `update()` publishes its honest type — the contract's `Record<string, unknown> | null`, not `any` (#14438)
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing, shipped as `minor` under the launch-window convention (the one PR #14434 used for the same door on `@objectstack/driver-memory`). `SqlDriver.update()` was written out with an explicit `Promise<any>` while it has always answered a missing id with `null` (`formatOutput(...) || null` on the un-rotated path, `null` once every rotation shard has been probed). `IDataDriver.update()` declares `Promise<Record<string, unknown> | null>`, and an explicit `any` satisfies that structurally — so the emitted `.d.ts` read `Promise<any>` and no caller holding a `SqlDriver`, or a `SqliteWasmDriver` (which inherits the door unchanged), was ever asked to narrow. It is now declared as the contract declares it, and the protected rotation-path producer `rotatedUpdateById()` carries the same type. A caller that read fields off `update()`'s result through the `any` now narrows the `null` arm first; a caller that leaned on `any` to read undeclared members now types them. No runtime behaviour changes.
+
+`@objectstack/driver-sqlite-wasm` re-declares no `update` member of its own (measured on its emitted `.d.ts`), so it carries no entry: the narrowing reaches its consumers through this package's `.d.ts`. `@objectstack/driver-turso` overrides the door and carries its own entry.
+
+<!-- adr-0087: not-required (type-surface-only packages/drivers/driver-sql/src/sql-driver.ts#update) A published driver method's declared return moves off an explicit `any` onto the contract's own shape. No metadata key is removed, renamed or re-shaped, `packages/spec` is untouched, and nothing exists for `objectstack migrate meta`, `spec-changes.json` or the upgrade guide to rewrite; the obligation is a TypeScript narrowing at the consumer's own call site, delivered by the compiler. -->

.changeset/driver-turso-update-declared-null.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/driver-turso': minor
+---
+
+feat(driver-turso): the `update()` override publishes its honest type — `Record<string, unknown> | null`, not `any` (#14438)
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing, shipped as `minor` under the launch-window convention. `TursoDriver` overrides `update()` rather than inheriting it, and the override was written out with its own explicit `Promise<any>` — so this package's emitted `.d.ts` re-declared the door as `any` on its own and would not have picked up the `@objectstack/driver-sql` narrowing. Both of its branches already answered the contract's type: the local branch forwards to `SqlDriver.update()` (narrowed alongside, #14438) and the remote branch passes `RemoteTransport.update()`'s `Record<string, unknown> | null` (#14428) through the generic `formatRemoteRow`. The override now declares what it answers. A caller that read fields off the result through the `any` now narrows the `null` arm first. No runtime behaviour changes.
+
+<!-- adr-0087: not-required (type-surface-only packages/drivers/driver-turso/src/turso-driver.ts#update) A published driver method's declared return moves off an explicit `any` onto the contract's own shape; no metadata key moves, `packages/spec` is untouched, and the obligation is a TypeScript narrowing at the consumer's own call site, delivered by the compiler. -->

packages/drivers/driver-sql/src/sql-driver-update-declared-null.test.ts

@@ -0,0 +1,108 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #14438 — `SqlDriver.update()`'s declared return type is the contract's, not
+// `any`, and it carries the not-found arm.
+//
+// `SqlDriver.update()` has always answered a missing id with `null`
+// (`return this.formatOutput(object, updated) || null` on the un-rotated path;
+// the rotation path's `return null` once every shard has been probed), while
+// its signature was written out as an EXPLICIT `Promise<any>`.
+// `IDataDriver.update()` declares `Promise<Record<string, unknown> | null>`
+// (the arm landed with #13878 / PR #14434 under the maintainer's 2026-09-01
+// ruling), and an explicit `any` satisfies that structurally — so `tsc` said
+// nothing, the published `.d.ts` of `@objectstack/driver-sql` read
+// `Promise<any>`, and no caller holding a `SqlDriver` (or a `SqliteWasmDriver`,
+// which inherits the door) was ever asked to narrow. It is the mask
+// `InMemoryDriver` carried, inferred there and written out here.
+//
+// This file pins BOTH halves at the type level, inside this package's tsc
+// program (`tsconfig.json` selects `src/**/*`, tests included, and the package
+// carries no DEBT / TEST_DEBT entry in `scripts/check-type-check-coverage.mjs`):
+//
+//   1. the CONTRACT: `IDataDriver.update()` resolves to
+//      `Record<string, unknown> | null` — read through `@objectstack/spec`'s
+//      built `.d.ts`, so reverting the declaration alone reds this file;
+//   2. the DRIVER: `SqlDriver.update()` is not `any` and resolves to exactly
+//      the contract's type — putting the annotation back to `Promise<any>` reds
+//      this file too: `IsAny` flips to `true` and `Equals` to `false`.
+//
+// Reverse verification, direction predicted BEFORE it was run: with the source
+// annotation at `Promise<any>`, `pnpm --filter @objectstack/driver-sql typecheck`
+// fails with TS2322 on `sqlUpdateIsAny` and on `sqlUpdateIsContract` (two
+// errors, both in this file), while `pnpm test` stays green — the type-level
+// facts are carried by consts vitest only compares. That split is the point:
+// this defect has no runtime face, which is why an assignability-only pin
+// would have passed against the very `any` being removed. Measured as
+// predicted: 2 × TS2322 (this file, the two driver consts) with the annotation
+// at `Promise<any>`, 0 errors with it at the contract's type.
+//
+// The typed-const form is the one `memory-update-declared-null.test.ts`
+// (driver-memory, #13878) and `sql-driver-distinct-filter-narrowing.test.ts`
+// use; the runtime cases below make the consts observable so the file is a
+// test and not a declaration. `SqliteWasmDriver` and `TursoDriver` carry their
+// own copies of the driver half in their own tsc programs.
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import type { Knex } from 'knex';
+import type { IDataDriver } from '@objectstack/spec/contracts';
+import { SqlDriver } from './index.js';
+
+/** `any` defeats ordinary assignability checks; this is the standard detector. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** Exact (mutual, non-`any`) type equality. */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+
+type ContractUpdate = Awaited<ReturnType<IDataDriver['update']>>;
+type SqlUpdate = Awaited<ReturnType<SqlDriver['update']>>;
+
+// 1. The contract declares the not-found arm.
+const contractUpdateDeclaresNull: Equals<ContractUpdate, Record<string, unknown> | null> = true;
+
+// 2. The driver's door is un-masked and reads exactly as the contract does.
+const sqlUpdateIsAny: IsAny<SqlUpdate> = false;
+const sqlUpdateIsContract: Equals<SqlUpdate, Record<string, unknown> | null> = true;
+
+describe('SqlDriver.update() declared return type (#14438)', () => {
+  let driver: SqlDriver;
+  let knexInstance: Knex;
+
+  beforeEach(async () => {
+    driver = new SqlDriver({
+      client: 'better-sqlite3',
+      connection: { filename: ':memory:' },
+      useNullAsDefault: true,
+    });
+    // `knex` is `protected` on SqlDriver; name the single member being reached
+    // rather than erasing the driver with `as any` (#6204 spelling).
+    knexInstance = (driver as unknown as { knex: Knex }).knex;
+    await knexInstance.schema.createTable('t', (t: Knex.CreateTableBuilder) => {
+      t.string('id').primary();
+      t.string('name');
+    });
+    await knexInstance('t').insert({ id: '1', name: 'before' });
+  });
+
+  afterEach(async () => {
+    await knexInstance.destroy();
+  });
+
+  it('pins the contract and the driver at the type level', () => {
+    expect([contractUpdateDeclaresNull, sqlUpdateIsAny, sqlUpdateIsContract]).toEqual([true, false, true]);
+  });
+
+  it('update() on a missing id resolves to null, and the declared type makes the caller narrow', async () => {
+    const result = await driver.update('t', 'missing', { name: 'x' });
+    expect(result).toBeNull();
+
+    // The narrowing the declared type now demands of every caller: a field
+    // read is only reachable behind the `null` check.
+    const name = result === null ? 'absent' : result.name;
+    expect(name).toBe('absent');
+  });
+
+  it('update() on an existing id resolves to the updated record, behind the same narrowing', async () => {
+    const result = await driver.update('t', '1', { name: 'after' });
+    expect(result).not.toBeNull();
+    expect(result === null ? 'absent' : result.name).toBe('after');
+  });
+});

packages/drivers/driver-sql/src/sql-driver.ts

@@ -6905,7 +6905,16 @@ export class SqlDriver implements IDataDriver {
     }
   }
 
-  async update(object: string, id: string | number, data: Record<string, any>, options?: DriverOptions): Promise<any> {
+  /**
+   * [#14438] Declared as `IDataDriver.update()` declares it: the updated
+   * record, or `null` when no row carries `id` — the un-rotated path answers
+   * `formatOutput(...) || null` and the rotation path answers `null` once
+   * every shard has been probed. The annotation used to be an explicit
+   * `Promise<any>`, which an un-narrowed caller could read fields off with no
+   * compiler complaint; it is the contract's type now, pinned by
+   * `sql-driver-update-declared-null.test.ts`.
+   */
+  async update(object: string, id: string | number, data: Record<string, any>, options?: DriverOptions): Promise<Record<string, unknown> | null> {
     this.auditMissingTenant(object, 'update', options);
     const rotationShards = this.rotationShardsOf(object);
     if (rotationShards) return this.rotatedUpdateById(object, rotationShards, id, data, options);
@@ -7987,7 +7996,7 @@ export class SqlDriver implements IDataDriver {
     id: string | number,
     data: Record<string, any>,
     options?: DriverOptions,
-  ): Promise<any> {
+  ): Promise<Record<string, unknown> | null> {
     const formatted = this.applyWriteColumnMap(object, this.formatInput(object, data));
     // [#11067] One definition of the decision, shared with {@link update}. No
     // fallback is threaded here, and that is a property of the path rather than

packages/drivers/driver-sqlite-wasm/src/sqlite-wasm-update-declared-null.test.ts

@@ -0,0 +1,89 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #14438 — `SqliteWasmDriver.update()` reads as the contract declares it, not
+// as `any`, and it carries the not-found arm.
+//
+// `SqliteWasmDriver extends SqlDriver` and does NOT override `update()`, so its
+// published `.d.ts` re-declares no `update` member of its own: the door it
+// exposes is `SqlDriver.update()`'s, read through `@objectstack/driver-sql`'s
+// built `.d.ts`. That is exactly the case that is easy to get wrong in both
+// directions — a reader assumes the sibling "must have its own copy", or
+// assumes inheritance and never measures it. This pin makes the inheritance a
+// measured fact inside THIS package's tsc program (`tsconfig.json` selects
+// `src/**/*`, tests included; no DEBT / TEST_DEBT entry): the door is not
+// `any` and resolves to exactly `Record<string, unknown> | null`.
+//
+// Two ways this file goes red, both by design:
+//   - `@objectstack/driver-sql` puts its `update()` annotation back to
+//     `Promise<any>` (the pre-#14438 state) — this package inherits the mask
+//     again and `IsAny` flips;
+//   - a future override in `sqlite-wasm-driver.ts` re-declares the door with a
+//     widened type — `Equals` flips, naming the drift here rather than at a
+//     consumer.
+//
+// Reverse verification, direction predicted BEFORE it was run: against the
+// pre-change `@objectstack/driver-sql` `.d.ts`, `pnpm --filter
+// @objectstack/driver-sqlite-wasm typecheck` fails with TS2322 on
+// `wasmUpdateIsAny` and on `wasmUpdateIsContract`; `pnpm test` is green
+// either way (type-level facts carried by consts). Measured as predicted:
+// 2 × TS2322 against the pre-change `.d.ts`, 0 against the narrowed one — and
+// the built `dist/index.d.ts` of this package declares no `update(` member
+// (0 matches), confirming the door is inherited, not re-declared.
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import type { Knex } from 'knex';
+import type { IDataDriver } from '@objectstack/spec/contracts';
+import { SqliteWasmDriver } from './index.js';
+
+/** `any` defeats ordinary assignability checks; this is the standard detector. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** Exact (mutual, non-`any`) type equality. */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+
+type ContractUpdate = Awaited<ReturnType<IDataDriver['update']>>;
+type WasmUpdate = Awaited<ReturnType<SqliteWasmDriver['update']>>;
+
+// 1. The contract declares the not-found arm.
+const contractUpdateDeclaresNull: Equals<ContractUpdate, Record<string, unknown> | null> = true;
+
+// 2. The inherited door is un-masked and reads exactly as the contract does.
+const wasmUpdateIsAny: IsAny<WasmUpdate> = false;
+const wasmUpdateIsContract: Equals<WasmUpdate, Record<string, unknown> | null> = true;
+
+describe('SqliteWasmDriver.update() declared return type (#14438)', () => {
+  let driver: SqliteWasmDriver;
+
+  beforeEach(async () => {
+    driver = new SqliteWasmDriver({ filename: ':memory:' });
+    // `knex` is `protected` on the base; name the single member being reached.
+    const k = (driver as unknown as { knex: Knex }).knex;
+    await k.schema.createTable('t', (t: Knex.CreateTableBuilder) => {
+      t.string('id').primary();
+      t.string('name');
+    });
+    await k('t').insert({ id: '1', name: 'before' });
+  });
+
+  afterEach(async () => {
+    await driver.disconnect();
+  });
+
+  it('pins the contract and the inherited door at the type level', () => {
+    expect([contractUpdateDeclaresNull, wasmUpdateIsAny, wasmUpdateIsContract]).toEqual([true, false, true]);
+  });
+
+  it('update() on a missing id resolves to null, and the declared type makes the caller narrow', async () => {
+    const result = await driver.update('t', 'missing', { name: 'x' });
+    expect(result).toBeNull();
+
+    // The narrowing the declared type now demands of every caller.
+    const name = result === null ? 'absent' : result.name;
+    expect(name).toBe('absent');
+  });
+
+  it('update() on an existing id resolves to the updated record, behind the same narrowing', async () => {
+    const result = await driver.update('t', '1', { name: 'after' });
+    expect(result).not.toBeNull();
+    expect(result === null ? 'absent' : result.name).toBe('after');
+  });
+});

packages/drivers/driver-turso/src/turso-driver-update-declared-null.test.ts

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #14438 — `TursoDriver.update()`'s declared return type is the contract's, not
+// `any`, and it carries the not-found arm.
+//
+// `TursoDriver` does not merely inherit `SqlDriver.update()` — it OVERRIDES it
+// (a local branch that forwards to `super.update`, a remote branch that passes
+// `RemoteTransport.update()`'s result through the generic `formatRemoteRow`),
+// and the override was written out with its own explicit `Promise<any>`. Both
+// branches already carried the honest type: `SqlDriver.update()` is narrowed
+// by #14438 and `RemoteTransport.update()` declared
+// `Promise<Record<string, unknown> | null>` with #14428. The override's
+// annotation was the one place the family's honest type was re-erased, so
+// this package's published `.d.ts` re-declared the door as `any` on its own —
+// which is why "TursoDriver inherits the fix" would have been wrong, and why
+// this pin lives in THIS package's tsc program rather than in driver-sql's.
+//
+// Pinned here, at the type level (`tsconfig.json` selects `src/**/*`, tests
+// included; no DEBT / TEST_DEBT entry for this package):
+//
+//   1. the CONTRACT: `IDataDriver.update()` resolves to
+//      `Record<string, unknown> | null`;
+//   2. the DRIVER: `TursoDriver.update()` is not `any` and resolves to exactly
+//      the contract's type — putting the override's annotation back to
+//      `Promise<any>` reds this file: `IsAny` flips to `true`, `Equals` to
+//      `false`.
+//
+// Reverse verification, direction predicted BEFORE it was run: with the
+// override at `Promise<any>`, `pnpm --filter @objectstack/driver-turso typecheck`
+// fails with TS2322 on `tursoUpdateIsAny` and on `tursoUpdateIsContract`; `pnpm
+// test` stays green either way (type-level facts carried by consts). Measured
+// as predicted: 2 × TS2322 on this file with the override at `Promise<any>`;
+// with the override narrowed, this file is clean and the package's remaining
+// errors are the consumer sites the narrowing was written to surface.
+//
+// The runtime case below drives the LOCAL face (`:memory:`); the remote face's
+// `null` on a miss is pinned by the `RemoteTransport` suites (#14428).
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import type { IDataDriver } from '@objectstack/spec/contracts';
+import { TursoDriver } from './turso-driver.js';
+
+/** `any` defeats ordinary assignability checks; this is the standard detector. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** Exact (mutual, non-`any`) type equality. */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+
+type ContractUpdate = Awaited<ReturnType<IDataDriver['update']>>;
+type TursoUpdate = Awaited<ReturnType<TursoDriver['update']>>;
+
+// 1. The contract declares the not-found arm.
+const contractUpdateDeclaresNull: Equals<ContractUpdate, Record<string, unknown> | null> = true;
+
+// 2. The override is un-masked and reads exactly as the contract does.
+const tursoUpdateIsAny: IsAny<TursoUpdate> = false;
+const tursoUpdateIsContract: Equals<TursoUpdate, Record<string, unknown> | null> = true;
+
+/**
+ * The slice of the inherited (protected) Knex instance this fixture touches.
+ * `knex` is not a dependency of this package, so its types are not imported;
+ * naming the members reached keeps the harness of a file about "the door is
+ * no longer `any`" free of `any` itself.
+ */
+type TableBuilder = { string(name: string): { primary(): unknown } };
+type KnexSlice = {
+  schema: { createTable(name: string, build: (t: TableBuilder) => void): Promise<unknown> };
+} & ((table: string) => { insert(row: Record<string, unknown>): Promise<unknown> });
+
+describe('TursoDriver.update() declared return type (#14438)', () => {
+  let driver: TursoDriver;
+
+  beforeEach(async () => {
+    driver = new TursoDriver({ url: ':memory:' });
+    const k = (driver as unknown as { knex: KnexSlice }).knex;
+    await k.schema.createTable('t', (t) => {
+      t.string('id').primary();
+      t.string('name');
+    });
+    await k('t').insert({ id: '1', name: 'before' });
+  });
+
+  afterEach(async () => {
+    await driver.disconnect();
+  });
+
+  it('pins the contract and the override at the type level', () => {
+    expect([contractUpdateDeclaresNull, tursoUpdateIsAny, tursoUpdateIsContract]).toEqual([true, false, true]);
+  });
+
+  it('update() on a missing id resolves to null on the local face, and the declared type makes the caller narrow', async () => {
+    const result = await driver.update('t', 'missing', { name: 'x' });
+    expect(result).toBeNull();
+
+    // The narrowing the declared type now demands of every caller.
+    const name = result === null ? 'absent' : result.name;
+    expect(name).toBe('absent');
+  });
+
+  it('update() on an existing id resolves to the updated record, behind the same narrowing', async () => {
+    const result = await driver.update('t', '1', { name: 'after' });
+    expect(result).not.toBeNull();
+    expect(result === null ? 'absent' : result.name).toBe('after');
+  });
+});