cursedbelt-server 2.0.0 → 2.1.0

package/dist/server/d1/limits.js

@@ -0,0 +1,96 @@
+/**
+ * D1's hard limits, and the helpers that keep a query inside them.
+ *
+ * 🔴 **These shape the schema, not just the bill.** Three of them change how code must be
+ * written, and all three are invisible on `bun:sqlite` — which has no such caps, so every
+ * one of them is a green-here / red-there defect waiting for the first real dataset:
+ *
+ *   · **1,000 queries per Worker invocation.** An N+1 loop over `family`'s 489 people
+ *     exceeds it. Join, or `batch()`; do not loop.
+ *   · **100 bound parameters per query.** Any seed, import or bulk insert hits this. Use
+ *     {@link chunkForBind}, which does the arithmetic rather than leaving it to a guess.
+ *   · **2 MB per string / BLOB / row.** Nothing may store a media byte in D1.
+ *
+ * The limits are asserted by the LOCAL driver as well as the remote one, which is the
+ * whole point: a bulk insert that would fail in production fails on the laptop, at the
+ * call site, with the chunk size it should have used in the message.
+ *
+ * Values are the Workers **Paid** tier, which is what the owner already pays for.
+ */
+import { D1LimitError } from './types';
+export const LIMITS = {
+    /** Bound parameters in a single statement. */
+    boundParams: 100,
+    /** Queries a single Worker invocation may issue, including every `batch()` member. */
+    queriesPerInvocation: 1_000,
+    /** Bytes of SQL text in one statement. A generated `IN (…)` list hits this first. */
+    sqlLength: 100_000,
+    /** Bytes in any single string or BLOB value, and in any single row. */
+    valueBytes: 2_000_000,
+    /** Columns in one table. The fleet's `data JSON` pattern stays far under it. */
+    columnsPerTable: 100,
+    /** Wall-clock milliseconds one query may take. */
+    queryDurationMs: 30_000,
+};
+const byteLength = (v) => {
+    if (typeof v === 'string')
+        return Buffer.byteLength(v, 'utf8');
+    if (v instanceof Uint8Array)
+        return v.byteLength;
+    if (v instanceof ArrayBuffer)
+        return v.byteLength;
+    return 0;
+};
+/**
+ * Refuse a statement that D1 would refuse — checked on BOTH drivers, at `bind()` time, so
+ * the failure lands on the call site that built the query rather than in production.
+ */
+export function assertWithinLimits(sql, params) {
+    if (params.length > LIMITS.boundParams) {
+        throw new D1LimitError('bound parameters per query', params.length, LIMITS.boundParams, 'Chunk the work — `chunkForBind(items, paramsPerItem)` sizes the batches for you, ' +
+            'or use `batch()` for independent statements.');
+    }
+    const sqlBytes = Buffer.byteLength(sql, 'utf8');
+    if (sqlBytes > LIMITS.sqlLength) {
+        throw new D1LimitError('SQL statement length (bytes)', sqlBytes, LIMITS.sqlLength, 'A generated `IN (...)` list hits this before the parameter cap — bind parameters instead of inlining values.');
+    }
+    for (let i = 0; i < params.length; i++) {
+        const bytes = byteLength(params[i]);
+        if (bytes > LIMITS.valueBytes) {
+            throw new D1LimitError(`value size for parameter ${i + 1} (bytes)`, bytes, LIMITS.valueBytes, 'D1 is not a blob store. Media bytes belong in R2 behind the binary server — see task 193.');
+        }
+    }
+}
+/** Refuse a `batch()` bigger than one Worker invocation may issue. */
+export function assertBatchSize(count) {
+    if (count > LIMITS.queriesPerInvocation) {
+        throw new D1LimitError('queries per Worker invocation', count, LIMITS.queriesPerInvocation, 'Split the work across invocations — a Queue consumer or a Cron Trigger, not one giant batch.');
+    }
+}
+/**
+ * Split a list into chunks that fit under the 100-parameter cap, given how many bound
+ * parameters each item contributes.
+ *
+ * A bulk insert of `n` rows with `c` columns binds `n * c` parameters, so the batch size
+ * is `floor(100 / c)` — the arithmetic nobody does correctly by eye at 3 a.m., which is
+ * why it is a function and not a sentence in a doc.
+ *
+ * ```ts
+ * for (const rows of chunkForBind(people, 4)) {           // 4 columns → 25 rows a chunk
+ *   await db.prepare(insertSql(rows.length)).bind(...rows.flatMap(toParams)).run();
+ * }
+ * ```
+ */
+export function chunkForBind(items, paramsPerItem) {
+    if (!Number.isInteger(paramsPerItem) || paramsPerItem < 1) {
+        throw new RangeError(`paramsPerItem must be a positive integer, got ${paramsPerItem}`);
+    }
+    if (paramsPerItem > LIMITS.boundParams) {
+        throw new D1LimitError('bound parameters per query', paramsPerItem, LIMITS.boundParams, 'A single item already exceeds the cap — store fewer columns, or move the wide value out of D1.');
+    }
+    const size = Math.floor(LIMITS.boundParams / paramsPerItem);
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}

package/dist/server/d1/local.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The LOCAL implementation of {@link D1LikeDatabase}, over `bun:sqlite`.
+ *
+ * This is the half that keeps the gate, the dev loop and a Mac-hosted app working
+ * unchanged while the fleet ports. It is async because the seam is async — not because
+ * anything here awaits I/O. `bun:sqlite` answers synchronously and these methods resolve
+ * an already-computed value, so the cost is a microtask, not a round trip.
+ *
+ * 🔴 **It is deliberately no more permissive than D1.** Every bind goes through
+ * `normalizeBind`, which refuses the two values `bun:sqlite` would have accepted silently
+ * (`undefined`, and out-of-range `bigint`) and coerces the one both can agree on
+ * (`boolean`). D1's limits are asserted here too, and an interactive transaction is
+ * refused here exactly as it is refused remotely. The point of a local driver is to fail
+ * the same way, early and on a laptop.
+ */
+import type { Database } from 'bun:sqlite';
+import { type D1LikeDatabase } from './types';
+/**
+ * Wrap a `bun:sqlite` {@link Database} in the async seam.
+ *
+ * The handle is the SAME one a not-yet-ported app still uses directly, so a half-ported
+ * app has one connection, one WAL and one transaction space — the property `createKysely`
+ * was written for. That is what makes a file-at-a-time port possible instead of an
+ * app-at-a-time one, and it is why this takes a `Database` rather than a path.
+ */
+export declare function createLocalD1(db: Database): D1LikeDatabase;
+/**
+ * Refuse an interactive transaction, for the same reason D1 refuses it. Exported so the
+ * Kysely dialect and any app-level helper give one message instead of three.
+ */
+export declare const refuseInteractiveTransaction: () => never;

package/dist/server/d1/local.js

@@ -0,0 +1,135 @@
+/**
+ * The LOCAL implementation of {@link D1LikeDatabase}, over `bun:sqlite`.
+ *
+ * This is the half that keeps the gate, the dev loop and a Mac-hosted app working
+ * unchanged while the fleet ports. It is async because the seam is async — not because
+ * anything here awaits I/O. `bun:sqlite` answers synchronously and these methods resolve
+ * an already-computed value, so the cost is a microtask, not a round trip.
+ *
+ * 🔴 **It is deliberately no more permissive than D1.** Every bind goes through
+ * `normalizeBind`, which refuses the two values `bun:sqlite` would have accepted silently
+ * (`undefined`, and out-of-range `bigint`) and coerces the one both can agree on
+ * (`boolean`). D1's limits are asserted here too, and an interactive transaction is
+ * refused here exactly as it is refused remotely. The point of a local driver is to fail
+ * the same way, early and on a laptop.
+ */
+import { assertBatchSize, assertWithinLimits } from './limits';
+import { D1UnsupportedError, } from './types';
+import { makeMeta, normalizeBinds, normalizeRows, normalizeValue } from './values';
+/** Shared clock, so `meta.duration` means the same thing on both sides of the seam. */
+const now = () => performance.now();
+class LocalStatement {
+    db;
+    sql;
+    params;
+    constructor(db, sql, params = []) {
+        this.db = db;
+        this.sql = sql;
+        this.params = params;
+    }
+    bind(...values) {
+        const params = normalizeBinds(values);
+        assertWithinLimits(this.sql, params);
+        return new LocalStatement(this.db, this.sql, params);
+    }
+    stmt() {
+        return this.db.query(this.sql);
+    }
+    allSync() {
+        const started = now();
+        const rows = this.stmt().all(...this.params);
+        return {
+            results: normalizeRows(rows),
+            success: true,
+            meta: makeMeta({ duration: now() - started }),
+        };
+    }
+    async first(column) {
+        const row = this.stmt().get(...this.params);
+        if (row === null || row === undefined)
+            return null;
+        if (column === undefined)
+            return normalizeRows([row])[0] ?? null;
+        if (!(column in row)) {
+            throw new RangeError(`column '${column}' is not in the result of: ${this.sql.slice(0, 80)}`);
+        }
+        return normalizeValue(row[column]);
+    }
+    async all() {
+        return this.allSync();
+    }
+    async run() {
+        const started = now();
+        const res = this.stmt().run(...this.params);
+        return {
+            results: [],
+            success: true,
+            meta: makeMeta({
+                changes: res.changes,
+                last_row_id: res.lastInsertRowid,
+                duration: now() - started,
+            }),
+        };
+    }
+    async raw() {
+        const rows = this.stmt().values(...this.params);
+        return rows.map((r) => r.map((v) => normalizeValue(v)));
+    }
+}
+/**
+ * Wrap a `bun:sqlite` {@link Database} in the async seam.
+ *
+ * The handle is the SAME one a not-yet-ported app still uses directly, so a half-ported
+ * app has one connection, one WAL and one transaction space — the property `createKysely`
+ * was written for. That is what makes a file-at-a-time port possible instead of an
+ * app-at-a-time one, and it is why this takes a `Database` rather than a path.
+ */
+export function createLocalD1(db) {
+    return {
+        flavor: 'local',
+        prepare(sql) {
+            return new LocalStatement(db, sql);
+        },
+        /**
+         * Atomic on both sides. Locally that is a real `bun:sqlite` transaction; on D1 it is
+         * one round trip the service commits or discards as a unit. The guarantee a caller
+         * can rely on is the same, which is the only reason `batch()` can be the fleet's
+         * transaction primitive — see the note on {@link SyncExecutable} for why the body
+         * below may not await.
+         */
+        async batch(statements) {
+            assertBatchSize(statements.length);
+            const run = db.transaction((stmts) => {
+                const out = [];
+                for (const s of stmts) {
+                    const sync = s;
+                    if (typeof sync.allSync !== 'function') {
+                        throw new TypeError('batch() accepts only statements from this same local database — ' +
+                            'a remote statement cannot run inside a local transaction.');
+                    }
+                    out.push(sync.allSync());
+                }
+                return out;
+            });
+            return run(statements);
+        },
+        async exec(sql) {
+            const started = now();
+            db.exec(sql);
+            // D1's `exec` reports how many statements it ran, and counts them by `;`.
+            // Matching that keeps the field meaning one thing on both sides.
+            const count = sql
+                .split(';')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0).length;
+            return { count, duration: now() - started };
+        },
+    };
+}
+/**
+ * Refuse an interactive transaction, for the same reason D1 refuses it. Exported so the
+ * Kysely dialect and any app-level helper give one message instead of three.
+ */
+export const refuseInteractiveTransaction = () => {
+    throw new D1UnsupportedError('an interactive transaction (BEGIN/COMMIT)', 'collect the statements and pass them to `db.batch([...])`, which is atomic on both drivers');
+};

package/dist/server/d1/remote.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 { type D1LikeDatabase } from './types';
+/** 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;
+    }>;
+}
+/**
+ * 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 declare function createRemoteD1(binding: D1BindingLike): D1LikeDatabase;
+/** Re-exported so both drivers refuse an interactive transaction with one message. */
+export declare const refuseInteractiveTransaction: () => never;

package/dist/server/d1/remote.js

@@ -0,0 +1,124 @@
+/**
+ * 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 { D1UnsupportedError, } from './types';
+import { makeMeta, normalizeBinds, normalizeRows, normalizeValue } from './values';
+/**
+ * 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, sql) {
+    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) => 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 {
+    stmt;
+    sql;
+    constructor(stmt, sql) {
+        this.stmt = stmt;
+        this.sql = sql;
+    }
+    /** The underlying binding statement — how `batch()` reaches the real objects. */
+    get binding() {
+        return this.stmt;
+    }
+    bind(...values) {
+        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(column) {
+        const row = await this.stmt.first(column);
+        if (row === null || row === undefined)
+            return null;
+        if (column !== undefined)
+            return normalizeValue(row);
+        return normalizeRows([row])[0] ?? null;
+    }
+    async all() {
+        const res = await this.stmt.all();
+        assertSucceeded(res, this.sql);
+        return {
+            results: normalizeRows((res.results ?? [])),
+            success: true,
+            meta: toMeta(res),
+        };
+    }
+    async run() {
+        const res = await this.stmt.run();
+        assertSucceeded(res, this.sql);
+        return { results: [], success: true, meta: toMeta(res) };
+    }
+    async raw() {
+        const rows = await this.stmt.raw();
+        return rows.map((r) => r.map((v) => normalizeValue(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) {
+    return {
+        flavor: 'd1',
+        prepare(sql) {
+            return new RemoteStatement(binding.prepare(sql), sql);
+        },
+        async batch(statements) {
+            assertBatchSize(statements.length);
+            const bindings = statements.map((s) => {
+                const b = s.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((res.results ?? [])),
+                    success: true,
+                    meta: toMeta(res),
+                };
+            });
+        },
+        exec(sql) {
+            return binding.exec(sql);
+        },
+    };
+}
+/** Re-exported so both drivers refuse an interactive transaction with one message. */
+export const refuseInteractiveTransaction = () => {
+    throw new D1UnsupportedError('an interactive transaction (BEGIN/COMMIT)', 'collect the statements and pass them to `db.batch([...])`, which is atomic on both drivers');
+};

package/dist/server/d1/scheduling.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `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;
+}
+/**
+ * A cron expression with six fields carries a leading SECONDS column. Cloudflare has no
+ * such column and no cadence below one minute.
+ */
+export declare function cronFieldCount(cron: string): number;
+/**
+ * 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 declare function toFiveField(cron: string): {
+    cron: string;
+    lossless: boolean;
+};
+/**
+ * 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 declare function classifySchedule(shape: TriggerShape): ScheduleVerdict;
+/** 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 declare function toCronTriggers(jobs: readonly PortableJob[]): {
+    crons: string[];
+    queues: string[];
+};
+/**
+ * 🔴 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 declare function jobsForCron(jobs: readonly PortableJob[], firedCron: string): PortableJob[];