payment-kit 1.29.0 → 1.29.2

package/cloudflare/migrations/0007_tenant_backfill_indexes.sql

@@ -0,0 +1,65 @@
+-- Payment Kit: tenant unique keys + indexes (Phase 2, W1-1b)
+-- Mirrors the index/unique-key part of api/src/store/migrations/20260611-tenant-backfill.ts.
+--
+-- IMPORTANT: the instance_did BACKFILL is NOT here. Static migration SQL
+-- cannot know the deployment app DID, so the backfill (and the table rebuilds
+-- that drop old inline single-column UNIQUE constraints) runs through the
+-- shared runtime routine `runTenantBackfill()` (api/src/store/tenant-backfill.ts),
+-- invoked idempotently from the worker's scheduled() handler.
+--
+-- Everything below is NULL-safe before that backfill runs: SQLite treats each
+-- NULL as distinct in unique indexes, and existing single-column uniqueness
+-- (identifier / did / key / idempotency_key) guarantees no composite dupes.
+
+-- composite tenant unique keys (W1 §2.1, decisions D1/D3)
+CREATE UNIQUE INDEX IF NOT EXISTS `uq_customers_tenant_did` ON `customers` (`instance_did`, `did`);
+CREATE UNIQUE INDEX IF NOT EXISTS `uq_meter_events_tenant_identifier` ON `meter_events` (`instance_did`, `identifier`);
+CREATE UNIQUE INDEX IF NOT EXISTS `uq_meters_tenant_event_name` ON `meters` (`instance_did`, `event_name`);
+CREATE UNIQUE INDEX IF NOT EXISTS `uq_entitlements_tenant_key` ON `entitlements` (`instance_did`, `key`);
+CREATE UNIQUE INDEX IF NOT EXISTS `uq_price_quotes_tenant_idem` ON `price_quotes` (`instance_did`, `idempotency_key`);
+CREATE UNIQUE INDEX IF NOT EXISTS `uq_promotion_codes_tenant_code` ON `promotion_codes` (`instance_did`, `livemode`, `code`);
+CREATE UNIQUE INDEX IF NOT EXISTS `uq_product_vendors_tenant_key` ON `product_vendors` (`instance_did`, `vendor_key`);
+CREATE UNIQUE INDEX IF NOT EXISTS `uq_revenue_snapshots_tenant` ON `revenue_snapshots` (`instance_did`, `timestamp`, `currency_id`, `livemode`, `period_type`);
+DROP INDEX IF EXISTS `idx_revenue_snapshots_unique`;
+DROP INDEX IF EXISTS `idx_entitlements_key`;
+DROP INDEX IF EXISTS `idx_pq_idempotency`;
+
+-- plain tenant indexes for scoped queries (Phase 3+); meter_events is served
+-- by its composite unique above (high-write table, avoid a second index)
+CREATE INDEX IF NOT EXISTS `idx_customers_instance_did` ON `customers` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_products_instance_did` ON `products` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_prices_instance_did` ON `prices` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_pricing_tables_instance_did` ON `pricing_tables` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_payment_methods_instance_did` ON `payment_methods` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_checkout_sessions_instance_did` ON `checkout_sessions` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_payment_intents_instance_did` ON `payment_intents` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_payment_links_instance_did` ON `payment_links` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_setup_intents_instance_did` ON `setup_intents` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_price_quotes_instance_did` ON `price_quotes` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_subscriptions_instance_did` ON `subscriptions` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_subscription_items_instance_did` ON `subscription_items` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_subscription_schedules_instance_did` ON `subscription_schedules` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_invoices_instance_did` ON `invoices` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_invoice_items_instance_did` ON `invoice_items` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_refunds_instance_did` ON `refunds` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_credit_grants_instance_did` ON `credit_grants` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_credit_transactions_instance_did` ON `credit_transactions` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_meters_instance_did` ON `meters` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_usage_records_instance_did` ON `usage_records` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_coupons_instance_did` ON `coupons` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_promotion_codes_instance_did` ON `promotion_codes` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_discounts_instance_did` ON `discounts` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_entitlements_instance_did` ON `entitlements` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_entitlement_grants_instance_did` ON `entitlement_grants` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_entitlement_products_instance_did` ON `entitlement_products` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_events_instance_did` ON `events` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_webhook_endpoints_instance_did` ON `webhook_endpoints` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_webhook_attempts_instance_did` ON `webhook_attempts` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_payouts_instance_did` ON `payouts` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_payment_stats_instance_did` ON `payment_stats` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_revenue_snapshots_instance_did` ON `revenue_snapshots` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_auto_recharge_configs_instance_did` ON `auto_recharge_configs` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_tax_rates_instance_did` ON `tax_rates` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_settings_instance_did` ON `settings` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_payment_currencies_instance_did` ON `payment_currencies` (`instance_did`);
+CREATE INDEX IF NOT EXISTS `idx_product_vendors_instance_did` ON `product_vendors` (`instance_did`);

package/cloudflare/migrations/0008_schema_parity.sql

@@ -0,0 +1,16 @@
+-- Phase 11 (W2′) schema parity: close the D1-lineage gaps the schema-drift guard
+-- (scripts/schema-drift-guard.ts) found versus the Umzug canonical schema.
+-- Additive only — safe to apply on a deployed D1 (no drops, no rewrites).
+
+-- events: the Umzug genesis creates `events` with api_version (NOT NULL) and
+-- metadata (JSON); the D1 0001 events table predates both, so the worker could
+-- not write them. Backfill api_version with the app constant
+-- (api/src/libs/audit.ts API_VERSION = '2023-09-05'); new rows carry the same.
+ALTER TABLE `events` ADD COLUMN `api_version` VARCHAR(16) NOT NULL DEFAULT '2023-09-05';
+ALTER TABLE `events` ADD COLUMN `metadata` JSON;
+
+-- Indexes present in the canonical but missing in the D1 lineage (perf parity;
+-- names match the Umzug migrations 20250904-discount / 20251007-relate-tax-rate).
+CREATE INDEX IF NOT EXISTS `idx_discounts_customer_id` ON `discounts` (`customer_id`);
+CREATE INDEX IF NOT EXISTS `idx_invoice_items_tax_rate_id` ON `invoice_items` (`tax_rate_id`);
+CREATE INDEX IF NOT EXISTS `idx_promotion_codes_verification_type_coupon_id` ON `promotion_codes` (`verification_type`, `coupon_id`);

package/cloudflare/migrations/0009_remove_did_space_jobs.sql

@@ -0,0 +1,5 @@
+-- The DID Space billing-mirror integration was removed (libs/did-space.ts,
+-- queues/space.ts). Rows in `jobs` with queue='did-space' can never be picked
+-- up again (the scheduled scan only matches registered queue names), so they
+-- would sit in the table forever. Delete them. Idempotent.
+DELETE FROM jobs WHERE queue = 'did-space';

package/cloudflare/queue-runtime-mode.ts

@@ -0,0 +1,13 @@
+// Phase 12b (W2′): pin the core queue engine to 'workerd' mode.
+//
+// This MUST be imported before any business queue module (api/src/queues/*),
+// because createQueue runs at import time and reads the mode to decide whether
+// to start the node background poll loop(). A frozen CF isolate cannot run a
+// background timer, so the worker disables the loop and drives due-job
+// re-dispatch from scheduled() via the core dispatchDueJobs() surface instead.
+//
+// ESM executes imported module bodies in source order, so importing this first
+// in worker.ts guarantees the mode is set before the engine is constructed.
+import { setQueueRuntimeMode } from '../api/src/libs/queue/runtime';
+
+setQueueRuntimeMode('workerd');

package/cloudflare/run-build.js

@@ -3,59 +3,15 @@ const path = require("path");
 const cfDir = __dirname;
 const s = (f) => path.resolve(cfDir, f);
 
-// Resolve the absolute path of the original queue module so we can intercept it
-const queueModulePath = path.resolve(cfDir, "../api/src/libs/queue/index.ts");
-const queueShimPath = s("shims/queue.ts");
-
-// Resolve the absolute path of the original lock module so we can intercept it
-const lockModulePath = path.resolve(cfDir, "../api/src/libs/lock.ts");
-const lockShimPath = s("shims/lock.ts");
-
-// Plugin to redirect libs/queue to our CF Workers shim
-const queueNormalizedTarget = queueModulePath.replace(/\/index\.ts$/, '').replace(/\/index$/, '');
-const queueShimPlugin = {
-  name: 'queue-shim',
-  setup(build) {
-    // Intercept any import that resolves to the original queue module
-    build.onResolve({ filter: /libs\/queue/ }, (args) => {
-      const resolveDir = args.resolveDir;
-      if (!resolveDir) return undefined;
-
-      // Resolve the relative import to an absolute path
-      const resolved = path.resolve(resolveDir, args.path).replace(/\/index(\.ts)?$/, '');
-      const match = resolved === queueNormalizedTarget;
-      if (args.path.includes('queue')) {
-        console.log(`[queue-shim] ${match ? 'MATCH' : 'skip'}: ${args.path} -> ${resolved} (target: ${queueNormalizedTarget})`);
-      }
-      if (match) {
-        return { path: queueShimPath };
-      }
-      return undefined;
-    });
-  },
-};
-
-// Plugin to redirect libs/lock to our CF Workers D1-based lock shim
-const lockNormalizedTarget = lockModulePath.replace(/\.ts$/, '');
-const lockShimPlugin = {
-  name: 'lock-shim',
-  setup(build) {
-    build.onResolve({ filter: /libs\/lock/ }, (args) => {
-      const resolveDir = args.resolveDir;
-      if (!resolveDir) return undefined;
-
-      const resolved = path.resolve(resolveDir, args.path).replace(/\.ts$/, '');
-      const match = resolved === lockNormalizedTarget;
-      if (args.path.includes('lock')) {
-        console.log(`[lock-shim] ${match ? 'MATCH' : 'skip'}: ${args.path} -> ${resolved} (target: ${lockNormalizedTarget})`);
-      }
-      if (match) {
-        return { path: lockShimPath };
-      }
-      return undefined;
-    });
-  },
-};
+// Phase 12b/12c: the queue-shim (libs/queue -> shims/queue.ts) and lock-shim
+// (libs/lock -> shims/lock.ts) plugins were REMOVED.
+//   - queue-shim: option A makes api/src/libs/queue the ONE queue engine for all
+//     runtimes (the worker drives it via api/src/libs/queue/runtime.ts); the
+//     duplicate shims/queue.ts engine is deleted, so there is nothing to redirect.
+//   - lock-shim: lock became a Phase 8 driver (libs/drivers/locks) and the old
+//     shims/lock.ts no longer exists; the redirect pointed at a deleted file and
+//     was the only thing that broke this script.
+// Everything else below is the original CF deploy-build optimization config.
 
 // Plugin to neutralize rolldown-generated `__require(import.meta.url)` helpers
 // that ship inside npm packages built with rolldown (e.g. @ocap/message,
@@ -216,13 +172,30 @@ const noopPackagesPlugin = {
   },
 };
 
+// Plugin: drop ethers' non-English BIP39 wordlists (~70K dead weight). The payment
+// worker never uses Mnemonic/HD wallets (0 source refs to Mnemonic/HDNode/wordlist),
+// so the 8 non-English word tables never execute. ethers' own /dist build strips
+// these too (~80kb). Keep LangEn (Mnemonic default). Stub the rest with a static
+// wordlist() returning null so wordlists.js's top-level LangXx.wordlist() calls
+// (run at module init) don't crash.
+const dropEthersWordlistsPlugin = {
+  name: 'drop-ethers-wordlists',
+  setup(build) {
+    build.onLoad({ filter: /ethers\/lib\.esm\/wordlists\/lang-(cz|es|fr|ja|ko|it|pt|zh)\.js$/ }, (args) => {
+      const lang = /lang-(\w+)\.js$/.exec(args.path)[1];
+      const cls = 'Lang' + lang.charAt(0).toUpperCase() + lang.slice(1);
+      return { contents: `export class ${cls} { static wordlist() { return null; } }`, loader: 'js' };
+    });
+  },
+};
+
 build({
   entryPoints: [s("worker.ts")],
   bundle: true, format: "esm", platform: "node", target: "esnext",
   outdir: s("dist"), minify: true, sourcemap: true, metafile: true,
   mainFields: ["module", "main"],
   plugins: [
-    noopPackagesPlugin, queueShimPlugin, lockShimPlugin, rolldownRuntimeNoopPlugin, lodashSubpathPlugin,
+    noopPackagesPlugin, rolldownRuntimeNoopPlugin, lodashSubpathPlugin, dropEthersWordlistsPlugin,
   ],
   external: ["cloudflare:*", "__STATIC_CONTENT_MANIFEST"],
   // Give import.meta.url a stable fallback so bundled deps that call
@@ -265,6 +238,10 @@ build({
     // axios → lightweight fetch-based shim (115KB → ~2KB)
     "axios": s("shims/axios-lite.ts"),
 
+    // node-fetch → native fetch (drops encoding/tr46/whatwg-url polyfill ~754KB
+    // pulled in by @apple/app-store-server-library; dead weight on CF Workers)
+    "node-fetch": s("shims/node-fetch.ts"),
+
     // Stripe — wrap constructor to use fetch HTTP client in CF Workers
     "stripe": s("shims/stripe-cf.ts"),
     "__real_stripe__": require.resolve("stripe"),
@@ -282,7 +259,6 @@ build({
     "sqlite3": s("shims/noop.ts"),
     "cls-hooked": s("shims/noop.ts"),
     "express-async-errors": s("shims/noop.ts"),
-    "express": s("shims/express-compat/index.ts"),
     "cors": s("shims/cors.ts"),
     "cookie-parser": s("shims/cookie-parser.ts"),
     "@blocklet/sdk/lib/middlewares/fallback": s("shims/blocklet-sdk/fallback.ts"),
@@ -310,7 +286,6 @@ build({
     "@blocklet/xss": s("shims/xss.ts"),
     "@blocklet/error": s("shims/error.ts"),
     "@blocklet/logger": s("shims/blocklet-sdk/logger.ts"),
-    "@blocklet/did-space-js": s("shims/did-space.ts"),
     "@blocklet/payment-vendor": s("shims/payment-vendor.ts"),
     "@arcblock/did-connect-storage-nedb": s("shims/nedb-storage.ts"),
     "@abtnode/cron": s("shims/cron.ts"),

package/cloudflare/shims/blocklet-sdk/asset-host-transformer.ts

@@ -0,0 +1,20 @@
+// CF shim for @blocklet/sdk/lib/util/asset-host-transformer.
+//
+// DEAD on the CF path: the only importer is the cdn middleware (node-shell only —
+// HTML CDN-URL rewriting on the full node app shell). The worker serves JSON API
+// routes through a LITE app-shell, so cdn never executes. A pass-through stub is
+// enough to resolve the bundled-but-unreachable node code.
+export class AssetHostTransformer {
+  // eslint-disable-next-line @typescript-eslint/no-useless-constructor, no-empty-function
+  constructor(_assetHost?: string) {}
+
+  transform(html: string, _assetHost?: string): string {
+    return html;
+  }
+
+  transformBuffer(body: Buffer | Uint8Array, _assetHost?: string): Buffer | Uint8Array {
+    return body;
+  }
+}
+
+export default { AssetHostTransformer };

package/cloudflare/shims/blocklet-sdk/config.ts

@@ -4,5 +4,12 @@ export { env };
 export const Events = {};
 export const events = { on: () => {}, emit: () => {} };
 
-const config = { env, Events, events };
+// Phase 4 (express→hono): the fallback middleware (SPA serving) reads these. It is
+// node-shell only — DEAD on the CF worker (which never serves the SPA) — so a
+// resolving stub is enough. getBlockletSettings also backs sessionMiddleware's
+// blacklist check, which is gated off on CF (enableBlacklist: false).
+export const getBlockletSettings = (): any => ({ enableBlacklist: false, theme: {} });
+export const getBlockletJs = (..._args: any[]): string => '';
+
+const config = { env, Events, events, getBlockletSettings, getBlockletJs };
 export default config;

package/cloudflare/shims/blocklet-sdk/login.ts

@@ -0,0 +1,12 @@
+// CF shim for @blocklet/sdk/lib/util/login.
+//
+// Reached on the LIVE CF path: sessionMiddleware (used by many resource routes)
+// calls isLoginToken/isAccessKey to classify the bearer token. These are pure
+// string-format checks — copied verbatim from the upstream so behavior matches.
+export const isLoginToken = (token: unknown): boolean =>
+  typeof token === 'string' && token.split('.').length === 3;
+
+export const isAccessKey = (token: unknown): boolean =>
+  typeof token === 'string' && token.split('.').length === 1 && token.startsWith('blocklet-');
+
+export default { isLoginToken, isAccessKey };

package/cloudflare/shims/blocklet-sdk/service-api.ts

@@ -0,0 +1,14 @@
+// CF shim for @blocklet/sdk/lib/util/service-api.
+//
+// The only caller on the CF path is sessionMiddleware's login-token blacklist
+// check, which is gated by `blockletSettings.enableBlacklist` (off on the CF
+// worker — the worker resolves identity via AUTH_SERVICE RPC, not the blacklist
+// endpoint). The old express-compat CF path never ran this check at all, so a
+// stub that reports "valid" preserves the worker's (no-blacklist) behavior and
+// never wrongly blocks a token if the setting is somehow on.
+const serviceApi = {
+  post: async (_url: string, _body?: unknown) => ({ data: { valid: true } }),
+  get: async (_url: string) => ({ data: {} }),
+};
+
+export default serviceApi;

package/cloudflare/shims/blocklet-sdk/session.ts

@@ -1,6 +1,8 @@
 // @blocklet/sdk/lib/middlewares/session shim
-// Auth is resolved in Hono middleware layer via AUTH_SERVICE RPC.
-// req.user is already populated by mountExpressRoutes().
+// Auth is resolved in the Hono middleware layer via AUTH_SERVICE RPC, then injected
+// as x-user-* request headers by the worker's /api/* dispatcher (worker.ts) — the
+// native authenticate()/sessionMiddleware read those. This express-middleware shim
+// is inert (the old express-compat mountExpressRoutes path it served is gone).
 export default function sessionMiddleware(_options?: any) {
   return (_req: any, _res: any, next: any) => next();
 }

package/cloudflare/shims/blocklet-sdk/util-constants.ts

@@ -0,0 +1,8 @@
+// CF shim for @blocklet/sdk/lib/util/constants.
+//
+// Reached via the fallback middleware (node-shell SPA serving — DEAD on the CF
+// worker, which never serves the SPA). SERVICE_PREFIX carries its real upstream
+// value so the bundled-but-unreachable node code is byte-faithful.
+export const SERVICE_PREFIX = '/.well-known/service';
+
+export default { SERVICE_PREFIX };

package/cloudflare/shims/blocklet-sdk/util-csrf.ts

@@ -0,0 +1,13 @@
+// CF shim for @blocklet/sdk/lib/util/csrf.
+//
+// DEAD on the CF path: the csrf middleware (middlewares/hono/csrf) lives only on
+// the NODE app-shell pipeline (service.ts buildHonoApp / configureNativePipeline,
+// reached via getHonoApp). The CF worker mounts a LITE app-shell (xss only) and
+// owns its own cors, so csrf never executes on the worker. These stubs exist only
+// so esbuild can resolve the import in the bundled-but-unreachable node code.
+export const getCsrfSecret = (): string => '';
+export const sign = (_secret: string, _value: string): string => '';
+export const verify = (_secret: string, _value: string, _token: string): boolean => false;
+export const hmac = (_secret: string, _value: string): string => '';
+
+export default { getCsrfSecret, sign, verify, hmac };

package/cloudflare/shims/blocklet-sdk/util-wallet.ts

@@ -0,0 +1,8 @@
+// CF shim for @blocklet/sdk/lib/util/wallet.
+//
+// DEAD on the CF path: the only importer is the csrf middleware (node-shell only;
+// see util-csrf.ts), which reads isDidWalletConnect to skip csrf for DID-wallet
+// requests. Never executes on the worker — a resolving stub is enough.
+export const isDidWalletConnect = (_userAgent?: string): boolean => false;
+
+export default { isDidWalletConnect };

package/cloudflare/shims/cron.ts

@@ -1,182 +1,62 @@
-// @abtnode/cron shim for CF Cron Triggers
+// @abtnode/cron shim for CF Cron Triggers (Phase 9, W2-1b).
 //
-// The real @abtnode/cron exports { init } where init({ context, jobs, onError }) registers jobs.
-// In CF Workers, we store the jobs and execute them via the scheduled() handler.
-//
-// The shim parses 6-field cron expressions (sec min hour day month weekday)
-// and only runs jobs whose schedule matches the current 5-minute window.
-
-type CronJob = {
-  name: string;
-  time: string;
-  fn: () => Promise<any> | any;
-  options?: { runOnInit?: boolean };
-};
+// The real @abtnode/cron exports { init } where init({ jobs, onError }) registers
+// jobs. In CF Workers we store the jobs and execute due ones from scheduled().
+// The cron-expression matcher + registry now live in the shared cron driver
+// (api/src/libs/drivers/cron.ts) so embedded and worker agree on when a job is
+// due; this file is the thin worker adapter that keeps the @abtnode/cron API.
+
+import {
+  createCronRegistry,
+  setCronDriver,
+  getCronDriver,
+  matchesCron,
+  shouldRunInWindow,
+} from '../../api/src/libs/drivers/cron';
+
+// D2: crons/index.ts now registers through getCronDriver() instead of importing
+// @abtnode/cron directly. On CF this shim is the active cron driver, so make the
+// cf-cron registry the global driver at module load — BEFORE worker.ts calls
+// crons.init(). That keeps crons.init()'s register() and this shim's runAll() on
+// the SAME passive cf-cron registry (host drives runDue from scheduled(); no
+// @abtnode/cron self-scheduling timer is ever created in the frozen isolate).
+const registry = createCronRegistry('cf-cron');
+setCronDriver(registry);
 
 type InitOptions = {
   context?: any;
-  jobs: CronJob[];
+  jobs: Array<{ name: string; time: string; fn: () => Promise<any> | any; options?: { runOnInit?: boolean } }>;
   onError?: (error: Error, name: string) => void;
 };
 
-// Singleton storage for registered cron jobs
-const registeredJobs: CronJob[] = [];
-let onErrorHandler: ((error: Error, name: string) => void) | undefined;
-
-// --- Cron expression matcher ---
-// Supports 6-field format: second minute hour dayOfMonth month dayOfWeek
-// Supports: numbers, *, */N, ranges (1-5), lists (1,3,5)
-
-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(',')) {
-    // */N — every N
-    const stepMatch = part.match(/^\*\/(\d+)$/);
-    if (stepMatch) {
-      const step = parseInt(stepMatch[1], 10);
-      for (let i = min; i <= max; i += step) {
-        values.add(i);
-      }
-      continue;
-    }
-
-    // N-M — range
-    const rangeMatch = part.match(/^(\d+)-(\d+)$/);
-    if (rangeMatch) {
-      const from = parseInt(rangeMatch[1], 10);
-      const to = parseInt(rangeMatch[2], 10);
-      for (let i = from; i <= to; i++) {
-        values.add(i);
-      }
-      continue;
-    }
-
-    // N — single value
-    const num = parseInt(part, 10);
-    if (!isNaN(num)) {
-      values.add(num);
-    }
-  }
-
-  return values.size > 0 ? Array.from(values) : null;
-}
-
-/**
- * Check if a date matches a 6-field cron expression.
- * Returns true if the date's minute/hour/day/month/weekday match.
- * Seconds field is ignored (CF triggers are minute-level).
- */
-function matchesCron(cronExpr: string, date: Date): boolean {
-  const fields = cronExpr.trim().split(/\s+/);
-  if (fields.length < 5) return true; // Can't parse — run it
-
-  // 6-field: sec min hour dom month dow
-  // 5-field: min hour dom month dow
-  const offset = fields.length >= 6 ? 1 : 0;
-
-  const minuteField = parseField(fields[offset], 0, 59);
-  const hourField = parseField(fields[offset + 1], 0, 23);
-  const domField = parseField(fields[offset + 2], 1, 31);
-  const monthField = parseField(fields[offset + 3], 0, 11); // cron months are 1-12, JS is 0-11
-  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(); // 0=Sunday
-
-  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;
-}
-
-// Check if a cron expression should fire at the given date (minute-level match).
-//
-// History: this helper previously used a 5-minute look-ahead window, under the
-// assumption that CF Cron Triggers fire every 5 minutes. Once the deploy config
-// switched to every-minute cron, that window made every stepped expression fire
-// 5x more often than intended, driving CF Queues past the free-tier daily cap
-// (2026-04-17 incident). With CF Scheduled firing every minute, we only check
-// the current minute — each cron expression triggers at its designed frequency.
-// See docs/cf-queues-ops-alert-analysis.md § 改动 B.
-function shouldRunInWindow(cronExpr: string, date: Date): boolean {
-  return matchesCron(cronExpr, date);
-}
-
-// --- Cron shim API ---
-
 function init(options: InitOptions) {
-  registeredJobs.length = 0;
-  onErrorHandler = options.onError;
-
-  for (const job of options.jobs || []) {
-    if (job.name && job.time && typeof job.fn === 'function') {
-      registeredJobs.push(job);
-    }
-  }
-
-  // Skip runOnInit jobs in CF Workers — they'll run on the next matching trigger
-  // (running them at module init time would block the request and may exceed CPU limits)
-
+  registry.register(options.jobs || [], options.onError);
+  // runOnInit jobs are skipped in CF Workers — they run on the next matching
+  // trigger (running them at module init would block the request / risk CPU limits)
   return {
     addJob(name: string, time: string, fn: Function, opts?: any) {
-      registeredJobs.push({ name, time, fn: fn as any, options: opts });
+      registry.addJob(name, time, fn as any, opts);
+    },
+    start() {
+      /* no-op — CF scheduled() drives runAll */
     },
-    start() { /* no-op */ },
   };
 }
 
-// Called by worker.ts scheduled handler — only runs jobs matching the trigger time.
-// Accepts an optional `now` so the caller can pass `event.scheduledTime` (the
-// intended trigger minute) instead of relying on wall-clock at execution time.
-// CF may deliver scheduled events with a small delay that crosses a minute
-// boundary; matching on `scheduledTime` keeps exact-minute cron reliable.
+// Called by worker.ts scheduled handler. Accepts an optional `now` so the caller
+// can pass `event.scheduledTime` (the intended trigger minute).
 async function runAll(now: Date = new Date()) {
-  const matched: string[] = [];
-  const skipped: string[] = [];
-
-  for (const job of registeredJobs) {
-    if (shouldRunInWindow(job.time, now)) {
-      matched.push(job.name);
-      try {
-        await job.fn();
-      } catch (err: any) {
-        console.error(`[Cron] ${job.name} failed:`, err?.message || err);
-        onErrorHandler?.(err, job.name);
-      }
-    } else {
-      skipped.push(job.name);
-    }
-  }
-
-  console.log(`[Cron] Ran ${matched.length} jobs: [${matched.join(', ')}]. Skipped ${skipped.length}.`);
+  const { ran, skipped } = await getCronDriver().runDue(now);
+  // eslint-disable-next-line no-console
+  console.log(`[Cron] Ran ${ran.length} jobs: [${ran.join(', ')}]. Skipped ${skipped.length}.`);
 }
 
 async function runJob(name: string) {
-  const job = registeredJobs.find((j) => j.name === name);
-  if (job) {
-    try {
-      await job.fn();
-    } catch (err: any) {
-      console.error(`[Cron] ${name} failed:`, err?.message || err);
-      onErrorHandler?.(err, name);
-    }
-  } else {
-    console.warn(`[Cron] Job ${name} not found`);
-  }
+  await getCronDriver().runJob(name);
 }
 
 function getJobNames(): string[] {
-  return registeredJobs.map((j) => `${j.name} (${j.time})`);
+  return getCronDriver().getJobNames();
 }
 
 // Export matching @abtnode/cron API: default export is { init }