payment-kit 1.29.1 → 1.29.3

package/api/tests/queues/queue-parity.spec.ts

@@ -0,0 +1,249 @@
+// Phase 9 (W2-1b): queue engine + executor parity (W2 判据 4).
+//
+// The CF worker runs the SAME queue engine as Blocklet Server
+// (api/src/libs/queue) — only the fastq EXECUTOR primitive is swapped (real
+// fastq on Node, cloudflare/shims/fastq in the worker). This spec proves:
+//   Part A — the engine's delay/retry/cancel/pushAndWait semantics (embedded).
+//   Part B — the fastq shim is a faithful drop-in for real fastq on the exact
+//            operations the engine uses, so the worker behaves identically.
+// Together that is the embedded↔worker queue parity the acceptance gate wants.
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Sequelize } from 'sequelize';
+import { SequelizeStorage, Umzug } from 'umzug';
+
+import { withTenant, getInstanceDid } from '../../src/libs/context';
+
+/* eslint-disable global-require, import/no-dynamic-require, require-await, no-promise-executor-return */
+
+// the retry/settle cases do real per-attempt DB ops on a shared sqlite file;
+// under full-suite parallel load they can exceed jest's 5s default, so give the
+// suite a generous timeout (these are inherently I/O-bound, not hung). Phase 12b
+// added queue-runtime-surface.spec.ts which contends for the same jest workers,
+// so the margin is bumped to keep the settle cases from a transient timeout.
+jest.setTimeout(60000);
+
+jest.mock('../../src/libs/logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() },
+}));
+
+const STORE_DIR = path.join(__dirname, '../../src/store');
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'queue-parity-'));
+const sequelize = new Sequelize({ dialect: 'sqlite', storage: path.join(dir, 'test.db'), logging: false });
+const umzug = new Umzug({
+  migrations: {
+    glob: ['migrations/*.ts', { cwd: STORE_DIR }],
+    resolve: ({ name, path: p, context }) => {
+      const migration = require(p!);
+      return {
+        name: name.replace(/\.ts$/, '.js'),
+        up: () => migration.up({ context }),
+        down: () => migration.down({ context }),
+      };
+    },
+  },
+  context: sequelize.getQueryInterface(),
+  storage: new SequelizeStorage({ sequelize }),
+  logger: undefined,
+});
+
+let createQueue: any;
+
+beforeAll(async () => {
+  await umzug.up();
+  const models = require('../../src/store/models');
+  models.initialize(sequelize);
+  createQueue = require('../../src/libs/queue').default;
+}, 120000);
+
+afterAll(async () => {
+  await sequelize.close();
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const settle = (emitter: any): Promise<{ event: string; data: any }> =>
+  new Promise((resolve) => {
+    ['finished', 'failed', 'cancelled'].forEach((e) => emitter.on(e, (data: any) => resolve({ event: e, data })));
+  });
+
+describe('Part A — Node queue engine contract semantics', () => {
+  beforeEach(async () => {
+    await sequelize.query('DELETE FROM jobs');
+  });
+
+  it('immediate job runs and the jobs row is cleared on finish', async () => {
+    const seen: any[] = [];
+    const q = createQueue({
+      name: `pa-imm-${Date.now()}`,
+      onJob: async (job: any) => {
+        seen.push(job.v);
+        return job.v * 2;
+      },
+    });
+    const ev = q.push({ job: { v: 21 } });
+    const { event, data } = await settle(ev);
+    expect(event).toBe('finished');
+    expect(data.result).toBe(42);
+    expect(seen).toEqual([21]);
+    const row = await q.get(ev.id);
+    expect(row).toBeNull(); // cleared
+  });
+
+  it('pushAndWait resolves with the handler result', async () => {
+    const q = createQueue({ name: `pa-paw-${Date.now()}`, onJob: async (job: any) => `ok:${job.v}` });
+    const res: any = await q.pushAndWait({ job: { v: 7 } });
+    expect(res.result).toBe('ok:7');
+  });
+
+  it('retries up to maxRetries then fails (no infinite retry)', async () => {
+    let attempts = 0;
+    const retries: number[] = [];
+    const q = createQueue({
+      name: `pa-retry-${Date.now()}`,
+      onJob: async () => {
+        attempts += 1;
+        throw new Error('always');
+      },
+      options: { maxRetries: 3, retryDelay: 1 },
+    });
+    q.on('retry', () => retries.push(1));
+    const ev = q.push({ job: { v: 1 } });
+    const { event } = await settle(ev);
+    expect(event).toBe('failed');
+    expect(attempts).toBe(3); // initial + 2 retries (retry_count starts at 1, fails at >= maxRetries)
+    expect(retries.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('nonRetryable error fails immediately (single attempt)', async () => {
+    let attempts = 0;
+    const q = createQueue({
+      name: `pa-nonretry-${Date.now()}`,
+      onJob: async () => {
+        attempts += 1;
+        const err: any = new Error('forged');
+        err.nonRetryable = true;
+        throw err;
+      },
+      options: { maxRetries: 5, retryDelay: 1 },
+    });
+    const ev = q.push({ job: { v: 1 } });
+    const { event } = await settle(ev);
+    expect(event).toBe('failed');
+    expect(attempts).toBe(1);
+  });
+
+  it('cancel marks the row and excludes it from recovery (the skip mechanism)', async () => {
+    const q = createQueue({ name: `pa-cancel-${Date.now()}`, onJob: async () => undefined });
+    await q.store.addJob('cj-1', { v: 1, instance_did: 'did:abt:zCANCEL' }, {});
+    // before cancel: recovery would pick the row up
+    expect((await q.store.getJobs()).some((j: any) => j.id === 'cj-1')).toBe(true);
+    await q.cancel('cj-1');
+    // after cancel: execution-time guard sees it, recovery query excludes it
+    expect(await q.store.isCancelled('cj-1')).toBe(true);
+    expect((await q.store.getJobs()).some((j: any) => j.id === 'cj-1')).toBe(false);
+  });
+
+  // Bad input
+  it('rejects an empty job', () => {
+    const q = createQueue({ name: `pa-empty-${Date.now()}`, onJob: async () => undefined });
+    expect(() => q.push({ job: undefined as any })).toThrow(/Can not queue empty job/);
+  });
+
+  // Data damage — same job id does not execute twice (duplicate guard)
+  it('a duplicate job id executes only once', async () => {
+    let runs = 0;
+    const q = createQueue({
+      name: `pa-dup-${Date.now()}`,
+      onJob: async () => {
+        runs += 1;
+        return runs;
+      },
+    });
+    q.push({ job: { v: 1 }, id: 'dup-1' });
+    q.push({ job: { v: 1 }, id: 'dup-1' }); // duplicate id — store rejects, no second execution
+    // Either push can win the concurrent addJob UNIQUE race; the LOSER's
+    // jobEvents never settles (its addJob rejects before queueJob), so awaiting
+    // one specific push is racy and starves under parallel load. Wait for the
+    // single execution to actually land instead — that is what we assert.
+    const deadline = Date.now() + 5000;
+    while (runs < 1 && Date.now() < deadline) {
+      // eslint-disable-next-line no-await-in-loop, no-promise-executor-return
+      await new Promise((r) => setTimeout(r, 20));
+    }
+    await new Promise((r) => setTimeout(r, 60));
+    expect(runs).toBe(1);
+  });
+
+  // Data leak — the handler runs under the PAYLOAD tenant, never another's
+  it('handler executes under the payload tenant (no cross-tenant leak)', async () => {
+    const seen: Record<string, string> = {};
+    const q = createQueue({
+      name: `pa-tenant-${Date.now()}`,
+      onJob: async (job: any) => {
+        seen[job.tag] = getInstanceDid();
+      },
+    });
+    // push under tenant A's context — payload is stamped with A
+    const evA = await withTenant('did:abt:zTENANTA', async () => q.push({ job: { tag: 'A' } }));
+    const evB = await withTenant('did:abt:zTENANTB', async () => q.push({ job: { tag: 'B' } }));
+    await Promise.all([settle(evA), settle(evB)]);
+    expect(seen.A).toBe('did:abt:zTENANTA');
+    expect(seen.B).toBe('did:abt:zTENANTB');
+  });
+});
+
+describe('Part B — fastq shim is a faithful drop-in for real fastq', () => {
+  // run the exact operations the engine uses against both executors
+  const realFastq = require('fastq');
+  const shimFastq = require('../../../cloudflare/shims/fastq').default;
+
+  const scenario = (fastqImpl: any) =>
+    new Promise<any>((resolve) => {
+      const order: string[] = [];
+      const results: any[] = [];
+      const q = fastqImpl(async (data: any, cb: Function) => {
+        order.push(data.id);
+        if (data.fail) {
+          cb(new Error(`fail:${data.id}`));
+          return;
+        }
+        cb(null, `done:${data.id}`);
+      }, 1);
+      let pending = 3;
+      const done = (tag: string) => (err: any, res: any) => {
+        results.push({ tag, err: err?.message ?? null, res: res ?? null });
+        pending -= 1;
+        if (pending === 0) resolve({ order, results });
+      };
+      q.push({ id: 'a' }, done('a'));
+      q.push({ id: 'b', fail: true }, done('b'));
+      q.unshift({ id: 'c' }, done('c')); // unshift jumps the queue (retry path)
+    });
+
+  it('produces identical execution order and results on both executors', async () => {
+    const real = await scenario(realFastq);
+    const shim = await scenario(shimFastq);
+    // same success/error callback shape per job
+    const norm = (r: any) => r.results.sort((x: any, y: any) => x.tag.localeCompare(y.tag));
+    expect(norm(shim)).toEqual(norm(real));
+    // job 'b' errored on both, 'a'/'c' succeeded on both
+    const byTag = (r: any) => Object.fromEntries(r.results.map((x: any) => [x.tag, x.err ? 'err' : 'ok']));
+    expect(byTag(shim)).toEqual(byTag(real));
+    expect(byTag(real)).toEqual({ a: 'ok', b: 'err', c: 'ok' });
+  });
+
+  it('the shim accepts the 2-arg fastq(worker, concurrency) form the engine uses', async () => {
+    // regression for the pre-existing "worker is not a function" bug
+    const ran: any[] = [];
+    const q = shimFastq(async (data: any, cb: Function) => {
+      ran.push(data.id);
+      cb(null, 'ok');
+    }, 1);
+    const res = await new Promise((r) => q.push({ id: 'x' }, (_e: any, v: any) => r(v)));
+    expect(ran).toEqual(['x']);
+    expect(res).toBe('ok');
+  });
+});

package/api/tests/queues/queue-runtime-surface.spec.ts

@@ -0,0 +1,277 @@
+// Phase 12b (W2′): core queue RUNTIME surface parity probes.
+//
+// These lock the contract the CF worker now drives through the service/slot
+// boundary instead of cloudflare/shims/queue.ts:
+//   - the queue REGISTRY is non-empty under the canonical (node-engine) build
+//   - a due delayed job dispatches + executes EXACTLY once via dispatchDueJobs()
+//   - a cancelled delayed job is NOT executed by dispatchDueJobs() (no
+//     half-execution residue — the spec's mandatory negative case)
+//   - retry / nonRetryable / maxRetries match the node engine
+//   - the handler runs under the PAYLOAD tenant; a cross-tenant object is
+//     fail-closed
+//   - in 'workerd' mode the background loop() is disabled (a frozen isolate
+//     must not run a timer) and an immediate push is not lost: flushQueueWork()
+//     drains it before the (simulated) response
+//   - the queue() consumer can resolve a core handler by name (no undefined ack)
+//
+// These supersede the deleted cloudflare/tests/shims/queue-{scheduled,delayed-
+// persist}.spec.ts: those probed the removed cloudflare/shims/queue.ts duplicate
+// engine (D1 + CF-Queue-send + inline-fallback). Under the canonical node engine
+// the worker never sends to CF Queue (immediate jobs run in-isolate via fastq),
+// so those CF-Queue-fallback scenarios no longer exist; due-delayed dispatch is
+// covered here by dispatchDueJobs().
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Sequelize } from 'sequelize';
+import { SequelizeStorage, Umzug } from 'umzug';
+
+import { withTenant, getInstanceDid } from '../../src/libs/context';
+import {
+  setQueueRuntimeMode,
+  getQueueHandler,
+  getAllQueueNames,
+  dispatchDueJobs,
+  flushQueueWork,
+  __test__ as runtimeTest,
+} from '../../src/libs/queue/runtime';
+
+/* eslint-disable global-require, require-await, no-promise-executor-return */
+
+// delayed/retry cases do real per-attempt DB ops on a shared sqlite file; give
+// the suite a generous timeout (I/O-bound, not hung).
+jest.setTimeout(30000);
+
+jest.mock('../../src/libs/logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() },
+}));
+
+const STORE_DIR = path.join(__dirname, '../../src/store');
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'queue-runtime-'));
+const sequelize = new Sequelize({ dialect: 'sqlite', storage: path.join(dir, 'test.db'), logging: false });
+const umzug = new Umzug({
+  migrations: {
+    glob: ['migrations/*.ts', { cwd: STORE_DIR }],
+    resolve: ({ name, path: p, context }) => {
+      const migration = require(p!);
+      return {
+        name: name.replace(/\.ts$/, '.js'),
+        up: () => migration.up({ context }),
+        down: () => migration.down({ context }),
+      };
+    },
+  },
+  context: sequelize.getQueryInterface(),
+  storage: new SequelizeStorage({ sequelize }),
+  logger: undefined,
+});
+
+let createQueue: any;
+const TENANT_A = 'did:abt:zRUNTIMEA';
+const TENANT_B = 'did:abt:zRUNTIMEB';
+
+const settle = (emitter: any): Promise<{ event: string; data: any }> =>
+  new Promise((resolve) => {
+    ['finished', 'failed', 'cancelled'].forEach((e) => emitter.on(e, (data: any) => resolve({ event: e, data })));
+  });
+
+beforeAll(async () => {
+  await umzug.up();
+  const models = require('../../src/store/models');
+  models.initialize(sequelize);
+  createQueue = require('../../src/libs/queue').default;
+}, 120000);
+
+afterAll(async () => {
+  await sequelize.close();
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+beforeEach(async () => {
+  await sequelize.query('DELETE FROM jobs');
+  setQueueRuntimeMode('node');
+});
+
+afterEach(() => {
+  // clears the registry + restores 'node' so each test is self-contained
+  runtimeTest.reset();
+});
+
+describe('registry + consumer lookup', () => {
+  it('createQueue registers the handle into the runtime registry (non-empty)', () => {
+    const name = `reg-${Date.now()}`;
+    const q = createQueue({ name, onJob: async () => undefined });
+    expect(getAllQueueNames()).toContain(name);
+    expect(getQueueHandler(name)).toBe(q);
+  });
+
+  it('the queue() consumer resolves a core handler by name and runs onJob once (no undefined ack)', async () => {
+    let runs = 0;
+    const name = `consume-${Date.now()}`;
+    createQueue({ name, onJob: async () => { runs += 1; return 'ok'; } });
+
+    const handle = getQueueHandler(name);
+    expect(handle).toBeTruthy();
+    const res: any = await withTenant(TENANT_A, async () =>
+      handle.pushAndWait({ job: { v: 1, instance_did: TENANT_A } })
+    );
+    expect(res.result).toBe('ok');
+    expect(runs).toBe(1);
+  });
+});
+
+describe('scheduled dispatch (delay) parity — host-driven dispatchDueJobs()', () => {
+  it("'workerd' mode disables the background loop (no auto-dispatch)", async () => {
+    setQueueRuntimeMode('workerd');
+    let ran = 0;
+    const name = `wd-loop-${Date.now()}`;
+    const q = createQueue({ name, onJob: async () => { ran += 1; }, options: { enableScheduledJob: true } });
+    // a due delayed row sitting in D1
+    await q.store.addJob('wd-1', { v: 1, instance_did: TENANT_A }, { delay: 5, will_run_at: Date.now() - 1000 });
+    // a node loop would have polled + run it by now; workerd must not
+    await new Promise((r) => setTimeout(r, 60));
+    expect(ran).toBe(0);
+  });
+
+  it('a due delayed job dispatches and executes exactly once via dispatchDueJobs()', async () => {
+    setQueueRuntimeMode('workerd');
+    let ran = 0;
+    const seenTenant: string[] = [];
+    const name = `wd-due-${Date.now()}`;
+    const q = createQueue({
+      name,
+      onJob: async () => { ran += 1; seenTenant.push(getInstanceDid()); },
+      options: { enableScheduledJob: true },
+    });
+    await q.store.addJob('due-1', { v: 1, instance_did: TENANT_A }, { delay: 5, will_run_at: Date.now() - 1000 });
+
+    const r = await dispatchDueJobs();
+    await flushQueueWork(); // drain the re-dispatched immediate execution
+
+    expect(r.dispatched).toBe(1);
+    expect(ran).toBe(1);
+    expect(seenTenant).toEqual([TENANT_A]); // ran under the payload tenant
+    // row cleared after success
+    expect(await q.store.getJob('due-1')).toBeNull();
+  });
+
+  it('a cancelled delayed job is NOT executed by dispatchDueJobs() (no half-execution residue)', async () => {
+    setQueueRuntimeMode('workerd');
+    let ran = 0;
+    const name = `wd-cancel-${Date.now()}`;
+    const q = createQueue({ name, onJob: async () => { ran += 1; }, options: { enableScheduledJob: true } });
+    await q.store.addJob('c-1', { v: 1, instance_did: TENANT_A }, { delay: 5, will_run_at: Date.now() - 1000 });
+    await q.cancel('c-1'); // marks cancelled=true BEFORE the due-dispatch tick
+
+    const r = await dispatchDueJobs();
+    await flushQueueWork();
+
+    expect(r.dispatched).toBe(0);
+    expect(ran).toBe(0);
+  });
+
+  it('node entry: a cancelled delayed row is excluded from due dispatch (same filter both entries use)', async () => {
+    setQueueRuntimeMode('node');
+    // no enableScheduledJob → no background loop leaks; we assert the exact
+    // store filter (cancelled:false) that BOTH the node loop() and the workerd
+    // dispatchDueJobs() select due rows with, so cancel parity is structural.
+    const q = createQueue({ name: `node-cancel-${Date.now()}`, onJob: async () => undefined });
+    await q.store.addJob('nc-1', { v: 1, instance_did: TENANT_A }, { delay: 5, will_run_at: Date.now() - 1000 });
+    expect((await q.store.getScheduledJobs()).some((j: any) => j.id === 'nc-1')).toBe(true);
+    await q.cancel('nc-1');
+    expect((await q.store.getScheduledJobs()).some((j: any) => j.id === 'nc-1')).toBe(false);
+  });
+});
+
+describe('retry / nonRetryable parity (node engine semantics)', () => {
+  it('retries up to maxRetries then fails (initial + retries, no infinite loop)', async () => {
+    let attempts = 0;
+    const q = createQueue({
+      name: `rt-retry-${Date.now()}`,
+      onJob: async () => { attempts += 1; throw new Error('always'); },
+      options: { maxRetries: 3, retryDelay: 1 },
+    });
+    const ev = q.push({ job: { v: 1, instance_did: TENANT_A } });
+    const { event } = await settle(ev);
+    expect(event).toBe('failed');
+    expect(attempts).toBe(3);
+  });
+
+  it('a nonRetryable error fails immediately (single attempt)', async () => {
+    let attempts = 0;
+    const q = createQueue({
+      name: `rt-nonretry-${Date.now()}`,
+      onJob: async () => {
+        attempts += 1;
+        const err: any = new Error('forged');
+        err.nonRetryable = true;
+        throw err;
+      },
+      options: { maxRetries: 5, retryDelay: 1 },
+    });
+    const ev = q.push({ job: { v: 1, instance_did: TENANT_A } });
+    const { event } = await settle(ev);
+    expect(event).toBe('failed');
+    expect(attempts).toBe(1);
+  });
+});
+
+describe('tenant safety', () => {
+  it('handler runs under the payload tenant; a cross-tenant object is fail-closed', async () => {
+    const { assertJobObjectTenant } = require('../../src/libs/queue');
+    let leaked = false;
+    let observedTenant = '';
+    const q = createQueue({
+      name: `tn-${Date.now()}`,
+      onJob: async (_job: any) => {
+        observedTenant = getInstanceDid();
+        // simulate an object loaded cross-tenant (payload says A, row says B)
+        assertJobObjectTenant({ instance_did: TENANT_B });
+        leaked = true; // must be unreachable — assert throws first
+      },
+    });
+    const ev = await withTenant(TENANT_A, async () => q.push({ job: { tag: 'x' } }));
+    const { event } = await settle(ev);
+    expect(observedTenant).toBe(TENANT_A);
+    expect(leaked).toBe(false);
+    expect(event).toBe('failed');
+  });
+});
+
+describe('workerd flush — immediate push not lost', () => {
+  it('flushQueueWork() drains an in-flight immediate push before the response', async () => {
+    setQueueRuntimeMode('workerd');
+    let ran = 0;
+    const q = createQueue({ name: `flush-${Date.now()}`, onJob: async () => { ran += 1; } });
+    // fire-and-forget immediate push (the worker does this inside a request)
+    q.push({ job: { v: 1, instance_did: TENANT_A } });
+    // simulate the host draining before the isolate freezes
+    await flushQueueWork();
+    expect(ran).toBe(1);
+  });
+
+  it('flushQueueWork() is a no-op on node (nothing tracked, returns immediately)', async () => {
+    setQueueRuntimeMode('node');
+    await expect(flushQueueWork()).resolves.toBeUndefined();
+  });
+
+  it('a duplicate immediate push does not hang flushQueueWork() (tracker released on addJob failure)', async () => {
+    setQueueRuntimeMode('workerd');
+    let runs = 0;
+    const q = createQueue({ name: `flush-dup-${Date.now()}`, onJob: async () => { runs += 1; } });
+    q.push({ job: { v: 1, instance_did: TENANT_A }, id: 'dup-flush' });
+    q.push({ job: { v: 1, instance_did: TENANT_A }, id: 'dup-flush' }); // duplicate → never enqueues
+    // must resolve, not hang on the never-settling duplicate
+    await flushQueueWork();
+    expect(runs).toBe(1);
+  });
+});
+
+describe('test harness sanity', () => {
+  it('runtime __test__.reset clears the registry', () => {
+    createQueue({ name: `sanity-${Date.now()}`, onJob: async () => undefined });
+    expect(runtimeTest.registrySize()).toBeGreaterThan(0);
+  });
+});

package/api/tests/queues/queue-teardown-d2.spec.ts

@@ -0,0 +1,127 @@
+// D2 (S3.0) — the node queue poll loop is cancelable. On a Node host the
+// per-scheduled-queue loop() polls due delayed rows on a timer; lifecycle.stop()
+// calls stopAllQueues() so no poll timer survives a stop / ARC_PAYMENT toggle
+// (the spec's "active handles 归零"). This proves: (1) the loop self-dispatches a
+// due job on node, (2) after stopAllQueues() it no longer dispatches AND its
+// sleep timer is gone.
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Sequelize } from 'sequelize';
+import { SequelizeStorage, Umzug } from 'umzug';
+
+import { withTenant } from '../../src/libs/context';
+import { setQueueRuntimeMode, stopAllQueues, __test__ as runtimeTest } from '../../src/libs/queue/runtime';
+
+jest.setTimeout(30000);
+
+jest.mock('../../src/libs/logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() },
+}));
+
+const STORE_DIR = path.join(__dirname, '../../src/store');
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'queue-teardown-'));
+const sequelize = new Sequelize({ dialect: 'sqlite', storage: path.join(dir, 'test.db'), logging: false });
+const umzug = new Umzug({
+  migrations: {
+    glob: ['migrations/*.ts', { cwd: STORE_DIR }],
+    resolve: ({ name, path: p, context }) => {
+      const migration = require(p!);
+      return {
+        name: name.replace(/\.ts$/, '.js'),
+        up: () => migration.up({ context }),
+        down: () => migration.down({ context }),
+      };
+    },
+  },
+  context: sequelize.getQueryInterface(),
+  storage: new SequelizeStorage({ sequelize }),
+  logger: undefined,
+});
+
+let createQueue: any;
+const TENANT = 'did:abt:zTEARDOWNA';
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+const countTimers = () =>
+  (process as any).getActiveResourcesInfo().filter((r: string) => r === 'Timeout').length;
+
+beforeAll(async () => {
+  await umzug.up();
+  const models = require('../../src/store/models');
+  models.initialize(sequelize);
+  createQueue = require('../../src/libs/queue').default;
+}, 120000);
+
+afterAll(async () => {
+  await sequelize.close();
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+beforeEach(async () => {
+  await sequelize.query('DELETE FROM jobs');
+  setQueueRuntimeMode('node');
+});
+
+afterEach(() => {
+  stopAllQueues();
+  runtimeTest.reset();
+});
+
+describe('D2 — node queue loop self-dispatches a due delayed job (positive)', () => {
+  it('a due delayed row is picked up by the node loop with no host tick', async () => {
+    let ran = 0;
+    const name = `loop-pos-${Date.now()}`;
+    const q = createQueue({
+      name,
+      onJob: async () => {
+        ran += 1;
+      },
+      options: { enableScheduledJob: true },
+    });
+    await q.store.addJob('due-1', { v: 1, instance_did: TENANT }, { delay: 5, will_run_at: Date.now() - 1000 });
+    await wait(1600); // loop polls every minDelay/2 = 1s in test env
+    expect(ran).toBeGreaterThanOrEqual(1);
+  });
+});
+
+describe('D2 — stopAllQueues() stops the loop and clears its timer (teardown)', () => {
+  it('after stopAllQueues() a due delayed row is NOT auto-dispatched', async () => {
+    let ran = 0;
+    const name = `loop-stop-${Date.now()}`;
+    const q = createQueue({
+      name,
+      onJob: async () => {
+        ran += 1;
+      },
+      options: { enableScheduledJob: true },
+    });
+    const withLoop = countTimers();
+    stopAllQueues(); // teardown before the first tick fires
+    const afterStop = countTimers();
+    // the loop's pending sleep timer is gone
+    expect(afterStop).toBeLessThan(withLoop);
+
+    await q.store.addJob('due-2', { v: 1, instance_did: TENANT }, { delay: 5, will_run_at: Date.now() - 1000 });
+    await wait(1600);
+    expect(ran).toBe(0); // loop is dead — nothing dispatched it
+  });
+
+  it('the queue handle exposes a stop() function', () => {
+    const q = createQueue({
+      name: `has-stop-${Date.now()}`,
+      onJob: async () => {},
+      options: { enableScheduledJob: true },
+    });
+    expect(typeof q.stop).toBe('function');
+  });
+
+  it('pushAndWait still works after a stop (immediate path unaffected by loop teardown)', async () => {
+    const name = `imm-${Date.now()}`;
+    const q = createQueue({ name, onJob: async () => 'ok', options: { enableScheduledJob: true } });
+    stopAllQueues();
+    const res: any = await withTenant(TENANT, async () => q.pushAndWait({ job: { v: 1, instance_did: TENANT } }));
+    expect(res.result).toBe('ok');
+  });
+});