@pithy-sh/core 0.1.0

package/src/data/boundParameters.ts

@@ -0,0 +1,197 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database, D1PreparedStatement } from "@cloudflare/workers-types";
+import { InternalError } from "../error/pithyError";
+
+/**
+ * D1's bound-parameter ceiling, and the chunking every `in (...)` list needs to stay under it.
+ *
+ * D1 rejects a statement carrying more than 100 bound parameters. The failure mode is the nastiest kind:
+ * every small test passes, and the query only breaks once real data arrives. Worse, the naive fix —
+ * chunking the list at exactly 100 — is *also* wrong whenever the statement binds anything else. A
+ * `where("indexName", "=", name).where("id", "in", <100 ids>)` binds 101, and an `update … set(a, b)`
+ * ahead of the list binds two more before a single id is counted.
+ *
+ * So the unit here is not "the cap" but **the budget left after the statement's own fixed parameters**.
+ * A call site names how many parameters its statement binds besides the list, and the chunk size is
+ * derived. Adding a `where` to one of those queries is then a one-number edit next to it, not a silent
+ * re-break of a limit nobody re-derived.
+ *
+ * Lives in core rather than in each capability because the arithmetic is the part that was got wrong,
+ * and because `data/` is already where D1's quirks live (see `withD1Retry`).
+ */
+
+/** D1's hard cap on bound parameters in one statement. Cloudflare documents it; over it is an error, not a truncation. */
+export const MAX_BOUND_PARAMETERS = 100;
+
+/**
+ * How many list values one statement may still bind once its fixed parameters are paid for.
+ *
+ * `fixed` is everything the statement binds that is *not* part of the chunked list — each `where` value,
+ * each `set` column, each limit. Throws when a statement leaves no room at all: that is a bug in the
+ * query, not a runtime condition, and silently returning zero would spin the caller's loop forever.
+ */
+export function boundParameterBudget(fixed: number): number {
+  if (!Number.isInteger(fixed) || fixed < 0) {
+    throw new InternalError({
+      message: "Something unexpected happened.",
+      detail: `boundParameterBudget requires a non-negative integer count of fixed parameters; got ${fixed}.`,
+    });
+  }
+  const budget = MAX_BOUND_PARAMETERS - fixed;
+  if (budget < 1) {
+    throw new InternalError({
+      message: "Something unexpected happened.",
+      detail: `A statement binding ${fixed} fixed parameters leaves no room under D1's cap of ${MAX_BOUND_PARAMETERS}.`,
+    });
+  }
+  return budget;
+}
+
+/**
+ * Split `values` into chunks, each small enough that one statement binding `fixed` other parameters
+ * stays under D1's cap. An empty input yields no chunks, so a caller's loop simply does not run.
+ */
+export function chunkByBoundParameters<T>(values: readonly T[], fixed: number): T[][] {
+  const size = boundParameterBudget(fixed);
+  const chunks: T[][] = [];
+  for (let start = 0; start < values.length; start += size) chunks.push(values.slice(start, start + size));
+  return chunks;
+}
+
+/**
+ * Split `rows` into chunks small enough that one multi-row `insert` stays under D1's cap.
+ *
+ * The sibling of {@link chunkByBoundParameters}, and a separate function because the arithmetic is
+ * genuinely different: an `in (…)` list binds **one** parameter per value, while an insert binds one
+ * per *column* per row. Reusing the list chunker for an insert silently allows `columns` times too
+ * many rows, which is a bug that passes every small test and only appears once real data arrives —
+ * `@pithy-sh/support` shipped exactly that, capping attachments at 10 rows of 11 columns and losing
+ * every one of them to `too many SQL variables`.
+ */
+export function chunkRowsByBoundParameters<T>(rows: readonly T[], columnsPerRow: number, fixed = 0): T[][] {
+  if (!Number.isInteger(columnsPerRow) || columnsPerRow < 1) {
+    throw new InternalError({
+      message: "Something unexpected happened.",
+      detail: `chunkRowsByBoundParameters requires a positive column count; got ${columnsPerRow}.`,
+    });
+  }
+  const size = Math.floor(boundParameterBudget(fixed) / columnsPerRow);
+  if (size < 1) {
+    throw new InternalError({
+      message: "Something unexpected happened.",
+      detail: `A row of ${columnsPerRow} columns cannot fit under D1's cap of ${MAX_BOUND_PARAMETERS}.`,
+    });
+  }
+  const chunks: T[][] = [];
+  for (let start = 0; start < rows.length; start += size) chunks.push(rows.slice(start, start + size));
+  return chunks;
+}
+
+/** Read a property off a platform object without losing its `this` — workerd's D1 objects need it. */
+function passThrough(target: object, property: PropertyKey): unknown {
+  const value = Reflect.get(target, property);
+  return typeof value === "function" ? value.bind(target) : value;
+}
+
+/** Enough of a statement to name it in a failure, without carrying a query of unbounded length. */
+function nameOf(query: string): string {
+  const collapsed = query.replace(/\s+/g, " ").trim();
+  return collapsed.length > 160 ? `${collapsed.slice(0, 157)}…` : collapsed;
+}
+
+/**
+ * D1, wrapped so a statement over the cap fails as **the rule** rather than as SQLite's complaint.
+ *
+ * `createDatabase` applies this to every database it builds, which is the whole point: the rule lives at
+ * the thing being called, not at each of the query sites that call it. A capability written next month
+ * that has never heard of the cap is covered by it, and so is one written last year — which matters,
+ * because the list of sites that got this wrong has been wrong five times running. Four capabilities
+ * bound past the cap while the arithmetic to avoid it sat in this file, unimported (#250).
+ *
+ * The check is at `bind`, because that is the only place the number is real: it is what the driver hands
+ * the platform, after Kysely has compiled the statement and after any chunking a caller did. Anything
+ * measured earlier measures intent.
+ *
+ * It does not chunk. It cannot — splitting an arbitrary statement is the caller's arithmetic, and
+ * {@link chunkByBoundParameters} and {@link chunkRowsByBoundParameters} are where it belongs. What this
+ * buys is that the failure names the rule that was broken, one statement before the platform says
+ * `too many SQL variables` and leaves the author to work out which list was too long.
+ */
+export function guardBoundParameters(d1: D1Database): D1Database {
+  return new Proxy(d1, {
+    get(target, property) {
+      if (property !== "prepare") return passThrough(target, property);
+      return (query: string): D1PreparedStatement => {
+        const statement = target.prepare(query);
+        return new Proxy(statement, {
+          get(inner, key) {
+            if (key !== "bind") return passThrough(inner, key);
+            // Returns the *real* bound statement, not another proxy: a bound statement is handed
+            // straight to `D1Database.batch`, which is a platform call that will not take a wrapper.
+            return (...values: unknown[]): D1PreparedStatement => {
+              if (values.length > MAX_BOUND_PARAMETERS) {
+                throw new InternalError({
+                  message: "Something unexpected happened.",
+                  action: "Retry. If it persists, the query needs chunking.",
+                  detail: `A statement bound ${values.length} parameters; D1 accepts ${MAX_BOUND_PARAMETERS}. Chunk the list through chunkByBoundParameters (one parameter per value) or chunkRowsByBoundParameters (one per column per row). Statement: ${nameOf(query)}`,
+                });
+              }
+              return inner.bind(...values);
+            };
+          },
+        });
+      };
+    },
+  });
+}
+
+/** What one recorded run bound, and whatever it threw. */
+export interface BoundParameterRecording {
+  /** Every parameter count D1 was asked to bind, in the order the statements ran. */
+  counts: number[];
+  /** What `run` threw, or `undefined`. Returned rather than propagated — see below. */
+  error: unknown;
+}
+
+/**
+ * Run `run` against a recording D1 and report every parameter count it bound.
+ *
+ * A gate wants to assert the ceiling *before* it rethrows, so the failure an author reads is the
+ * invariant rather than whatever the platform said about it. Hence the throw comes back in the result
+ * instead of propagating: the caller asserts the counts, then rethrows anything left.
+ *
+ * The counterpart to {@link guardBoundParameters} rather than a duplicate of it. The guard proves a
+ * statement was *refused*; this proves what was *bound* — that chunks fill the budget rather than
+ * creeping under it, and that chunking lost no rows on the way.
+ */
+export async function recordBoundParameters(
+  d1: D1Database,
+  run: (d1: D1Database) => Promise<void>,
+): Promise<BoundParameterRecording> {
+  const counts: number[] = [];
+  const recorder = new Proxy(d1, {
+    get(target, property) {
+      if (property !== "prepare") return passThrough(target, property);
+      return (query: string): D1PreparedStatement => {
+        const statement = target.prepare(query);
+        return new Proxy(statement, {
+          get(inner, key) {
+            if (key !== "bind") return passThrough(inner, key);
+            return (...values: unknown[]): D1PreparedStatement => {
+              counts.push(values.length);
+              return inner.bind(...values);
+            };
+          },
+        });
+      };
+    },
+  });
+  try {
+    await run(recorder);
+    return { counts, error: undefined };
+  } catch (error) {
+    return { counts, error };
+  }
+}

package/src/data/codecs.ts

@@ -0,0 +1,160 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * SQLite/D1 codecs: bidirectional JS ↔ SQLite conversion through Zod.
+ *
+ * SQLite has no booleans, no real dates, and no JSON — it stores 0|1, ms-epoch
+ * numbers, and strings. These codecs make that conversion the schema's job.
+ * `.parse()` decodes (DB → app); `.encode()` encodes (app → DB). Decode-side
+ * input is always a `z.union` (never `z.preprocess`) so the schema stays
+ * encode-compatible.
+ *
+ * **A codec reports; it never throws.** `safeParse` cannot throw — only `parse`
+ * throws — and every boundary reader in this kit and in the dashboard is written
+ * on that promise: `const parsed = X.safeParse(body); return parsed.success ?
+ * parsed.data : null;`, documented as *never throws*. Zod's `safeParse` catches a
+ * `ZodError`; it does **not** catch an arbitrary exception raised inside a
+ * transform, which propagates straight past it and out of the reader. So a
+ * transform that meets a value it cannot convert pushes a `$ZodRawIssue` onto the
+ * payload and returns `z.NEVER`. Zod aborts there, the failure arrives as
+ * `{ success: false }`, and `parse` still throws — a `ZodError`, which
+ * `fromZodError` maps to `validation/invalid_input` like every other failed parse.
+ *
+ * `JsonDate` and `SQLiteDate` threw an `InternalError` from inside `decode`, so a
+ * malformed timestamp from a customer's Worker was a 500 rather than a rejected
+ * field, on every pane that read a date (#358). The rule lives here rather than at
+ * the readers because a `try`/`catch` at a call site is the same defect one frame
+ * further out, and the next codec would not inherit it.
+ *
+ * The offending value rides along as the issue's `input`, which is where Zod puts
+ * it and which {@link fromZodError} drops — it keeps `path`, `message` and `code`
+ * only, so the value stays available to a logger at the throw site and never
+ * reaches a client. The `message` is written to be read by one: client-safe, and
+ * still specific enough to say *what* was wrong.
+ */
+
+/**
+ * The invariant every transform below is written to, stated once so it can be cited:
+ * push, return `z.NEVER`, never `throw`.
+ */
+type Payload<T> = z.core.ParsePayload<T>;
+
+const TRUTHY: readonly unknown[] = [true, 1, "1", "true", "True", "TRUE"];
+
+function isTruthy(value: unknown): boolean {
+  return TRUTHY.includes(value);
+}
+
+/** SQLiteBoolean: boolean ↔ 0|1. Decode is lenient (number/boolean/string). */
+export const SQLiteBoolean = z.codec(z.union([z.literal(0), z.literal(1), z.boolean(), z.string()]), z.boolean(), {
+  decode: (input: 0 | 1 | boolean | string): boolean => (typeof input === "boolean" ? input : isTruthy(input)),
+  encode: (value: boolean): 0 | 1 => (value ? 1 : 0),
+});
+
+/**
+ * The shared decode for both date codecs. A string is parsed, a number is ms-epoch — what `encode`
+ * writes, so a caller ingesting seconds-epoch from elsewhere converts explicitly — and a `Date` passes
+ * through by identity.
+ *
+ * **Every branch can produce an unusable `Date`**, not only the string one: `new Date(8.64e15 + 1)` is
+ * as invalid as `new Date("not-a-date")`. So the check is on the result, once, rather than on the input
+ * shape — which is what stops the next accepted input type from arriving without it.
+ */
+function toDate(input: number | string | Date, payload: Payload<number | string | Date>): Date {
+  const parsed = input instanceof Date ? input : new Date(input);
+  if (Number.isNaN(parsed.getTime())) {
+    payload.issues.push({ code: "invalid_format", format: "datetime", input: String(input), message: "Not a date." });
+    return z.NEVER;
+  }
+  return parsed;
+}
+
+/** SQLiteDate: Date ↔ ms-epoch number. Decode accepts number/string/Date. */
+export const SQLiteDate = z.codec(z.union([z.number(), z.string(), z.date()]), z.date(), {
+  decode: toDate,
+  encode: (value: Date): number => value.getTime(),
+});
+
+/** JsonDate: Date ↔ ISO string, for dates nested inside `sqliteJson` payloads. */
+export const JsonDate = z.codec(z.union([z.string(), z.number(), z.date()]), z.date(), {
+  decode: toDate,
+  encode: (value: Date): string => value.toISOString(),
+});
+
+/**
+ * sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode
+ * accepts a JSON string or an already-parsed value; the result is validated
+ * against `schema` before it reaches the app.
+ *
+ * **Both `JSON` functions throw**, and both were reachable. `JSON.parse` throws a
+ * `SyntaxError` on any string that is not a JSON document — which a column holding
+ * text an older writer put there, or a payload a customer's Worker returned, can be.
+ * `JSON.stringify` throws a `TypeError` on a `BigInt` and on a cycle, either of
+ * which a `schema` can legitimately admit. Both become an issue (#358).
+ */
+export function sqliteJson<T extends z.ZodType>(schema: T) {
+  return z.codec(z.union([z.string(), schema]), schema, {
+    decode: (value, payload): z.input<T> => {
+      if (typeof value !== "string") return value as z.input<T>;
+      try {
+        return JSON.parse(value) as z.input<T>;
+      } catch {
+        payload.issues.push({ code: "invalid_format", format: "json", input: value, message: "Not valid JSON." });
+        return z.NEVER;
+      }
+    },
+    encode: (value, payload): string => {
+      // The offending value is deliberately not carried onto the issue: it is the thing JSON could not
+      // hold, so a reporter that renders an issue would be the second place to trip over it.
+      try {
+        const json = JSON.stringify(value);
+        if (typeof json === "string") return json;
+      } catch {
+        // Falls through to the one push below. A `BigInt`, a cycle and an `undefined` result are the
+        // same answer — this value does not survive the round trip — and they deserve the same issue.
+      }
+      payload.issues.push({
+        code: "invalid_format",
+        format: "json",
+        input: undefined,
+        message: "Not serializable as JSON.",
+      });
+      return z.NEVER;
+    },
+  });
+}
+
+export const MAX_TIMEZONE_LENGTH = 64;
+
+/**
+ * Trim, validate, and canonicalize an IANA timezone; anything invalid becomes
+ * `undefined`. Returns Intl's canonical casing (`america/new_york` →
+ * `America/New_York`) so a zone is stored and compared as one value.
+ */
+export function normalizeIanaTimezone(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_TIMEZONE_LENGTH) return undefined;
+  try {
+    return Intl.DateTimeFormat(undefined, { timeZone: trimmed }).resolvedOptions().timeZone;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether `value` is a usable IANA timezone (bounded length, recognized by Intl). */
+export function isValidIanaTimezone(value: string): boolean {
+  return normalizeIanaTimezone(value) !== undefined;
+}
+
+/**
+ * IanaTimezone: validated/bounded IANA timezone string. Coerces invalid input
+ * to `undefined` on both decode and encode rather than throwing.
+ */
+export const IanaTimezone = z.codec(z.string().nullish(), z.string().optional(), {
+  decode: (input: string | null | undefined): string | undefined => normalizeIanaTimezone(input),
+  encode: (value: string | undefined): string | undefined => normalizeIanaTimezone(value),
+});

package/src/data/cursor.ts

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * Keyset pagination, once, for every capability that lists an unbounded table.
+ *
+ * ## Why keyset and never offset
+ *
+ * `OFFSET` shifts under a client whenever a row is inserted, and every table these paginate — audit
+ * events, email jobs, users, ledger transactions — is written to constantly while somebody is reading
+ * it. With `OFFSET 25` a row inserted at the head pushes one row from page 1 onto page 2, so a client
+ * paging through sees it twice and misses nothing only by luck; a deletion drops a row entirely. A
+ * keyset cursor names the last row's sort position, so the next page starts exactly where the previous
+ * ended whatever happened in between.
+ *
+ * ## Why this is in core rather than copied
+ *
+ * `@pithy-sh/support` had the only implementation, and Part 3 of #89 needs the same thing in four more
+ * packages. Four copies of a security-adjacent decode — where the difference between "malformed cursor"
+ * and "500" is a caller's ability to probe — is four places for one of them to be wrong. Capabilities
+ * depend on core seams, which is exactly what this is.
+ *
+ * ## The shape of a page
+ *
+ * A caller asks for `limit`; the query fetches `limit + 1` and, when it gets them, drops the extra and
+ * returns a `nextCursor`. That is what makes "is there another page" answerable **without a count
+ * query**, which on an audit table is the difference between a page load and a table scan.
+ */
+
+/** A sensible page when a caller names none. Small enough to render, large enough to be one request. */
+export const DEFAULT_PAGE_SIZE = 25;
+
+/** The most a caller may ask for in one page, whatever they send. An unbounded page is a table scan. */
+export const MAX_PAGE_SIZE = 100;
+
+/**
+ * The `limit` a query should actually use, clamped into range.
+ *
+ * Clamped rather than rejected: a client asking for 1000 wants "as many as you'll give me", and failing
+ * the request teaches it nothing a capped page does not. A caller asking for 0 or a negative gets one
+ * row rather than an empty page that looks like the end of the list.
+ */
+export function pageLimit(requested: number | undefined): number {
+  return Math.min(Math.max(requested ?? DEFAULT_PAGE_SIZE, 1), MAX_PAGE_SIZE);
+}
+
+/**
+ * An opaque position in a descending `(sort, id)` ordering.
+ *
+ * `sort` is the primary column's value — a ms-epoch for a date, a number for a monotonic id. `id` is the
+ * tiebreak that makes the position exact: without it, two rows sharing a timestamp straddle a page
+ * boundary and one of them is skipped or repeated.
+ */
+export const PageCursor = z
+  .object({
+    sort: z
+      .union([z.number(), z.string()])
+      .describe(
+        "The sort column's value on the last row of the previous page — a ms-epoch for a date column, a number for a monotonic id, a string for an ISO-8601 date column. A string and a number compare differently in SQLite, so this carries whichever the column actually stores.",
+      ),
+    id: z
+      .union([z.number(), z.string()])
+      .describe(
+        "That row's primary key, the tiebreak that makes the position exact. Two rows sharing a sort value would otherwise straddle a page boundary, and one of them would be skipped or returned twice.",
+      ),
+  })
+  .describe("An opaque position in a descending (sort, id) ordering — where the next page starts.");
+export type PageCursor = z.infer<typeof PageCursor>;
+
+/**
+ * Encode a cursor for the wire.
+ *
+ * Base64url over JSON, and **opaque by intent rather than by obscurity**: the point is that a client
+ * cannot construct one by hand and therefore cannot come to depend on its shape, so the ordering can
+ * change later without breaking every caller. It is not a secret — it holds a sort value and an id the
+ * caller was just given, both of which were in the page it came from.
+ */
+export function encodeCursor(cursor: PageCursor): string {
+  // UTF-8 first. `btoa` throws `InvalidCharacterError` on any code unit above U+00FF, and a cursor's
+  // `id` can be a caller-minted string — a device id, an external reference — so a single non-Latin-1
+  // character would turn a page boundary into a 500 rather than a cursor.
+  const bytes = new TextEncoder().encode(JSON.stringify(cursor));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * Decode a cursor. Returns undefined for anything malformed.
+ *
+ * **A bad cursor is a first page, not a 500.** Cursors travel through URLs, get truncated by clients,
+ * and outlive deploys; treating a malformed one as an error turns an ordinary client bug into a page
+ * that never loads, and hands anyone probing the endpoint a way to tell a parse failure from a
+ * not-found. Every failure mode here — bad base64, bad JSON, wrong shape — collapses to the same
+ * undefined.
+ */
+export function decodeCursor(value: string | undefined): PageCursor | undefined {
+  if (!value) return undefined;
+  try {
+    const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    const parsed = PageCursor.safeParse(JSON.parse(new TextDecoder().decode(bytes)));
+    return parsed.success ? parsed.data : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Split an over-fetched result into the page and the cursor that follows it.
+ *
+ * Pass the rows a query returned when asked for `limit + 1`. When there are more than `limit`, the extra
+ * is dropped and `nextCursor` names the last row of the page; otherwise `nextCursor` is null and the
+ * client knows it has reached the end without a second request.
+ */
+export function toPage<T>(
+  rows: readonly T[],
+  limit: number,
+  position: (row: T) => PageCursor,
+): { items: T[]; nextCursor: string | null } {
+  const hasMore = rows.length > limit;
+  const items = hasMore ? rows.slice(0, limit) : [...rows];
+  const last = items[items.length - 1];
+  return { items, nextCursor: hasMore && last !== undefined ? encodeCursor(position(last)) : null };
+}

package/src/data/databases.ts

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+import type { z } from "zod";
+import type { Capability } from "../capability/capability";
+import { type BindingGroup, bindingGroupsFrom, composeBindingGroups } from "../capability/compose";
+import { createDatabase, type DatabaseSchema, type SchemaMap } from "./db";
+
+/**
+ * One named D1 database a capability contributes tables to: the `binding` it lives in plus this
+ * capability's slice of its schema. A production Worker commonly binds several D1 databases (app
+ * data, analytics, …); each is a named database here, and `createBackend` serves one typed `Kysely`
+ * per name on `c.var.db.<name>`. Capabilities targeting the same database name merge their slices.
+ */
+export interface DatabaseSpec<Tables extends SchemaMap = SchemaMap> {
+  /** The D1 binding name in the Worker env this database lives in. */
+  binding: string;
+  /** This capability's slice of the database's schema (table name → Zod table schema). */
+  tables: Tables;
+  /**
+   * This capability's migrations for this database, by stable local key (e.g. "0001_init") —
+   * co-located with the tables they create, so the database association is declared once. The
+   * migration namespace is the capability's name; `pithy migrate` composes every capability's
+   * sets through `createMigrationRegistry` and runs them per database.
+   */
+  migrations?: Record<string, Migration>;
+  /** Sort order within this database relative to other capabilities (core low, app high). Required with `migrations`. */
+  migrationOrder?: number;
+}
+
+/** A capability's databases: database name → {@link DatabaseSpec}. */
+export type DatabaseSpecMap = Record<string, DatabaseSpec>;
+
+/**
+ * The typed database registry exposed on `c.var.db`: each named database becomes its live `Kysely`
+ * over that database's merged schema — so `c.var.db.app.selectFrom("…")` and
+ * `c.var.db.analytics.selectFrom("…")` are each typed to their own tables.
+ */
+export type DbRegistry<Dbs extends DatabaseSpecMap> = {
+  [Name in keyof Dbs]: Dbs[Name] extends DatabaseSpec<infer Tables> ? Kysely<DatabaseSchema<Tables>> : never;
+};
+
+/** The merged databases: each database name → its binding and the union of every capability's tables. */
+export type MergedDatabases = Record<string, BindingGroup<z.ZodType>>;
+
+/**
+ * Merge every capability's `databases` into one map keyed by database name. Capabilities targeting
+ * the same name union their table slices (the project-wide schema, per database); a table claimed
+ * twice in one database, or a database name bound to two bindings, throws at assembly.
+ */
+export function composeDatabases(capabilities: Capability[]): MergedDatabases {
+  return composeBindingGroups<z.ZodType>(
+    capabilities,
+    (cap) => bindingGroupsFrom(cap.databases, (db) => db.tables),
+    "database",
+    "table",
+  );
+}
+
+/** A registry of live Kysely instances keyed by database name; the per-request value of `c.var.db`. */
+type LiveDbRegistry = Record<string, Kysely<DatabaseSchema<SchemaMap>>>;
+
+/**
+ * Build the per-request database registry from the merged databases and the request's env. Each
+ * `Kysely` is constructed lazily on first access from its D1 binding — a request that never touches
+ * `c.var.db.analytics` never builds it.
+ */
+export function buildDbRegistry(env: Record<string, unknown>, databases: MergedDatabases): LiveDbRegistry {
+  const registry: LiveDbRegistry = {};
+  for (const [name, group] of Object.entries(databases)) {
+    let instance: Kysely<DatabaseSchema<SchemaMap>> | undefined;
+    Object.defineProperty(registry, name, {
+      enumerable: true,
+      get(): Kysely<DatabaseSchema<SchemaMap>> {
+        if (!instance) instance = createDatabase(env[group.binding] as D1Database, group.items);
+        return instance;
+      },
+    });
+  }
+  return registry;
+}

package/src/data/db.ts

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { CamelCasePlugin, type Generated, Kysely } from "kysely";
+import { D1Dialect } from "kysely-d1";
+import type { z } from "zod";
+import { guardBoundParameters } from "./boundParameters";
+
+/**
+ * The Kysely D1 database builder.
+ *
+ * One master map of table name → Zod table schema is the whole database
+ * definition. The database interface Kysely sees is derived from each schema's
+ * `z.input` side — the SQLite row shape — never a hand-written row interface.
+ * `CamelCasePlugin` is mandatory: tables use snake_case columns, query code
+ * uses camelCase, and the plugin bridges the two in both directions.
+ */
+
+/** A master map of table name → that table's Zod schema. */
+export type SchemaMap = Record<string, z.ZodType>;
+
+/**
+ * Present a numeric `id` to Kysely as `Generated<number>`: optional on insert
+ * (D1 assigns it), a number on select. A table without a numeric `id` is left
+ * unchanged. Externally-exposed entities use a text id and so are untouched.
+ */
+export type WithGeneratedId<Row> = Row extends { id: number } ? Omit<Row, "id"> & { id: Generated<number> } : Row;
+
+/** The Kysely database interface derived from a schema map's `z.input` (row) side. */
+export type DatabaseSchema<M extends SchemaMap> = {
+  [K in keyof M]: WithGeneratedId<z.input<M[K]>>;
+};
+
+/**
+ * Build a typed Kysely instance over D1 for `map`. The `map` argument carries
+ * the table types — it drives inference of the database interface; Kysely needs
+ * no values from it at runtime. `CamelCasePlugin` is always installed.
+ *
+ * So is `guardBoundParameters`. This is the one seam every Kysely instance in
+ * the repository comes from, so it is the one place the bound-parameter ceiling
+ * can be stated for all of them — including for query sites that have never
+ * heard of it. Five capabilities bound past the cap while the arithmetic to
+ * avoid it sat unimported in `boundParameters.ts` (#246, #250); a rule that
+ * every call site has to remember is a rule in the wrong place.
+ */
+export function createDatabase<M extends SchemaMap>(d1: D1Database, map: M): Kysely<DatabaseSchema<M>> {
+  void map; // type-only carrier; see doc comment
+  return new Kysely<DatabaseSchema<M>>({
+    dialect: new D1Dialect({ database: guardBoundParameters(d1) }),
+    plugins: [new CamelCasePlugin()],
+  });
+}