@pithy-sh/payments 0.1.0

package/src/projection/event.ts

@@ -0,0 +1,101 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { PurchaseEnvironment, PurchaseRole } from "../data/purchase";
+import { PaymentsRail } from "../data/rail";
+import { PurchaseStatus } from "../data/status";
+import { PaymentsSubject } from "../data/subject";
+
+/**
+ * A provider event, normalized. This is the writer's whole input, and the seam between "how a rail talks"
+ * and "what the projection stores": a rail module verifies a receipt or parses a notification and produces
+ * one of these, and nothing past this point knows which store it came from.
+ *
+ * The shape is deliberately a *state*, not a *delta*. A rail reports what the transaction is now, and the
+ * writer projects it — so a renewal, a refund, a grace period, and a revocation are all the same code path
+ * rather than four handlers that must each be kept correct.
+ *
+ * `providerEventAt` is the field the whole design leans on. It is the provider's own timestamp, not ours,
+ * because ours would record delivery order and delivery order is exactly what providers do not guarantee.
+ *
+ * **This is the owner-bound half of a two-part shape.** A rail produces an `UnboundProviderEvent` — this
+ * object with the subject pair omitted, declared in `rails/contract.ts` — and the route binds an owner onto
+ * it to make one of these. The split is the whole reason a store's bytes cannot decide who is entitled: a
+ * rail parses a payload and knows the transaction completely and the holder not at all, so the field it
+ * would have to fill in does not exist for it to fill in wrongly.
+ */
+export const ProviderEvent = z
+  .object({
+    rail: PaymentsRail.describe("Which store the event came from."),
+    providerTransactionId: z
+      .string()
+      .min(1)
+      .describe(
+        "The rail's own transaction id. Together with `rail` this is the row's identity forever — one provider transaction is one purchase row.",
+      ),
+    providerProductId: z
+      .string()
+      .min(1)
+      .describe("The rail's own SKU or price id. The writer resolves the logical product from it."),
+    subjectType: PaymentsSubject.shape.subjectType.describe(
+      "Whether `subjectId` names a user or an organization. Half the owner, and never separable from the other half — the route binds both together or neither.",
+    ),
+    subjectId: PaymentsSubject.shape.subjectId.describe(
+      "The subject the transaction belongs to. A client submission takes it from the authenticated caller through the configured subject seam; a webhook resolves it through the provider-account map or a decoded account reference.",
+    ),
+    status: PurchaseStatus.describe("The transaction's current normalized state, as the rail reports it."),
+    role: PurchaseRole.default("charge").describe(
+      "Whether this event records money moving or a subscription's standing. Omitted by every rail but Lemon Squeezy, which reports the two separately because its store does.",
+    ),
+    environment: PurchaseEnvironment.describe(
+      "Which store environment the transaction happened in. Checked against the deployment's own before anything is written.",
+    ),
+    purchasedAt: z.date().describe("When the store recorded the purchase."),
+    expiresAt: z
+      .date()
+      .nullable()
+      .default(null)
+      .describe("When access lapses, or null for a purchase that never expires. Null for a one-time purchase."),
+    revokedAt: z
+      .date()
+      .nullable()
+      .default(null)
+      .describe("When the purchase was refunded or revoked, or null while it stands."),
+    resumesAt: z
+      .date()
+      .nullable()
+      .default(null)
+      .describe(
+        "When a paused subscription resumes, as the provider stated it — never computed, and never set on a status other than `paused`. Null on a paused event is the provider reporting an indefinite pause. Produced only by `pauseResumesAt` in `data/pause.ts`, which is where each rail's source for it is declared.",
+      ),
+    originalTransactionId: z
+      .string()
+      .nullable()
+      .default(null)
+      .describe("The transaction that started the subscription, chaining renewals back to it. Null for a one-off."),
+    amountMinor: z
+      .number()
+      .int()
+      .nullable()
+      .default(null)
+      .describe("The amount charged in the currency's minor unit, or null when the rail did not report one."),
+    currency: z
+      .string()
+      .nullable()
+      .default(null)
+      .describe("The ISO currency of `amountMinor`, or null when the rail did not report one."),
+    providerEventAt: z
+      .date()
+      .describe(
+        "The provider's own timestamp for this event. The monotonic write rule compares against it, so an event staler than the row it would update changes nothing.",
+      ),
+    payload: z
+      .record(z.string(), z.unknown())
+      .describe("The verified provider payload, stored as received. The reconciliation and audit record."),
+  })
+  .describe(
+    "One provider event, normalized and bound to its owner — the projection writer's input. A rail produces this shape less the subject pair; the route adds it.",
+  );
+export type ProviderEvent = z.output<typeof ProviderEvent>;
+export type ProviderEventInput = z.input<typeof ProviderEvent>;

package/src/projection/orphans.ts

@@ -0,0 +1,226 @@
+// 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 type { PaymentsConfig } from "../config/config";
+import type { PurchaseEnvironment } from "../data/purchase";
+import type { PaymentsRail } from "../data/rail";
+import { PAYMENTS_WEBHOOK_EVENTS_TABLE, paymentsDatabase } from "../data/tables";
+import { PaymentsWebhookEvent, WEBHOOK_EVENT_ORPHANED, webhookEventAwaitsOwner } from "../data/webhookEvent";
+import type { VerifiedNotification } from "../rails/contract";
+import { resolveNotificationOwner } from "./owner";
+import { type PurchaseProjection, projectPurchase } from "./writer";
+
+/**
+ * The repair that runs when an account links: project the purchases that were waiting for exactly that.
+ *
+ * ## The gap this closes (#341)
+ *
+ * An orphan is an authentic notification carrying a real purchase and nothing that says whose it is. Both
+ * paths that meet one leave the row unfinished on purpose — the webhook handler records the reason and
+ * withholds `processedAt`, the sweep stamps `abandonedAt` so its stream can advance — and both then rely on
+ * **a later delivery of the same event** to repair it. That is the right bet when the store redelivers. It
+ * is no bet at all when the only future event is the account linking: nothing redelivers on that signal,
+ * every store's retry window closes within days, and the sweep's cursor is long past.
+ *
+ * Reproduced on real D1 before this existed: sweep an unstamped `subscription.activated` for an unlinked
+ * customer, link the account, sweep ten more times. The purchase is never projected. Not once, ever — the
+ * orphan gets exactly one owner resolution in its life, at the moment nobody could answer it.
+ *
+ * ## Why here and not in the sweep
+ *
+ * The two halves of the question live in different places. The link path knows *which* customer just became
+ * resolvable; the sweep knows *which events* are outstanding. One of them has to ask the other, and asking
+ * from the link side is the cheaper direction by a wide margin: it runs once per link rather than once per
+ * sweep, the set it looks at is bounded by {@link ORPHAN_REPAIR_LIMIT}, and — decisively — it works on the
+ * four rails that have no sweep at all. A rail without a repair pass is exactly where a lost orphan stays
+ * lost.
+ *
+ * ## Which rows, and why not simply "unfinished"
+ *
+ * {@link webhookEventAwaitsOwner}: unfinished, and carrying the {@link WEBHOOK_EVENT_ORPHANED} marker. An
+ * account linking repairs one thing — a missing owner. A quarantined event, a failed projection, an unmapped
+ * SKU are all unfinished too, and re-running them on this signal would be an unbounded retry loop triggered
+ * by unrelated traffic. The marker is what makes the set the *right* set rather than merely a small one.
+ *
+ * ## Why a payload replay rather than a stored event
+ *
+ * The row already holds the notification whole — that is what `payload` is for, and the reason it is stored
+ * rather than summarized. So the purchase is recoverable without a second column, a migration, or a shape
+ * that could disagree with the payload it was derived from. What it costs is a rail able to re-read its own
+ * recorded body, which is {@link PaymentsRailProvider.replay} and is optional for the two rails whose stored
+ * body is a signed blob.
+ *
+ * ## What it deliberately does not do
+ *
+ * It never *invents* an owner. Every row goes back through {@link resolveNotificationOwner}, against the same
+ * table in the same trust order, so a link that resolves nothing changes nothing — and a row for a different
+ * holder that happens to be in the same page is left exactly as it stood. Passing the freshly linked subject
+ * straight to the writer would be the shortcut, and it would project one customer's purchase onto another's
+ * account the first time two orphans shared a page.
+ *
+ * **Per row, and both halves per row.** The subject is resolved inside the loop, from the row's own hints, so
+ * a page of orphans is a page of independent questions rather than one answer applied to all of them. There
+ * is no subject computed before the loop for the same reason there is no `subjectType` taken from config: a
+ * kind that outlived the row it came from is how an organization's purchase lands on a user with the same id.
+ */
+
+/**
+ * How many orphaned rows one link may repair.
+ *
+ * A bound rather than "all of them", because this runs inside a webhook handler that a store is timing. A
+ * link arriving after a long outage could face hundreds of orphans, and a handler that walks them all is a
+ * handler the store times out and redelivers — which produces the same walk again, from the top.
+ *
+ * Small enough to be invisible in a request, and the leftovers are not lost: they still carry the marker, and
+ * the next link on that rail takes the next page. The rows are taken oldest first so the queue drains in
+ * order rather than starving its own tail.
+ */
+export const ORPHAN_REPAIR_LIMIT = 25;
+
+/** What the repair needs to project what it finds: the catalog, the environment it is writing for, the clock. */
+export interface RepairOrphansOptions {
+  /** The resolved catalog, handed to the writer unchanged. */
+  config: PaymentsConfig;
+  /** This deployment's store environment. The writer refuses a row that disagrees. */
+  environment: PurchaseEnvironment;
+  /** The clock. */
+  now: Date;
+  /**
+   * Re-read one recorded payload — {@link PaymentsRailProvider.replay}, bound to its rail.
+   *
+   * Passed in rather than resolved here because building a rail provider needs credentials, and this module
+   * has no business reading a secret. A caller whose rail cannot replay passes nothing and the repair is a
+   * no-op, which is the honest answer for it.
+   */
+  replay?: (payload: Record<string, unknown>) => Promise<VerifiedNotification | undefined>;
+  /** What to do with each repaired projection — the same fulfillment the delivery would have performed. */
+  fulfill?: (projection: PurchaseProjection) => Promise<void>;
+  /** How many rows to take. Defaults to {@link ORPHAN_REPAIR_LIMIT}. */
+  limit?: number;
+}
+
+/** What one repair pass did. Returned so a caller can log it and a test can assert on it. */
+export interface RepairedOrphans {
+  /** Rows examined — orphan-marked and unfinished, on this rail. */
+  readonly examined: number;
+  /** Rows whose purchase is now projected and whose event is now finished. */
+  readonly projected: readonly string[];
+  /** Rows still waiting: no owner yet, no replay, or nothing to project. Left exactly as they stood. */
+  readonly waiting: number;
+}
+
+/**
+ * Project the orphaned events on one rail that an owner can now be resolved for.
+ *
+ * Called after a link is written, on every path that writes one. Never throws for a row it cannot repair: a
+ * replay that cannot read an old payload, an owner that still does not resolve, a projection the catalog
+ * refuses — each leaves that row untouched and the pass moves to the next. The caller is a webhook handler
+ * answering a store, and a repair failing must not turn a delivery that succeeded into a non-2xx.
+ *
+ * A row it *does* project is finished the same way the original delivery would have finished it, so the
+ * store's own redelivery of it is a duplicate from then on.
+ */
+export async function repairOrphanedEvents(
+  d1: D1Database,
+  rail: PaymentsRail,
+  options: RepairOrphansOptions,
+): Promise<RepairedOrphans> {
+  const projected: string[] = [];
+  let examined = 0;
+  let waiting = 0;
+
+  if (options.replay === undefined) return { examined, projected, waiting };
+
+  const db = paymentsDatabase(d1);
+  const rows = await db
+    .selectFrom(PAYMENTS_WEBHOOK_EVENTS_TABLE)
+    .selectAll()
+    .where("rail", "=", rail)
+    // Unfinished. The marker check below is the narrow half, but this one is what a `processedAt` index can
+    // serve, and it keeps a store's whole finished history out of the scan.
+    .where("processedAt", "is", null)
+    .where("error", "like", `${WEBHOOK_EVENT_ORPHANED}%`)
+    // Oldest first: the queue drains in the order the purchases were made, not the order D1 happens to scan.
+    .orderBy("receivedAt")
+    .limit(options.limit ?? ORPHAN_REPAIR_LIMIT)
+    .execute();
+
+  for (const stored of rows) {
+    const row = PaymentsWebhookEvent.parse(stored);
+    // The predicate again, on the decoded row. The `where` above is the query this scan can afford; this is
+    // the question being asked. They agree today, and a reader must not have to prove that to trust the set.
+    if (!webhookEventAwaitsOwner(stored)) continue;
+    examined += 1;
+
+    const notification = await options.replay(row.payload);
+    if (notification?.event === undefined || notification.event === null) {
+      waiting += 1;
+      continue;
+    }
+
+    // This row's own subject, resolved from this row's own hints. Both halves come back together or neither
+    // does — `projection/owner.ts` reads them from one row for exactly this reason.
+    const subject = await resolveNotificationOwner(db, rail, {
+      providerAccountId: notification.providerAccountId,
+      providerTransactionId: notification.event.providerTransactionId,
+      originalTransactionId: notification.event.originalTransactionId,
+    });
+    if (subject === undefined) {
+      // Still nobody. The link that just landed was somebody else's, and this row waits for its own.
+      waiting += 1;
+      continue;
+    }
+
+    let projection: PurchaseProjection;
+    try {
+      projection = await projectPurchase(
+        d1,
+        { ...notification.event, ...subject },
+        { config: options.config, environment: options.environment, now: options.now },
+      );
+      if (notification.stateEvent) {
+        await projectPurchase(
+          d1,
+          { ...notification.stateEvent, ...subject },
+          { config: options.config, environment: options.environment, now: options.now },
+        );
+      }
+      await options.fulfill?.(projection);
+    } catch {
+      // An unmapped SKU, a sandbox row in a production database, a ledger that would not assemble. None of
+      // them is this link's fault and none is repaired by trying again here, so the row keeps its marker and
+      // its reason and this pass moves on. The delivery that called us still succeeds.
+      waiting += 1;
+      continue;
+    }
+
+    await finish(d1, row.id, options.now);
+    projected.push(row.providerEventId);
+  }
+
+  return { examined, projected, waiting };
+}
+
+/**
+ * Mark a repaired row finished, and clear the reason it carried.
+ *
+ * `processedAt` because it now genuinely is finished — the purchase is projected, and a redelivery has
+ * nothing left to add. The `error` goes with it: it said "no subject could be resolved", which stopped
+ * being true, and a stale reason beside a finished timestamp is the contradiction `data/webhookEvent.ts`
+ * refuses to store.
+ *
+ * `abandonedAt` is left exactly where it was. A sweep having given up on this row is a fact about that pass
+ * and a record of how close the purchase came to being lost; `finished` already wins over it by construction.
+ */
+async function finish(d1: D1Database, id: string, now: Date): Promise<void> {
+  await withD1Retry(() =>
+    paymentsDatabase(d1)
+      .updateTable(PAYMENTS_WEBHOOK_EVENTS_TABLE)
+      // biome-ignore lint/suspicious/noExplicitAny: encoded column values, not the app shape.
+      .set({ processedAt: now.getTime(), error: null } as any)
+      .where("id", "=", id)
+      .execute(),
+  );
+}

package/src/projection/owner.ts

@@ -0,0 +1,247 @@
+// 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 { PaymentsProviderAccount } from "../data/providerAccount";
+import type { PaymentsRail } from "../data/rail";
+import { PaymentsSubject } from "../data/subject";
+import {
+  PAYMENTS_PROVIDER_ACCOUNTS_TABLE,
+  PAYMENTS_PURCHASES_TABLE,
+  type PaymentsDatabase,
+  paymentsDatabase,
+} from "../data/tables";
+
+/**
+ * Who a purchase belongs to — the question a webhook cannot answer for itself.
+ *
+ * A notification arrives carrying the store's own identifiers and no Pithy identity at all. The projection
+ * writer takes an owner as an input and refuses to infer one, deliberately: a writer that could derive a
+ * holder from a payload could be talked into deriving the wrong one. So resolution happens here, once,
+ * against rows the server itself wrote.
+ *
+ * **The answer is a subject, not a user id** — the pair, and always both halves. Under organization billing
+ * the person who clicked is not the holder, and `data/subject.ts` states why an id on its own identifies
+ * nobody: nothing keeps an organization id from equalling some user's, so a resolution that returned an id
+ * alone would let one collect the other's renewals. Every lookup below therefore selects both columns **from
+ * the same row**, and the pair is never assembled from two places — not a kind from config beside an id from
+ * a row, not a kind from one table beside an id from another.
+ *
+ * **Three sources, and the order they are consulted in is a trust order.**
+ *
+ * 1. **The same transaction, already projected.** A redelivery of a notification we handled is never
+ *    orphaned, whatever the app set.
+ * 2. **The transaction that started the subscription.** This is what makes renewals work for an app that set
+ *    no account token at all: the first purchase was submitted by its owner, and every renewal chains back to
+ *    it through `originalTransactionId`.
+ * 3. **The account link** — `pithy_payments_provider_accounts`, written when the purchase was submitted,
+ *    through the hook every store provides: Apple's `appAccountToken`, Google's `obfuscatedAccountId`,
+ *    Stripe's `client_reference_id`.
+ *
+ * The first two are facts this server established; the third is a value a client chose. That is the whole
+ * ordering, and {@link resolveNotificationOwner} spells out the attack it prevents.
+ *
+ * When nothing answers, the answer is undefined — an orphan. The notification is still recorded, so it is
+ * visible and replayable once a link arrives. Guessing would be the alternative, and a guess here grants
+ * somebody else's subscription.
+ */
+
+/** What a notification offers as identification. Every field is optional; a rail supplies what it carries. */
+export interface OwnerHints {
+  /** The store's account identifier, if the purchase carried one. */
+  providerAccountId?: string | null;
+  /** This transaction's own id. Matches a purchase already projected. */
+  providerTransactionId?: string | null;
+  /** The transaction that started the subscription. Matches the purchase a renewal descends from. */
+  originalTransactionId?: string | null;
+}
+
+/** Options for the account link. The clock is injected so a link's `createdAt` is deterministic in tests. */
+export interface LinkProviderAccountOptions {
+  /** The clock. */
+  now?: Date;
+  /** The id minter. */
+  newId?: () => string;
+}
+
+/**
+ * The pair, read off the one row it was found in.
+ *
+ * A function rather than an object literal at each lookup, because the literal is exactly where the two
+ * halves could come from two places: a `subjectType` taken from config beside a `subjectId` taken from a row
+ * typechecks perfectly and names a holder nobody meant. Taking a row and reading both columns off it leaves
+ * nowhere to pass a mismatched pair. The parse is the D1 boundary check every other decoded row in this
+ * package gets, over a value the table's own CHECK constraint already closes.
+ */
+function subjectOf(row: { subjectType: string; subjectId: string }): PaymentsSubject {
+  return PaymentsSubject.parse(row);
+}
+
+/**
+ * Bind a store account identifier to a subject, and return the subject it is bound to.
+ *
+ * Idempotent, and **never rebinding**: `UNIQUE (rail, providerAccountId)` plus `ON CONFLICT DO NOTHING`
+ * means the first binding wins and a later one is a no-op. That matters because a client re-submits its
+ * receipt on every launch, and because rebinding would let a second holder capture the first one's renewal
+ * notifications simply by submitting a receipt from the same store account.
+ *
+ * **The key is deliberately not widened by the subject**, and the kind is no escape from it either: an
+ * organization whose id equals a user's does not get its own link, because `organization:acme` and
+ * `user:acme` would still be two rows competing for one `(rail, providerAccountId)`. One provider identity
+ * resolves to one holder, and which holder is decided once.
+ *
+ * The returned subject is the one actually bound, which is not always the one passed in. A caller that cares
+ * about the difference compares them with `sameSubject`; the purchase-level owner check in the writer is
+ * what refuses a transaction outright.
+ *
+ * **A link is also a repair signal, and this function does not act on it.** Purchases that arrived before
+ * their owner was knowable are sitting in `pithy_payments_webhook_events` waiting for exactly this row —
+ * see `projection/orphans.ts`, and #341 for what it cost while nothing looked. Acting on it here would mean
+ * this function taking a catalog, an environment and a rail able to replay its own payloads, which is three
+ * arguments a link has no business knowing about; so every call site calls `repairOrphanedEvents` beside
+ * this one instead. **A fourth call site owes the same call.**
+ */
+export async function linkProviderAccount(
+  d1: D1Database,
+  rail: PaymentsRail,
+  providerAccountId: string,
+  subject: PaymentsSubject,
+  options: LinkProviderAccountOptions = {},
+): Promise<PaymentsSubject> {
+  const db = paymentsDatabase(d1);
+  const row = PaymentsProviderAccount.encode({
+    id: options.newId?.() ?? crypto.randomUUID(),
+    rail,
+    providerAccountId,
+    subjectType: subject.subjectType,
+    subjectId: subject.subjectId,
+    createdAt: options.now ?? new Date(),
+  });
+
+  await withD1Retry(() =>
+    db
+      .insertInto(PAYMENTS_PROVIDER_ACCOUNTS_TABLE)
+      // biome-ignore lint/suspicious/noExplicitAny: an encoded row; Kysely's insert type derives from z.input.
+      .values(row as any)
+      .onConflict((oc) => oc.columns(["rail", "providerAccountId"]).doNothing())
+      .execute(),
+  );
+
+  const bound = await db
+    .selectFrom(PAYMENTS_PROVIDER_ACCOUNTS_TABLE)
+    .select(["subjectType", "subjectId"])
+    .where("rail", "=", rail)
+    .where("providerAccountId", "=", providerAccountId)
+    .executeTakeFirst();
+  // Absent only if the row vanished between the insert and this read, which nothing in this package does.
+  return bound === undefined ? subject : subjectOf(bound);
+}
+
+/**
+ * The store account this subject already has on this rail, or undefined.
+ *
+ * The reverse of {@link resolveNotificationOwner}, and it exists for the two hosted Stripe flows. `/checkout`
+ * passes it so a returning buyer keeps one Stripe customer instead of minting a new one per purchase — without
+ * that, the billing portal their first purchase created would not show their second. `/portal` needs it because
+ * a portal session is *about* a customer, and taking that from a request would let any caller open somebody
+ * else's billing.
+ *
+ * **Both halves filter, and that is what the portal rests on.** An id-only filter would hand `organization:acme`
+ * the portal session belonging to `user:acme` — a live billing session over somebody else's card, invoices and
+ * cancellation, reachable by anybody who can act for a subject whose id collides.
+ *
+ * The oldest link wins. A subject with two accounts on one rail is already an anomaly — the link is never
+ * rebound, so it takes two purchases made under two store accounts — and the first is the one every earlier
+ * purchase is filed under.
+ */
+export async function providerAccountForSubject(
+  db: PaymentsDatabase,
+  rail: PaymentsRail,
+  subject: PaymentsSubject,
+): Promise<string | undefined> {
+  const row = await db
+    .selectFrom(PAYMENTS_PROVIDER_ACCOUNTS_TABLE)
+    .select("providerAccountId")
+    .where("rail", "=", rail)
+    .where("subjectType", "=", subject.subjectType)
+    .where("subjectId", "=", subject.subjectId)
+    .orderBy("createdAt")
+    .executeTakeFirst();
+  return row?.providerAccountId;
+}
+
+/**
+ * The subject a notification belongs to, or undefined when nothing identifies one.
+ *
+ * **The order is a trust order, not a convenience order.** The two transaction lookups ask a question this
+ * server already answered: who owned the purchase we projected for an authenticated caller. The account link
+ * asks a question the *app* answered, because on Apple and Google `providerAccountId` is `appAccountToken` /
+ * `obfuscatedAccountId` — values a client puts in a purchase and may put anything in. `contract.ts` says as
+ * much about `accountReference`, and the same reasoning applies one hop further out: a value a client chose
+ * must never outrank a fact this server established.
+ *
+ * Consulting the link first is a cross-subject entitlement hijack. An attacker who can guess a victim's token
+ * value makes one purchase carrying it, submits it as themselves, and owns the link; the victim's own
+ * notifications then resolve to the attacker, and because a renewal carries a fresh transaction id the
+ * writer's owner check never fires. Last is where a client's claim belongs.
+ *
+ * It still belongs *somewhere*: on Stripe the link is written from `client_reference_id`, which `/checkout`
+ * set from the authenticated buyer, so it is server-established and it is the only thing that can attribute
+ * a first invoice. Hence last rather than gone.
+ *
+ * Each source answers with the whole pair or with nothing. A source that matched a row contributes that
+ * row's `subjectType` **and** its `subjectId`, so a purchase filed against an organization can never resolve
+ * to the user with the same id — see {@link subjectOf}.
+ */
+export async function resolveNotificationOwner(
+  db: PaymentsDatabase,
+  rail: PaymentsRail,
+  hints: OwnerHints,
+): Promise<PaymentsSubject | undefined> {
+  // A falsy hint is skipped rather than passed to the query: `where(column, "=", undefined)` in Kysely
+  // compares against null, which on a nullable column matches every unrelated one-off purchase.
+  if (hints.providerTransactionId) {
+    const owner = await db
+      .selectFrom(PAYMENTS_PURCHASES_TABLE)
+      .select(["subjectType", "subjectId"])
+      .where("rail", "=", rail)
+      .where("providerTransactionId", "=", hints.providerTransactionId)
+      .executeTakeFirst();
+    if (owner) return subjectOf(owner);
+  }
+
+  if (hints.originalTransactionId) {
+    // The whole subscription family, matched on either column. A renewal's `originalTransactionId` names the
+    // *first transaction's own id*, so the purchase that started the subscription is found on
+    // `providerTransactionId` while its siblings are found on `originalTransactionId`. Matching only the
+    // latter would miss the one row that is guaranteed to exist — the one somebody actually bought.
+    const owner = await db
+      .selectFrom(PAYMENTS_PURCHASES_TABLE)
+      .select(["subjectType", "subjectId"])
+      .where("rail", "=", rail)
+      .where((eb) =>
+        eb.or([
+          eb("providerTransactionId", "=", hints.originalTransactionId as string),
+          eb("originalTransactionId", "=", hints.originalTransactionId as string),
+        ]),
+      )
+      // Oldest first: the transaction that started the subscription is the one whose owner is least disputable.
+      .orderBy("purchasedAt")
+      .executeTakeFirst();
+    if (owner) return subjectOf(owner);
+  }
+
+  // Last, and only when nothing this server established answers. See the trust order above.
+  if (hints.providerAccountId) {
+    const linked = await db
+      .selectFrom(PAYMENTS_PROVIDER_ACCOUNTS_TABLE)
+      .select(["subjectType", "subjectId"])
+      .where("rail", "=", rail)
+      .where("providerAccountId", "=", hints.providerAccountId)
+      .executeTakeFirst();
+    if (linked) return subjectOf(linked);
+  }
+
+  return undefined;
+}

package/src/projection/resolve.ts

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Entitlement } from "@pithy-sh/core/src/entitlement/entitlement";
+import { PaymentsEntitlement } from "../data/entitlement";
+import type { PaymentsSubject } from "../data/subject";
+import { PAYMENTS_ENTITLEMENTS_TABLE, type PaymentsDatabase } from "../data/tables";
+
+/**
+ * The read path: every entitlement a subject holds, as the core seam's shape.
+ *
+ * **A read never writes.** Repairing a stale row is the reconciliation Workflow's job, which is what keeps
+ * this the hot path it needs to be — one indexed lookup per request, no KV cache, no token claim, so a
+ * revocation is immediate and the truth has one home (issue #79 decision 5).
+ *
+ * The recheck is why the read exists as its own function rather than a `selectAll`. A subscription can lapse
+ * with **no notification arriving at all** — the store simply stops renewing, and nothing tells us. So the
+ * stored `active` flag is an optimization and `expiresAt` is the truth, and the read applies the timestamp
+ * itself rather than trusting the flag. A row that says `active = 1` with an expiry in the past does not
+ * grant, and it does not need a write to stop granting.
+ *
+ * Lapsed rows are returned rather than filtered out, with `active` false. A paywall wants to say "your Pro
+ * ended on the 4th", and it can only do that if the row and its date survive the read.
+ *
+ * **Both halves of the subject are in the `where`, and neither is decorative.** Nothing in the kit makes the
+ * user id space and the adopter's organization id space disjoint — they are minted by different things, and
+ * neither knows the other exists — so a read filtered on the id alone would hand `user:acme` whatever
+ * `organization:acme` bought. The pair arrives as one object for exactly that reason: it is read from and
+ * compared as a unit, and no call site here pairs a kind from config with an id from somewhere else.
+ *
+ * Both columns lead `UNIQUE (subjectType, subjectId, entitlement)`, so this stays the one indexed lookup it
+ * has to be — the index answers the whole predicate rather than filtering a kind out afterwards.
+ */
+export async function resolveEntitlements(
+  db: PaymentsDatabase,
+  subject: PaymentsSubject,
+  now: Date,
+): Promise<readonly Entitlement[]> {
+  const rows = await db
+    .selectFrom(PAYMENTS_ENTITLEMENTS_TABLE)
+    .selectAll()
+    .where("subjectType", "=", subject.subjectType)
+    .where("subjectId", "=", subject.subjectId)
+    .orderBy("entitlement")
+    .execute();
+
+  return rows.map((row) => {
+    const entitlement = PaymentsEntitlement.parse(row);
+    const lapsed = entitlement.expiresAt !== null && entitlement.expiresAt.getTime() <= now.getTime();
+    return {
+      key: entitlement.entitlement,
+      active: entitlement.active && !lapsed,
+      expiresAt: entitlement.expiresAt,
+      source: entitlement.sourcePurchaseId,
+    };
+  });
+}