payment-kit 1.29.0 → 1.29.2

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');
+  });
+});

package/api/tests/queues/tenant-matrix-a.spec.ts

@@ -0,0 +1,245 @@
+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 { TENANT_CONTEXT_MISSING, TENANT_MISMATCH } from '../../src/libs/tenant';
+import { systemFindByPk } from '../../src/store/scoped';
+import { TENANT_A, TENANT_B } from '../fixtures/tenants';
+
+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(), 'tenant-matrix-a-'));
+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 }) => {
+      // eslint-disable-next-line import/no-dynamic-require, global-require
+      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 models: any;
+let createQueue: any;
+let assertJobObjectTenant: any;
+
+beforeAll(async () => {
+  await umzug.up();
+  // eslint-disable-next-line global-require
+  models = require('../../src/store/models');
+  models.initialize(sequelize);
+  // eslint-disable-next-line global-require
+  const queueModule = require('../../src/libs/queue');
+  createQueue = queueModule.default;
+  assertJobObjectTenant = queueModule.assertJobObjectTenant;
+}, 120000);
+
+afterAll(async () => {
+  await sequelize.close();
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const waitFor = (emitter: any, events: string[]): Promise<{ event: string; data: any }> =>
+  new Promise((resolve) => {
+    for (const event of events) {
+      emitter.on(event, (data: any) => resolve({ event, data }));
+    }
+  });
+
+describe('queue tenant layer — first batch (phase 5)', () => {
+  beforeEach(async () => {
+    await sequelize.query('DELETE FROM customers');
+    await sequelize.query('DELETE FROM jobs');
+  });
+
+  describe('happy path', () => {
+    it('push stamps the active tenant into the payload, job row included, handler runs in that tenant', async () => {
+      const seen: string[] = [];
+      const queue = createQueue({
+        name: `tm-happy-${Date.now()}`,
+        onJob: async (job: any) => {
+          // eslint-disable-next-line global-require
+          const { getInstanceDid } = require('../../src/libs/context');
+          seen.push(job.instance_did, getInstanceDid());
+        },
+      });
+
+      const handle = await withTenant(TENANT_A, async () => queue.push({ job: { businessId: 'x1' }, persist: true }));
+      await waitFor(handle, ['finished', 'failed']);
+      expect(seen).toEqual([TENANT_A, TENANT_A]);
+    });
+
+    it('handler object guard passes for matching tenants', async () => {
+      const customer = await withTenant(TENANT_A, () =>
+        models.Customer.create({ livemode: false, did: 'z-m-a', delinquent: false, instance_did: TENANT_A })
+      );
+      await withTenant(TENANT_A, async () => {
+        expect(() => assertJobObjectTenant(customer)).not.toThrow();
+      });
+    });
+  });
+
+  describe('bad input', () => {
+    it('multi mode push without tenant context is rejected at the gate', async () => {
+      process.env.PAYMENT_TENANT_MODE = 'multi';
+      try {
+        const queue = createQueue({ name: `tm-bad-${Date.now()}`, onJob: async () => {} });
+        expect(() => queue.push({ job: { businessId: 'x' } })).toThrow(
+          expect.objectContaining({ code: TENANT_CONTEXT_MISSING })
+        );
+      } finally {
+        delete process.env.PAYMENT_TENANT_MODE;
+      }
+    });
+
+    it('illegal tenant DID in the payload is refused', () => {
+      const queue = createQueue({ name: `tm-bad2-${Date.now()}`, onJob: async () => {} });
+      expect(() => queue.push({ job: { businessId: 'x', instance_did: 'a b' } })).toThrow(
+        expect.objectContaining({ code: TENANT_CONTEXT_MISSING })
+      );
+    });
+  });
+
+  describe('security: forged payload tenant vs object tenant', () => {
+    it('handler refuses to act on another tenant object; the object is untouched', async () => {
+      const victim = await withTenant(TENANT_B, () =>
+        models.Customer.create({ livemode: false, did: 'z-victim', delinquent: false, instance_did: TENANT_B })
+      );
+
+      let observedError: any;
+      const queue = createQueue({
+        name: `tm-forged-${Date.now()}`,
+        onJob: async (job: any) => {
+          // handlers load the tenant-stamped object cross-tenant (system) then
+          // enforce its tenant — mirrors the real queue handlers so a forged
+          // payload surfaces an observable TENANT_MISMATCH rather than folding
+          // into a scoped null (tenant-design §10).
+          const row: any = await systemFindByPk(models.Customer, job.customerId);
+          assertJobObjectTenant(row); // throws TENANT_MISMATCH
+          await row.update({ name: 'pwned' });
+        },
+      });
+      // forge: payload claims TENANT_A but targets B's customer
+      const handle = await withTenant(TENANT_A, async () =>
+        queue.push({ job: { customerId: victim.id }, persist: true })
+      );
+      const outcome = await waitFor(handle, ['failed', 'finished']);
+      observedError = (outcome.data as any).error;
+
+      expect(outcome.event).toBe('failed');
+      expect(observedError?.code).toBe(TENANT_MISMATCH);
+      const reloaded: any = await systemFindByPk(models.Customer, victim.id);
+      expect(reloaded.name).toBeNull(); // not 'pwned'
+      expect(reloaded.instance_did).toBe(TENANT_B);
+    });
+  });
+
+  describe('data loss: refused jobs surface as failures, not silence', () => {
+    it('the failed event fires with the tenant error attached', async () => {
+      const queue = createQueue({
+        name: `tm-fail-${Date.now()}`,
+        onJob: async () => {
+          const err: any = new Error('refused');
+          err.code = TENANT_MISMATCH;
+          err.nonRetryable = true;
+          throw err;
+        },
+      });
+      const handle = await withTenant(TENANT_A, async () => queue.push({ job: { businessId: 'x' }, persist: true }));
+      const outcome = await waitFor(handle, ['failed', 'finished']);
+      expect(outcome.event).toBe('failed');
+      expect((outcome.data as any).error?.code).toBe(TENANT_MISMATCH);
+    });
+  });
+
+  describe('data damage: retries keep the original tenant', () => {
+    it('a retried job re-executes under the same tenant, never a different one', async () => {
+      const tenantsSeen: string[] = [];
+      const queue = createQueue({
+        name: `tm-retry-${Date.now()}`,
+        onJob: async (job: any) => {
+          tenantsSeen.push(job.instance_did);
+          if (tenantsSeen.length < 2) throw new Error('transient');
+        },
+        options: { maxRetries: 2, retryDelay: 1 },
+      });
+      const handle = await withTenant(TENANT_B, async () => queue.push({ job: { businessId: 'r1' }, persist: true }));
+      await waitFor(handle, ['finished', 'failed']);
+      expect(tenantsSeen.length).toBeGreaterThanOrEqual(2);
+      expect(new Set(tenantsSeen)).toEqual(new Set([TENANT_B]));
+    });
+  });
+
+  // NOTE: spec's "channel-identifier job id prefix" row converts to a no-op
+  // for Phase 5 queues — all job ids are internal globally-unique business
+  // ids (see queue-matrix.md); channel-identifier dedup moves to Phase 6
+  // integrations as (instance_did, identifier) composite keys.
+  describe('data leak: legacy job strategy', () => {
+    it('a pre-tenant job (no instance_did) executes under the default tenant in single mode', async () => {
+      const seen: string[] = [];
+      const queue = createQueue({
+        name: `tm-legacy-${Date.now()}`,
+        onJob: async () => {
+          // eslint-disable-next-line global-require
+          const { getInstanceDid } = require('../../src/libs/context');
+          seen.push(getInstanceDid());
+        },
+      });
+      // simulate a legacy row: bypass push's injection by writing the store directly
+      await queue.store.addJob('legacy-1', { businessId: 'legacy' }, {});
+      const row = await queue.get('legacy-1');
+      expect(row.instance_did).toBeUndefined();
+      // re-deliver it the way startup recovery does (push with persist=false keeps payload as-is? no — push injects)
+      // execution path: runJobWithTenant falls back to the default tenant
+      const handle = queue.push({
+        job: row,
+        id: 'legacy-1',
+        persist: false,
+        skipDuplicateCheck: true,
+        fromStore: true,
+      });
+      await waitFor(handle, ['finished', 'failed']);
+      // eslint-disable-next-line global-require
+      const { getDefaultInstanceDid } = require('../../src/libs/tenant');
+      expect(seen).toEqual([getDefaultInstanceDid()]);
+    });
+
+    it('a legacy job is refused permanently in multi mode (structured, non-retryable)', async () => {
+      const queue = createQueue({
+        name: `tm-legacy-multi-${Date.now()}`,
+        onJob: async () => 'should-not-run',
+      });
+      process.env.PAYMENT_TENANT_MODE = 'multi';
+      try {
+        const handle = queue.push({
+          job: { businessId: 'legacy-multi' },
+          id: 'legacy-multi-1',
+          persist: false,
+          fromStore: true, // store re-delivery path: gate skipped, execution-side refuses
+        });
+        const outcome = await waitFor(handle, ['failed', 'finished']);
+        expect(outcome.event).toBe('failed');
+        expect((outcome.data as any).error?.code).toBe(TENANT_CONTEXT_MISSING);
+        expect((outcome.data as any).error?.nonRetryable).toBe(true);
+      } finally {
+        delete process.env.PAYMENT_TENANT_MODE;
+      }
+    });
+  });
+});