feat(driver-turso): the remote face issues auto_number values from the shared persistent sequence

Disposition A of the remote-autonumber question, executed: a create,
bulkCreate or upsert on the Turso REMOTE transport that leaves an
auto_number slot empty now gets a generated value, atomically in the
database, from the same `_objectstack_sequences` counter the local and
embedded-replica faces draw from.

- sql-driver: the rules a second face must share are lifted into protected
  members (`resolveSequenceTenantId`, `defineSequencesTable`,
  `maxAutonumberCounter`, `escapeLikePrefix`, the table name and retry
  budget). No behaviour change on the local faces.
- turso-driver: `getNextSequenceValue` routes by transport; the remote face
  moves the counter in one statement (`UPDATE … RETURNING`, cold path
  `INSERT … ON CONFLICT DO UPDATE … RETURNING`), bootstraps from the data
  table by the shared reading, and carries the #5495 re-seed. A legacy
  (pre-key_hash) table is refused loudly, not keyed by a second rule.
- remote-transport: `upsert` takes insert-only columns so a merge keeps the
  number already in the row.
- The refusal suite is converted to the generation suite; the two resync
  boundary pins are rewritten to pin generation; a cross-process pin runs
  two writers in two processes against one database file.

Claude-Session: https://claude.ai/code/session_01Ujdtvqs7ree7WyQmEDwEnG
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

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

@@ -44,6 +44,12 @@ export type {
   // checking with it.
   SqlWindowFunctionSpec,
   SqlWindowFunctionQuery,
+  // The autonumber reservation a write draws (#5495): what `fillAutoNumberFields`
+  // reports and the collision re-seed consumes. Exported so a subclass that
+  // issues numbers over another transport (`TursoDriver`'s remote face) can
+  // override the re-seed primitives with their declared parameter type instead
+  // of a structural copy of it.
+  AutoNumberReservation,
 } from './sql-driver.js';
 
 // [#5222] The cross-field `{ $field }` push-down conformance corpus: one

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

@@ -7593,6 +7593,56 @@ export class SqlDriver implements IDataDriver {
       .digest('hex');
   }
 
+  // ── The sequence semantics a second face shares, stated once ──────────────
+  //
+  // `TursoDriver`'s REMOTE face issues record numbers over `@libsql/client`
+  // rather than through this class's Knex transaction, and an embedded-replica
+  // face and a remote face can point at ONE database. Two faces computing a
+  // different counter key, a different tenant bucket or a different data-table
+  // bootstrap would hand out colliding numbers on that database, so each rule
+  // below is a `protected` member that face CALLS — never a copy it keeps. The
+  // members are small on purpose: they are the whole of what decides which
+  // counter a value is drawn from and where a cold counter starts.
+
+  /** The sequence-counter table's name, for a face that spells its own statements against it. */
+  protected get sequencesTableName(): string {
+    return SEQUENCES_TABLE;
+  }
+
+  /** How many times a write re-seeds and retries on a provable autonumber collision (#5495). */
+  protected get autoNumberCollisionRetries(): number {
+    return AUTONUMBER_COLLISION_RETRIES;
+  }
+
+  /**
+   * The tenant bucket a counter row is keyed by: the row's tenant when the
+   * object HAS a tenant column and the row carries one, else the platform
+   * bucket `GLOBAL_TENANT`. One spelling for the issue path, the re-seed path
+   * and the counter identity, which used to carry it three times.
+   */
+  protected resolveSequenceTenantId(tenantField: string | null, tenantId: string | null): string {
+    return tenantField && tenantId ? String(tenantId) : GLOBAL_TENANT;
+  }
+
+  /**
+   * The column definitions of the `key_hash`-keyed sequences table — the ONE
+   * place the shape is spelled. {@link createSequencesTable} runs it through a
+   * live connection; a face with no Knex connection compiles the same builder
+   * to text (`knex.schema.createTable(name, t => this.defineSequencesTable(t)).toSQL()`)
+   * and sends that, so both faces create byte-for-byte the same table.
+   */
+  protected defineSequencesTable(t: Knex.CreateTableBuilder): void {
+    t.string('key_hash', 64).notNullable().primary();
+    t.string('object').notNullable();
+    t.string('tenant_id').notNullable();
+    t.string('field').notNullable();
+    // Non-indexed, so it is free of the PK length limit — a long `{plan_no}`
+    // composite scope fits. 1024 is far above any realistic rendered prefix.
+    t.string('scope', 1024).notNullable().defaultTo('');
+    t.bigInteger('last_value').notNullable().defaultTo(0);
+    t.timestamp('updated_at').defaultTo(this.knex.fn.now());
+  }
+
   /**
    * Create the current `key_hash`-keyed sequences table shape. `runner` is the
    * connection the DDL runs on (a fresh pooled connection by default, or the
@@ -7602,17 +7652,7 @@ export class SqlDriver implements IDataDriver {
     table: string,
     runner: Knex | Knex.Transaction = this.knex,
   ): Promise<void> {
-    await runner.schema.createTable(table, (t) => {
-      t.string('key_hash', 64).notNullable().primary();
-      t.string('object').notNullable();
-      t.string('tenant_id').notNullable();
-      t.string('field').notNullable();
-      // Non-indexed, so it is free of the PK length limit — a long `{plan_no}`
-      // composite scope fits. 1024 is far above any realistic rendered prefix.
-      t.string('scope', 1024).notNullable().defaultTo('');
-      t.bigInteger('last_value').notNullable().defaultTo(0);
-      t.timestamp('updated_at').defaultTo(this.knex.fn.now());
-    });
+    await runner.schema.createTable(table, (t) => this.defineSequencesTable(t));
   }
 
   /**
@@ -7743,16 +7783,34 @@ export class SqlDriver implements IDataDriver {
     tenantId: string | null,
     suffix = '',
   ): Promise<number> {
-    const escapedPrefix = prefix.replace(/([\\%_])/g, '\\$1');
-    let builder = queryRunner(tableName).select(field).where(field, 'like', `${escapedPrefix}%`).whereNotNull(field);
+    let builder = queryRunner(tableName).select(field).where(field, 'like', `${this.escapeLikePrefix(prefix)}%`).whereNotNull(field);
     if (tenantField && tenantId !== null) {
       builder = builder.where(tenantField, tenantId);
     }
     const rows = await builder;
+    return this.maxAutonumberCounter((rows as any[]).map((r) => (r as any)[field]), prefix, suffix);
+  }
+
+  /**
+   * The rendered prefix as a `LIKE` anchor: `\`, `%` and `_` escaped with a
+   * backslash, so a prefix is matched literally. The predicate's pre-filter
+   * only — {@link maxAutonumberCounter} re-checks the prefix per row.
+   */
+  protected escapeLikePrefix(prefix: string): string {
+    return prefix.replace(/([\\%_])/g, '\\$1');
+  }
+
+  /**
+   * The bootstrap reading itself — the highest counter among the stored values
+   * of one counter's partition, under the anchored / unanchored rules the
+   * {@link scanMaxNumericTail} docblock states. Separated from the statement
+   * that fetches the values so a face that fetches them through another
+   * transport reads them by this one rule rather than by a copy of it.
+   */
+  protected maxAutonumberCounter(values: Iterable<unknown>, prefix: string, suffix: string): number {
     let maxN = 0;
     const anchored = prefix !== '' || suffix !== '';
-    for (const r of rows as any[]) {
-      const v: string = (r as any)[field];
+    for (const v of values) {
       if (typeof v !== 'string') continue;
       let n: number;
       if (anchored) {
@@ -7893,7 +7951,7 @@ export class SqlDriver implements IDataDriver {
     // locking on a second one (SQLite pool max=1). `initObjects` normally warms
     // this up front, making the call a no-op — this only bites the lazy path.
     await this.ensureSequencesTable(parentTrx);
-    const resolvedTenantId = tenantField && tenantId ? String(tenantId) : GLOBAL_TENANT;
+    const resolvedTenantId = this.resolveSequenceTenantId(tenantField, tenantId);
     if (scope !== '' && !this.sequencesHasKeyHash) {
       // The legacy sequences table could not be migrated to the key_hash shape,
       // so it cannot represent per-scope counters. Fail with a clear, actionable
@@ -8153,8 +8211,7 @@ export class SqlDriver implements IDataDriver {
    */
   protected async resyncSequenceToDataMax(reservation: AutoNumberReservation): Promise<void> {
     await this.ensureSequencesTable();
-    const resolvedTenantId =
-      reservation.tenantField && reservation.tenantId ? String(reservation.tenantId) : GLOBAL_TENANT;
+    const resolvedTenantId = this.resolveSequenceTenantId(reservation.tenantField, reservation.tenantId);
     const key = this.sequencesHasKeyHash
       ? { key_hash: this.sequenceKeyHash(reservation.tableName, resolvedTenantId, reservation.field, reservation.scope) }
       : { object: reservation.tableName, tenant_id: resolvedTenantId, field: reservation.field };
@@ -8188,8 +8245,7 @@ export class SqlDriver implements IDataDriver {
    * that drew from it. See {@link bulkCreate}.
    */
   protected autoNumberCounterKey(reservation: AutoNumberReservation): string {
-    const resolvedTenantId =
-      reservation.tenantField && reservation.tenantId ? String(reservation.tenantId) : GLOBAL_TENANT;
+    const resolvedTenantId = this.resolveSequenceTenantId(reservation.tenantField, reservation.tenantId);
     return this.sequenceKeyHash(reservation.tableName, resolvedTenantId, reservation.field, reservation.scope);
   }
 

packages/drivers/driver-turso/package.json

@@ -47,6 +47,7 @@
   "devDependencies": {
     "@types/node": "^26.2.0",
     "better-sqlite3": "^13.0.3",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11"
   },

packages/drivers/driver-turso/src/remote-transport.ts

@@ -1595,11 +1595,21 @@ export class RemoteTransport {
     return rows[0] ?? null;
   }
 
+  /**
+   * `insertOnlyColumns` — columns written on the INSERT leg and left alone on
+   * the MERGE leg, so a value the caller (or the driver, on its behalf) put on
+   * the row for a NEW row never overwrites the one an existing row already
+   * holds. The transport is told WHICH columns, not WHY: the driver decides
+   * from the schema it holds and this class does not (the same division
+   * `setFilterColumnSql` and `setTenantFieldResolver` draw). A column named
+   * here that is also a merge key is simply a merge key.
+   */
   async upsert(
     object: string,
     data: Record<string, unknown>,
     conflictKeys?: string[],
     table: string = object,
+    insertOnlyColumns: readonly string[] = [],
   ): Promise<Record<string, unknown>> {
     await this.ensureConnected();
 
@@ -1618,7 +1628,7 @@ export class RemoteTransport {
     const mergeKeys = conflictKeys && conflictKeys.length > 0 ? conflictKeys : ['id'];
 
     // Build ON CONFLICT ... DO UPDATE SET
-    const updateCols = columns.filter((c) => !mergeKeys.includes(c));
+    const updateCols = columns.filter((c) => !mergeKeys.includes(c) && !insertOnlyColumns.includes(c));
     const updateClauses = updateCols.map((col) => `"${col}" = excluded."${col}"`).join(', ');
 
     let sql = `INSERT INTO ${this.tableSql(table)} (${columns.map((c) => `"${c}"`).join(', ')}) VALUES (${placeholders})`;

packages/drivers/driver-turso/src/turso-autonumber-batch-resync.test.ts

@@ -15,33 +15,37 @@
  *  - **LOCAL (and replica, same local engine)** falls through to
  *    `super.bulkCreate` / `super.upsert` and with them the re-seed. Asserted
  *    below on rows.
- *  - **REMOTE** hands the batch to `RemoteTransport.bulkCreate`, which builds
- *    its own INSERT and never enters `fillAutoNumberFields` — so it has neither
- *    the defect nor the fix. On that face `auto_number` is only a column-type
- *    mapping and no sequence machinery exists to be stale; the boundary is
- *    pinned as an ASSERTION rather than a comment, so wiring autonumber into
- *    the remote transport later cannot silently inherit this file's green.
- *    (That gap was #6944's, not this card's — and #6944 has since answered it.)
+ *  - **REMOTE** used to hand the batch to `RemoteTransport.bulkCreate`, which
+ *    builds its own INSERT and never entered `fillAutoNumberFields` — so it had
+ *    neither the defect nor the fix: on that face `auto_number` was only a
+ *    column-type mapping and no sequence machinery existed to be stale. The
+ *    boundary was pinned as an ASSERTION rather than a comment, so wiring
+ *    autonumber into the remote transport later could not silently inherit
+ *    this file's green. (That gap was #6944's; #6944 answered it with a
+ *    refusal, and #21113 answered it with generation.)
  *
- * # ⚠️ [#6944] The pin below was rewritten, not deleted
+ * # ⚠️ [#6944 → #21113] The pin below was rewritten twice, never deleted
  *
  * This file's REMOTE case pinned an ABSENCE: `RemoteTransport` has no autonumber
  * surface on the batch path any more than on the single-row one, and a remote
  * `bulkCreate` therefore resolved with `[null, null]` in the slots. #6944
  * carried out triage's disposition B and made that face refuse LOUDLY
  * (`NOT_IMPLEMENTED`/501), raised on `TursoDriver` because
- * `RemoteTransport.create(object, data)` cannot see a field type. The absence
- * half is still true and still worth guarding; the "and therefore nothing
- * happens" half is not.
+ * `RemoteTransport.create(object, data)` cannot see a field type. #21113 then
+ * opened the appetite door (measured demand on the hosted product) and made
+ * the driver ISSUE the numbers on this face, one row at a time through its own
+ * `create` — the transport still sees no field type and still gets a row that
+ * already carries its number. The absence half is still true and still worth
+ * guarding; "and therefore nothing happens" is not, and neither is "and
+ * therefore it refuses".
  *
  * Deleting the pin would remove the guard against a silent half-implementation
  * inside the transport; leaving it untouched would keep a green assertion
  * standing next to a claim that no longer holds. So it keeps the surface probe
- * verbatim and gains the refusal — asserted on `bulkCreate` specifically,
- * because Turso OVERRIDES it and `RemoteTransport.bulkCreate` loops its OWN
- * `create`, so "`create` refuses" is not on its own an answer about this path
- * either. The refusal's own suite is
- * `turso-remote-autonumber-refusal.test.ts`.
+ * verbatim and gains the generation AND the re-seed — asserted on `bulkCreate`
+ * specifically, because Turso OVERRIDES it, so "`create` generates" is not on
+ * its own an answer about this path. The generation's own suite is
+ * `turso-remote-autonumber-generation.test.ts`.
  */
 
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
@@ -131,26 +135,28 @@ describe('[#6943] TursoDriver batch/upsert autonumber re-seed', () => {
     expect(merged.title).toBe('edited');
   });
 
-  it('REMOTE: the transport that bypasses this path still has no autonumber machinery to re-seed', async () => {
+  it('REMOTE: the transport still has no autonumber machinery of its own, on the batch path either', async () => {
     const remote = new TursoDriver({ url: 'libsql://example.turso.io', authToken: 'placeholder' });
     expect(remote.transportMode).toBe('remote');
 
     // The boundary, stated as a fact about the code rather than about a live
     // connection: `RemoteTransport` has no autonumber surface at all, on the
-    // batch path any more than the single-row one. #6944 did not add one — it
-    // refused one layer up — so this half is unchanged, and it remains what a
-    // future half-implementation inside the transport has to go through.
+    // batch path any more than the single-row one. Neither #6944 nor #21113
+    // added one — both acted one layer up, on the driver — so this half is
+    // unchanged, and it remains what a future half-implementation inside the
+    // transport has to go through.
     const transportSurface = Object.getOwnPropertyNames(
       Object.getPrototypeOf((remote as any).remoteTransport),
     );
     expect(transportSurface).toContain('bulkCreate');
     expect(transportSurface.some((m) => /autonumber|sequence/i.test(m))).toBe(false);
   });
 
-  it('REMOTE: [#6944] and having none, it refuses the batch rather than writing nothing', async () => {
+  it('REMOTE: [#21113] and the driver numbers the batch on this face too — and re-seeds it after a seed replay', async () => {
+    const stub = makeLibsqlSqliteStub();
     const remote = new TursoDriver({
       url: 'libsql://example.turso.io',
-      client: makeLibsqlSqliteStub() as never,
+      client: stub as never,
     });
     await remote.connect();
     await remote.initObjects([
@@ -164,20 +170,27 @@ describe('[#6943] TursoDriver batch/upsert autonumber re-seed', () => {
       } as any,
     ]);
 
-    // ⚠️ `code` AND `status`, never a bare `toThrow` (ADR-0112, #6144).
-    const err = await remote
-      .bulkCreate('crm_case', [
-        { organization_id: 'orgA', title: 'b1' },
-        { organization_id: 'orgA', title: 'b2' },
-      ])
-      .then(
-        (rows) => {
-          throw new Error(`expected a refusal, got ${JSON.stringify(rows)}`);
-        },
-        (e) => e as Error & { code?: string; status?: number },
-      );
-    expect(err.code).toBe('NOT_IMPLEMENTED');
-    expect(err.status).toBe(501);
+    const first = await remote.bulkCreate('crm_case', [
+      { organization_id: 'orgA', title: 'b1' },
+      { organization_id: 'orgA', title: 'b2' },
+    ]);
+    expect((first as any[]).map((r) => r.case_number)).toEqual(['CASE-00001', 'CASE-00002']);
+
+    // The LOCAL half's scenario, on the remote face: rows 3..10 land by a path
+    // that never enters `fillAutoNumberFields`, so the counter sits at 2 while
+    // the table holds 10. The next batch is served above it, on the first call.
+    const insert = stub.raw.prepare(
+      'insert into "crm_case" ("id", "organization_id", "case_number", "title") values (?, ?, ?, ?)',
+    );
+    for (let n = 3; n <= 10; n++) insert.run(`bypass-${n}`, 'orgA', `CASE-${String(n).padStart(5, '0')}`, `row ${n}`);
+
+    const after = await remote.bulkCreate('crm_case', [
+      { organization_id: 'orgA', title: 'b3' },
+      { organization_id: 'orgA', title: 'b4' },
+    ]);
+    expect((after as any[]).map((r) => r.case_number)).toEqual(['CASE-00011', 'CASE-00012']);
+    const count = (stub.raw.prepare('select count(*) as c from "crm_case"').all() as Array<{ c: number }>)[0].c;
+    expect(count).toBe(12);
 
     await remote.disconnect();
   });