@pithy-sh/payments 0.1.0

package/src/grants/apply.ts

@@ -0,0 +1,207 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { type AuditEmit, noopEmit } from "@pithy-sh/core/src/audit/recorder";
+import { PaymentsAuditActions } from "../audit/actions";
+import type { PaymentsConfig, PaymentsLedgerGrant } from "../config/config";
+import type { PaymentsPurchase } from "../data/purchase";
+import type { PurchaseStatus } from "../data/status";
+import type { PurchaseProjection } from "../projection/writer";
+import { type ClawbackOutcome, clawbackGrants } from "./clawback";
+import { ledgerAccountId, openPaymentsLedger, type PaymentsLedger } from "./ledgerSeam";
+
+/**
+ * Fulfillment: turning a projected purchase into the balance a `grants` clause promised.
+ *
+ * This is deliberately **not** in the projection writer. The writer stays pure D1 so its tests resolve no
+ * optional package, and the credit is a separate step its caller runs on what it returned — a route, or any
+ * other caller holding a projection. Nothing is lost by the separation, because the credit's idempotency has
+ * never rested on call ordering: it rests on the ledger's `UNIQUE (ref)`.
+ *
+ * ## The ref, which is the whole design
+ *
+ * `payments:grant:<purchaseId>:<currency>`. Three properties, each load-bearing:
+ *
+ * - **Per credit, never per purchase.** A duplicate `ref` aborts the ledger's batch, and the ledger reports
+ *   that abort as *success* with the current balance — a replay must be a no-op, so it cannot distinguish
+ *   itself from one. So a purchase crediting two currencies under one ref would credit the first and silently
+ *   drop the second, with nothing anywhere to read. The currency is in the ref for that reason alone.
+ * - **A pure function of durable identifiers.** Never `crypto.randomUUID()`, never `Date.now()`. `purchaseId`
+ *   is minted once, at first projection, and every later write keeps it — so a retry three days later derives
+ *   the identical ref and the ledger recognizes the replay. A ref that varied would double-credit.
+ * - **Per billing period on a subscription, for free.** Each renewal is a distinct provider transaction on all
+ *   three rails, so it is a distinct purchase row with a distinct id, so it is a distinct ref. The same guard
+ *   that makes a redelivery a no-op lets next month's renewal through, with no period arithmetic anywhere.
+ *
+ * ## When a credit fires
+ *
+ * Whenever the charge stands — regardless of the projection's `outcome`. Applying a grant for an `ignored`
+ * replay is not waste, it is the repair: if a previous delivery projected the purchase and then failed before
+ * the ledger write, the redelivery is the only thing that will ever fix it, and the stable ref makes trying
+ * free. The one thing checked is whether the money is actually with us; see {@link UNPAID_STATUSES}.
+ *
+ * A failure that is not the ledger's own refusal propagates. `openLedger` classifies aborts by regexing the
+ * error message, so a transient D1 fault arrives unwrapped and un-typed — treating it as "credited nothing"
+ * would drop a purchase's currency permanently, where letting it raise leaves the retry to settle it.
+ */
+
+/**
+ * The statuses in which this charge's money is not with us: a payment still outstanding, one that never
+ * arrived at all, or one that was taken back. Everything else — `active`, `canceled`, `expired`, `paused` —
+ * describes a period that was paid for, whatever has since become of the subscription.
+ *
+ * `expired` is the member most easily got wrong in the other direction. It says a period ended, not that its
+ * invoice failed; refusing to credit on it would lose a coin pack whose only delivery arrived late. Which is
+ * precisely why a termination that took no money needs its own status: **`never_paid`** is here, and reading
+ * a never-paid ending as `expired` credited a 100-coin pack for a bank debit that bounced — with no clawback
+ * ever to follow it, because nothing was ever charged to reverse. See `data/status.ts`.
+ */
+const UNPAID_STATUSES: ReadonlySet<PurchaseStatus> = new Set<PurchaseStatus>([
+  "in_grace",
+  "on_hold",
+  "never_paid",
+  "refunded",
+  "revoked",
+]);
+
+/** One balance credit a purchase produced, with the ref that makes it happen exactly once. */
+export interface AppliedGrant {
+  /** The ledger currency credited. */
+  currency: string;
+  /** How much, as an integer in the currency's minor unit. */
+  amount: number;
+  /** The idempotency key the ledger recorded it under. */
+  ref: string;
+}
+
+/** What one fulfillment did in both directions. Empty on both sides for a catalog with no `grants` clause. */
+export interface FulfillmentReport {
+  /** The credits applied, in catalog order. */
+  granted: readonly AppliedGrant[];
+  /** The refund reversals attempted, whether or not the balance covered them. */
+  clawedBack: readonly ClawbackOutcome[];
+}
+
+/** What the grant modules need beyond the projection: the catalog the `grants` clause lives in. */
+export interface GrantOptions {
+  /** The resolved catalog. */
+  config: PaymentsConfig;
+}
+
+/** What {@link fulfillPurchase} needs: the catalog, the audit seam, and optionally a ledger to use. */
+export interface FulfillPurchaseOptions extends GrantOptions {
+  /** The audit seam. Defaults to core's no-op, so a caller with no recorder composed needs no branch. */
+  emit?: AuditEmit;
+  /** An already-open ledger. Absent in production — the guarded import supplies one only when it is needed. */
+  ledger?: PaymentsLedger;
+  /** The clock the ledger stamps its rows with. Injected so a fulfillment is deterministic under test. */
+  now?: () => number;
+}
+
+/**
+ * The idempotency key for one credit. A pure function of two durable identifiers, and the only place the
+ * shape is written — a caller reconciling a ledger row back to a purchase derives it the same way.
+ */
+export function grantRef(purchaseId: string, currency: string): string {
+  return `payments:grant:${purchaseId}:${currency}`;
+}
+
+/** The ledger grant this purchase's catalog product declares, or undefined for the products that declare none. */
+export function ledgerGrantFor(config: PaymentsConfig, productId: string): PaymentsLedgerGrant | undefined {
+  return config.products[productId]?.grants?.ledger;
+}
+
+/**
+ * Whether this purchase's charge stands, and so whether what it bought should be credited.
+ *
+ * **A `state` row is never paid, whatever its status says**, and the check is on `role` before it is on
+ * `status` because the two answer different questions. `status` asks what became of a charge; a
+ * subscription's standing is not a charge, so the question does not apply to it and an honest `active`
+ * would otherwise read as money that arrived. Lemon Squeezy is the only rail that writes such a row —
+ * its subscription webhooks carry no charge at all — and without this line every LS subscriber would be
+ * credited once for the subscription on top of once per invoice. See {@link PurchaseRole}.
+ */
+export function purchaseIsPaid(purchase: Pick<PaymentsPurchase, "status" | "role">): boolean {
+  if (purchase.role === "state") return false;
+  return !UNPAID_STATUSES.has(purchase.status);
+}
+
+/**
+ * Credit what a fulfilled purchase's `grants` clause promised. Returns what was asked of the ledger, which is
+ * not the same as what changed: a replay asks for the identical credit and the ledger no-ops it.
+ */
+export async function applyGrants(
+  ledger: PaymentsLedger,
+  projection: PurchaseProjection,
+  options: GrantOptions,
+): Promise<AppliedGrant[]> {
+  const { purchase } = projection;
+  const grant = ledgerGrantFor(options.config, purchase.productId);
+  if (grant === undefined || !purchaseIsPaid(purchase)) return [];
+
+  const ref = grantRef(purchase.id, grant.currency);
+  // The account is derived from the purchase's subject pair, never from its id alone — `ledgerAccountId`
+  // says why, and the clawback derives it the same way so a reversal cannot miss.
+  //
+  // Identifiers only in the memo. It lands in a queryable ledger row beside a player's balance, so it names
+  // what was bought and on which store, and never the artifact that proved it.
+  await ledger.credit(ledgerAccountId(purchase), grant.currency, grant.amount, ref, {
+    memo: `payments ${purchase.rail} ${purchase.productId}`,
+  });
+  return [{ currency: grant.currency, amount: grant.amount, ref }];
+}
+
+/**
+ * Fulfill one projected purchase in both directions: credit what it bought, and reverse what a refund took
+ * back where the catalog asks for it.
+ *
+ * The ledger is opened **lazily, and only when the catalog names a currency**. That laziness is the whole
+ * reason the optional peer stays optional: a project selling nothing but features never resolves the import,
+ * so it neither installs `@pithy-sh/ledger` nor carries it in a Worker bundle.
+ *
+ * A refused clawback is recorded here rather than thrown. It is the one fulfillment fact no other table
+ * holds — a successful credit or debit is already a ledger row, keyed by a ref that names the purchase — so
+ * the audit trail is where a shortfall becomes queryable and alertable.
+ */
+export async function fulfillPurchase(
+  d1: D1Database,
+  projection: PurchaseProjection,
+  options: FulfillPurchaseOptions,
+): Promise<FulfillmentReport> {
+  const { purchase } = projection;
+  if (ledgerGrantFor(options.config, purchase.productId) === undefined) return { granted: [], clawedBack: [] };
+
+  const ledger = options.ledger ?? (await openPaymentsLedger(d1, { now: options.now }));
+  const granted = await applyGrants(ledger, projection, options);
+  const clawedBack = await clawbackGrants(ledger, projection, options);
+
+  const emit = options.emit ?? noopEmit;
+  for (const attempt of clawedBack) {
+    if (attempt.outcome !== "refused") continue;
+    await emit({
+      action: PaymentsAuditActions.clawbackFailed,
+      outcome: "failure",
+      // Alert-worthy: the refund stands, the balance does not cover it, and only a human can decide what to
+      // do about the difference. A run of these on one product is a catalog that should not claw back at all.
+      severity: "critical",
+      actorType: "system",
+      resourceType: "purchase",
+      resourceId: purchase.id,
+      metadata: {
+        rail: purchase.rail,
+        productId: purchase.productId,
+        // Both halves, as every record of an owner carries them. An id alone would leave whoever answers the
+        // alert unable to say whether the shortfall is a person's balance or a company's.
+        subjectType: purchase.subjectType,
+        subjectId: purchase.subjectId,
+        currency: attempt.currency,
+        amount: attempt.amount,
+        ref: attempt.ref,
+        reason: attempt.error.payload.code,
+      },
+    });
+  }
+
+  return { granted, clawedBack };
+}

package/src/grants/clawback.ts

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { PurchaseStatus } from "../data/status";
+import { PaymentsClawbackFailedError } from "../error/errors";
+import type { PurchaseProjection } from "../projection/writer";
+import type { GrantOptions } from "./apply";
+import { ledgerGrantFor } from "./apply";
+import { ledgerAccountId, type PaymentsLedger } from "./ledgerSeam";
+
+/**
+ * The refund clawback: taking back what a `grants` clause credited, where — and only where — the catalog says
+ * to.
+ *
+ * **A clawback can fail, and that failure is correct behavior.** The ledger's `CHECK (balance >= 0)` refuses
+ * a debit the balance cannot cover, and a player who spent their coins before the refund arrived is exactly
+ * that case. There are only three things to do about it and two are wrong: allow a negative balance, which
+ * breaks the invariant the ledger exists to hold; write the difference off silently, which leaves nothing
+ * anywhere to read; or accept the refusal and record it. This module does the third.
+ *
+ * So the shape is: the refund is projected and audited **unconditionally** by the caller, the clawback is
+ * attempted **only** where `clawback: true`, and a refusal is returned as an outcome rather than thrown.
+ * `fulfillPurchase` turns that outcome into a `payments/clawback_failed` audit event at `critical` — a
+ * recorded, queryable, alertable state, which is what issue #79 asks for and what an exception could not be.
+ *
+ * **Off by default**, and that default is the honest one. Clawing back is the exception: the user may well
+ * have spent the currency legitimately, and a store's refund decision is not automatically a fraud finding. A
+ * project that sells hard currency and has decided otherwise says so per product, in one word.
+ */
+
+/** The statuses that mean this charge came back — the two a clawback answers. */
+const REVERSED_STATUSES: ReadonlySet<PurchaseStatus> = new Set<PurchaseStatus>(["refunded", "revoked"]);
+
+/** The ledger's own code for the refusal a clawback is expected to meet. Anything else is unknown, not short. */
+const INSUFFICIENT_FUNDS_CODE = "ledger/insufficient_funds";
+
+/**
+ * One attempted reversal. `refused` carries its payload rather than a boolean, because the shortfall has to
+ * survive as far as the audit trail with its code and its context intact.
+ */
+export type ClawbackOutcome =
+  | {
+      /** The debit applied, or was recognized as one already applied. */
+      outcome: "reversed";
+      /** The ledger currency debited. */
+      currency: string;
+      /** How much, as an integer in the currency's minor unit. */
+      amount: number;
+      /** The idempotency key the ledger recorded it under. */
+      ref: string;
+    }
+  | {
+      /** The balance could not cover it. The refund stands; the difference is a fact for a human. */
+      outcome: "refused";
+      /** The ledger currency the debit was attempted in. */
+      currency: string;
+      /** How much the reversal would have taken. */
+      amount: number;
+      /** The idempotency key the debit was attempted under. */
+      ref: string;
+      /** The refusal, as the payload the audit trail records. */
+      error: PaymentsClawbackFailedError;
+    };
+
+/**
+ * The idempotency key for one reversal. Distinct from the grant's by its verb: sharing the grant's ref would
+ * make the debit look like a replayed credit, which the ledger swallows as success — so the reversal would
+ * report success and move nothing.
+ */
+export function clawbackRef(purchaseId: string, currency: string): string {
+  return `payments:clawback:${purchaseId}:${currency}`;
+}
+
+/**
+ * Reverse what a refunded purchase credited, if the catalog opted in.
+ *
+ * Runs on every delivery of the refund, not only the first: the debit is idempotent on its ref, so a
+ * redelivery is a no-op and a delivery that arrived after an earlier attempt failed is the repair.
+ */
+export async function clawbackGrants(
+  ledger: PaymentsLedger,
+  projection: PurchaseProjection,
+  options: GrantOptions,
+): Promise<ClawbackOutcome[]> {
+  const { purchase } = projection;
+  const product = options.config.products[purchase.productId];
+  const grant = ledgerGrantFor(options.config, purchase.productId);
+  // `role` first, and for the mirror of the reason `purchaseIsPaid` checks it first: a `state` row records a
+  // subscription's standing rather than a charge, so it never credited and there is nothing to take back.
+  // Debiting one would take currency the buyer was never given — the same row's `revoked` status is what a
+  // refund correctly writes there, so without this line every clawback-enabled Lemon Squeezy product would
+  // debit twice for one refund.
+  if (purchase.role === "state") return [];
+  if (grant === undefined || product?.clawback !== true || !REVERSED_STATUSES.has(purchase.status)) return [];
+
+  const ref = clawbackRef(purchase.id, grant.currency);
+  // The same derivation the credit used, from the same helper. This is the invariant the helper exists for:
+  // a reversal that composed the account any other way would debit an account nothing was ever credited to,
+  // and the ledger would answer that with `insufficient_funds` — a refusal indistinguishable from a spent
+  // balance, so the shortfall would be recorded and nobody would learn the reversal had missed.
+  const accountId = ledgerAccountId(purchase);
+  try {
+    await ledger.debit(accountId, grant.currency, grant.amount, ref, {
+      memo: `payments refund ${purchase.rail} ${purchase.productId}`,
+    });
+  } catch (cause) {
+    // Only the ledger's own solvency refusal is an outcome. A transient D1 fault reaches here unwrapped —
+    // `openLedger` classifies aborts by regexing the message — and recording that as "the balance was short"
+    // would assert something we do not know. It propagates, and the stable ref settles it on the retry.
+    if (!(cause instanceof PithyError) || cause.payload.code !== INSUFFICIENT_FUNDS_CODE) throw cause;
+    return [
+      {
+        outcome: "refused",
+        currency: grant.currency,
+        amount: grant.amount,
+        ref,
+        error: new PaymentsClawbackFailedError(
+          {
+            detail: `Reversing ${grant.amount} ${grant.currency} for ${accountId} after the refund of ${purchase.rail} transaction ${purchase.providerTransactionId} exceeds their available balance.`,
+          },
+          { cause },
+        ),
+      },
+    ];
+  }
+  return [{ outcome: "reversed", currency: grant.currency, amount: grant.amount, ref }];
+}

package/src/grants/ledgerSeam.ts

@@ -0,0 +1,141 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { encodeSubjectReference, type PaymentsSubject } from "../data/subject";
+
+/**
+ * The single point of contact between `@pithy-sh/payments` and `@pithy-sh/ledger`.
+ *
+ * The ledger is an **optional peer**: most catalogs sell features, not currency, and a project that never
+ * declares a `grants` clause must neither install the package nor pay for it in its Worker bundle. So the
+ * import is dynamic and it lives in exactly one file — grep `@pithy-sh/ledger` in this package and you find
+ * this line and nothing else. Everything downstream depends on {@link PaymentsLedger}, a structural
+ * two-method view, which is also what keeps the grant modules testable without resolving an optional package.
+ *
+ * **An absent ledger is an error, never a skip.** A catalog with a `grants` clause has told us a purchase
+ * credits a balance; quietly not crediting it is a support ticket that arrives weeks later as "I paid and got
+ * no coins". The normal place this is caught is far earlier — `payments()`'s `compose` hook refuses at
+ * assembly when a `grants` product is composed without the ledger, so a deploy fails rather than a purchase.
+ * This throw is the backstop for a caller that reached fulfillment some other way, and it names the fix.
+ */
+
+/**
+ * The ledger operations payments performs: one to fulfill a purchase, one to reverse it.
+ *
+ * A structural subset rather than `@pithy-sh/ledger`'s own `Ledger`, because a type imported from an optional
+ * package would put that package on the typecheck path of every module that touches fulfillment. Holds,
+ * captures, and transfers are absent because a purchase is not a wager — money arrives from a store and, on a
+ * refund, leaves again.
+ *
+ * The leading parameter is `@pithy-sh/ledger`'s own `userId`, named `accountId` here because payments never
+ * hands it one — see {@link ledgerAccountId}.
+ */
+export interface PaymentsLedger {
+  /** Add funds. Idempotent on `ref`, which is `UNIQUE` across the whole ledger. */
+  credit(
+    accountId: string,
+    currency: string,
+    amount: number,
+    ref: string,
+    options?: { memo?: string },
+  ): Promise<unknown>;
+  /** Remove funds. Refuses with `ledger/insufficient_funds` rather than letting a balance go negative. */
+  debit(
+    accountId: string,
+    currency: string,
+    amount: number,
+    ref: string,
+    options?: { memo?: string },
+  ): Promise<unknown>;
+}
+
+/**
+ * The ledger account a subject's balance lives in — **the pair, encoded, and the only derivation of it**.
+ *
+ * `@pithy-sh/ledger` keys an account on `(userId, currency)`: one flat id namespace, with no column saying
+ * what kind of thing the id names. Nothing in the kit keeps a user id and an organization id disjoint — they
+ * are minted by different systems, and under `billingSubject: "organization"` the id belongs to a membership
+ * model this package knows nothing about. So handing the ledger a bare `subjectId` would let an organization
+ * called `acme` and a user called `acme` share one balance: coins the company bought spendable by the person,
+ * and a refund of either debiting whatever the other had left.
+ *
+ * **`@pithy-sh/ledger` is a per-user model, deliberately**, and this function's whole job is to respect that.
+ * It keys an account `(userId, currency)`, and every route it serves addresses a user: the authenticated
+ * balance read, the `:userId` segment on its management routes, its own seeds. So a user's ledger account id
+ * **is** their user id — the identity on `subjectId`, nothing composed.
+ *
+ * It briefly encoded both halves, and that was a bug rather than a stylistic choice: a grant credited to
+ * `user:ada` landed in an account nothing reads. The player's balance stayed empty, the grant was invisible
+ * from both sides, and no test in either package could see it, because each package was internally
+ * consistent while the two disagreed.
+ *
+ * **An organization never reaches here.** `checkLedgerGrants` in `capability.ts` refuses a catalog carrying a
+ * `grants.ledger` clause under `billingSubject: "organization"`, at assembly — there is no account in a
+ * per-user ledger for a company's credit to land in, and inventing one would write a non-user into a column
+ * that means user. The throw below is the backstop for a path that composition already closed.
+ *
+ * **One derivation, called by `apply.ts` and `clawback.ts` alike.** A credit and its clawback must address the
+ * identical account or the reversal misses, silently, leaving a refunded buyer holding the currency. Keeping
+ * that in one function makes it a property of the code rather than of two edits staying in step.
+ */
+export function ledgerAccountId(subject: PaymentsSubject): string {
+  if (subject.subjectType !== "user") {
+    // Unreachable through composition: `checkLedgerGrants` refuses a catalog with a `grants.ledger` clause
+    // under organization billing, at assembly. Thrown rather than encoded anyway, because the alternative is
+    // a row in `pithy_ledger_accounts` whose `userId` is not a user — invisible to every route the ledger
+    // serves, and impossible to tell from a balance nobody funded.
+    throw new InternalError({
+      message: "A balance cannot be credited to an organization.",
+      action: 'Set `billingSubject: "user"`, or drop the `grants` clause from the products that credit one.',
+      detail: `@pithy-sh/ledger keys every account on a user id. Refused an account for ${encodeSubjectReference(subject)}.`,
+    });
+  }
+  return subject.subjectId;
+}
+
+/** How the ledger module is reached. Injectable so the absent-package path is a test rather than a hope. */
+export type PaymentsLedgerLoader = () => Promise<{
+  openLedger: (d1: D1Database, now?: () => number) => PaymentsLedger;
+}>;
+
+/** The real loader — the only `@pithy-sh/ledger` import in the package. */
+const loadLedgerModule: PaymentsLedgerLoader = () => import("@pithy-sh/ledger/src/ledger");
+
+/** What {@link openPaymentsLedger} accepts beyond the binding. */
+export interface OpenPaymentsLedgerOptions {
+  /** Override the module loader. Tests only; production always resolves the real package. */
+  load?: PaymentsLedgerLoader;
+  /** The clock the ledger stamps its rows with. Injected so a fulfillment is deterministic under test. */
+  now?: () => number;
+}
+
+/**
+ * Open the ledger against the app database, or explain what is missing.
+ *
+ * The ledger's tables live in the same D1 as payments' own — both capabilities bind `DB` — so there is no
+ * second database to reach and no configuration to resolve. That is also why the two write independently and
+ * a credit is idempotent on its `ref` rather than on being in the purchase's transaction: D1 has no
+ * cross-statement transaction a caller can hold open across two packages.
+ */
+export async function openPaymentsLedger(
+  d1: D1Database,
+  options: OpenPaymentsLedgerOptions = {},
+): Promise<PaymentsLedger> {
+  const load = options.load ?? loadLedgerModule;
+  let module: { openLedger: (d1: D1Database, now?: () => number) => PaymentsLedger };
+  try {
+    module = await load();
+  } catch (cause) {
+    throw new InternalError(
+      {
+        message: "This purchase credits a balance, and the ledger is not installed.",
+        action: "Install @pithy-sh/ledger and compose ledger(...), or drop the `grants` clause from the product.",
+        detail: `Loading @pithy-sh/ledger failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+      },
+      { cause },
+    );
+  }
+  return module.openLedger(d1, options.now);
+}

package/src/http/dispatch.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import { triggerWorkflow } from "@pithy-sh/core/src/workflow/dispatch";
+import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
+import { PAYMENTS_CAPABILITY, type PaymentsReconcileParams, paymentsWorkflowRegistry } from "../workflows/specs";
+
+/**
+ * Starting a reconciliation pass from inside a Worker.
+ *
+ * **One dispatch path, three callers.** The cron in the host worker, an on-demand pass for a single holder,
+ * and anything a later surface adds all route through {@link triggerWorkflow} — so a scheduled run and a
+ * manual one validate their parameters identically, resolve the binding identically, and log an absent
+ * binding identically. Calling `env.PAYMENTS_RECONCILE.create()` directly would skip all three: a mistyped
+ * payload would surface as a failed step inside a running instance rather than at the call site, and an
+ * unprovisioned project would silently do nothing.
+ *
+ * **What is handed over is a payload, and that is why a holder is the pair.** `triggerWorkflow` parses
+ * `params` through `PaymentsReconcileParams` before it touches the binding, so a narrowing missing half its
+ * subject is refused here — where the caller is still on the stack — rather than inside an instance that
+ * would otherwise start, scan the wrong rows, and report them as the account somebody asked about. Nothing
+ * callable crosses: the instance runs with no subject seam at all, which `workflows/worker.ts` explains.
+ *
+ * **An absent binding is a logged skip, not a failure.** The job is declared `optional`, because the Workflow
+ * lives in the prebuilt reconcile worker and that worker exists only once `pithy payments provision` has run.
+ * A support request that cannot start a pass yet must not become a 500 on a route that otherwise works.
+ *
+ * It lives under `http/` because the on-demand caller is a request handler — support reconciling one holder.
+ * The host worker's cron uses the identical function, which is the point: there is one way to start this job.
+ */
+
+/** The dispatch key for the reconciliation pass. Built from core's key builder, never spelled out. */
+export const PAYMENTS_RECONCILE_KEY = workflowKey(PAYMENTS_CAPABILITY, "reconcile");
+
+/**
+ * Start a reconciliation pass.
+ *
+ * `env` is the raw Worker env rather than a typed binding, because that is what `triggerWorkflow` reads the
+ * binding off — and taking the binding itself would let a caller pass one the registry never validated.
+ */
+export async function triggerPaymentsReconcile(
+  env: Record<string, unknown>,
+  params: PaymentsReconcileParams = {},
+  log?: Logger,
+): Promise<void> {
+  await triggerWorkflow(env, paymentsWorkflowRegistry, PAYMENTS_RECONCILE_KEY, params, log);
+}

package/src/http/guards.ts

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * The payments routes' identity gates: the one middleware payments owns.
+ *
+ * **The scope constants moved to `./scopes`** (#315). A management client reads them to render what a
+ * connection may do, and it reads them in a browser — so they cannot live in a module that imports
+ * Hono middleware and `PithyHonoEnv`. The gates stayed here; the names they demand are next door, and
+ * the routes import both.
+ *
+ * ## `requireAuth` is copied, not imported
+ *
+ * These three lines are the same three `@pithy-sh/storage`, `@pithy-sh/media`, and `@pithy-sh/ledger` each
+ * carry, and the duplication is deliberate. Importing the gate from `@pithy-sh/auth` would make auth a hard
+ * dependency, and a package that *imports its authorization from another package fails open when that package
+ * is absent*. Depending on the core `AuthContext` seam instead means `c.var.auth` is simply `null` with no
+ * auth capability composed, and every route denies. Failing closed is not a side effect of the copy; it is the
+ * reason for it. So `dependsOn` stays free of auth and the manifest lists it under `optionalCapabilities`.
+ *
+ * ## The control-plane gate is core's, and payments contributes only the scope names
+ *
+ * `requireControlPlane` lives in `@pithy-sh/core/src/controlPlane/http/guard` and the two admin routes wear it
+ * directly. Payments verifies nothing itself: a management call arrives as an EdDSA-signed compact JWS on the
+ * `pithy-control-plane` header, and the seam checks the signature against a public key the **adopter**
+ * registered, the connection it addresses, that connection's environment, the token's lifetime, a digest of
+ * the body, and the token's single use — none of which a capability could re-implement per package without
+ * five subtly different answers to the same question.
+ *
+ * **This is not the opposite of the rule above; it is the same rule.** The rule is never to import
+ * authorization from a package that might be absent. `@pithy-sh/auth` is optional, so its gate is copied.
+ * `@pithy-sh/core` is a hard dependency of every capability there is, so importing its gate cannot leave a
+ * deployment without one — and when the *seam* is not composed the imported gate raises
+ * `controlplane/not_connected` rather than passing. Both halves fail closed; only the mechanism differs.
+ *
+ * **`requireAuth()` must never sit on those two routes.** A management client is not a user of the adopter's
+ * app: it holds no session, owns no user row, and the seam deliberately leaves `c.var.auth` null so that a
+ * control-plane credential cannot satisfy an ordinary `requireAuth()` anywhere in the tree. An auth gate on an
+ * admin route would therefore deny every legitimate management call, permanently, and no credential could fix
+ * it. The gate that replaced the interim one is the whole verification strategy, not half of it.
+ */
+
+/** Require an authenticated caller (the core AuthContext seam). */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}

package/src/http/manifestConfig.ts

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CapabilityManifestConfig } from "@pithy-sh/core/src/controlPlane/discovery/configuration";
+import { defineManifestConfig } from "@pithy-sh/core/src/controlPlane/discovery/configuration";
+import { PaymentsSubjectType } from "../data/subject";
+
+/**
+ * The configured fact payments states into `GET /control-plane/manifest` (#422).
+ *
+ * **A management client cannot write a grant without it.** `POST {base}/entitlements/grant` names the
+ * holder and never assumes it, which is right — the two kinds are different rows and different gates.
+ * But `PaymentsConfig.billingSubject` is required with no default, so there is nothing a client may
+ * safely assume either: guessing `user` against an organization-billed project writes a row nothing
+ * reads, the call succeeds, and the person still cannot use what somebody just gave them.
+ *
+ * Nothing else on the wire answers it. `GET {base}/admin/catalog` returns products.
+ * `PaymentsClientProjection` leaves it out deliberately and is a browser bundle besides. And
+ * `GET {base}/admin/entitlements` carries a `subjectType` per *row* — evidence about who happens to hold
+ * something, not a statement about what the project bills. An empty table says nothing, and a project
+ * that migrated has both kinds in it.
+ *
+ * **Its own module rather than a block in `scopes.ts`.** That module declares nine `ControlPlaneScope`
+ * constants and `tooling/browser-scopes/src/coverage.test.ts` holds every such module to type-only
+ * imports, so a scope name compiles in a browser program with no Workers types. This needs
+ * `defineManifestConfig` and `PaymentsSubjectType` as values, which is exactly what that gate refuses —
+ * so the two live apart rather than the gate being weakened.
+ */
+
+/** The key the fact appears under. The join key a management client reads it back by. */
+export const PAYMENTS_BILLING_SUBJECT = "billingSubject";
+
+/**
+ * What this project bills, stated for a client that has to name a holder.
+ *
+ * **Takes the resolved value rather than reading config itself**, for the same reason
+ * `paymentsAdminRoutes` takes the resolved `basePath`: a declaration built from defaults describes a
+ * Worker other than this one, and nothing downstream compares the two — a manifest that drifts from the
+ * capability is worse than no manifest, because a client believes it.
+ *
+ * `choices` is read off {@link PaymentsSubjectType} rather than retyped. A third kind of holder is a
+ * change to that enum, and reading it here is what makes the manifest learn about it in the same commit.
+ */
+export function paymentsManifestConfig(billingSubject: PaymentsSubjectType): CapabilityManifestConfig {
+  return defineManifestConfig({
+    keys: [
+      {
+        key: PAYMENTS_BILLING_SUBJECT,
+        choices: [...PaymentsSubjectType.options],
+        summary:
+          "What kind of thing holds a purchase in this project — one person, or one organization. Every entitlement this project grants names a subject of this kind, so a client must state it rather than guess it.",
+      },
+    ],
+    values: { [PAYMENTS_BILLING_SUBJECT]: billingSubject },
+  });
+}