@pithy-sh/core 0.1.0

package/src/data/withD1Retry.ts

@@ -0,0 +1,176 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * 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 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",
+} as const;
+export type D1RetryableError = (typeof D1RetryableError)[keyof typeof D1RetryableError];
+
+/** Every transient (retry-initiating) fault class — the default `retryOn`. Excludes the guard-only `unique-constraint`. */
+export const D1_TRANSIENT_ERRORS: readonly D1RetryableError[] = [
+  D1RetryableError.TIMEOUT,
+  D1RetryableError.DATABASE_BUSY,
+  D1RetryableError.NETWORK,
+  D1RetryableError.STORAGE_RESET,
+  D1RetryableError.INTERNAL,
+];
+
+/** 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;
+}
+
+/**
+ * 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: Record<D1RetryableError, readonly string[]> = {
+  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: string, fault: D1RetryableError): boolean {
+  return errorMatchers[fault].some((signature) => message.includes(signature));
+}
+
+/** Whether an error is a UNIQUE-constraint failure — the idempotency-guard signal. */
+function isUniqueConstraint(error: unknown): boolean {
+  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: unknown, retryOn: readonly D1RetryableError[]): D1RetryableError | null {
+  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.
+ */
+export function d1TransientFault(error: unknown): D1RetryableError | null {
+  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.
+ */
+export async function withD1Retry<T>(fn: () => Promise<T>, options?: D1RetryOptions): Promise<T> {
+  const retryOn = options?.retryOn ?? D1_TRANSIENT_ERRORS;
+  const maxRetries = options?.maxRetries ?? 3;
+  const initialDelayMs = options?.initialDelayMs ?? 200;
+  const backoffMultiplier = options?.backoffMultiplier ?? 2;
+
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      // Idempotency guard: a unique-constraint hit on a retry means a prior attempt's write already
+      // landed — the conflict is with our own earlier success, so treat it as done. On the first
+      // attempt it is a genuine conflict and falls through to propagate.
+      if (attempt > 0 && isUniqueConstraint(error)) return undefined as T;
+
+      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;
+}

package/src/entitlement/entitlement.ts

@@ -0,0 +1,191 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The entitlement seam. `@pithy-sh/core` owns the contract — what an entitlement *is*, how a request
+ * resolves the caller's, and the read-time rule that decides whether one grants access. It owns no
+ * payments logic: `@pithy-sh/payments` is the provider that fills the seam, and any capability that
+ * gates on a paid feature depends on this file rather than on that package (principle 4).
+ *
+ * **The uncomposed default denies.** This is the one deliberate difference from the audit seam next
+ * door. Audit's `emit()` no-ops when no audit capability is composed, and that is safe — a missing
+ * audit write cannot grant anyone access. An entitlement check is a gate, so a missing provider must
+ * fail closed: {@link noEntitlementProvider} resolves to nothing, and every `requireEntitlement()`
+ * denies. Runtime denial is the backstop rather than the primary defense — a Worker whose routes gate
+ * on entitlements while composing no provider is a composition error `pithy doctor` reports, not
+ * something an adopter is meant to discover as production 403s.
+ */
+
+/**
+ * A logical entitlement key — `pro`, `ads_removed`. Lowercase, digits, and underscores, because the
+ * key is a stable identifier gating code names, not display copy.
+ *
+ * The pattern is the load-bearing distinction of the whole capability: **a product is not an
+ * entitlement.** `pro_monthly` and `pro_annual` are two products, in three rails' catalogs, granting
+ * one entitlement — `pro`. Gating code never names a SKU.
+ */
+const ENTITLEMENT_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+
+export const EntitlementKey = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(
+    ENTITLEMENT_KEY_PATTERN,
+    "An entitlement key is lowercase letters, digits, and underscores, starting with a letter.",
+  )
+  .describe(
+    "A logical entitlement key (`pro`, `ads_removed`) — what gating code names. Never a store SKU: many products across many rails grant one key.",
+  );
+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 const Entitlement = z
+  .object({
+    key: EntitlementKey.describe("The entitlement key this grant is for."),
+    active: z
+      .boolean()
+      .describe(
+        "Whether the granting purchase was in an access-granting state when the projection last wrote this row. An optimization, not the truth — `expiresAt` is rechecked on every read.",
+      ),
+    expiresAt: z
+      .date()
+      .nullable()
+      .describe(
+        "When the grant lapses, or null for a grant that never does (a non-consumable purchase). Evaluated at read time, so a silent lapse revokes access without a write.",
+      ),
+    source: z
+      .string()
+      .nullable()
+      .describe(
+        "Provenance — an opaque reference to whatever currently grants this entitlement (a purchase id, or a support grant). Opaque to core; the provider decides what it means.",
+      ),
+  })
+  .describe("One entitlement the current caller holds, as the core seam exposes it — the resolved read model.");
+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 function entitlementGrantsAccess(entitlement: Entitlement, now: Date): boolean {
+  if (!entitlement.active) return false;
+  return entitlement.expiresAt === null || now.getTime() < entitlement.expiresAt.getTime();
+}
+
+/** Every key in `entitlements` that grants access at `now`, deduped. The set a gate is checked against. */
+export function grantedEntitlementKeys(entitlements: readonly Entitlement[], now: Date): Set<string> {
+  const granted = new Set<string>();
+  for (const entitlement of entitlements) {
+    if (entitlementGrantsAccess(entitlement, now)) granted.add(entitlement.key);
+  }
+  return granted;
+}
+
+/**
+ * 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 const noEntitlementProvider: EntitlementResolver = {
+  provider: null,
+  list: async () => [],
+};
+
+/**
+ * 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 const ENTITLEMENT_DENIED_ACTION = "entitlement/denied";

package/src/entitlement/gateScan.ts

@@ -0,0 +1,107 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Finding an entitlement gate in source text — the pure half of the composition check.
+ *
+ * `pithy doctor` scans a Worker's own source for calls to the gates in `./require`, because the runtime
+ * cannot tell the two failing cases apart: a legitimately unentitled user and a Worker that forgot to
+ * compose a provider both produce a 403. Walking a directory needs the filesystem. Deciding whether one
+ * string of source gates does not, and the halves are split here so the second can be used on its own.
+ *
+ * On its own, because an adopter has the same question about their own source with the answer inverted:
+ * not *where a gate must exist* but *where one may not*. No control-plane route in the Pithy dashboard may
+ * gate on a subscription — a customer's data must not become unreachable over a billing problem of ours —
+ * and a gate that is never reached at runtime is precisely the one a runtime test misses. That assertion
+ * is a few lines over `import.meta.glob(…, "?raw")`, provided it can import these rules rather than restate
+ * them. A restated copy drifts, and drifts quietly: both copies keep passing while they disagree.
+ *
+ * It lives beside the gates it names rather than in the CLI. A rename in `./require` is then one file's
+ * work, core is the package every adopter already depends on, and core's no-`node:` rule is asserted over
+ * every module here (`../worker-safety.test.ts`) — which is what makes this importable from a program
+ * typed for the Workers runtime at all. The CLI composes it; see `entitlementGap.ts` there.
+ *
+ * The scan is textual, deliberately. Loading a Worker's routes to inspect them would execute the code
+ * under audit, and the question is not subtle enough to need a parser: a call to one of two named helpers.
+ */
+
+/**
+ * A call to either gate. `\b` before the name keeps `myRequireEntitlement(` out, and requiring the open
+ * paren keeps a bare import or a re-export out — importing a gate is not applying one, and reporting an
+ * unused import would make the check noise rather than signal.
+ */
+const GATE_CALL = /\brequire(?:Any)?Entitlement\s*\(/;
+
+/**
+ * The source with its comments blanked, so a `// TODO: requireEntitlement("pro")` is not read as a gate.
+ *
+ * **String-aware, and it has to be.** Doing this with two regexes over raw source looks equivalent and is
+ * not: a `/*` inside a string literal opens a comment the scanner never sees closed, and everything up to
+ * the next `*/` in the file vanishes. A Worker with `app.get("/assets/*", …)` followed by any doc comment
+ * loses whatever sat between them — so a real gate goes unseen and the check reports clean. The same trap
+ * in reverse is `https://`, whose `//` is not a comment.
+ *
+ * So this walks the source once, tracking which of code / string / template / line comment / block comment
+ * it is in, and replaces comment characters with spaces rather than removing them — offsets stay put, which
+ * keeps anything reported against this text meaningful. A real parser would be the third option and is far
+ * more than a two-identifier search needs.
+ */
+export function withoutComments(source: string): string {
+  const out: string[] = [];
+  let index = 0;
+  while (index < source.length) {
+    const char = source[index] as string;
+    const next = source[index + 1];
+
+    if (char === "/" && next === "*") {
+      const close = source.indexOf("*/", index + 2);
+      const end = close === -1 ? source.length : close + 2;
+      // Newlines are kept so line structure survives; everything else becomes a space.
+      out.push(source.slice(index, end).replace(/[^\n]/g, " "));
+      index = end;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      const newline = source.indexOf("\n", index);
+      const end = newline === -1 ? source.length : newline;
+      out.push(" ".repeat(end - index));
+      index = end;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      // Consume the whole literal, escapes included, so nothing inside it is read as code or as a comment.
+      let scan = index + 1;
+      while (scan < source.length && source[scan] !== char) {
+        // A newline ends an unterminated quoted string; a template literal may legally span lines.
+        if (source[scan] === "\n" && char !== "`") break;
+        scan += source[scan] === "\\" ? 2 : 1;
+      }
+      const end = Math.min(scan + 1, source.length);
+      out.push(source.slice(index, end));
+      index = end;
+      continue;
+    }
+    out.push(char);
+    index += 1;
+  }
+  return out.join("");
+}
+
+/** Whether this source applies an entitlement gate, comments and string literals discounted. */
+export function callsGate(source: string): boolean {
+  return GATE_CALL.test(withoutComments(source));
+}
+
+/**
+ * The files, of those given, that apply an entitlement gate — sorted, so a finding reads as a set.
+ *
+ * Takes the sources rather than a directory, which is what keeps this half free of `node:fs`. The CLI
+ * hands it a walked `src/`; a test in a Workers-typed program hands it `import.meta.glob(…, "?raw")`,
+ * which is the only way that program can read files at all.
+ */
+export function gateCallSites(sources: Readonly<Record<string, string>>): string[] {
+  return Object.entries(sources)
+    .filter(([, source]) => callsGate(source))
+    .map(([file]) => file)
+    .sort((a, b) => a.localeCompare(b));
+}