cursedbelt 2.7.0 → 3.0.0

package/src/server/drivers/retentionPolicy.pg.test.ts

@@ -1,103 +0,0 @@
-/**
- * The retention policy table against a REAL Postgres (D30).
- *
- * `retentionPolicy.spec.ts` proves the behavior over SQLite and runs on every
- * gate. Three things only an engine can answer for, each of which fails by
- * producing a plausible WRONG value rather than an error:
- *
- *   * **`retain_days` is `bigint` on Postgres** (the `toPostgresDdl` mapping for
- *     `INTEGER`), and Bun's driver hands a bigint back as a **string**. A
- *     comparison like `days > 0` against `"30"` is true, and `days === 30` is
- *     false — so a policy read that skipped the coercion would turn the sweep
- *     off in exactly the deployment that configured it.
- *   * **`{{now}}` renders as `to_char(now() …)` here and `strftime` there.** The
- *     provenance stamp has to be an ISO-8601 string in both.
- *   * **The upsert is `ON CONFLICT (subject) DO UPDATE`** over a control-plane
- *     table, reached through `createPooledControlExecutor` — the same executor
- *     the sweep uses, and the same one the FORCE-RLS trap would silently defeat.
- *
- * SKIPPED, loudly, when `CC_PG_URL` is absent — a skip is a missing proof.
- */
-import { SQL } from 'bun';
-import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'bun:test';
-import { toPostgresDdl, type SaasConnection, type SaasPool, type StatementExecutor } from 'cwip/storage';
-import { createPooledControlExecutor } from './pooledControlStores';
-import {
-  readRetentionPolicy,
-  RETENTION_POLICY_DDL,
-  RETENTION_POLICY_DEFAULTS,
-  RETENTION_POLICY_TABLE,
-  setRetentionWindow,
-} from './retentionPolicy';
-
-const URL_ = process.env.CC_PG_URL;
-
-let sql: SQL;
-let executor: StatementExecutor;
-
-// SKIPPED unless CC_PG_URL names a throwaway Postgres — this suite's subject IS the engine. `bun run test:pg` supplies one.
-describe.skipIf(!URL_)('the retention policy table against a real Postgres (D30)', () => {
-  beforeAll(async () => {
-    sql = new SQL(URL_ as string);
-    const connection: SaasConnection = {
-      async query<R>(text: string, params: readonly unknown[] = []): Promise<R[]> {
-        return (await sql.unsafe(text, [...params])) as R[];
-      },
-      async execute(text: string, params: readonly unknown[] = []) {
-        const result = await sql.unsafe(text, [...params]);
-        return { rowCount: (result as { count?: number }).count ?? 0 };
-      },
-    };
-    const pool: SaasPool = {
-      async withConnection(fn) {
-        return await fn(connection);
-      },
-    };
-    executor = createPooledControlExecutor(pool);
-    await sql.unsafe(`DROP TABLE IF EXISTS ${RETENTION_POLICY_TABLE}`);
-    // Through the COMPILER, exactly as `SAAS_CONTROL_PLANE_DDL` does it — a test
-    // that hand-wrote the pg form would prove the hand-written copy, not the
-    // chain a deployment runs.
-    await sql.unsafe(toPostgresDdl(RETENTION_POLICY_DDL));
-  }, 120_000);
-
-  afterAll(async () => {
-    await sql?.close();
-  });
-
-  beforeEach(async () => {
-    await sql.unsafe(`DELETE FROM ${RETENTION_POLICY_TABLE}`);
-  });
-
-  it('reads the defaults from an empty table', async () => {
-    const policy = await readRetentionPolicy(executor);
-    expect(policy.meter).toMatchObject({ retainDays: RETENTION_POLICY_DEFAULTS.meter, source: 'default' });
-  });
-
-  it('🔴 returns retain_days as a NUMBER, not the bigint STRING the driver hands back', async () => {
-    await setRetentionWindow(executor, { subject: 'meter', retainDays: 400, updatedBy: 'cli:pg-test' });
-    const window = (await readRetentionPolicy(executor)).meter;
-    // `toBe(400)` is the assertion — `"400"` would pass a truthiness check, pass
-    // `> 0`, and then fail every comparison the sweep actually makes.
-    expect(window.retainDays).toBe(400);
-    expect(typeof window.retainDays).toBe('number');
-    expect(window.source).toBe('stored');
-  });
-
-  it('stamps `updated_at` from POSTGRES’ clock as an ISO-8601 string', async () => {
-    const window = await setRetentionWindow(executor, { subject: 'audit', retainDays: 120, updatedBy: 'cli:pg-test' });
-    expect(window.updatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
-    // Same rendering as every other `{{now}}` column in this deployment, so a
-    // policy change can be lined up against the audit row it explains.
-    const drift = Math.abs(Date.parse(window.updatedAt as string) - Date.now());
-    expect(drift).toBeLessThan(60_000);
-  });
-
-  it('upserts in place — `ON CONFLICT (subject) DO UPDATE`, one row per subject', async () => {
-    await setRetentionWindow(executor, { subject: 'meter', retainDays: 30, updatedBy: 'env:CC_METER_RETENTION_DAYS' });
-    await setRetentionWindow(executor, { subject: 'meter', retainDays: 400, updatedBy: 'cli:curt' });
-    const rows = (await sql.unsafe(`SELECT COUNT(*)::int AS n FROM ${RETENTION_POLICY_TABLE}`)) as Array<{ n: number }>;
-    expect(rows[0]?.n).toBe(1);
-    expect((await readRetentionPolicy(executor)).meter).toMatchObject({ retainDays: 400, updatedBy: 'cli:curt' });
-  });
-});

package/src/server/drivers/retentionPolicy.spec.ts

@@ -1,110 +0,0 @@
-/**
- * The retention WINDOWS as stored state (owner decision D30).
- *
- * Over a real SQLite engine, not a fake executor — the two claims that matter
- * ("an absent row reads as the default, and says so" and "a write records the
- * DATABASE's own time") are claims about what an engine did. The Postgres half —
- * the same upsert through the control executor, where `{{now}}` renders as
- * `to_char(now() …)` and `retain_days` comes back as a bigint STRING — is
- * `retentionPolicy.pg.test.ts`.
- */
-import { Database } from 'bun:sqlite';
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import { createSqliteExecutor, type StatementExecutor } from 'cwip/storage';
-import {
-  assertRetainDays,
-  describeRetentionWindow,
-  ensureRetentionPolicySchema,
-  readRetentionPolicy,
-  RETENTION_MAX_DAYS,
-  RETENTION_OFF,
-  RETENTION_POLICY_DEFAULTS,
-  setRetentionWindow,
-} from './retentionPolicy';
-
-let db: Database;
-let executor: StatementExecutor;
-
-beforeEach(async () => {
-  db = new Database(':memory:');
-  executor = createSqliteExecutor(db as never);
-  await ensureRetentionPolicySchema(executor);
-});
-
-afterEach(() => {
-  db.close();
-});
-
-describe('the retention policy store', () => {
-  it('reads the DEFAULTS when nothing has been set, and reports the source as such', async () => {
-    const policy = await readRetentionPolicy(executor);
-    expect(policy.meter).toMatchObject({ retainDays: RETENTION_POLICY_DEFAULTS.meter, source: 'default' });
-    expect(policy.audit).toMatchObject({ retainDays: RETENTION_POLICY_DEFAULTS.audit, source: 'default' });
-    // The distinction is the whole point of `source`: "30 days because that is
-    // the default" and "30 days because the owner picked it" are very different
-    // states to be in when a customer disputes a charge.
-    expect(policy.meter.updatedBy).toBeUndefined();
-  });
-
-  it('D30: the meter default is 30 days — one month, pre-revenue', () => {
-    // Pinned as a test rather than left to a constant nobody re-reads: this
-    // number is an OWNER decision (D30), and a silent edit of it changes how
-    // long billing evidence survives in every deployment that never set one.
-    expect(RETENTION_POLICY_DEFAULTS.meter).toBe(30);
-    expect(RETENTION_POLICY_DEFAULTS.audit).toBe(90);
-  });
-
-  it('stores a window with its provenance, and reads it back as `stored`', async () => {
-    const written = await setRetentionWindow(executor, { subject: 'meter', retainDays: 400, updatedBy: 'cli:curt' });
-    expect(written).toMatchObject({ subject: 'meter', retainDays: 400, source: 'stored', updatedBy: 'cli:curt' });
-    // The DATABASE clock, not this process': an ISO-8601 stamp the sweep's own
-    // log lines can be lined up against.
-    expect(written.updatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
-
-    const policy = await readRetentionPolicy(executor);
-    expect(policy.meter.retainDays).toBe(400);
-    // Setting one subject leaves the other on its default rather than
-    // materialising a row nobody chose.
-    expect(policy.audit.source).toBe('default');
-  });
-
-  it('overwrites in place — one row per subject, and the LAST writer is the one on record', async () => {
-    await setRetentionWindow(executor, { subject: 'meter', retainDays: 30, updatedBy: 'env:CC_METER_RETENTION_DAYS' });
-    await setRetentionWindow(executor, { subject: 'meter', retainDays: 400, updatedBy: 'cli:curt' });
-    const rows = db.query('SELECT COUNT(*) AS n FROM cc_retention_policy').get() as { n: number };
-    expect(rows.n).toBe(1);
-    expect((await readRetentionPolicy(executor)).meter).toMatchObject({ retainDays: 400, updatedBy: 'cli:curt' });
-  });
-
-  it('OFF is a stored decision, not an absent row', async () => {
-    const off = await setRetentionWindow(executor, { subject: 'meter', retainDays: RETENTION_OFF, updatedBy: 'cli:curt' });
-    expect(off).toMatchObject({ retainDays: RETENTION_OFF, source: 'stored' });
-    expect(describeRetentionWindow(off)).toContain('OFF (never swept)');
-  });
-
-  it('🔴 REFUSES a window between OFF and one day — the worst typo available at this keyboard', () => {
-    // `--set-meter-days 0` must mean "stop sweeping", never "delete every row
-    // ever written including the one from a second ago". Those two readings are
-    // one keystroke apart, so the range between them is closed.
-    expect(() => assertRetainDays('meter', -1)).toThrow(/refused/);
-    expect(() => assertRetainDays('meter', 0.5)).toThrow(/whole number/);
-    expect(() => assertRetainDays('meter', RETENTION_MAX_DAYS + 1)).toThrow(/extra digit/);
-    expect(assertRetainDays('meter', RETENTION_OFF)).toBe(RETENTION_OFF);
-    expect(assertRetainDays('meter', 1)).toBe(1);
-  });
-
-  it('refuses an anonymous write — "who changed it" is the first question asked afterwards', async () => {
-    await expect(setRetentionWindow(executor, { subject: 'meter', retainDays: 400, updatedBy: '   ' })).rejects.toThrow(
-      /non-empty `updatedBy`/,
-    );
-  });
-
-  it('ignores a subject the code no longer knows, rather than crashing the sweep', async () => {
-    // A future rename, or a row written by a newer node during a rolling deploy.
-    // The sweep must still run on the subjects it does understand.
-    db.query("INSERT INTO cc_retention_policy (subject, retain_days, updated_at, updated_by) VALUES ('telemetry', 7, '2026-01-01T00:00:00.000Z', 'cli')").run();
-    const policy = await readRetentionPolicy(executor);
-    expect(Object.keys(policy).sort()).toEqual(['audit', 'meter']);
-    expect(policy.meter.source).toBe('default');
-  });
-});

package/src/server/drivers/retentionPolicy.ts

@@ -1,242 +0,0 @@
-/**
- * The retention WINDOWS, as state a deployment can read and change — owner
- * decision **D30**.
- *
- * ## What D30 actually asked for
- *
- * The previous arc landed {@link runRetentionJob} with the meter sweep OFF and
- * the window taken from `CC_METER_RETENTION_DAYS` on a cron line, and escalated
- * the number as a billing decision. The answer was *"Option A (400 days), but
- * make that an admin setting or something that I can stay on top of, then make
- * it be 1 month for now, so I can enable the 13 month version when this has
- * finally made real sales and accounts."*
- *
- * Two requirements, and the first is the one that changes the design: a number
- * living only in a crontab is not something anyone can stay on top of. Nothing
- * can show it, nothing records when it last changed, and the only way to read it
- * is to find the machine that runs the job. So the window becomes a ROW in the
- * control plane, with provenance, and `retention --show` prints it.
- *
- * ## One source of truth, and the env var is a WRITER rather than a rival
- *
- * The sweep reads the stored row and nothing else. `CC_METER_RETENTION_DAYS`
- * still works, but it is applied as an explicit {@link setRetentionWindow} with
- * `updatedBy: "env:CC_METER_RETENTION_DAYS"` *before* the sweep — so a deployment
- * that keeps its number in a cron line still gets a table that says the truth,
- * and `--show` can never disagree with what the last sweep actually used. Two
- * rules about one number means the untested one wins; this is one rule plus a
- * recorded writer.
- *
- * ## Why 30 days is the default and 400 is not
- *
- * A deleted meter row is a bill you can no longer justify to a customer, so 400
- * days (13 months — any monthly invoice re-derivable plus a month of slack for a
- * late dispute) remains the RECOMMENDED window for a deployment with real
- * revenue, and {@link RETENTION_RECOMMENDED_METER_DAYS} names it. Until then the
- * owner's answer is 30: pre-revenue, the rows are development traffic, nobody
- * will ever dispute one, and an unbounded table is the failure that actually
- * threatens the deployment. Raising it later is one `--set-meter-days 400`.
- *
- * ## A floor exists, and it is not a style preference
- *
- * {@link RETENTION_MIN_DAYS} refuses a window under a day. `--set-meter-days 0`
- * would not be "sweep aggressively", it would be *delete every row ever written
- * including the one from a second ago*, which is the single worst typo available
- * at this keyboard. Turning a sweep OFF is spelled {@link RETENTION_OFF} — a
- * distinct value, so "off" and "delete everything" cannot be one fat-finger
- * apart.
- */
-import type { StatementExecutor } from 'cwip/storage';
-
-/** The two append-only tables E35/D25 left growing. Extend deliberately: every
- *  subject added here is a new class of row somebody may need to produce later. */
-export type RetentionSubject = 'audit' | 'meter';
-
-export const RETENTION_SUBJECTS: readonly RetentionSubject[] = ['audit', 'meter'];
-
-/** Windows below this are refused — see the header. A day is already extreme. */
-export const RETENTION_MIN_DAYS = 1;
-
-/**
- * The sentinel for "do not sweep this table at all", stored as a real row so
- * that OFF is a decision somebody made on a date rather than an absent row that
- * could equally mean "never configured".
- */
-export const RETENTION_OFF = 0;
-
-/** A century. A window past this is a typo (an extra digit), not a policy. */
-export const RETENTION_MAX_DAYS = 36_500;
-
-/**
- * What a deployment gets before anyone sets anything.
- *
- * `audit: 90` matches `AUDIT_TRAIL_RETENTION_MS` and the local profile's
- * per-node janitor, so the two profiles keep entries for the same time.
- * `meter: 30` is D30's answer for the pre-revenue phase; see the header.
- */
-export const RETENTION_POLICY_DEFAULTS: Readonly<Record<RetentionSubject, number>> = {
-  audit: 90,
-  meter: 30,
-};
-
-/** The window to move the meter to once invoices are real. Named so the runbook,
- *  the CLI hint and the report cannot each quote a different number. */
-export const RETENTION_RECOMMENDED_METER_DAYS = 400;
-
-export const RETENTION_POLICY_TABLE = 'cc_retention_policy';
-
-/**
- * Authored for SQLite and compiled to Postgres by `toPostgresDdl`, like every
- * other control-plane table — one authored schema cannot drift from itself.
- *
- * `updated_by` is NOT NULL with no default on purpose: every write to this table
- * is somebody changing how long billing evidence survives, and "who" is the
- * first question anyone asks afterwards. `"env:CC_METER_RETENTION_DAYS"` and
- * `"cli"` are both real answers; an empty string is not.
- */
-export const RETENTION_POLICY_DDL = `CREATE TABLE IF NOT EXISTS ${RETENTION_POLICY_TABLE} (
-  subject TEXT PRIMARY KEY NOT NULL,
-  retain_days INTEGER NOT NULL,
-  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
-  updated_by TEXT NOT NULL
-)`;
-
-export interface RetentionWindow {
-  readonly subject: RetentionSubject;
-  /** Days of history kept. {@link RETENTION_OFF} ⇒ this table is not swept. */
-  readonly retainDays: number;
-  /**
-   * `'default'` means no row exists — the deployment is running on
-   * {@link RETENTION_POLICY_DEFAULTS} and nobody has ever chosen. The CLI says
-   * so out loud, because "30 days because that is the default" and "30 days
-   * because the owner picked it" are very different states to be in when a
-   * customer disputes a charge.
-   */
-  readonly source: 'default' | 'stored';
-  readonly updatedAt?: string;
-  readonly updatedBy?: string;
-}
-
-/**
- * The set of billing/audit retention WINDOWS a deployment runs with — one per
- * subject. Named `RetentionWindows` (not `RetentionPolicy`) since DEDUP-8(c):
- * the canonical fleet `RetentionPolicy` is the category-based opt-in design in
- * `cursedbelt/server/retention`, and this billing-evidence concern is
- * deliberately distinct — a meter row is a bill you must keep, not diagnostic
- * data an owner can lose, so it is not expressible as a retention category.
- */
-export type RetentionWindows = Readonly<Record<RetentionSubject, RetentionWindow>>;
-
-interface PolicyRow {
-  readonly subject: string;
-  readonly retain_days: number | string;
-  readonly updated_at: string;
-  readonly updated_by: string;
-}
-
-const isSubject = (value: string): value is RetentionSubject =>
-  (RETENTION_SUBJECTS as readonly string[]).includes(value);
-
-/**
- * Validate a proposed window, or throw naming the bound it broke.
- *
- * Exported because the CLI validates argv before it opens a pool: refusing
- * `--set-meter-days -1` should not depend on a database being reachable.
- */
-export const assertRetainDays = (subject: RetentionSubject, retainDays: number): number => {
-  if (!Number.isInteger(retainDays))
-    throw new Error(`The ${subject} retention window must be a whole number of days, got ${JSON.stringify(retainDays)}.`);
-  if (retainDays === RETENTION_OFF) return RETENTION_OFF;
-  if (retainDays < RETENTION_MIN_DAYS)
-    throw new Error(
-      `A ${subject} retention window of ${retainDays} days is refused. Use ${RETENTION_OFF} to turn the sweep OFF; anything between that and ${RETENTION_MIN_DAYS} would delete rows written moments ago.`,
-    );
-  if (retainDays > RETENTION_MAX_DAYS)
-    throw new Error(`A ${subject} retention window of ${retainDays} days is past the ${RETENTION_MAX_DAYS}-day ceiling — that is an extra digit, not a policy.`);
-  return retainDays;
-};
-
-/** Create the policy table if it is absent. Ships inside `SAAS_CONTROL_PLANE_DDL`
- *  too, so a deployment that runs the documented migration step needs no extra
- *  call; this exists for tests and for a SQLite-backed operator tool. */
-export const ensureRetentionPolicySchema = async (executor: StatementExecutor): Promise<void> => {
-  await executor.write({ sql: RETENTION_POLICY_DDL });
-};
-
-/**
- * Read every window, filling absent subjects from
- * {@link RETENTION_POLICY_DEFAULTS}.
- *
- * One statement for the whole policy: two subjects today, and a per-subject
- * `get` would make the read cost grow with a list this module expects to extend.
- */
-export const readRetentionPolicy = async (executor: StatementExecutor): Promise<RetentionWindows> => {
-  const rows = await executor.all<PolicyRow>({
-    sql: `SELECT subject, retain_days, updated_at, updated_by FROM ${RETENTION_POLICY_TABLE}`,
-  });
-  const stored = new Map<RetentionSubject, PolicyRow>();
-  for (const row of rows) if (isSubject(row.subject)) stored.set(row.subject, row);
-
-  const policy = {} as Record<RetentionSubject, RetentionWindow>;
-  for (const subject of RETENTION_SUBJECTS) {
-    const row = stored.get(subject);
-    policy[subject] =
-      row === undefined
-        ? { subject, retainDays: RETENTION_POLICY_DEFAULTS[subject], source: 'default' }
-        : {
-            subject,
-            // A pg `bigint` arrives as a string. `Number` here rather than at the
-            // call site, so no caller can compare a window against a string and
-            // silently always lose.
-            retainDays: Number(row.retain_days),
-            source: 'stored',
-            updatedAt: row.updated_at,
-            updatedBy: row.updated_by,
-          };
-  }
-  return policy;
-};
-
-/**
- * Set one window, recording who did it and when — by the DATABASE clock, for the
- * same reason the sweep's cutoff uses it: two nodes and the database disagree
- * about the time, and a provenance record stamped by whichever machine happened
- * to run the CLI is a record nobody can line up against the sweep's own logs.
- */
-export const setRetentionWindow = async (
-  executor: StatementExecutor,
-  options: { readonly subject: RetentionSubject; readonly retainDays: number; readonly updatedBy: string },
-): Promise<RetentionWindow> => {
-  const retainDays = assertRetainDays(options.subject, options.retainDays);
-  const updatedBy = options.updatedBy.trim();
-  if (updatedBy.length === 0)
-    throw new Error('setRetentionWindow requires a non-empty `updatedBy` — "who changed how long billing evidence survives" is the first question asked afterwards.');
-
-  await executor.write({
-    sql: `INSERT INTO ${RETENTION_POLICY_TABLE} (subject, retain_days, updated_at, updated_by)
-          VALUES (?, ?, {{now}}, ?)
-          ON CONFLICT (subject) DO UPDATE SET
-            retain_days = excluded.retain_days,
-            updated_at = excluded.updated_at,
-            updated_by = excluded.updated_by`,
-    params: [options.subject, retainDays, updatedBy],
-  });
-
-  const policy = await readRetentionPolicy(executor);
-  return policy[options.subject];
-};
-
-/**
- * The line an operator reads. Same text in `--show` and in the sweep's own log,
- * so a scheduled run and a hand check cannot describe the deployment
- * differently.
- */
-export const describeRetentionWindow = (window: RetentionWindow): string => {
-  const value =
-    window.retainDays === RETENTION_OFF ? 'OFF (never swept)' : `${window.retainDays} day${window.retainDays === 1 ? '' : 's'}`;
-  const provenance =
-    window.source === 'default'
-      ? 'default — nobody has chosen yet'
-      : `set by ${window.updatedBy ?? 'unknown'} at ${window.updatedAt ?? 'unknown'}`;
-  return `${window.subject.padEnd(6)} ${value.padEnd(20)} (${provenance})`;
-};

package/src/server/drivers/saasJobBroker.ts

@@ -1,221 +0,0 @@
-/**
- * SaaS profile `JobBroker` (03 §7.3) — stateless workers, at-least-once leases,
- * durable cross-process completion.
- *
- * cursedbelt does not depend on Redis, BullMQ or any hosted queue: shipping one
- * would put a native/service dependency into a library every generated app
- * links, and the choice is genuinely the deployment's. So the queue is an injected
- * seam ({@link SaasQueueBackend}) — twenty lines of adapter around whatever the
- * deployment runs — while everything that makes completion CORRECT across
- * processes lives here and is shared with the local profile:
- *
- *   * outcomes are recorded in a shared {@link JobResultStore}, never a heap;
- *   * waiting is read-through with an optional push wake, so a waiter on API
- *     node A sees a completion produced by worker B;
- *   * `onComplete` is sugar over that wait, with identical semantics to local.
- *
- * That is the difference between "the interface has a SaaS variant" and "the
- * SaaS variant honors the interface". The previous shape (`onComplete` over an
- * in-memory callback map) could not be honored at all off-process — a caller
- * that worked locally silently stopped receiving completions in production.
- */
-import { AppError } from '../errors';
-import { defaultJobLogger } from '../jobs/logger';
-import type { JobLogger } from '../jobs/types';
-import type { JobBroker, JobId, JobResult, JobSpec } from './jobBroker';
-import {
-  type AwaitCompletionOptions,
-  awaitRecordedCompletion,
-  type JobResultStore,
-  type RecordedJobResult,
-  UNSCOPED_TENANT,
-} from './jobResults';
-
-/** What the broker persists for a worker to pick up. */
-export interface SaasQueuePayload {
-  kind: string;
-  tenantId: string;
-  instanceId?: string;
-  payload: Record<string, unknown>;
-}
-
-/**
- * A payload the backend has DELIVERED to a worker — the persisted envelope plus
- * the queue's own id, which is the {@link JobId} everywhere else. The consumer
- * side of {@link SaasQueueBackend.lease} hands one of these to the processor.
- */
-export interface LeasedJob extends SaasQueuePayload {
-  id: JobId;
-}
-
-/**
- * The worker's processor. Resolving ACKNOWLEDGES the lease (the backend marks
- * the job completed and stops redelivering it); throwing leaves the lease to
- * expire so the backend redelivers per its own retry policy. The processor is
- * expected to have made the outcome durable (recorded in the shared
- * {@link JobResultStore}) BEFORE it resolves — see {@link runSaasJobWorker}.
- */
-export type LeaseProcessor = (job: LeasedJob) => Promise<void>;
-
-export interface LeaseOptions {
-  /** How many leased jobs the backend may run through the processor at once. */
-  concurrency: number;
-}
-
-/**
- * A running lease subscription. {@link LeaseControl.close} DRAINS: it stops
- * accepting new leases and resolves once the jobs already handed to the
- * processor have settled — the graceful-shutdown primitive a deploy needs so a
- * rolling restart does not strand in-flight work (the lease timeout is the
- * backstop for a handler that ignores the drain, never the mechanism).
- */
-export interface LeaseControl {
-  close(): Promise<void>;
-}
-
-/**
- * The deployment's queue. A BullMQ adapter is `add` → `queue.add`, `remove` →
- * `job.remove`, `subscribe` → a `QueueEvents` `completed` listener, and
- * `lease` → a `new Worker(name, processor, { concurrency })`. Nothing else
- * about BullMQ leaks into the framework — see `bullmqQueueAdapter.ts` for the
- * reference wiring of exactly those four calls.
- */
-export interface SaasQueueBackend {
-  /** Enqueue and return the queue's own id — that id is the `JobId` everywhere. */
-  add(payload: SaasQueuePayload, options?: { delayMs?: number }): Promise<JobId>;
-  /**
-   * Best-effort cancellation. A job already leased by a worker cannot be pulled
-   * back; the worker observes the recorded `cancelled` result through its own
-   * handler context, so cancellation is cooperative — same as local.
-   */
-  remove(id: JobId): Promise<void>;
-  /**
-   * Optional push notification that SOME job finished (the id is not needed —
-   * waiters re-read the store). Without it, waiting degrades to pure polling,
-   * which is correct but slower.
-   */
-  subscribe?(onCompletion: () => void): () => void;
-  /**
-   * CONSUMER side — a long-running worker begins leasing payloads and dispatches
-   * each to `process`. The backend owns at-least-once delivery and the
-   * lease/visibility timeout; the framework owns everything that makes
-   * completion correct on top of it ({@link runSaasJobWorker}). Producer-only
-   * deployments (API nodes that enqueue but never execute) never call this, so
-   * it is optional on the seam — an API node's backend can omit it entirely.
-   */
-  lease?(process: LeaseProcessor, options: LeaseOptions): LeaseControl;
-}
-
-export interface SaasJobBrokerOptions {
-  queue: SaasQueueBackend;
-  /** Shared across every API node and worker — Postgres table, Redis hash, … */
-  results: JobResultStore;
-  logger?: JobLogger;
-  /** Read-through interval when no push notification arrives. Default 500ms. */
-  pollMs?: number;
-  /** `onComplete` giving-up horizon. Default 24h. */
-  completionTimeoutMs?: number;
-}
-
-export interface SaasJobBroker extends JobBroker {
-  /**
-   * Called by a WORKER when its handler terminates. Workers are stateless and
-   * own no callback registry; recording the outcome IS the notification, and it
-   * is what every waiting process reads.
-   */
-  recordCompletion(result: RecordedJobResult): Promise<void>;
-  /** Detach the completion subscription. */
-  close(): void;
-}
-
-export const createSaasJobBroker = (options: SaasJobBrokerOptions): SaasJobBroker => {
-  const logger = options.logger ?? defaultJobLogger;
-  const pollMs = options.pollMs ?? 500;
-  const completionTimeoutMs = options.completionTimeoutMs ?? 86_400_000;
-
-  const waiters = new Set<() => void>();
-  const wakeAll = (): void => {
-    for (const wake of [...waiters]) {
-      try {
-        wake();
-      } catch (error) {
-        logger.error('SaaS JobBroker completion waiter threw', error);
-      }
-    }
-  };
-
-  const detach = options.queue.subscribe?.(wakeAll) ?? null;
-
-  const subscribeWaiter = (cb: () => void): (() => void) => {
-    waiters.add(cb);
-    return () => {
-      waiters.delete(cb);
-    };
-  };
-
-  const readResult = async (id: JobId): Promise<JobResult | null> => {
-    const recorded = await options.results.read(id);
-    if (!recorded) return null;
-    return { jobId: recorded.jobId, ok: recorded.ok, output: recorded.output, error: recorded.error };
-  };
-
-  return {
-    async enqueue(job: JobSpec): Promise<JobId> {
-      if (typeof job.kind !== 'string' || job.kind.length === 0)
-        throw new AppError('A JobSpec needs a non-empty `kind` — it is the worker selector.', {
-          code: 'JOB_KIND_UNREGISTERED',
-          status: 500,
-          context: { tenantId: job.tenantId },
-        });
-      return await options.queue.add(
-        { kind: job.kind, tenantId: job.tenantId, instanceId: job.instanceId, payload: job.payload },
-        job.delayMs === undefined ? undefined : { delayMs: job.delayMs },
-      );
-    },
-
-    onComplete(id: JobId, cb: (result: JobResult) => void): void {
-      // One path — see the note on the local broker's `onComplete`.
-      // `awaitRecordedCompletion` reads before it arms anything.
-      void awaitRecordedCompletion(options.results, id, {
-        timeoutMs: completionTimeoutMs,
-        pollMs,
-        subscribe: subscribeWaiter,
-      }).then(
-        (result) => cb({ jobId: result.jobId, ok: result.ok, output: result.output, error: result.error }),
-        (error) => logger.error(`SaaS JobBroker completion wait for ${id} failed`, error),
-      );
-    },
-
-    async awaitCompletion(id: JobId, waitOptions: AwaitCompletionOptions = {}): Promise<JobResult> {
-      const result = await awaitRecordedCompletion(options.results, id, {
-        pollMs,
-        ...waitOptions,
-        subscribe: subscribeWaiter,
-      });
-      return { jobId: result.jobId, ok: result.ok, output: result.output, error: result.error };
-    },
-
-    async cancel(id: JobId): Promise<void> {
-      await options.queue.remove(id);
-      // Record first, then wake: a waiter must never observe the wake without
-      // the row it is being woken for. The `await` is what keeps that ordering
-      // real against a shared store that answers over a network.
-      await options.results.record({ jobId: id, ok: false, error: 'cancelled', tenantId: UNSCOPED_TENANT });
-      wakeAll();
-    },
-
-    async status(id: JobId): Promise<JobResult | { jobId: JobId; ok: null }> {
-      return (await readResult(id)) ?? { jobId: id, ok: null };
-    },
-
-    async recordCompletion(result: RecordedJobResult): Promise<void> {
-      await options.results.record(result);
-      wakeAll();
-    },
-
-    close(): void {
-      detach?.();
-      waiters.clear();
-    },
-  };
-};