objectstack-ai
diff --git a/‎.changeset/driver-update-missing-id-null.md‎
Lines changed: 64 additions & 0 deletions b/‎.changeset/driver-update-missing-id-null.md‎
Lines changed: 64 additions & 0 deletions
diff --git a/‎packages/drivers/driver-mongodb/src/mongodb-driver.test.ts‎
Lines changed: 7 additions & 3 deletions b/‎packages/drivers/driver-mongodb/src/mongodb-driver.test.ts‎
Lines changed: 7 additions & 3 deletions
diff --git a/‎packages/drivers/driver-mongodb/src/mongodb-driver.ts‎
Lines changed: 29 additions & 2 deletions b/‎packages/drivers/driver-mongodb/src/mongodb-driver.ts‎
Lines changed: 29 additions & 2 deletions
diff --git a/‎packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts‎
Lines changed: 202 additions & 0 deletions b/‎packages/drivers/driver-mongodb/src/mongodb-update-missing-id.test.ts‎
Lines changed: 202 additions & 0 deletions
@@ -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. -->
@@ -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');
     });
 
 
@@ -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>> {
 
@@ -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');
+  });
+});