@pithy-sh/payments 0.1.0

package/src/data/syncCursor.ts

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { PaymentsRail } from "./rail";
+
+/**
+ * Where a resumable sweep of a provider's stream left off — the row in `pithy_payments_sync_cursors`,
+ * keyed `UNIQUE (rail, name)`.
+ *
+ * **This is not a copy of a provider's data**, and the distinction matters enough to state: the row holds
+ * one opaque resume token and two timestamps. No amount, no customer, no event body. The alternative to
+ * storing it is re-reading ninety days of somebody else's event stream on every run, which is worse for
+ * them as well as for us.
+ *
+ * One rail may sweep more than one stream, so the key is `(rail, name)` rather than the rail alone. Paddle
+ * has exactly one today — {@link PADDLE_EVENTS_CURSOR} — and the second column is what stops a second one
+ * needing a migration.
+ */
+export const PaymentsSyncCursor = z
+  .object({
+    id: z.string().describe("The row's UUID."),
+    rail: PaymentsRail.describe("Which store's stream this cursor points into."),
+    name: z
+      .string()
+      .describe("Which of that store's streams. One rail may have several, so the name is part of the key."),
+    cursor: z
+      .string()
+      .nullable()
+      .describe(
+        "The provider's own resume token — Paddle's `evt_…` — or null for a stream never swept. Null is a real state and means 'start at the oldest event the provider still retains', not 'unknown'.",
+      ),
+    updatedAt: SQLiteDate.describe(
+      "When the cursor last advanced. Read against the provider's retention window: a cursor older than it can never be caught up, and the sweep reports that gap rather than restarting from the beginning.",
+    ),
+    createdAt: SQLiteDate.describe("When this row was written."),
+  })
+  .describe("Where a resumable sweep of a provider's event stream left off. One opaque token, and nothing else.");
+export type PaymentsSyncCursor = z.output<typeof PaymentsSyncCursor>;
+export type PaymentsSyncCursorRow = z.input<typeof PaymentsSyncCursor>;
+
+/** The name of Paddle's events-stream cursor. One per rail per stream; this rail has one. */
+export const PADDLE_EVENTS_CURSOR = "events";

package/src/data/tables.ts

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { PaymentsEntitlement } from "./entitlement";
+import { PaymentsProviderAccount } from "./providerAccount";
+import { PaymentsPurchase } from "./purchase";
+import { PaymentsReconcileRun } from "./reconcileRun";
+import { PaymentsSyncCursor } from "./syncCursor";
+import { PaymentsWebhookEvent } from "./webhookEvent";
+
+/** The projection of provider truth. `CamelCasePlugin` snake-cases it to `pithy_payments_purchases`. */
+export const PAYMENTS_PURCHASES_TABLE = "pithyPaymentsPurchases";
+/** The materialized read model `requireEntitlement()` hits. → `pithy_payments_entitlements`. */
+export const PAYMENTS_ENTITLEMENTS_TABLE = "pithyPaymentsEntitlements";
+/** Provider identity → the subject that holds it. → `pithy_payments_provider_accounts`. */
+export const PAYMENTS_PROVIDER_ACCOUNTS_TABLE = "pithyPaymentsProviderAccounts";
+/** Raw received notifications, the replay source. → `pithy_payments_webhook_events`. */
+export const PAYMENTS_WEBHOOK_EVENTS_TABLE = "pithyPaymentsWebhookEvents";
+/** One row per reconciliation pass — the tally, kept. → `pithy_payments_reconcile_runs`. */
+export const PAYMENTS_RECONCILE_RUNS_TABLE = "pithyPaymentsReconcileRuns";
+/** Where a resumable sweep of a provider's stream left off. → `pithy_payments_sync_cursors`. */
+export const PAYMENTS_SYNC_CURSORS_TABLE = "pithyPaymentsSyncCursors";
+
+/** The payments tables map. All six are always present — none is behind a config flag. */
+export function paymentsTables(): Record<string, z.ZodObject> {
+  return {
+    [PAYMENTS_PURCHASES_TABLE]: PaymentsPurchase,
+    [PAYMENTS_ENTITLEMENTS_TABLE]: PaymentsEntitlement,
+    [PAYMENTS_PROVIDER_ACCOUNTS_TABLE]: PaymentsProviderAccount,
+    [PAYMENTS_WEBHOOK_EVENTS_TABLE]: PaymentsWebhookEvent,
+    [PAYMENTS_RECONCILE_RUNS_TABLE]: PaymentsReconcileRun,
+    [PAYMENTS_SYNC_CURSORS_TABLE]: PaymentsSyncCursor,
+  };
+}
+
+/** The typed Kysely database over the payments tables. */
+export type PaymentsTables = {
+  [PAYMENTS_PURCHASES_TABLE]: typeof PaymentsPurchase;
+  [PAYMENTS_ENTITLEMENTS_TABLE]: typeof PaymentsEntitlement;
+  [PAYMENTS_PROVIDER_ACCOUNTS_TABLE]: typeof PaymentsProviderAccount;
+  [PAYMENTS_WEBHOOK_EVENTS_TABLE]: typeof PaymentsWebhookEvent;
+  [PAYMENTS_RECONCILE_RUNS_TABLE]: typeof PaymentsReconcileRun;
+  [PAYMENTS_SYNC_CURSORS_TABLE]: typeof PaymentsSyncCursor;
+};
+export type PaymentsDatabase = Kysely<DatabaseSchema<PaymentsTables>>;
+
+/** Build the payments database from the `DB` binding (CamelCasePlugin installed). */
+export function paymentsDatabase(d1: D1Database): PaymentsDatabase {
+  return createDatabase(d1, {
+    [PAYMENTS_PURCHASES_TABLE]: PaymentsPurchase,
+    [PAYMENTS_ENTITLEMENTS_TABLE]: PaymentsEntitlement,
+    [PAYMENTS_PROVIDER_ACCOUNTS_TABLE]: PaymentsProviderAccount,
+    [PAYMENTS_WEBHOOK_EVENTS_TABLE]: PaymentsWebhookEvent,
+    [PAYMENTS_RECONCILE_RUNS_TABLE]: PaymentsReconcileRun,
+    [PAYMENTS_SYNC_CURSORS_TABLE]: PaymentsSyncCursor,
+  }) as unknown as PaymentsDatabase;
+}

package/src/data/webhookEvent.ts

@@ -0,0 +1,196 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { PaymentsRail } from "./rail";
+
+/** A received notification body, as the rail delivered it. Only the envelope is fixed; shapes differ. */
+const NotificationPayload = z
+  .record(z.string(), z.unknown())
+  .describe("The notification body as received, before any rail-specific interpretation.");
+
+/**
+ * One received provider notification — the row in `pithy_payments_webhook_events`, keyed
+ * `UNIQUE (rail, providerEventId)`.
+ *
+ * Every provider delivers at-least-once and retries, so a redelivery is expected and must be recognized
+ * rather than reprocessed. This is the replay source, and it is what makes "why didn't this renew"
+ * answerable: `receivedAt` says whether the notification arrived at all, `processedAt` whether it was
+ * finished with, `abandonedAt` whether a repair pass gave up on it, and `error` why.
+ *
+ * ## Why two timestamps and no status column (#337)
+ *
+ * `processedAt` used to be the whole answer, and three writers meant three different things by it —
+ * projected, tried and failed, and given up on. Because the webhook guard short-circuits on it, two of
+ * those three silently stopped a purchase from ever being projected.
+ *
+ * **The defect was not too few states. It was every reader spelling out its own predicate over a column
+ * whose meaning the writers disagreed about.** A stored `status` enum makes the writers exhaustive and
+ * leaves the readers exactly as free to write `status <> 'pending'` — which is the short-circuit that was
+ * wrong. So the fix has to be a named question each reader asks by name, and once there is one, the
+ * storage shape is the smaller decision.
+ *
+ * Given that, two nullable timestamps beat an enum twice over. They answer *when*, which is what this
+ * table is read for, and they cannot contradict themselves the way `status = 'projected'` beside a null
+ * `processedAt` can. An enum would add an invariant nothing enforces; a timestamp is its own evidence.
+ *
+ * So the state is **derived, never stored** — see {@link webhookEventState} — and the two readers that
+ * matter ask different questions of it: {@link isWebhookEventFinished} for the guard's short-circuit, and
+ * {@link isWebhookEventOutstanding} for a repair pass. Both switch over every state, so a fifth one cannot
+ * be added without each reader saying what it means by it.
+ *
+ * A third reader asks a question the state cannot answer — see {@link webhookEventAwaitsOwner}. It exists
+ * because a link repairs one kind of unfinished row and not the others, and *which* kind is in `error`.
+ */
+export const PaymentsWebhookEvent = z
+  .object({
+    id: z.string().describe("The row's UUID."),
+    rail: PaymentsRail.describe("Which store delivered the notification."),
+    providerEventId: z
+      .string()
+      .describe(
+        "The rail's own event id. `UNIQUE (rail, providerEventId)` — a redelivery is recognized, not reprocessed.",
+      ),
+    payload: sqliteJson(NotificationPayload).describe(
+      "The notification body, Zod-validated on write and on read. The replay source, so it is stored whole.",
+    ),
+    receivedAt: SQLiteDate.describe("When the notification arrived. Present even for one that never processed."),
+    processedAt: SQLiteDate.nullable().describe(
+      "When this delivery was finished with — projected, or deliberately nothing to project — or null while it has not been. The only column the webhook guard short-circuits on, so it means 'we have finished this' and never 'we have seen this'. Null with an old `receivedAt` is the drift signal.",
+    ),
+    abandonedAt: SQLiteDate.nullable()
+      .optional()
+      .describe(
+        "When a repair pass gave up on this event so its stream could advance, or null. Separate from `processedAt` because abandoning is that pass's decision about its own progress and must never answer for a webhook: a later delivery of the same event has to be reprocessed, and fixing the cause has to be able to repair it. Optional because the webhook path never abandons anything and the column defaults to null for it.",
+      ),
+    error: z
+      .string()
+      .nullable()
+      .describe(
+        "Why this delivery did not project — or, beside a set `processedAt`, why there was never anything to project. Internal text: it is read by an operator and never rendered to a client. Its presence is not the state; the two timestamps are, because an explanation must not be able to change one.",
+      ),
+    attempts: z
+      .number()
+      .int()
+      .nonnegative()
+      .optional()
+      .describe(
+        "How many times a repair pass has tried this event and failed. Optional because the webhook path neither retries nor counts, and the column defaults to 0 for it; the sweep uses it to bound how long one unprojectable event may hold the stream up before it is quarantined.",
+      ),
+    createdAt: SQLiteDate.describe("When this row was written."),
+  })
+  .describe("One received provider notification — the row in `pithy_payments_webhook_events`, the replay source.");
+export type PaymentsWebhookEvent = z.output<typeof PaymentsWebhookEvent>;
+export type PaymentsWebhookEventRow = z.input<typeof PaymentsWebhookEvent>;
+
+/**
+ * What has become of a recorded delivery. Four cases, and each one behaves differently.
+ *
+ * - `pending` — it arrived and nothing has tried it yet.
+ * - `failed` — it was tried, it did not project, and it is still outstanding.
+ * - `abandoned` — a repair pass gave up so its stream could advance. Outstanding, but not to that pass.
+ * - `finished` — projected, or deliberately nothing to project. Nothing is left to do.
+ */
+export type PaymentsWebhookEventState = "pending" | "failed" | "abandoned" | "finished";
+
+/**
+ * The two timestamps and the reason, as a reader gets them off a narrow `select`.
+ *
+ * Deliberately the **encoded** shape rather than {@link PaymentsWebhookEvent}: both readers want two or
+ * three columns, and making them decode a whole row — payload included — to answer "may this be
+ * short-circuited" would be a JSON parse per redelivery. `undefined` is accepted beside `null` for the
+ * same reason a defaulted column can read back absent.
+ */
+export interface PaymentsWebhookEventProgress {
+  /** `processed_at`, as `SQLiteDate` accepts it, or absent. Only its presence is read here. */
+  readonly processedAt?: z.input<typeof SQLiteDate> | null;
+  /** `abandoned_at`, likewise. */
+  readonly abandonedAt?: z.input<typeof SQLiteDate> | null;
+  /** `error`, or absent. */
+  readonly error?: string | null;
+}
+
+/**
+ * Classify one recorded delivery. **Derived here, once, rather than stored** — see the module doc.
+ *
+ * Finished wins over abandoned, and that ordering is the point rather than an accident: an event the sweep
+ * gave up on and a later delivery then projected is *finished*, and `abandonedAt` stays on the row as the
+ * record of how close that purchase came to being lost.
+ */
+export function webhookEventState(row: PaymentsWebhookEventProgress): PaymentsWebhookEventState {
+  if (row.processedAt !== null && row.processedAt !== undefined) return "finished";
+  if (row.abandonedAt !== null && row.abandonedAt !== undefined) return "abandoned";
+  if (row.error !== null && row.error !== undefined) return "failed";
+  return "pending";
+}
+
+/**
+ * May a redelivery be answered as a duplicate without running anything?
+ *
+ * **Only for a delivery that is finished with.** This is the webhook guard's short-circuit, and it is the
+ * whole of #337: while it meant "we have seen this", a delivery that arrived and failed was answered 200
+ * for ever, and no path in this package repaired it.
+ */
+export function isWebhookEventFinished(state: PaymentsWebhookEventState): boolean {
+  switch (state) {
+    case "finished":
+      return true;
+    case "pending":
+    case "failed":
+    case "abandoned":
+      return false;
+  }
+}
+
+/**
+ * The prefix an event's `error` carries when the one thing missing was **an owner**.
+ *
+ * `error` is free text an operator reads, and two writers put two different sentences in it for the same
+ * condition — the webhook handler's "no subject could be resolved", and the sweep's own `orphaned:`. That
+ * was fine while nothing queried it. It stopped being fine with #341: linking an account has to find exactly
+ * the rows that were waiting on that link, and "waiting on a link" is not derivable from the two timestamps —
+ * a quarantine after three failures wears the same pair.
+ *
+ * So the reason is written on the row, once, by a constant both writers share. A prefix rather than a column
+ * because it costs no migration and stays legible to the operator reading `error`, and it is a prefix rather
+ * than a substring so the match is anchored and a note quoting the word cannot be mistaken for one.
+ *
+ * See {@link webhookEventAwaitsOwner} for the reader, and `projection/orphans.ts` for what it is read by.
+ */
+export const WEBHOOK_EVENT_ORPHANED = "orphaned:";
+
+/**
+ * Is this event outstanding for want of an owner, rather than for want of anything else?
+ *
+ * The question the relink repair asks, and it is deliberately narrower than "not finished". A quarantined
+ * event, a failed projection, an unmapped SKU — none of those is repaired by an account linking, and running
+ * them again on that signal would be a second unbounded retry loop wearing the first one's clothes.
+ *
+ * `abandoned` and `failed` both qualify, because both paths produce an orphan and they produce different
+ * states: the sweep abandons one so its stream can advance, and the webhook handler leaves one failed so a
+ * redelivery repairs it. Neither is finished, and both are waiting on the same thing.
+ */
+export function webhookEventAwaitsOwner(row: PaymentsWebhookEventProgress): boolean {
+  if (webhookEventState(row) === "finished") return false;
+  return (row.error ?? "").startsWith(WEBHOOK_EVENT_ORPHANED);
+}
+
+/**
+ * Has a repair pass anything left to do with this event?
+ *
+ * `abandoned` is false here, and false is right: the bound exists so one unprojectable event cannot hold a
+ * stream up for ever, and a pass that picked its own quarantines back up would restart the count and stall
+ * again. That is the asymmetry the two readers exist for — the pass must move on, and a webhook delivery
+ * must still be able to repair what it walked past.
+ */
+export function isWebhookEventOutstanding(state: PaymentsWebhookEventState): boolean {
+  switch (state) {
+    case "pending":
+    case "failed":
+      return true;
+    case "abandoned":
+    case "finished":
+      return false;
+  }
+}

package/src/entitlement/manual.ts

@@ -0,0 +1,209 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { withD1Retry } from "@pithy-sh/core/src/data/withD1Retry";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { grantableEntitlements, type PaymentsConfig } from "../config/config";
+import { PaymentsEntitlement } from "../data/entitlement";
+import { encodeSubjectReference, type PaymentsSubject } from "../data/subject";
+import { PAYMENTS_ENTITLEMENTS_TABLE, paymentsDatabase } from "../data/tables";
+import { PaymentsEntitlementNotInCatalogError } from "../error/errors";
+
+/**
+ * Manual entitlement writes — the support surface behind `POST /payments/entitlements/grant` and `/revoke`.
+ *
+ * These are the only writes to the read model that no purchase produced, which is exactly why the routes over
+ * them are `control-plane`, default-denied, and audited on both paths. Everything else in this package can be
+ * traced back to a store's own artifact; this cannot, so the trail is the only record of who decided it.
+ *
+ * ## The hold, and why `grant` and `revoke` are not symmetric
+ *
+ * Every other row in this table is derived: the projection recomputes it from the purchases table on every
+ * write that touches its key, which is what keeps the read model from silently disagreeing with the money.
+ * A comp has no purchase behind it, so a derivation would find nothing supporting it and clear it — and a
+ * support comp erased by the user's next renewal is worse than no comp at all, because nobody would notice.
+ *
+ * So a grant sets `manual`, and the projection skips a row carrying it. Both shapes work and both last:
+ * comping a key the catalog does not sell (`founder`) and comping one it does (`pro`).
+ *
+ * ## The catalog check is here, at the write
+ *
+ * {@link grantEntitlement} refuses a key this project does not define, with
+ * `payments/entitlement_not_in_catalog`, a 400 naming the key (#300). An operator who meant `pro` and
+ * typed `pr` used to get a 200, a row, and a customer who stayed locked out, invisible on both sides.
+ *
+ * That check first landed in `POST /payments/entitlements/grant`, and lived there alone (#305). A rule at a
+ * call site has a second call site eventually: an adopter's own handler, a later route in this package, the
+ * reconciliation workflow — each one a path to the row write with the rule removed. So the check moved to
+ * the thing being called. The route no longer decides; it reports.
+ *
+ * The shape that makes that unbypassable is a **split**: `writeEntitlement` below asks nothing and is not
+ * exported, and the exported grant takes a {@link PaymentsConfig} it cannot be called without. A caller
+ * cannot reach the unchecked half from outside this module, and the type says why.
+ *
+ * Comping a key nothing sells is therefore **declared** rather than achieved by nobody checking:
+ * `manualEntitlements` in `pithy.config.ts` is where an adopter names the keys they comp but do not sell,
+ * and those keys are grantable and are published on the catalog read beside the products. The check reads
+ * `grantableEntitlements`, so that escape travels with it. Only grants are constrained. A revoke is not, or
+ * dropping a product from the catalog would be irreversible for every account still holding its key — which
+ * is why {@link revokeEntitlement} takes no config, and must never grow one.
+ *
+ * A **revoke clears the hold** rather than setting it, which is the deliberate asymmetry. It means a revoke
+ * is the exact inverse of a grant — it takes the row back out of a human's hands — and it means a revoke
+ * never becomes a permanent block on a user who later pays. That matters: an entitlement the purchases still
+ * support is re-derived on the next event, so revoking a *paid* subscription here holds only until the store
+ * next says something about it. To end a paid entitlement, refund it through the store; that is the record
+ * the projection reads, and the only one that keeps the read model and the money agreeing.
+ *
+ * A revoke writes an inactive row even when the subject held nothing, because support tooling should not have
+ * to know whether a row exists, and because the row is itself the record that somebody decided this account is
+ * not entitled.
+ *
+ * ## The holder is a subject, and both halves are named
+ *
+ * A comp is a contract somebody signed, and under organization billing the party to it is the company rather
+ * than whoever at the company asked. So these take a {@link PaymentsSubject} — the pair, never an id on its
+ * own. The pair is the upsert's conflict target, the read-back's predicate and the row's identity, and it is
+ * the same pair the read path filters on, so a grant and the gate that honors it cannot disagree about who
+ * was meant. `user:acme` and `organization:acme` are two holders: nothing in the kit makes those id spaces
+ * disjoint, and support revoking the right id under the wrong kind must take nothing away from the other.
+ */
+
+/**
+ * Who, and to what. The caller has already been through `requireControlPlane`.
+ *
+ * It **extends** {@link PaymentsSubject} rather than restating two strings, so a caller cannot supply half a
+ * holder and the type is the same one every other subject-bearing surface takes. Never the caller's own
+ * subject — this is support acting on somebody else's account.
+ */
+export interface ManualEntitlementInput extends PaymentsSubject {
+  /** The entitlement key, as gating code names it. */
+  entitlement: string;
+  /** When a grant lapses. Absent or null never lapses; ignored on a revoke. */
+  expiresAt?: Date | null;
+}
+
+/** The clock and the id minter, injected so a test is deterministic. */
+export interface ManualEntitlementOptions {
+  /** The write timestamp. Defaults to now. */
+  now?: Date;
+  /** The id minter for a row that does not exist yet. Defaults to `crypto.randomUUID`. */
+  newId?: () => string;
+}
+
+/**
+ * Grant an entitlement by hand, and hold it against the projection. Idempotent; overwrites whatever the
+ * projection last derived for this key, and survives every later purchase event for it.
+ *
+ * Refuses a key this project does not define — no product grants it and `manualEntitlements` does not
+ * declare it — before any row is written. The config is a parameter rather than a closure because a grant
+ * without one is the defect: see the module doc.
+ */
+export async function grantEntitlement(
+  d1: D1Database,
+  config: PaymentsConfig,
+  input: ManualEntitlementInput,
+  options: ManualEntitlementOptions = {},
+): Promise<PaymentsEntitlement> {
+  const grantable = grantableEntitlements(config);
+  if (!grantable.has(input.entitlement)) {
+    throw new PaymentsEntitlementNotInCatalogError({
+      message: `No entitlement "${input.entitlement}" is defined here.`,
+      // The set goes in `detail`, which the HTTP codec strips. An operator reading the customer's logs gets
+      // the near miss spelled out; the caller learns only which key it sent, because what this project sells
+      // is a separate disclosure behind `payments:catalog:read`.
+      detail: `No product grants "${input.entitlement}" and \`manualEntitlements\` does not declare it. Defined: ${[...grantable].sort().join(", ") || "nothing"}.`,
+    });
+  }
+  return writeEntitlement(d1, input, true, options);
+}
+
+/**
+ * Revoke an entitlement by hand and release the hold. Idempotent, and records the decision even where there
+ * was nothing to clear. A key the purchases still support is re-derived on the next event — see the module doc.
+ *
+ * **Takes no config, deliberately.** A revoke of a key the catalog has since dropped must stay legal, or a
+ * catalog edit becomes irreversible for every account still holding it. The missing parameter is the rule.
+ */
+export function revokeEntitlement(
+  d1: D1Database,
+  input: ManualEntitlementInput,
+  options: ManualEntitlementOptions = {},
+): Promise<PaymentsEntitlement> {
+  return writeEntitlement(d1, input, false, options);
+}
+
+/**
+ * The upsert both directions share. One statement, on the `UNIQUE (subjectType, subjectId, entitlement)`
+ * conflict target, so a concurrent write cannot produce a second row for one key.
+ *
+ * The target is all three columns because that is the index the table really has. A two-column target names
+ * no unique constraint and SQLite refuses the statement outright — which is the loud failure worth having
+ * here, rather than an upsert that quietly inserts a second row per holder and leaves two answers to one
+ * gate. The read-back's predicate is the same three columns for the same reason.
+ *
+ * `sourcePurchaseId` is set to null on both paths, and that is the honest answer: no purchase supports this
+ * row. `manual` is the half that differs — set by a grant, cleared by a revoke — and it is what the
+ * projection's derivation reads to decide whether the row is its to touch.
+ */
+async function writeEntitlement(
+  d1: D1Database,
+  input: ManualEntitlementInput,
+  active: boolean,
+  options: ManualEntitlementOptions,
+): Promise<PaymentsEntitlement> {
+  const now = options.now ?? new Date();
+  const newId = options.newId ?? (() => crypto.randomUUID());
+  const db = paymentsDatabase(d1);
+  const row = PaymentsEntitlement.encode({
+    id: newId(),
+    // Both halves off the one input, together. Nothing here pairs a kind from config with an id from a row.
+    subjectType: input.subjectType,
+    subjectId: input.subjectId,
+    entitlement: input.entitlement,
+    active,
+    // An expiry only means anything on a grant. A revoke that carried one would describe a row that stops
+    // being revoked, which is not a thing.
+    expiresAt: active ? (input.expiresAt ?? null) : null,
+    sourcePurchaseId: null,
+    // A grant is held against the projection; a revoke hands the key back to it.
+    manual: active,
+    createdAt: now,
+    updatedAt: now,
+  });
+
+  await withD1Retry(() =>
+    db
+      .insertInto(PAYMENTS_ENTITLEMENTS_TABLE)
+      // biome-ignore lint/suspicious/noExplicitAny: the row is the schema's z.input side; Kysely's insert type derives from it.
+      .values(row as any)
+      .onConflict((oc) =>
+        oc.columns(["subjectType", "subjectId", "entitlement"]).doUpdateSet({
+          active: row.active,
+          expiresAt: row.expiresAt,
+          sourcePurchaseId: null,
+          manual: row.manual,
+          updatedAt: row.updatedAt,
+          // biome-ignore lint/suspicious/noExplicitAny: as above — an encoded row, not the app shape.
+        } as any),
+      )
+      .execute(),
+  );
+
+  const written = await db
+    .selectFrom(PAYMENTS_ENTITLEMENTS_TABLE)
+    .selectAll()
+    .where("subjectType", "=", input.subjectType)
+    .where("subjectId", "=", input.subjectId)
+    .where("entitlement", "=", input.entitlement)
+    .executeTakeFirst();
+  if (written === undefined) {
+    throw new InternalError({
+      message: "The entitlement could not be recorded.",
+      action: "Retry. If it persists, check the app database for the pithy_payments_* tables.",
+      detail: `Wrote entitlement "${input.entitlement}" for ${encodeSubjectReference(input)} but could not read it back.`,
+    });
+  }
+  return PaymentsEntitlement.parse(written);
+}

package/src/entitlement/resolver.ts

@@ -0,0 +1,125 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyMiddleware } from "@pithy-sh/core/src/capability/capability";
+import type { Entitlement, EntitlementHolder, EntitlementResolver } from "@pithy-sh/core/src/entitlement/entitlement";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { encodeSubjectReference, type PaymentsSubject } from "../data/subject";
+import type { PaymentsDatabase } from "../data/tables";
+import { resolveEntitlements } from "../projection/resolve";
+import { type PaymentsSubjectSeam, resolvePaymentsSubject } from "./subjectSeam";
+
+/**
+ * Payments filling the entitlement seam. Core's default (`noEntitlementProvider`) holds nothing so that an
+ * uncomposed gate denies; this replaces it with a resolver over the materialized read model in D1.
+ *
+ * The name payments answers under. `requireEntitlement()` puts it in `detail` on a denial, which is what
+ * lets an operator tell "genuinely unentitled" from "nothing wired" without telling a client either.
+ */
+export const PAYMENTS_ENTITLEMENT_PROVIDER = "payments";
+
+/**
+ * How a subject appears in a denial's `detail` and on a denial's audit row — core's {@link EntitlementHolder},
+ * which is display text and an audit dimension and **nothing a gate compares**.
+ *
+ * The label is `encodeSubjectReference`'s form, so the string in a log line is the same string the rails
+ * stamp into a store and the same one `pithy payments reconcile --subject` takes. One spelling of a holder
+ * across the whole capability means an operator reading a denial can paste it into the support command.
+ *
+ * **`tenant` is the organization id, or null under per-person billing** — and the null is the honest answer
+ * rather than a gap. `AuditEvent.tenant` is the dimension a trail is read by, and a consumer app has no such
+ * dimension: the holder is the actor, so a tenant here would echo `actorId` and invent a tenancy the app
+ * does not have. Under organization billing it is exactly the value that answers "which of our customers is
+ * hitting the paywall", which `actorId` cannot, because one person acts in two organizations.
+ */
+export function paymentsEntitlementHolder(subject: PaymentsSubject): EntitlementHolder {
+  return {
+    label: encodeSubjectReference(subject),
+    tenant: subject.subjectType === "organization" ? subject.subjectId : null,
+  };
+}
+
+/**
+ * A resolver for one subject, over one database. The whole seam: who is asking is already decided.
+ *
+ * The subject is the **pair**, never an id — `data/subject.ts` for why both halves travel together. Taking
+ * one object rather than two strings is what keeps a caller from transposing them, and what keeps a
+ * `subjectType` from config being paired with a `subjectId` from somewhere else.
+ */
+export function createPaymentsEntitlementResolver(
+  db: PaymentsDatabase,
+  subject: PaymentsSubject,
+  now: () => Date = () => new Date(),
+): EntitlementResolver {
+  return {
+    provider: PAYMENTS_ENTITLEMENT_PROVIDER,
+    list: () => resolveEntitlements(db, subject, now()),
+    // Unconditional here: this resolver was handed its subject, so there is no case where it cannot say.
+    holder: async () => paymentsEntitlementHolder(subject),
+  };
+}
+
+/**
+ * The middleware that installs the resolver, per request, over `c.var.db.<database>`.
+ *
+ * **Everything is resolved inside `list()`, not around it, and that is the point.** Middleware order is the
+ * adopter's — it follows the order of the `capabilities` array in their `pithy.config.ts` — so this
+ * middleware may well run before `@pithy-sh/auth` has set `c.var.auth`. Reading the caller at gate time
+ * rather than at install time makes the resolver correct whatever that order is, and it means a request that
+ * never gates on an entitlement never builds a Kysely instance or touches D1. The subject seam is resolved
+ * on the same schedule and for the same reason: an adopter's resolver reads the session, and the session is
+ * only on the request once whichever middleware sets it has run.
+ *
+ * **The subject is resolved first, before the database is even looked for.** With nobody resolved there is
+ * nothing to ask D1, so the binding check below has no business running — an organization-billed Worker
+ * whose seam answers nothing must read as unentitled, which is a denial from the gate, and not as broken,
+ * which is what a 500 from a wiring check would have said. Unanswered is unentitled: see `subjectSeam.ts`
+ * for why that is the only safe direction, and why nothing here falls back to `c.var.auth.userId`.
+ *
+ * With nobody to resolve for, the resolver holds nothing. It still names payments as the provider, because
+ * payments *is* composed — an anonymous caller is a 401 from the gate and an unresolved subject is a 403,
+ * neither is a composition problem, and reporting `null` here would send an operator looking for a missing
+ * capability.
+ */
+export function installEntitlementResolver(database: string, seam: PaymentsSubjectSeam): PithyMiddleware {
+  return (app) => {
+    app.use("*", async (c, next) => {
+      // **One resolution per request, shared by `list()` and `holder()`.** The seam is the adopter's and
+      // usually reads their session — a KV get, a D1 row — and a denial calls both halves, so resolving
+      // twice would double that cost on precisely the path that is already failing. Memoizing the
+      // *promise* rather than the value also makes two concurrent gates on one request share one read.
+      let resolving: Promise<PaymentsSubject | undefined> | undefined;
+      const subjectOnce = (): Promise<PaymentsSubject | undefined> => {
+        resolving ??= resolvePaymentsSubject(c, seam);
+        return resolving;
+      };
+      c.set("entitlements", {
+        provider: PAYMENTS_ENTITLEMENT_PROVIDER,
+        // Who the read answered for, for the log and the trail alone. `undefined` is a real answer and a
+        // different one from "holds nothing": it is a caller acting for no organization, which is what
+        // lets core's denial say so instead of reporting an empty list twice over.
+        holder: async (): Promise<EntitlementHolder | undefined> => {
+          const subject = await subjectOnce();
+          return subject ? paymentsEntitlementHolder(subject) : undefined;
+        },
+        list: async (): Promise<readonly Entitlement[]> => {
+          const subject = await subjectOnce();
+          if (!subject) return [];
+          const db = (c.var.db as Record<string, PaymentsDatabase>)[database];
+          if (!db) {
+            // Unreachable through `createBackend`, which validates the `DB` binding at boot. Thrown rather
+            // than returned as an empty list so the gate's own catch logs the wiring fault: a silent empty
+            // list denies correctly but looks identical to a subject that simply has not bought anything.
+            throw new InternalError({
+              message: "Payments is not configured.",
+              action: "Bind a D1 database named DB in wrangler.jsonc.",
+              detail: `No \`${database}\` database on c.var.db; payments cannot resolve entitlements.`,
+            });
+          }
+          return resolveEntitlements(db, subject, new Date());
+        },
+      });
+      await next();
+    });
+  };
+}