cursedbelt-server 1.1.0 → 2.1.0

package/src/server/d1/remote.ts

@@ -0,0 +1,182 @@
+/**
+ * The REMOTE implementation of {@link D1LikeDatabase}, over a Cloudflare D1 binding.
+ *
+ * It is thin on purpose. D1's own API is the shape `./types` mirrors, so nearly all of
+ * this file is the normalization that makes a D1 answer indistinguishable from a
+ * `bun:sqlite` one — the same `normalizeBind` / `normalizeValue` the local driver calls,
+ * so "the two drivers agree" is a property of one implementation rather than a
+ * coincidence between two.
+ *
+ * 🔴 **`workerd` is not imported here, and must not be.** This package is built and tested
+ * with Bun, and `@cloudflare/workers-types` would be a dependency the other 99 % of the
+ * library does not need. The binding is described structurally by {@link D1BindingLike}
+ * below, which is the subset of Cloudflare's `D1Database` this driver actually calls — so
+ * a real binding satisfies it without a cast, and the test suite can satisfy it with a
+ * fake that has no `workerd` in sight.
+ */
+
+import { assertBatchSize, assertWithinLimits } from './limits';
+import {
+	type D1LikeBindable,
+	type D1LikeDatabase,
+	type D1LikeResult,
+	type D1LikeRow,
+	type D1LikeStatement,
+	type D1LikeValue,
+	D1UnsupportedError,
+} from './types';
+import { makeMeta, normalizeBinds, normalizeRows, normalizeValue } from './values';
+
+/** What D1 reports back about a statement. Its `meta` is richer than the local driver's. */
+export interface D1BindingMeta {
+	duration?: number;
+	changes?: number;
+	last_row_id?: number;
+	rows_read?: number;
+	rows_written?: number;
+	served_by?: string;
+}
+
+export interface D1BindingResult {
+	results?: unknown[];
+	success?: boolean;
+	meta?: D1BindingMeta;
+	error?: string;
+}
+
+/** The subset of Cloudflare's `D1PreparedStatement` this driver calls. */
+export interface D1BindingStatement {
+	bind(...values: unknown[]): D1BindingStatement;
+	first(column?: string): Promise<unknown>;
+	all(): Promise<D1BindingResult>;
+	run(): Promise<D1BindingResult>;
+	raw(): Promise<unknown[][]>;
+}
+
+/** The subset of Cloudflare's `D1Database` this driver calls. A real binding satisfies it. */
+export interface D1BindingLike {
+	prepare(sql: string): D1BindingStatement;
+	batch(statements: D1BindingStatement[]): Promise<D1BindingResult[]>;
+	exec(sql: string): Promise<{ count: number; duration: number }>;
+}
+
+/**
+ * D1 reports a failed statement by RESOLVING with `success: false` in some paths rather
+ * than rejecting, so a driver that only catches rejections reports a silent no-op as a
+ * successful write. Every result goes through here.
+ */
+function assertSucceeded(res: D1BindingResult, sql: string): void {
+	if (res.success === false || res.error) {
+		throw new Error(`D1 refused the statement: ${res.error ?? 'success: false'}\n  ${sql.slice(0, 160)}`);
+	}
+}
+
+const toMeta = (res: D1BindingResult) =>
+	makeMeta({
+		changes: res.meta?.changes ?? 0,
+		last_row_id: res.meta?.last_row_id ?? null,
+		duration: res.meta?.duration ?? 0,
+		rows_read: res.meta?.rows_read ?? null,
+		rows_written: res.meta?.rows_written ?? null,
+	});
+
+class RemoteStatement implements D1LikeStatement {
+	constructor(
+		private readonly stmt: D1BindingStatement,
+		private readonly sql: string,
+	) {}
+
+	/** The underlying binding statement — how `batch()` reaches the real objects. */
+	get binding(): D1BindingStatement {
+		return this.stmt;
+	}
+
+	bind(...values: D1LikeBindable[]): D1LikeStatement {
+		const params = normalizeBinds(values);
+		assertWithinLimits(this.sql, params);
+		// D1 accepts ArrayBuffer for BLOBs; `normalizeBind` has already reduced every blob
+		// to a `Uint8Array`, so this is the one place that converts back out.
+		const wire = params.map((p) => (p instanceof Uint8Array ? p.buffer.slice(p.byteOffset, p.byteOffset + p.byteLength) : p));
+		return new RemoteStatement(this.stmt.bind(...wire), this.sql);
+	}
+
+	async first<T = D1LikeRow>(column?: string): Promise<T | null> {
+		const row = await this.stmt.first(column);
+		if (row === null || row === undefined) return null;
+		if (column !== undefined) return normalizeValue(row) as T;
+		return normalizeRows<T>([row as Record<string, unknown>])[0] ?? null;
+	}
+
+	async all<T = D1LikeRow>(): Promise<D1LikeResult<T>> {
+		const res = await this.stmt.all();
+		assertSucceeded(res, this.sql);
+		return {
+			results: normalizeRows<T>((res.results ?? []) as Record<string, unknown>[]),
+			success: true,
+			meta: toMeta(res),
+		};
+	}
+
+	async run(): Promise<D1LikeResult<never>> {
+		const res = await this.stmt.run();
+		assertSucceeded(res, this.sql);
+		return { results: [], success: true, meta: toMeta(res) };
+	}
+
+	async raw<V = D1LikeValue>(): Promise<V[][]> {
+		const rows = await this.stmt.raw();
+		return rows.map((r) => r.map((v) => normalizeValue(v) as V));
+	}
+}
+
+/**
+ * Wrap a Cloudflare D1 binding in the async seam.
+ *
+ * On a Worker this is constructed per request from `env.DB` — a binding is not a
+ * connection and holds no state worth caching, so there is nothing to pool and nothing to
+ * close.
+ */
+export function createRemoteD1(binding: D1BindingLike): D1LikeDatabase {
+	return {
+		flavor: 'd1',
+
+		prepare(sql: string): D1LikeStatement {
+			return new RemoteStatement(binding.prepare(sql), sql);
+		},
+
+		async batch<T = D1LikeRow>(statements: D1LikeStatement[]): Promise<D1LikeResult<T>[]> {
+			assertBatchSize(statements.length);
+			const bindings = statements.map((s) => {
+				const b = (s as Partial<RemoteStatement>).binding;
+				if (!b) {
+					throw new TypeError(
+						'batch() accepts only statements from this same D1 database — ' +
+							'a local statement cannot run inside a D1 batch.',
+					);
+				}
+				return b;
+			});
+			const results = await binding.batch(bindings);
+			return results.map((res, i) => {
+				assertSucceeded(res, `batch statement ${i + 1}`);
+				return {
+					results: normalizeRows<T>((res.results ?? []) as Record<string, unknown>[]),
+					success: true as const,
+					meta: toMeta(res),
+				};
+			});
+		},
+
+		exec(sql: string): Promise<{ count: number; duration: number }> {
+			return binding.exec(sql);
+		},
+	};
+}
+
+/** Re-exported so both drivers refuse an interactive transaction with one message. */
+export const refuseInteractiveTransaction = (): never => {
+	throw new D1UnsupportedError(
+		'an interactive transaction (BEGIN/COMMIT)',
+		'collect the statements and pass them to `db.batch([...])`, which is atomic on both drivers',
+	);
+};

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([]);
+	});
+});