cursedbelt-server 2.0.0 → 3.0.0

package/src/server/d1/sameShape.spec.ts

@@ -0,0 +1,279 @@
+/**
+ * 🔴 The load-bearing test of the whole seam: the local and remote drivers return
+ * IDENTICAL shapes for the same query.
+ *
+ * Every case runs the same SQL through both drivers and compares the results to each
+ * other — not to a hand-written expectation. An expectation written by the same person who
+ * wrote the driver encodes their belief; comparing the two drivers encodes the property
+ * the fleet actually needs, which is that a ported call site cannot tell which side it is
+ * on.
+ *
+ * The remote driver runs against `createFakeD1Binding`, which deliberately reproduces the
+ * four places SQLite drivers disagree (BLOB wire shape, bind strictness, result wrapping,
+ * no interactive transaction). See the header of `./fakeD1` — if that fake ever drifts
+ * toward mirroring our driver, this file stops proving anything.
+ */
+
+import { Database } from 'bun:sqlite';
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { createFakeD1Binding } from './fakeD1';
+import { createLocalD1 } from './local';
+import { createRemoteD1 } from './remote';
+import { D1BindError, type D1LikeBindable, type D1LikeDatabase } from './types';
+
+const DDL = `CREATE TABLE t (
+  id INTEGER PRIMARY KEY,
+  int_col INTEGER,
+  real_col REAL,
+  text_col TEXT,
+  blob_col BLOB,
+  bool_col INTEGER,
+  null_col TEXT
+)`;
+
+/** Two databases with identical contents, one behind each driver. */
+function pair(): { local: D1LikeDatabase; remote: D1LikeDatabase; seed: (sql: string) => void } {
+	const a = new Database(':memory:');
+	const b = new Database(':memory:');
+	a.run(DDL);
+	b.run(DDL);
+	return {
+		local: createLocalD1(a),
+		remote: createRemoteD1(createFakeD1Binding(b)),
+		seed: (sql: string) => {
+			a.run(sql);
+			b.run(sql);
+		},
+	};
+}
+
+/** Run the same statement on both drivers and return both answers. */
+async function both<T>(
+	p: ReturnType<typeof pair>,
+	fn: (db: D1LikeDatabase) => Promise<T>,
+): Promise<{ local: T; remote: T }> {
+	return { local: await fn(p.local), remote: await fn(p.remote) };
+}
+
+describe('local and D1 drivers return identical shapes', () => {
+	let p: ReturnType<typeof pair>;
+	beforeEach(() => {
+		p = pair();
+	});
+
+	// ── the four places SQLite drivers disagree ──────────────────────────────────────
+
+	test('NULL — an absent column is null on both, not undefined and not omitted', async () => {
+		p.seed(`INSERT INTO t (id, int_col, null_col) VALUES (1, 7, NULL)`);
+		const { local, remote } = await both(p, (db) => db.prepare('SELECT * FROM t').all());
+
+		expect(local.results).toEqual(remote.results);
+		expect(local.results[0]).toHaveProperty('null_col', null);
+		// The column must be PRESENT and null — a driver that drops null columns changes
+		// `'null_col' in row` and every `??` downstream of it.
+		expect(Object.keys(local.results[0] as object)).toEqual(Object.keys(remote.results[0] as object));
+	});
+
+	test('BLOB — Uint8Array on both, where D1 natively hands back a number[]', async () => {
+		p.seed(`INSERT INTO t (id, blob_col) VALUES (1, X'00FF107F')`);
+		const { local, remote } = await both(p, (db) => db.prepare('SELECT blob_col FROM t').all());
+
+		const lv = (local.results[0] as { blob_col: unknown }).blob_col;
+		const rv = (remote.results[0] as { blob_col: unknown }).blob_col;
+
+		expect(lv).toBeInstanceOf(Uint8Array);
+		expect(rv).toBeInstanceOf(Uint8Array);
+		expect(Array.from(rv as Uint8Array)).toEqual([0, 255, 16, 127]);
+		expect(lv).toEqual(rv);
+	});
+
+	test('BLOB — an EMPTY blob stays an empty Uint8Array, not null', async () => {
+		// The case a `value ?? null` normalizer gets wrong: an empty array is falsy-adjacent
+		// and an empty Uint8Array is not null.
+		p.seed(`INSERT INTO t (id, blob_col) VALUES (1, X'')`);
+		const { local, remote } = await both(p, (db) => db.prepare('SELECT blob_col FROM t').all());
+		const lv = (local.results[0] as { blob_col: unknown }).blob_col;
+		expect(lv).toBeInstanceOf(Uint8Array);
+		expect((lv as Uint8Array).length).toBe(0);
+		expect(lv).toEqual((remote.results[0] as { blob_col: unknown }).blob_col);
+	});
+
+	test('integer vs float — REAL 1.0 and INTEGER 1 agree across drivers', async () => {
+		p.seed(`INSERT INTO t (id, int_col, real_col) VALUES (1, 1, 1.0)`);
+		p.seed(`INSERT INTO t (id, int_col, real_col) VALUES (2, 2, 2.5)`);
+		const { local, remote } = await both(p, (db) =>
+			db.prepare('SELECT int_col, real_col FROM t ORDER BY id').all(),
+		);
+
+		expect(local.results).toEqual(remote.results);
+		// SQLite stores 1.0 in a REAL column and both drivers surface it as the number 1.
+		// Asserted so a future driver change that started returning "1.0" is caught here.
+		expect(local.results[0]).toEqual({ int_col: 1, real_col: 1 });
+		expect(local.results[1]).toEqual({ int_col: 2, real_col: 2.5 });
+	});
+
+	test('boolean — bound as true/false, stored 1/0, read back identically on both', async () => {
+		const insert = (db: D1LikeDatabase, id: number, v: boolean) =>
+			db.prepare('INSERT INTO t (id, bool_col) VALUES (?, ?)').bind(id, v).run();
+
+		await insert(p.local, 1, true);
+		await insert(p.remote, 1, true);
+		await insert(p.local, 2, false);
+		await insert(p.remote, 2, false);
+
+		const { local, remote } = await both(p, (db) => db.prepare('SELECT id, bool_col FROM t ORDER BY id').all());
+		expect(local.results).toEqual(remote.results);
+		expect(local.results).toEqual([
+			{ id: 1, bool_col: 1 },
+			{ id: 2, bool_col: 0 },
+		]);
+	});
+
+	// ── the strictness that must match, or it is green here and red in production ─────
+
+	test('undefined bind is REFUSED by both, with the same error', async () => {
+		const attempt = async (db: D1LikeDatabase) => {
+			try {
+				await db
+					.prepare('INSERT INTO t (id, text_col) VALUES (?, ?)')
+					.bind(1, undefined as unknown as D1LikeBindable)
+					.run();
+				return 'no error';
+			} catch (e) {
+				return `${(e as Error).name}: ${(e as Error).message}`;
+			}
+		};
+		const local = await attempt(p.local);
+		const remote = await attempt(p.remote);
+
+		// 🔴 `bun:sqlite` alone would have bound NULL here and said nothing, while D1 throws.
+		// That divergence is the defect; identical refusal is the fix.
+		expect(local).toBe(remote);
+		expect(local).toContain('D1BindError');
+		expect(local).toContain('pass null explicitly');
+	});
+
+	test('a Date bind is refused by both, naming the fix', async () => {
+		for (const db of [p.local, p.remote]) {
+			expect(() =>
+				db.prepare('INSERT INTO t (id, text_col) VALUES (?, ?)').bind(1, new Date() as unknown as D1LikeBindable),
+			).toThrow(D1BindError);
+		}
+	});
+
+	test('an out-of-range bigint is refused rather than silently rounded', async () => {
+		// Measured: `bun:sqlite` returns 9007199254740992 for a stored 9007199254740993.
+		for (const db of [p.local, p.remote]) {
+			expect(() => db.prepare('INSERT INTO t (id, int_col) VALUES (1, ?)').bind(9007199254740993n)).toThrow(
+				D1BindError,
+			);
+		}
+		// …and one inside the range is accepted, as a number, on both.
+		const { local, remote } = await both(p, async (db) => {
+			await db.prepare('INSERT INTO t (id, int_col) VALUES (1, ?)').bind(42n).run();
+			return db.prepare('SELECT int_col FROM t').first();
+		});
+		expect(local).toEqual(remote);
+		expect(local).toEqual({ int_col: 42 });
+	});
+
+	// ── result and meta shapes ────────────────────────────────────────────────────────
+
+	test('first() on no rows is null on both, not undefined', async () => {
+		const { local, remote } = await both(p, (db) => db.prepare('SELECT * FROM t WHERE id = 999').first());
+		expect(local).toBeNull();
+		expect(remote).toBeNull();
+	});
+
+	test('all() on no rows is an empty results array on both', async () => {
+		const { local, remote } = await both(p, (db) => db.prepare('SELECT * FROM t WHERE id = 999').all());
+		expect(local.results).toEqual([]);
+		expect(remote.results).toEqual([]);
+		expect(local.success).toBe(remote.success);
+	});
+
+	test('first(column) returns the bare value on both', async () => {
+		p.seed(`INSERT INTO t (id, text_col) VALUES (1, 'hello')`);
+		const { local, remote } = await both(p, (db) => db.prepare('SELECT text_col FROM t').first('text_col'));
+		expect(local).toBe('hello');
+		expect(remote).toBe('hello');
+	});
+
+	test('run() reports the same changes and last_row_id on both', async () => {
+		const { local, remote } = await both(p, (db) =>
+			db.prepare('INSERT INTO t (text_col) VALUES (?)').bind('x').run(),
+		);
+		expect(local.meta.changes).toBe(remote.meta.changes);
+		expect(local.meta.changes).toBe(1);
+		expect(local.meta.last_row_id).toBe(remote.meta.last_row_id);
+		expect(local.meta.last_row_id).toBe(1);
+		expect(local.results).toEqual(remote.results);
+	});
+
+	test('meta carries the same KEYS on both, so a caller can read it blind', async () => {
+		const { local, remote } = await both(p, (db) => db.prepare('SELECT * FROM t').all());
+		expect(Object.keys(local.meta).sort()).toEqual(Object.keys(remote.meta).sort());
+	});
+
+	test('a read reports last_row_id null on both, rather than a misleading 0', async () => {
+		p.seed(`INSERT INTO t (id, int_col) VALUES (1, 1)`);
+		const { local, remote } = await both(p, (db) => db.prepare('SELECT * FROM t').all());
+		expect(local.meta.last_row_id).toBeNull();
+		expect(remote.meta.last_row_id).toBeNull();
+	});
+
+	test('raw() returns positional arrays that match across drivers', async () => {
+		p.seed(`INSERT INTO t (id, text_col, blob_col) VALUES (1, 'a', X'0102')`);
+		const { local, remote } = await both(p, (db) => db.prepare('SELECT id, text_col, blob_col FROM t').raw());
+		expect(local).toEqual(remote);
+		expect(local[0]?.[0]).toBe(1);
+		expect(local[0]?.[1]).toBe('a');
+		expect(local[0]?.[2]).toBeInstanceOf(Uint8Array);
+	});
+
+	test('a round-tripped blob bind survives identically on both', async () => {
+		const bytes = new Uint8Array([0, 1, 254, 255]);
+		const { local, remote } = await both(p, async (db) => {
+			await db.prepare('INSERT INTO t (id, blob_col) VALUES (1, ?)').bind(bytes).run();
+			return db.prepare('SELECT blob_col FROM t').first<{ blob_col: Uint8Array }>();
+		});
+		expect(local?.blob_col).toEqual(remote?.blob_col as Uint8Array);
+		expect(Array.from(local?.blob_col as Uint8Array)).toEqual([0, 1, 254, 255]);
+	});
+
+	// ── batch, which is the only transaction either side has ──────────────────────────
+
+	test('batch() runs every statement and returns one result each, on both', async () => {
+		const { local, remote } = await both(p, async (db) => {
+			const res = await db.batch([
+				db.prepare("INSERT INTO t (id, text_col) VALUES (1, 'a')"),
+				db.prepare("INSERT INTO t (id, text_col) VALUES (2, 'b')"),
+			]);
+			const rows = await db.prepare('SELECT id, text_col FROM t ORDER BY id').all();
+			return { count: res.length, rows: rows.results };
+		});
+		expect(local).toEqual(remote);
+		expect(local.count).toBe(2);
+		expect(local.rows).toEqual([
+			{ id: 1, text_col: 'a' },
+			{ id: 2, text_col: 'b' },
+		]);
+	});
+
+	test('batch() is atomic on both — a failing member rolls the whole batch back', async () => {
+		const attempt = async (db: D1LikeDatabase) => {
+			try {
+				await db.batch([
+					db.prepare("INSERT INTO t (id, text_col) VALUES (1, 'a')"),
+					// Duplicate primary key — fails, and must take the first insert with it.
+					db.prepare("INSERT INTO t (id, text_col) VALUES (1, 'b')"),
+				]);
+			} catch {
+				/* expected */
+			}
+			return (await db.prepare('SELECT COUNT(*) AS n FROM t').first<{ n: number }>())?.n;
+		};
+		expect(await attempt(p.local)).toBe(0);
+		expect(await attempt(p.remote)).toBe(0);
+	});
+});

package/src/server/d1/scheduling.spec.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from 'bun:test';
+import {
+	classifySchedule,
+	cronFieldCount,
+	jobsForCron,
+	type PortableJob,
+	toCronTriggers,
+	toFiveField,
+} from './scheduling';
+
+const job = (name: string, shape: PortableJob['shape']): PortableJob => ({
+	name,
+	shape,
+	run: async () => {},
+});
+
+describe('classifySchedule', () => {
+	test('a nightly backup is a Cron Trigger and costs nothing', () => {
+		const v = classifySchedule({ kind: 'periodic', cron: '0 3 * * *' });
+		expect(v.primitive).toBe('cron-trigger');
+		expect(v.cron).toBe('0 3 * * *');
+		expect(v.estimatedMonthlyUsd).toBe(0);
+	});
+
+	test('a 6-field expression with a fixed seconds column drops it losslessly', () => {
+		// `0 3 * * * *` and `3 * * *` fire at the same wall-clock moments.
+		const v = classifySchedule({ kind: 'periodic', cron: '0 3 * * * *' });
+		expect(v.primitive).toBe('cron-trigger');
+		expect(v.cron).toBe('3 * * * *');
+	});
+
+	test('🔴 a once-per-second job is UNPORTABLE, not silently rounded to a minute', () => {
+		// This repo already declares three jobs as `* * * * * *`. Rounding them up would
+		// make them 60× less frequent in production and nowhere else.
+		const v = classifySchedule({ kind: 'periodic', cron: '* * * * * *' });
+		expect(v.primitive).toBe('unportable');
+		expect(v.cron).toBeNull();
+		expect(v.reason).toContain('one-minute floor');
+	});
+
+	test('a sub-minute STEP is unportable too', () => {
+		const v = classifySchedule({ kind: 'periodic', cron: '*/10 * * * * *' });
+		expect(v.primitive).toBe('unportable');
+	});
+
+	test('work fanned out from a request is a Queue, priced at two operations a message', () => {
+		// 1M operations are included; a delivered message costs one write and one read, so
+		// the free tier covers 500k messages a month, not 1M. Pricing it as one operation
+		// is the mistake that makes Queues look half price.
+		const free = classifySchedule({ kind: 'fanned-out-from-request', expectedPerDay: 16_000 });
+		expect(free.primitive).toBe('queue');
+		expect(free.estimatedMonthlyUsd).toBe(0); // 480k messages → 960k ops, still included
+
+		const paid = classifySchedule({ kind: 'fanned-out-from-request', expectedPerDay: 100_000 });
+		// 3M messages → 6M ops → 5M billable → $2.00
+		expect(paid.estimatedMonthlyUsd).toBeCloseTo(2.0, 4);
+	});
+
+	test('per-entity scheduling is a Durable Object Alarm', () => {
+		const v = classifySchedule({ kind: 'per-entity' });
+		expect(v.primitive).toBe('durable-object-alarm');
+		expect(v.reason).toContain('scan every row');
+	});
+});
+
+describe('cron helpers', () => {
+	test('cronFieldCount tolerates ragged whitespace', () => {
+		expect(cronFieldCount('  0   3 * * *  ')).toBe(5);
+		expect(cronFieldCount('0 0 3 * * *')).toBe(6);
+	});
+
+	test('toFiveField leaves a 5-field expression alone', () => {
+		expect(toFiveField('0 3 * * *')).toEqual({ cron: '0 3 * * *', lossless: true });
+	});
+});
+
+describe('toCronTriggers', () => {
+	test('renders the wrangler triggers block, de-duplicating shared expressions', () => {
+		const { crons, queues } = toCronTriggers([
+			job('backup', { kind: 'periodic', cron: '0 3 * * *' }),
+			job('metrics-flush', { kind: 'periodic', cron: '0 3 * * *' }),
+			job('thumbnails', { kind: 'fanned-out-from-request', expectedPerDay: 10 }),
+		]);
+		expect(crons).toEqual(['0 3 * * *']);
+		expect(queues).toEqual(['thumbnails']);
+	});
+
+	test('🔴 THROWS on an unportable job rather than quietly omitting it', () => {
+		// A generated config that drops a job is a job that stops running in production
+		// while every local test still passes.
+		expect(() =>
+			toCronTriggers([job('poller', { kind: 'periodic', cron: '* * * * * *' })]),
+		).toThrow(/cannot be expressed/);
+	});
+});
+
+describe('jobsForCron', () => {
+	test('🔴 both jobs sharing an expression are returned, not just the first', () => {
+		// Cloudflare dispatches by EXPRESSION, not by job name: two jobs on `0 3 * * *`
+		// arrive as ONE event. A handler that ran the first match would silently never run
+		// the second.
+		const jobs = [
+			job('backup', { kind: 'periodic', cron: '0 3 * * *' }),
+			job('metrics-flush', { kind: 'periodic', cron: '0 3 * * *' }),
+			job('hourly', { kind: 'periodic', cron: '0 * * * *' }),
+		];
+		expect(jobsForCron(jobs, '0 3 * * *').map((j) => j.name)).toEqual(['backup', 'metrics-flush']);
+		expect(jobsForCron(jobs, '0 * * * *').map((j) => j.name)).toEqual(['hourly']);
+	});
+
+	test('a 6-field declaration is matched by its rendered 5-field expression', () => {
+		const jobs = [job('nightly', { kind: 'periodic', cron: '0 3 * * * *' })];
+		expect(jobsForCron(jobs, '3 * * * *').map((j) => j.name)).toEqual(['nightly']);
+	});
+
+	test('a queue job is never dispatched by a cron event', () => {
+		const jobs = [job('thumbs', { kind: 'fanned-out-from-request' })];
+		expect(jobsForCron(jobs, '0 3 * * *')).toEqual([]);
+	});
+});

package/src/server/d1/scheduling.ts

@@ -0,0 +1,210 @@
+/**
+ * `plainjob` → the Workers answer, and the choice is measured rather than guessed.
+ *
+ * ## What `plainjob` actually is, and why a Worker cannot have it
+ *
+ * An in-process SQLite job queue that POLLS a table on a timer. A Worker has no background
+ * loop: it exists for the duration of a request or a scheduled event and then stops. There
+ * is no timer to hang a poller off, so the mechanism does not port — it is replaced.
+ *
+ * ## 🔴 The measurement that makes this cheaper than the task file assumed
+ *
+ * Re-measured 2026-09-16 over `apps/` and `libs/`: all **12** `plainjob` files are in
+ * `libs/` (ten in `cursedbelt-server`, two in `cursedbelt-cc`), and **zero** are in
+ * `apps/`. No app declares a job through this engine yet. The original table read "12
+ * files using plainjob" as twelve call sites to port; they are one mechanism in one
+ * library, which is this seam. The port is a library change, not a fleet sweep.
+ *
+ * That also means the shape below is free to be the right one rather than the compatible
+ * one — there is no app-side caller to keep happy.
+ *
+ * ## The three primitives, and the rule for choosing
+ *
+ * | primitive | cost | when it is the answer |
+ * |---|---|---|
+ * | **Cron Triggers** | free | anything periodic at ≥ 1-minute cadence. Nightly backups and ingests — most of this fleet |
+ * | **Queues** | $0.40/M operations, 1M included | work fanned out FROM a request, where the response must not wait |
+ * | **Durable Object Alarms** | DO pricing | per-entity scheduling: one timer per row, set from the row's own lifecycle |
+ *
+ * 🔴 **The hard discriminator is cadence, and it is a real cliff.** Cloudflare Cron
+ * Triggers take a **5-field** expression with a **one-minute floor**. `JobDef.cron` accepts
+ * a 6-field expression with a leading seconds column, and this repo already contains three
+ * jobs declared `'* * * * * *'` — once per second. Those cannot become Cron Triggers at
+ * all, and {@link classifySchedule} says so by name instead of silently rounding them up to
+ * a minute, which would change behaviour in production and nowhere else.
+ */
+
+import type { D1LikeDatabase } from './types';
+
+/** The Workers primitive a piece of scheduled work maps onto. */
+export type WorkersPrimitive = 'cron-trigger' | 'queue' | 'durable-object-alarm' | 'unportable';
+
+/** How a job is triggered — the input to the choice, not the choice itself. */
+export type TriggerShape =
+	| { kind: 'periodic'; cron: string }
+	| { kind: 'fanned-out-from-request'; expectedPerDay?: number }
+	| { kind: 'per-entity' };
+
+export interface ScheduleVerdict {
+	primitive: WorkersPrimitive;
+	/** Why — quoted into the port task, so the next reader sees the reasoning not the answer. */
+	reason: string;
+	/** The 5-field expression to put in `wrangler.toml`, when there is one. */
+	cron: string | null;
+	/** Monthly cost at the stated volume, in US dollars. */
+	estimatedMonthlyUsd: number;
+}
+
+/** Cloudflare Queues: $0.40 per million operations, first million free each month. */
+const QUEUE_USD_PER_MILLION = 0.4;
+const QUEUE_FREE_OPERATIONS = 1_000_000;
+
+/**
+ * A cron expression with six fields carries a leading SECONDS column. Cloudflare has no
+ * such column and no cadence below one minute.
+ */
+export function cronFieldCount(cron: string): number {
+	return cron.trim().split(/\s+/).filter(Boolean).length;
+}
+
+/**
+ * Drop the seconds column from a 6-field expression, reporting whether doing so changes
+ * when the job fires. `'0 3 * * * *'` is 3 a.m. daily either way; `'* * * * * *'` is not.
+ */
+export function toFiveField(cron: string): { cron: string; lossless: boolean } {
+	const parts = cron.trim().split(/\s+/).filter(Boolean);
+	if (parts.length <= 5) return { cron: parts.join(' '), lossless: true };
+	const [seconds, ...rest] = parts;
+	// Only a fixed single second (`0`, `30`, …) survives the drop: it means "once, at that
+	// second of the matching minute", which a minute-granularity trigger reproduces. A
+	// wildcard or a step means sub-minute cadence, which it cannot.
+	const lossless = /^\d+$/.test(seconds ?? '');
+	return { cron: rest.join(' '), lossless };
+}
+
+/**
+ * Choose the Workers primitive for a piece of scheduled work.
+ *
+ * Returns `'unportable'` rather than a best guess when the cadence is below Cloudflare's
+ * floor — a job that silently became 60× less frequent in production would be found by a
+ * user, not by a check.
+ */
+export function classifySchedule(shape: TriggerShape): ScheduleVerdict {
+	switch (shape.kind) {
+		case 'periodic': {
+			const fields = cronFieldCount(shape.cron);
+			const { cron, lossless } = toFiveField(shape.cron);
+			if (fields > 5 && !lossless) {
+				return {
+					primitive: 'unportable',
+					reason:
+						`'${shape.cron}' fires below Cloudflare's one-minute floor. A Cron Trigger cannot express it. ` +
+						'Either relax the cadence to ≥ 1 minute, or keep this job on a host with a real timer ' +
+						'(it is a poller, and a poller is usually a Queue consumer in disguise).',
+					cron: null,
+					estimatedMonthlyUsd: 0,
+				};
+			}
+			return {
+				primitive: 'cron-trigger',
+				reason:
+					'Periodic at ≥ 1-minute cadence — a Cron Trigger, which is free and needs no table, no poll ' +
+					'and no process. This is most of the fleet: nightly backups, ingests and metric flushes.',
+				cron,
+				estimatedMonthlyUsd: 0,
+			};
+		}
+
+		case 'fanned-out-from-request': {
+			const perMonth = (shape.expectedPerDay ?? 0) * 30;
+			// Each message is counted on write and on read, so a delivered message is two
+			// operations. Pricing it as one is the mistake that makes Queues look half price.
+			const operations = perMonth * 2;
+			const billable = Math.max(0, operations - QUEUE_FREE_OPERATIONS);
+			return {
+				primitive: 'queue',
+				reason:
+					'Work fanned out from a request, where the response must not wait for it. A Queue decouples the ' +
+					'two and retries on failure. 1M operations are included each month; a delivered message costs two ' +
+					'(one write, one read).',
+				cron: null,
+				estimatedMonthlyUsd: Number(((billable / 1_000_000) * QUEUE_USD_PER_MILLION).toFixed(4)),
+			};
+		}
+
+		case 'per-entity':
+			return {
+				primitive: 'durable-object-alarm',
+				reason:
+					'One timer per entity, set from that entity’s own lifecycle — a reminder on a row, a lease that ' +
+					'expires. A Cron Trigger would have to scan every row every minute to find the few that are due; ' +
+					'an alarm is woken only for the one that is.',
+				cron: null,
+				// A DO is only billed for the requests and duration it actually uses; an idle
+				// alarm costs nothing until it fires. The real number depends on entity count,
+				// so a fabricated figure here would be worse than none.
+				estimatedMonthlyUsd: 0,
+			};
+	}
+}
+
+/** A scheduled job, declared once and readable by both the local runner and `wrangler`. */
+export interface PortableJob {
+	name: string;
+	shape: TriggerShape;
+	/** The work. Takes the async seam, so the same handler runs on either side. */
+	run(ctx: PortableJobContext): Promise<void>;
+}
+
+export interface PortableJobContext {
+	db: D1LikeDatabase;
+	signal: AbortSignal;
+	log: { info(m: string): void; warn(m: string): void; error(m: string): void };
+}
+
+/**
+ * Render the `[triggers]` block of a `wrangler.toml` from a job list — and refuse to render
+ * one that silently drops a job.
+ *
+ * 🔴 It throws on an unportable job rather than skipping it. A generated config that
+ * quietly omits a job is a job that stops running in production while every local test
+ * still passes, which is the failure mode this whole seam exists to prevent.
+ */
+export function toCronTriggers(jobs: readonly PortableJob[]): { crons: string[]; queues: string[] } {
+	const crons: string[] = [];
+	const queues: string[] = [];
+	const unportable: string[] = [];
+
+	for (const job of jobs) {
+		const verdict = classifySchedule(job.shape);
+		if (verdict.primitive === 'unportable') {
+			unportable.push(`  ${job.name}: ${verdict.reason}`);
+		} else if (verdict.primitive === 'cron-trigger' && verdict.cron) {
+			if (!crons.includes(verdict.cron)) crons.push(verdict.cron);
+		} else if (verdict.primitive === 'queue') {
+			queues.push(job.name);
+		}
+	}
+
+	if (unportable.length > 0) {
+		throw new Error(
+			`${unportable.length} job(s) cannot be expressed as a Cloudflare trigger:\n${unportable.join('\n')}\n` +
+				'Fix the cadence or keep the job on a host — do not ship a config that omits it.',
+		);
+	}
+	return { crons, queues };
+}
+
+/**
+ * 🔴 Cloudflare dispatches a Cron Trigger by EXPRESSION, not by job name — the
+ * `scheduled` handler is told which cron fired and nothing else. Two jobs sharing
+ * `0 3 * * *` arrive as one event, so the Worker has to fan back out to every job matching
+ * that expression. Forgetting this runs the first job and silently never runs the second.
+ */
+export function jobsForCron(jobs: readonly PortableJob[], firedCron: string): PortableJob[] {
+	return jobs.filter((job) => {
+		if (job.shape.kind !== 'periodic') return false;
+		const verdict = classifySchedule(job.shape);
+		return verdict.primitive === 'cron-trigger' && verdict.cron === firedCron.trim();
+	});
+}