payment-kit 1.29.1 → 1.29.2

package/api/src/libs/lock.ts

@@ -1,53 +1,57 @@
-const { EventEmitter } = require('events');
-
-export class Lock {
-  name: string;
-  locked: boolean;
-  events: typeof EventEmitter;
-
-  constructor(name: string) {
-    this.name = name;
-    this.locked = false;
-    this.events = new EventEmitter();
-  }
-
-  acquire() {
-    return new Promise((resolve) => {
-      // If somebody has the lock, wait until he/she releases the lock and try again
-      if (this.locked) {
-        const tryAcquire = () => {
-          if (!this.locked) {
-            this.locked = true;
-            this.events.removeListener('release', tryAcquire);
-            resolve(true);
-          }
-        };
+// Phase 8 (W2-1a): lock facade over the locks slot driver.
+//
+// Call sites keep using `getLock(name)` unchanged. Behind the facade:
+//   - the active locks driver is injectable (`setLocksDriver`) — default is the
+//     in-process memory driver (Blocklet Server / Node). The worker injects the
+//     D1 driver through the locks slot.
+//   - lock names are tenant-prefixed (W1 §2.2) by default. Per-resource locks
+//     are tenant-scoped; process-level singleton guards (queue start guards,
+//     recovery) opt out with `{ scope: 'global' }`. In single-tenant mode the
+//     prefix is the constant deployment app DID, so lock identity is unchanged.
+
+import { getInstanceDid } from './context';
+import {
+  createMemoryLocksDriver,
+  scopedLockName,
+  MemoryLock,
+  type LockHandle,
+  type LocksDriver,
+  type LockScope,
+} from './drivers';
+
+let activeDriver: LocksDriver = createMemoryLocksDriver();
+
+/** Inject the locks driver (worker wires the D1 driver here). */
+export function setLocksDriver(driver: LocksDriver): void {
+  activeDriver = driver;
+}
 
-        this.events.on('release', tryAcquire);
-      } else {
-        // Otherwise, take the lock and resolve immediately
-        this.locked = true;
-        resolve(true);
-      }
-    });
-  }
+export function getLocksDriver(): LocksDriver {
+  return activeDriver;
+}
 
-  release() {
-    // Release the lock immediately
-    this.locked = false;
-    setImmediate(() => this.events.emit('release'));
-  }
+export interface GetLockOptions {
+  ttl?: number;
+  /** 'tenant' (default) prefixes the lock name with the current tenant; 'global' keeps the bare name. */
+  scope?: LockScope;
 }
 
-const locks = new Map<string, Lock>();
-export function getLock(name: string): Lock {
-  const exist = locks.get(name);
-  if (exist instanceof Lock) {
-    return exist;
+/**
+ * Acquire a handle to a named lock. Tenant-scoped by default; resolving the
+ * tenant fails closed in multi-tenant mode when no context is present (matching
+ * the scoped-query helpers from Phase 3).
+ */
+export function getLock(name: string, options: GetLockOptions = {}): LockHandle {
+  if (!name || typeof name !== 'string') {
+    throw new Error('getLock: a non-empty lock name is required');
   }
-
-  const lock = new Lock(name);
-  locks.set(name, lock);
-
-  return lock;
+  const scope: LockScope = options.scope ?? 'tenant';
+  const instanceDid = scope === 'tenant' ? getInstanceDid() : null;
+  const resolvedName = scopedLockName(name, instanceDid, scope);
+  return activeDriver.getLock(resolvedName, options.ttl !== undefined ? { ttl: options.ttl } : undefined);
 }
+
+// `Lock` is the in-process memory lock class — kept as a public export so the
+// standalone constructor form (`new Lock(name)`) and `LockHandle` annotations
+// both keep working.
+export { MemoryLock as Lock };

package/api/src/libs/logger.ts

@@ -1,4 +1,13 @@
-const createLogger = require('@blocklet/logger');
+// Phase 13b: lazy logging boundary.
+//
+// @blocklet/logger throws at REQUIRE time when BLOCKLET_LOG_DIR is absent
+// ("valid BLOCKLET_LOG_DIR env is required by logger"). That made importing the
+// core — and therefore createEmbeddedPaymentService / rpc.entitlements.check,
+// which transitively import this module — demand a blocklet log env even for a
+// bare host (arc embedding before its blocklet runtime is wired). Defer the
+// require to first use and fall back to console when no blocklet log env exists.
+// The blocklet server (BLOCKLET_LOG_DIR set) and the CF worker (aliased shim)
+// still get the real logger on first call — behavior unchanged for them.
 
 interface Logger {
   debug: (...args: any[]) => void;
@@ -7,14 +16,45 @@ interface Logger {
   warn: (...args: any[]) => void;
 }
 
-const init = (label: string): Logger => {
-  const instance = createLogger(label || '');
-  return instance;
-};
+let resolved: Logger | undefined;
 
-const logger = init('app');
+function resolveLogger(): Logger {
+  if (resolved) return resolved;
+  try {
+    // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+    const createLogger = require('@blocklet/logger');
+    resolved = createLogger('app') as Logger;
+  } catch {
+    // bare host without a blocklet log env — console fallback.
+    /* eslint-disable no-console */
+    resolved = {
+      debug: (...args: any[]) => console.debug(...args),
+      info: (...args: any[]) => console.info(...args),
+      error: (...args: any[]) => console.error(...args),
+      warn: (...args: any[]) => console.warn(...args),
+    };
+    /* eslint-enable no-console */
+  }
+  return resolved;
+}
+
+const logger: Logger = {
+  debug: (...args: any[]) => resolveLogger().debug(...args),
+  info: (...args: any[]) => resolveLogger().info(...args),
+  error: (...args: any[]) => resolveLogger().error(...args),
+  warn: (...args: any[]) => resolveLogger().warn(...args),
+};
 
 export default logger;
 
-const { setupAccessLogger } = createLogger;
-export { setupAccessLogger };
+// Express access logger — also lazy. A bare host that never mounts the node
+// handler (where setupAccessLogger runs) never needs the blocklet log env.
+export function setupAccessLogger(app: any): void {
+  try {
+    // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+    const createLogger = require('@blocklet/logger');
+    createLogger.setupAccessLogger?.(app);
+  } catch {
+    // bare host: no access logging
+  }
+}

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

@@ -1,4 +1,4 @@
-import { Notification as BlockletNotification } from '@blocklet/sdk';
+import BlockletNotification from '@blocklet/sdk/service/notification';
 
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './template/base';
 import { CheckoutSession, CreditGrant, Invoice, Meter, MeterEvent, Subscription } from '../../store/models';

package/api/src/libs/notification/template/customer-credit-low-balance.ts

@@ -2,6 +2,7 @@
 /* eslint-disable @typescript-eslint/indent */
 import { withQuery } from 'ufo';
 import { BN } from '@ocap/util';
+import { creditLowBalanceThresholdPercentage } from '../../env';
 import { getUserLocale } from '../../../integrations/blocklet/notification';
 import { translate } from '../../../locales';
 import { Customer, PaymentCurrency, CreditGrant } from '../../../store/models';
@@ -35,7 +36,7 @@ export class CustomerCreditLowBalanceEmailTemplate implements BaseEmailTemplate<
    * @returns threshold percentage (default: 10)
    */
   static getLowBalanceThresholdPercent(): number {
-    return parseInt(process.env.CREDIT_LOW_BALANCE_THRESHOLD_PERCENTAGE || '10', 10);
+    return creditLowBalanceThresholdPercentage();
   }
 
   /**

package/api/src/libs/notification/template/customer-revenue-succeeded.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/brace-style */
 /* eslint-disable @typescript-eslint/indent */
-import { getUrl } from '@blocklet/sdk';
+import { getUrl } from '@blocklet/sdk/lib/component';
 import { getUserLocale } from '../../../integrations/blocklet/notification';
 import { translate } from '../../../locales';
 import { CheckoutSession, Customer, PaymentLink, PaymentMethod, Payout } from '../../../store/models';

package/api/src/libs/notification/template/customer-reward-succeeded.ts

@@ -4,7 +4,7 @@ import isEmpty from 'lodash/isEmpty';
 import pWaitFor from 'p-wait-for';
 import type { LiteralUnion } from 'type-fest';
 
-import { getUrl } from '@blocklet/sdk';
+import { getUrl } from '@blocklet/sdk/lib/component';
 import { getUserLocale } from '../../../integrations/blocklet/notification';
 import { translate } from '../../../locales';
 import {

package/api/src/libs/overdraft-protection.ts

@@ -1,4 +1,4 @@
-import { createProductAndPrices } from '../routes/products';
+import { createProductAndPrices } from '../routes/hono/products';
 import { PaymentCurrency, PaymentMethod, Price, Product } from '../store/models';
 import logger from './logger';
 

package/api/src/libs/payout.ts

@@ -1,4 +1,4 @@
-import { component } from '@blocklet/sdk';
+import component from '@blocklet/sdk/lib/component';
 import type { LiteralUnion } from 'type-fest';
 import { withQuery } from 'ufo';
 import { getConnectQueryParam } from './util';

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

@@ -6,15 +6,91 @@ import fastq from 'fastq';
 import { nanoid } from 'nanoid';
 
 import { AsyncLocalStorage } from 'async_hooks';
+import { isTestEnv } from '../env';
 import logger from '../logger';
-import { sleep, tryWithTimeout } from '../util';
+import { context, withTenant } from '../context';
+import {
+  TENANT_CONTEXT_MISSING,
+  TENANT_MISMATCH,
+  TenantError,
+  assertValidInstanceDid,
+  getDefaultInstanceDid,
+  getTenantMode,
+  resolveRowTenant,
+} from '../tenant';
+import { tryWithTimeout } from '../util';
 import dayjs from '../dayjs';
 import createQueueStore from './store';
+import { registerQueue, getQueueRuntimeMode, trackPending } from './runtime';
 import { Job } from '../../store/models/job';
 import { sequelize } from '../../store/sequelize';
 
 const CANCELLED = '__CANCELLED__';
-const MIN_DELAY = process.env.NODE_ENV === 'test' ? 2 : 8;
+// lazy so the injected config (set after import) is honored at call time
+const minDelay = (): number => (isTestEnv() ? 2 : 8);
+
+// ---------------------------------------------------------------------------
+// Phase 5 (W1-4a): generic queue tenant layer.
+// Every queue gets this uniformly — see docs/arc-integration/planning/w1-w2/
+// queue-matrix.md for the per-queue conclusions built on top of it.
+// ---------------------------------------------------------------------------
+
+/**
+ * Stamp the active tenant into a job payload at enqueue time.
+ * - payload already carries instance_did: validated (and in multi mode it
+ *   must be a legal DID — a forged/illegal value is refused at the gate)
+ * - otherwise: the context tenant (single mode = app DID); multi mode
+ *   without context -> the push itself is rejected (fail-closed)
+ */
+function injectJobTenant(job: any): any {
+  if (!job || typeof job !== 'object') return job;
+  if (job.instance_did) {
+    assertValidInstanceDid(job.instance_did);
+    return job;
+  }
+  return { ...job, instance_did: context.getInstanceDid() };
+}
+
+/**
+ * Run a job handler inside its payload tenant. Legacy jobs persisted before
+ * Phase 5 have no instance_did: single mode falls back to the deployment
+ * default, multi mode refuses permanently (non-retryable + structured alert).
+ */
+function runJobWithTenant<T>(job: any, onJob: (job: T) => Promise<any>): Promise<any> {
+  const tenant = job?.instance_did;
+  if (tenant) {
+    return withTenant(tenant, () => onJob(job));
+  }
+  if (getTenantMode() === 'single') {
+    return withTenant(getDefaultInstanceDid(), () => onJob(job));
+  }
+  const err = new TenantError(TENANT_CONTEXT_MISSING, 'legacy job without tenant refused in multi mode');
+  (err as any).nonRetryable = true;
+  logger.error('[queue] legacy job without tenant refused', { code: TENANT_CONTEXT_MISSING, job });
+  return Promise.reject(err);
+}
+
+/**
+ * Handler-entry invariant for object-bound queues: the object loaded by id
+ * must belong to the payload tenant the handler is running under. A forged
+ * payload (tenant A, object of B) dies here permanently — nothing executes.
+ */
+export function assertJobObjectTenant(row: { instance_did?: string | null } | null | undefined): void {
+  if (!row) return; // absent objects are the handler's own no-op/warn path
+  const rowTenant = resolveRowTenant(row);
+  const jobTenant = context.getInstanceDid();
+  if (rowTenant !== jobTenant) {
+    // Phase 4 (W1-3): emit a structured violation alert BEFORE throwing, so a
+    // forged/mixed cross-tenant job is observable in logs (same dedicated code
+    // as the W1 §4.1 event-rejection path) even if the queue swallows the
+    // thrown error. Loading the object cross-tenant (systemFindByPk) is what
+    // makes this violation visible instead of folding into a scoped null.
+    logger.error('TENANT_VIOLATION', { code: TENANT_MISMATCH, rowTenant, jobTenant });
+    const err = new TenantError(TENANT_MISMATCH, `job object belongs to ${rowTenant} but payload says ${jobTenant}`);
+    (err as any).nonRetryable = true;
+    throw err;
+  }
+}
 
 type QueueOptions<T> = {
   id?: (job: T) => string;
@@ -46,6 +122,18 @@ type PushParams<T> = {
   delay?: number; // in seconds
   runAt?: number; // unix timestamp in seconds
   skipDuplicateCheck?: boolean; // Q1: skip addJob's findOne when caller guarantees no duplicate
+  /**
+   * Internal: re-delivery of a row already persisted in the jobs table
+   * (startup/scheduled recovery). Skips the push-side tenant gate so legacy
+   * pre-tenant rows reach runJobWithTenant, which owns the legacy strategy
+   * (single -> default tenant, multi -> structured non-retryable refusal).
+   *
+   * NEVER set this from application code: it bypasses the enqueue tenant
+   * gate. Object-bound handlers are still protected by
+   * assertJobObjectTenant, but system-operation queues (no object load)
+   * would run under whatever tenant the payload claims.
+   */
+  fromStore?: boolean;
 };
 
 export default function createQueue<T = any>({ name, onJob, options = defaults }: QueueParams<T>) {
@@ -98,7 +186,7 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
       }
 
       try {
-        const result = await tryWithTimeout(() => onJob(job), maxTimeout);
+        const result = await tryWithTimeout(() => runJobWithTenant(job, onJob), maxTimeout);
         logger.info('job finished', { id, result });
         cb(null, result);
       } catch (err) {
@@ -108,7 +196,15 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
     // @ts-ignore
   }, concurrency);
 
-  const push = ({ job, id, persist = true, delay, runAt, skipDuplicateCheck = false }: PushParams<T>) => {
+  const push = ({
+    job: rawJob,
+    id,
+    persist = true,
+    delay,
+    runAt,
+    skipDuplicateCheck = false,
+    fromStore = false,
+  }: PushParams<T>) => {
     const jobEvents = new EventEmitter();
     const emit = (e: string, data: any) => {
       queueEvents.emit(e, data);
@@ -116,20 +212,24 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
     };
     const now = dayjs().unix();
 
-    if (!job) {
+    if (!rawJob) {
       throw new Error('Can not queue empty job');
     }
 
+    // fail-closed gate: every NEW payload carries its tenant from here on;
+    // store re-deliveries pass through so the execution-side legacy strategy applies
+    const job = (fromStore ? rawJob : injectJobTenant(rawJob)) as T;
+
     const jobId = getJobId(id, job);
 
-    if ((delay && delay >= MIN_DELAY) || (runAt && runAt > now)) {
+    if ((delay && delay >= minDelay()) || (runAt && runAt > now)) {
       if (!enableScheduledJob) {
         throw new Error('Must set options.enableScheduledJob to true to run delay jobs');
       }
 
       // 这里不是精确的 delay, 延迟的时间太短没有意义，所以这里限制了最小 delay
-      if (delay && delay < MIN_DELAY) {
-        throw new Error(`minimum delay is ${MIN_DELAY}s`);
+      if (delay && delay < minDelay()) {
+        throw new Error(`minimum delay is ${minDelay()}s`);
       }
 
       const attrs: { delay?: number; will_run_at?: number } = {};
@@ -221,12 +321,31 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
         queue.push({ id: jobId, job, persist }, onJobComplete);
       });
 
+    // Phase 12b: workerd flush. Track this immediate execution so a frozen-
+    // isolate host can drain it before returning the response — otherwise the
+    // fire-and-forget setImmediate/fastq work is dropped when the isolate is
+    // torn down. Tracked ONLY on a workerd host: zero overhead and no extra
+    // listeners on a long-lived node process.
+    let resolveSettled: () => void = () => {};
+    if (getQueueRuntimeMode() === 'workerd') {
+      const settled = new Promise<void>((resolve) => {
+        resolveSettled = resolve;
+      });
+      jobEvents.on('finished', resolveSettled);
+      jobEvents.on('failed', resolveSettled);
+      jobEvents.on('cancelled', resolveSettled);
+      trackPending(settled);
+    }
+
     if (persist) {
       store
         .addJob(jobId, job, {}, skipDuplicateCheck)
         .then(queueJob)
         .catch((err) => {
           logger.error('Can not add job to store', { error: err });
+          // never enqueued (e.g. duplicate id) → emits nothing; release the
+          // workerd flush tracker so flushQueueWork() cannot hang on it.
+          resolveSettled();
         });
     } else {
       queueJob();
@@ -246,7 +365,11 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
 
         const job = push(params);
         job.on('finished', (data: { id: string; job: T; result: any }) => resolve(data));
-        job.on('canceled', (data: { id: string; job: T }) => resolve(data));
+        // Phase 12b: the engine emits 'cancelled' (two L); the old 'canceled'
+        // listener never fired, so a cancelled job left pushAndWait hanging
+        // forever — and the CF queue() consumer now runs through pushAndWait,
+        // where that hang would stall the queue batch until CF kills it.
+        job.on('cancelled', (data: { id: string; job: T }) => resolve(data));
         job.on('failed', (data: { id: string; job: T; error: Error }) => reject(data));
       } catch (err) {
         reject(err);
@@ -296,60 +419,128 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
     return updatedJob;
   };
 
-  // Populate the queue on startup
-  process.nextTick(async () => {
-    try {
-      if (!Job.isInitialized()) {
-        Job.initialize(sequelize);
+  // Populate the queue on startup. Phase 12b: this is a long-lived-process
+  // recovery — re-queue persisted immediate rows on boot. A workerd host spins
+  // up a fresh isolate per request and MUST NOT re-run every persisted row on
+  // each cold start; it drives due-job re-dispatch through dispatchDueJobs()
+  // from scheduled() instead. So the boot recovery is node-mode only.
+  if (getQueueRuntimeMode() === 'node') {
+    process.nextTick(async () => {
+      try {
+        if (!Job.isInitialized()) {
+          Job.initialize(sequelize);
+        }
+        const jobs = await store.getJobs();
+        jobs.forEach((x) => {
+          if (x.job && x.id) {
+            try {
+              push({ job: x.job, id: x.id, persist: false, fromStore: true });
+            } catch (err: any) {
+              // one bad row must never break recovery of the rest
+              logger.error('failed to re-queue stored job', { id: x.id, code: err?.code, message: err?.message });
+            }
+          } else {
+            logger.info('skip invalid job from db', { job: x });
+          }
+        });
+        // eslint-disable-next-line no-shadow
+      } catch (err) {
+        console.error(err);
+        logger.error(`Can not load existing ${name} jobs`, { error: err });
       }
-      const jobs = await store.getJobs();
-      jobs.forEach((x) => {
-        if (x.job && x.id) {
-          push({ job: x.job, id: x.id, persist: false });
-        } else {
-          logger.info('skip invalid job from db', { job: x });
+    });
+  }
+
+  // Re-deliver this queue's due delayed rows once — the body shared by the node
+  // loop() (timer-driven) and the host dispatchDueJobs() (CF scheduled()-driven).
+  // Same cancel-then-replay-from-store path either way, so worker and node agree
+  // on exactly how a due delayed job runs.
+  const redispatchDue = async (): Promise<{ dispatched: number; failed: number }> => {
+    let dispatched = 0;
+    let failed = 0;
+    if (enableScheduledJob !== true) return { dispatched, failed };
+    const jobs = await store.getScheduledJobs();
+    for (const x of jobs) {
+      if (x.job && x.id) {
+        // fix: https://github.com/blocklet/payment-kit/issues/287
+        // Intentional cancel-then-replay: marking the row cancelled=true keeps
+        // the NEXT due-poll (loop tick / dispatchDueJobs) from re-picking it
+        // while this run is in flight; the immediate re-push below clears the
+        // in-memory cancel flag for THIS execution, and onJobComplete deletes
+        // the row on success. A reader watching raw DB state mid-dispatch will
+        // briefly see cancelled=true — that is the de-dupe latch, not an error.
+        // eslint-disable-next-line no-await-in-loop
+        await cancel(x.id);
+        logger.info('reschedule delayed or scheduled job', { id: x.id, job: x.job });
+        try {
+          push({ job: x.job, id: x.id, persist: false, fromStore: true });
+          dispatched += 1;
+        } catch (err: any) {
+          failed += 1;
+          logger.error('failed to reschedule stored job', { id: x.id, code: err?.code, message: err?.message });
         }
-      });
-      // eslint-disable-next-line no-shadow
-    } catch (err) {
-      console.error(err);
-      logger.error(`Can not load existing ${name} jobs`, { error: err });
+      } else {
+        logger.info('skip invalid job from db', { job: x });
+      }
     }
-  });
+    return { dispatched, failed };
+  };
 
-  const loop = async () => {
-    if (enableScheduledJob === true) {
-      // eslint-disable-next-line no-constant-condition
-      while (true) {
-        await sleep((MIN_DELAY * 1000) / 2);
+  // D2 teardown: the node poll loop is cancelable. `stopLoop()` flips the flag
+  // AND clears the pending sleep timer (so the process has no dangling handle on
+  // stop — the spec's "active handles 归零") and resolves the in-flight sleep so
+  // the loop observes the flag and returns immediately.
+  let loopStopped = false;
+  let loopTimer: ReturnType<typeof setTimeout> | null = null;
+  let loopWake: (() => void) | null = null;
+  const cancelableSleep = (ms: number): Promise<void> =>
+    new Promise<void>((resolve) => {
+      loopWake = resolve;
+      loopTimer = setTimeout(() => {
+        loopTimer = null;
+        loopWake = null;
+        resolve();
+      }, ms);
+    });
+  const stopLoop = (): void => {
+    loopStopped = true;
+    if (loopTimer) {
+      clearTimeout(loopTimer);
+      loopTimer = null;
+    }
+    if (loopWake) {
+      const wake = loopWake;
+      loopWake = null;
+      wake();
+    }
+  };
 
-        try {
-          /* eslint-disable no-await-in-loop */
-          const jobs = await store.getScheduledJobs();
-          for (const x of jobs) {
-            if (x.job && x.id) {
-              // fix: https://github.com/blocklet/payment-kit/issues/287
-              await cancel(x.id);
-              logger.info('reschedule delayed or scheduled job', {
-                id: x.id,
-                job: x.job,
-              });
-              push({ job: x.job, id: x.id, persist: false });
-            } else {
-              logger.info('skip invalid job from db', { job: x });
-            }
-          }
-        } catch (err) {
-          console.error(err);
-          logger.error(`Can not load scheduled ${name} jobs`, { error: err });
-        }
+  // The node poll loop. Disabled on a workerd host: a frozen isolate cannot run
+  // a background timer, so the host calls dispatchDueJobs() from scheduled()
+  // instead (which runs redispatchDue() above — the same code path).
+  const loop = async () => {
+    if (enableScheduledJob !== true) return;
+    if (getQueueRuntimeMode() !== 'node') return;
+    while (!loopStopped) {
+      // eslint-disable-next-line no-await-in-loop
+      await cancelableSleep((minDelay() * 1000) / 2);
+      // stopped during the sleep (teardown) — exit before doing any work.
+      if (loopStopped) return;
+      // mode can flip after assembly (a host that sets workerd late); stop then.
+      if (getQueueRuntimeMode() !== 'node') return;
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await redispatchDue();
+      } catch (err) {
+        console.error(err);
+        logger.error(`Can not load scheduled ${name} jobs`, { error: err });
       }
     }
   };
 
   loop();
 
-  return Object.assign(queueEvents, {
+  const queueInstance = Object.assign(queueEvents, {
     store,
     push,
     pushAndWait,
@@ -361,6 +552,8 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
     delete: deleteJob,
     cancel,
     update: updateJob,
+    /** D2 teardown: stop this queue's node poll loop (no-op if not scheduled). */
+    stop: stopLoop,
     options: {
       concurrency,
       maxRetries,
@@ -369,4 +562,18 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
       enableScheduledJob,
     },
   });
+
+  // Phase 12b: register into the host-facing queue runtime surface so the CF
+  // worker can look the handle up by name (queue() consumer) and drive due
+  // re-dispatch (scheduled()) through the service/slot boundary — no more
+  // direct cloudflare/shims/queue.ts imports.
+  registerQueue({
+    name,
+    enableScheduledJob: enableScheduledJob === true,
+    handle: queueInstance,
+    redispatchDue,
+    stop: stopLoop,
+  });
+
+  return queueInstance;
 }