payment-kit 1.29.1 → 1.29.3

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);
+    },
+  };
+}

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

@@ -0,0 +1,142 @@
+// Phase 10 (W2-2): identity slot driver contract.
+//
+// The identity slot resolves a request Host to a tenant (instanceDid) and, from
+// Phase 11, supplies per-tenant encryption keys. It mirrors the relevant slice
+// of BlockletServiceRPCInterface (resolveInstanceDidForHost). The CF identity
+// shims (blocklet-sdk/{auth-service,session,verify-session,verify-sign}) sit
+// behind this contract.
+//
+// Resolution is single-point: ONLY the tenant-resolving middleware calls
+// resolveInstanceDidForHost (the scanner enforces that no route/queue/cron
+// reads Host directly). In single-tenant mode the default driver ignores the
+// host and returns the deployment app DID, so Blocklet Server behavior is
+// unchanged; multi-tenant hosts inject a driver that maps Host -> instanceDid
+// and returns null for unknown hosts (the middleware then fails closed 4xx).
+
+import type { WalletObject } from '@ocap/wallet';
+
+import { getDefaultInstanceDid, getTenantMode, TenantError, TENANT_HOST_UNRESOLVED } from '../tenant';
+
+/** Branding/profile used by DID-Connect prompts (mirrors did-connect-service InstanceAppInfoDTO). */
+export interface InstanceAppInfo {
+  name?: string;
+  description?: string;
+  icon?: string;
+  link?: string;
+}
+
+/**
+ * Per-instance app signing identity used to build the DID-Connect authenticator
+ * (mirrors did-connect-service@4.0.3 InstanceAppIdentityDTO). The AUTH_SERVICE
+ * RPC `getInstanceAppIdentity(instanceDid)` already resolves the arc run-mode
+ * (instance `app:sk` → instance identity; else auth-service root `APP_SK/APP_PSK`;
+ * else fail-closed), so the payment runtime never reimplements "instance ?? root".
+ */
+export interface InstanceAppIdentity {
+  /** Current app signing key for this instance. */
+  appSk: string;
+  /** Permanent app signing key, present when the instance has rotated keys. */
+  appPsk?: string;
+  /** Branding/profile for DID-Connect prompts. */
+  appInfo?: InstanceAppInfo;
+}
+
+export interface IdentityDriver {
+  /**
+   * Resolve a request Host to its tenant instanceDid, or null/undefined when
+   * the host is unknown (multi-tenant fail-closed). The host value is the raw
+   * Host header — never a proxy header.
+   */
+  resolveInstanceDidForHost(host: string | undefined): Promise<string | null> | string | null;
+  /**
+   * Phase 11: the tenant's encryption key (EK). Required by the keyring secrets
+   * driver; optional on the contract because the single-tenant default secrets
+   * driver uses the process key and never calls it.
+   */
+  getAppEk?(instanceDid: string): Promise<string> | string;
+  /**
+   * S3-CF (DID convergence): the per-instance app signing identity backing the
+   * DID-Connect authenticator. The AUTH_SERVICE-backed driver (CF + arc-node
+   * embedded) implements this via `AUTH_SERVICE.getInstanceAppIdentity`; the
+   * blocklet-server runtime uses the @blocklet/sdk wallet wrapper and never calls
+   * it. Optional on the contract for that reason — `resolveTenantIdentity` throws
+   * a clear error if a non-SDK runtime reaches a driver that lacks it.
+   */
+  getInstanceAppIdentity?(instanceDid: string): Promise<InstanceAppIdentity> | InstanceAppIdentity;
+  /**
+   * The current tenant's business chain wallet (the receiving address + on-chain
+   * tx/refund/payout signer). SYNCHRONOUS — `wallet.address` is read inline on hot
+   * paths — so it reads the warmed per-tenant cache (see warmTenantIdentity), never
+   * an RPC. Present on AUTH_SERVICE-backed drivers (arc-node + CF, derived from
+   * getInstanceAppIdentity); ABSENT on the blocklet-server default, where auth.ts
+   * falls back to the @blocklet/sdk env wallet (which alone handles the remote-sign
+   * / delegation / migration cases a bare appSk cannot). This is the single seam:
+   * a consumer never branches on the runtime, only on "does the driver provide it".
+   */
+  getBusinessWallet?(chain: 'arcblock' | 'ethereum'): WalletObject;
+  /**
+   * The host user directory (`blocklet.getUser` etc.). Present on the arc-node
+   * embedded driver (a DID-echo: the DID-Connect DID IS the wallet DID); ABSENT on
+   * blocklet-server (real BlockletService) and on CF (its build-alias shim). auth.ts
+   * uses `driver.directory?.() ?? <real BlockletService>` — same one-seam pattern.
+   */
+  directory?(): BlockletDirectory;
+}
+
+/** The subset of @blocklet/sdk BlockletService the payment runtime calls. */
+export interface BlockletDirectory {
+  getUser(did: string, opts?: any): Promise<{ user: any }> | { user: any };
+  getUsers(params?: any): Promise<{ users: any[] }> | { users: any[] };
+  getVault(): Promise<any> | any;
+  getBlocklet(): Promise<any> | any;
+}
+
+/**
+ * Single-tenant default: every host maps to the deployment app DID. Used by
+ * Blocklet Server and the standalone worker's single-mode transition.
+ */
+export function createDefaultIdentityDriver(): IdentityDriver {
+  return {
+    resolveInstanceDidForHost() {
+      return getDefaultInstanceDid();
+    },
+  };
+}
+
+let activeIdentityDriver: IdentityDriver = createDefaultIdentityDriver();
+
+/** Inject the identity driver (multi-tenant hosts wire a Host->tenant map here). */
+export function setIdentityDriver(driver: IdentityDriver): void {
+  activeIdentityDriver = driver;
+}
+
+export function getIdentityDriver(): IdentityDriver {
+  return activeIdentityDriver;
+}
+
+/**
+ * Resolve a request's raw Host header to a tenant instanceDid. SINGLE POINT of
+ * Host -> tenant resolution — both host adapters funnel through here (the
+ * Express `contextMiddleware` and the CF worker `tenantMiddleware`), so neither
+ * reinvents Host parsing (the tenant-scan rule forbids any route/queue/cron
+ * from reading Host directly).
+ *
+ * single mode: always the deployment app DID (Blocklet Server / standalone
+ * worker unchanged). multi mode: the identity driver maps Host -> instanceDid;
+ * an unknown/missing host throws TENANT_HOST_UNRESOLVED so the caller fails
+ * closed 4xx with no default-tenant fallback.
+ *
+ * The host MUST be the raw Host header — never a proxy header
+ * (X-Forwarded-Host / X-Real-IP). The runtime host (CF route / blocklet server /
+ * reverse proxy) is responsible for ensuring it cannot be forged by the client.
+ */
+export async function resolveTenantForHost(host: string | undefined): Promise<string> {
+  if (getTenantMode() === 'single') {
+    return getDefaultInstanceDid();
+  }
+  const resolved = await activeIdentityDriver.resolveInstanceDidForHost(host);
+  if (!resolved) {
+    throw new TenantError(TENANT_HOST_UNRESOLVED, `no tenant resolved for host "${host ?? ''}"`);
+  }
+  return resolved;
+}

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

@@ -0,0 +1,40 @@
+// Phase 8 (W2-1a): db / locks driver contracts barrel.
+export type { DbDriver, DbDriverKind, DbExecResult, D1Binding } from './db';
+export { createNodeDbDriver, createD1DbDriver } from './db';
+
+export type { LockHandle, LocksDriver, LocksDriverKind, LockScope } from './locks';
+export { createMemoryLocksDriver, createD1LocksDriver, scopedLockName, MemoryLock } from './locks';
+
+export type { AuthRecord } from './auth-storage';
+export { DbAuthStorage, createAuthStorage } from './auth-storage';
+
+export type { QueueOptions, PushParams, JobEvents, QueueHandle, QueueFactory, QueueHostHooks } from './queue';
+export { nodeQueueHostHooks, setQueueHostHooks, getQueueHostHooks } from './queue';
+
+export type { CronJob, CronDriver } from './cron';
+export { matchesCron, shouldRunInWindow, createCronRegistry, setCronDriver, getCronDriver } from './cron';
+
+export type { SqlMigration } from './migrate-runner';
+export { applySqlMigrations, splitStatements } from './migrate-runner';
+
+// The embedded D1 SQL lineage, inlined (store/sql-migrations is generated from
+// cloudflare/migrations/*.sql) so it ships INSIDE the @arcblock/payment-service
+// bundle. A host provisions the embedded schema with applyPaymentCoreMigrations
+// alone — no repo paths, no wrangler. See migrate-runner.ts.
+// eslint-disable-next-line import/first
+import type { DbDriver as DbDriverForMigrations } from './db';
+// eslint-disable-next-line import/first
+import { applySqlMigrations as applySql } from './migrate-runner';
+// eslint-disable-next-line import/first
+import { paymentCoreSqlMigrations } from '../../store/sql-migrations';
+
+export { paymentCoreSqlMigrations };
+export function applyPaymentCoreMigrations(driver: DbDriverForMigrations): Promise<string[]> {
+  return applySql(driver, paymentCoreSqlMigrations);
+}
+
+export type { IdentityDriver, InstanceAppIdentity, InstanceAppInfo, BlockletDirectory } from './identity';
+export { createDefaultIdentityDriver, setIdentityDriver, getIdentityDriver } from './identity';
+
+export type { SecretsDriver } from './secrets';
+export { createDefaultSecretsDriver, createKeyringSecretsDriver, setSecretsDriver, getSecretsDriver } from './secrets';