@pithy-sh/core 0.1.1 → 0.1.3

package/dist/logger/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/logger/record.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,QAAQ;;;;;EAE4F,CAAC;AAClH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAgD,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,SAAS,wCAEsF,CAAC;AAC7G,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW+E,CAAC;AACtG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMzD"}

package/dist/logger/record.js

@@ -0,0 +1,79 @@
+import { ErrorPayload } from "../error/payload.js";
+import { z } from "zod";
+//#region src/logger/record.ts
+/**
+* The logger object model. A log call is a **record**, not a formatted line — `{ level, msg, ...fields }`
+* — so both adapters (local diagnostics, CF-native) serialize the same structured shape rather than
+* re-parsing text. The schema IS the documentation: every field carries a `.describe()`, like any other
+* Pithy boundary. Log copy follows the brand voice — the `msg` is one pithy line; data lives in `fields`.
+*/
+/** The four severities, low to high. `debug` is dev diagnostics; `error` is a failure that was observed. */
+const LogLevel = z.enum([
+	"debug",
+	"info",
+	"warn",
+	"error"
+]).describe("Log severity, low to high: `debug` < `info` < `warn` < `error`. The threshold a logger filters on.");
+/**
+* Numeric rank per level, for threshold filtering — a logger drops any record ranked below its level.
+* Not a schema (it is a lookup table), so the meta-test that polices `.describe()` skips it.
+*/
+const LOG_LEVEL_ORDER = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40
+};
+/**
+* Structured fields carried on a record — the data half of a log. Arbitrary JSON-ish values keyed by
+* name (`{ userId, elapsed, request }`); an adapter renders or serializes them. The reserved key
+* `error` may carry a `PithyError` or `ErrorPayload`; the engine lifts it into {@link LogRecord.error}.
+*/
+const LogFields = z.record(z.string(), z.unknown()).describe("Structured, arbitrary fields carried on a log record — the queryable data half of a log call.");
+/**
+* One finished log record — what an adapter's sink receives. This is the on-the-wire structured shape
+* CF Workers Logs indexes per line and the local adapter renders. `error` carries the **full**
+* `ErrorPayload` including `detail`: a log is an internal surface (the same side of the boundary as
+* audit `detail`), the inverse of the HTTP codec which strips it. A logger is never wired to a client.
+*/
+const LogRecord = z.object({
+	level: LogLevel.describe("The severity of this record."),
+	msg: z.string().describe("The one-line, brand-voice message. No data — data lives in `fields`."),
+	time: z.number().int().describe("When the record was made, as a millisecond epoch."),
+	name: z.string().nullish().describe("The emitting logger's namespace (from `child(name)`), if any."),
+	fields: LogFields.nullish().describe("Structured fields carried on this record, if any were supplied."),
+	error: ErrorPayload.nullish().describe("The full error payload — `detail` included — when the call carried a PithyError. Internal only.")
+}).describe("One structured log record: an adapter's sink serializes or renders exactly this shape.");
+/**
+* A JSON replacer that keeps serialization total: `BigInt` becomes a string, and a repeated object
+* reference (a cycle) becomes `"[Circular]"`. A logger must never throw — an unserializable field in a
+* log call must not crash the caller — so both adapters serialize through {@link serializeRecord}.
+*/
+function safeReplacer() {
+	const seen = /* @__PURE__ */ new WeakSet();
+	return (_key, value) => {
+		if (typeof value === "bigint") return value.toString();
+		if (typeof value === "object" && value !== null) {
+			if (seen.has(value)) return "[Circular]";
+			seen.add(value);
+		}
+		return value;
+	};
+}
+/**
+* Serialize a record to one JSON line, tolerating cycles and `BigInt` so a log call is crash-proof. If
+* even the safe pass fails, fall back to the always-serializable core fields — never throw.
+*/
+function serializeRecord(record) {
+	try {
+		return JSON.stringify(record, safeReplacer());
+	} catch {
+		return JSON.stringify({
+			level: record.level,
+			msg: record.msg,
+			time: record.time
+		});
+	}
+}
+//#endregion
+export { LOG_LEVEL_ORDER, LogFields, LogLevel, LogRecord, serializeRecord };

package/dist/logger/worker.d.ts

@@ -0,0 +1,74 @@
+import { type Logger } from "./logger";
+import type { LogFields, LogLevel, LogRecord } from "./record";
+/**
+ * Mode 2 — CF-native structured logs, for a deployed Worker. Each log emits as **one per-line
+ * structured record** Cloudflare Workers Logs indexes and can query — not one buried per-request blob.
+ * With `observability.enabled` on in the generated `wrangler.jsonc`, these are queryable in the
+ * dashboard with zero adopter setup. The `transport` hook fans the same records to a tail-consumer
+ * Worker or Logpush without touching any call site.
+ */
+/** Options for {@link createWorkerLogger}. */
+export interface WorkerLoggerOptions {
+    /** The threshold. Defaults to `info` — a deployed Worker is quieter than local dev. */
+    level?: LogLevel;
+    /**
+     * The tail/Logpush plug point: called with every finished record after it is emitted, so records can
+     * fan to a tail-consumer or Logpush unchanged. Enabling it changes no log call site.
+     */
+    transport?: (record: LogRecord) => void;
+    /**
+     * How a record reaches Workers Logs. Defaults to a single crash-proof JSON line via `console.log`,
+     * which Workers Logs indexes as structured JSON. Injectable for tests.
+     */
+    emit?: (record: LogRecord) => void;
+    /** Fields bound onto every record (e.g. `env`, `version`). */
+    fields?: LogFields;
+    /** A starting namespace. */
+    name?: string;
+    /** The clock, injectable for tests. */
+    now?: () => number;
+}
+/**
+ * Build a Mode 2 CF-native logger. The sink emits one structured line to Workers Logs, then hands the
+ * same record to `transport` when one is configured. The record shape is unchanged whether or not a
+ * transport is attached — tail/Logpush readiness is by construction.
+ */
+export declare function createWorkerLogger(options?: WorkerLoggerOptions): Logger;
+/** The per-request correlation fields bound onto every Worker-side record. Resolved from the request. */
+export interface RequestContext {
+    /** A stable id for this request (the CF ray id, or a generated uuid). */
+    request: string;
+    /** The HTTP method. */
+    method: string;
+    /** The request path. */
+    path: string;
+    /** The environment name (`dev` | `staging` | `production`), from config. */
+    env: string;
+    /** The deployed Worker version id, when the version-metadata binding is present. */
+    version?: string;
+}
+/**
+ * Derive a per-request logger by binding {@link RequestContext} onto `base` — so every record the
+ * handler emits auto-carries `request`/`method`/`path`/`env`/`version` with no caller effort. Uses the
+ * nameless `child` form, leaving the logger's namespace free for a capability to claim.
+ */
+export declare function bindRequestContext(base: Logger, context: RequestContext): Logger;
+/** The per-run correlation fields bound onto every record a Workflow emits. Resolved from the run's event and env. */
+export interface WorkflowContext {
+    /** The deployed Workflow name, from `event.workflowName`. */
+    workflow: string;
+    /** This run's instance id, from `event.instanceId` — what the dashboard and `wrangler workflows` key on. */
+    instance: string;
+    /** The environment name (`dev` | `staging` | `prod`), from the host's `ENVIRONMENT` var. */
+    env: string;
+    /** The deployed Worker version id, when the version-metadata binding is present. */
+    version?: string;
+}
+/**
+ * Derive a per-run logger by binding {@link WorkflowContext} onto `base` — the Workflow peer of
+ * {@link bindRequestContext}, so a durable run correlates the way a request already does. A run has no
+ * method or path; it has an instance, and that is the id anyone reading Workflows Logs searches by. Uses
+ * the nameless `child` form, leaving the logger's namespace free for a capability to claim.
+ */
+export declare function bindWorkflowContext(base: Logger, context: WorkflowContext): Logger;
+//# sourceMappingURL=worker.d.ts.map

package/dist/logger/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/logger/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG/D;;;;;;GAMG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,8DAA8D;IAC9D,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAgB5E;AAED,yGAAyG;AACzG,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAShF;AAED,sHAAsH;AACtH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,4GAA4G;IAC5G,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAQlF"}

package/dist/logger/worker.js

@@ -0,0 +1,54 @@
+import { serializeRecord } from "./record.js";
+import { createLogger } from "./logger.js";
+//#region src/logger/worker.ts
+/**
+* Build a Mode 2 CF-native logger. The sink emits one structured line to Workers Logs, then hands the
+* same record to `transport` when one is configured. The record shape is unchanged whether or not a
+* transport is attached — tail/Logpush readiness is by construction.
+*/
+function createWorkerLogger(options = {}) {
+	const emit = options.emit ?? ((record) => console.log(serializeRecord(record)));
+	const { transport } = options;
+	return createLogger({
+		level: options.level ?? "info",
+		name: options.name,
+		fields: options.fields,
+		now: options.now,
+		sink: (record) => {
+			emit(record);
+			transport?.(record);
+		}
+	});
+}
+/**
+* Derive a per-request logger by binding {@link RequestContext} onto `base` — so every record the
+* handler emits auto-carries `request`/`method`/`path`/`env`/`version` with no caller effort. Uses the
+* nameless `child` form, leaving the logger's namespace free for a capability to claim.
+*/
+function bindRequestContext(base, context) {
+	const fields = {
+		request: context.request,
+		method: context.method,
+		path: context.path,
+		env: context.env
+	};
+	if (context.version !== void 0) fields.version = context.version;
+	return base.child(void 0, fields);
+}
+/**
+* Derive a per-run logger by binding {@link WorkflowContext} onto `base` — the Workflow peer of
+* {@link bindRequestContext}, so a durable run correlates the way a request already does. A run has no
+* method or path; it has an instance, and that is the id anyone reading Workflows Logs searches by. Uses
+* the nameless `child` form, leaving the logger's namespace free for a capability to claim.
+*/
+function bindWorkflowContext(base, context) {
+	const fields = {
+		workflow: context.workflow,
+		instance: context.instance,
+		env: context.env
+	};
+	if (context.version !== void 0) fields.version = context.version;
+	return base.child(void 0, fields);
+}
+//#endregion
+export { bindRequestContext, bindWorkflowContext, createWorkerLogger };

package/dist/migrations/batch.d.ts

@@ -0,0 +1,10 @@
+import type { D1Database } from "@cloudflare/workers-types";
+import type { MigrationProvider } from "kysely/migration";
+/**
+ * Wrap a provider so every migration it yields applies and reverses in one round trip each.
+ *
+ * Applied at the runner's seam rather than inside each capability, so a migration author writes
+ * ordinary Kysely and gets this for free — including adopters, who are the ones paying for it.
+ */
+export declare function batchedProvider(provider: MigrationProvider, database: D1Database): MigrationProvider;
+//# sourceMappingURL=batch.d.ts.map

package/dist/migrations/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/migrations/batch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAuB,MAAM,2BAA2B,CAAC;AAGjF,OAAO,KAAK,EAAa,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA4MrE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,EAAE,UAAU,GAAG,iBAAiB,CASpG"}

package/dist/migrations/batch.js

@@ -0,0 +1,193 @@
+import { D1MigrationDialect } from "./bookkeeping.js";
+import { CamelCasePlugin, Kysely } from "kysely";
+//#region src/migrations/batch.ts
+/**
+* **One round trip per migration, instead of one per statement.**
+*
+* `kysely-d1` executes every compiled query as its own `prepare().bind().all()`, so a capability's
+* `0001_init` — nineteen tables and thirty-eight indexes, composed — cost fifty-seven hops to D1.
+* Measured against a real composed application in the Workers runtime: 1,028ms and 68 round trips to
+* migrate, 2,041ms per drop-and-rebuild. An adopter following the kit's own advice (Workers-runtime
+* tests against real D1, not mocks) pays that once per test that needs a clean database; in
+* `pithy-sh/dashboard` it was 78% of total wall time, and the setup floor it left put ordinary test
+* bodies within reach of the 5,000ms timeout (`pithy-sh/pithy#368`).
+*
+* `d1.batch()` sends many statements in one round trip, in order, in one implicit transaction. A
+* migration's statements are already ordered and already a unit, which is the shape `batch` exists
+* for. So a migration body runs against a Kysely whose driver **queues** its statements and sends
+* them as one batch when the body returns.
+*
+* ## Only DDL is queued, and that is the whole safety argument
+*
+* A queued statement's result is returned to the migration body before the statement has run, so it
+* cannot carry rows, a row count, or an insert id. Rather than document that as a caveat, the queue
+* only takes statements that **have no such result to carry** — `create`/`drop`/`alter` on a table,
+* index, view, schema or type. Everything else — every select, insert, update, delete, and every raw
+* `sql` template, whose shape is not knowable from its node — **flushes the queue and then executes
+* on its own**, exactly as before. Ordering is therefore preserved unconditionally: a read always
+* sees every statement written before it.
+*
+* The consequence worth stating: a migration that interleaves data with DDL is split into several
+* batches, one per run of consecutive DDL. It is still correct and still faster; it is simply not one
+* transaction. Every migration the kit ships is pure DDL and is one batch.
+*
+* ## Failure semantics, which did change
+*
+* Before: a migration failing at its k-th statement left statements 1..k-1 applied, with no ledger
+* row — a half-applied migration, the thing a chain exists to prevent. After: the batch is the unit,
+* so a failure anywhere in it rolls back all of it and the ledger still records nothing. The
+* migration is all-or-nothing.
+*
+* What did **not** change is anything across a migration boundary. Each `up`/`down` builds its own
+* queue and flushes before returning, so no statement of one migration can share a batch with
+* another's, and the ledger row is written by Kysely's `Migrator` on the ordinary path afterwards.
+* A chain that fails at its third migration still has its first two applied and recorded, and the
+* error still names them. Batching across migrations would make a partial chain unrepresentable in
+* the ledger, which is worse than slow.
+*/
+/**
+* Compiled-query kinds with no result a migration body could read — the only ones safe to queue.
+* SQLite ignores schemas and types, but the nodes exist and cost nothing to name.
+*/
+const QUEUEABLE_KINDS = /* @__PURE__ */ new Set([
+	"CreateTableNode",
+	"DropTableNode",
+	"CreateIndexNode",
+	"DropIndexNode",
+	"AlterTableNode",
+	"CreateViewNode",
+	"DropViewNode",
+	"CreateSchemaNode",
+	"DropSchemaNode",
+	"CreateTypeNode",
+	"DropTypeNode"
+]);
+/** Statements waiting for their one round trip. Ordered; flushed as a single `d1.batch()`. */
+var StatementQueue = class {
+	#database;
+	#pending = [];
+	constructor(database) {
+		this.#database = database;
+	}
+	add(query) {
+		this.#pending.push(query);
+	}
+	/**
+	* Send everything queued, in order, as one batch — and nothing at all when nothing is queued, so a
+	* flush is always safe to call. Cleared before the call, so a failed batch is not retried by a
+	* later flush.
+	*/
+	async flush() {
+		if (this.#pending.length === 0) return;
+		const pending = this.#pending;
+		this.#pending = [];
+		const statements = pending.map((query) => this.#database.prepare(query.sql).bind(...query.parameters));
+		await this.#database.batch(statements);
+	}
+};
+/** Queues what it can, and flushes before anything it cannot — see the module note. */
+var QueueingConnection = class {
+	#direct;
+	#queue;
+	constructor(direct, queue) {
+		this.#direct = direct;
+		this.#queue = queue;
+	}
+	async executeQuery(query) {
+		if (QUEUEABLE_KINDS.has(query.query.kind)) {
+			this.#queue.add(query);
+			return { rows: [] };
+		}
+		await this.#queue.flush();
+		return this.#direct.executeQuery(query);
+	}
+	streamQuery(query, chunkSize) {
+		return this.#direct.streamQuery(query, chunkSize);
+	}
+};
+/** The stock D1 driver, with every connection wrapped in the queue. Transactions stay unsupported. */
+var QueueingDriver = class {
+	#inner;
+	#queue;
+	#inners = /* @__PURE__ */ new WeakMap();
+	constructor(inner, queue) {
+		this.#inner = inner;
+		this.#queue = queue;
+	}
+	async init() {
+		await this.#inner.init();
+	}
+	async acquireConnection() {
+		const inner = await this.#inner.acquireConnection();
+		const wrapped = new QueueingConnection(inner, this.#queue);
+		this.#inners.set(wrapped, inner);
+		return wrapped;
+	}
+	async beginTransaction(connection, settings) {
+		await this.#inner.beginTransaction(this.#unwrap(connection), settings);
+	}
+	async commitTransaction(connection) {
+		await this.#inner.commitTransaction(this.#unwrap(connection));
+	}
+	async rollbackTransaction(connection) {
+		await this.#inner.rollbackTransaction(this.#unwrap(connection));
+	}
+	async releaseConnection(connection) {
+		await this.#inner.releaseConnection(this.#unwrap(connection));
+	}
+	async destroy() {
+		await this.#inner.destroy();
+	}
+	#unwrap(connection) {
+		return this.#inners.get(connection) ?? connection;
+	}
+};
+/** Pithy's D1 dialect — same compiler, same `sqlite_master`-only introspector — driving the queue. */
+var QueueingD1Dialect = class extends D1MigrationDialect {
+	#queue;
+	constructor(database, queue) {
+		super({ database });
+		this.#queue = queue;
+	}
+	createDriver() {
+		return new QueueingDriver(super.createDriver(), this.#queue);
+	}
+};
+/**
+* Run one migration body against a queueing Kysely and send its statements as one batch.
+*
+* The `db` Kysely's `Migrator` would have passed is deliberately not used: it is the instance that
+* also writes the ledger, and the ledger row must stay on the ordinary path so that a failed batch
+* leaves no record of having applied. Same binding, same `CamelCasePlugin`, same dialect — a
+* migration body cannot tell the difference except in how many hops it costs.
+*/
+async function batchBody(body, database) {
+	const queue = new StatementQueue(database);
+	await body(new Kysely({
+		dialect: new QueueingD1Dialect(database, queue),
+		plugins: [new CamelCasePlugin()]
+	}));
+	await queue.flush();
+}
+/** One migration, both directions batched. A migration with no `down` still has none. */
+function batchMigration(migration, database) {
+	const down = migration.down;
+	return {
+		up: async () => batchBody((db) => migration.up(db), database),
+		...down ? { down: async () => batchBody((db) => down(db), database) } : {}
+	};
+}
+/**
+* Wrap a provider so every migration it yields applies and reverses in one round trip each.
+*
+* Applied at the runner's seam rather than inside each capability, so a migration author writes
+* ordinary Kysely and gets this for free — including adopters, who are the ones paying for it.
+*/
+function batchedProvider(provider, database) {
+	return { getMigrations: async () => {
+		const migrations = await provider.getMigrations();
+		return Object.fromEntries(Object.entries(migrations).map(([name, migration]) => [name, batchMigration(migration, database)]));
+	} };
+}
+//#endregion
+export { batchedProvider };

package/dist/migrations/bookkeeping.d.ts

@@ -0,0 +1,24 @@
+import type { D1Database } from "@cloudflare/workers-types";
+import type { DatabaseIntrospector } from "kysely";
+import { Kysely } from "kysely";
+import { D1Dialect } from "kysely-d1";
+/**
+ * The applied-migration ledger. Renamed off Kysely's `kysely_migration` default: an adopter running
+ * their own Kysely migrations on the same D1 would otherwise collide on it (principle 1).
+ */
+export declare const MIGRATION_TABLE = "pithy_migrations";
+/** The migration lock, renamed off Kysely's `kysely_migration_lock` default for the same reason. */
+export declare const MIGRATION_LOCK_TABLE = "pithy_migrations_lock";
+/**
+ * The owning project's stamp — one row, written by `claimMigrationOwnership`, read by `pithy migrate`
+ * before it applies anything. Deliberately *beside* the ledger rather than inside it: it is not a
+ * migration, so a rollback or a full reset must not remove it, and no capability has to ship it.
+ */
+export declare const MIGRATION_OWNER_TABLE = "pithy_migrations_owner";
+/** The D1 dialect Pithy migrates through: stock kysely-d1, with the `sqlite_master`-only introspector. */
+export declare class D1MigrationDialect extends D1Dialect {
+    createIntrospector(db: Kysely<unknown>): DatabaseIntrospector;
+}
+/** A Kysely over one D1 binding, with Pithy's dialect and `CamelCasePlugin` — the one way in. */
+export declare function migrationKysely<DB = unknown>(database: D1Database): Kysely<DB>;
+//# sourceMappingURL=bookkeeping.d.ts.map

package/dist/migrations/bookkeeping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bookkeeping.d.ts","sourceRoot":"","sources":["../../src/migrations/bookkeeping.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAA0D,MAAM,QAAQ,CAAC;AAC3G,OAAO,EAAmB,MAAM,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAsBtC;;;GAGG;AACH,eAAO,MAAM,eAAe,qBAAqB,CAAC;AAElD,oGAAoG;AACpG,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAgC9D,0GAA0G;AAC1G,qBAAa,kBAAmB,SAAQ,SAAS;IACtC,kBAAkB,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,oBAAoB,CAErE;CACF;AAED,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,CAAC,CAE9E"}

package/dist/migrations/bookkeeping.js

@@ -0,0 +1,57 @@
+import { CamelCasePlugin, Kysely } from "kysely";
+import { D1Dialect } from "kysely-d1";
+//#region src/migrations/bookkeeping.ts
+/**
+* The applied-migration ledger. Renamed off Kysely's `kysely_migration` default: an adopter running
+* their own Kysely migrations on the same D1 would otherwise collide on it (principle 1).
+*/
+const MIGRATION_TABLE = "pithy_migrations";
+/** The migration lock, renamed off Kysely's `kysely_migration_lock` default for the same reason. */
+const MIGRATION_LOCK_TABLE = "pithy_migrations_lock";
+/**
+* The owning project's stamp — one row, written by `claimMigrationOwnership`, read by `pithy migrate`
+* before it applies anything. Deliberately *beside* the ledger rather than inside it: it is not a
+* migration, so a rollback or a full reset must not remove it, and no capability has to ship it.
+*/
+const MIGRATION_OWNER_TABLE = "pithy_migrations_owner";
+/** Pithy's bookkeeping tables — hidden by the introspector the way Kysely hides its own defaults. */
+const INTERNAL_TABLES = [
+	MIGRATION_TABLE,
+	MIGRATION_LOCK_TABLE,
+	MIGRATION_OWNER_TABLE
+];
+/** Table names from `sqlite_master` only — no pragma joins, no column metadata. */
+var D1Introspector = class {
+	#db;
+	constructor(db) {
+		this.#db = db;
+	}
+	async getSchemas() {
+		return [];
+	}
+	async getTables(options = { withInternalKyselyTables: false }) {
+		let query = this.#db.selectFrom("sqlite_master").where("type", "in", ["table", "view"]).where("name", "not like", "sqlite_%").select(["name", "type"]).orderBy("name");
+		if (!options.withInternalKyselyTables) query = query.where("name", "not in", INTERNAL_TABLES);
+		return (await query.execute()).map((row) => ({
+			name: row.name,
+			isView: row.type === "view",
+			isForeign: false,
+			columns: []
+		}));
+	}
+};
+/** The D1 dialect Pithy migrates through: stock kysely-d1, with the `sqlite_master`-only introspector. */
+var D1MigrationDialect = class extends D1Dialect {
+	createIntrospector(db) {
+		return new D1Introspector(db);
+	}
+};
+/** A Kysely over one D1 binding, with Pithy's dialect and `CamelCasePlugin` — the one way in. */
+function migrationKysely(database) {
+	return new Kysely({
+		dialect: new D1MigrationDialect({ database }),
+		plugins: [new CamelCasePlugin()]
+	});
+}
+//#endregion
+export { D1MigrationDialect, MIGRATION_LOCK_TABLE, MIGRATION_OWNER_TABLE, MIGRATION_TABLE, migrationKysely };

package/dist/migrations/owner.d.ts

@@ -0,0 +1,41 @@
+import type { D1Database } from "@cloudflare/workers-types";
+import { z } from "zod";
+/** The recorded owner of a database: who stamped it, and when. */
+export declare const MigrationOwner: z.ZodObject<{
+    project: z.ZodString;
+    stampedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type MigrationOwner = z.output<typeof MigrationOwner>;
+/** How a claim resolved: the database had no owner, or it already had this one. */
+export type OwnershipOutcome = "adopted" | "confirmed";
+/** The result of a successful claim — a refused one throws instead. */
+export interface ProjectOwnership {
+    /** The claiming project, which is now (or already was) the recorded owner. */
+    project: string;
+    /** `adopted` on the first migrate of a database, `confirmed` on every run after it. */
+    outcome: OwnershipOutcome;
+    /** When the owner was first recorded — the original stamp, not this run. */
+    stampedAt: Date;
+}
+/** Who is claiming, and how to name the database if the claim is refused. */
+export interface ClaimOwnershipOptions {
+    /** The claiming project — the root `pithy.config.ts` `name`, kebab-cased (`requireProjectName`). */
+    project: string;
+    /** The binding this database is reached by (`DB`), so a refusal names it. Optional. */
+    binding?: string;
+}
+/**
+ * The project recorded as this database's owner, or `undefined` when none is — read-only, creating
+ * nothing. `pithy doctor` and any other reporter reads the stamp through this; only
+ * {@link claimMigrationOwnership} writes it.
+ */
+export declare function readMigrationOwner(database: D1Database): Promise<MigrationOwner | undefined>;
+/**
+ * Claim a database for a project, or refuse it to a foreign one. Idempotent and safe to re-run: an
+ * unstamped database is adopted (nothing has shipped, so a first run has no ambiguity to preserve),
+ * the owning project re-claims as a no-op, and any other project throws a `core/conflict` naming both
+ * projects. The insert is `on conflict do nothing` against a fixed primary key and is followed by a
+ * re-read, so two runs racing the very first claim settle on one owner rather than two rows.
+ */
+export declare function claimMigrationOwnership(database: D1Database, options: ClaimOwnershipOptions): Promise<ProjectOwnership>;
+//# sourceMappingURL=owner.d.ts.map

package/dist/migrations/owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../src/migrations/owner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2BxB,kEAAkE;AAClE,eAAO,MAAM,cAAc;;;iBAOuF,CAAC;AACnH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAa7D,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,CAAC;AAEvD,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,OAAO,EAAE,gBAAgB,CAAC;IAC1B,4EAA4E;IAC5E,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA8BD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAElG;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,UAAU,EACpB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CA0C3B"}