objectstack-ai · os-musk · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026
diff --git a/.changeset/driver-update-missing-id-null.md b/.changeset/driver-update-missing-id-null.md
@@ -0,0 +1,64 @@
+---
+"@objectstack/driver-mongodb": minor
+"@objectstack/driver-turso": minor
+---
+
+fix(drivers): `update()` on a missing id answers `null` on MongoDB and on Turso's remote face
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing alongside a
+runtime behaviour change, shipped as `minor` under the launch-window convention. Two
+published declared returns move: `MongoDBDriver.update()` and `RemoteTransport.update()`
+(both exported from their package index) now declare
+`Promise<Record<string, unknown> | null>` where they declared
+`Promise<Record<string, unknown>>`. A caller that reads fields off either result —
+`result.id`, `result.title` — no longer compiles until it narrows the `null` arm first.
+The narrowing is delivered by the compiler at every call site, and it is the honest
+declaration: the value that arm carries has always been reachable, it was simply being
+answered with a fabricated record instead.
+
+`IDataDriver.update()` declares `Promise<Record<string, unknown> | null>` — the
+not-found arm landed with the ruling on the contract (`packages/spec` is untouched here),
+and it is the answer `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and `TursoDriver`'s
+local face have always given. Two implementations did not honour it. They **invented a
+record** instead:
+
+- `MongoDBDriver.update()` ran `updateOne({ id })`, then `findOne({ id })`, and
+ when nothing came back returned
+ `withoutUndefinedOwnKeys({ id: String(id), ...updateData })` — a row assembled
+ from the caller's own payload plus the `updated_at` it had just stamped, under
+ an id that names no document.
+- `RemoteTransport.update()` ran `UPDATE … WHERE "id" = ?`, then
+ `SELECT * … WHERE "id" = ?`, and when no row came back returned
+ `{ id, ...data }` — the caller's payload with the id stapled on.
+
+Both now return `null`. That is the runtime half of this change, and it is why this
+release is not a pure type-surface move: the value a caller receives for a missing id is
+different at run time, not only in the `.d.ts`.
+
+This is the expensive direction of wrong, not merely the wrong answer: the
+fabricated row said **succeeded** where the truth was **not found**, and said it
+in a shape carrying the caller's own fields back, so nothing about it looked
+wrong. Through the engine's by-id door a REST / SDK / MCP `update` against a
+deleted or mistyped id answered **200 with a record that does not exist** — on
+these two implementations only. A caller, human or agent, read that as a landed
+write and did not retry, alert or roll back.
+
+Two things downstream become correct rather than merely different:
+
+- **One `TursoDriver`, one answer.** Its remote branch passes the transport
+ result through `formatRemoteRow`, which already guards
+ `row && typeof row === 'object'`, so `null` reaches the engine untouched and
+ the two faces converge with no edit at that seam. Previously the same driver
+ answered the same missing id two ways, chosen by `isRemote`.
+- **`RemoteTransport.bulkUpdate()`'s skip stops being dead code.**
+ `if (updated) results.push(updated)` is the cross-driver convention
+ `SqlDriver.bulkUpdate` follows; on this transport `updated` could never be
+ falsy, so a batch over N missing ids answered N invented rows. It now answers
+ the rows that exist.
+
+`upsert()` is untouched on both drivers: an upsert never answers "not found".
+
+No landed test pinned the fabricating posture on either driver, so the
+regression pins added here are net-new coverage rather than a changed baseline.
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata key is removed, renamed or re-shaped: the moving surfaces are two driver methods' declared return types and the value they answer for an id that names no row, so there is nothing for `objectstack migrate meta`, `spec-changes.json` or the upgrade guide to project, and this changeset prescribes no rewrite. The consumer obligation is a TypeScript narrowing at the call site, delivered by the compiler. `type-surface-only` is NOT claimable here: its predicate 4 (narrowed-from-erased) is false — neither declared return was `any` at the merge base, they were the non-null `Promise<Record<string, unknown>>` — and, independently, runtime behaviour moves in the same diff, which is more than a type surface. Same disposition and reasoning as `.changeset/driver-memory-update-upsert-honest-types.md` (PR #14434), one day earlier in this same series. -->
diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts
@@ -155,9 +155,13 @@ describe.skipIf(!sharedMongod)('MongoDBDriver', () => {
  it('should update a record and return updated data', async () => {
  await driver.create('task', { id: 'upd-1', title: 'Original', status: 'new' });
  const result = await driver.update('task', 'upd-1', { title: 'Updated', status: 'done' });
- expect(result.title).toBe('Updated');
- expect(result.status).toBe('done');
- expect(result.id).toBe('upd-1');
+ // `update()` declares `Record<string, unknown> | null` (#14428): a miss
+ // answers `null`. This case is the FOUND arm, so pin that first and read
+ // the fields through it -- same idiom as `findOne` above.
+ expect(result).not.toBeNull();
+ expect(result!.title).toBe('Updated');
+ expect(result!.status).toBe('done');
+ expect(result!.id).toBe('upd-1');
  expect(result).not.toHaveProperty('_id');
  });
 

diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.ts
@@ -400,7 +400,34 @@ export class MongoDBDriver implements IDataDriver {
  return result;
  }
 
- async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>> {
+ /**
+ * [#14428] A miss answers `null` — the arm `IDataDriver.update()` declares
+ * (#13878) and the one `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and
+ * `TursoDriver`'s local face already return.
+ *
+ * This door used to answer a missing id with a row ASSEMBLED from the
+ * caller's own payload plus the `updated_at` it had just stamped:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne` matched nothing, `findOne` came back `null`, and the caller was
+ * handed a record for an id that names no document. The reason that was ever
+ * written — "the declaration does not permit `null`, so something has to come
+ * back" — was removed by #13878; the posture outlived it. The maintainer
+ * ruled it out on 2026-09-03 (「同意」, decision batch #15 item 1, posture A).
+ *
+ * Why the fabricated row is the expensive direction, not merely the wrong
+ * one: it says SUCCEEDED where the truth is NOT FOUND, and it says so in a
+ * shape that carries the caller's own fields back, so nothing about it looks
+ * wrong. A caller — human or agent — reads it as a landed write and does not
+ * retry, alert or roll back. Through the engine's by-id door
+ * (`engine.ts` → `driver.update`) it surfaced as a REST/SDK/MCP `200` with a
+ * record that does not exist, on this driver and Turso's remote face only.
+ *
+ * ⚠️ `upsert()` is deliberately untouched: an upsert never answers
+ * "not found" (it inserts instead), so it has no not-found arm to declare.
+ */
+ async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown> | null> {
  const collection = this.getCollection(object);
  const session = this.getSession(options);
 
@@ -419,7 +446,7 @@ export class MongoDBDriver implements IDataDriver {
  { session, projection: { _id: 0 } },
  );
 
- return (updated as Record<string, unknown>) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ return (updated as Record<string, unknown> | null) ?? null;
  }
 
  async upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>> {

diff --git a/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts b/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts
@@ -0,0 +1,202 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#14428] `MongoDBDriver.update()` answers a missing id with `null`, not with
+ * a record it made up.
+ *
+ * # What was broken
+ *
+ * The door read:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne({ id })` matching nothing and `findOne({ id })` coming back `null`
+ * still produced a row — the caller's own payload plus the `updated_at` this
+ * driver had just stamped, under an id that names no document. Since #13878
+ * (PR #14434) `IDataDriver.update()` declares `Promise[Record[string, unknown]
+ * | null]`, so "a row for an id that does not exist" is no longer a way of
+ * satisfying the declaration: it is a value the declaration distinguishes from.
+ * Four of six shipped implementations already answered `null`; this one and
+ * Turso's remote face answered "updated". Maintainer ruling 2026-09-03,
+ * posture A.
+ *
+ * # Why this file exists at all
+ *
+ * The card measured that NO landed test pinned the miss posture on this driver
+ * — `mongodb-driver.test.ts:157,175` read `update()` results over rows that
+ * EXIST. So this is net-new coverage, and the fabricating posture could have
+ * come back without reddening anything.
+ *
+ * # Why it does not live in `mongodb-driver.test.ts`
+ *
+ * That suite is `describe.skipIf(!sharedMongod)` and `createTestMongod` skips
+ * it unless `OS_TEST_MONGODB_MEMORY_SERVER_ENABLED=1` (#5517 retired the
+ * 123 MB binary download that was ejecting unrelated PRs from the merge queue).
+ * A pin added there would be GREEN-BY-SKIP on every CI run — a phantom pin,
+ * which is worse than none: it reads as coverage in the file list and can
+ * never fail. The fake `Db` below is the pattern
+ * `mongodb-findone-options.test.ts` established and
+ * `mongodb-own-key-undefined.test.ts` reuses: `getCollection` is
+ * `this.db.collection(name)`, so replacing `db` observes every call the real
+ * code path makes, with no server and no download.
+ *
+ * # The pins, and what each alone would miss
+ *
+ * - **The miss pin** is the defect: `findOne` empty ⇒ `null`.
+ * - **The positive control** is what stops the fix from being "return `null`
+ * always". A driver that had simply deleted the read-back would pass the
+ * miss pin and break every update that works.
+ * - **The no-fabrication pin** asserts the specific shape that used to come
+ * back (the caller's fields, the stamped `updated_at`). `toBeNull()` alone
+ * would also be satisfied by a driver that threw and was caught elsewhere;
+ * this states what must NOT be synthesized.
+ * - **The write-still-issued pin** holds the other half of the contract: the
+ * `updateOne` is still sent. A "fix" that short-circuited on a miss by
+ * reading FIRST would answer `null` correctly and quietly stop writing.
+ *
+ * # ⚠️ There is deliberately NO type-level pin in this file — and NOT because
+ * # nothing would read one
+ *
+ * #13878's `memory-update-declared-null.test.ts` pins the declared return type
+ * with `Equals`/`IsAny` consts. That instrument reaches this file through only
+ * ONE program, and it is not the one whose name is on the package:
+ *
+ * - **This package's own `typecheck` script cannot see it.** `tsconfig.json`
+ * here carries `"exclude": [..., "**\/*.test.ts"]` (escaped so this comment
+ * does not terminate early), and `tsc --noEmit` reads that config. Measured,
+ * not assumed: `tsc --noEmit --listFiles` in this package lists 0 files
+ * ending `.test.ts` (the sibling `driver-turso`, whose tsconfig excludes
+ * only `node_modules`/`dist`, lists 43). vitest transpiles without
+ * typechecking, and the root `tsconfig.json` excludes `packages` entirely,
+ * so neither of those picks it up either. That exclusion is itself a filed
+ * defect (#14917), not a design.
+ * - **`pnpm check:type-check-debt` DOES compile it.** The ratchet's
+ * `--re-measure` leg generates a project that drops the test exclusion and
+ * runs `tsc` over this package with its tests un-hidden, then compares the
+ * error count to the frozen `TEST_DEBT['@objectstack/driver-mongodb']` entry
+ * (10: `TS1309` x7 + `TS2550` x3). ⭐ Not theory: the first head of this
+ * branch widened `update()`'s declaration, the three found-arm reads in
+ * `mongodb-driver.test.ts` became `TS18047 'result' is possibly 'null'`, and
+ * that lane went red at 13 (+3) while `pnpm typecheck` stayed green. CI
+ * caught in this file's layer exactly what the package's own typecheck is
+ * blind to.
+ *
+ * So a type pin here would not be a phantom — it would be checked, once, in a
+ * lane that reports a break as a ledger COUNT moving rather than as a named
+ * assertion failure, and that reports it only when someone runs the whole-repo
+ * re-measure. The declaration is pinned by better instruments instead, both of
+ * which run in this package's own `typecheck`:
+ *
+ * - **narrowing the declaration back** to `Promise[Record[string, unknown]]`
+ * is a `tsc` error in `mongodb-driver.ts` itself — that file IS in the
+ * program, and the body's `?? null` then returns `Record[string, unknown] |
+ * null` from a non-null signature. `pnpm --filter @objectstack/driver-mongodb
+ * typecheck` reds.
+ * - **losing the contract linkage** (should `IDataDriver.update()` drop its
+ * `| null` arm) reds the same typecheck through `implements IDataDriver`.
+ * - **reverting the behaviour** while keeping the signature reds the runtime
+ * pins below.
+ *
+ * # Reverse verification — predicted direction, then what was OBSERVED
+ *
+ * Predicted: restoring the `|| withoutUndefinedOwnKeys({ id: String(id),
+ * ...updateData })` fallback reds the miss pin and the no-fabrication pin,
+ * while the positive control and the write-still-issued pin stay GREEN — they
+ * exercise the found arm, which the revert does not touch.
+ *
+ * Observed, with the mutation proved on disk (injected text counted, deleted
+ * text absent) and the restore proved by a `git hash-object` match against the
+ * HEAD blob: `Test Files 1 failed (1)`, `Tests 2 failed | 2 passed (4)`. The
+ * two reds are the miss pin and the no-fabrication pin, by name. ⚠️ All FOUR
+ * cases ran — there is no compile-time leg here, because there is no type pin
+ * in this file to red; a prediction that the file would fail to typecheck as a
+ * whole would have been wrong for exactly that reason.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { MongoDBDriver } from './mongodb-driver.js';
+
+/** What the fake collection recorded, so the WRITE half stays observable. */
+interface Recorded {
+ updateOne: Array<{ filter: Record<string, unknown>; update: Record<string, unknown> }>;
+ findOne: Array<Record<string, unknown>>;
+}
+
+/**
+ * A driver wired to a recording fake `Db` — no `connect()`, no server.
+ *
+ * `stored` is the document `findOne` answers with; `null` models the miss (a
+ * real `findOne` resolves `null` when nothing matches), and an object models
+ * the row that exists.
+ */
+function makeDriver(stored: Record<string, unknown> | null) {
+ const recorded: Recorded = { updateOne: [], findOne: [] };
+ const collection = {
+ async updateOne(filter: Record<string, unknown>, update: Record<string, unknown>) {
+ recorded.updateOne.push({ filter, update });
+ return { matchedCount: stored ? 1 : 0, modifiedCount: stored ? 1 : 0 };
+ },
+ async findOne(filter: Record<string, unknown>) {
+ recorded.findOne.push(filter);
+ return stored;
+ },
+ };
+ const driver = new MongoDBDriver({ url: 'mongodb://127.0.0.1:1/probe' });
+ (driver as any).db = { collection: () => collection };
+ return { driver, recorded };
+}
+
+describe('[#14428] MongoDBDriver.update() on a missing id', () => {
+ it('resolves null when no document carries that id', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(result).toBeNull();
+ // The narrowing the declared type demands of every caller.
+ const title = result === null ? 'absent' : result.title;
+ expect(title).toBe('absent');
+ });
+
+ it('fabricates nothing — no id, no payload echo, no stamped updated_at', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited', owner: 'u1' });
+
+ // The exact shape the old fallback produced: `{ id, ...updateData }` with
+ // `updated_at` stamped a moment earlier. Asserted as a NON-match against a
+ // reconstruction of it, so the pin names the thing it forbids rather than
+ // only the thing it wants — `toBeNull()` alone would also be satisfied by a
+ // driver that threw and was caught somewhere up the stack.
+ //
+ // ⚠️ NOT written as `expect(result).not.toBeTypeOf('object')`: `typeof
+ // null` IS `'object'` in JS, so that assertion fails on the correct value.
+ expect(result).toBeNull();
+ expect(result).not.toMatchObject({ id: 'no-such-id' });
+ expect(Object.keys((result as Record<string, unknown> | null) ?? {})).toEqual([]);
+ });
+
+ it('still ISSUES the write — the miss is discovered by reading back, not by refusing', async () => {
+ const { driver, recorded } = makeDriver(null);
+
+ await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(recorded.updateOne).toHaveLength(1);
+ expect(recorded.updateOne[0].filter).toEqual({ id: 'no-such-id' });
+ expect((recorded.updateOne[0].update as any).$set.title).toBe('edited');
+ expect(recorded.findOne).toHaveLength(1);
+ expect(recorded.findOne[0]).toEqual({ id: 'no-such-id' });
+ });
+
+ it('POSITIVE CONTROL — an id that DOES exist still returns the stored row', async () => {
+ const stored = { id: 'task-1', title: 'edited', owner: 'u1', updated_at: new Date('2026-01-01T00:00:00Z') };
+ const { driver } = makeDriver(stored);
+
+ const result = await driver.update('task', 'task-1', { title: 'edited' });
+
+ expect(result).not.toBeNull();
+ expect(result!.id).toBe('task-1');
+ expect(result!.title).toBe('edited');
+ });
+});
diff --git a/.changeset/driver-update-missing-id-null.md b/.changeset/driver-update-missing-id-null.md
@@ -0,0 +1,64 @@
+---
+"@objectstack/driver-mongodb": minor
+"@objectstack/driver-turso": minor
+---
+
+fix(drivers): `update()` on a missing id answers `null` on MongoDB and on Turso's remote face
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing alongside a
+runtime behaviour change, shipped as `minor` under the launch-window convention. Two
+published declared returns move: `MongoDBDriver.update()` and `RemoteTransport.update()`
+(both exported from their package index) now declare
+`Promise<Record<string, unknown> | null>` where they declared
+`Promise<Record<string, unknown>>`. A caller that reads fields off either result —
+`result.id`, `result.title` — no longer compiles until it narrows the `null` arm first.
+The narrowing is delivered by the compiler at every call site, and it is the honest
+declaration: the value that arm carries has always been reachable, it was simply being
+answered with a fabricated record instead.
+
+`IDataDriver.update()` declares `Promise<Record<string, unknown> | null>` — the
+not-found arm landed with the ruling on the contract (`packages/spec` is untouched here),
+and it is the answer `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and `TursoDriver`'s
+local face have always given. Two implementations did not honour it. They **invented a
+record** instead:
+
+- `MongoDBDriver.update()` ran `updateOne({ id })`, then `findOne({ id })`, and
+ when nothing came back returned
+ `withoutUndefinedOwnKeys({ id: String(id), ...updateData })` — a row assembled
+ from the caller's own payload plus the `updated_at` it had just stamped, under
+ an id that names no document.
+- `RemoteTransport.update()` ran `UPDATE … WHERE "id" = ?`, then
+ `SELECT * … WHERE "id" = ?`, and when no row came back returned
+ `{ id, ...data }` — the caller's payload with the id stapled on.
+
+Both now return `null`. That is the runtime half of this change, and it is why this
+release is not a pure type-surface move: the value a caller receives for a missing id is
+different at run time, not only in the `.d.ts`.
+
+This is the expensive direction of wrong, not merely the wrong answer: the
+fabricated row said **succeeded** where the truth was **not found**, and said it
+in a shape carrying the caller's own fields back, so nothing about it looked
+wrong. Through the engine's by-id door a REST / SDK / MCP `update` against a
+deleted or mistyped id answered **200 with a record that does not exist** — on
+these two implementations only. A caller, human or agent, read that as a landed
+write and did not retry, alert or roll back.
+
+Two things downstream become correct rather than merely different:
+
+- **One `TursoDriver`, one answer.** Its remote branch passes the transport
+ result through `formatRemoteRow`, which already guards
+ `row && typeof row === 'object'`, so `null` reaches the engine untouched and
+ the two faces converge with no edit at that seam. Previously the same driver
+ answered the same missing id two ways, chosen by `isRemote`.
+- **`RemoteTransport.bulkUpdate()`'s skip stops being dead code.**
+ `if (updated) results.push(updated)` is the cross-driver convention
+ `SqlDriver.bulkUpdate` follows; on this transport `updated` could never be
+ falsy, so a batch over N missing ids answered N invented rows. It now answers
+ the rows that exist.
+
+`upsert()` is untouched on both drivers: an upsert never answers "not found".
+
+No landed test pinned the fabricating posture on either driver, so the
+regression pins added here are net-new coverage rather than a changed baseline.
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata key is removed, renamed or re-shaped: the moving surfaces are two driver methods' declared return types and the value they answer for an id that names no row, so there is nothing for `objectstack migrate meta`, `spec-changes.json` or the upgrade guide to project, and this changeset prescribes no rewrite. The consumer obligation is a TypeScript narrowing at the call site, delivered by the compiler. `type-surface-only` is NOT claimable here: its predicate 4 (narrowed-from-erased) is false — neither declared return was `any` at the merge base, they were the non-null `Promise<Record<string, unknown>>` — and, independently, runtime behaviour moves in the same diff, which is more than a type surface. Same disposition and reasoning as `.changeset/driver-memory-update-upsert-honest-types.md` (PR #14434), one day earlier in this same series. -->
diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts
@@ -155,9 +155,13 @@ describe.skipIf(!sharedMongod)('MongoDBDriver', () => {
  it('should update a record and return updated data', async () => {
  await driver.create('task', { id: 'upd-1', title: 'Original', status: 'new' });
  const result = await driver.update('task', 'upd-1', { title: 'Updated', status: 'done' });
- expect(result.title).toBe('Updated');
- expect(result.status).toBe('done');
- expect(result.id).toBe('upd-1');
+ // `update()` declares `Record<string, unknown> | null` (#14428): a miss
+ // answers `null`. This case is the FOUND arm, so pin that first and read
+ // the fields through it -- same idiom as `findOne` above.
+ expect(result).not.toBeNull();
+ expect(result!.title).toBe('Updated');
+ expect(result!.status).toBe('done');
+ expect(result!.id).toBe('upd-1');
  expect(result).not.toHaveProperty('_id');
  });
 

diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.ts
@@ -400,7 +400,34 @@ export class MongoDBDriver implements IDataDriver {
  return result;
  }
 
- async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>> {
+ /**
+ * [#14428] A miss answers `null` — the arm `IDataDriver.update()` declares
+ * (#13878) and the one `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and
+ * `TursoDriver`'s local face already return.
+ *
+ * This door used to answer a missing id with a row ASSEMBLED from the
+ * caller's own payload plus the `updated_at` it had just stamped:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne` matched nothing, `findOne` came back `null`, and the caller was
+ * handed a record for an id that names no document. The reason that was ever
+ * written — "the declaration does not permit `null`, so something has to come
+ * back" — was removed by #13878; the posture outlived it. The maintainer
+ * ruled it out on 2026-09-03 (「同意」, decision batch #15 item 1, posture A).
+ *
+ * Why the fabricated row is the expensive direction, not merely the wrong
+ * one: it says SUCCEEDED where the truth is NOT FOUND, and it says so in a
+ * shape that carries the caller's own fields back, so nothing about it looks
+ * wrong. A caller — human or agent — reads it as a landed write and does not
+ * retry, alert or roll back. Through the engine's by-id door
+ * (`engine.ts` → `driver.update`) it surfaced as a REST/SDK/MCP `200` with a
+ * record that does not exist, on this driver and Turso's remote face only.
+ *
+ * ⚠️ `upsert()` is deliberately untouched: an upsert never answers
+ * "not found" (it inserts instead), so it has no not-found arm to declare.
+ */
+ async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown> | null> {
  const collection = this.getCollection(object);
  const session = this.getSession(options);
 
@@ -419,7 +446,7 @@ export class MongoDBDriver implements IDataDriver {
  { session, projection: { _id: 0 } },
  );
 
- return (updated as Record<string, unknown>) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ return (updated as Record<string, unknown> | null) ?? null;
  }
 
  async upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>> {

diff --git a/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts b/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts
@@ -0,0 +1,202 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#14428] `MongoDBDriver.update()` answers a missing id with `null`, not with
+ * a record it made up.
+ *
+ * # What was broken
+ *
+ * The door read:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne({ id })` matching nothing and `findOne({ id })` coming back `null`
+ * still produced a row — the caller's own payload plus the `updated_at` this
+ * driver had just stamped, under an id that names no document. Since #13878
+ * (PR #14434) `IDataDriver.update()` declares `Promise[Record[string, unknown]
+ * | null]`, so "a row for an id that does not exist" is no longer a way of
+ * satisfying the declaration: it is a value the declaration distinguishes from.
+ * Four of six shipped implementations already answered `null`; this one and
+ * Turso's remote face answered "updated". Maintainer ruling 2026-09-03,
+ * posture A.
+ *
+ * # Why this file exists at all
+ *
+ * The card measured that NO landed test pinned the miss posture on this driver
+ * — `mongodb-driver.test.ts:157,175` read `update()` results over rows that
+ * EXIST. So this is net-new coverage, and the fabricating posture could have
+ * come back without reddening anything.
+ *
+ * # Why it does not live in `mongodb-driver.test.ts`
+ *
+ * That suite is `describe.skipIf(!sharedMongod)` and `createTestMongod` skips
+ * it unless `OS_TEST_MONGODB_MEMORY_SERVER_ENABLED=1` (#5517 retired the
+ * 123 MB binary download that was ejecting unrelated PRs from the merge queue).
+ * A pin added there would be GREEN-BY-SKIP on every CI run — a phantom pin,
+ * which is worse than none: it reads as coverage in the file list and can
+ * never fail. The fake `Db` below is the pattern
+ * `mongodb-findone-options.test.ts` established and
+ * `mongodb-own-key-undefined.test.ts` reuses: `getCollection` is
+ * `this.db.collection(name)`, so replacing `db` observes every call the real
+ * code path makes, with no server and no download.
+ *
+ * # The pins, and what each alone would miss
+ *
+ * - **The miss pin** is the defect: `findOne` empty ⇒ `null`.
+ * - **The positive control** is what stops the fix from being "return `null`
+ * always". A driver that had simply deleted the read-back would pass the
+ * miss pin and break every update that works.
+ * - **The no-fabrication pin** asserts the specific shape that used to come
+ * back (the caller's fields, the stamped `updated_at`). `toBeNull()` alone
+ * would also be satisfied by a driver that threw and was caught elsewhere;
+ * this states what must NOT be synthesized.
+ * - **The write-still-issued pin** holds the other half of the contract: the
+ * `updateOne` is still sent. A "fix" that short-circuited on a miss by
+ * reading FIRST would answer `null` correctly and quietly stop writing.
+ *
+ * # ⚠️ There is deliberately NO type-level pin in this file — and NOT because
+ * # nothing would read one
+ *
+ * #13878's `memory-update-declared-null.test.ts` pins the declared return type
+ * with `Equals`/`IsAny` consts. That instrument reaches this file through only
+ * ONE program, and it is not the one whose name is on the package:
+ *
+ * - **This package's own `typecheck` script cannot see it.** `tsconfig.json`
+ * here carries `"exclude": [..., "**\/*.test.ts"]` (escaped so this comment
+ * does not terminate early), and `tsc --noEmit` reads that config. Measured,
+ * not assumed: `tsc --noEmit --listFiles` in this package lists 0 files
+ * ending `.test.ts` (the sibling `driver-turso`, whose tsconfig excludes
+ * only `node_modules`/`dist`, lists 43). vitest transpiles without
+ * typechecking, and the root `tsconfig.json` excludes `packages` entirely,
+ * so neither of those picks it up either. That exclusion is itself a filed
+ * defect (#14917), not a design.
+ * - **`pnpm check:type-check-debt` DOES compile it.** The ratchet's
+ * `--re-measure` leg generates a project that drops the test exclusion and
+ * runs `tsc` over this package with its tests un-hidden, then compares the
+ * error count to the frozen `TEST_DEBT['@objectstack/driver-mongodb']` entry
+ * (10: `TS1309` x7 + `TS2550` x3). ⭐ Not theory: the first head of this
+ * branch widened `update()`'s declaration, the three found-arm reads in
+ * `mongodb-driver.test.ts` became `TS18047 'result' is possibly 'null'`, and
+ * that lane went red at 13 (+3) while `pnpm typecheck` stayed green. CI
+ * caught in this file's layer exactly what the package's own typecheck is
+ * blind to.
+ *
+ * So a type pin here would not be a phantom — it would be checked, once, in a
+ * lane that reports a break as a ledger COUNT moving rather than as a named
+ * assertion failure, and that reports it only when someone runs the whole-repo
+ * re-measure. The declaration is pinned by better instruments instead, both of
+ * which run in this package's own `typecheck`:
+ *
+ * - **narrowing the declaration back** to `Promise[Record[string, unknown]]`
+ * is a `tsc` error in `mongodb-driver.ts` itself — that file IS in the
+ * program, and the body's `?? null` then returns `Record[string, unknown] |
+ * null` from a non-null signature. `pnpm --filter @objectstack/driver-mongodb
+ * typecheck` reds.
+ * - **losing the contract linkage** (should `IDataDriver.update()` drop its
+ * `| null` arm) reds the same typecheck through `implements IDataDriver`.
+ * - **reverting the behaviour** while keeping the signature reds the runtime
+ * pins below.
+ *
+ * # Reverse verification — predicted direction, then what was OBSERVED
+ *
+ * Predicted: restoring the `|| withoutUndefinedOwnKeys({ id: String(id),
+ * ...updateData })` fallback reds the miss pin and the no-fabrication pin,
+ * while the positive control and the write-still-issued pin stay GREEN — they
+ * exercise the found arm, which the revert does not touch.
+ *
+ * Observed, with the mutation proved on disk (injected text counted, deleted
+ * text absent) and the restore proved by a `git hash-object` match against the
+ * HEAD blob: `Test Files 1 failed (1)`, `Tests 2 failed | 2 passed (4)`. The
+ * two reds are the miss pin and the no-fabrication pin, by name. ⚠️ All FOUR
+ * cases ran — there is no compile-time leg here, because there is no type pin
+ * in this file to red; a prediction that the file would fail to typecheck as a
+ * whole would have been wrong for exactly that reason.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { MongoDBDriver } from './mongodb-driver.js';
+
+/** What the fake collection recorded, so the WRITE half stays observable. */
+interface Recorded {
+ updateOne: Array<{ filter: Record<string, unknown>; update: Record<string, unknown> }>;
+ findOne: Array<Record<string, unknown>>;
+}
+
+/**
+ * A driver wired to a recording fake `Db` — no `connect()`, no server.
+ *
+ * `stored` is the document `findOne` answers with; `null` models the miss (a
+ * real `findOne` resolves `null` when nothing matches), and an object models
+ * the row that exists.
+ */
+function makeDriver(stored: Record<string, unknown> | null) {
+ const recorded: Recorded = { updateOne: [], findOne: [] };
+ const collection = {
+ async updateOne(filter: Record<string, unknown>, update: Record<string, unknown>) {
+ recorded.updateOne.push({ filter, update });
+ return { matchedCount: stored ? 1 : 0, modifiedCount: stored ? 1 : 0 };
+ },
+ async findOne(filter: Record<string, unknown>) {
+ recorded.findOne.push(filter);
+ return stored;
+ },
+ };
+ const driver = new MongoDBDriver({ url: 'mongodb://127.0.0.1:1/probe' });
+ (driver as any).db = { collection: () => collection };
+ return { driver, recorded };
+}
+
+describe('[#14428] MongoDBDriver.update() on a missing id', () => {
+ it('resolves null when no document carries that id', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(result).toBeNull();
+ // The narrowing the declared type demands of every caller.
+ const title = result === null ? 'absent' : result.title;
+ expect(title).toBe('absent');
+ });
+
+ it('fabricates nothing — no id, no payload echo, no stamped updated_at', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited', owner: 'u1' });
+
+ // The exact shape the old fallback produced: `{ id, ...updateData }` with
+ // `updated_at` stamped a moment earlier. Asserted as a NON-match against a
+ // reconstruction of it, so the pin names the thing it forbids rather than
+ // only the thing it wants — `toBeNull()` alone would also be satisfied by a
+ // driver that threw and was caught somewhere up the stack.
+ //
+ // ⚠️ NOT written as `expect(result).not.toBeTypeOf('object')`: `typeof
+ // null` IS `'object'` in JS, so that assertion fails on the correct value.
+ expect(result).toBeNull();
+ expect(result).not.toMatchObject({ id: 'no-such-id' });
+ expect(Object.keys((result as Record<string, unknown> | null) ?? {})).toEqual([]);
+ });
+
+ it('still ISSUES the write — the miss is discovered by reading back, not by refusing', async () => {
+ const { driver, recorded } = makeDriver(null);
+
+ await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(recorded.updateOne).toHaveLength(1);
+ expect(recorded.updateOne[0].filter).toEqual({ id: 'no-such-id' });
+ expect((recorded.updateOne[0].update as any).$set.title).toBe('edited');
+ expect(recorded.findOne).toHaveLength(1);
+ expect(recorded.findOne[0]).toEqual({ id: 'no-such-id' });
+ });
+
+ it('POSITIVE CONTROL — an id that DOES exist still returns the stored row', async () => {
+ const stored = { id: 'task-1', title: 'edited', owner: 'u1', updated_at: new Date('2026-01-01T00:00:00Z') };
+ const { driver } = makeDriver(stored);
+
+ const result = await driver.update('task', 'task-1', { title: 'edited' });
+
+ expect(result).not.toBeNull();
+ expect(result!.id).toBe('task-1');
+ expect(result!.title).toBe('edited');
+ });
+});
diff --git a/.changeset/driver-update-missing-id-null.md b/.changeset/driver-update-missing-id-null.md
@@ -0,0 +1,64 @@
+---
+"@objectstack/driver-mongodb": minor
+"@objectstack/driver-turso": minor
+---
+
+fix(drivers): `update()` on a missing id answers `null` on MongoDB and on Turso's remote face
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing alongside a
+runtime behaviour change, shipped as `minor` under the launch-window convention. Two
+published declared returns move: `MongoDBDriver.update()` and `RemoteTransport.update()`
+(both exported from their package index) now declare
+`Promise<Record<string, unknown> | null>` where they declared
+`Promise<Record<string, unknown>>`. A caller that reads fields off either result —
+`result.id`, `result.title` — no longer compiles until it narrows the `null` arm first.
+The narrowing is delivered by the compiler at every call site, and it is the honest
+declaration: the value that arm carries has always been reachable, it was simply being
+answered with a fabricated record instead.
+
+`IDataDriver.update()` declares `Promise<Record<string, unknown> | null>` — the
+not-found arm landed with the ruling on the contract (`packages/spec` is untouched here),
+and it is the answer `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and `TursoDriver`'s
+local face have always given. Two implementations did not honour it. They **invented a
+record** instead:
+
+- `MongoDBDriver.update()` ran `updateOne({ id })`, then `findOne({ id })`, and
+ when nothing came back returned
+ `withoutUndefinedOwnKeys({ id: String(id), ...updateData })` — a row assembled
+ from the caller's own payload plus the `updated_at` it had just stamped, under
+ an id that names no document.
+- `RemoteTransport.update()` ran `UPDATE … WHERE "id" = ?`, then
+ `SELECT * … WHERE "id" = ?`, and when no row came back returned
+ `{ id, ...data }` — the caller's payload with the id stapled on.
+
+Both now return `null`. That is the runtime half of this change, and it is why this
+release is not a pure type-surface move: the value a caller receives for a missing id is
+different at run time, not only in the `.d.ts`.
+
+This is the expensive direction of wrong, not merely the wrong answer: the
+fabricated row said **succeeded** where the truth was **not found**, and said it
+in a shape carrying the caller's own fields back, so nothing about it looked
+wrong. Through the engine's by-id door a REST / SDK / MCP `update` against a
+deleted or mistyped id answered **200 with a record that does not exist** — on
+these two implementations only. A caller, human or agent, read that as a landed
+write and did not retry, alert or roll back.
+
+Two things downstream become correct rather than merely different:
+
+- **One `TursoDriver`, one answer.** Its remote branch passes the transport
+ result through `formatRemoteRow`, which already guards
+ `row && typeof row === 'object'`, so `null` reaches the engine untouched and
+ the two faces converge with no edit at that seam. Previously the same driver
+ answered the same missing id two ways, chosen by `isRemote`.
+- **`RemoteTransport.bulkUpdate()`'s skip stops being dead code.**
+ `if (updated) results.push(updated)` is the cross-driver convention
+ `SqlDriver.bulkUpdate` follows; on this transport `updated` could never be
+ falsy, so a batch over N missing ids answered N invented rows. It now answers
+ the rows that exist.
+
+`upsert()` is untouched on both drivers: an upsert never answers "not found".
+
+No landed test pinned the fabricating posture on either driver, so the
+regression pins added here are net-new coverage rather than a changed baseline.
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata key is removed, renamed or re-shaped: the moving surfaces are two driver methods' declared return types and the value they answer for an id that names no row, so there is nothing for `objectstack migrate meta`, `spec-changes.json` or the upgrade guide to project, and this changeset prescribes no rewrite. The consumer obligation is a TypeScript narrowing at the call site, delivered by the compiler. `type-surface-only` is NOT claimable here: its predicate 4 (narrowed-from-erased) is false — neither declared return was `any` at the merge base, they were the non-null `Promise<Record<string, unknown>>` — and, independently, runtime behaviour moves in the same diff, which is more than a type surface. Same disposition and reasoning as `.changeset/driver-memory-update-upsert-honest-types.md` (PR #14434), one day earlier in this same series. -->
diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts
@@ -155,9 +155,13 @@ describe.skipIf(!sharedMongod)('MongoDBDriver', () => {
  it('should update a record and return updated data', async () => {
  await driver.create('task', { id: 'upd-1', title: 'Original', status: 'new' });
  const result = await driver.update('task', 'upd-1', { title: 'Updated', status: 'done' });
- expect(result.title).toBe('Updated');
- expect(result.status).toBe('done');
- expect(result.id).toBe('upd-1');
+ // `update()` declares `Record<string, unknown> | null` (#14428): a miss
+ // answers `null`. This case is the FOUND arm, so pin that first and read
+ // the fields through it -- same idiom as `findOne` above.
+ expect(result).not.toBeNull();
+ expect(result!.title).toBe('Updated');
+ expect(result!.status).toBe('done');
+ expect(result!.id).toBe('upd-1');
  expect(result).not.toHaveProperty('_id');
  });
 

diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.ts
@@ -400,7 +400,34 @@ export class MongoDBDriver implements IDataDriver {
  return result;
  }
 
- async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>> {
+ /**
+ * [#14428] A miss answers `null` — the arm `IDataDriver.update()` declares
+ * (#13878) and the one `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and
+ * `TursoDriver`'s local face already return.
+ *
+ * This door used to answer a missing id with a row ASSEMBLED from the
+ * caller's own payload plus the `updated_at` it had just stamped:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne` matched nothing, `findOne` came back `null`, and the caller was
+ * handed a record for an id that names no document. The reason that was ever
+ * written — "the declaration does not permit `null`, so something has to come
+ * back" — was removed by #13878; the posture outlived it. The maintainer
+ * ruled it out on 2026-09-03 (「同意」, decision batch #15 item 1, posture A).
+ *
+ * Why the fabricated row is the expensive direction, not merely the wrong
+ * one: it says SUCCEEDED where the truth is NOT FOUND, and it says so in a
+ * shape that carries the caller's own fields back, so nothing about it looks
+ * wrong. A caller — human or agent — reads it as a landed write and does not
+ * retry, alert or roll back. Through the engine's by-id door
+ * (`engine.ts` → `driver.update`) it surfaced as a REST/SDK/MCP `200` with a
+ * record that does not exist, on this driver and Turso's remote face only.
+ *
+ * ⚠️ `upsert()` is deliberately untouched: an upsert never answers
+ * "not found" (it inserts instead), so it has no not-found arm to declare.
+ */
+ async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown> | null> {
  const collection = this.getCollection(object);
  const session = this.getSession(options);
 
@@ -419,7 +446,7 @@ export class MongoDBDriver implements IDataDriver {
  { session, projection: { _id: 0 } },
  );
 
- return (updated as Record<string, unknown>) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ return (updated as Record<string, unknown> | null) ?? null;
  }
 
  async upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>> {

diff --git a/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts b/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts
@@ -0,0 +1,202 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#14428] `MongoDBDriver.update()` answers a missing id with `null`, not with
+ * a record it made up.
+ *
+ * # What was broken
+ *
+ * The door read:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne({ id })` matching nothing and `findOne({ id })` coming back `null`
+ * still produced a row — the caller's own payload plus the `updated_at` this
+ * driver had just stamped, under an id that names no document. Since #13878
+ * (PR #14434) `IDataDriver.update()` declares `Promise[Record[string, unknown]
+ * | null]`, so "a row for an id that does not exist" is no longer a way of
+ * satisfying the declaration: it is a value the declaration distinguishes from.
+ * Four of six shipped implementations already answered `null`; this one and
+ * Turso's remote face answered "updated". Maintainer ruling 2026-09-03,
+ * posture A.
+ *
+ * # Why this file exists at all
+ *
+ * The card measured that NO landed test pinned the miss posture on this driver
+ * — `mongodb-driver.test.ts:157,175` read `update()` results over rows that
+ * EXIST. So this is net-new coverage, and the fabricating posture could have
+ * come back without reddening anything.
+ *
+ * # Why it does not live in `mongodb-driver.test.ts`
+ *
+ * That suite is `describe.skipIf(!sharedMongod)` and `createTestMongod` skips
+ * it unless `OS_TEST_MONGODB_MEMORY_SERVER_ENABLED=1` (#5517 retired the
+ * 123 MB binary download that was ejecting unrelated PRs from the merge queue).
+ * A pin added there would be GREEN-BY-SKIP on every CI run — a phantom pin,
+ * which is worse than none: it reads as coverage in the file list and can
+ * never fail. The fake `Db` below is the pattern
+ * `mongodb-findone-options.test.ts` established and
+ * `mongodb-own-key-undefined.test.ts` reuses: `getCollection` is
+ * `this.db.collection(name)`, so replacing `db` observes every call the real
+ * code path makes, with no server and no download.
+ *
+ * # The pins, and what each alone would miss
+ *
+ * - **The miss pin** is the defect: `findOne` empty ⇒ `null`.
+ * - **The positive control** is what stops the fix from being "return `null`
+ * always". A driver that had simply deleted the read-back would pass the
+ * miss pin and break every update that works.
+ * - **The no-fabrication pin** asserts the specific shape that used to come
+ * back (the caller's fields, the stamped `updated_at`). `toBeNull()` alone
+ * would also be satisfied by a driver that threw and was caught elsewhere;
+ * this states what must NOT be synthesized.
+ * - **The write-still-issued pin** holds the other half of the contract: the
+ * `updateOne` is still sent. A "fix" that short-circuited on a miss by
+ * reading FIRST would answer `null` correctly and quietly stop writing.
+ *
+ * # ⚠️ There is deliberately NO type-level pin in this file — and NOT because
+ * # nothing would read one
+ *
+ * #13878's `memory-update-declared-null.test.ts` pins the declared return type
+ * with `Equals`/`IsAny` consts. That instrument reaches this file through only
+ * ONE program, and it is not the one whose name is on the package:
+ *
+ * - **This package's own `typecheck` script cannot see it.** `tsconfig.json`
+ * here carries `"exclude": [..., "**\/*.test.ts"]` (escaped so this comment
+ * does not terminate early), and `tsc --noEmit` reads that config. Measured,
+ * not assumed: `tsc --noEmit --listFiles` in this package lists 0 files
+ * ending `.test.ts` (the sibling `driver-turso`, whose tsconfig excludes
+ * only `node_modules`/`dist`, lists 43). vitest transpiles without
+ * typechecking, and the root `tsconfig.json` excludes `packages` entirely,
+ * so neither of those picks it up either. That exclusion is itself a filed
+ * defect (#14917), not a design.
+ * - **`pnpm check:type-check-debt` DOES compile it.** The ratchet's
+ * `--re-measure` leg generates a project that drops the test exclusion and
+ * runs `tsc` over this package with its tests un-hidden, then compares the
+ * error count to the frozen `TEST_DEBT['@objectstack/driver-mongodb']` entry
+ * (10: `TS1309` x7 + `TS2550` x3). ⭐ Not theory: the first head of this
+ * branch widened `update()`'s declaration, the three found-arm reads in
+ * `mongodb-driver.test.ts` became `TS18047 'result' is possibly 'null'`, and
+ * that lane went red at 13 (+3) while `pnpm typecheck` stayed green. CI
+ * caught in this file's layer exactly what the package's own typecheck is
+ * blind to.
+ *
+ * So a type pin here would not be a phantom — it would be checked, once, in a
+ * lane that reports a break as a ledger COUNT moving rather than as a named
+ * assertion failure, and that reports it only when someone runs the whole-repo
+ * re-measure. The declaration is pinned by better instruments instead, both of
+ * which run in this package's own `typecheck`:
+ *
+ * - **narrowing the declaration back** to `Promise[Record[string, unknown]]`
+ * is a `tsc` error in `mongodb-driver.ts` itself — that file IS in the
+ * program, and the body's `?? null` then returns `Record[string, unknown] |
+ * null` from a non-null signature. `pnpm --filter @objectstack/driver-mongodb
+ * typecheck` reds.
+ * - **losing the contract linkage** (should `IDataDriver.update()` drop its
+ * `| null` arm) reds the same typecheck through `implements IDataDriver`.
+ * - **reverting the behaviour** while keeping the signature reds the runtime
+ * pins below.
+ *
+ * # Reverse verification — predicted direction, then what was OBSERVED
+ *
+ * Predicted: restoring the `|| withoutUndefinedOwnKeys({ id: String(id),
+ * ...updateData })` fallback reds the miss pin and the no-fabrication pin,
+ * while the positive control and the write-still-issued pin stay GREEN — they
+ * exercise the found arm, which the revert does not touch.
+ *
+ * Observed, with the mutation proved on disk (injected text counted, deleted
+ * text absent) and the restore proved by a `git hash-object` match against the
+ * HEAD blob: `Test Files 1 failed (1)`, `Tests 2 failed | 2 passed (4)`. The
+ * two reds are the miss pin and the no-fabrication pin, by name. ⚠️ All FOUR
+ * cases ran — there is no compile-time leg here, because there is no type pin
+ * in this file to red; a prediction that the file would fail to typecheck as a
+ * whole would have been wrong for exactly that reason.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { MongoDBDriver } from './mongodb-driver.js';
+
+/** What the fake collection recorded, so the WRITE half stays observable. */
+interface Recorded {
+ updateOne: Array<{ filter: Record<string, unknown>; update: Record<string, unknown> }>;
+ findOne: Array<Record<string, unknown>>;
+}
+
+/**
+ * A driver wired to a recording fake `Db` — no `connect()`, no server.
+ *
+ * `stored` is the document `findOne` answers with; `null` models the miss (a
+ * real `findOne` resolves `null` when nothing matches), and an object models
+ * the row that exists.
+ */
+function makeDriver(stored: Record<string, unknown> | null) {
+ const recorded: Recorded = { updateOne: [], findOne: [] };
+ const collection = {
+ async updateOne(filter: Record<string, unknown>, update: Record<string, unknown>) {
+ recorded.updateOne.push({ filter, update });
+ return { matchedCount: stored ? 1 : 0, modifiedCount: stored ? 1 : 0 };
+ },
+ async findOne(filter: Record<string, unknown>) {
+ recorded.findOne.push(filter);
+ return stored;
+ },
+ };
+ const driver = new MongoDBDriver({ url: 'mongodb://127.0.0.1:1/probe' });
+ (driver as any).db = { collection: () => collection };
+ return { driver, recorded };
+}
+
+describe('[#14428] MongoDBDriver.update() on a missing id', () => {
+ it('resolves null when no document carries that id', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(result).toBeNull();
+ // The narrowing the declared type demands of every caller.
+ const title = result === null ? 'absent' : result.title;
+ expect(title).toBe('absent');
+ });
+
+ it('fabricates nothing — no id, no payload echo, no stamped updated_at', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited', owner: 'u1' });
+
+ // The exact shape the old fallback produced: `{ id, ...updateData }` with
+ // `updated_at` stamped a moment earlier. Asserted as a NON-match against a
+ // reconstruction of it, so the pin names the thing it forbids rather than
+ // only the thing it wants — `toBeNull()` alone would also be satisfied by a
+ // driver that threw and was caught somewhere up the stack.
+ //
+ // ⚠️ NOT written as `expect(result).not.toBeTypeOf('object')`: `typeof
+ // null` IS `'object'` in JS, so that assertion fails on the correct value.
+ expect(result).toBeNull();
+ expect(result).not.toMatchObject({ id: 'no-such-id' });
+ expect(Object.keys((result as Record<string, unknown> | null) ?? {})).toEqual([]);
+ });
+
+ it('still ISSUES the write — the miss is discovered by reading back, not by refusing', async () => {
+ const { driver, recorded } = makeDriver(null);
+
+ await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(recorded.updateOne).toHaveLength(1);
+ expect(recorded.updateOne[0].filter).toEqual({ id: 'no-such-id' });
+ expect((recorded.updateOne[0].update as any).$set.title).toBe('edited');
+ expect(recorded.findOne).toHaveLength(1);
+ expect(recorded.findOne[0]).toEqual({ id: 'no-such-id' });
+ });
+
+ it('POSITIVE CONTROL — an id that DOES exist still returns the stored row', async () => {
+ const stored = { id: 'task-1', title: 'edited', owner: 'u1', updated_at: new Date('2026-01-01T00:00:00Z') };
+ const { driver } = makeDriver(stored);
+
+ const result = await driver.update('task', 'task-1', { title: 'edited' });
+
+ expect(result).not.toBeNull();
+ expect(result!.id).toBe('task-1');
+ expect(result!.title).toBe('edited');
+ });
+});
diff --git a/.changeset/driver-update-missing-id-null.md b/.changeset/driver-update-missing-id-null.md
@@ -0,0 +1,64 @@
+---
+"@objectstack/driver-mongodb": minor
+"@objectstack/driver-turso": minor
+---
+
+fix(drivers): `update()` on a missing id answers `null` on MongoDB and on Turso's remote face
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing alongside a
+runtime behaviour change, shipped as `minor` under the launch-window convention. Two
+published declared returns move: `MongoDBDriver.update()` and `RemoteTransport.update()`
+(both exported from their package index) now declare
+`Promise<Record<string, unknown> | null>` where they declared
+`Promise<Record<string, unknown>>`. A caller that reads fields off either result —
+`result.id`, `result.title` — no longer compiles until it narrows the `null` arm first.
+The narrowing is delivered by the compiler at every call site, and it is the honest
+declaration: the value that arm carries has always been reachable, it was simply being
+answered with a fabricated record instead.
+
+`IDataDriver.update()` declares `Promise<Record<string, unknown> | null>` — the
+not-found arm landed with the ruling on the contract (`packages/spec` is untouched here),
+and it is the answer `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and `TursoDriver`'s
+local face have always given. Two implementations did not honour it. They **invented a
+record** instead:
+
+- `MongoDBDriver.update()` ran `updateOne({ id })`, then `findOne({ id })`, and
+ when nothing came back returned
+ `withoutUndefinedOwnKeys({ id: String(id), ...updateData })` — a row assembled
+ from the caller's own payload plus the `updated_at` it had just stamped, under
+ an id that names no document.
+- `RemoteTransport.update()` ran `UPDATE … WHERE "id" = ?`, then
+ `SELECT * … WHERE "id" = ?`, and when no row came back returned
+ `{ id, ...data }` — the caller's payload with the id stapled on.
+
+Both now return `null`. That is the runtime half of this change, and it is why this
+release is not a pure type-surface move: the value a caller receives for a missing id is
+different at run time, not only in the `.d.ts`.
+
+This is the expensive direction of wrong, not merely the wrong answer: the
+fabricated row said **succeeded** where the truth was **not found**, and said it
+in a shape carrying the caller's own fields back, so nothing about it looked
+wrong. Through the engine's by-id door a REST / SDK / MCP `update` against a
+deleted or mistyped id answered **200 with a record that does not exist** — on
+these two implementations only. A caller, human or agent, read that as a landed
+write and did not retry, alert or roll back.
+
+Two things downstream become correct rather than merely different:
+
+- **One `TursoDriver`, one answer.** Its remote branch passes the transport
+ result through `formatRemoteRow`, which already guards
+ `row && typeof row === 'object'`, so `null` reaches the engine untouched and
+ the two faces converge with no edit at that seam. Previously the same driver
+ answered the same missing id two ways, chosen by `isRemote`.
+- **`RemoteTransport.bulkUpdate()`'s skip stops being dead code.**
+ `if (updated) results.push(updated)` is the cross-driver convention
+ `SqlDriver.bulkUpdate` follows; on this transport `updated` could never be
+ falsy, so a batch over N missing ids answered N invented rows. It now answers
+ the rows that exist.
+
+`upsert()` is untouched on both drivers: an upsert never answers "not found".
+
+No landed test pinned the fabricating posture on either driver, so the
+regression pins added here are net-new coverage rather than a changed baseline.
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata key is removed, renamed or re-shaped: the moving surfaces are two driver methods' declared return types and the value they answer for an id that names no row, so there is nothing for `objectstack migrate meta`, `spec-changes.json` or the upgrade guide to project, and this changeset prescribes no rewrite. The consumer obligation is a TypeScript narrowing at the call site, delivered by the compiler. `type-surface-only` is NOT claimable here: its predicate 4 (narrowed-from-erased) is false — neither declared return was `any` at the merge base, they were the non-null `Promise<Record<string, unknown>>` — and, independently, runtime behaviour moves in the same diff, which is more than a type surface. Same disposition and reasoning as `.changeset/driver-memory-update-upsert-honest-types.md` (PR #14434), one day earlier in this same series. -->
diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts
@@ -155,9 +155,13 @@ describe.skipIf(!sharedMongod)('MongoDBDriver', () => {
  it('should update a record and return updated data', async () => {
  await driver.create('task', { id: 'upd-1', title: 'Original', status: 'new' });
  const result = await driver.update('task', 'upd-1', { title: 'Updated', status: 'done' });
- expect(result.title).toBe('Updated');
- expect(result.status).toBe('done');
- expect(result.id).toBe('upd-1');
+ // `update()` declares `Record<string, unknown> | null` (#14428): a miss
+ // answers `null`. This case is the FOUND arm, so pin that first and read
+ // the fields through it -- same idiom as `findOne` above.
+ expect(result).not.toBeNull();
+ expect(result!.title).toBe('Updated');
+ expect(result!.status).toBe('done');
+ expect(result!.id).toBe('upd-1');
  expect(result).not.toHaveProperty('_id');
  });
 

diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.ts
@@ -400,7 +400,34 @@ export class MongoDBDriver implements IDataDriver {
  return result;
  }
 
- async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>> {
+ /**
+ * [#14428] A miss answers `null` — the arm `IDataDriver.update()` declares
+ * (#13878) and the one `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and
+ * `TursoDriver`'s local face already return.
+ *
+ * This door used to answer a missing id with a row ASSEMBLED from the
+ * caller's own payload plus the `updated_at` it had just stamped:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne` matched nothing, `findOne` came back `null`, and the caller was
+ * handed a record for an id that names no document. The reason that was ever
+ * written — "the declaration does not permit `null`, so something has to come
+ * back" — was removed by #13878; the posture outlived it. The maintainer
+ * ruled it out on 2026-09-03 (「同意」, decision batch #15 item 1, posture A).
+ *
+ * Why the fabricated row is the expensive direction, not merely the wrong
+ * one: it says SUCCEEDED where the truth is NOT FOUND, and it says so in a
+ * shape that carries the caller's own fields back, so nothing about it looks
+ * wrong. A caller — human or agent — reads it as a landed write and does not
+ * retry, alert or roll back. Through the engine's by-id door
+ * (`engine.ts` → `driver.update`) it surfaced as a REST/SDK/MCP `200` with a
+ * record that does not exist, on this driver and Turso's remote face only.
+ *
+ * ⚠️ `upsert()` is deliberately untouched: an upsert never answers
+ * "not found" (it inserts instead), so it has no not-found arm to declare.
+ */
+ async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown> | null> {
  const collection = this.getCollection(object);
  const session = this.getSession(options);
 
@@ -419,7 +446,7 @@ export class MongoDBDriver implements IDataDriver {
  { session, projection: { _id: 0 } },
  );
 
- return (updated as Record<string, unknown>) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ return (updated as Record<string, unknown> | null) ?? null;
  }
 
  async upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>> {

diff --git a/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts b/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts
@@ -0,0 +1,202 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#14428] `MongoDBDriver.update()` answers a missing id with `null`, not with
+ * a record it made up.
+ *
+ * # What was broken
+ *
+ * The door read:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne({ id })` matching nothing and `findOne({ id })` coming back `null`
+ * still produced a row — the caller's own payload plus the `updated_at` this
+ * driver had just stamped, under an id that names no document. Since #13878
+ * (PR #14434) `IDataDriver.update()` declares `Promise[Record[string, unknown]
+ * | null]`, so "a row for an id that does not exist" is no longer a way of
+ * satisfying the declaration: it is a value the declaration distinguishes from.
+ * Four of six shipped implementations already answered `null`; this one and
+ * Turso's remote face answered "updated". Maintainer ruling 2026-09-03,
+ * posture A.
+ *
+ * # Why this file exists at all
+ *
+ * The card measured that NO landed test pinned the miss posture on this driver
+ * — `mongodb-driver.test.ts:157,175` read `update()` results over rows that
+ * EXIST. So this is net-new coverage, and the fabricating posture could have
+ * come back without reddening anything.
+ *
+ * # Why it does not live in `mongodb-driver.test.ts`
+ *
+ * That suite is `describe.skipIf(!sharedMongod)` and `createTestMongod` skips
+ * it unless `OS_TEST_MONGODB_MEMORY_SERVER_ENABLED=1` (#5517 retired the
+ * 123 MB binary download that was ejecting unrelated PRs from the merge queue).
+ * A pin added there would be GREEN-BY-SKIP on every CI run — a phantom pin,
+ * which is worse than none: it reads as coverage in the file list and can
+ * never fail. The fake `Db` below is the pattern
+ * `mongodb-findone-options.test.ts` established and
+ * `mongodb-own-key-undefined.test.ts` reuses: `getCollection` is
+ * `this.db.collection(name)`, so replacing `db` observes every call the real
+ * code path makes, with no server and no download.
+ *
+ * # The pins, and what each alone would miss
+ *
+ * - **The miss pin** is the defect: `findOne` empty ⇒ `null`.
+ * - **The positive control** is what stops the fix from being "return `null`
+ * always". A driver that had simply deleted the read-back would pass the
+ * miss pin and break every update that works.
+ * - **The no-fabrication pin** asserts the specific shape that used to come
+ * back (the caller's fields, the stamped `updated_at`). `toBeNull()` alone
+ * would also be satisfied by a driver that threw and was caught elsewhere;
+ * this states what must NOT be synthesized.
+ * - **The write-still-issued pin** holds the other half of the contract: the
+ * `updateOne` is still sent. A "fix" that short-circuited on a miss by
+ * reading FIRST would answer `null` correctly and quietly stop writing.
+ *
+ * # ⚠️ There is deliberately NO type-level pin in this file — and NOT because
+ * # nothing would read one
+ *
+ * #13878's `memory-update-declared-null.test.ts` pins the declared return type
+ * with `Equals`/`IsAny` consts. That instrument reaches this file through only
+ * ONE program, and it is not the one whose name is on the package:
+ *
+ * - **This package's own `typecheck` script cannot see it.** `tsconfig.json`
+ * here carries `"exclude": [..., "**\/*.test.ts"]` (escaped so this comment
+ * does not terminate early), and `tsc --noEmit` reads that config. Measured,
+ * not assumed: `tsc --noEmit --listFiles` in this package lists 0 files
+ * ending `.test.ts` (the sibling `driver-turso`, whose tsconfig excludes
+ * only `node_modules`/`dist`, lists 43). vitest transpiles without
+ * typechecking, and the root `tsconfig.json` excludes `packages` entirely,
+ * so neither of those picks it up either. That exclusion is itself a filed
+ * defect (#14917), not a design.
+ * - **`pnpm check:type-check-debt` DOES compile it.** The ratchet's
+ * `--re-measure` leg generates a project that drops the test exclusion and
+ * runs `tsc` over this package with its tests un-hidden, then compares the
+ * error count to the frozen `TEST_DEBT['@objectstack/driver-mongodb']` entry
+ * (10: `TS1309` x7 + `TS2550` x3). ⭐ Not theory: the first head of this
+ * branch widened `update()`'s declaration, the three found-arm reads in
+ * `mongodb-driver.test.ts` became `TS18047 'result' is possibly 'null'`, and
+ * that lane went red at 13 (+3) while `pnpm typecheck` stayed green. CI
+ * caught in this file's layer exactly what the package's own typecheck is
+ * blind to.
+ *
+ * So a type pin here would not be a phantom — it would be checked, once, in a
+ * lane that reports a break as a ledger COUNT moving rather than as a named
+ * assertion failure, and that reports it only when someone runs the whole-repo
+ * re-measure. The declaration is pinned by better instruments instead, both of
+ * which run in this package's own `typecheck`:
+ *
+ * - **narrowing the declaration back** to `Promise[Record[string, unknown]]`
+ * is a `tsc` error in `mongodb-driver.ts` itself — that file IS in the
+ * program, and the body's `?? null` then returns `Record[string, unknown] |
+ * null` from a non-null signature. `pnpm --filter @objectstack/driver-mongodb
+ * typecheck` reds.
+ * - **losing the contract linkage** (should `IDataDriver.update()` drop its
+ * `| null` arm) reds the same typecheck through `implements IDataDriver`.
+ * - **reverting the behaviour** while keeping the signature reds the runtime
+ * pins below.
+ *
+ * # Reverse verification — predicted direction, then what was OBSERVED
+ *
+ * Predicted: restoring the `|| withoutUndefinedOwnKeys({ id: String(id),
+ * ...updateData })` fallback reds the miss pin and the no-fabrication pin,
+ * while the positive control and the write-still-issued pin stay GREEN — they
+ * exercise the found arm, which the revert does not touch.
+ *
+ * Observed, with the mutation proved on disk (injected text counted, deleted
+ * text absent) and the restore proved by a `git hash-object` match against the
+ * HEAD blob: `Test Files 1 failed (1)`, `Tests 2 failed | 2 passed (4)`. The
+ * two reds are the miss pin and the no-fabrication pin, by name. ⚠️ All FOUR
+ * cases ran — there is no compile-time leg here, because there is no type pin
+ * in this file to red; a prediction that the file would fail to typecheck as a
+ * whole would have been wrong for exactly that reason.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { MongoDBDriver } from './mongodb-driver.js';
+
+/** What the fake collection recorded, so the WRITE half stays observable. */
+interface Recorded {
+ updateOne: Array<{ filter: Record<string, unknown>; update: Record<string, unknown> }>;
+ findOne: Array<Record<string, unknown>>;
+}
+
+/**
+ * A driver wired to a recording fake `Db` — no `connect()`, no server.
+ *
+ * `stored` is the document `findOne` answers with; `null` models the miss (a
+ * real `findOne` resolves `null` when nothing matches), and an object models
+ * the row that exists.
+ */
+function makeDriver(stored: Record<string, unknown> | null) {
+ const recorded: Recorded = { updateOne: [], findOne: [] };
+ const collection = {
+ async updateOne(filter: Record<string, unknown>, update: Record<string, unknown>) {
+ recorded.updateOne.push({ filter, update });
+ return { matchedCount: stored ? 1 : 0, modifiedCount: stored ? 1 : 0 };
+ },
+ async findOne(filter: Record<string, unknown>) {
+ recorded.findOne.push(filter);
+ return stored;
+ },
+ };
+ const driver = new MongoDBDriver({ url: 'mongodb://127.0.0.1:1/probe' });
+ (driver as any).db = { collection: () => collection };
+ return { driver, recorded };
+}
+
+describe('[#14428] MongoDBDriver.update() on a missing id', () => {
+ it('resolves null when no document carries that id', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(result).toBeNull();
+ // The narrowing the declared type demands of every caller.
+ const title = result === null ? 'absent' : result.title;
+ expect(title).toBe('absent');
+ });
+
+ it('fabricates nothing — no id, no payload echo, no stamped updated_at', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited', owner: 'u1' });
+
+ // The exact shape the old fallback produced: `{ id, ...updateData }` with
+ // `updated_at` stamped a moment earlier. Asserted as a NON-match against a
+ // reconstruction of it, so the pin names the thing it forbids rather than
+ // only the thing it wants — `toBeNull()` alone would also be satisfied by a
+ // driver that threw and was caught somewhere up the stack.
+ //
+ // ⚠️ NOT written as `expect(result).not.toBeTypeOf('object')`: `typeof
+ // null` IS `'object'` in JS, so that assertion fails on the correct value.
+ expect(result).toBeNull();
+ expect(result).not.toMatchObject({ id: 'no-such-id' });
+ expect(Object.keys((result as Record<string, unknown> | null) ?? {})).toEqual([]);
+ });
+
+ it('still ISSUES the write — the miss is discovered by reading back, not by refusing', async () => {
+ const { driver, recorded } = makeDriver(null);
+
+ await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(recorded.updateOne).toHaveLength(1);
+ expect(recorded.updateOne[0].filter).toEqual({ id: 'no-such-id' });
+ expect((recorded.updateOne[0].update as any).$set.title).toBe('edited');
+ expect(recorded.findOne).toHaveLength(1);
+ expect(recorded.findOne[0]).toEqual({ id: 'no-such-id' });
+ });
+
+ it('POSITIVE CONTROL — an id that DOES exist still returns the stored row', async () => {
+ const stored = { id: 'task-1', title: 'edited', owner: 'u1', updated_at: new Date('2026-01-01T00:00:00Z') };
+ const { driver } = makeDriver(stored);
+
+ const result = await driver.update('task', 'task-1', { title: 'edited' });
+
+ expect(result).not.toBeNull();
+ expect(result!.id).toBe('task-1');
+ expect(result!.title).toBe('edited');
+ });
+});
diff --git a/.changeset/driver-update-missing-id-null.md b/.changeset/driver-update-missing-id-null.md
@@ -0,0 +1,64 @@
+---
+"@objectstack/driver-mongodb": minor
+"@objectstack/driver-turso": minor
+---
+
+fix(drivers): `update()` on a missing id answers `null` on MongoDB and on Turso's remote face
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing alongside a
+runtime behaviour change, shipped as `minor` under the launch-window convention. Two
+published declared returns move: `MongoDBDriver.update()` and `RemoteTransport.update()`
+(both exported from their package index) now declare
+`Promise<Record<string, unknown> | null>` where they declared
+`Promise<Record<string, unknown>>`. A caller that reads fields off either result —
+`result.id`, `result.title` — no longer compiles until it narrows the `null` arm first.
+The narrowing is delivered by the compiler at every call site, and it is the honest
+declaration: the value that arm carries has always been reachable, it was simply being
+answered with a fabricated record instead.
+
+`IDataDriver.update()` declares `Promise<Record<string, unknown> | null>` — the
+not-found arm landed with the ruling on the contract (`packages/spec` is untouched here),
+and it is the answer `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and `TursoDriver`'s
+local face have always given. Two implementations did not honour it. They **invented a
+record** instead:
+
+- `MongoDBDriver.update()` ran `updateOne({ id })`, then `findOne({ id })`, and
+ when nothing came back returned
+ `withoutUndefinedOwnKeys({ id: String(id), ...updateData })` — a row assembled
+ from the caller's own payload plus the `updated_at` it had just stamped, under
+ an id that names no document.
+- `RemoteTransport.update()` ran `UPDATE … WHERE "id" = ?`, then
+ `SELECT * … WHERE "id" = ?`, and when no row came back returned
+ `{ id, ...data }` — the caller's payload with the id stapled on.
+
+Both now return `null`. That is the runtime half of this change, and it is why this
+release is not a pure type-surface move: the value a caller receives for a missing id is
+different at run time, not only in the `.d.ts`.
+
+This is the expensive direction of wrong, not merely the wrong answer: the
+fabricated row said **succeeded** where the truth was **not found**, and said it
+in a shape carrying the caller's own fields back, so nothing about it looked
+wrong. Through the engine's by-id door a REST / SDK / MCP `update` against a
+deleted or mistyped id answered **200 with a record that does not exist** — on
+these two implementations only. A caller, human or agent, read that as a landed
+write and did not retry, alert or roll back.
+
+Two things downstream become correct rather than merely different:
+
+- **One `TursoDriver`, one answer.** Its remote branch passes the transport
+ result through `formatRemoteRow`, which already guards
+ `row && typeof row === 'object'`, so `null` reaches the engine untouched and
+ the two faces converge with no edit at that seam. Previously the same driver
+ answered the same missing id two ways, chosen by `isRemote`.
+- **`RemoteTransport.bulkUpdate()`'s skip stops being dead code.**
+ `if (updated) results.push(updated)` is the cross-driver convention
+ `SqlDriver.bulkUpdate` follows; on this transport `updated` could never be
+ falsy, so a batch over N missing ids answered N invented rows. It now answers
+ the rows that exist.
+
+`upsert()` is untouched on both drivers: an upsert never answers "not found".
+
+No landed test pinned the fabricating posture on either driver, so the
+regression pins added here are net-new coverage rather than a changed baseline.
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata key is removed, renamed or re-shaped: the moving surfaces are two driver methods' declared return types and the value they answer for an id that names no row, so there is nothing for `objectstack migrate meta`, `spec-changes.json` or the upgrade guide to project, and this changeset prescribes no rewrite. The consumer obligation is a TypeScript narrowing at the call site, delivered by the compiler. `type-surface-only` is NOT claimable here: its predicate 4 (narrowed-from-erased) is false — neither declared return was `any` at the merge base, they were the non-null `Promise<Record<string, unknown>>` — and, independently, runtime behaviour moves in the same diff, which is more than a type surface. Same disposition and reasoning as `.changeset/driver-memory-update-upsert-honest-types.md` (PR #14434), one day earlier in this same series. -->
diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts
@@ -155,9 +155,13 @@ describe.skipIf(!sharedMongod)('MongoDBDriver', () => {
  it('should update a record and return updated data', async () => {
  await driver.create('task', { id: 'upd-1', title: 'Original', status: 'new' });
  const result = await driver.update('task', 'upd-1', { title: 'Updated', status: 'done' });
- expect(result.title).toBe('Updated');
- expect(result.status).toBe('done');
- expect(result.id).toBe('upd-1');
+ // `update()` declares `Record<string, unknown> | null` (#14428): a miss
+ // answers `null`. This case is the FOUND arm, so pin that first and read
+ // the fields through it -- same idiom as `findOne` above.
+ expect(result).not.toBeNull();
+ expect(result!.title).toBe('Updated');
+ expect(result!.status).toBe('done');
+ expect(result!.id).toBe('upd-1');
  expect(result).not.toHaveProperty('_id');
  });
 

diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.ts
@@ -400,7 +400,34 @@ export class MongoDBDriver implements IDataDriver {
  return result;
  }
 
- async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>> {
+ /**
+ * [#14428] A miss answers `null` — the arm `IDataDriver.update()` declares
+ * (#13878) and the one `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and
+ * `TursoDriver`'s local face already return.
+ *
+ * This door used to answer a missing id with a row ASSEMBLED from the
+ * caller's own payload plus the `updated_at` it had just stamped:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne` matched nothing, `findOne` came back `null`, and the caller was
+ * handed a record for an id that names no document. The reason that was ever
+ * written — "the declaration does not permit `null`, so something has to come
+ * back" — was removed by #13878; the posture outlived it. The maintainer
+ * ruled it out on 2026-09-03 (「同意」, decision batch #15 item 1, posture A).
+ *
+ * Why the fabricated row is the expensive direction, not merely the wrong
+ * one: it says SUCCEEDED where the truth is NOT FOUND, and it says so in a
+ * shape that carries the caller's own fields back, so nothing about it looks
+ * wrong. A caller — human or agent — reads it as a landed write and does not
+ * retry, alert or roll back. Through the engine's by-id door
+ * (`engine.ts` → `driver.update`) it surfaced as a REST/SDK/MCP `200` with a
+ * record that does not exist, on this driver and Turso's remote face only.
+ *
+ * ⚠️ `upsert()` is deliberately untouched: an upsert never answers
+ * "not found" (it inserts instead), so it has no not-found arm to declare.
+ */
+ async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown> | null> {
  const collection = this.getCollection(object);
  const session = this.getSession(options);
 
@@ -419,7 +446,7 @@ export class MongoDBDriver implements IDataDriver {
  { session, projection: { _id: 0 } },
  );
 
- return (updated as Record<string, unknown>) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ return (updated as Record<string, unknown> | null) ?? null;
  }
 
  async upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>> {

diff --git a/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts b/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts
@@ -0,0 +1,202 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#14428] `MongoDBDriver.update()` answers a missing id with `null`, not with
+ * a record it made up.
+ *
+ * # What was broken
+ *
+ * The door read:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne({ id })` matching nothing and `findOne({ id })` coming back `null`
+ * still produced a row — the caller's own payload plus the `updated_at` this
+ * driver had just stamped, under an id that names no document. Since #13878
+ * (PR #14434) `IDataDriver.update()` declares `Promise[Record[string, unknown]
+ * | null]`, so "a row for an id that does not exist" is no longer a way of
+ * satisfying the declaration: it is a value the declaration distinguishes from.
+ * Four of six shipped implementations already answered `null`; this one and
+ * Turso's remote face answered "updated". Maintainer ruling 2026-09-03,
+ * posture A.
+ *
+ * # Why this file exists at all
+ *
+ * The card measured that NO landed test pinned the miss posture on this driver
+ * — `mongodb-driver.test.ts:157,175` read `update()` results over rows that
+ * EXIST. So this is net-new coverage, and the fabricating posture could have
+ * come back without reddening anything.
+ *
+ * # Why it does not live in `mongodb-driver.test.ts`
+ *
+ * That suite is `describe.skipIf(!sharedMongod)` and `createTestMongod` skips
+ * it unless `OS_TEST_MONGODB_MEMORY_SERVER_ENABLED=1` (#5517 retired the
+ * 123 MB binary download that was ejecting unrelated PRs from the merge queue).
+ * A pin added there would be GREEN-BY-SKIP on every CI run — a phantom pin,
+ * which is worse than none: it reads as coverage in the file list and can
+ * never fail. The fake `Db` below is the pattern
+ * `mongodb-findone-options.test.ts` established and
+ * `mongodb-own-key-undefined.test.ts` reuses: `getCollection` is
+ * `this.db.collection(name)`, so replacing `db` observes every call the real
+ * code path makes, with no server and no download.
+ *
+ * # The pins, and what each alone would miss
+ *
+ * - **The miss pin** is the defect: `findOne` empty ⇒ `null`.
+ * - **The positive control** is what stops the fix from being "return `null`
+ * always". A driver that had simply deleted the read-back would pass the
+ * miss pin and break every update that works.
+ * - **The no-fabrication pin** asserts the specific shape that used to come
+ * back (the caller's fields, the stamped `updated_at`). `toBeNull()` alone
+ * would also be satisfied by a driver that threw and was caught elsewhere;
+ * this states what must NOT be synthesized.
+ * - **The write-still-issued pin** holds the other half of the contract: the
+ * `updateOne` is still sent. A "fix" that short-circuited on a miss by
+ * reading FIRST would answer `null` correctly and quietly stop writing.
+ *
+ * # ⚠️ There is deliberately NO type-level pin in this file — and NOT because
+ * # nothing would read one
+ *
+ * #13878's `memory-update-declared-null.test.ts` pins the declared return type
+ * with `Equals`/`IsAny` consts. That instrument reaches this file through only
+ * ONE program, and it is not the one whose name is on the package:
+ *
+ * - **This package's own `typecheck` script cannot see it.** `tsconfig.json`
+ * here carries `"exclude": [..., "**\/*.test.ts"]` (escaped so this comment
+ * does not terminate early), and `tsc --noEmit` reads that config. Measured,
+ * not assumed: `tsc --noEmit --listFiles` in this package lists 0 files
+ * ending `.test.ts` (the sibling `driver-turso`, whose tsconfig excludes
+ * only `node_modules`/`dist`, lists 43). vitest transpiles without
+ * typechecking, and the root `tsconfig.json` excludes `packages` entirely,
+ * so neither of those picks it up either. That exclusion is itself a filed
+ * defect (#14917), not a design.
+ * - **`pnpm check:type-check-debt` DOES compile it.** The ratchet's
+ * `--re-measure` leg generates a project that drops the test exclusion and
+ * runs `tsc` over this package with its tests un-hidden, then compares the
+ * error count to the frozen `TEST_DEBT['@objectstack/driver-mongodb']` entry
+ * (10: `TS1309` x7 + `TS2550` x3). ⭐ Not theory: the first head of this
+ * branch widened `update()`'s declaration, the three found-arm reads in
+ * `mongodb-driver.test.ts` became `TS18047 'result' is possibly 'null'`, and
+ * that lane went red at 13 (+3) while `pnpm typecheck` stayed green. CI
+ * caught in this file's layer exactly what the package's own typecheck is
+ * blind to.
+ *
+ * So a type pin here would not be a phantom — it would be checked, once, in a
+ * lane that reports a break as a ledger COUNT moving rather than as a named
+ * assertion failure, and that reports it only when someone runs the whole-repo
+ * re-measure. The declaration is pinned by better instruments instead, both of
+ * which run in this package's own `typecheck`:
+ *
+ * - **narrowing the declaration back** to `Promise[Record[string, unknown]]`
+ * is a `tsc` error in `mongodb-driver.ts` itself — that file IS in the
+ * program, and the body's `?? null` then returns `Record[string, unknown] |
+ * null` from a non-null signature. `pnpm --filter @objectstack/driver-mongodb
+ * typecheck` reds.
+ * - **losing the contract linkage** (should `IDataDriver.update()` drop its
+ * `| null` arm) reds the same typecheck through `implements IDataDriver`.
+ * - **reverting the behaviour** while keeping the signature reds the runtime
+ * pins below.
+ *
+ * # Reverse verification — predicted direction, then what was OBSERVED
+ *
+ * Predicted: restoring the `|| withoutUndefinedOwnKeys({ id: String(id),
+ * ...updateData })` fallback reds the miss pin and the no-fabrication pin,
+ * while the positive control and the write-still-issued pin stay GREEN — they
+ * exercise the found arm, which the revert does not touch.
+ *
+ * Observed, with the mutation proved on disk (injected text counted, deleted
+ * text absent) and the restore proved by a `git hash-object` match against the
+ * HEAD blob: `Test Files 1 failed (1)`, `Tests 2 failed | 2 passed (4)`. The
+ * two reds are the miss pin and the no-fabrication pin, by name. ⚠️ All FOUR
+ * cases ran — there is no compile-time leg here, because there is no type pin
+ * in this file to red; a prediction that the file would fail to typecheck as a
+ * whole would have been wrong for exactly that reason.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { MongoDBDriver } from './mongodb-driver.js';
+
+/** What the fake collection recorded, so the WRITE half stays observable. */
+interface Recorded {
+ updateOne: Array<{ filter: Record<string, unknown>; update: Record<string, unknown> }>;
+ findOne: Array<Record<string, unknown>>;
+}
+
+/**
+ * A driver wired to a recording fake `Db` — no `connect()`, no server.
+ *
+ * `stored` is the document `findOne` answers with; `null` models the miss (a
+ * real `findOne` resolves `null` when nothing matches), and an object models
+ * the row that exists.
+ */
+function makeDriver(stored: Record<string, unknown> | null) {
+ const recorded: Recorded = { updateOne: [], findOne: [] };
+ const collection = {
+ async updateOne(filter: Record<string, unknown>, update: Record<string, unknown>) {
+ recorded.updateOne.push({ filter, update });
+ return { matchedCount: stored ? 1 : 0, modifiedCount: stored ? 1 : 0 };
+ },
+ async findOne(filter: Record<string, unknown>) {
+ recorded.findOne.push(filter);
+ return stored;
+ },
+ };
+ const driver = new MongoDBDriver({ url: 'mongodb://127.0.0.1:1/probe' });
+ (driver as any).db = { collection: () => collection };
+ return { driver, recorded };
+}
+
+describe('[#14428] MongoDBDriver.update() on a missing id', () => {
+ it('resolves null when no document carries that id', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(result).toBeNull();
+ // The narrowing the declared type demands of every caller.
+ const title = result === null ? 'absent' : result.title;
+ expect(title).toBe('absent');
+ });
+
+ it('fabricates nothing — no id, no payload echo, no stamped updated_at', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited', owner: 'u1' });
+
+ // The exact shape the old fallback produced: `{ id, ...updateData }` with
+ // `updated_at` stamped a moment earlier. Asserted as a NON-match against a
+ // reconstruction of it, so the pin names the thing it forbids rather than
+ // only the thing it wants — `toBeNull()` alone would also be satisfied by a
+ // driver that threw and was caught somewhere up the stack.
+ //
+ // ⚠️ NOT written as `expect(result).not.toBeTypeOf('object')`: `typeof
+ // null` IS `'object'` in JS, so that assertion fails on the correct value.
+ expect(result).toBeNull();
+ expect(result).not.toMatchObject({ id: 'no-such-id' });
+ expect(Object.keys((result as Record<string, unknown> | null) ?? {})).toEqual([]);
+ });
+
+ it('still ISSUES the write — the miss is discovered by reading back, not by refusing', async () => {
+ const { driver, recorded } = makeDriver(null);
+
+ await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(recorded.updateOne).toHaveLength(1);
+ expect(recorded.updateOne[0].filter).toEqual({ id: 'no-such-id' });
+ expect((recorded.updateOne[0].update as any).$set.title).toBe('edited');
+ expect(recorded.findOne).toHaveLength(1);
+ expect(recorded.findOne[0]).toEqual({ id: 'no-such-id' });
+ });
+
+ it('POSITIVE CONTROL — an id that DOES exist still returns the stored row', async () => {
+ const stored = { id: 'task-1', title: 'edited', owner: 'u1', updated_at: new Date('2026-01-01T00:00:00Z') };
+ const { driver } = makeDriver(stored);
+
+ const result = await driver.update('task', 'task-1', { title: 'edited' });
+
+ expect(result).not.toBeNull();
+ expect(result!.id).toBe('task-1');
+ expect(result!.title).toBe('edited');
+ });
+});
diff --git a/.changeset/driver-update-missing-id-null.md b/.changeset/driver-update-missing-id-null.md
@@ -0,0 +1,64 @@
+---
+"@objectstack/driver-mongodb": minor
+"@objectstack/driver-turso": minor
+---
+
+fix(drivers): `update()` on a missing id answers `null` on MongoDB and on Turso's remote face
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing alongside a
+runtime behaviour change, shipped as `minor` under the launch-window convention. Two
+published declared returns move: `MongoDBDriver.update()` and `RemoteTransport.update()`
+(both exported from their package index) now declare
+`Promise<Record<string, unknown> | null>` where they declared
+`Promise<Record<string, unknown>>`. A caller that reads fields off either result —
+`result.id`, `result.title` — no longer compiles until it narrows the `null` arm first.
+The narrowing is delivered by the compiler at every call site, and it is the honest
+declaration: the value that arm carries has always been reachable, it was simply being
+answered with a fabricated record instead.
+
+`IDataDriver.update()` declares `Promise<Record<string, unknown> | null>` — the
+not-found arm landed with the ruling on the contract (`packages/spec` is untouched here),
+and it is the answer `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and `TursoDriver`'s
+local face have always given. Two implementations did not honour it. They **invented a
+record** instead:
+
+- `MongoDBDriver.update()` ran `updateOne({ id })`, then `findOne({ id })`, and
+ when nothing came back returned
+ `withoutUndefinedOwnKeys({ id: String(id), ...updateData })` — a row assembled
+ from the caller's own payload plus the `updated_at` it had just stamped, under
+ an id that names no document.
+- `RemoteTransport.update()` ran `UPDATE … WHERE "id" = ?`, then
+ `SELECT * … WHERE "id" = ?`, and when no row came back returned
+ `{ id, ...data }` — the caller's payload with the id stapled on.
+
+Both now return `null`. That is the runtime half of this change, and it is why this
+release is not a pure type-surface move: the value a caller receives for a missing id is
+different at run time, not only in the `.d.ts`.
+
+This is the expensive direction of wrong, not merely the wrong answer: the
+fabricated row said **succeeded** where the truth was **not found**, and said it
+in a shape carrying the caller's own fields back, so nothing about it looked
+wrong. Through the engine's by-id door a REST / SDK / MCP `update` against a
+deleted or mistyped id answered **200 with a record that does not exist** — on
+these two implementations only. A caller, human or agent, read that as a landed
+write and did not retry, alert or roll back.
+
+Two things downstream become correct rather than merely different:
+
+- **One `TursoDriver`, one answer.** Its remote branch passes the transport
+ result through `formatRemoteRow`, which already guards
+ `row && typeof row === 'object'`, so `null` reaches the engine untouched and
+ the two faces converge with no edit at that seam. Previously the same driver
+ answered the same missing id two ways, chosen by `isRemote`.
+- **`RemoteTransport.bulkUpdate()`'s skip stops being dead code.**
+ `if (updated) results.push(updated)` is the cross-driver convention
+ `SqlDriver.bulkUpdate` follows; on this transport `updated` could never be
+ falsy, so a batch over N missing ids answered N invented rows. It now answers
+ the rows that exist.
+
+`upsert()` is untouched on both drivers: an upsert never answers "not found".
+
+No landed test pinned the fabricating posture on either driver, so the
+regression pins added here are net-new coverage rather than a changed baseline.
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata key is removed, renamed or re-shaped: the moving surfaces are two driver methods' declared return types and the value they answer for an id that names no row, so there is nothing for `objectstack migrate meta`, `spec-changes.json` or the upgrade guide to project, and this changeset prescribes no rewrite. The consumer obligation is a TypeScript narrowing at the call site, delivered by the compiler. `type-surface-only` is NOT claimable here: its predicate 4 (narrowed-from-erased) is false — neither declared return was `any` at the merge base, they were the non-null `Promise<Record<string, unknown>>` — and, independently, runtime behaviour moves in the same diff, which is more than a type surface. Same disposition and reasoning as `.changeset/driver-memory-update-upsert-honest-types.md` (PR #14434), one day earlier in this same series. -->
diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts
@@ -155,9 +155,13 @@ describe.skipIf(!sharedMongod)('MongoDBDriver', () => {
  it('should update a record and return updated data', async () => {
  await driver.create('task', { id: 'upd-1', title: 'Original', status: 'new' });
  const result = await driver.update('task', 'upd-1', { title: 'Updated', status: 'done' });
- expect(result.title).toBe('Updated');
- expect(result.status).toBe('done');
- expect(result.id).toBe('upd-1');
+ // `update()` declares `Record<string, unknown> | null` (#14428): a miss
+ // answers `null`. This case is the FOUND arm, so pin that first and read
+ // the fields through it -- same idiom as `findOne` above.
+ expect(result).not.toBeNull();
+ expect(result!.title).toBe('Updated');
+ expect(result!.status).toBe('done');
+ expect(result!.id).toBe('upd-1');
  expect(result).not.toHaveProperty('_id');
  });
 

diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.ts
@@ -400,7 +400,34 @@ export class MongoDBDriver implements IDataDriver {
  return result;
  }
 
- async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>> {
+ /**
+ * [#14428] A miss answers `null` — the arm `IDataDriver.update()` declares
+ * (#13878) and the one `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and
+ * `TursoDriver`'s local face already return.
+ *
+ * This door used to answer a missing id with a row ASSEMBLED from the
+ * caller's own payload plus the `updated_at` it had just stamped:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne` matched nothing, `findOne` came back `null`, and the caller was
+ * handed a record for an id that names no document. The reason that was ever
+ * written — "the declaration does not permit `null`, so something has to come
+ * back" — was removed by #13878; the posture outlived it. The maintainer
+ * ruled it out on 2026-09-03 (「同意」, decision batch #15 item 1, posture A).
+ *
+ * Why the fabricated row is the expensive direction, not merely the wrong
+ * one: it says SUCCEEDED where the truth is NOT FOUND, and it says so in a
+ * shape that carries the caller's own fields back, so nothing about it looks
+ * wrong. A caller — human or agent — reads it as a landed write and does not
+ * retry, alert or roll back. Through the engine's by-id door
+ * (`engine.ts` → `driver.update`) it surfaced as a REST/SDK/MCP `200` with a
+ * record that does not exist, on this driver and Turso's remote face only.
+ *
+ * ⚠️ `upsert()` is deliberately untouched: an upsert never answers
+ * "not found" (it inserts instead), so it has no not-found arm to declare.
+ */
+ async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown> | null> {
  const collection = this.getCollection(object);
  const session = this.getSession(options);
 
@@ -419,7 +446,7 @@ export class MongoDBDriver implements IDataDriver {
  { session, projection: { _id: 0 } },
  );
 
- return (updated as Record<string, unknown>) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ return (updated as Record<string, unknown> | null) ?? null;
  }
 
  async upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>> {

diff --git a/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts b/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts
@@ -0,0 +1,202 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#14428] `MongoDBDriver.update()` answers a missing id with `null`, not with
+ * a record it made up.
+ *
+ * # What was broken
+ *
+ * The door read:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne({ id })` matching nothing and `findOne({ id })` coming back `null`
+ * still produced a row — the caller's own payload plus the `updated_at` this
+ * driver had just stamped, under an id that names no document. Since #13878
+ * (PR #14434) `IDataDriver.update()` declares `Promise[Record[string, unknown]
+ * | null]`, so "a row for an id that does not exist" is no longer a way of
+ * satisfying the declaration: it is a value the declaration distinguishes from.
+ * Four of six shipped implementations already answered `null`; this one and
+ * Turso's remote face answered "updated". Maintainer ruling 2026-09-03,
+ * posture A.
+ *
+ * # Why this file exists at all
+ *
+ * The card measured that NO landed test pinned the miss posture on this driver
+ * — `mongodb-driver.test.ts:157,175` read `update()` results over rows that
+ * EXIST. So this is net-new coverage, and the fabricating posture could have
+ * come back without reddening anything.
+ *
+ * # Why it does not live in `mongodb-driver.test.ts`
+ *
+ * That suite is `describe.skipIf(!sharedMongod)` and `createTestMongod` skips
+ * it unless `OS_TEST_MONGODB_MEMORY_SERVER_ENABLED=1` (#5517 retired the
+ * 123 MB binary download that was ejecting unrelated PRs from the merge queue).
+ * A pin added there would be GREEN-BY-SKIP on every CI run — a phantom pin,
+ * which is worse than none: it reads as coverage in the file list and can
+ * never fail. The fake `Db` below is the pattern
+ * `mongodb-findone-options.test.ts` established and
+ * `mongodb-own-key-undefined.test.ts` reuses: `getCollection` is
+ * `this.db.collection(name)`, so replacing `db` observes every call the real
+ * code path makes, with no server and no download.
+ *
+ * # The pins, and what each alone would miss
+ *
+ * - **The miss pin** is the defect: `findOne` empty ⇒ `null`.
+ * - **The positive control** is what stops the fix from being "return `null`
+ * always". A driver that had simply deleted the read-back would pass the
+ * miss pin and break every update that works.
+ * - **The no-fabrication pin** asserts the specific shape that used to come
+ * back (the caller's fields, the stamped `updated_at`). `toBeNull()` alone
+ * would also be satisfied by a driver that threw and was caught elsewhere;
+ * this states what must NOT be synthesized.
+ * - **The write-still-issued pin** holds the other half of the contract: the
+ * `updateOne` is still sent. A "fix" that short-circuited on a miss by
+ * reading FIRST would answer `null` correctly and quietly stop writing.
+ *
+ * # ⚠️ There is deliberately NO type-level pin in this file — and NOT because
+ * # nothing would read one
+ *
+ * #13878's `memory-update-declared-null.test.ts` pins the declared return type
+ * with `Equals`/`IsAny` consts. That instrument reaches this file through only
+ * ONE program, and it is not the one whose name is on the package:
+ *
+ * - **This package's own `typecheck` script cannot see it.** `tsconfig.json`
+ * here carries `"exclude": [..., "**\/*.test.ts"]` (escaped so this comment
+ * does not terminate early), and `tsc --noEmit` reads that config. Measured,
+ * not assumed: `tsc --noEmit --listFiles` in this package lists 0 files
+ * ending `.test.ts` (the sibling `driver-turso`, whose tsconfig excludes
+ * only `node_modules`/`dist`, lists 43). vitest transpiles without
+ * typechecking, and the root `tsconfig.json` excludes `packages` entirely,
+ * so neither of those picks it up either. That exclusion is itself a filed
+ * defect (#14917), not a design.
+ * - **`pnpm check:type-check-debt` DOES compile it.** The ratchet's
+ * `--re-measure` leg generates a project that drops the test exclusion and
+ * runs `tsc` over this package with its tests un-hidden, then compares the
+ * error count to the frozen `TEST_DEBT['@objectstack/driver-mongodb']` entry
+ * (10: `TS1309` x7 + `TS2550` x3). ⭐ Not theory: the first head of this
+ * branch widened `update()`'s declaration, the three found-arm reads in
+ * `mongodb-driver.test.ts` became `TS18047 'result' is possibly 'null'`, and
+ * that lane went red at 13 (+3) while `pnpm typecheck` stayed green. CI
+ * caught in this file's layer exactly what the package's own typecheck is
+ * blind to.
+ *
+ * So a type pin here would not be a phantom — it would be checked, once, in a
+ * lane that reports a break as a ledger COUNT moving rather than as a named
+ * assertion failure, and that reports it only when someone runs the whole-repo
+ * re-measure. The declaration is pinned by better instruments instead, both of
+ * which run in this package's own `typecheck`:
+ *
+ * - **narrowing the declaration back** to `Promise[Record[string, unknown]]`
+ * is a `tsc` error in `mongodb-driver.ts` itself — that file IS in the
+ * program, and the body's `?? null` then returns `Record[string, unknown] |
+ * null` from a non-null signature. `pnpm --filter @objectstack/driver-mongodb
+ * typecheck` reds.
+ * - **losing the contract linkage** (should `IDataDriver.update()` drop its
+ * `| null` arm) reds the same typecheck through `implements IDataDriver`.
+ * - **reverting the behaviour** while keeping the signature reds the runtime
+ * pins below.
+ *
+ * # Reverse verification — predicted direction, then what was OBSERVED
+ *
+ * Predicted: restoring the `|| withoutUndefinedOwnKeys({ id: String(id),
+ * ...updateData })` fallback reds the miss pin and the no-fabrication pin,
+ * while the positive control and the write-still-issued pin stay GREEN — they
+ * exercise the found arm, which the revert does not touch.
+ *
+ * Observed, with the mutation proved on disk (injected text counted, deleted
+ * text absent) and the restore proved by a `git hash-object` match against the
+ * HEAD blob: `Test Files 1 failed (1)`, `Tests 2 failed | 2 passed (4)`. The
+ * two reds are the miss pin and the no-fabrication pin, by name. ⚠️ All FOUR
+ * cases ran — there is no compile-time leg here, because there is no type pin
+ * in this file to red; a prediction that the file would fail to typecheck as a
+ * whole would have been wrong for exactly that reason.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { MongoDBDriver } from './mongodb-driver.js';
+
+/** What the fake collection recorded, so the WRITE half stays observable. */
+interface Recorded {
+ updateOne: Array<{ filter: Record<string, unknown>; update: Record<string, unknown> }>;
+ findOne: Array<Record<string, unknown>>;
+}
+
+/**
+ * A driver wired to a recording fake `Db` — no `connect()`, no server.
+ *
+ * `stored` is the document `findOne` answers with; `null` models the miss (a
+ * real `findOne` resolves `null` when nothing matches), and an object models
+ * the row that exists.
+ */
+function makeDriver(stored: Record<string, unknown> | null) {
+ const recorded: Recorded = { updateOne: [], findOne: [] };
+ const collection = {
+ async updateOne(filter: Record<string, unknown>, update: Record<string, unknown>) {
+ recorded.updateOne.push({ filter, update });
+ return { matchedCount: stored ? 1 : 0, modifiedCount: stored ? 1 : 0 };
+ },
+ async findOne(filter: Record<string, unknown>) {
+ recorded.findOne.push(filter);
+ return stored;
+ },
+ };
+ const driver = new MongoDBDriver({ url: 'mongodb://127.0.0.1:1/probe' });
+ (driver as any).db = { collection: () => collection };
+ return { driver, recorded };
+}
+
+describe('[#14428] MongoDBDriver.update() on a missing id', () => {
+ it('resolves null when no document carries that id', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(result).toBeNull();
+ // The narrowing the declared type demands of every caller.
+ const title = result === null ? 'absent' : result.title;
+ expect(title).toBe('absent');
+ });
+
+ it('fabricates nothing — no id, no payload echo, no stamped updated_at', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited', owner: 'u1' });
+
+ // The exact shape the old fallback produced: `{ id, ...updateData }` with
+ // `updated_at` stamped a moment earlier. Asserted as a NON-match against a
+ // reconstruction of it, so the pin names the thing it forbids rather than
+ // only the thing it wants — `toBeNull()` alone would also be satisfied by a
+ // driver that threw and was caught somewhere up the stack.
+ //
+ // ⚠️ NOT written as `expect(result).not.toBeTypeOf('object')`: `typeof
+ // null` IS `'object'` in JS, so that assertion fails on the correct value.
+ expect(result).toBeNull();
+ expect(result).not.toMatchObject({ id: 'no-such-id' });
+ expect(Object.keys((result as Record<string, unknown> | null) ?? {})).toEqual([]);
+ });
+
+ it('still ISSUES the write — the miss is discovered by reading back, not by refusing', async () => {
+ const { driver, recorded } = makeDriver(null);
+
+ await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(recorded.updateOne).toHaveLength(1);
+ expect(recorded.updateOne[0].filter).toEqual({ id: 'no-such-id' });
+ expect((recorded.updateOne[0].update as any).$set.title).toBe('edited');
+ expect(recorded.findOne).toHaveLength(1);
+ expect(recorded.findOne[0]).toEqual({ id: 'no-such-id' });
+ });
+
+ it('POSITIVE CONTROL — an id that DOES exist still returns the stored row', async () => {
+ const stored = { id: 'task-1', title: 'edited', owner: 'u1', updated_at: new Date('2026-01-01T00:00:00Z') };
+ const { driver } = makeDriver(stored);
+
+ const result = await driver.update('task', 'task-1', { title: 'edited' });
+
+ expect(result).not.toBeNull();
+ expect(result!.id).toBe('task-1');
+ expect(result!.title).toBe('edited');
+ });
+});
diff --git a/.changeset/driver-update-missing-id-null.md b/.changeset/driver-update-missing-id-null.md
@@ -0,0 +1,64 @@
+---
+"@objectstack/driver-mongodb": minor
+"@objectstack/driver-turso": minor
+---
+
+fix(drivers): `update()` on a missing id answers `null` on MongoDB and on Turso's remote face
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing alongside a
+runtime behaviour change, shipped as `minor` under the launch-window convention. Two
+published declared returns move: `MongoDBDriver.update()` and `RemoteTransport.update()`
+(both exported from their package index) now declare
+`Promise<Record<string, unknown> | null>` where they declared
+`Promise<Record<string, unknown>>`. A caller that reads fields off either result —
+`result.id`, `result.title` — no longer compiles until it narrows the `null` arm first.
+The narrowing is delivered by the compiler at every call site, and it is the honest
+declaration: the value that arm carries has always been reachable, it was simply being
+answered with a fabricated record instead.
+
+`IDataDriver.update()` declares `Promise<Record<string, unknown> | null>` — the
+not-found arm landed with the ruling on the contract (`packages/spec` is untouched here),
+and it is the answer `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and `TursoDriver`'s
+local face have always given. Two implementations did not honour it. They **invented a
+record** instead:
+
+- `MongoDBDriver.update()` ran `updateOne({ id })`, then `findOne({ id })`, and
+ when nothing came back returned
+ `withoutUndefinedOwnKeys({ id: String(id), ...updateData })` — a row assembled
+ from the caller's own payload plus the `updated_at` it had just stamped, under
+ an id that names no document.
+- `RemoteTransport.update()` ran `UPDATE … WHERE "id" = ?`, then
+ `SELECT * … WHERE "id" = ?`, and when no row came back returned
+ `{ id, ...data }` — the caller's payload with the id stapled on.
+
+Both now return `null`. That is the runtime half of this change, and it is why this
+release is not a pure type-surface move: the value a caller receives for a missing id is
+different at run time, not only in the `.d.ts`.
+
+This is the expensive direction of wrong, not merely the wrong answer: the
+fabricated row said **succeeded** where the truth was **not found**, and said it
+in a shape carrying the caller's own fields back, so nothing about it looked
+wrong. Through the engine's by-id door a REST / SDK / MCP `update` against a
+deleted or mistyped id answered **200 with a record that does not exist** — on
+these two implementations only. A caller, human or agent, read that as a landed
+write and did not retry, alert or roll back.
+
+Two things downstream become correct rather than merely different:
+
+- **One `TursoDriver`, one answer.** Its remote branch passes the transport
+ result through `formatRemoteRow`, which already guards
+ `row && typeof row === 'object'`, so `null` reaches the engine untouched and
+ the two faces converge with no edit at that seam. Previously the same driver
+ answered the same missing id two ways, chosen by `isRemote`.
+- **`RemoteTransport.bulkUpdate()`'s skip stops being dead code.**
+ `if (updated) results.push(updated)` is the cross-driver convention
+ `SqlDriver.bulkUpdate` follows; on this transport `updated` could never be
+ falsy, so a batch over N missing ids answered N invented rows. It now answers
+ the rows that exist.
+
+`upsert()` is untouched on both drivers: an upsert never answers "not found".
+
+No landed test pinned the fabricating posture on either driver, so the
+regression pins added here are net-new coverage rather than a changed baseline.
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata key is removed, renamed or re-shaped: the moving surfaces are two driver methods' declared return types and the value they answer for an id that names no row, so there is nothing for `objectstack migrate meta`, `spec-changes.json` or the upgrade guide to project, and this changeset prescribes no rewrite. The consumer obligation is a TypeScript narrowing at the call site, delivered by the compiler. `type-surface-only` is NOT claimable here: its predicate 4 (narrowed-from-erased) is false — neither declared return was `any` at the merge base, they were the non-null `Promise<Record<string, unknown>>` — and, independently, runtime behaviour moves in the same diff, which is more than a type surface. Same disposition and reasoning as `.changeset/driver-memory-update-upsert-honest-types.md` (PR #14434), one day earlier in this same series. -->
diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts
@@ -155,9 +155,13 @@ describe.skipIf(!sharedMongod)('MongoDBDriver', () => {
  it('should update a record and return updated data', async () => {
  await driver.create('task', { id: 'upd-1', title: 'Original', status: 'new' });
  const result = await driver.update('task', 'upd-1', { title: 'Updated', status: 'done' });
- expect(result.title).toBe('Updated');
- expect(result.status).toBe('done');
- expect(result.id).toBe('upd-1');
+ // `update()` declares `Record<string, unknown> | null` (#14428): a miss
+ // answers `null`. This case is the FOUND arm, so pin that first and read
+ // the fields through it -- same idiom as `findOne` above.
+ expect(result).not.toBeNull();
+ expect(result!.title).toBe('Updated');
+ expect(result!.status).toBe('done');
+ expect(result!.id).toBe('upd-1');
  expect(result).not.toHaveProperty('_id');
  });
 

diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.ts
@@ -400,7 +400,34 @@ export class MongoDBDriver implements IDataDriver {
  return result;
  }
 
- async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>> {
+ /**
+ * [#14428] A miss answers `null` — the arm `IDataDriver.update()` declares
+ * (#13878) and the one `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and
+ * `TursoDriver`'s local face already return.
+ *
+ * This door used to answer a missing id with a row ASSEMBLED from the
+ * caller's own payload plus the `updated_at` it had just stamped:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne` matched nothing, `findOne` came back `null`, and the caller was
+ * handed a record for an id that names no document. The reason that was ever
+ * written — "the declaration does not permit `null`, so something has to come
+ * back" — was removed by #13878; the posture outlived it. The maintainer
+ * ruled it out on 2026-09-03 (「同意」, decision batch #15 item 1, posture A).
+ *
+ * Why the fabricated row is the expensive direction, not merely the wrong
+ * one: it says SUCCEEDED where the truth is NOT FOUND, and it says so in a
+ * shape that carries the caller's own fields back, so nothing about it looks
+ * wrong. A caller — human or agent — reads it as a landed write and does not
+ * retry, alert or roll back. Through the engine's by-id door
+ * (`engine.ts` → `driver.update`) it surfaced as a REST/SDK/MCP `200` with a
+ * record that does not exist, on this driver and Turso's remote face only.
+ *
+ * ⚠️ `upsert()` is deliberately untouched: an upsert never answers
+ * "not found" (it inserts instead), so it has no not-found arm to declare.
+ */
+ async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown> | null> {
  const collection = this.getCollection(object);
  const session = this.getSession(options);
 
@@ -419,7 +446,7 @@ export class MongoDBDriver implements IDataDriver {
  { session, projection: { _id: 0 } },
  );
 
- return (updated as Record<string, unknown>) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ return (updated as Record<string, unknown> | null) ?? null;
  }
 
  async upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>> {

diff --git a/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts b/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts
@@ -0,0 +1,202 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#14428] `MongoDBDriver.update()` answers a missing id with `null`, not with
+ * a record it made up.
+ *
+ * # What was broken
+ *
+ * The door read:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne({ id })` matching nothing and `findOne({ id })` coming back `null`
+ * still produced a row — the caller's own payload plus the `updated_at` this
+ * driver had just stamped, under an id that names no document. Since #13878
+ * (PR #14434) `IDataDriver.update()` declares `Promise[Record[string, unknown]
+ * | null]`, so "a row for an id that does not exist" is no longer a way of
+ * satisfying the declaration: it is a value the declaration distinguishes from.
+ * Four of six shipped implementations already answered `null`; this one and
+ * Turso's remote face answered "updated". Maintainer ruling 2026-09-03,
+ * posture A.
+ *
+ * # Why this file exists at all
+ *
+ * The card measured that NO landed test pinned the miss posture on this driver
+ * — `mongodb-driver.test.ts:157,175` read `update()` results over rows that
+ * EXIST. So this is net-new coverage, and the fabricating posture could have
+ * come back without reddening anything.
+ *
+ * # Why it does not live in `mongodb-driver.test.ts`
+ *
+ * That suite is `describe.skipIf(!sharedMongod)` and `createTestMongod` skips
+ * it unless `OS_TEST_MONGODB_MEMORY_SERVER_ENABLED=1` (#5517 retired the
+ * 123 MB binary download that was ejecting unrelated PRs from the merge queue).
+ * A pin added there would be GREEN-BY-SKIP on every CI run — a phantom pin,
+ * which is worse than none: it reads as coverage in the file list and can
+ * never fail. The fake `Db` below is the pattern
+ * `mongodb-findone-options.test.ts` established and
+ * `mongodb-own-key-undefined.test.ts` reuses: `getCollection` is
+ * `this.db.collection(name)`, so replacing `db` observes every call the real
+ * code path makes, with no server and no download.
+ *
+ * # The pins, and what each alone would miss
+ *
+ * - **The miss pin** is the defect: `findOne` empty ⇒ `null`.
+ * - **The positive control** is what stops the fix from being "return `null`
+ * always". A driver that had simply deleted the read-back would pass the
+ * miss pin and break every update that works.
+ * - **The no-fabrication pin** asserts the specific shape that used to come
+ * back (the caller's fields, the stamped `updated_at`). `toBeNull()` alone
+ * would also be satisfied by a driver that threw and was caught elsewhere;
+ * this states what must NOT be synthesized.
+ * - **The write-still-issued pin** holds the other half of the contract: the
+ * `updateOne` is still sent. A "fix" that short-circuited on a miss by
+ * reading FIRST would answer `null` correctly and quietly stop writing.
+ *
+ * # ⚠️ There is deliberately NO type-level pin in this file — and NOT because
+ * # nothing would read one
+ *
+ * #13878's `memory-update-declared-null.test.ts` pins the declared return type
+ * with `Equals`/`IsAny` consts. That instrument reaches this file through only
+ * ONE program, and it is not the one whose name is on the package:
+ *
+ * - **This package's own `typecheck` script cannot see it.** `tsconfig.json`
+ * here carries `"exclude": [..., "**\/*.test.ts"]` (escaped so this comment
+ * does not terminate early), and `tsc --noEmit` reads that config. Measured,
+ * not assumed: `tsc --noEmit --listFiles` in this package lists 0 files
+ * ending `.test.ts` (the sibling `driver-turso`, whose tsconfig excludes
+ * only `node_modules`/`dist`, lists 43). vitest transpiles without
+ * typechecking, and the root `tsconfig.json` excludes `packages` entirely,
+ * so neither of those picks it up either. That exclusion is itself a filed
+ * defect (#14917), not a design.
+ * - **`pnpm check:type-check-debt` DOES compile it.** The ratchet's
+ * `--re-measure` leg generates a project that drops the test exclusion and
+ * runs `tsc` over this package with its tests un-hidden, then compares the
+ * error count to the frozen `TEST_DEBT['@objectstack/driver-mongodb']` entry
+ * (10: `TS1309` x7 + `TS2550` x3). ⭐ Not theory: the first head of this
+ * branch widened `update()`'s declaration, the three found-arm reads in
+ * `mongodb-driver.test.ts` became `TS18047 'result' is possibly 'null'`, and
+ * that lane went red at 13 (+3) while `pnpm typecheck` stayed green. CI
+ * caught in this file's layer exactly what the package's own typecheck is
+ * blind to.
+ *
+ * So a type pin here would not be a phantom — it would be checked, once, in a
+ * lane that reports a break as a ledger COUNT moving rather than as a named
+ * assertion failure, and that reports it only when someone runs the whole-repo
+ * re-measure. The declaration is pinned by better instruments instead, both of
+ * which run in this package's own `typecheck`:
+ *
+ * - **narrowing the declaration back** to `Promise[Record[string, unknown]]`
+ * is a `tsc` error in `mongodb-driver.ts` itself — that file IS in the
+ * program, and the body's `?? null` then returns `Record[string, unknown] |
+ * null` from a non-null signature. `pnpm --filter @objectstack/driver-mongodb
+ * typecheck` reds.
+ * - **losing the contract linkage** (should `IDataDriver.update()` drop its
+ * `| null` arm) reds the same typecheck through `implements IDataDriver`.
+ * - **reverting the behaviour** while keeping the signature reds the runtime
+ * pins below.
+ *
+ * # Reverse verification — predicted direction, then what was OBSERVED
+ *
+ * Predicted: restoring the `|| withoutUndefinedOwnKeys({ id: String(id),
+ * ...updateData })` fallback reds the miss pin and the no-fabrication pin,
+ * while the positive control and the write-still-issued pin stay GREEN — they
+ * exercise the found arm, which the revert does not touch.
+ *
+ * Observed, with the mutation proved on disk (injected text counted, deleted
+ * text absent) and the restore proved by a `git hash-object` match against the
+ * HEAD blob: `Test Files 1 failed (1)`, `Tests 2 failed | 2 passed (4)`. The
+ * two reds are the miss pin and the no-fabrication pin, by name. ⚠️ All FOUR
+ * cases ran — there is no compile-time leg here, because there is no type pin
+ * in this file to red; a prediction that the file would fail to typecheck as a
+ * whole would have been wrong for exactly that reason.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { MongoDBDriver } from './mongodb-driver.js';
+
+/** What the fake collection recorded, so the WRITE half stays observable. */
+interface Recorded {
+ updateOne: Array<{ filter: Record<string, unknown>; update: Record<string, unknown> }>;
+ findOne: Array<Record<string, unknown>>;
+}
+
+/**
+ * A driver wired to a recording fake `Db` — no `connect()`, no server.
+ *
+ * `stored` is the document `findOne` answers with; `null` models the miss (a
+ * real `findOne` resolves `null` when nothing matches), and an object models
+ * the row that exists.
+ */
+function makeDriver(stored: Record<string, unknown> | null) {
+ const recorded: Recorded = { updateOne: [], findOne: [] };
+ const collection = {
+ async updateOne(filter: Record<string, unknown>, update: Record<string, unknown>) {
+ recorded.updateOne.push({ filter, update });
+ return { matchedCount: stored ? 1 : 0, modifiedCount: stored ? 1 : 0 };
+ },
+ async findOne(filter: Record<string, unknown>) {
+ recorded.findOne.push(filter);
+ return stored;
+ },
+ };
+ const driver = new MongoDBDriver({ url: 'mongodb://127.0.0.1:1/probe' });
+ (driver as any).db = { collection: () => collection };
+ return { driver, recorded };
+}
+
+describe('[#14428] MongoDBDriver.update() on a missing id', () => {
+ it('resolves null when no document carries that id', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(result).toBeNull();
+ // The narrowing the declared type demands of every caller.
+ const title = result === null ? 'absent' : result.title;
+ expect(title).toBe('absent');
+ });
+
+ it('fabricates nothing — no id, no payload echo, no stamped updated_at', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited', owner: 'u1' });
+
+ // The exact shape the old fallback produced: `{ id, ...updateData }` with
+ // `updated_at` stamped a moment earlier. Asserted as a NON-match against a
+ // reconstruction of it, so the pin names the thing it forbids rather than
+ // only the thing it wants — `toBeNull()` alone would also be satisfied by a
+ // driver that threw and was caught somewhere up the stack.
+ //
+ // ⚠️ NOT written as `expect(result).not.toBeTypeOf('object')`: `typeof
+ // null` IS `'object'` in JS, so that assertion fails on the correct value.
+ expect(result).toBeNull();
+ expect(result).not.toMatchObject({ id: 'no-such-id' });
+ expect(Object.keys((result as Record<string, unknown> | null) ?? {})).toEqual([]);
+ });
+
+ it('still ISSUES the write — the miss is discovered by reading back, not by refusing', async () => {
+ const { driver, recorded } = makeDriver(null);
+
+ await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(recorded.updateOne).toHaveLength(1);
+ expect(recorded.updateOne[0].filter).toEqual({ id: 'no-such-id' });
+ expect((recorded.updateOne[0].update as any).$set.title).toBe('edited');
+ expect(recorded.findOne).toHaveLength(1);
+ expect(recorded.findOne[0]).toEqual({ id: 'no-such-id' });
+ });
+
+ it('POSITIVE CONTROL — an id that DOES exist still returns the stored row', async () => {
+ const stored = { id: 'task-1', title: 'edited', owner: 'u1', updated_at: new Date('2026-01-01T00:00:00Z') };
+ const { driver } = makeDriver(stored);
+
+ const result = await driver.update('task', 'task-1', { title: 'edited' });
+
+ expect(result).not.toBeNull();
+ expect(result!.id).toBe('task-1');
+ expect(result!.title).toBe('edited');
+ });
+});
diff --git a/.changeset/driver-update-missing-id-null.md b/.changeset/driver-update-missing-id-null.md
@@ -0,0 +1,64 @@
+---
+"@objectstack/driver-mongodb": minor
+"@objectstack/driver-turso": minor
+---
+
+fix(drivers): `update()` on a missing id answers `null` on MongoDB and on Turso's remote face
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing alongside a
+runtime behaviour change, shipped as `minor` under the launch-window convention. Two
+published declared returns move: `MongoDBDriver.update()` and `RemoteTransport.update()`
+(both exported from their package index) now declare
+`Promise<Record<string, unknown> | null>` where they declared
+`Promise<Record<string, unknown>>`. A caller that reads fields off either result —
+`result.id`, `result.title` — no longer compiles until it narrows the `null` arm first.
+The narrowing is delivered by the compiler at every call site, and it is the honest
+declaration: the value that arm carries has always been reachable, it was simply being
+answered with a fabricated record instead.
+
+`IDataDriver.update()` declares `Promise<Record<string, unknown> | null>` — the
+not-found arm landed with the ruling on the contract (`packages/spec` is untouched here),
+and it is the answer `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and `TursoDriver`'s
+local face have always given. Two implementations did not honour it. They **invented a
+record** instead:
+
+- `MongoDBDriver.update()` ran `updateOne({ id })`, then `findOne({ id })`, and
+ when nothing came back returned
+ `withoutUndefinedOwnKeys({ id: String(id), ...updateData })` — a row assembled
+ from the caller's own payload plus the `updated_at` it had just stamped, under
+ an id that names no document.
+- `RemoteTransport.update()` ran `UPDATE … WHERE "id" = ?`, then
+ `SELECT * … WHERE "id" = ?`, and when no row came back returned
+ `{ id, ...data }` — the caller's payload with the id stapled on.
+
+Both now return `null`. That is the runtime half of this change, and it is why this
+release is not a pure type-surface move: the value a caller receives for a missing id is
+different at run time, not only in the `.d.ts`.
+
+This is the expensive direction of wrong, not merely the wrong answer: the
+fabricated row said **succeeded** where the truth was **not found**, and said it
+in a shape carrying the caller's own fields back, so nothing about it looked
+wrong. Through the engine's by-id door a REST / SDK / MCP `update` against a
+deleted or mistyped id answered **200 with a record that does not exist** — on
+these two implementations only. A caller, human or agent, read that as a landed
+write and did not retry, alert or roll back.
+
+Two things downstream become correct rather than merely different:
+
+- **One `TursoDriver`, one answer.** Its remote branch passes the transport
+ result through `formatRemoteRow`, which already guards
+ `row && typeof row === 'object'`, so `null` reaches the engine untouched and
+ the two faces converge with no edit at that seam. Previously the same driver
+ answered the same missing id two ways, chosen by `isRemote`.
+- **`RemoteTransport.bulkUpdate()`'s skip stops being dead code.**
+ `if (updated) results.push(updated)` is the cross-driver convention
+ `SqlDriver.bulkUpdate` follows; on this transport `updated` could never be
+ falsy, so a batch over N missing ids answered N invented rows. It now answers
+ the rows that exist.
+
+`upsert()` is untouched on both drivers: an upsert never answers "not found".
+
+No landed test pinned the fabricating posture on either driver, so the
+regression pins added here are net-new coverage rather than a changed baseline.
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata key is removed, renamed or re-shaped: the moving surfaces are two driver methods' declared return types and the value they answer for an id that names no row, so there is nothing for `objectstack migrate meta`, `spec-changes.json` or the upgrade guide to project, and this changeset prescribes no rewrite. The consumer obligation is a TypeScript narrowing at the call site, delivered by the compiler. `type-surface-only` is NOT claimable here: its predicate 4 (narrowed-from-erased) is false — neither declared return was `any` at the merge base, they were the non-null `Promise<Record<string, unknown>>` — and, independently, runtime behaviour moves in the same diff, which is more than a type surface. Same disposition and reasoning as `.changeset/driver-memory-update-upsert-honest-types.md` (PR #14434), one day earlier in this same series. -->
diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.test.ts
@@ -155,9 +155,13 @@ describe.skipIf(!sharedMongod)('MongoDBDriver', () => {
  it('should update a record and return updated data', async () => {
  await driver.create('task', { id: 'upd-1', title: 'Original', status: 'new' });
  const result = await driver.update('task', 'upd-1', { title: 'Updated', status: 'done' });
- expect(result.title).toBe('Updated');
- expect(result.status).toBe('done');
- expect(result.id).toBe('upd-1');
+ // `update()` declares `Record<string, unknown> | null` (#14428): a miss
+ // answers `null`. This case is the FOUND arm, so pin that first and read
+ // the fields through it -- same idiom as `findOne` above.
+ expect(result).not.toBeNull();
+ expect(result!.title).toBe('Updated');
+ expect(result!.status).toBe('done');
+ expect(result!.id).toBe('upd-1');
  expect(result).not.toHaveProperty('_id');
  });
 

diff --git a/packages/drivers/driver-mongodb/src/mongodb-driver.ts b/packages/drivers/driver-mongodb/src/mongodb-driver.ts
@@ -400,7 +400,34 @@ export class MongoDBDriver implements IDataDriver {
  return result;
  }
 
- async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>> {
+ /**
+ * [#14428] A miss answers `null` — the arm `IDataDriver.update()` declares
+ * (#13878) and the one `InMemoryDriver`, `SqlDriver`, `SqliteWasmDriver` and
+ * `TursoDriver`'s local face already return.
+ *
+ * This door used to answer a missing id with a row ASSEMBLED from the
+ * caller's own payload plus the `updated_at` it had just stamped:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne` matched nothing, `findOne` came back `null`, and the caller was
+ * handed a record for an id that names no document. The reason that was ever
+ * written — "the declaration does not permit `null`, so something has to come
+ * back" — was removed by #13878; the posture outlived it. The maintainer
+ * ruled it out on 2026-09-03 (「同意」, decision batch #15 item 1, posture A).
+ *
+ * Why the fabricated row is the expensive direction, not merely the wrong
+ * one: it says SUCCEEDED where the truth is NOT FOUND, and it says so in a
+ * shape that carries the caller's own fields back, so nothing about it looks
+ * wrong. A caller — human or agent — reads it as a landed write and does not
+ * retry, alert or roll back. Through the engine's by-id door
+ * (`engine.ts` → `driver.update`) it surfaced as a REST/SDK/MCP `200` with a
+ * record that does not exist, on this driver and Turso's remote face only.
+ *
+ * ⚠️ `upsert()` is deliberately untouched: an upsert never answers
+ * "not found" (it inserts instead), so it has no not-found arm to declare.
+ */
+ async update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown> | null> {
  const collection = this.getCollection(object);
  const session = this.getSession(options);
 
@@ -419,7 +446,7 @@ export class MongoDBDriver implements IDataDriver {
  { session, projection: { _id: 0 } },
  );
 
- return (updated as Record<string, unknown>) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ return (updated as Record<string, unknown> | null) ?? null;
  }
 
  async upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>> {

diff --git a/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts b/packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts
@@ -0,0 +1,202 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#14428] `MongoDBDriver.update()` answers a missing id with `null`, not with
+ * a record it made up.
+ *
+ * # What was broken
+ *
+ * The door read:
+ *
+ * return (updated as Record[string, unknown]) || withoutUndefinedOwnKeys({ id: String(id), ...updateData });
+ *
+ * `updateOne({ id })` matching nothing and `findOne({ id })` coming back `null`
+ * still produced a row — the caller's own payload plus the `updated_at` this
+ * driver had just stamped, under an id that names no document. Since #13878
+ * (PR #14434) `IDataDriver.update()` declares `Promise[Record[string, unknown]
+ * | null]`, so "a row for an id that does not exist" is no longer a way of
+ * satisfying the declaration: it is a value the declaration distinguishes from.
+ * Four of six shipped implementations already answered `null`; this one and
+ * Turso's remote face answered "updated". Maintainer ruling 2026-09-03,
+ * posture A.
+ *
+ * # Why this file exists at all
+ *
+ * The card measured that NO landed test pinned the miss posture on this driver
+ * — `mongodb-driver.test.ts:157,175` read `update()` results over rows that
+ * EXIST. So this is net-new coverage, and the fabricating posture could have
+ * come back without reddening anything.
+ *
+ * # Why it does not live in `mongodb-driver.test.ts`
+ *
+ * That suite is `describe.skipIf(!sharedMongod)` and `createTestMongod` skips
+ * it unless `OS_TEST_MONGODB_MEMORY_SERVER_ENABLED=1` (#5517 retired the
+ * 123 MB binary download that was ejecting unrelated PRs from the merge queue).
+ * A pin added there would be GREEN-BY-SKIP on every CI run — a phantom pin,
+ * which is worse than none: it reads as coverage in the file list and can
+ * never fail. The fake `Db` below is the pattern
+ * `mongodb-findone-options.test.ts` established and
+ * `mongodb-own-key-undefined.test.ts` reuses: `getCollection` is
+ * `this.db.collection(name)`, so replacing `db` observes every call the real
+ * code path makes, with no server and no download.
+ *
+ * # The pins, and what each alone would miss
+ *
+ * - **The miss pin** is the defect: `findOne` empty ⇒ `null`.
+ * - **The positive control** is what stops the fix from being "return `null`
+ * always". A driver that had simply deleted the read-back would pass the
+ * miss pin and break every update that works.
+ * - **The no-fabrication pin** asserts the specific shape that used to come
+ * back (the caller's fields, the stamped `updated_at`). `toBeNull()` alone
+ * would also be satisfied by a driver that threw and was caught elsewhere;
+ * this states what must NOT be synthesized.
+ * - **The write-still-issued pin** holds the other half of the contract: the
+ * `updateOne` is still sent. A "fix" that short-circuited on a miss by
+ * reading FIRST would answer `null` correctly and quietly stop writing.
+ *
+ * # ⚠️ There is deliberately NO type-level pin in this file — and NOT because
+ * # nothing would read one
+ *
+ * #13878's `memory-update-declared-null.test.ts` pins the declared return type
+ * with `Equals`/`IsAny` consts. That instrument reaches this file through only
+ * ONE program, and it is not the one whose name is on the package:
+ *
+ * - **This package's own `typecheck` script cannot see it.** `tsconfig.json`
+ * here carries `"exclude": [..., "**\/*.test.ts"]` (escaped so this comment
+ * does not terminate early), and `tsc --noEmit` reads that config. Measured,
+ * not assumed: `tsc --noEmit --listFiles` in this package lists 0 files
+ * ending `.test.ts` (the sibling `driver-turso`, whose tsconfig excludes
+ * only `node_modules`/`dist`, lists 43). vitest transpiles without
+ * typechecking, and the root `tsconfig.json` excludes `packages` entirely,
+ * so neither of those picks it up either. That exclusion is itself a filed
+ * defect (#14917), not a design.
+ * - **`pnpm check:type-check-debt` DOES compile it.** The ratchet's
+ * `--re-measure` leg generates a project that drops the test exclusion and
+ * runs `tsc` over this package with its tests un-hidden, then compares the
+ * error count to the frozen `TEST_DEBT['@objectstack/driver-mongodb']` entry
+ * (10: `TS1309` x7 + `TS2550` x3). ⭐ Not theory: the first head of this
+ * branch widened `update()`'s declaration, the three found-arm reads in
+ * `mongodb-driver.test.ts` became `TS18047 'result' is possibly 'null'`, and
+ * that lane went red at 13 (+3) while `pnpm typecheck` stayed green. CI
+ * caught in this file's layer exactly what the package's own typecheck is
+ * blind to.
+ *
+ * So a type pin here would not be a phantom — it would be checked, once, in a
+ * lane that reports a break as a ledger COUNT moving rather than as a named
+ * assertion failure, and that reports it only when someone runs the whole-repo
+ * re-measure. The declaration is pinned by better instruments instead, both of
+ * which run in this package's own `typecheck`:
+ *
+ * - **narrowing the declaration back** to `Promise[Record[string, unknown]]`
+ * is a `tsc` error in `mongodb-driver.ts` itself — that file IS in the
+ * program, and the body's `?? null` then returns `Record[string, unknown] |
+ * null` from a non-null signature. `pnpm --filter @objectstack/driver-mongodb
+ * typecheck` reds.
+ * - **losing the contract linkage** (should `IDataDriver.update()` drop its
+ * `| null` arm) reds the same typecheck through `implements IDataDriver`.
+ * - **reverting the behaviour** while keeping the signature reds the runtime
+ * pins below.
+ *
+ * # Reverse verification — predicted direction, then what was OBSERVED
+ *
+ * Predicted: restoring the `|| withoutUndefinedOwnKeys({ id: String(id),
+ * ...updateData })` fallback reds the miss pin and the no-fabrication pin,
+ * while the positive control and the write-still-issued pin stay GREEN — they
+ * exercise the found arm, which the revert does not touch.
+ *
+ * Observed, with the mutation proved on disk (injected text counted, deleted
+ * text absent) and the restore proved by a `git hash-object` match against the
+ * HEAD blob: `Test Files 1 failed (1)`, `Tests 2 failed | 2 passed (4)`. The
+ * two reds are the miss pin and the no-fabrication pin, by name. ⚠️ All FOUR
+ * cases ran — there is no compile-time leg here, because there is no type pin
+ * in this file to red; a prediction that the file would fail to typecheck as a
+ * whole would have been wrong for exactly that reason.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { MongoDBDriver } from './mongodb-driver.js';
+
+/** What the fake collection recorded, so the WRITE half stays observable. */
+interface Recorded {
+ updateOne: Array<{ filter: Record<string, unknown>; update: Record<string, unknown> }>;
+ findOne: Array<Record<string, unknown>>;
+}
+
+/**
+ * A driver wired to a recording fake `Db` — no `connect()`, no server.
+ *
+ * `stored` is the document `findOne` answers with; `null` models the miss (a
+ * real `findOne` resolves `null` when nothing matches), and an object models
+ * the row that exists.
+ */
+function makeDriver(stored: Record<string, unknown> | null) {
+ const recorded: Recorded = { updateOne: [], findOne: [] };
+ const collection = {
+ async updateOne(filter: Record<string, unknown>, update: Record<string, unknown>) {
+ recorded.updateOne.push({ filter, update });
+ return { matchedCount: stored ? 1 : 0, modifiedCount: stored ? 1 : 0 };
+ },
+ async findOne(filter: Record<string, unknown>) {
+ recorded.findOne.push(filter);
+ return stored;
+ },
+ };
+ const driver = new MongoDBDriver({ url: 'mongodb://127.0.0.1:1/probe' });
+ (driver as any).db = { collection: () => collection };
+ return { driver, recorded };
+}
+
+describe('[#14428] MongoDBDriver.update() on a missing id', () => {
+ it('resolves null when no document carries that id', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(result).toBeNull();
+ // The narrowing the declared type demands of every caller.
+ const title = result === null ? 'absent' : result.title;
+ expect(title).toBe('absent');
+ });
+
+ it('fabricates nothing — no id, no payload echo, no stamped updated_at', async () => {
+ const { driver } = makeDriver(null);
+
+ const result = await driver.update('task', 'no-such-id', { title: 'edited', owner: 'u1' });
+
+ // The exact shape the old fallback produced: `{ id, ...updateData }` with
+ // `updated_at` stamped a moment earlier. Asserted as a NON-match against a
+ // reconstruction of it, so the pin names the thing it forbids rather than
+ // only the thing it wants — `toBeNull()` alone would also be satisfied by a
+ // driver that threw and was caught somewhere up the stack.
+ //
+ // ⚠️ NOT written as `expect(result).not.toBeTypeOf('object')`: `typeof
+ // null` IS `'object'` in JS, so that assertion fails on the correct value.
+ expect(result).toBeNull();
+ expect(result).not.toMatchObject({ id: 'no-such-id' });
+ expect(Object.keys((result as Record<string, unknown> | null) ?? {})).toEqual([]);
+ });
+
+ it('still ISSUES the write — the miss is discovered by reading back, not by refusing', async () => {
+ const { driver, recorded } = makeDriver(null);
+
+ await driver.update('task', 'no-such-id', { title: 'edited' });
+
+ expect(recorded.updateOne).toHaveLength(1);
+ expect(recorded.updateOne[0].filter).toEqual({ id: 'no-such-id' });
+ expect((recorded.updateOne[0].update as any).$set.title).toBe('edited');
+ expect(recorded.findOne).toHaveLength(1);
+ expect(recorded.findOne[0]).toEqual({ id: 'no-such-id' });
+ });
+
+ it('POSITIVE CONTROL — an id that DOES exist still returns the stored row', async () => {
+ const stored = { id: 'task-1', title: 'edited', owner: 'u1', updated_at: new Date('2026-01-01T00:00:00Z') };
+ const { driver } = makeDriver(stored);
+
+ const result = await driver.update('task', 'task-1', { title: 'edited' });
+
+ expect(result).not.toBeNull();
+ expect(result!.id).toBe('task-1');
+ expect(result!.title).toBe('edited');
+ });
+});