payment-kit 1.29.1 → 1.29.2

package/api/src/libs/context.ts

@@ -1,13 +1,29 @@
 import { AsyncLocalStorage, AsyncResource } from 'async_hooks';
 
+import {
+  TENANT_CONTEXT_MISSING,
+  TenantError,
+  assertValidInstanceDid,
+  getDefaultInstanceDid,
+  getTenantMode,
+} from './tenant';
+
+export * from './tenant';
+
 interface RequestContext {
   requestedBy?: string;
   requestId?: string;
+  instanceDid?: string;
 }
 
 class RequestContextManager {
   private storage = new AsyncLocalStorage<RequestContext>();
   private contexts = new Map<string, RequestContext>();
+  // System-operation flag: when set, TenantModel bypasses tenant scoping so a
+  // legitimate cross-tenant read (queue dispatch, IAP bundle->tenant reverse
+  // lookup, event fan-out) can load rows across tenants. Entered ONLY via the
+  // system* helpers — a normal route context can never read across tenants.
+  private systemStorage = new AsyncLocalStorage<boolean>();
 
   getContext(requestId?: string): RequestContext {
     if (requestId && this.contexts.has(requestId)) {
@@ -20,16 +36,62 @@ class RequestContextManager {
     return this.getContext(requestId).requestedBy;
   }
 
+  /**
+   * Run fn with the given tenant. Nested calls shadow the outer tenant and restore it on exit.
+   * Other context fields (requestId, requestedBy) are inherited from the enclosing scope.
+   */
+  withTenant<T>(instanceDid: string, fn: () => Promise<T> | T): Promise<T> {
+    try {
+      assertValidInstanceDid(instanceDid);
+    } catch (err) {
+      return Promise.reject(err);
+    }
+    const parent = this.storage.getStore();
+    // frozen so fn cannot mutate the stored context and affect sibling calls
+    const next = Object.freeze({ ...parent, instanceDid });
+    return this.storage.run(next, () => Promise.resolve(fn()));
+  }
+
+  /**
+   * Current tenant. Single mode falls back to the deployment app DID;
+   * multi mode fails closed with TENANT_CONTEXT_MISSING.
+   */
+  getInstanceDid(): string {
+    const instanceDid = this.storage.getStore()?.instanceDid;
+    if (instanceDid) return instanceDid;
+    if (getTenantMode() === 'single') return getDefaultInstanceDid();
+    throw new TenantError(TENANT_CONTEXT_MISSING, 'tenant context is missing in multi-tenant mode');
+  }
+
+  /**
+   * Run fn as a system operation: TenantModel scoping is bypassed for the span
+   * of fn so legitimate cross-tenant reads can load rows regardless of tenant.
+   * The scope ends when fn settles — callers must enforce the row's tenant
+   * themselves (e.g. assertJobObjectTenant). Explicit by construction: only the
+   * system* helpers enter this, so a normal route can never read across tenants.
+   */
+  runAsSystem<T>(fn: () => Promise<T> | T): Promise<T> {
+    return this.systemStorage.run(true, () => Promise.resolve(fn()));
+  }
+
+  /** True inside a runAsSystem span — TenantModel checks this to skip scoping. */
+  isSystem(): boolean {
+    return this.systemStorage.getStore() === true;
+  }
+
   run<T>(context: RequestContext, fn: () => Promise<T> | T): Promise<T> {
     const requestId = context.requestId || `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    // inherit tenant from the enclosing scope unless explicitly provided
+    const instanceDid = context.instanceDid ?? this.storage.getStore()?.instanceDid;
 
     this.contexts.set(requestId, {
       ...context,
+      instanceDid,
       requestId,
     });
 
     return new Promise((resolve, reject) => {
-      this.storage.run({ ...context, requestId }, async () => {
+      this.storage.run({ ...context, instanceDid, requestId }, async () => {
         const resource = new AsyncResource('RequestContext');
         try {
           const result = await resource.runInAsyncScope(fn);
@@ -46,3 +108,18 @@ class RequestContextManager {
 }
 
 export const context = new RequestContextManager();
+
+/** Run fn with the given tenant — also the test injection helper for jest. */
+export function withTenant<T>(instanceDid: string, fn: () => Promise<T> | T): Promise<T> {
+  return context.withTenant(instanceDid, fn);
+}
+
+/** Current tenant; see RequestContextManager#getInstanceDid for mode semantics. */
+export function getInstanceDid(): string {
+  return context.getInstanceDid();
+}
+
+/** True inside a runAsSystem span; TenantModel uses it to bypass scoping. */
+export function isSystemContext(): boolean {
+  return context.isSystem();
+}

package/api/src/libs/currency.ts

@@ -1,8 +1,8 @@
 import { fromTokenToUnit, fromUnitToToken } from '@ocap/util';
-import { getUrl } from '@blocklet/sdk';
+import { getUrl } from '@blocklet/sdk/lib/component';
 import { PaymentCurrency, Price, Product, RechargeConfig } from '../store/models';
 import { trimDecimals } from './math-utils';
-import { createPaymentLink } from '../routes/payment-links';
+import { createPaymentLink } from '../routes/hono/payment-links';
 import logger from './logger';
 
 export async function formatCurrencyToken(amount: string, currencyId: string) {

package/api/src/libs/dayjs.ts

@@ -5,8 +5,14 @@ import relativeTime from 'dayjs/plugin/relativeTime';
 import timezone from 'dayjs/plugin/timezone'; // dependent on utc plugin
 import utc from 'dayjs/plugin/utc';
 
-import('dayjs/locale/en');
-import('dayjs/locale/zh');
+// Use explicit `.js` so the dynamic import resolves under Node ESM (strict
+// resolution: dayjs ships no `exports` map, so the extensionless subpath
+// `dayjs/locale/en` fails when payment-core is embedded in a Node ESM host
+// like arc). Webpack/blocklet-server tolerate the extension too.
+// eslint-disable-next-line import/extensions -- explicit .js required for Node ESM hosts (arc)
+import('dayjs/locale/en.js');
+// eslint-disable-next-line import/extensions -- explicit .js required for Node ESM hosts (arc)
+import('dayjs/locale/zh.js');
 
 dayjs.extend(relativeTime);
 dayjs.extend(localizedFormat);

package/api/src/libs/drivers/auth-storage.ts

@@ -0,0 +1,118 @@
+// Phase 8 (W2-1a): DID Connect token storage on the db driver.
+//
+// In Blocklet Server the real @arcblock/did-connect-storage-nedb (file-backed)
+// is used unchanged. In the CF worker that package was aliased to a NO-OP stub
+// (cloudflare/shims/nedb-storage.ts) — DID Connect state was silently dropped.
+// This is the from-scratch persistent implementation on top of the db driver
+// contract, so the same code runs on the node (sqlite) and d1 backends and is
+// covered by the driver consistency suite.
+//
+// Records are flexible JSON documents keyed by `token` (the DID-Auth session
+// token, globally unique — no instance_did column needed; isolation is by the
+// unguessable token, matching the original file store's scope).
+
+import type { DbDriver } from './db';
+
+const { EventEmitter } = require('events');
+
+const TABLE = 'did_auth_records';
+
+export interface AuthRecord {
+  token: string;
+  [key: string]: any;
+}
+
+export class DbAuthStorage extends EventEmitter {
+  private driver: DbDriver;
+  private ready: Promise<void> | null = null;
+
+  constructor(driver: DbDriver) {
+    super();
+    if (!driver) throw new Error('DbAuthStorage requires a db driver');
+    this.driver = driver;
+  }
+
+  // idempotent lazy schema — the original file store self-managed its db file
+  // (it was never part of the Umzug/D1 migration chain), so we keep that here.
+  private ensureTable(): Promise<void> {
+    if (!this.ready) {
+      this.ready = this.driver
+        .exec(
+          `CREATE TABLE IF NOT EXISTS ${TABLE} (` +
+            'token TEXT PRIMARY KEY, ' +
+            'doc TEXT NOT NULL, ' +
+            'created_at INTEGER NOT NULL, ' +
+            'updated_at INTEGER NOT NULL)'
+        )
+        .then(() => undefined)
+        .catch((err) => {
+          // reset so a transient failure can be retried on next call
+          this.ready = null;
+          throw err;
+        });
+    }
+    return this.ready;
+  }
+
+  async read(token: string): Promise<AuthRecord | null> {
+    if (!token) throw new Error('token is required to read auth record');
+    await this.ensureTable();
+    const row = await this.driver.get<{ doc: string }>(`SELECT doc FROM ${TABLE} WHERE token = ?`, [token]);
+    if (!row) return null;
+    return JSON.parse(row.doc) as AuthRecord;
+  }
+
+  async create(token: string, status = 'created'): Promise<AuthRecord> {
+    if (!token) throw new Error('token is required to create auth record');
+    await this.ensureTable();
+    const now = Date.now();
+    const doc: AuthRecord = { token, status, createdAt: now, updatedAt: now };
+    await this.driver.exec(`INSERT INTO ${TABLE} (token, doc, created_at, updated_at) VALUES (?, ?, ?, ?)`, [
+      token,
+      JSON.stringify(doc),
+      now,
+      now,
+    ]);
+    this.emit('create', doc);
+    return doc;
+  }
+
+  async update(token: string, updates: Record<string, any> = {}): Promise<AuthRecord | null> {
+    if (!token) throw new Error('token is required to update auth record');
+    await this.ensureTable();
+    const current = await this.read(token);
+    if (!current) return null;
+    const now = Date.now();
+    const merged: AuthRecord = { ...current, ...updates, token, updatedAt: now };
+    await this.driver.exec(`UPDATE ${TABLE} SET doc = ?, updated_at = ? WHERE token = ?`, [
+      JSON.stringify(merged),
+      now,
+      token,
+    ]);
+    this.emit('update', merged);
+    return merged;
+  }
+
+  async delete(token: string): Promise<number> {
+    if (!token) throw new Error('token is required to delete auth record');
+    await this.ensureTable();
+    const res = await this.driver.exec(`DELETE FROM ${TABLE} WHERE token = ?`, [token]);
+    this.emit('destroy', token);
+    return res.changes;
+  }
+
+  async exist(token: string, did: any): Promise<boolean> {
+    if (!token) throw new Error('token is required to check auth record');
+    const doc = await this.read(token);
+    return !!doc && doc.did === did;
+  }
+
+  async clear(): Promise<void> {
+    await this.ensureTable();
+    await this.driver.exec(`DELETE FROM ${TABLE}`);
+  }
+}
+
+export function createAuthStorage(driver: DbDriver): DbAuthStorage {
+  return new DbAuthStorage(driver);
+}

package/api/src/libs/drivers/cron.ts

@@ -0,0 +1,264 @@
+// Phase 9 (W2-1b): cron slot driver contract.
+//
+// The cron contract is: register jobs + a due-poll dispatch entry. The HOST
+// provides the trigger — CF `scheduled()` calls runDue() every minute; the Node
+// host uses @abtnode/cron's own scheduler. Both share ONE cron-expression
+// matcher (previously duplicated in cloudflare/shims/cron.ts), so embedded and
+// worker agree on exactly when a job is due.
+
+export interface CronJob {
+  name: string;
+  time: string;
+  fn: () => Promise<any> | any;
+  /**
+   * runOnInit: honored by the node host scheduler (@abtnode/cron) which runs
+   * the job once at registration. The shared registry's runDue (used by the
+   * cf-cron host) does NOT auto-run it — CF deliberately skips runOnInit and
+   * lets the next matching trigger fire it (running at module-init would block
+   * the request / risk CPU limits). It is a host-trigger concern, not a matcher
+   * concern.
+   */
+  options?: { runOnInit?: boolean };
+}
+
+export interface CronDriver {
+  kind: 'node-cron' | 'cf-cron';
+  /** register jobs (idempotent: clears + re-adds) */
+  register(jobs: CronJob[], onError?: (err: Error, name: string) => void): void;
+  /** add a single job after init */
+  addJob(name: string, time: string, fn: CronJob['fn'], options?: CronJob['options']): void;
+  /** due-poll dispatch entry — runs every job whose schedule matches `now` */
+  runDue(now?: Date): Promise<{ ran: string[]; skipped: string[] }>;
+  /** run one named job regardless of schedule (manual trigger) */
+  runJob(name: string): Promise<void>;
+  /** registered job descriptions (name + schedule) */
+  getJobNames(): string[];
+  /**
+   * D2 teardown surface. Stop all live timers (the node-cron driver tears down
+   * its @abtnode/cron scheduler so the process has no dangling cron timer); the
+   * registry is preserved so a later start() can re-register. No-op for the
+   * passive cf-cron driver (it never owns a timer — the host drives runDue).
+   */
+  stop(): void;
+  /** stop + clear the registry (a full reset; start() re-registers from scratch). */
+  dispose(): void;
+}
+
+// @abtnode/cron's CronScheduler shape we drive (lib/scheduler.js): addJob wires
+// a self-scheduling `cron` CronJob (start=true) and exposes the live jobs map.
+interface AbtnodeCronScheduler {
+  jobs: Record<string, { start(): void; stop(): void }>;
+  addJob(name: string, time: string, fn: (...args: any[]) => any, options?: Record<string, any>): unknown;
+}
+
+// --- shared cron-expression matcher ---
+// 6-field: second minute hour dayOfMonth month dayOfWeek (seconds ignored —
+// CF triggers are minute-level). Supports numbers, *, */N, ranges, lists.
+
+function parseField(field: string, min: number, max: number): number[] | null {
+  // null means "match all"
+  if (field === '*') return null;
+
+  const values = new Set<number>();
+
+  for (const part of field.split(',')) {
+    const stepMatch = part.match(/^\*\/(\d+)$/);
+    const rangeMatch = part.match(/^(\d+)-(\d+)$/);
+    if (stepMatch) {
+      const step = parseInt(stepMatch[1]!, 10);
+      for (let i = min; i <= max; i += step) values.add(i);
+    } else if (rangeMatch) {
+      const from = parseInt(rangeMatch[1]!, 10);
+      const to = parseInt(rangeMatch[2]!, 10);
+      for (let i = from; i <= to; i += 1) values.add(i);
+    } else {
+      const num = parseInt(part, 10);
+      if (!Number.isNaN(num)) values.add(num);
+    }
+  }
+
+  return values.size > 0 ? Array.from(values) : null;
+}
+
+/**
+ * Whether `date` matches a 5- or 6-field cron expression (minute granularity).
+ */
+export function matchesCron(cronExpr: string, date: Date): boolean {
+  const fields = cronExpr.trim().split(/\s+/);
+  if (fields.length < 5) return true; // can't parse — run it
+
+  const offset = fields.length >= 6 ? 1 : 0;
+  // length >= 5 guaranteed above, so offset..offset+4 are present
+  const minuteField = parseField(fields[offset]!, 0, 59);
+  const hourField = parseField(fields[offset + 1]!, 0, 23);
+  const domField = parseField(fields[offset + 2]!, 1, 31);
+  // cron months are 1-12 (matched against getUTCMonth()+1); a 0-11 range here
+  // made step patterns like */3 generate {0,3,6,9} and never match real months.
+  const monthField = parseField(fields[offset + 3]!, 1, 12);
+  const dowField = parseField(fields[offset + 4]!, 0, 6);
+
+  const m = date.getUTCMinutes();
+  const h = date.getUTCHours();
+  const dom = date.getUTCDate();
+  const month = date.getUTCMonth() + 1; // JS 0-based → cron 1-based
+  const dow = date.getUTCDay();
+
+  if (minuteField && !minuteField.includes(m)) return false;
+  if (hourField && !hourField.includes(h)) return false;
+  if (domField && !domField.includes(dom)) return false;
+  if (monthField && !monthField.includes(month)) return false;
+  if (dowField && !dowField.includes(dow)) return false;
+
+  return true;
+}
+
+/**
+ * Whether a cron expression should fire at `date`. Minute-level match — the
+ * trigger source (CF scheduled / node cron) fires every minute, so each
+ * expression triggers at its designed frequency (see the 2026-04-17 incident
+ * note in the prior cloudflare/shims/cron.ts history).
+ */
+export function shouldRunInWindow(cronExpr: string, date: Date): boolean {
+  return matchesCron(cronExpr, date);
+}
+
+/**
+ * A cron registry implementing the due-poll dispatch entry on top of the shared
+ * matcher. Both the node-cron and cf-cron drivers are built from this — the
+ * only difference is who calls runDue (node scheduler vs CF scheduled()).
+ */
+export function createCronRegistry(kind: CronDriver['kind']): CronDriver {
+  const jobs: CronJob[] = [];
+  let onErrorHandler: ((err: Error, name: string) => void) | undefined;
+
+  // node-cron self-schedules through @abtnode/cron; cf-cron stays a passive
+  // matcher registry whose runDue() is driven by the host's scheduled().
+  const selfSchedule = kind === 'node-cron';
+  let scheduler: AbtnodeCronScheduler | null = null;
+
+  // Tear down every live @abtnode/cron timer (each scheduler.jobs[*] is a `cron`
+  // CronJob with its own setTimeout). Clears the scheduler so the process has no
+  // dangling cron handle and a later start() rebuilds from scratch.
+  const stopScheduler = (): void => {
+    if (!scheduler) return;
+    for (const job of Object.values(scheduler.jobs)) {
+      try {
+        job.stop();
+      } catch {
+        /* a job already stopped — ignore */
+      }
+    }
+    scheduler = null;
+  };
+
+  // (Re)build the live scheduler from the current jobs array. Always stops the
+  // previous scheduler first so register()/start() is idempotent: no double
+  // timers, no double registration. Lazy-requires @abtnode/cron so the cf-cron
+  // path and pure imports never load the Node scheduler.
+  const startScheduler = (): void => {
+    stopScheduler();
+    if (!selfSchedule || jobs.length === 0) return;
+    // eslint-disable-next-line global-require
+    const mod = require('@abtnode/cron');
+    // real package (CJS): module.exports = { init }; the CF shim (ESM default)
+    // resolves to { default: { init } } under the bundler interop.
+    type AbtnodeInit = (params: {
+      context: any;
+      jobs: any[];
+      onError: (e: Error, n: string) => void;
+    }) => AbtnodeCronScheduler;
+    const init: AbtnodeInit = mod.init ?? mod.default?.init;
+    // D2/multi: skip runOnInit in multi-tenant mode — same as the CF host
+    // (cloudflare/shims/cron.ts). A runOnInit job fires immediately at register,
+    // before any request, so it has NO tenant context; in multi mode that makes
+    // a tenant-requiring startup push (e.g. deposit.vault / credit.consumption)
+    // throw TENANT_CONTEXT_MISSING and abort lifecycle.start(). The job still
+    // runs on its next scheduled tick (where the handler resolves its own
+    // tenant). Single mode keeps runOnInit (the default tenant is always present).
+    // eslint-disable-next-line global-require
+    const { getTenantMode } = require('../tenant');
+    const isMulti = getTenantMode() === 'multi';
+    scheduler = init({
+      context: {},
+      jobs: jobs.map((j) => ({
+        name: j.name,
+        time: j.time,
+        fn: j.fn,
+        options: isMulti ? { ...(j.options || {}), runOnInit: false } : j.options || {},
+      })),
+      onError: onErrorHandler ?? (() => {}),
+    });
+  };
+
+  return {
+    kind,
+    register(next, onError) {
+      jobs.length = 0;
+      onErrorHandler = onError;
+      for (const job of next || []) {
+        if (job.name && job.time && typeof job.fn === 'function') jobs.push(job);
+      }
+      startScheduler();
+    },
+    addJob(name, time, fn, options) {
+      jobs.push({ name, time, fn, options });
+      // keep the live scheduler in sync when one is already running
+      if (selfSchedule && scheduler) {
+        try {
+          scheduler.addJob(name, time, fn, options || {});
+        } catch (err: any) {
+          onErrorHandler?.(err, name);
+        }
+      }
+    },
+    stop() {
+      stopScheduler();
+    },
+    dispose() {
+      stopScheduler();
+      jobs.length = 0;
+    },
+    async runDue(now = new Date()) {
+      const ran: string[] = [];
+      const skipped: string[] = [];
+      for (const job of jobs) {
+        if (shouldRunInWindow(job.time, now)) {
+          ran.push(job.name);
+          try {
+            // eslint-disable-next-line no-await-in-loop -- jobs run sequentially within a tick
+            await job.fn();
+          } catch (err: any) {
+            onErrorHandler?.(err, job.name);
+          }
+        } else {
+          skipped.push(job.name);
+        }
+      }
+      return { ran, skipped };
+    },
+    async runJob(name) {
+      const job = jobs.find((j) => j.name === name);
+      if (!job) return;
+      try {
+        await job.fn();
+      } catch (err: any) {
+        onErrorHandler?.(err, name);
+      }
+    },
+    getJobNames() {
+      return jobs.map((j) => `${j.name} (${j.time})`);
+    },
+  };
+}
+
+// Active cron driver — injectable by the factory's `cron` slot; defaults to a
+// node-cron registry. The worker shell injects the cf-cron driver.
+let activeCronDriver: CronDriver = createCronRegistry('node-cron');
+
+export function setCronDriver(driver: CronDriver): void {
+  activeCronDriver = driver;
+}
+
+export function getCronDriver(): CronDriver {
+  return activeCronDriver;
+}

package/api/src/libs/drivers/db.ts

@@ -0,0 +1,170 @@
+// Phase 8 (W2-1a): db slot driver contract.
+//
+// The db slot carries the SQL layer. Two implementations conform to the same
+// contract:
+//   - node driver: wraps the existing Sequelize instance (raw helpers go
+//     through `sequelize.query`); `sequelize` is exposed so the factory can
+//     bind models to it (unchanged from Phase 7).
+//   - d1 driver: wraps a Cloudflare D1 binding (`prepare().bind().run()/all()/
+//     first()`), the worker-side implementation that `cloudflare/shims/
+//     sequelize-d1` is the model layer for. This phase formalizes the
+//     D1Binding contract beneath that model layer; physically relocating the
+//     sequelize-d1 files out of cloudflare/shims is part of the Phase 12 §3.1
+//     shim cleanup (the small, build-orphan shims — lock.ts, nedb-storage — are
+//     handled here since they carried no build-alias risk).
+//
+// The minimal raw surface (`exec/all/get`) is what tenant-agnostic
+// infrastructure (e.g. the did-connect AuthStorage) builds on so a single
+// implementation runs identically on both backends — see auth-storage.ts and
+// the driver consistency suite.
+
+export type DbDriverKind = 'node' | 'd1';
+
+export interface DbExecResult {
+  /** rows affected by an INSERT/UPDATE/DELETE */
+  changes: number;
+}
+
+/** a single statement in a batch (the shared transactional primitive) */
+export interface DbBatchOp {
+  sql: string;
+  params?: any[];
+}
+
+export interface DbDriver {
+  kind: DbDriverKind;
+  /** run a write statement; returns affected row count */
+  exec(sql: string, params?: any[]): Promise<DbExecResult>;
+  /** run a SELECT; returns all rows */
+  all<T = any>(sql: string, params?: any[]): Promise<T[]>;
+  /** run a SELECT; returns the first row or null */
+  get<T = any>(sql: string, params?: any[]): Promise<T | null>;
+  /**
+   * Run statements atomically. This is the contract's transactional primitive:
+   * D1 offers no interactive transactions, only batch-level atomicity, so the
+   * shared surface is "all-or-nothing batch" rather than an interactive
+   * transaction(fn). Any statement failing rolls the whole batch back. The node
+   * driver wraps a real Sequelize transaction; the d1 driver uses binding.batch.
+   */
+  batch(ops: DbBatchOp[]): Promise<any[]>;
+  /**
+   * The ORM instance, when the backend is Sequelize-based. Present on the node
+   * driver (model binding target); absent on the raw d1 binding driver.
+   */
+  sequelize?: any;
+}
+
+/** D1 binding shape (subset actually used). */
+export interface D1Binding {
+  prepare(sql: string): {
+    bind(...params: any[]): {
+      run(): Promise<{ success?: boolean; meta?: { changes?: number; rows_written?: number } }>;
+      all(): Promise<{ results?: any[] }>;
+      first(): Promise<any | null>;
+    };
+  };
+  batch(stmts: any[]): Promise<any[]>;
+}
+
+/**
+ * Node driver — wraps an existing Sequelize instance. Raw helpers route through
+ * `sequelize.query` with bind replacements (`$1, $2, ...` style); no string
+ * interpolation of values, matching the d1 driver's parameter binding.
+ */
+export function createNodeDbDriver(sequelize: any): DbDriver {
+  if (!sequelize) throw new Error('createNodeDbDriver: sequelize instance is required');
+  // Sequelize positional bind uses `$1`-style markers; callers pass `?` which we
+  // translate so the same SQL string works on both drivers.
+  const toBind = (sql: string) => {
+    let i = 0;
+    return sql.replace(/\?/g, () => {
+      i += 1;
+      return `$${i}`;
+    });
+  };
+  return {
+    kind: 'node',
+    sequelize,
+    async exec(sql, params = []) {
+      const [, meta] = await sequelize.query(toBind(sql), { bind: params });
+      // sqlite returns affected rows on meta.changes; fall back to 0
+      const changes = (meta && (meta.changes ?? meta.rowCount)) ?? 0;
+      return { changes };
+    },
+    async all(sql, params = []) {
+      const rows = await sequelize.query(toBind(sql), {
+        bind: params,
+        type: sequelize.QueryTypes ? sequelize.QueryTypes.SELECT : 'SELECT',
+      });
+      return rows as any[];
+    },
+    async get(sql, params = []) {
+      const rows = await sequelize.query(toBind(sql), {
+        bind: params,
+        type: sequelize.QueryTypes ? sequelize.QueryTypes.SELECT : 'SELECT',
+      });
+      return (rows as any[])[0] ?? null;
+    },
+    // eslint-disable-next-line require-await -- async contract; returns the transaction promise
+    async batch(ops) {
+      // real Sequelize transaction — any statement throwing rolls everything back
+      return sequelize.transaction(async (t: any) => {
+        const results: any[] = [];
+        for (const op of ops) {
+          // eslint-disable-next-line no-await-in-loop -- ordered within one transaction
+          const rows = await sequelize.query(toBind(op.sql), { bind: op.params ?? [], transaction: t });
+          results.push(rows);
+        }
+        return results;
+      });
+    },
+  };
+}
+
+/**
+ * D1 driver — wraps a Cloudflare D1 binding. This is the worker-side db driver;
+ * the sequelize-d1 model layer is built on the same binding. Accepts the
+ * binding directly or a lazy getter (the worker resolves the binding per
+ * request, so it may be absent at construction time).
+ */
+export function createD1DbDriver(binding: D1Binding | (() => D1Binding)): DbDriver {
+  if (!binding) throw new Error('createD1DbDriver: D1 binding (or getter) is required');
+  const resolve = (): D1Binding => {
+    const b = typeof binding === 'function' ? (binding as () => D1Binding)() : binding;
+    if (!b) throw new Error('createD1DbDriver: D1 binding is not available');
+    return b;
+  };
+  return {
+    kind: 'd1',
+    async exec(sql, params = []) {
+      const res = await resolve()
+        .prepare(sql)
+        .bind(...params)
+        .run();
+      const changes = res?.meta?.changes ?? res?.meta?.rows_written ?? 0;
+      return { changes };
+    },
+    async all(sql, params = []) {
+      const res = await resolve()
+        .prepare(sql)
+        .bind(...params)
+        .all();
+      return (res?.results ?? []) as any[];
+    },
+    async get(sql, params = []) {
+      const row = await resolve()
+        .prepare(sql)
+        .bind(...params)
+        .first();
+      return (row ?? null) as any;
+    },
+    // eslint-disable-next-line require-await -- async contract; resolve() throws surface as rejection
+    async batch(ops) {
+      const b = resolve();
+      // D1 batch is atomic (implicitly transactional) — a failing statement
+      // rolls the batch back, matching the node driver's transaction semantics
+      const stmts = ops.map((op) => b.prepare(op.sql).bind(...(op.params ?? [])));
+      return b.batch(stmts);
+    },
+  };
+}