@pithy-sh/core 0.1.2 → 0.1.3

package/dist/data/cursor.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+//#region src/data/cursor.ts
+/**
+* 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. */
+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. */
+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.
+*/
+function pageLimit(requested) {
+	return Math.min(Math.max(requested ?? 25, 1), 100);
+}
+/**
+* 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.
+*/
+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.");
+/**
+* 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.
+*/
+function encodeCursor(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.
+*/
+function decodeCursor(value) {
+	if (!value) return void 0;
+	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 : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* 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.
+*/
+function toPage(rows, limit, position) {
+	const hasMore = rows.length > limit;
+	const items = hasMore ? rows.slice(0, limit) : [...rows];
+	const last = items[items.length - 1];
+	return {
+		items,
+		nextCursor: hasMore && last !== void 0 ? encodeCursor(position(last)) : null
+	};
+}
+//#endregion
+export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, PageCursor, decodeCursor, encodeCursor, pageLimit, toPage };

package/dist/data/databases.d.ts

@@ -0,0 +1,55 @@
+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 } from "../capability/compose";
+import { 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 declare function composeDatabases(capabilities: Capability[]): MergedDatabases;
+/** 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 declare function buildDbRegistry(env: Record<string, unknown>, databases: MergedDatabases): LiveDbRegistry;
+export {};
+//# sourceMappingURL=databases.d.ts.map

package/dist/data/databases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"databases.d.ts","sourceRoot":"","sources":["../../src/data/databases.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,KAAK,YAAY,EAA2C,MAAM,uBAAuB,CAAC;AACnG,OAAO,EAAkB,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,MAAM,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS;IAChE,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACvC,uHAAuH;IACvH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,GAAG,SAAS,eAAe,IAAI;KACnD,IAAI,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,YAAY,CAAC,MAAM,MAAM,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK;CAC3G,CAAC;AAEF,yGAAyG;AACzG,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,eAAe,CAO5E;AAED,uGAAuG;AACvG,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,eAAe,GAAG,cAAc,CAaxG"}

package/dist/data/databases.js

@@ -0,0 +1,32 @@
+import { createDatabase } from "./db.js";
+import { bindingGroupsFrom, composeBindingGroups } from "../capability/compose.js";
+//#region src/data/databases.ts
+/**
+* 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.
+*/
+function composeDatabases(capabilities) {
+	return composeBindingGroups(capabilities, (cap) => bindingGroupsFrom(cap.databases, (db) => db.tables), "database", "table");
+}
+/**
+* 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.
+*/
+function buildDbRegistry(env, databases) {
+	const registry = {};
+	for (const [name, group] of Object.entries(databases)) {
+		let instance;
+		Object.defineProperty(registry, name, {
+			enumerable: true,
+			get() {
+				if (!instance) instance = createDatabase(env[group.binding], group.items);
+				return instance;
+			}
+		});
+	}
+	return registry;
+}
+//#endregion
+export { buildDbRegistry, composeDatabases };

package/dist/data/db.d.ts

@@ -0,0 +1,42 @@
+import type { D1Database } from "@cloudflare/workers-types";
+import { type Generated, Kysely } from "kysely";
+import type { z } from "zod";
+/**
+ * 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 declare function createDatabase<M extends SchemaMap>(d1: D1Database, map: M): Kysely<DatabaseSchema<M>>;
+//# sourceMappingURL=db.d.ts.map

package/dist/data/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/data/db.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEjE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B;;;;;;;;GAQG;AAEH,4DAA4D;AAC5D,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,GAAG,IAAI,GAAG,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG;IAAE,EAAE,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;CAAE,GAAG,GAAG,CAAC;AAElH,sFAAsF;AACtF,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,SAAS,IAAI;KAC/C,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,SAAS,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAMrG"}

package/dist/data/db.js

@@ -0,0 +1,24 @@
+import { guardBoundParameters } from "./boundParameters.js";
+import { CamelCasePlugin, Kysely } from "kysely";
+import { D1Dialect } from "kysely-d1";
+//#region src/data/db.ts
+/**
+* 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.
+*/
+function createDatabase(d1, map) {
+	return new Kysely({
+		dialect: new D1Dialect({ database: guardBoundParameters(d1) }),
+		plugins: [new CamelCasePlugin()]
+	});
+}
+//#endregion
+export { createDatabase };

package/dist/data/withD1Retry.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Retry a D1 write through transient faults. Ported from the CMS `withD1Retry`, adapted to
+ * Pithy: no injected logger (core has none), an optional `onRetry` notifier instead, and a
+ * documented idempotency guard. The shared helper every capability's D1 writes can wrap; the
+ * audit recorder is its first consumer.
+ *
+ * D1 surfaces a whole family of transient failures by message — a statement that exceeded its
+ * timeout, a database briefly locked/busy under contention, a dropped network connection to the
+ * backing store, a storage object reset mid-flight, or an opaque internal error. All of these are
+ * worth retrying with exponential backoff; a deterministic failure (a constraint violation, a SQL
+ * error) is not. The matchers key off the error message because that is all D1 exposes; a
+ * non-matching error is re-thrown untouched (this is a passthrough wrapper, never an originator — it
+ * does not wrap foreign throws in a `PithyError`; the caller's own layer owns that). By default
+ * **every** transient class is retried, so a caller gets robust coverage without enumerating D1's
+ * error vocabulary.
+ *
+ * The idempotency guard is always active and independent of `retryOn`: a `unique-constraint`
+ * failure **on a retry** (attempt > 0) means the prior attempt already committed the row before its
+ * transport hiccup — the retry is the duplicate, not a real conflict — so the wrapper returns rather
+ * than throwing. A unique-constraint never *initiates* a retry (it is not a transient fault), so on
+ * the **first** attempt it is a genuine conflict and propagates. This is what makes a broad retry
+ * policy safe for a write: pair it with a unique idempotency key (the audit recorder's `eventId`) and
+ * a post-commit retry can never double-write.
+ */
+/** A retryable D1 fault class, matched against the error message. */
+export declare const D1RetryableError: {
+    /** A statement exceeded its execution timeout (`exceeded timeout`, `storage timeout`, `Timed out`). */
+    readonly TIMEOUT: "timeout";
+    /** The database was locked or busy under contention (`database is locked/busy`, `SQLITE_BUSY`). */
+    readonly DATABASE_BUSY: "database-busy";
+    /** The connection to the backing store dropped mid-request (`Network connection lost`, `connection … reset`). */
+    readonly NETWORK: "network";
+    /** The storage object was reset mid-flight (`reset because its code was updated`, `caused object to be reset`). */
+    readonly STORAGE_RESET: "storage-reset";
+    /** An opaque D1/storage internal error (`internal error`, `Cannot resolve D1`). */
+    readonly INTERNAL: "internal";
+    /** A UNIQUE constraint failed — never a retry initiator; drives only the idempotency guard (see module doc). */
+    readonly UNIQUE_CONSTRAINT: "unique-constraint";
+};
+export type D1RetryableError = (typeof D1RetryableError)[keyof typeof D1RetryableError];
+/** Every transient (retry-initiating) fault class — the default `retryOn`. Excludes the guard-only `unique-constraint`. */
+export declare const D1_TRANSIENT_ERRORS: readonly D1RetryableError[];
+/** One D1 retry attempt's context, handed to {@link D1RetryOptions.onRetry}. */
+export interface D1RetryInfo {
+    /** The fault class that triggered the retry. */
+    error: D1RetryableError;
+    /** The attempt that just failed (0-based). */
+    attempt: number;
+    /** The configured maximum number of retries. */
+    maxRetries: number;
+    /** How long the wrapper will wait before the next attempt, in ms. */
+    delayMs: number;
+}
+/** Options for {@link withD1Retry}. All optional; the defaults retry timeouts three times. */
+export interface D1RetryOptions {
+    /**
+     * Which transient fault classes initiate a retry. Defaults to {@link D1_TRANSIENT_ERRORS} — every
+     * transient class. Narrow it only when a caller deliberately wants to ignore some. Listing
+     * `unique-constraint` here has no effect — it is never a retry initiator; it only ever drives the
+     * always-on idempotency guard (see module doc).
+     */
+    retryOn?: readonly D1RetryableError[];
+    /** Maximum retries after the initial attempt. Defaults to `3`. */
+    maxRetries?: number;
+    /** Backoff base delay, in ms. Defaults to `200`. */
+    initialDelayMs?: number;
+    /** Backoff growth factor. Defaults to `2` (200ms, 400ms, 800ms…). */
+    backoffMultiplier?: number;
+    /** Notified before each backoff wait — for an optional log line. Never throws into the retry. */
+    onRetry?: (info: D1RetryInfo) => void;
+}
+/**
+ * The transient D1 fault class an error is, or `null` when D1 did not report one of them.
+ *
+ * The same matchers this wrapper retries on, exported because a second layer has to ask the same
+ * question: a Workflow step decides whether to re-drive a body that raised, and "is this D1 fault
+ * transient" must have exactly one answer in this kit (pithy-sh/pithy#338). A step that classified D1
+ * for itself would be a second vocabulary — and the one that drifted would be the one nobody read.
+ *
+ * `unique-constraint` is deliberately not reported: it is the idempotency guard's signal, never a
+ * transient fault, so a caller asking "should this be retried" is told no.
+ */
+export declare function d1TransientFault(error: unknown): D1RetryableError | null;
+/**
+ * Run `fn`, retrying it through the configured transient D1 faults with exponential backoff.
+ * Returns `fn`'s result; on the idempotency-guard path (a unique-constraint on a retry) returns
+ * `undefined` cast to `T`, since the prior attempt already produced the effect. A non-retryable
+ * error, or exhausted retries, throws the last error untouched.
+ */
+export declare function withD1Retry<T>(fn: () => Promise<T>, options?: D1RetryOptions): Promise<T>;
+//# sourceMappingURL=withD1Retry.d.ts.map

package/dist/data/withD1Retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withD1Retry.d.ts","sourceRoot":"","sources":["../../src/data/withD1Retry.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,qEAAqE;AACrE,eAAO,MAAM,gBAAgB;IAC3B,uGAAuG;aACvG,OAAO,EAAE,SAAS;IAClB,mGAAmG;aACnG,aAAa,EAAE,eAAe;IAC9B,iHAAiH;aACjH,OAAO,EAAE,SAAS;IAClB,mHAAmH;aACnH,aAAa,EAAE,eAAe;IAC9B,mFAAmF;aACnF,QAAQ,EAAE,UAAU;IACpB,gHAAgH;aAChH,iBAAiB,EAAE,mBAAmB;CAC9B,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAExF,2HAA2H;AAC3H,eAAO,MAAM,mBAAmB,EAAE,SAAS,gBAAgB,EAM1D,CAAC;AAEF,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,KAAK,EAAE,gBAAgB,CAAC;IACxB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iGAAiG;IACjG,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CACvC;AA0CD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAExE;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CA6B/F"}

package/dist/data/withD1Retry.js

@@ -0,0 +1,152 @@
+//#region src/data/withD1Retry.ts
+/**
+* Retry a D1 write through transient faults. Ported from the CMS `withD1Retry`, adapted to
+* Pithy: no injected logger (core has none), an optional `onRetry` notifier instead, and a
+* documented idempotency guard. The shared helper every capability's D1 writes can wrap; the
+* audit recorder is its first consumer.
+*
+* D1 surfaces a whole family of transient failures by message — a statement that exceeded its
+* timeout, a database briefly locked/busy under contention, a dropped network connection to the
+* backing store, a storage object reset mid-flight, or an opaque internal error. All of these are
+* worth retrying with exponential backoff; a deterministic failure (a constraint violation, a SQL
+* error) is not. The matchers key off the error message because that is all D1 exposes; a
+* non-matching error is re-thrown untouched (this is a passthrough wrapper, never an originator — it
+* does not wrap foreign throws in a `PithyError`; the caller's own layer owns that). By default
+* **every** transient class is retried, so a caller gets robust coverage without enumerating D1's
+* error vocabulary.
+*
+* The idempotency guard is always active and independent of `retryOn`: a `unique-constraint`
+* failure **on a retry** (attempt > 0) means the prior attempt already committed the row before its
+* transport hiccup — the retry is the duplicate, not a real conflict — so the wrapper returns rather
+* than throwing. A unique-constraint never *initiates* a retry (it is not a transient fault), so on
+* the **first** attempt it is a genuine conflict and propagates. This is what makes a broad retry
+* policy safe for a write: pair it with a unique idempotency key (the audit recorder's `eventId`) and
+* a post-commit retry can never double-write.
+*/
+/** A retryable D1 fault class, matched against the error message. */
+const D1RetryableError = {
+	/** A statement exceeded its execution timeout (`exceeded timeout`, `storage timeout`, `Timed out`). */
+	TIMEOUT: "timeout",
+	/** The database was locked or busy under contention (`database is locked/busy`, `SQLITE_BUSY`). */
+	DATABASE_BUSY: "database-busy",
+	/** The connection to the backing store dropped mid-request (`Network connection lost`, `connection … reset`). */
+	NETWORK: "network",
+	/** The storage object was reset mid-flight (`reset because its code was updated`, `caused object to be reset`). */
+	STORAGE_RESET: "storage-reset",
+	/** An opaque D1/storage internal error (`internal error`, `Cannot resolve D1`). */
+	INTERNAL: "internal",
+	/** A UNIQUE constraint failed — never a retry initiator; drives only the idempotency guard (see module doc). */
+	UNIQUE_CONSTRAINT: "unique-constraint"
+};
+/** Every transient (retry-initiating) fault class — the default `retryOn`. Excludes the guard-only `unique-constraint`. */
+const D1_TRANSIENT_ERRORS = [
+	D1RetryableError.TIMEOUT,
+	D1RetryableError.DATABASE_BUSY,
+	D1RetryableError.NETWORK,
+	D1RetryableError.STORAGE_RESET,
+	D1RetryableError.INTERNAL
+];
+/**
+* Lowercased message substrings that identify each fault class. Matching is case-insensitive (the
+* message is lowered first) and substring-based, because D1 wraps the same underlying fault in
+* varying envelopes (`D1_ERROR: …`, a bare SQLite message, a Workers runtime message). Each list is
+* the set of signatures Cloudflare is known to surface for that class.
+*/
+const errorMatchers = {
+	timeout: [
+		"exceeded timeout",
+		"storage timeout",
+		"timed out"
+	],
+	"database-busy": [
+		"database is locked",
+		"database is busy",
+		"sqlite_busy"
+	],
+	network: [
+		"network connection lost",
+		"connection was reset",
+		"connection reset",
+		"connection lost"
+	],
+	"storage-reset": [
+		"reset because its code was updated",
+		"caused object to be reset",
+		"durable object reset"
+	],
+	internal: [
+		"internal error",
+		"cannot resolve d1",
+		"an unknown error occurred"
+	],
+	"unique-constraint": ["unique constraint failed"]
+};
+/** Whether a lowercased message matches any signature of `fault`. */
+function matchesFault(message, fault) {
+	return errorMatchers[fault].some((signature) => message.includes(signature));
+}
+/** Whether an error is a UNIQUE-constraint failure — the idempotency-guard signal. */
+function isUniqueConstraint(error) {
+	return error instanceof Error && matchesFault(error.message.toLowerCase(), D1RetryableError.UNIQUE_CONSTRAINT);
+}
+/**
+* The transient fault class an error matches within `retryOn`, or `null` if none. `unique-constraint`
+* is excluded from initiation — it is handled only by the idempotency guard — so listing it in
+* `retryOn` is a no-op.
+*/
+function matchTransient(error, retryOn) {
+	if (!(error instanceof Error)) return null;
+	const message = error.message.toLowerCase();
+	for (const fault of retryOn) {
+		if (fault === D1RetryableError.UNIQUE_CONSTRAINT) continue;
+		if (matchesFault(message, fault)) return fault;
+	}
+	return null;
+}
+/**
+* The transient D1 fault class an error is, or `null` when D1 did not report one of them.
+*
+* The same matchers this wrapper retries on, exported because a second layer has to ask the same
+* question: a Workflow step decides whether to re-drive a body that raised, and "is this D1 fault
+* transient" must have exactly one answer in this kit (pithy-sh/pithy#338). A step that classified D1
+* for itself would be a second vocabulary — and the one that drifted would be the one nobody read.
+*
+* `unique-constraint` is deliberately not reported: it is the idempotency guard's signal, never a
+* transient fault, so a caller asking "should this be retried" is told no.
+*/
+function d1TransientFault(error) {
+	return matchTransient(error, D1_TRANSIENT_ERRORS);
+}
+/**
+* Run `fn`, retrying it through the configured transient D1 faults with exponential backoff.
+* Returns `fn`'s result; on the idempotency-guard path (a unique-constraint on a retry) returns
+* `undefined` cast to `T`, since the prior attempt already produced the effect. A non-retryable
+* error, or exhausted retries, throws the last error untouched.
+*/
+async function withD1Retry(fn, options) {
+	const retryOn = options?.retryOn ?? D1_TRANSIENT_ERRORS;
+	const maxRetries = options?.maxRetries ?? 3;
+	const initialDelayMs = options?.initialDelayMs ?? 200;
+	const backoffMultiplier = options?.backoffMultiplier ?? 2;
+	let lastError;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+		return await fn();
+	} catch (error) {
+		lastError = error;
+		if (attempt > 0 && isUniqueConstraint(error)) return void 0;
+		const fault = matchTransient(error, retryOn);
+		if (!fault) throw error;
+		if (attempt >= maxRetries) break;
+		const delayMs = initialDelayMs * backoffMultiplier ** attempt;
+		options?.onRetry?.({
+			error: fault,
+			attempt,
+			maxRetries,
+			delayMs
+		});
+		await new Promise((resolve) => setTimeout(resolve, delayMs));
+	}
+	throw lastError;
+}
+//#endregion
+export { D1RetryableError, D1_TRANSIENT_ERRORS, d1TransientFault, withD1Retry };

package/dist/entitlement/entitlement.d.ts

@@ -0,0 +1,118 @@
+import { z } from "zod";
+export declare const EntitlementKey: z.ZodString;
+export type EntitlementKey = z.output<typeof EntitlementKey>;
+/**
+ * One entitlement the caller holds, as the seam exposes it. This is the resolved read model, not a table:
+ * `@pithy-sh/payments` materializes a row per `(holder, entitlement)` and decodes it into this shape.
+ *
+ * **Who the holder is stays out of this shape, deliberately.** A payments project bills either a person or
+ * an organization, and its rows are keyed on that pair — but the seam resolves for *one* caller acting for
+ * *one* holder, so the pair is constant across a single `list()` and every element of the result would
+ * repeat it. Carrying it here would put a comparison within reach of {@link requireEntitlement} that the
+ * gate has no correct way to make (see {@link EntitlementResolver}), and would hand every non-payments
+ * provider two fields it cannot fill.
+ *
+ * `active` and `expiresAt` are both present, and both matter. The flag is an optimization written by
+ * the projection; the timestamp is the truth. {@link entitlementGrantsAccess} applies both, so a
+ * subscription that lapsed with no notification arriving stops granting access on the read path
+ * without waiting for a write.
+ */
+export declare const Entitlement: z.ZodObject<{
+    key: z.ZodString;
+    active: z.ZodBoolean;
+    expiresAt: z.ZodNullable<z.ZodDate>;
+    source: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type Entitlement = z.infer<typeof Entitlement>;
+/**
+ * The read-time rule, in one place: an entitlement grants access when the projection marked it active
+ * **and** it has not expired. Applied by {@link requireEntitlement} rather than left to each provider,
+ * so the recheck is a property of the seam instead of something a provider must remember.
+ *
+ * A read never writes. Repairing a stale row is the reconciliation Workflow's job, which keeps the hot
+ * path a pure read.
+ */
+export declare function entitlementGrantsAccess(entitlement: Entitlement, now: Date): boolean;
+/** Every key in `entitlements` that grants access at `now`, deduped. The set a gate is checked against. */
+export declare function grantedEntitlementKeys(entitlements: readonly Entitlement[], now: Date): Set<string>;
+/**
+ * The resolver seam on the request context (`c.var.entitlements`). One method: every entitlement the
+ * **current caller** holds. The resolver is built per request by the provider's middleware, so it
+ * already knows who is asking — a gate never passes a holder, and so can never gate on the wrong one.
+ *
+ * **That property is why the seam still takes no argument, now that a provider's holder can be an
+ * organization rather than a person.** `@pithy-sh/payments` decides which subject the caller is acting
+ * for *before* it constructs the resolver: the resolution happens once, in its middleware, against the
+ * adopter's own membership model, and the resolver closes over the answer. So a gate cannot pass the
+ * wrong holder because it passes none, and the alternative — a `list(holder)` — would put that choice at
+ * every call site, where a route reaching for `c.var.auth.userId` under organization billing looks
+ * exactly like correct code and quietly checks a company's plan against one employee.
+ *
+ * `provider` names the capability answering, or is `null` when none is composed. It exists so a denial
+ * can say *which* of the two reasons it was — genuinely unentitled, or nothing wired — in `detail`,
+ * where an operator sees it and a client never does.
+ */
+export interface EntitlementResolver {
+    /** The capability resolving entitlements (`payments`), or null when none is composed. */
+    readonly provider: string | null;
+    /** Every entitlement the current caller holds, granting or not. The gate applies the read-time rule. */
+    list(): Promise<readonly Entitlement[]>;
+    /**
+     * Who {@link list} answered for, **for the log and the audit trail only**. Optional: a resolver that
+     * cannot say omits it, and every gate behaves exactly as it did before this existed.
+     *
+     * See {@link EntitlementHolder} for why this is a label and a tenant rather than the holder itself.
+     */
+    holder?(): Promise<EntitlementHolder | undefined>;
+}
+/**
+ * How a resolver's holder appears in a denial's `detail` and on the denial's audit row — and **nothing a
+ * gate may compare**.
+ *
+ * A provider's holder stopped being a person when `@pithy-sh/payments` learned to bill organizations, and
+ * that left a denial unable to say which of two things had happened: a company that has bought nothing,
+ * and a caller acting for **no** company at all — the ordinary state of somebody signed in with no
+ * organization selected. Both produced `payments resolved []`. They are different problems: one is a sale,
+ * the other is a subject resolver returning nothing. The same gap left the denial's audit row with no
+ * `tenant`, so a trail could not answer "which of our customers is hitting the paywall" — `actorId` cannot,
+ * because one person acts in two tenants.
+ *
+ * **So why not put the holder on the seam?** Because {@link EntitlementResolver} deliberately takes no
+ * holder and returns none: the provider decides who the caller acts for *once*, in its own middleware,
+ * before it builds the resolver, and a gate that never receives a holder can never check the wrong one.
+ * A field carrying the holder itself would put that choice back within reach — a route comparing a resolved
+ * subject against `c.var.auth.userId` looks like careful code and quietly checks a company's plan against
+ * one employee.
+ *
+ * The shape is what keeps that from happening. Neither field is the holder:
+ *
+ * - **`label`** is display text for one log line. It is not parsed, not matched, and has no format this
+ *   package defines — a provider renders it however reads best (`@pithy-sh/payments` uses `user:ada` and
+ *   `organization:acme`, its own encoding).
+ * - **`tenant`** is the audit dimension and nothing else, opaque exactly as `AuditEvent.tenant` is. `null`
+ *   means *the holder is not a tenant* — which is the honest answer under per-person billing, where the
+ *   holder is the actor and a tenant echoing `actorId` would be a dimension the app does not have.
+ *
+ * There is nothing here to compare a caller against, because there is no caller-shaped value: `label` is
+ * prose and `tenant` is a dimension. `require.test.ts` pins the property directly — the gate's decision is
+ * identical for every holder, including none.
+ */
+export interface EntitlementHolder {
+    /** Display text naming the holder, for a denial's `detail`. Never parsed, never matched. */
+    readonly label: string;
+    /** The tenant this was resolved for, or null when the holder is not a tenant. `AuditEvent.tenant`. */
+    readonly tenant: string | null;
+}
+/**
+ * The default resolver when no provider is composed: hold nothing. Every gate denies, which is the
+ * fail-closed default the seam exists to guarantee. `createBackend` seeds it on every request, and a
+ * provider's middleware replaces it.
+ */
+export declare const noEntitlementProvider: EntitlementResolver;
+/**
+ * The audit action a denied entitlement gate records, through the core `emit()` seam. Part of the
+ * federated `domain/reason` taxonomy — core owns this one because core owns the gate. A blocked
+ * attempt is a first-class audit record (`outcome: "denied"`), not only a 403.
+ */
+export declare const ENTITLEMENT_DENIED_ACTION = "entitlement/denied";
+//# sourceMappingURL=entitlement.d.ts.map

package/dist/entitlement/entitlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlement.d.ts","sourceRoot":"","sources":["../../src/entitlement/entitlement.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2BxB,eAAO,MAAM,cAAc,aAUxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW;;;;;iBAqBuF,CAAC;AAChH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGpF;AAED,2GAA2G;AAC3G,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAMnG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,wGAAwG;IACxG,IAAI,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IACxC;;;;;OAKG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,iBAAiB;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sGAAsG;IACtG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAGnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,uBAAuB,CAAC"}