payment-kit 1.29.1 → 1.29.3

package/api/src/service.ts

@@ -0,0 +1,814 @@
+/* eslint-disable global-require, max-classes-per-file */
+// 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 } 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';
+
+// Phase 7 (W2-0): the embedded payment service factory.
+//
+// Assembly happens HERE (factory call time), never at module import time —
+// the blocklet server shell (./index.ts) listens itself and calls
+// lifecycle.start(); other hosts (arc, standalone worker) mount `handler`
+// under their own prefix and own the lifecycle explicitly.
+//
+// Slot semantics in this phase: validated and carried, with implementations
+// passing through to the current internals (db -> the global sequelize
+// instance, queue/cron/locks -> existing libs). The `config` slot is now
+// authoritative (Phase 8 W2′): setCoreConfig makes the injected config the
+// source of truth for every core read via the libs/env.ts boundary, with
+// process.env as the fallback; the api/src core-env whitelist is zero. NOTE:
+// two factory calls in one process still share the module-level singletons
+// (models, sequelize, queues) — documented transition state, not the end contract.
+
+export type TenancySlot =
+  | { mode: 'single'; instanceDid: string }
+  | {
+      mode: 'multi';
+      /**
+       * D6 (optional): a host-provided enumeration of all known tenant
+       * instanceDids. When given, start() bootstraps each at startup; otherwise
+       * the host drives bootstrapTenant() per tenant (e.g. on first request).
+       * This is the ONLY sanctioned tenant-registry hook — the IdentityDriver
+       * (host->tenant + getAppEk) must not be repurposed for enumeration.
+       */
+      listInstanceDids?: () => Promise<string[]> | string[];
+    };
+
+export interface PaymentCoreSlots {
+  /** all runtime configuration, explicit (Phase 12 makes this exhaustive) */
+  config: Record<string, any>;
+  /** SQL driver slot — currently the sequelize instance to bind models to */
+  db: { sequelize: any };
+  queue?: QueueHostHooks;
+  cron?: CronDriver;
+  locks?: LocksDriver;
+  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 {
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+}
+
+export interface PaymentCoreService {
+  /**
+   * The full hono app: forked app-shell middleware + DID-Connect handlers +
+   * resource routes + static/SPA fallback + unified error handling. For node
+   * hosts (blocklet server, arc-node). Built lazily on first access — a workerd
+   * host that never touches it never runs the node-only app shell (static
+   * serving, fallback), which the CF worker serves through its own Hono pipeline
+   * instead. Phase 4: this is the SAME hono instance exposed as `fetch`.
+   */
+  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). 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`.
+   */
+  http: {
+    resourceRoutes: Hono;
+    /**
+     * D5: the Web-Fetch entry over the FULL hono app. A Fetch-native host
+     * (arc-node registerPrefixHandler) forwards a Web Request and gets a Web
+     * Response — base-strip, raw-body, multi Set-Cookie / redirect passthrough
+     * are all handled inside. The host writes zero express/req-res bridge. Never
+     * touched by the workerd host.
+     */
+    fetch: (request: Request, opts?: PaymentFetchOptions) => Promise<Response>;
+  };
+  rpc: {
+    entitlements: {
+      check: (input: { customerDid: string; featureKey: string; livemode?: boolean }) => Promise<any>;
+    };
+    meterEvents: {
+      report: (input: Record<string, any>) => Promise<any>;
+    };
+  };
+  lifecycle: PaymentCoreLifecycle;
+  /**
+   * D6 — idempotent per-tenant bootstrap (currency logos, overdraft prices,
+   * exchange-rate-health schedule, per-tenant integrations), run inside the
+   * tenant context. Multi-mode hosts MUST call this per tenant (single mode
+   * 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>;
+}
+
+/**
+ * Phase 4 (express→hono): the factory return is the published PaymentCoreService
+ * PLUS a top-level `fetch` — the hono app the blocklet server shell serves through
+ * `@hono/node-server` `serve({ fetch })`. `fetch` is the same hono instance as
+ * `handler` (kept as a convenience entry); `http.fetch` is the base-strip variant
+ * for arc consumers (same Request/Response shape, strips the host mount prefix).
+ */
+export type EmbeddedPaymentService = PaymentCoreService & {
+  fetch: (request: Request) => Response | Promise<Response>;
+};
+
+export class PaymentCoreSlotError extends Error {
+  code = 'MISSING_SLOT';
+
+  slot: string;
+
+  constructor(slot: string) {
+    super(`createEmbeddedPaymentService: required slot "${slot}" is missing`);
+    this.name = 'PaymentCoreSlotError';
+    this.slot = slot;
+  }
+}
+
+// Phase 8 (W2′): a REQUIRED config field is absent from the injected config (and
+// not present in the process.env fallback). Distinct from a missing slot so the
+// host can tell "you forgot a whole driver" from "you forgot one config key".
+export class MissingConfigError extends Error {
+  code = 'MISSING_CONFIG_FIELD';
+
+  field: string;
+
+  constructor(field: string) {
+    super(`createEmbeddedPaymentService: required config field "${field}" is missing`);
+    this.name = 'MissingConfigError';
+    this.field = field;
+  }
+}
+
+// D1 (S3.0): the tenancy slot is the authoritative source of the tenant mode.
+// A tenancy.mode that is neither "single" nor "multi", or that disagrees with an
+// explicit config.PAYMENT_TENANT_MODE, is a construction-time fail-fast (the
+// factory never silently picks one side). Distinct from a missing slot/config
+// field so the host can tell "your tenancy slot is malformed/contradictory"
+// from "you forgot a driver / a config key".
+export class TenancySlotError extends Error {
+  code: 'INVALID_TENANCY_MODE' | 'TENANCY_MODE_CONFLICT';
+
+  constructor(code: 'INVALID_TENANCY_MODE' | 'TENANCY_MODE_CONFLICT', message: string) {
+    super(message);
+    this.name = 'TenancySlotError';
+    this.code = code;
+  }
+}
+
+const VALID_TENANT_MODES = ['single', 'multi'] as const;
+
+// Phase 4 (express→hono): the /api surface is now two hono layers so an embedding
+// host can take only what fits its runtime.
+//
+//   buildResourceRoutesHono() — /api/healthz + the migrated resource domains, each
+//     scoped to its own forked app-shell pipeline. No DID-Connect handlers, no
+//     static/SPA fallback. This is the layer the CF worker mounts into its own
+//     Hono pipeline via `app.route('/', resourceRoutes)`.
+//   buildHonoApp()            — the full node hono app (app-shell pipeline +
+//     migrated resources + DID-Connect + static/SPA fallback + error handling).
+//     For node hosts (blocklet server, arc-node via svc.http.fetch).
+//
+// All route modules are required lazily so importing THIS module stays
+// side-effect-free for hosts that never build a layer.
+
+/**
+ * /api/healthz + the migrated resource domains on a standalone hono app — the
+ * embeddable surface (no app shell static/fallback, no DID-Connect). The CF
+ * worker mounts this whole app via `app.route('/', resourceRoutes)`. Each domain
+ * carries its own scoped app-shell pipeline (cors/xss/csrf/cdn/context + livemode
+ * + optional baseCurrency) via mountMigratedResources / mountResourceGroup.
+ */
+function buildResourceRoutesHono(): Hono {
+  const { mountMigratedResources } = require('./routes/hono');
+  const app = new Hono();
+  app.get('/api/healthz', (c) => c.json({ ok: true }));
+  // No appShell arg → mountResourceGroup defaults to the LITE app-shell (xss for
+  // sanitizedBody + livemode + baseCurrency). The CF worker (the only consumer of
+  // resourceRoutes) owns its own cors + tenant and never ran csrf/cdn/i18n. Keeping
+  // this path free of pipeline.ts (csrf/cdn/context) keeps the worker bundle clear
+  // of @blocklet/sdk/lib/util/* subpaths its shim does not map.
+  mountMigratedResources(app);
+  return app;
+}
+
+/** The 14 DID-Connect handler modules (each carries its own `action` + callbacks). */
+function connectHandlerModules(): any[] {
+  return [
+    require('./routes/connect/collect').default,
+    require('./routes/connect/collect-batch').default,
+    require('./routes/connect/pay').default,
+    require('./routes/connect/setup').default,
+    require('./routes/connect/subscribe').default,
+    require('./routes/connect/change-payment').default,
+    require('./routes/connect/change-plan').default,
+    require('./routes/connect/recharge').default,
+    require('./routes/connect/recharge-account').default,
+    require('./routes/connect/delegation').default,
+    require('./routes/connect/overdraft-protection').default,
+    require('./routes/connect/re-stake').default,
+    require('./routes/connect/auto-recharge-auth').default,
+    require('./routes/connect/change-payer').default,
+  ];
+}
+
+/**
+ * The DID-Connect handlers attached to a hono app. did-connect-js v4 dispatches
+ * by isHonoApp() → native attachHono (design §3.3), so the 14 handlers run with
+ * zero rewrite. Mounted on the main hono app alongside the native resource group
+ * (NOT under it — DID-Connect carries its own ensureSignedJson, no xss/csrf/cors).
+ */
+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;
+}
+
+/**
+ * Phase 4 (express→hono) — the full node hono app. The loopback bridge + express
+ * app shell are gone; this hono app is the only entry.
+ *
+ * Structure (registration order is load-bearing — hono matches in registration
+ * order):
+ *   ① /api/healthz — bare health route (BS liveness probe).
+ *   ② native       — the migrated resource domains + their scoped forked app-shell
+ *                    pipeline (cors/xss/csrf/cdn/context + livemode/baseCurrency),
+ *                    populated by `configureNative`.
+ *   ③ connectApp   — the DID-Connect sub-app, mounted alongside `native` (NOT under
+ *                    it — it carries its own ensureSignedJson, no xss/csrf/cors).
+ *   ④ 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,
+  attachStatic?: (app: Hono) => void
+): Hono {
+  const app = new Hono();
+
+  // Unified error handling — the hono equivalent of express-async-errors + the
+  // express ErrorRequestHandler: CustomError → its mapped status + formatError;
+  // otherwise 500 JSON.
+  app.onError((err, c) => {
+    logger.error('handle router error', err);
+    if (err instanceof CustomError) {
+      // getStatusFromError returns a plain number; hono's c.json wants a
+      // StatusCode union — cast through the contentful-status type.
+      return c.json({ error: formatError(err) }, getStatusFromError(err) as ContentfulStatusCode);
+    }
+    return c.json({ error: (err as Error).message }, 500);
+  });
+
+  // ① /api/healthz — was on the express resource router; now a bare hono route.
+  app.get('/api/healthz', (c) => c.json({ ok: true }));
+
+  const native = new Hono();
+  configureNative?.(native);
+  app.route('/', native); // ② native group (forked middleware + migrated resources)
+  if (getConnectApp) {
+    app.route('/', getConnectApp()); // ③ DID-Connect
+  }
+
+  // ④ 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;
+}
+
+/** rpc calls demand a tenant: explicit context or single-mode default. */
+function requireTenant(): string {
+  return requestContext.getInstanceDid(); // throws TENANT_CONTEXT_MISSING in multi mode without context
+}
+
+function buildRpc(): PaymentCoreService['rpc'] {
+  return {
+    entitlements: {
+      check(input) {
+        // validation errors must surface as rejections, not sync throws
+        return Promise.resolve().then(() => {
+          const instanceDid = requireTenant();
+          const { checkEntitlement } = require('./libs/entitlement');
+          return requestContext.withTenant(instanceDid, () =>
+            checkEntitlement({
+              customer_did: input.customerDid,
+              product_id: input.featureKey,
+              livemode: input.livemode,
+            })
+          );
+        });
+      },
+    },
+    meterEvents: {
+      report(input) {
+        return Promise.resolve().then(() => {
+          const instanceDid = requireTenant();
+          const { MeterEvent } = require('./store/models');
+          return requestContext.withTenant(instanceDid, () => MeterEvent.create(input as any));
+        });
+      },
+    },
+  };
+}
+
+let servicesStarted = false;
+
+// D6: a host-provided tenant enumeration hook (tenancy.listInstanceDids). When a
+// multi-mode host wants every known tenant bootstrapped at start(), it injects
+// this; otherwise the host drives bootstrapTenant() per provisioned tenant (e.g.
+// arc-node on first payment request). We do NOT abuse the IdentityDriver as a
+// tenant registry — it only does host->tenant + getAppEk.
+let listInstanceDidsHook: (() => Promise<string[]> | string[]) | undefined;
+
+/**
+ * D6 — idempotent per-tenant bootstrap. The tenant-scoped startup work that used
+ * to run (unscoped) inside startBackgroundServices lives here, executed INSIDE
+ * `withTenant(instanceDid)` so every query/push is correctly tenant-scoped:
+ *   - syncCurrencyLogo()                    (PaymentMethod logo backfill)
+ *   - ensureCreateOverdraftProtectionPrices (Price upsert)
+ *   - scheduleHealthChecks(instanceDid)     (exchange-rate-health, tenant in payload)
+ *   - ensureStakedForGas() / ensureWebhookRegistered() (per-tenant integrations)
+ *
+ * Multi mode has no default tenant, so a host MUST bootstrap each tenant
+ * explicitly (per provisioned host / first request, or all-at-once via
+ * tenancy.listInstanceDids). Single mode bootstraps the default tenant from
+ * start() automatically (original behavior preserved).
+ */
+async function bootstrapTenant(instanceDid: string): Promise<void> {
+  if (!instanceDid || typeof instanceDid !== 'string') {
+    throw new TenantError(TENANT_CONTEXT_MISSING, 'bootstrapTenant requires an instanceDid');
+  }
+  const { syncCurrencyLogo } = require('./crons/currency');
+  const { ensureStakedForGas } = require('./integrations/arcblock/stake');
+  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 })
+    );
+    await Promise.resolve(ensureCreateOverdraftProtectionPrices()).catch((error: unknown) =>
+      logger.error('bootstrapTenant: ensureCreateOverdraftProtectionPrices failed', { instanceDid, error })
+    );
+    // exchange-rate-health: tenant carried in the job payload (re-schedule safe)
+    scheduleHealthChecks(instanceDid);
+    if (isProduction()) {
+      await ensureWebhookRegistered().catch((error: unknown) =>
+        logger.error('bootstrapTenant: ensureWebhookRegistered failed', { instanceDid, error })
+      );
+    }
+    await Promise.resolve(ensureStakedForGas()).catch((error: unknown) =>
+      logger.error('bootstrapTenant: ensureStakedForGas failed', { instanceDid, error })
+    );
+  });
+}
+
+// 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');
+    return;
+  }
+  servicesStarted = true;
+
+  const crons = require('./crons/index').default;
+  const { initResourceHandler } = require('./integrations/blocklet/resource');
+  const { initUserHandler } = require('./integrations/blocklet/user');
+  const { initEventBroadcast } = require('./libs/ws');
+
+  // Tenant-AGNOSTIC engine registration: these create the queues + register the
+  // consumer handlers. Jobs carry their own tenant (instance_did), so no startup
+  // tenant context is needed. The exchange-rate-health SCHEDULE moved to
+  // bootstrapTenant (it pushes a tenant-scoped job); the queue itself is created
+  // at module import.
+  const starters: [string, () => Promise<any> | void][] = [
+    ['payment', require('./queues/payment').startPaymentQueue],
+    ['invoice', require('./queues/invoice').startInvoiceQueue],
+    ['subscription', require('./queues/subscription').startSubscriptionQueue],
+    ['event', require('./queues/event').startEventQueue],
+    ['payout', require('./queues/payout').startPayoutQueue],
+    ['vendor commission', require('./queues/vendors/commission').startVendorCommissionQueue],
+    ['vendor fulfillment', require('./queues/vendors/fulfillment').startVendorFulfillmentQueue],
+    ['coordinated fulfillment', require('./queues/vendors/fulfillment-coordinator').startCoordinatedFulfillmentQueue],
+    ['checkoutSession', require('./queues/checkout-session').startCheckoutSessionQueue],
+    ['notification', require('./queues/notification').startNotificationQueue],
+    ['refund', require('./queues/refund').startRefundQueue],
+    ['credit', require('./queues/credit-consume').startCreditConsumeQueue],
+    ['credit grant', require('./queues/credit-grant').startCreditGrantQueue],
+    ['token transfer', require('./queues/token-transfer').startTokenTransferQueue],
+    ['credit reconciliation', require('./queues/credit-reconciliation').startReconciliationQueue],
+    ['discount status', require('./queues/discount-status').startDiscountStatusQueue],
+  ];
+  for (const [name, start] of starters) {
+    Promise.resolve(start()).then(() => logger.info(`${name} queue started`));
+  }
+
+  // cron + global handlers (tenant-agnostic; runOnInit is skipped in multi mode)
+  crons.init();
+  initEventBroadcast();
+  initResourceHandler();
+  initUserHandler();
+
+  // Per-tenant bootstrap. Single mode: the default tenant always exists, so
+  // bootstrap it now (preserves the original startup behavior). Multi mode: the
+  // host drives bootstrapTenant per tenant — either eagerly via the optional
+  // tenancy.listInstanceDids hook, or lazily (per provisioned host / first req).
+  if (getTenantMode() === 'single') {
+    await bootstrapTenant(getDefaultInstanceDid());
+  } else if (listInstanceDidsHook) {
+    const dids = (await listInstanceDidsHook()) || [];
+    for (const did of dids) {
+      // eslint-disable-next-line no-await-in-loop -- bootstraps run sequentially
+      await bootstrapTenant(did).catch((error: unknown) =>
+        logger.error('startup bootstrapTenant failed', { instanceDid: did, error })
+      );
+    }
+  }
+}
+
+// eslint-disable-next-line require-await -- async contract; teardown is synchronous today
+async function stopBackgroundServices(): Promise<void> {
+  if (!servicesStarted) return;
+
+  // D2 teardown surface. In-flight jobs are never lost: the jobs table is the
+  // source of truth and re-delivery happens on the next start (queue recovery
+  // scan). We tear down the two background trigger sources so the process has no
+  // dangling handle after stop (the spec's "active handles 归零"):
+  //   1. cron timers — the node-cron driver stops its @abtnode/cron scheduler
+  //   2. queue poll loops — each scheduled queue's node loop sleep timer
+  // Both are idempotent on the next start(): cron register() clears + restarts,
+  // and the queue registry dedupes by name + the old loops are already stopped,
+  // so a start()/stop()/start() cycle never double-registers.
+  try {
+    const { getCronDriver } = require('./libs/drivers/cron');
+    getCronDriver().stop();
+  } catch (err) {
+    logger.error('cron teardown failed on stop', { error: err });
+  }
+  try {
+    const { stopAllQueues } = require('./libs/queue/runtime');
+    stopAllQueues();
+  } catch (err) {
+    logger.error('queue teardown failed on stop', { error: err });
+  }
+
+  // clear the guard so a later start() rebuilds the background services cleanly.
+  servicesStarted = false;
+}
+
+/**
+ * The W2 §1 factory. Synchronous on purpose: hosts get a fully assembled
+ * service object and decide when to listen / start. No partial
+ * initialization on validation failure.
+ */
+export function createEmbeddedPaymentService(slots: PaymentCoreSlots): EmbeddedPaymentService {
+  if (!slots || typeof slots !== 'object') throw new PaymentCoreSlotError('config');
+  if (!slots.config) throw new PaymentCoreSlotError('config');
+  if (!slots.db || !slots.db.sequelize) throw new PaymentCoreSlotError('db');
+  // D1 (S3.0): validate the tenancy slot and derive the effective config BEFORE
+  // any setCoreConfig — so a malformed/contradictory slot fails fast without
+  // writing a half-baked mode into the config boundary.
+  let effectiveConfig = slots.config;
+  if (slots.tenancy) {
+    const slotMode = (slots.tenancy as { mode?: unknown }).mode;
+    if (typeof slotMode !== 'string' || !VALID_TENANT_MODES.includes(slotMode as any)) {
+      throw new TenancySlotError(
+        'INVALID_TENANCY_MODE',
+        `tenancy.mode "${String(slotMode)}" is invalid — expected one of: ${VALID_TENANT_MODES.join(', ')}`
+      );
+    }
+    // slotMode is validated above; use slots.tenancy.mode for the branches below
+    // so TypeScript narrows the TenancySlot union (instanceDid only on single).
+    if (slots.tenancy.mode === 'single' && !slots.tenancy.instanceDid) {
+      throw new TenantError(TENANT_CONTEXT_MISSING, 'tenancy.mode=single requires instanceDid');
+    }
+    // intending multi must never silently degrade to single: the default
+    // identity driver resolves every host to the deployment app DID and the
+    // default secrets driver uses a single process key — both are single-tenant
+    // behaviors. A multi-mode host that omits either slot fails closed.
+    if (slots.tenancy.mode === 'multi') {
+      if (!slots.identity) throw new PaymentCoreSlotError('identity');
+      if (!slots.secrets) throw new PaymentCoreSlotError('secrets');
+    }
+    // config.PAYMENT_TENANT_MODE that disagrees with the slot is a conflict —
+    // fail fast rather than silently honoring one source.
+    const configMode = slots.config.PAYMENT_TENANT_MODE;
+    if (configMode !== undefined && configMode !== null && String(configMode) !== slotMode) {
+      throw new TenancySlotError(
+        'TENANCY_MODE_CONFLICT',
+        `tenancy.mode "${slotMode}" conflicts with config.PAYMENT_TENANT_MODE "${String(configMode)}" — set only one`
+      );
+    }
+    // the slot wins: effectiveConfig carries the slot mode through the boundary
+    // so getTenantMode() sees it with no env.
+    effectiveConfig = { ...slots.config, PAYMENT_TENANT_MODE: slotMode };
+  }
+
+  // Phase 8 (W2′): make the config slot authoritative — every core read goes
+  // through libs/env.ts, which now prefers this injected config over process.env.
+  const { setCoreConfig, readConfig } = require('./libs/env');
+  setCoreConfig(effectiveConfig);
+
+  // Fail-fast on a missing REQUIRED config field (not a silent default): a
+  // single-mode deployment cannot establish its default tenant without an app
+  // DID. Multi mode resolves the tenant per request via the identity slot, so
+  // BLOCKLET_APP_PID is not required there.
+  const singleMode = !slots.tenancy || slots.tenancy.mode === 'single';
+  const hasSingleTenantId = Boolean((slots.tenancy as any)?.instanceDid) || Boolean(readConfig('BLOCKLET_APP_PID'));
+  if (singleMode && !hasSingleTenantId) {
+    throw new MissingConfigError('BLOCKLET_APP_PID');
+  }
+
+  // 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;
+  // otherwise the lock facade keeps its default in-process memory driver. The
+  // worker passes the D1 locks driver here.
+  if (slots.locks) {
+    const { setLocksDriver } = require('./libs/lock');
+    setLocksDriver(slots.locks);
+  }
+
+  // queue / cron slots (Phase 9): inject the host flush hook + cron driver if
+  // provided; otherwise the Node defaults apply (no-op flush, node-cron
+  // registry). The worker injects flush-before-response hooks and the cf-cron
+  // driver here.
+  const { setQueueHostHooks, setCronDriver, setIdentityDriver, setSecretsDriver } = require('./libs/drivers');
+  if (slots.queue) setQueueHostHooks(slots.queue);
+  if (slots.cron) setCronDriver(slots.cron);
+
+  // secrets slot (Phase 11): the host injects a per-tenant keyring driver for
+  // multi-tenant; the default driver wraps the process @blocklet/sdk security
+  // (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).
+  if (slots.identity) setIdentityDriver(slots.identity);
+
+  // tenancy slot (Phase 10): a single-mode host declares its tenant identity
+  // explicitly; wire it into the default-tenant getter so it is not silently
+  // ignored (env app DID remains the fallback when no slot value is given).
+  if (slots.tenancy && slots.tenancy.mode === 'single' && slots.tenancy.instanceDid) {
+    const { setDefaultInstanceDid } = require('./libs/tenant');
+    setDefaultInstanceDid(slots.tenancy.instanceDid);
+  }
+
+  // D6: wire the optional multi-mode tenant enumeration hook (start() bootstraps
+  // each enumerated tenant). Absent => the host bootstraps per tenant on demand.
+  listInstanceDidsHook = slots.tenancy && slots.tenancy.mode === 'multi' ? slots.tenancy.listInstanceDids : undefined;
+
+  // Lazy, memoized layer construction (Option 3 seam). Assembly above already
+  // ran (config/db/slots) — that is the factory's eager contract. The HTTP
+  // layers are built on first access so a workerd host that only reads
+  // `http.resourceRoutes` never constructs the full node app (static/fallback),
+  // and a node host that reads `handler`/`fetch` reuses the same hono instance.
+  const memo = <T>(build: () => T): (() => T) => {
+    let value: T | undefined;
+    return () => {
+      value ??= build();
+      return value;
+    };
+  };
+  // Phase 4: the CF worker's embeddable surface — /api/healthz + migrated
+  // resources on a standalone hono app (no app-shell static/fallback, no connect).
+  const getResourceRoutes = memo(buildResourceRoutesHono);
+  // The DID-Connect handlers on a hono app for the full node shell.
+  const getConnectRoutesHono = memo(buildConnectRoutesHono);
+  // Phase 4: the full node hono app — the only entry. Memoized so `service.fetch`
+  // /`handler` are a stable instance for serve({ fetch }). configureNativePipeline
+  // + mountMigratedResources (lazily required to keep this module's import
+  // side-effect-free) build the native resource group; getConnectRoutesHono mounts
+  // DID-Connect; production static/SPA fallback are wired inside buildHonoApp.
+  const getHonoApp = memo(() => {
+    // eslint-disable-next-line global-require
+    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,
+      // 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.
+  let fetchHandler: FetchHandler | null = null;
+  const getFetchHandler = (): FetchHandler => {
+    if (fetchHandler) return fetchHandler;
+    // eslint-disable-next-line global-require
+    const { createFetchHandler } = require('./libs/http-fetch-adapter');
+    const h: FetchHandler = createFetchHandler(getHonoApp());
+    fetchHandler = h;
+    return h;
+  };
+
+  const rpc = buildRpc();
+  const lifecycle: PaymentCoreLifecycle = {
+    start: startBackgroundServices,
+    async stop() {
+      await stopBackgroundServices();
+      // Phase 4: the loopback server is gone, so there is no socket to close. The
+      // base-strip adapter's close() is a no-op; reset the memo for symmetry.
+      if (fetchHandler) {
+        const h = fetchHandler;
+        fetchHandler = null;
+        await h.close();
+      }
+    },
+  };
+
+  return {
+    // Phase 4: handler IS the full node hono app (same instance as `fetch`).
+    get handler() {
+      return getHonoApp();
+    },
+    // The hono app the blocklet server shell serves via @hono/node-server.
+    fetch(request: Request): Response | Promise<Response> {
+      return getHonoApp().fetch(request);
+    },
+    http: {
+      get resourceRoutes() {
+        return getResourceRoutes();
+      },
+      fetch(request: Request, opts?: PaymentFetchOptions): Promise<Response> {
+        return getFetchHandler()(request, opts);
+      },
+    },
+    rpc,
+    lifecycle,
+    bootstrapTenant,
+    provisionTenant,
+  };
+}