payment-kit 1.29.2 → 1.29.3

package/api/src/queues/payment.ts

@@ -7,6 +7,7 @@ import { ensureStakedForGas } from '../integrations/arcblock/stake';
 import { transferErc20FromUser } from '../integrations/ethereum/token';
 import { createEvent, reportAuditFailure } from '../libs/audit';
 import { blocklet, wallet } from '../libs/auth';
+import { withTenant } from '../libs/context';
 import dayjs from '../libs/dayjs';
 import CustomError from '../libs/error';
 import { events } from '../libs/event';
@@ -1379,16 +1380,29 @@ export const startPaymentQueue = async () => {
     },
   });
 
-  payments.forEach(async (x) => {
-    const supportAutoCharge = await PaymentMethod.supportAutoCharge(x.payment_method_id);
-    if (supportAutoCharge === false) {
-      return;
-    }
-    const exist = await paymentQueue.get(x.id);
-    if (!exist) {
-      paymentQueue.push({ id: x.id, job: { paymentIntentId: x.id } });
+  // Each pending intent belongs to a tenant: the scoped supportAutoCharge query
+  // and the queue push (push stamps the job tenant via getInstanceDid) must run in
+  // that tenant's context — multi mode fails closed otherwise. for-of + await,
+  // NOT forEach(async): a fire-and-forget rejection here becomes an
+  // unhandledRejection → FATAL on boot. Per-record try/catch isolates one bad row.
+  for (const x of payments) {
+    const dispatch = async () => {
+      const supportAutoCharge = await PaymentMethod.supportAutoCharge(x.payment_method_id);
+      if (supportAutoCharge === false) {
+        return;
+      }
+      const exist = await paymentQueue.get(x.id);
+      if (!exist) {
+        paymentQueue.push({ id: x.id, job: { paymentIntentId: x.id } });
+      }
+    };
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await (x.instance_did ? withTenant(x.instance_did, dispatch) : dispatch());
+    } catch (error) {
+      logger.error('startPaymentQueue: re-queue failed', { id: x.id, error });
     }
-  });
+  }
 };
 
 paymentQueue.on('failed', ({ id, job, error }) => {

package/api/src/queues/payout.ts

@@ -4,6 +4,7 @@ import logger from '../libs/logger';
 import { getGasPayerExtra } from '../libs/payment';
 import createQueue, { assertJobObjectTenant } from '../libs/queue';
 import { wallet, ethWallet } from '../libs/auth';
+import { withTenant } from '../libs/context';
 import { sendErc20ToUser } from '../integrations/ethereum/token';
 import { PaymentMethod } from '../store/models/payment-method';
 import { PaymentCurrency } from '../store/models/payment-currency';
@@ -244,24 +245,35 @@ export const startPayoutQueue = async () => {
     },
   });
 
-  payouts.forEach(async (payout) => {
-    const exist = await payoutQueue.get(payout.id);
-    if (!exist) {
-      // Use next attempt time if set
-      if (payout.next_attempt && payout.next_attempt > dayjs().unix()) {
-        payoutQueue.push({
-          id: payout.id,
-          job: { payoutId: payout.id, retryOnError: true },
-          runAt: payout.next_attempt,
-        });
-      } else {
-        payoutQueue.push({
-          id: payout.id,
-          job: { payoutId: payout.id, retryOnError: true },
-        });
+  // Per-record tenant context: queue push stamps the job tenant via getInstanceDid,
+  // which fails closed in multi mode without it. for-of + await (not forEach(async),
+  // which leaks an unhandledRejection → FATAL on boot); per-record catch isolates.
+  for (const payout of payouts) {
+    const dispatch = async () => {
+      const exist = await payoutQueue.get(payout.id);
+      if (!exist) {
+        // Use next attempt time if set
+        if (payout.next_attempt && payout.next_attempt > dayjs().unix()) {
+          payoutQueue.push({
+            id: payout.id,
+            job: { payoutId: payout.id, retryOnError: true },
+            runAt: payout.next_attempt,
+          });
+        } else {
+          payoutQueue.push({
+            id: payout.id,
+            job: { payoutId: payout.id, retryOnError: true },
+          });
+        }
       }
+    };
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await (payout.instance_did ? withTenant(payout.instance_did, dispatch) : dispatch());
+    } catch (error) {
+      logger.error('startPayoutQueue: re-queue failed', { id: payout.id, error });
     }
-  });
+  }
 };
 
 // Listen for newly created payouts

package/api/src/queues/refund.ts

@@ -3,6 +3,7 @@ import { isRefundReasonSupportedByStripe } from '../libs/refund';
 import { checkRemainingStake, getSubscriptionStakeAddress } from '../libs/subscription';
 import { sendErc20ToUser } from '../integrations/ethereum/token';
 import { wallet } from '../libs/auth';
+import { withTenant } from '../libs/context';
 import CustomError, { NonRetryableError } from '../libs/error';
 import { events } from '../libs/event';
 import logger from '../libs/logger';
@@ -493,13 +494,24 @@ export const refundQueue = createQueue<RefundJob>({
 
 export const startRefundQueue = async () => {
   const refunds = await systemFindAll(Refund, { where: { status: ['pending'] } });
-  refunds.forEach(async (x) => {
-    const exist = await refundQueue.get(x.id);
-    if (!exist) {
-      refundQueue.push({ id: x.id, job: { refundId: x.id } });
-      logger.info('Re-queued pending refund', { id: x.id });
+  // Per-record tenant context: queue push stamps the job tenant via getInstanceDid,
+  // which fails closed in multi mode without it. for-of + await (not forEach(async),
+  // which leaks an unhandledRejection → FATAL on boot); per-record catch isolates.
+  for (const x of refunds) {
+    const dispatch = async () => {
+      const exist = await refundQueue.get(x.id);
+      if (!exist) {
+        refundQueue.push({ id: x.id, job: { refundId: x.id } });
+        logger.info('Re-queued pending refund', { id: x.id });
+      }
+    };
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await (x.instance_did ? withTenant(x.instance_did, dispatch) : dispatch());
+    } catch (error) {
+      logger.error('startRefundQueue: re-queue failed', { id: x.id, error });
     }
-  });
+  }
 };
 
 refundQueue.on('failed', ({ id, job, error }) => {

package/api/src/routes/hono/customers.ts

@@ -5,7 +5,12 @@
 import { Hono } from 'hono';
 import Joi from 'joi';
 import pick from 'lodash/pick';
-import isEmail from 'validator/es/lib/isEmail';
+// Use the CommonJS build (`lib`), not the ESM `es` build: `es/lib/isEmail.js`
+// uses extensionless relative imports (`./util/assertString`) that Node ESM
+// strict resolution rejects with ERR_MODULE_NOT_FOUND when payment-core is
+// embedded in a Node host like arc. The `lib` build is plain CJS and resolves
+// everywhere. Same default export.
+import isEmail from 'validator/lib/isEmail';
 
 import { Op, type WhereOptions } from 'sequelize';
 import { BN } from '@ocap/util';

package/api/src/routes/hono/refunds.ts

@@ -11,7 +11,6 @@ import { Hono } from 'hono';
 import Joi from 'joi';
 import pick from 'lodash/pick';
 
-import { getWallet } from '@blocklet/sdk/lib/wallet';
 import { Op } from 'sequelize';
 import { sendErc20ToUser } from '../../integrations/ethereum/token';
 import {
@@ -498,8 +497,8 @@ app.post('/sync', authAdmin, async (c: any) => {
       }
     }
 
-    // Get system DID as default payer (发款方)
-    const systemDid = getWallet().address;
+    // Get system DID as default payer (发款方) — the active tenant's business wallet.
+    const systemDid = wallet.address;
 
     // Create mock customer if customerName is provided, otherwise use "Broker" as default
     const finalCustomerName = customerName || 'Broker';

package/api/src/service.ts

@@ -1,16 +1,15 @@
 /* eslint-disable global-require, max-classes-per-file */
-import path from 'path';
-
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { CustomError, formatError, getStatusFromError } from '@blocklet/error';
 import { Hono } from 'hono';
 import type { ContentfulStatusCode } from 'hono/utils/http-status';
-import { isProduction, blockletAppDir } from './libs/env';
+import { isProduction } from './libs/env';
 
 import logger from './libs/logger';
 import { context as requestContext } from './libs/context';
 import { TENANT_CONTEXT_MISSING, TenantError, getTenantMode, getDefaultInstanceDid } from './libs/tenant';
 import type { LocksDriver, QueueHostHooks, CronDriver, IdentityDriver, SecretsDriver } from './libs/drivers';
+import type { DidConnectTokenStorage, DidConnectRuntime } from './libs/auth';
 import type { PaymentFetchOptions, FetchHandler } from './libs/http-fetch-adapter';
 
 export type { PaymentFetchOptions } from './libs/http-fetch-adapter';
@@ -56,6 +55,30 @@ export interface PaymentCoreSlots {
   identity?: IdentityDriver;
   secrets?: SecretsDriver;
   tenancy?: TenancySlot;
+  /**
+   * S3-CF Phase 1 inversion ③: a host-provided DID-Connect token storage (same
+   * reversal as db/queue/cron). The CF worker injects a D1-backed store so the
+   * token handshake state lands in PAYMENT_DB (strongly consistent); node hosts
+   * omit it and keep the file-backed nedb default. The 14 DID-Connect handler
+   * routes are unchanged — only the persistence backend swaps.
+   */
+  storage?: DidConnectTokenStorage;
+  /**
+   * S3-CF (DID convergence): the host-injected DID-Connect runtime (the host
+   * injection entry). blocklet-server injects createBlockletServerDidConnectRuntime
+   * (@blocklet/sdk wrapper); CF + arc-node embedded inject the real
+   * @arcblock/did-connect-js runtime (AUTH_SERVICE identity + host tokenStorage).
+   * Takes precedence over `storage` (the runtime carries its own tokenStorage).
+   */
+  didConnectRuntime?: DidConnectRuntime;
+  /**
+   * S3-CF Phase 1 inversion ①: a host-provided static/SPA handler wired onto the
+   * full node hono app AFTER the api/connect routes. The node blocklet-server host
+   * injects host-node/serve-static's `attachNodeStatic` to replicate today's SPA
+   * serving; the CF/standalone worker serves assets via env.ASSETS and omits this,
+   * keeping the runtime-neutral `http.fetch` free of node:fs.
+   */
+  staticHandler?: (app: Hono) => void;
 }
 
 export interface PaymentCoreLifecycle {
@@ -75,9 +98,11 @@ export interface PaymentCoreService {
   handler: Hono;
   /**
    * The embeddable HTTP surface for hosts that own their own app shell. The CF
-   * worker mounts `resourceRoutes` into its Hono pipeline (Option 3 seam:
-   * resource routes only — no app shell static/fallback, no DID-Connect
-   * handlers, which the worker registers via its own Hono `attachDIDConnectRoutes`).
+   * worker mounts `resourceRoutes` into its Hono pipeline (Option 3 seam: resource
+   * routes only — no app shell static/fallback, no DID-Connect handlers). S3-CF
+   * (DID convergence): the worker now mounts the 14 payment DID actions from the
+   * shared core `buildConnectRoutesHono` (backed by the injected CF DID-Connect
+   * runtime), not a private surface.
    * Phase 4: a hono app (`/api/healthz` + the migrated resource domains, each
    * scoped to its own app-shell pipeline), mounted by the worker via `app.route`.
    */
@@ -108,6 +133,17 @@ export interface PaymentCoreService {
    * bootstraps the default tenant from lifecycle.start automatically).
    */
   bootstrapTenant: (instanceDid: string) => Promise<void>;
+  /**
+   * Idempotent per-tenant base-data provisioning: seeds the default ArcBlock
+   * payment methods (main + beta) and their base currencies, scoped to the
+   * tenant's instanceDid. The single-tenant `20230911-seeding` migration writes
+   * these with NO instance_did, so they are invisible to multi-tenant queries;
+   * a multi-tenant host calls this per tenant (e.g. lazily on first request) so
+   * the tenant has the payment method/currency every downstream entity (meters,
+   * products, prices, subscriptions) depends on. No secrets / no chain calls —
+   * pure records. Skips if the tenant already has an arcblock method.
+   */
+  provisionTenant: (instanceDid: string) => Promise<void>;
 }
 
 /**
@@ -229,6 +265,22 @@ function connectHandlerModules(): any[] {
 export function buildConnectRoutesHono(): Hono {
   const { handlers } = require('./libs/auth');
   const connectApp = new Hono();
+
+  // S3-CF (DID convergence) F: a LIGHTWEIGHT tenant-context-only middleware — NOT
+  // the full resource pipeline (no cors/xss/csrf/i18n/cdn; DID-Connect carries its
+  // own ensureSignedJson and did-connect-js registers its own CORS). The CF / AUTH_
+  // SERVICE runtimes resolve the per-tenant signing identity + scope the token store
+  // by the TenantContext instanceDid, so every DID route must run inside one. If the
+  // host already established a context (e.g. the CF worker wrapped /api/* in
+  // withTenant) we pass through; otherwise we resolve Host→tenant once and wrap.
+  connectApp.use('*', async (c, next) => {
+    const { context: requestCtx } = require('./libs/context');
+    if (requestCtx.peekInstanceDid()) return next();
+    const { resolveTenantForHost } = require('./libs/drivers/identity');
+    const instanceDid = await resolveTenantForHost(c.req.header('host'));
+    return requestCtx.withTenant(instanceDid, () => next());
+  });
+
   for (const h of connectHandlerModules()) handlers.attach(Object.assign({ app: connectApp }, h));
   return connectApp;
 }
@@ -245,15 +297,20 @@ export function buildConnectRoutesHono(): Hono {
  *                    populated by `configureNative`.
  *   ③ connectApp   — the DID-Connect sub-app, mounted alongside `native` (NOT under
  *                    it — it carries its own ensureSignedJson, no xss/csrf/cors).
- *   ④ static + SPA fallback (production only) — what the express buildNodeHandler
- *                    served; now hono-native. `fallback` runs first and skips asset
- *                    paths (RESOURCE_PATTERN) + non-html, so real files fall through
- *                    to serveStatic and html navigations get the injected index.html.
- *
- * Static/fallback modules are required lazily so importing this module stays
- * side-effect-free for the workerd host (which never builds this app).
+ *   ④ host static + SPA fallback (optional) — S3-CF Phase 1 inversion ①: the
+ *                    node-only static/SPA shell is no longer wired HERE (that kept
+ *                    `http.fetch` node-bound). The HOST injects `attachStatic`
+ *                    (node blocklet-server replicates today's serving via
+ *                    host-node/serve-static; the CF/standalone worker serves assets
+ *                    via env.ASSETS and injects nothing). Absent → the app serves
+ *                    no static and carries ZERO node:fs, so node, CF, and the
+ *                    standalone worker share this one surface.
  */
-export function buildHonoApp(configureNative?: (native: Hono) => void, getConnectApp?: () => Hono): Hono {
+export function buildHonoApp(
+  configureNative?: (native: Hono) => void,
+  getConnectApp?: () => Hono,
+  attachStatic?: (app: Hono) => void
+): Hono {
   const app = new Hono();
 
   // Unified error handling — the hono equivalent of express-async-errors + the
@@ -279,19 +336,10 @@ export function buildHonoApp(configureNative?: (native: Hono) => void, getConnec
     app.route('/', getConnectApp()); // ③ DID-Connect
   }
 
-  // ④ production static + SPA fallback (the express buildNodeHandler served these;
-  //    there is no more bridge to delegate to). Lazily required to keep this
-  //    module import side-effect-free for the workerd host.
-  if (isProduction()) {
-    const { serveStatic } = require('@hono/node-server/serve-static');
-    const { fallback } = require('./middlewares/hono/fallback');
-    const staticDir = path.resolve(blockletAppDir()!, 'dist');
-    // serveStatic resolves `root` relative to process.cwd(); map the absolute
-    // app dist dir back to a cwd-relative path so it resolves to the same place.
-    const staticRoot = path.relative(process.cwd(), staticDir) || '.';
-    app.use('*', fallback('index.html', { root: staticDir })); // injected index.html for html GET (skips assets)
-    app.use('*', serveStatic({ root: staticRoot })); // real asset files
-  }
+  // ④ host-provided static + SPA fallback, wired LAST (after api/connect routes)
+  //    so real routes win and only unmatched html navigations hit the fallback.
+  //    The node:fs implementation lives in host-node/serve-static (node-only).
+  attachStatic?.(app);
 
   return app;
 }
@@ -363,11 +411,17 @@ async function bootstrapTenant(instanceDid: string): Promise<void> {
   const { ensureWebhookRegistered } = require('./integrations/stripe/setup');
   const { ensureCreateOverdraftProtectionPrices } = require('./libs/overdraft-protection');
   const { scheduleHealthChecks } = require('./queues/exchange-rate-health');
+  const { warmTenantIdentity } = require('./libs/did-connect/tenant-identity');
 
   // Run the whole bootstrap inside the tenant context. We AWAIT each op so its
   // async continuation stays in-scope (a fire-and-forget would lose the ALS
   // context after the callback returns).
   await requestContext.withTenant(instanceDid, async () => {
+    // Warm the tenant's signing identity first — the lifecycle analog of the
+    // HTTP/queue warm. ensureStakedForGas reads `wallet.address` synchronously;
+    // without a warmed cache it fails-closed on the AUTH_SERVICE runtimes (no-op
+    // on blocklet-server). Best-effort, like the other bootstrap steps.
+    await warmTenantIdentity(instanceDid);
     await Promise.resolve(syncCurrencyLogo()).catch((error: unknown) =>
       logger.error('bootstrapTenant: syncCurrencyLogo failed', { instanceDid, error })
     );
@@ -387,6 +441,76 @@ async function bootstrapTenant(instanceDid: string): Promise<void> {
   });
 }
 
+// Per-tenant analog of the single-tenant `20230911-seeding` migration: that
+// migration bulk-inserts the default ArcBlock methods/currencies with NO
+// instance_did, so they are invisible to a multi-tenant query. This recreates
+// them scoped to one tenant. Mirrors the proven create order in
+// routes/hono/payment-methods.ts (method → currency → method.default_currency_id).
+async function provisionTenant(instanceDid: string): Promise<void> {
+  if (!instanceDid || typeof instanceDid !== 'string') {
+    throw new TenantError(TENANT_CONTEXT_MISSING, 'provisionTenant requires an instanceDid');
+  }
+  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+  const { fromTokenToUnit } = require('@ocap/util');
+  const { PaymentMethod, PaymentCurrency } = require('./store/models');
+
+  const CHAINS = [
+    { chainId: 'main', livemode: true, symbol: 'ABT', label: 'ArcBlock Main', contract: 'z35nNRvYxBoHitx9yZ5ATS88psfShzPPBLxYD' },
+    { chainId: 'beta', livemode: false, symbol: 'TBA', label: 'ArcBlock Beta', contract: 'z35n6UoHSi9MED4uaQy6ozFgKPaZj2UKrurBG' },
+  ];
+
+  await requestContext.withTenant(instanceDid, async () => {
+    // Idempotent: a tenant that already has an arcblock method is provisioned.
+    const existing = await PaymentMethod.findOne({ where: { type: 'arcblock' } });
+    if (existing) return;
+
+    for (const chain of CHAINS) {
+      const logo = '/methods/arcblock.png';
+      const method = await PaymentMethod.create({
+        instance_did: instanceDid,
+        active: true,
+        livemode: chain.livemode,
+        locked: true,
+        type: 'arcblock',
+        name: chain.label,
+        description: `Process payments with tokens on ArcBlock ${chain.chainId} chain`,
+        logo,
+        confirmation: { type: 'immediate' },
+        settings: {
+          arcblock: {
+            chain_id: chain.chainId,
+            api_host: `https://${chain.chainId}.abtnetwork.io/api/`,
+            explorer_host: `https://${chain.chainId}.abtnetwork.io/explorer/`,
+          },
+        },
+        features: { recurring: true, refund: true, dispute: false },
+        metadata: {},
+      });
+      const currency = await PaymentCurrency.create({
+        instance_did: instanceDid,
+        active: true,
+        livemode: chain.livemode,
+        locked: true,
+        is_base_currency: true,
+        payment_method_id: method.id,
+        type: 'standard',
+        name: chain.symbol,
+        description: chain.symbol,
+        logo,
+        symbol: chain.symbol,
+        decimal: 18,
+        minimum_payment_amount: fromTokenToUnit(0.1, 18).toString(),
+        maximum_precision: 6,
+        maximum_payment_amount: fromTokenToUnit(100000000, 18).toString(),
+        contract: chain.contract,
+        metadata: {},
+      });
+      await method.update({ default_currency_id: currency.id });
+    }
+    logger.info('provisionTenant: seeded arcblock payment methods + currencies', { instanceDid });
+  });
+}
+
 async function startBackgroundServices(): Promise<void> {
   if (servicesStarted) {
     logger.info('payment core background services already started, skipping');
@@ -544,6 +668,12 @@ export function createEmbeddedPaymentService(slots: PaymentCoreSlots): EmbeddedP
 
   // model binding — only after validation passed (no partial init)
   const { initialize } = require('./store/models');
+  // Make the default-export `sequelize` resolve to the host instance too, so code
+  // that imports it directly (Price.expand's `sequelize.models.Product`, etc.) hits
+  // the SAME instance the models bind to — in a bare host the default would
+  // otherwise build a broken sqlite from an undefined data dir.
+  const { setDefaultSequelize } = require('./store/sequelize');
+  setDefaultSequelize(slots.db.sequelize);
   initialize(slots.db.sequelize);
 
   // locks slot (Phase 8): inject the locks driver if the host provides one;
@@ -567,6 +697,17 @@ export function createEmbeddedPaymentService(slots: PaymentCoreSlots): EmbeddedP
   // (single key — Blocklet Server unchanged, existing ciphertext decryptable).
   if (slots.secrets) setSecretsDriver(slots.secrets);
 
+  // DID-Connect runtime + storage slots (S3-CF DID convergence): the host injects
+  // its runtime (blocklet-server: SDK wrapper; CF/arc-node: real
+  // @arcblock/did-connect-js) and/or a token store. Set before buildConnectRoutesHono
+  // materializes `handlers`. The runtime is the primary host-injection entry; the
+  // storage-only slot remains for hosts that keep the default authenticator/handlers.
+  if (slots.didConnectRuntime || slots.storage) {
+    const { setDidConnectRuntime, setDidConnectTokenStorage } = require('./libs/auth');
+    if (slots.didConnectRuntime) setDidConnectRuntime(slots.didConnectRuntime);
+    if (slots.storage) setDidConnectTokenStorage(slots.storage);
+  }
+
   // identity slot (Phase 10): the host injects a Host->tenant resolver for
   // multi-tenant; the default driver resolves every host to the deployment app
   // DID (single mode, unchanged Blocklet Server behavior).
@@ -611,10 +752,15 @@ export function createEmbeddedPaymentService(slots: PaymentCoreSlots): EmbeddedP
     const { configureNativePipeline, fullPipeline } = require('./middlewares/hono/pipeline');
     // eslint-disable-next-line global-require
     const { mountMigratedResources } = require('./routes/hono');
-    return buildHonoApp((native: Hono) => {
-      configureNativePipeline(native); // forked app-shell middleware (+ test stub)
-      mountMigratedResources(native, { appShell: fullPipeline() }); // full app-shell on the node host
-    }, getConnectRoutesHono);
+    return buildHonoApp(
+      (native: Hono) => {
+        configureNativePipeline(native); // forked app-shell middleware (+ test stub)
+        mountMigratedResources(native, { appShell: fullPipeline() }); // full app-shell on the node host
+      },
+      getConnectRoutesHono,
+      // S3-CF Phase 1 ①: host-provided static/SPA shell (node injects it; CF omits).
+      slots.staticHandler
+    );
   });
   // D5: the base-strip Fetch adapter wraps the full hono app (arc consumer). Lazy
   // require + memo so the adapter is built only on the first http.fetch call.
@@ -663,5 +809,6 @@ export function createEmbeddedPaymentService(slots: PaymentCoreSlots): EmbeddedP
     rpc,
     lifecycle,
     bootstrapTenant,
+    provisionTenant,
   };
 }

package/api/src/store/sequelize.ts

@@ -61,7 +61,22 @@ const getSequelize = (): Sequelize => {
   return instance;
 };
 
-// eslint-disable-next-line import/prefer-default-export
+/**
+ * Point the default-export `sequelize` at the host-injected instance. In a bare
+ * host (arc embedding, no BLOCKLET_DATA_DIR) the default export is a deferred
+ * Proxy whose `buildSequelize()` would crash on `join(undefined, …)`; the host
+ * binds every model to ITS OWN sequelize via `initialize(slots.db.sequelize)`.
+ * Code that imports this default directly (e.g. `sequelize.models.Product` in
+ * Price.expand) must therefore resolve to that SAME instance — otherwise it
+ * builds the broken default. The factory calls this at the single bind point so
+ * the imported default and the model-bound instance are always one object.
+ * Equivalent to a no-op for blocklet-server/CF, where the default is already the
+ * bind target.
+ */
+export function setDefaultSequelize(seq: Sequelize): void {
+  instance = seq;
+}
+
 export const sequelize: Sequelize = env.dataDir
   ? getSequelize()
   : new Proxy({} as Sequelize, {