@pithy-sh/payments 0.1.0

package/pithy.manifest.json

@@ -0,0 +1,68 @@
+{
+  "name": "payments",
+  "package": "@pithy-sh/payments",
+  "requiredBindings": [
+    { "type": "d1", "name": "DB" },
+    {
+      "type": "workflow",
+      "name": "PAYMENTS_RECONCILE",
+      "job": "reconcile",
+      "className": "PaymentsReconcileWorkflow",
+      "optional": true
+    }
+  ],
+  "peerCapabilities": ["secrets"],
+  "optionalCapabilities": ["auth", "controlplane", "ledger"],
+  "migrationNamespace": "payments",
+  "secrets": [
+    {
+      "name": "payments-provider-credentials",
+      "origin": {
+        "kind": "obtained",
+        "issuer": "other",
+        "documentation": "https://github.com/pithy-sh/pithy/blob/main/docs/commands/payments.md#where-each-rails-credentials-come-from"
+      },
+      "rotation": {
+        "kind": "manual",
+        "issuer": "other",
+        "documentation": "https://github.com/pithy-sh/pithy/blob/main/docs/commands/payments.md#where-each-rails-credentials-come-from"
+      }
+    }
+  ],
+  "whenToEnable": "Four payment rails — Apple, Google, Stripe, Lemon Squeezy — resolving to one cross-rail entitlement, in your own Worker and your own D1. Buy Pro on iOS, be entitled on the web, with no hosted data plane holding your purchase history. A product is not an entitlement: `pro_monthly` and `pro_annual`, across four stores' catalogs, grant one key — `pro` — and gating code names the key, never a SKU. Every write converges on one idempotent projection keyed on (rail, provider transaction id), so a client submission, a provider webhook, and a reconciliation pass produce the identical row: a dropped client call costs nothing and a replayed webhook changes nothing. The projection is monotonic on the provider's own event time, because providers do not guarantee delivery order and a stale `expired` arriving after the `renewed` that superseded it would silently revoke a paying subscriber. Sandbox purchases are tracked as sandbox and never grant a production entitlement. A cron Workflow re-verifies what the webhooks missed, because webhook-only systems rot silently. Lemon Squeezy is the merchant of record — it owns the sales tax, the EU VAT registration, the invoicing and the chargebacks, which is what a solo developer reaches for when the alternative is registering for VAT in twenty-seven countries. Add auth — every route belongs to an authenticated purchaser or a machine proving authenticity, and there are no public routes. Add secrets: the four rails' credentials are read through it, so payments will not compose without it. Ledger fulfillment is opt-in per product; most products never touch a balance.",
+  "scaffold": [
+    "Add a `payments({ rails: {...}, products: {...} })` block to pithy.config.ts. The catalog lives in config, not in D1 — a product's entitlement mapping is policy, so it belongs in git rather than in a mutable table. A new SKU needs a deploy, which is the correct trade.",
+    "Give every product a `type` (`consumable`, `non_consumable`, or `subscription`), a display `name`, the `entitlements` it grants, and one block per rail it ships on. Omit a rail to ship without it — `remove_ads` on mobile only is expressed by omission, not a flag.",
+    "Bind a D1 database named DB in wrangler.jsonc — the same app database your other capabilities use.",
+    "Run `pithy migrate` to create pithy_payments_purchases, pithy_payments_entitlements, pithy_payments_provider_accounts, pithy_payments_webhook_events, and pithy_payments_reconcile_runs.",
+    "Add `@pithy-sh/secrets` if it is not already installed, then supply each rail's credentials through it: Apple's App Store Connect key with its key and issuer ids, Google's service account, Stripe's secret key and webhook signing secret. Apple's root certificates are public and ship with the package.",
+    "Add `@pithy-sh/auth` if it is not already installed. Purchases belong to an authenticated user; with no auth capability composed every route denies.",
+    "Comping and revoking entitlements by hand is a `control-plane` surface, not an admin user, so /payments/entitlements/grant and /payments/entitlements/revoke are reached with a signed management credential rather than a session. A grant must name an entitlement key this project defines — one a product grants, or one declared in `manualEntitlements` — so a console cannot comp `pr` for `pro` and leave a customer locked out; `payments:catalog:read` is the separately-granted read that lets a console offer a list instead of a text box, and it discloses only each product's id, kind, name and keys. Add `controlplane()` to this Worker and run `pithy dashboard connect`, then grant the connection `payments:catalog:read`, `payments:entitlements:grant`, `payments:entitlements:revoke`, or only the one its tooling needs — a refund tool that cannot comp cannot be turned into one, and a comp tool cannot take paid access away from a live customer. With the seam not composed both routes answer `controlplane/not_connected`, and no app session opens either of them whatever scopes it carries.",
+    "Selling through Stripe also needs a `stripe` block naming where its hosted pages return to — `successUrl`, `cancelUrl`, `portalReturnUrl`. Required whenever the rail is on, and config rather than request input: a client that could name a return URL could send a paying customer to a page it controls. Put `{CHECKOUT_SESSION_ID}` in the success URL's query and the thank-you page can post it to /payments/purchases for an entitlement at once.",
+    "Set the account link on every purchase your app starts — Apple's appAccountToken and Google's obfuscatedAccountId, in the app's own purchase flow. A webhook arrives carrying the provider's identifier and names no holder of ours, so a purchase made without one arrives orphaned. Stripe needs nothing from you here: /payments/checkout sets `client_reference_id` from the subject the caller acts for, which is the one hook a client must never be allowed to name.",
+    "Run `pithy payments provision` to deploy the reconciliation Workflow and write its binding. Every pass it runs leaves a row in pithy_payments_reconcile_runs — started, finished, rail, environment and tally, kept ninety days — and `GET /payments/admin/reconcile-runs` reads them behind `payments:reconcile:read`, so an adopter can tell a healthy integration from one whose cron stopped firing without granting anybody the purchase log. `pithy add` touches no Cloudflare account; provisioning is the separate, explicit step. Skipping it costs nothing up front — the binding is optional and every route works without it — but webhook-only systems rot silently, so the nightly pass is what turns a dropped delivery into a repaired row rather than a support ticket.",
+    "Gate a paid route with `requireEntitlement(\"pro\")` from @pithy-sh/core. The gate lives in core, so a Worker with no payments capability composed denies rather than opens."
+  ],
+  "configOptions": [
+    {
+      "key": "basePath",
+      "default": "/payments",
+      "describe": "Where the payments routes mount, webhooks included. Edit the `rails` and `products` objects by hand — the catalog maps each store's SKU to one logical product and the entitlements it grants, and it is the whole point of the capability."
+    },
+    {
+      "key": "billingSubject",
+      "choices": ["user", "organization"],
+      "describe": "Who holds a subscription in this project. user — one person buys, one person is entitled. organization — a company buys, and everybody in it is entitled. It keys the entitlement column and its UNIQUE index, so changing it once anybody has subscribed is a migration, not an edit."
+    },
+    {
+      "key": "manualEntitlements",
+      "default": [],
+      "describe": "Entitlement keys the control plane may grant that no product sells — a beta flag, an internal tier, a key that exists only to be comped. Declared, because the alternative to declaring is not checking: with this empty, a manual grant of any key outside the catalog is refused. Only grants are constrained; a revoke of a key the catalog has since dropped stays legal."
+    },
+    {
+      "key": "graceGrantsAccess",
+      "default": true,
+      "describe": "Whether a subscription in its billing-retry grace period still grants its entitlements. True, because that is the point of grace — a failed card should not lock a paying subscriber out mid-period. Once grace is exhausted the purchase moves to on_hold, which never grants."
+    }
+  ]
+}

package/src/admin/coverage.ts

@@ -0,0 +1,107 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+import type { PaymentsTables } from "../data/tables";
+import {
+  PAYMENTS_ENTITLEMENTS_READ_SCOPE,
+  PAYMENTS_PURCHASES_READ_SCOPE,
+  PAYMENTS_RECONCILE_READ_SCOPE,
+  PAYMENTS_SUBSCRIPTIONS_READ_SCOPE,
+} from "../http/scopes";
+
+/**
+ * What a management client may learn from each table payments owns.
+ *
+ * **This is a decision, taken once, where the tables are.** Issue #247 was not a missing route so much
+ * as a missing question: payments stored a customer's whole purchase history and their entitlement read
+ * model, shipped two control-plane writes against the second, and nobody ever asked whether a management
+ * client could *see* either. Three panes in the first adopter computed `absent` and dropped out of the
+ * rail. Absent, not blocked — no grant restores a route that does not exist.
+ *
+ * So every table declares which side of the line it is on, and the type is
+ * `Record<keyof PaymentsTables, …>` rather than a partial map: **a sixth table does not compile until
+ * somebody decides what a management client may see of it.** That is the structural half of the gate.
+ * `coverage.test.ts` is the other half — it checks that a table declaring a read has a control-plane
+ * `GET` demanding exactly that scope, and that every resource this capability can *write* it can also
+ * read.
+ *
+ * A withheld table states its reason here rather than in a test's exclusion list, because the reason is
+ * a property of the table and belongs next to it. Neither reason below is "no pane asked for it".
+ */
+
+/** One table's disclosure decision: the reads that return its rows, or why there are none. */
+export type PaymentsDisclosure =
+  | {
+      /**
+       * Every control-plane scope that returns rows from this table. Non-empty by construction, so
+       * "readable" cannot degrade into "readable by nothing" through an edit.
+       */
+      readonly reads: readonly [ControlPlaneScope, ...ControlPlaneScope[]];
+    }
+  | {
+      /** Why no management client may read this table. A property of the table, not an exemption. */
+      readonly withheld: string;
+    };
+
+/** Every payments table, and what a management client may learn from it. */
+export const PAYMENTS_TABLE_DISCLOSURE: Record<keyof PaymentsTables, PaymentsDisclosure> = {
+  /**
+   * The purchase log, read two ways. `payments:purchases:read` is the whole projection of provider
+   * truth; `payments:subscriptions:read` is the same rows narrowed to the ones that renew, so a tool
+   * watching renewals can be granted the forward-looking half without the customer's entire order
+   * history. Neither read ever selects `payload` — see `read.ts`.
+   */
+  pithyPaymentsPurchases: { reads: [PAYMENTS_PURCHASES_READ_SCOPE, PAYMENTS_SUBSCRIPTIONS_READ_SCOPE] },
+  /** The entitlement read model — what a subject holds right now, and why. */
+  pithyPaymentsEntitlements: { reads: [PAYMENTS_ENTITLEMENTS_READ_SCOPE] },
+  /**
+   * Withheld, and the argument is stronger now that the far side is a subject rather than a user. Every row
+   * is a *provider-side* identity — `cus_PithyAda`, an Apple `appAccountToken` — paired with the subject
+   * that holds it: a Pithy user, or an organization whose id came out of the adopter's own membership
+   * model. Listing it in bulk hands a management client a cross-reference from a store account to the
+   * adopter's internal id space, and under organization billing that maps a company to its billing
+   * identity at every store it sells through.
+   *
+   * There is nothing an operator can do with the page that a purchase does not already answer: a purchase
+   * names its own subject and its own rail. The one legitimate question it settles — "which Stripe customer
+   * is this holder" — belongs to a route that answers it for one named subject, if it is ever wanted, and
+   * not to a page of a thousand of them.
+   */
+  pithyPaymentsProviderAccounts: {
+    withheld:
+      "Every row pairs a provider-side account identifier with a subject — a Pithy user, or an organization from the adopter's own membership model. In bulk that is a cross-reference from a store's id space into the adopter's, and nothing on this surface needs it: a purchase already names its subject and its rail.",
+  },
+  /**
+   * Withheld. Each row holds the raw verified provider notification exactly as it arrived, and that
+   * payload is a bearer artifact — the same thing `responses.ts` refuses to put on a purchase view, for
+   * the same reason. There is no projection of a delivery log worth a read scope either: what an operator
+   * wants from it is "why did this purchase not update", and that question is answered by the purchase's
+   * own status and the audit trail's `payments/webhook_received` events, neither of which is a receipt.
+   */
+  pithyPaymentsWebhookEvents: {
+    withheld:
+      "Each row is a raw verified provider payload — a bearer artifact. The question a delivery log is read for is answered by the purchase's status and the audit trail, without handing anyone a receipt.",
+  },
+  /**
+   * The reconciliation run log — operational state, on its own scope.
+   *
+   * Readable, and readable *separately*, because it is the one table here that is not about a customer. A
+   * run names no account, no transaction and no amount; it says whether the compensating control for a
+   * delivery mechanism that is known to fail has been firing. A health monitor should be able to hold
+   * exactly this, and an adopter granting it should not thereby disclose what anybody bought.
+   */
+  pithyPaymentsReconcileRuns: { reads: [PAYMENTS_RECONCILE_READ_SCOPE] },
+  /**
+   * Withheld. One opaque resume token per stream, and nothing else — no amount, no customer, no event.
+   *
+   * Withheld because there is nothing here a management client could act on and one thing it could break:
+   * a pane that could read a cursor invites a pane that could write one, and a cursor moved forward skips
+   * every event between the old value and the new, silently and unrepairably. The sweep's own state is
+   * the sweep's; what it *found* is in the purchases and webhook-event tables, which are readable.
+   */
+  pithyPaymentsSyncCursors: {
+    withheld:
+      "A sweep's resume token is internal bookkeeping, not a fact about a customer. Reading it answers nothing a management client asks, and the write it invites would silently skip every event between two cursor values.",
+  },
+};

package/src/admin/read.ts

@@ -0,0 +1,360 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { decodeCursor, type PageCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
+import type { z } from "zod";
+import { PaymentsEntitlement } from "../data/entitlement";
+import { PaymentsPurchase, type PurchaseEnvironment } from "../data/purchase";
+import type { PaymentsRail } from "../data/rail";
+import { PaymentsReconcileRun } from "../data/reconcileRun";
+import type { PurchaseStatus } from "../data/status";
+import type { PaymentsSubject } from "../data/subject";
+import {
+  PAYMENTS_ENTITLEMENTS_TABLE,
+  PAYMENTS_PURCHASES_TABLE,
+  PAYMENTS_RECONCILE_RUNS_TABLE,
+  paymentsDatabase,
+} from "../data/tables";
+
+/**
+ * The management read model — the queries behind the control-plane reads, and nothing else.
+ *
+ * **It lives beside the projection rather than inside it.** Everything in `projection/` writes or reads
+ * one subject's own rows; these read across *every* subject, which is a different operation with a
+ * different blast radius. Keeping it out of the projection means no in-process caller reaches it by
+ * accident, and it is the same arrangement `@pithy-sh/ledger`'s `admin/read.ts` makes for the same
+ * reason.
+ *
+ * ## The payload is not projected, and it is not selected either
+ *
+ * `pithy_payments_purchases.payload` is the whole verified provider response: a bearer artifact on Apple
+ * and Google, and on Stripe a document carrying the buyer's email address, name and billing details.
+ * Every query below names its columns, and that column is not among them — so the receipt does not reach
+ * the Worker's memory on a management read at all, let alone the response. A projection that dropped it
+ * afterwards would be one refactor away from leaking it; a `SELECT` that never asks for it is not.
+ *
+ * That is also the honest answer to the masking question `@pithy-sh/email` answers by masking a
+ * recipient. Payments stores **no** direct personal identifier of its own — the only identity on either
+ * table is the **subject pair**, `(subjectType, subjectId)`, opaque ids the adopter's auth capability and
+ * the adopter's own membership model issued, and already the address a management client must name to ask
+ * about a holder. The single field that would have carried an email address into a purchases list is
+ * `payload`, and the control is stronger than a mask: it is never read.
+ *
+ * ## A subject filter is the pair or it is nothing
+ *
+ * Every query below takes its owner filter as one {@link PaymentsSubject}, never as a loose id. Nothing in
+ * the kit keeps an organization id from equalling some user's id, so a `WHERE subject_id = ?` alone would
+ * hand a management client asking about a person the rows of an organization that happens to share the id.
+ * The object is what makes the two halves inseparable at every call site — `data/subject.ts` states the
+ * argument once.
+ *
+ * ## Keyset, never offset
+ *
+ * Every listing pages on `(sort, id)` descending through core's shared cursor helper. `OFFSET` shifts
+ * under a reader whenever a row is inserted, and a purchase table is written to by three paths at once —
+ * a client submission, three providers' webhooks, and the nightly reconciliation pass. A page 2 fetched
+ * a second later would repeat rows it already showed and skip rows it never did.
+ *
+ * The primary key here is a **text UUID**, deliberately (sequential ids would leak order volume), so it
+ * is no use as a sort: it is unique but it is not monotonic. Purchases therefore sort on `purchasedAt`
+ * with the id as the tiebreak, and entitlements on `createdAt` with the same. Both columns are indexed
+ * for exactly this by `payments_0001_purchases` — without those indexes a purchases pane would sort a
+ * customer's entire order history on every page load.
+ */
+
+/** One page of a keyset listing, and where the next one resumes. */
+export interface PaymentsPage<T> {
+  /** The rows, newest first. */
+  items: T[];
+  /** The cursor for the next page, or null at the end of the list. Opaque; hand it back verbatim. */
+  nextCursor: string | null;
+}
+
+/**
+ * A purchase as a management read sees it — every column but the stored provider payload, the provider
+ * SKU, and the bookkeeping timestamps the projection keeps for itself.
+ *
+ * Derived from {@link PaymentsPurchase} with `.pick`, never restated, so the row schema stays the one
+ * definition of the table and the codecs still decode dates on the way out of D1. `providerProductId`
+ * is left behind because `productId` and `rail` already name what was bought and the SKU is the
+ * adopter's own config; `providerEventAt` and `createdAt` because they describe when *we* processed
+ * something, which is a question for the audit trail rather than for a purchases pane.
+ */
+export const PaymentsPurchaseRecord = PaymentsPurchase.pick({
+  id: true,
+  subjectType: true,
+  subjectId: true,
+  rail: true,
+  providerTransactionId: true,
+  originalTransactionId: true,
+  productId: true,
+  type: true,
+  status: true,
+  environment: true,
+  amountMinor: true,
+  currency: true,
+  purchasedAt: true,
+  expiresAt: true,
+  revokedAt: true,
+  resumesAt: true,
+  updatedAt: true,
+}).describe("One purchase as a management read selects it — never the stored provider payload.");
+export type PaymentsPurchaseRecord = z.output<typeof PaymentsPurchaseRecord>;
+
+/** The columns {@link PaymentsPurchaseRecord} covers, as Kysely needs them. One list, derived from the schema. */
+const PURCHASE_COLUMNS = Object.keys(PaymentsPurchaseRecord.shape) as (keyof PaymentsPurchaseRecord)[];
+
+/** What {@link listPurchases} accepts. Every filter is optional; together they are an AND. */
+export interface PurchasesQuery {
+  /** Restrict to one subject's purchases — the pair, so an id shared across kinds cannot cross. */
+  subject?: PaymentsSubject;
+  /** Restrict to one store. */
+  rail?: PaymentsRail;
+  /** Restrict to one normalized status. */
+  status?: PurchaseStatus;
+  /** Restrict to one store environment — the filter that separates real money from test transactions. */
+  environment?: PurchaseEnvironment;
+  /** Where to resume, from a previous page's `nextCursor`. A malformed one is a first page. */
+  cursor?: string;
+  /** How many rows to return, clamped by `pageLimit`. */
+  limit?: number;
+}
+
+/** What {@link listSubscriptions} accepts. No `rail`: a subscription is read forwards, not by store. */
+export interface SubscriptionsQuery {
+  /** Restrict to one subject's subscriptions — the pair, never an id on its own. */
+  subject?: PaymentsSubject;
+  /** Restrict to one normalized status — `active`, `in_grace`, `canceled`. */
+  status?: PurchaseStatus;
+  /** Where to resume, from a previous page's `nextCursor`. A malformed one is a first page. */
+  cursor?: string;
+  /** How many rows to return, clamped by `pageLimit`. */
+  limit?: number;
+}
+
+/** What {@link listEntitlements} accepts. */
+export interface EntitlementsQuery {
+  /** Restrict to one subject — the pair, never an id on its own. */
+  subject?: PaymentsSubject;
+  /** Restrict to one entitlement key — "who holds `pro`". */
+  entitlement?: string;
+  /** Where to resume, from a previous page's `nextCursor`. A malformed one is a first page. */
+  cursor?: string;
+  /** How many rows to return, clamped by `pageLimit`. */
+  limit?: number;
+}
+
+/**
+ * A cursor this table can resume from, or undefined.
+ *
+ * `PageCursor.sort` is a union because Better Auth stores ISO text where Pithy's own tables store
+ * ms-epoch numbers, and comparing a string against an integer column in SQLite silently orders by
+ * something nobody meant. Both tables here store a number, so anything else is treated exactly as a
+ * malformed cursor is: undefined, and the caller gets a first page rather than an error it could probe.
+ */
+function resume(raw: string | undefined): { sort: number; id: string } | undefined {
+  const cursor: PageCursor | undefined = decodeCursor(raw);
+  if (!cursor || typeof cursor.sort !== "number") return undefined;
+  return { sort: cursor.sort, id: String(cursor.id) };
+}
+
+/**
+ * The purchase log, newest first, filtered.
+ *
+ * Ordered on `purchasedAt` — when the *store* recorded the sale — rather than on when we first heard of
+ * it. A reconciliation pass backfilling a week-old purchase must land in the week-old position, or a
+ * purchases pane becomes a log of our own processing rather than of the customer's commerce.
+ */
+export async function listPurchases(
+  d1: D1Database,
+  query: PurchasesQuery = {},
+): Promise<PaymentsPage<PaymentsPurchaseRecord>> {
+  return await purchasePage(d1, query, undefined);
+}
+
+/**
+ * The purchases that renew, newest first.
+ *
+ * A separate function rather than a `type` filter {@link listPurchases} would accept, because a caller
+ * that could name the type could hold `payments:subscriptions:read` and read the whole purchase log
+ * through it. The narrowing is applied here, where no request reaches it.
+ */
+export async function listSubscriptions(
+  d1: D1Database,
+  query: SubscriptionsQuery = {},
+): Promise<PaymentsPage<PaymentsPurchaseRecord>> {
+  return await purchasePage(d1, query, "subscription");
+}
+
+/** One page of the purchases table, with the product type fixed by the caller rather than by a request. */
+async function purchasePage(
+  d1: D1Database,
+  query: PurchasesQuery,
+  type: "subscription" | undefined,
+): Promise<PaymentsPage<PaymentsPurchaseRecord>> {
+  const limit = pageLimit(query.limit);
+  const after = resume(query.cursor);
+
+  let selection = paymentsDatabase(d1)
+    .selectFrom(PAYMENTS_PURCHASES_TABLE)
+    // Named columns, never `selectAll`. `payload` is a bearer artifact and is not among them, so a
+    // management read never loads one — see the file comment.
+    .select(PURCHASE_COLUMNS)
+    .orderBy("purchasedAt", "desc")
+    .orderBy("id", "desc")
+    // One more than asked for: the extra row is how "is there another page" is answered without a COUNT,
+    // which on a purchase table is a full scan on every page load.
+    .limit(limit + 1);
+
+  if (type !== undefined) selection = selection.where("type", "=", type);
+  if (query.subject !== undefined) {
+    // Both halves or neither. One column of the pair is not a narrower filter, it is a different question.
+    selection = selection
+      .where("subjectType", "=", query.subject.subjectType)
+      .where("subjectId", "=", query.subject.subjectId);
+  }
+  if (query.rail !== undefined) selection = selection.where("rail", "=", query.rail);
+  if (query.status !== undefined) selection = selection.where("status", "=", query.status);
+  if (query.environment !== undefined) selection = selection.where("environment", "=", query.environment);
+  if (after) {
+    selection = selection.where((eb) =>
+      eb.or([
+        eb("purchasedAt", "<", after.sort),
+        eb.and([eb("purchasedAt", "=", after.sort), eb("id", "<", after.id)]),
+      ]),
+    );
+  }
+
+  const rows = await selection.execute();
+  return toPage(
+    rows.map((row) => PaymentsPurchaseRecord.parse(row)),
+    limit,
+    (purchase) => ({ sort: purchase.purchasedAt.getTime(), id: purchase.id }),
+  );
+}
+
+/**
+ * The entitlement model, newest first, filtered.
+ *
+ * Sorted on `createdAt` rather than `updatedAt`, and the difference matters on this table: the
+ * projection re-derives every affected row on every purchase write, so `updatedAt` moves constantly for
+ * reasons that have nothing to do with the grant. Ordering on it would shuffle rows under a reader. When
+ * a key first appeared for a subject never moves.
+ *
+ * A lapsed row is returned rather than filtered out. Whether it still grants is the projection's question
+ * in `http/view.ts`, resolved against `expiresAt` at read time exactly as the hot path resolves it — and an
+ * operator answering "when did their Pro end" needs the row and its date to survive the read.
+ */
+export async function listEntitlements(
+  d1: D1Database,
+  query: EntitlementsQuery = {},
+): Promise<PaymentsPage<PaymentsEntitlement>> {
+  const limit = pageLimit(query.limit);
+  const after = resume(query.cursor);
+
+  let selection = paymentsDatabase(d1)
+    .selectFrom(PAYMENTS_ENTITLEMENTS_TABLE)
+    .selectAll()
+    .orderBy("createdAt", "desc")
+    .orderBy("id", "desc")
+    .limit(limit + 1);
+
+  if (query.subject !== undefined) {
+    selection = selection
+      .where("subjectType", "=", query.subject.subjectType)
+      .where("subjectId", "=", query.subject.subjectId);
+  }
+  if (query.entitlement !== undefined) selection = selection.where("entitlement", "=", query.entitlement);
+  if (after) {
+    selection = selection.where((eb) =>
+      eb.or([eb("createdAt", "<", after.sort), eb.and([eb("createdAt", "=", after.sort), eb("id", "<", after.id)])]),
+    );
+  }
+
+  const rows = await selection.execute();
+  return toPage(
+    rows.map((row) => PaymentsEntitlement.parse(row)),
+    limit,
+    (entitlement) => ({ sort: entitlement.createdAt.getTime(), id: entitlement.id }),
+  );
+}
+
+/**
+ * Every entitlement one subject holds, ordered by key.
+ *
+ * Unpaginated on purpose, and for the reason `@pithy-sh/ledger`'s `readAccounts` is: the table is keyed
+ * `UNIQUE (subjectType, subjectId, entitlement)`, so this returns at most one row per key the catalog
+ * sells plus whatever has been comped by hand. A cursor over a list that short would be ceremony.
+ *
+ * The subject is one argument because it is one fact. Two positional strings would typecheck transposed,
+ * and the pair leads the unique index in that order — so this read is a covering prefix scan rather than
+ * a filter over every holder of the key.
+ *
+ * A subject holding nothing is an empty list, not a 404. An entitlement row appears with the first
+ * purchase that grants one, so its absence is not a missing holder — and answering 404 would make this
+ * surface an existence oracle for user and organization ids alike.
+ */
+export async function readEntitlements(d1: D1Database, subject: PaymentsSubject): Promise<PaymentsEntitlement[]> {
+  const rows = await paymentsDatabase(d1)
+    .selectFrom(PAYMENTS_ENTITLEMENTS_TABLE)
+    .selectAll()
+    .where("subjectType", "=", subject.subjectType)
+    .where("subjectId", "=", subject.subjectId)
+    .orderBy("entitlement", "asc")
+    .execute();
+  return rows.map((row) => PaymentsEntitlement.parse(row));
+}
+
+/** What {@link listReconcileRuns} accepts. */
+export interface ReconcileRunsQuery {
+  /** Restrict to the passes narrowed to one store. Never matches a pass that ran against every rail. */
+  rail?: PaymentsRail;
+  /** Restrict to one store environment. */
+  environment?: PurchaseEnvironment;
+  /** Where to resume, from a previous page's `nextCursor`. A malformed one is a first page. */
+  cursor?: string;
+  /** How many rows to return, clamped by `pageLimit`. */
+  limit?: number;
+}
+
+/**
+ * The reconciliation passes this deployment has run, newest first.
+ *
+ * Ordered on `startedAt`, not `finishedAt`, and the difference is the health question: a pass that began and
+ * never ended is the failure worth seeing, and ordering on the timestamp it never wrote would hide it behind
+ * every pass that did. The id is the tiebreak, on the index the migration creates for exactly this.
+ *
+ * `selectAll` here where the purchase read names its columns, and the reason is the point of the table: there
+ * is no column to withhold. Every field is a count, a timestamp or an enum, so there is no bearer artifact to
+ * leave behind and no personal identifier to mask — see `data/reconcileRun.ts`.
+ */
+export async function listReconcileRuns(
+  d1: D1Database,
+  query: ReconcileRunsQuery = {},
+): Promise<PaymentsPage<PaymentsReconcileRun>> {
+  const limit = pageLimit(query.limit);
+  const after = resume(query.cursor);
+
+  let selection = paymentsDatabase(d1)
+    .selectFrom(PAYMENTS_RECONCILE_RUNS_TABLE)
+    .selectAll()
+    .orderBy("startedAt", "desc")
+    .orderBy("id", "desc")
+    .limit(limit + 1);
+
+  if (query.rail !== undefined) selection = selection.where("rail", "=", query.rail);
+  if (query.environment !== undefined) selection = selection.where("environment", "=", query.environment);
+  if (after) {
+    selection = selection.where((eb) =>
+      eb.or([eb("startedAt", "<", after.sort), eb.and([eb("startedAt", "=", after.sort), eb("id", "<", after.id)])]),
+    );
+  }
+
+  const rows = await selection.execute();
+  return toPage(
+    rows.map((row) => PaymentsReconcileRun.parse(row)),
+    limit,
+    (run) => ({ sort: run.startedAt.getTime(), id: run.id }),
+  );
+}