cursedbelt 2.7.0 → 3.0.0

package/src/server/runtime/retentionJob.pg.test.ts

@@ -1,151 +0,0 @@
-/**
- * The retention entrypoint against a REAL Postgres (01 §4.3).
- *
- * `retentionJob.spec.ts` proves the BEHAVIOR over SQLite — windows, paging,
- * idempotence, the database-clock cutoff and its negative control — and runs on
- * every gate. What it cannot answer is the half that only an engine can:
- *
- *   * **A control-plane `DELETE` really removes rows.** `cc_meter_events` and
- *     the shared trail carry NO RLS policy on purpose, and are reached through
- *     `createPostgresControlExecutor`. The trap this asserts against is the one
- *     `§D` records: an unscoped statement under `FORCE ROW LEVEL SECURITY`
- *     **silently deletes nothing and reports success**, so a naïve
- *     implementation prunes zero rows and every log line says it worked. Hence
- *     the assertion is a NON-ZERO delete count, never merely "it did not throw".
- *   * **`to_char(now() …)` compares against the stored `at`.** The cutoff is a
- *     lexicographic comparison on an ISO-8601 string produced by two different
- *     `{{now}}` renderings; SQLite agreeing proves nothing about Postgres.
- *   * **`DELETE … WHERE event_uuid IN (SELECT … LIMIT ?)`** — `DELETE … LIMIT`
- *     is not valid Postgres at all, and this is the form both dialects run.
- *
- *   bun run test:pg          (starts a disposable container, runs, tears down)
- *   CC_PG_URL=postgres://…   (or point it at any throwaway database)
- *
- * SKIPPED, loudly, when `CC_PG_URL` is absent — a skip is a missing proof, never
- * a passing one.
- */
-import { SQL } from 'bun';
-import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'bun:test';
-import {
-  AUDIT_TRAIL_TABLE,
-  createStatementAuditTrailStore,
-  ensureAuditTrailSchema,
-  type SaasConnection,
-  type SaasPool,
-  type StatementExecutor,
-} from 'cwip/storage';
-import { ensureSharedMeterSchema, SHARED_METER_TABLE } from 'cwip/telemetry';
-import { createPooledControlExecutor } from '../drivers/pooledControlStores';
-import { runRetentionJob } from './retentionJob';
-
-const URL_ = process.env.CC_PG_URL;
-const TENANT = 't_pg_retention';
-const DAY_MS = 24 * 60 * 60 * 1000;
-
-let sql: SQL;
-let pool: SaasPool;
-let executor: StatementExecutor;
-
-const daysAgo = (days: number): string => new Date(Date.now() - days * DAY_MS).toISOString();
-
-const insertMeterRow = async (uuid: string, days: number): Promise<void> => {
-  await sql.unsafe(
-    `INSERT INTO ${SHARED_METER_TABLE} (event_uuid, at, tenant_id, metric, qty, meta, row_signature, node_id, local_id)
-     VALUES ($1, $2, $3, 'storage.bytes', 1, '{}', 'sig', 'node-a', 1)`,
-    [uuid, daysAgo(days), TENANT],
-  );
-};
-
-const meterCount = async (): Promise<number> =>
-  Number(((await sql.unsafe(`SELECT COUNT(*)::int AS n FROM ${SHARED_METER_TABLE}`)) as Array<{ n: number }>)[0]?.n ?? -1);
-const auditCount = async (): Promise<number> =>
-  Number(((await sql.unsafe(`SELECT COUNT(*)::int AS n FROM ${AUDIT_TRAIL_TABLE}`)) as Array<{ n: number }>)[0]?.n ?? -1);
-
-// 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 job against a real Postgres (01 §4)', () => {
-  // 120s rather than Bun's 5s, for the reason the sibling pg suites record: this
-  // hook issues real DDL, and on a shared runner a timeout surfaces as a
-  // misleading mid-migration connection close rather than as "the hook was slow".
-  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 };
-      },
-    };
-    pool = {
-      async withConnection(fn) {
-        return await fn(connection);
-      },
-    };
-    executor = createPooledControlExecutor(pool);
-    await sql.unsafe(`DROP TABLE IF EXISTS ${SHARED_METER_TABLE}`);
-    await sql.unsafe(`DROP TABLE IF EXISTS ${AUDIT_TRAIL_TABLE}`);
-    await ensureSharedMeterSchema(executor);
-    await ensureAuditTrailSchema(executor);
-  }, 120_000);
-
-  afterAll(async () => {
-    await sql?.close();
-  });
-
-  beforeEach(async () => {
-    await sql.unsafe(`DELETE FROM ${SHARED_METER_TABLE}`);
-    await sql.unsafe(`DELETE FROM ${AUDIT_TRAIL_TABLE}`);
-  });
-
-  it('deletes a NON-ZERO number of rows — the FORCE-RLS trap, asserted against', async () => {
-    await insertMeterRow('pg-old-1', 500);
-    await insertMeterRow('pg-old-2', 500);
-    await insertMeterRow('pg-fresh', 10);
-
-    const sink = createStatementAuditTrailStore(executor);
-    for (let i = 0; i < 3; i += 1)
-      await sink.record({ tenantId: TENANT, action: 'k.item.create', domain: 'knowledge', profile: 'saas', actor: 'u1', inTransaction: false });
-    await sql.unsafe(`UPDATE ${AUDIT_TRAIL_TABLE} SET at = $1 WHERE id IN (SELECT id FROM ${AUDIT_TRAIL_TABLE} ORDER BY id ASC LIMIT 2)`, [
-      daysAgo(200),
-    ]);
-
-    const result = await runRetentionJob({
-      auditTrail: { sink, retainDays: 90 },
-      meterEvents: { executor, retainDays: 400 },
-    });
-
-    expect(result.errors).toEqual([]);
-    // NON-ZERO, on both, and that is the whole point of running this here: a
-    // sweep that silently matched nothing would also report `errors: []`.
-    expect(result.meterRowsDeleted).toBe(2);
-    expect(result.auditRowsDeleted).toBe(2);
-    expect(await meterCount()).toBe(1);
-    expect(await auditCount()).toBe(1);
-  });
-
-  it('is idempotent — a second pass over the same window removes nothing', async () => {
-    await insertMeterRow('pg-old', 500);
-    expect((await runRetentionJob({ meterEvents: { executor, retainDays: 400 } })).meterRowsDeleted).toBe(1);
-    expect((await runRetentionJob({ meterEvents: { executor, retainDays: 400 } })).meterRowsDeleted).toBe(0);
-  });
-
-  it('pages through a sweep larger than one pass — `DELETE … LIMIT` is not valid Postgres', async () => {
-    for (let i = 0; i < 5; i += 1) await insertMeterRow(`pg-page-${i}`, 500);
-    const result = await runRetentionJob({ meterEvents: { executor, retainDays: 400, pageLimit: 2 } });
-    expect(result.errors).toEqual([]);
-    expect(result.meterRowsDeleted).toBe(5);
-    expect(await meterCount()).toBe(0);
-  });
-
-  it('reads the cutoff from POSTGRES’ clock, not this process’ — `to_char(now() …)` against a stored `at`', async () => {
-    // The window brackets the row from both sides in two runs: 500 days old, a
-    // 600-day window keeps it and a 400-day window removes it. If the cutoff
-    // expression rendered wrong for this dialect, one of the two would be wrong.
-    await insertMeterRow('pg-bracket', 500);
-    expect((await runRetentionJob({ meterEvents: { executor, retainDays: 600 } })).meterRowsDeleted).toBe(0);
-    expect(await meterCount()).toBe(1);
-    expect((await runRetentionJob({ meterEvents: { executor, retainDays: 400 } })).meterRowsDeleted).toBe(1);
-    expect(await meterCount()).toBe(0);
-  });
-});

package/src/server/runtime/retentionJob.spec.ts

@@ -1,187 +0,0 @@
-/**
- * The retention entrypoint (01 §4) — the program E35 named and nobody wrote.
- *
- * Every case here is over a real SQLite engine rather than a fake executor, for
- * the reason `§D` records twice: a probe that asserts against its OWN fixture is
- * a tautology, and the two claims that matter — "the cutoff comes from the
- * DATABASE clock" and "a second run is a no-op" — are both claims about what an
- * engine did, not about what a function returned. The Postgres half (the
- * non-zero delete count under a control executor) is `retentionJob.pg.test.ts`.
- */
-import { Database } from 'bun:sqlite';
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import {
-  createSqliteExecutor,
-  createStatementAuditTrailStore,
-  ensureAuditTrailSchema,
-  AUDIT_TRAIL_TABLE,
-  type AuditTrailSink,
-  type StatementExecutor,
-} from 'cwip/storage';
-import { ensureSharedMeterSchema, SHARED_METER_TABLE } from 'cwip/telemetry';
-import { runRetentionJob } from './retentionJob';
-
-const TENANT = 'tenant-a';
-const DAY_MS = 24 * 60 * 60 * 1000;
-
-let db: Database;
-let executor: StatementExecutor;
-let sink: AuditTrailSink;
-
-/** Backdate the audit rows an interceptor just wrote — `at` is written by the
- *  database's own `{{now}}`, so ageing them is the only way to make a cutoff
- *  bite inside a test that runs in milliseconds. */
-const backdateAudit = (daysAgo: number, howMany: number): void => {
-  const at = new Date(Date.now() - daysAgo * DAY_MS).toISOString();
-  db.query(`UPDATE ${AUDIT_TRAIL_TABLE} SET at = ? WHERE id IN (SELECT id FROM ${AUDIT_TRAIL_TABLE} ORDER BY id ASC LIMIT ?)`).run(
-    at,
-    howMany,
-  );
-};
-
-const insertMeterRow = (uuid: string, daysAgo: number): void => {
-  db.query(
-    `INSERT INTO ${SHARED_METER_TABLE} (event_uuid, at, tenant_id, metric, qty, meta, row_signature, node_id, local_id)
-     VALUES (?, ?, ?, 'storage.bytes', 1, '{}', 'sig', 'node-a', 1)`,
-  ).run(uuid, new Date(Date.now() - daysAgo * DAY_MS).toISOString(), TENANT);
-};
-
-const auditCount = (): number =>
-  (db.query(`SELECT COUNT(*) AS n FROM ${AUDIT_TRAIL_TABLE}`).get() as { n: number }).n;
-const meterCount = (): number =>
-  (db.query(`SELECT COUNT(*) AS n FROM ${SHARED_METER_TABLE}`).get() as { n: number }).n;
-
-beforeEach(async () => {
-  db = new Database(':memory:');
-  executor = createSqliteExecutor(db as never);
-  await ensureAuditTrailSchema(executor);
-  await ensureSharedMeterSchema(executor);
-  sink = createStatementAuditTrailStore(executor);
-});
-
-afterEach(() => {
-  db.close();
-});
-
-describe('runRetentionJob', () => {
-  it('deletes what is past the window and keeps what is inside it — both tables', async () => {
-    for (let i = 0; i < 5; i += 1)
-      await sink.record({ tenantId: TENANT, action: 'k.item.create', domain: 'knowledge', profile: 'saas', actor: 'u1', inTransaction: false });
-    backdateAudit(200, 3); // three old, two fresh
-
-    insertMeterRow('m-old-1', 500);
-    insertMeterRow('m-old-2', 500);
-    insertMeterRow('m-fresh', 10);
-
-    const result = await runRetentionJob({
-      auditTrail: { sink, retainDays: 90 },
-      meterEvents: { executor, retainDays: 400 },
-    });
-
-    expect(result.errors).toEqual([]);
-    expect(result.auditRowsDeleted).toBe(3);
-    expect(result.meterRowsDeleted).toBe(2);
-    expect(auditCount()).toBe(2);
-    expect(meterCount()).toBe(1);
-  });
-
-  it('a second run is a NO-OP — the predicate is an age, so there is nothing left to find', async () => {
-    await sink.record({ tenantId: TENANT, action: 'k.item.create', domain: 'knowledge', profile: 'saas', actor: 'u1', inTransaction: false });
-    backdateAudit(200, 1);
-    insertMeterRow('m-old', 500);
-
-    const first = await runRetentionJob({ auditTrail: { sink, retainDays: 90 }, meterEvents: { executor, retainDays: 400 } });
-    const second = await runRetentionJob({ auditTrail: { sink, retainDays: 90 }, meterEvents: { executor, retainDays: 400 } });
-
-    expect(first).toMatchObject({ auditRowsDeleted: 1, meterRowsDeleted: 1 });
-    expect(second).toMatchObject({ auditRowsDeleted: 0, meterRowsDeleted: 0, errors: [] });
-  });
-
-  it('OMITTING meterEvents sweeps no meter rows — the safe default a first deployment gets', async () => {
-    // 01 §4.2(b): a deleted meter row is a bill you can no longer justify to a
-    // customer, so the window is an owner decision and this module will not make
-    // it silently. `retainDays` is required and the whole block is optional.
-    insertMeterRow('m-ancient', 5_000);
-    const result = await runRetentionJob({ auditTrail: { sink, retainDays: 90 } });
-    expect(result.meterRowsDeleted).toBe(0);
-    expect(meterCount()).toBe(1);
-  });
-
-  it('pages a sweep larger than one pass, rather than one unbounded DELETE', async () => {
-    // The lock argument, made testable: with `pageLimit: 2` and 5 eligible rows
-    // the loop must run three passes and still report 5.
-    for (let i = 0; i < 5; i += 1) insertMeterRow(`m-${i}`, 500);
-    const result = await runRetentionJob({ meterEvents: { executor, retainDays: 400, pageLimit: 2 } });
-    expect(result.meterRowsDeleted).toBe(5);
-    expect(meterCount()).toBe(0);
-  });
-
-  it('REFUSES a sink that cannot prune, rather than sweeping nothing and reporting success', async () => {
-    const shipper: AuditTrailSink = { record: async () => {}, read: async () => [] };
-    const result = await runRetentionJob({ auditTrail: { sink: shipper, retainDays: 90 } });
-    expect(result.auditRowsDeleted).toBe(0);
-    expect(result.errors).toHaveLength(1);
-    expect(result.errors[0]?.message).toMatch(/implements no `prune`/);
-  });
-
-  it('collects both sweeps’ errors instead of letting one jammed table stop the other', async () => {
-    const shipper: AuditTrailSink = { record: async () => {}, read: async () => [] };
-    insertMeterRow('m-old', 500);
-    const result = await runRetentionJob({
-      auditTrail: { sink: shipper, retainDays: 90 },
-      meterEvents: { executor, retainDays: 400 },
-    });
-    // The audit sweep failed and the meter sweep still ran.
-    expect(result.errors).toHaveLength(1);
-    expect(result.meterRowsDeleted).toBe(1);
-  });
-
-  it('reads the cutoff from the DATABASE clock — substituting the process clock changes the answer', async () => {
-    // 🔴 The falsification `01 §4.3` demands, with numbers chosen so the two
-    // clocks genuinely disagree about this row: the database is skewed 3 days
-    // FAST, the row is 88 days old by the process clock, and the window is 90.
-    // Process clock ⇒ 88 < 90 ⇒ keep. Database clock ⇒ 91 > 90 ⇒ delete. A
-    // 30-vs-45 style pair would pass under either and prove nothing.
-    insertMeterRow('m-borderline', 88);
-
-    const skewed: StatementExecutor = {
-      dialect: executor.dialect,
-      all: (statement) => executor.all(statement),
-      write: (statement) => executor.write(statement),
-      get: async <Row>(statement: { sql: string }) => {
-        if (statement.sql.includes('{{now}}'))
-          return { now: new Date(Date.now() + 3 * DAY_MS).toISOString() } as Row;
-        return executor.get<Row>(statement as never);
-      },
-    } as StatementExecutor;
-
-    expect(await runRetentionJob({ meterEvents: { executor: skewed, retainDays: 90 } })).toMatchObject({
-      meterRowsDeleted: 1,
-    });
-    expect(meterCount()).toBe(0);
-
-    // The negative control, and the half that makes the test an assertion rather
-    // than a coincidence: with the UNSKEWED database clock the same row survives.
-    insertMeterRow('m-borderline-2', 88);
-    expect(await runRetentionJob({ meterEvents: { executor, retainDays: 90 } })).toMatchObject({
-      meterRowsDeleted: 0,
-    });
-    expect(meterCount()).toBe(1);
-  });
-
-  it('refuses to delete when the database clock is unreadable', async () => {
-    insertMeterRow('m-old', 500);
-    const blind: StatementExecutor = {
-      dialect: executor.dialect,
-      all: (statement) => executor.all(statement),
-      write: (statement) => executor.write(statement),
-      get: async () => null,
-    } as StatementExecutor;
-
-    const result = await runRetentionJob({ meterEvents: { executor: blind, retainDays: 400 } });
-    expect(result.errors[0]?.message).toMatch(/could not read the database clock/);
-    // Refusing means the row is still there — a cutoff of `NaN` that deleted
-    // everything would be the worst possible reading of "the clock is broken".
-    expect(meterCount()).toBe(1);
-  });
-});

package/src/server/runtime/retentionJob.ts

@@ -1,237 +0,0 @@
-/**
- * The maintenance pass a saas DEPLOYMENT schedules — E35's "a cron beside the
- * migrations", the thing that decision named and nobody built.
- *
- * ## What was wrong
- *
- * Owner decision E35/D25 turned the audit trail ON by default in every
- * generated app: one row per mutation, forever, unless something prunes it.
- * Under `profile: "local"` the emitted `server.ts` wires a real
- * `createAuditTrailRetention` janitor and that is correct. Under
- * `profile: "saas"` — the profile that targets a real multi-tenant deployment —
- * the emitted code was a COMMENT explaining that retention belongs to the
- * deployment. The reasoning is right and the program did not exist: no script,
- * no workflow, no runbook entry, no entrypoint. And `cc_meter_events` had no
- * retention on any profile at all; a grep for a DELETE, a prune, a vacuum or a
- * retention against it returned nothing. Two unbounded append-only tables, both
- * on by default, both on the shared profile.
- *
- * ## Why an ENTRYPOINT and not a timer
- *
- * N nodes each sweeping one shared table is N times the work for one outcome.
- * That is exactly why the per-node janitor is right under `local` and wrong
- * under `saas`, and it is why this module exports a function a scheduler calls
- * rather than something that installs an interval. Nothing here holds the
- * process open; there is nothing to `unref`.
- *
- * ## Three properties, each load-bearing
- *
- *   * **The cutoff comes from the DATABASE clock, never `Date.now()`.** Asked
- *     for with one extra statement per pass, exactly as `AuditTrailSink.prune`
- *     already does it. When two nodes and the database disagree about the time —
- *     and they do — a process-clock cutoff means each runner deletes a different
- *     set and neither can say which.
- *   * **The predicate is an AGE, not a cursor.** An interrupted pass, a restart
- *     mid-sweep, and two concurrent runners all converge on the same set. There
- *     is no position to lose and nothing to reconcile.
- *   * **Every pass is BOUNDED and resumed by looping.** An unbounded `DELETE`
- *     over a year of a busy deployment's meter is one long write lock on a table
- *     whose writer is every metered action in the app.
- *
- * ## What this deliberately does NOT prune, and why
- *
- * The node-local `meter_events` table. Under saas those rows are shipped to
- * `cc_meter_events` by `createMeterRollup`, whose resume point is
- * `MAX(local_id)` **in the destination** — so a row deleted locally before it
- * ships is not late, it is gone, and the bill for it was never collected. A
- * sweep of the local table would have to know the rollup's high-water mark,
- * which makes it a rollup feature rather than a retention one. Under `local`
- * there is no rollup and the table is genuinely unbounded; that is recorded as
- * an open item rather than fixed by deleting billing evidence on a guess.
- */
-import { AUDIT_TRAIL_PRUNE_LIMIT, type AuditTrailSink, type StatementExecutor } from 'cwip/storage';
-import { SHARED_METER_TABLE } from 'cwip/telemetry';
-
-/** Audit rows kept, in days. Matches `AUDIT_TRAIL_RETENTION_MS` (E35's 90). */
-export const AUDIT_RETAIN_DAYS = 90;
-
-/** Rows one DELETE may remove. Same reasoning — and same number — as
- *  `AUDIT_TRAIL_PRUNE_LIMIT`: a page, then return, so the lock is short. */
-export const RETENTION_PAGE_LIMIT = AUDIT_TRAIL_PRUNE_LIMIT;
-
-/**
- * Passes one sweep may run before giving up and reporting what it did.
- *
- * A backstop, not a budget: at the default page size this is 1,000,000 rows in
- * one invocation, far past any real day's backlog. Its job is to make a bug
- * that leaves rows matching the predicate after deletion (a broken cutoff, a
- * dialect mismatch) terminate and be visible, rather than spin.
- */
-export const RETENTION_MAX_PASSES = 1000;
-
-export interface AuditRetentionOptions {
-  /**
-   * The sink to prune. It must implement `prune` — `createStatementAuditTrailStore`
-   * does; a SIEM shipper deliberately does not, because it no longer owns the
-   * entries. A sink without one is refused rather than swept to no effect.
-   */
-  readonly sink: AuditTrailSink;
-  /** Keep entries younger than this many days. Default {@link AUDIT_RETAIN_DAYS}. */
-  readonly retainDays?: number;
-  /** Rows per pass. Default {@link RETENTION_PAGE_LIMIT}. */
-  readonly pageLimit?: number;
-}
-
-export interface MeterRetentionOptions {
-  /**
-   * A CONTROL-plane executor over the shared pool —
-   * `createSaasHostServices().auditExecutor`, which is the same
-   * `createPooledControlExecutor` the trail uses.
-   *
-   * 🔴 Never a tenant-scoped `createPostgresExecutor`. `cc_meter_events` carries
-   * no RLS policy on purpose (its maintenance verbs are cross-tenant by
-   * design), but the general trap is dispositive elsewhere in this codebase and
-   * would be here the day a policy is added: an unscoped `DELETE` under
-   * `FORCE ROW LEVEL SECURITY` deletes NOTHING and reports success. The pg test
-   * asserts a NON-ZERO delete count for exactly that reason — "it ran" is not
-   * the same claim as "it deleted".
-   */
-  readonly executor: StatementExecutor;
-  /**
-   * Keep meter events younger than this many days. **REQUIRED, with no
-   * default, on purpose.**
-   *
-   * A deleted meter row is a bill you can no longer justify to a customer.
-   * 400 days (13 months — any monthly invoice re-derivable, plus a month of
-   * slack for a dispute) is the recommendation, and it is a BILLING decision
-   * rather than an engineering one, so this module will not make it silently.
-   * A caller that omits `meterEvents` entirely sweeps no meter rows, which is
-   * the safe default a first deployment gets.
-   */
-  readonly retainDays: number;
-  /** Rows per pass. Default {@link RETENTION_PAGE_LIMIT}. */
-  readonly pageLimit?: number;
-}
-
-export interface RetentionJobOptions {
-  /** Omit ⇒ the audit trail is not swept. */
-  readonly auditTrail?: AuditRetentionOptions;
-  /** Omit ⇒ meter events are not swept. See {@link MeterRetentionOptions.retainDays}. */
-  readonly meterEvents?: MeterRetentionOptions;
-}
-
-export interface RetentionJobResult {
-  readonly auditRowsDeleted: number;
-  readonly meterRowsDeleted: number;
-  /**
-   * Failures, collected rather than thrown. One sweep failing must not stop the
-   * other — a locked audit table is not a reason to leave the meter unbounded —
-   * and the caller decides the exit code from a complete picture.
-   */
-  readonly errors: readonly Error[];
-}
-
-const DAY_MS = 24 * 60 * 60 * 1000;
-
-const asError = (cause: unknown): Error => (cause instanceof Error ? cause : new Error(String(cause)));
-
-/**
- * The database's own clock, as the ISO-8601 string both profiles store.
- *
- * `{{now}}` renders per dialect (`strftime` / `to_char(now() …)`), so the cutoff
- * this derives is comparable to the stored `at` column lexicographically — no
- * date parsing in SQL and no dialect divergence in the predicate.
- */
-const databaseNowMs = async (executor: StatementExecutor): Promise<number> => {
-  const clock = await executor.get<{ now: string }>({ sql: 'SELECT {{now}} AS now' });
-  const nowMs = Date.parse(clock?.now ?? '');
-  if (!Number.isFinite(nowMs))
-    throw new Error(
-      `The retention job could not read the database clock (got ${JSON.stringify(clock?.now ?? null)}), so a cutoff cannot be computed. Refusing to delete.`,
-    );
-  return nowMs;
-};
-
-/**
- * Sweep the shared meter table.
- *
- * `DELETE … WHERE event_uuid IN (SELECT … LIMIT ?)` rather than
- * `DELETE … LIMIT ?`: the latter is a SQLite compile-time option (off in Bun's
- * build) and is not valid Postgres at all. The sub-select form is the one both
- * dialects run — the same shape `AuditTrailSink.prune` settled on.
- */
-const pruneMeterEvents = async (options: MeterRetentionOptions): Promise<number> => {
-  const pageLimit = Math.max(1, Math.floor(options.pageLimit ?? RETENTION_PAGE_LIMIT));
-  const retainDays = Math.max(0, options.retainDays);
-  const cutoff = new Date((await databaseNowMs(options.executor)) - retainDays * DAY_MS).toISOString();
-
-  let deleted = 0;
-  for (let pass = 0; pass < RETENTION_MAX_PASSES; pass += 1) {
-    const result = await options.executor.write({
-      sql: `DELETE FROM ${SHARED_METER_TABLE}
-            WHERE event_uuid IN (
-              SELECT event_uuid FROM ${SHARED_METER_TABLE}
-              WHERE at < ?
-              ORDER BY at ASC
-              LIMIT ?
-            )`,
-      params: [cutoff, pageLimit],
-    });
-    deleted += result.changes;
-    // A short page means the predicate is exhausted. Checking the RESULT rather
-    // than re-counting keeps the sweep to one statement per pass.
-    if (result.changes < pageLimit) break;
-  }
-  return deleted;
-};
-
-const pruneAuditTrail = async (options: AuditRetentionOptions): Promise<number> => {
-  const prune = options.sink.prune?.bind(options.sink);
-  if (prune === undefined)
-    throw new Error(
-      'This audit-trail sink implements no `prune`, so a retention sweep over it would delete nothing while reporting success. Either give the sink a prune, or omit `auditTrail` and let whatever owns the entries (an external SIEM, a log shipper) apply its own retention.',
-    );
-  const pageLimit = Math.max(1, Math.floor(options.pageLimit ?? RETENTION_PAGE_LIMIT));
-  const olderThanMs = Math.max(0, options.retainDays ?? AUDIT_RETAIN_DAYS) * DAY_MS;
-
-  let deleted = 0;
-  for (let pass = 0; pass < RETENTION_MAX_PASSES; pass += 1) {
-    const removed = await prune({ olderThanMs, limit: pageLimit });
-    deleted += removed;
-    if (removed < pageLimit) break;
-  }
-  return deleted;
-};
-
-/**
- * Run one maintenance pass. Idempotent — a second run immediately after a first
- * deletes nothing, because the predicate is an age and the first pass already
- * removed everything older than it.
- *
- * Never throws for a sweep failure: both sweeps are attempted and their errors
- * collected, so a caller sees the whole picture and one jammed table cannot
- * leave the other unbounded. It DOES surface a programming error (a sink that
- * cannot prune, an unreadable clock) through the same `errors` array — the
- * emitted `retention.ts` exits non-zero on any entry.
- */
-export const runRetentionJob = async (options: RetentionJobOptions): Promise<RetentionJobResult> => {
-  const errors: Error[] = [];
-  let auditRowsDeleted = 0;
-  let meterRowsDeleted = 0;
-
-  if (options.auditTrail)
-    try {
-      auditRowsDeleted = await pruneAuditTrail(options.auditTrail);
-    } catch (cause) {
-      errors.push(asError(cause));
-    }
-
-  if (options.meterEvents)
-    try {
-      meterRowsDeleted = await pruneMeterEvents(options.meterEvents);
-    } catch (cause) {
-      errors.push(asError(cause));
-    }
-
-  return { auditRowsDeleted, meterRowsDeleted, errors };
-};