@pithy-sh/payments 0.1.0

package/src/workflows/report.ts

@@ -0,0 +1,64 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
+import type { AuditEmit } from "@pithy-sh/core/src/audit/recorder";
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import type { LogLevel } from "@pithy-sh/core/src/logger/record";
+import type { ReconcileReport } from "./reconcile";
+
+/**
+ * What a reconcile pass says about itself: its tally, and each repair it had to make.
+ *
+ * Both are pure functions of a logger and a value, and both used to live in `worker.ts` beside the
+ * Workflow class that calls them. That module imports `cloudflare:workers`, which resolves in workerd
+ * and nowhere else, so everything it exported was reachable only from inside the Workers runtime — a
+ * Node-side caller taking one of these would have taken the whole runtime module with it and failed
+ * with `Could not load pithy.config.ts`, naming the config rather than the import.
+ *
+ * That is #172 and #180, twice, and neither was noticed until somebody accepted the offer. The shape
+ * both were fixed into is this one: a sibling module with no runtime import, which the runtime module
+ * imports from. `configEntrypoints.test.ts` states the invariant and holds every runtime module to it.
+ *
+ * Nothing here needs a binding, a request, or a Workers global, which is why its tests are node tests.
+ */
+
+/** An audit event ranks itself; this is that rank as a log level. */
+const AUDIT_LEVEL: Record<AuditSeverity, LogLevel> = { info: "info", warning: "warn", critical: "error" };
+
+/**
+ * The audit emitter a standalone host can honestly offer: a structured record per repaired purchase.
+ *
+ * A host worker composes no capabilities, so there is no `@pithy-sh/audit` recorder to reach and no
+ * `c.var.emit` to inherit — writing to `pithy_audit_events` from here would mean this package reaching into
+ * another capability's tables, which is exactly what the seam exists to prevent. A logged event is what the
+ * seam degrades to everywhere else it is uncomposed, and it keeps the drift visible where an operator reads
+ * this worker's output. The event shape is core's, so a recorder wired in later takes the identical input.
+ *
+ * It takes the run's logger rather than building its own, so every event carries the instance the repair
+ * happened in — without that, a trail read out of Workers Logs cannot be attributed to a pass.
+ */
+export function auditLogEmit(log: Logger): AuditEmit {
+  return async (event) => {
+    // The event already ranks itself, so the record takes that rank rather than inventing one — a repaired
+    // drift is emitted at `warning` because a pattern of them is a broken webhook path, and a log that
+    // flattened it to `info` would hide exactly the thing the trail exists to surface. Absent severity is
+    // the schema's own `info` default.
+    log[AUDIT_LEVEL[event.severity ?? "info"]]("audit event, no recorder composed", { ...event });
+  };
+}
+
+/**
+ * The tally, as one record. The run's only visible output: a pass whose findings are invisible is a pass
+ * nobody can tell has stopped working.
+ *
+ * Three levels, and the distinction is the point of logging it at all. `failed` counts purchases a store
+ * refused to answer for — a failure that was observed, so an operator has something to chase. `drifted`
+ * and `truncated` are the degraded-but-continuing pair: the first says webhooks are being dropped and the
+ * repair is covering for them, the second says the page cap stopped the pass with catalog left unread. A
+ * clean pass is routine, and a nightly job that reports routine at `warn` teaches an operator to ignore it.
+ */
+export function logReconcileReport(log: Logger, report: ReconcileReport): void {
+  const level: LogLevel = report.failed > 0 ? "error" : report.drifted > 0 || report.truncated ? "warn" : "info";
+  log[level]("reconcile pass complete", { ...report });
+}

package/src/workflows/retryPolicy.ts

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { WorkflowRetryPolicy } from "@pithy-sh/core/src/workflow/faults";
+
+/**
+ * **What the reconciliation pass retries, and what it refuses to.**
+ *
+ * The pass already draws this line in prose — `reconcile.ts` §"What a failure means" — and the line was
+ * the right one: a store that cannot be *reached* fails the page so the step re-drives it, and every
+ * other refusal is about one purchase and is counted rather than thrown. What was missing is that the
+ * platform never heard it, so anything that did escape a page was retried on the same terms
+ * (pithy-sh/pithy#338). This is that paragraph, in the form the step reads.
+ *
+ * ## Retryable
+ *
+ * - **`payments/provider_unavailable`** — Apple, Google, Stripe, Paddle or Lemon Squeezy unreachable, out
+ *   of time, rate-limiting, or answering 5xx; every rail's HTTP layer folds those into this one code. A
+ *   page is idempotent — it re-asks and re-projects to the same place — so a re-drive costs a request and
+ *   fixes an outage that has since ended.
+ * - **`core/upstream_failed` / `core/upstream_timeout`** — the same fault, raised by a shared client
+ *   rather than by a rail.
+ * - **A transient D1 fault** — classified in core by `withD1Retry`, never restated here.
+ *
+ * ## Terminal
+ *
+ * Everything else, and the list is deliberately not enumerated: an unmapped store state, a SKU no longer
+ * in the catalog, a rail switched off since the row was written, a receipt that will not verify, a
+ * parameter that will not validate. None of them answer differently to the same question an hour later,
+ * and a pass that spends its retry budget on one of them is a pass that does not reach page forty-one.
+ */
+export const paymentsWorkflowRetry: WorkflowRetryPolicy = {
+  capability: "payments",
+  retryable: {
+    "payments/provider_unavailable":
+      "The store could not be reached. A page is idempotent, so re-asking is free and the outage may be over.",
+    "core/upstream_failed": "A dependency this pass does not control was unreachable; the next attempt may reach it.",
+    "core/upstream_timeout": "A dependency ran out of time rather than refusing; the same page can be asked again.",
+  },
+};

package/src/workflows/specs.ts

@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
+import type { WorkflowRegistry, WorkflowSpecMap } from "@pithy-sh/core/src/workflow/spec";
+import { z } from "zod";
+import { PaymentsRail } from "../data/rail";
+import { PaymentsSubject } from "../data/subject";
+
+/**
+ * The one durable job payments owns: the reconciliation pass.
+ *
+ * Declared once, here. `capability.ts` derives its Workflow binding from this map, `provision/` derives the
+ * host worker's `workflows` array and its cron from it, and any caller triggers it by the `payments/reconcile`
+ * key. There is no second place where the binding name, the class name, or the schedule is written down, so
+ * none of them can drift.
+ *
+ * `optional: true` because the Workflow lives in the prebuilt reconcile worker, which exists only once
+ * `pithy payments provision` has run. Until then an app composing payments must still verify receipts, accept
+ * webhooks, and resolve entitlements — every one of which works with no Workflow at all. An absent binding
+ * degrades to a logged skip rather than a boot failure.
+ */
+
+/** The capability name — the first segment of the dispatch key and of every deployed resource name. */
+export const PAYMENTS_CAPABILITY = "payments";
+
+/** How far ahead of expiry a subscription is re-verified, when the caller names no window. Two days. */
+export const DEFAULT_EXPIRING_WITHIN_SECONDS = 172_800;
+
+/** How long a subscription may go unverified before a pass looks at it anyway. One week. */
+export const DEFAULT_STALE_AFTER_SECONDS = 604_800;
+
+/**
+ * The pass's parameters. **Every field is optional, and that is a requirement rather than a convenience:** a
+ * cron supplies no input, and `createEntrypoint` dispatches a scheduled job with `{}`. A schema that demanded
+ * a field could never run on its own schedule.
+ *
+ * The two windows are the pass's whole selection policy, and they are parameters rather than config because
+ * the reason to change one is always a one-off: reproducing a repair in staging without waiting for a
+ * subscription to age, or sweeping wider after an outage that ate a day of deliveries.
+ *
+ * **A holder narrowing is the pair, both halves or neither** — the rule `data/subject.ts` states, applied to
+ * the one field a support pass narrows on. Neither half is the cron. Both is *"reconcile this account"*. One
+ * half is refused rather than ignored: `subjectId` alone would scan whichever user *or* organization happens
+ * to carry that id, and nothing keeps those two ids apart, so the pass would answer about somebody else and
+ * report it as the account that was asked about.
+ */
+export const PaymentsReconcileParams = z
+  .object({
+    subjectType: PaymentsSubject.shape.subjectType
+      .optional()
+      .describe(
+        "Which kind of holder to narrow to. Send it with `subjectId` or send neither — half a subject names nobody.",
+      ),
+    subjectId: PaymentsSubject.shape.subjectId
+      .optional()
+      .describe(
+        "Reconcile one holder's purchases instead of the whole catalog. This is the support tool for \"my subscription isn't showing up\" — the same steps, narrowed, so the answer comes from the same code path the cron runs. Send it with `subjectType`: an id alone names whichever user or organization happens to carry it.",
+      ),
+    rail: PaymentsRail.optional().describe(
+      "Reconcile one rail's purchases only. The pass to run when a single store's webhooks were interrupted, rather than paying for the other two.",
+    ),
+    expiringWithinSeconds: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "How far ahead of its expiry a subscription is re-verified. Omitted uses two days, so a daily cron looks at every subscription at least twice before the period it paid for ends.",
+      ),
+    staleAfterSeconds: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "How long a subscription may go unverified before a pass looks at it regardless of its expiry. Omitted uses a week. This is what catches a subscription whose state changed nowhere near a renewal — a refund, a pause, a revocation whose notification never arrived.",
+      ),
+    pageSize: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "Purchases per durable step. Each page is one journalled step, so this is the unit of work a retry repeats. Omitted uses 100, which keeps a page inside the life of the one access token it mints.",
+      ),
+    maxPages: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "Cap how many pages one run scans. A bound on the work, so a first pass over a very large catalog finishes rather than running until it is killed. The next run resumes from the beginning and reaches what this one did not, because a reconciled row stops matching the selection.",
+      ),
+    dryRun: z
+      .boolean()
+      .optional()
+      .describe(
+        "Ask every store and write nothing. The safe way to answer 'how much drift is there' before letting a pass repair it, and the way to measure whether the webhook path is working at all.",
+      ),
+  })
+  .refine(
+    (params) => (params.subjectType === undefined) === (params.subjectId === undefined),
+    // The remedy is the other field, so the refusal names it. This is read off a CLI flag most of the time,
+    // where the two-line house error is all the operator sees.
+    { message: "Narrow on `subjectType` and `subjectId` together, or neither. Half a subject names no holder." },
+  )
+  .describe("What one reconciliation run should cover. Every field optional, because a cron passes none of them.");
+export type PaymentsReconcileParams = z.infer<typeof PaymentsReconcileParams>;
+
+/**
+ * Payments' durable jobs, keyed by job name.
+ *
+ * The schedule is daily at 04:00 UTC — offset from storage's 03:00 sweep and the secrets rotation, so three
+ * hosts in one account do not contend for the same minute. Daily is the right cadence because subscription
+ * expiry windows are hours wide rather than minutes wide, and because the client-submission path already gives
+ * a purchaser immediate feedback: reconciliation is the repair path, never the primary one.
+ *
+ * It is a cron **and** a dispatch target. A pass nobody can run on demand cannot be tested in staging, and it
+ * could not be the support tool the issue asks for — "my subscription isn't showing up" is answered by running
+ * these exact steps for one user.
+ */
+export const paymentsWorkflows = {
+  reconcile: {
+    binding: "PAYMENTS_RECONCILE",
+    className: "PaymentsReconcileWorkflow",
+    params: PaymentsReconcileParams,
+    schedule: "0 4 * * *",
+    optional: true,
+  },
+} as const satisfies WorkflowSpecMap;
+
+/**
+ * Payments' jobs as a dispatch registry, keyed `payments/<job>`. Built here rather than through
+ * `composeWorkflows` because the reconcile worker dispatches its own job before any project-wide registry
+ * exists — and the key format comes from core's {@link workflowKey} either way, so the two cannot drift.
+ */
+export const paymentsWorkflowRegistry: WorkflowRegistry = Object.fromEntries(
+  Object.entries(paymentsWorkflows).map(([job, spec]) => {
+    const key = workflowKey(PAYMENTS_CAPABILITY, job);
+    return [key, { key, capability: PAYMENTS_CAPABILITY, job, spec }];
+  }),
+);

package/src/workflows/worker.ts

@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+import { NonRetryableError } from "cloudflare:workflows";
+import { bindWorkflowContext, createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
+import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
+import { configureSharedSecrets, sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
+import type { PurchaseEnvironment } from "../data/purchase";
+import { triggerPaymentsReconcile } from "../http/dispatch";
+import { PAYMENTS_PROVIDER_SECRET, paymentsSecretsRegistry, railCredentials } from "../secret/registry";
+import { sweepPaddle } from "./paddleSweep";
+import { batchedRailAccess } from "./railAccess";
+import { type ReconcileReport, reconcilePayments } from "./reconcile";
+import { auditLogEmit, logReconcileReport } from "./report";
+import { paymentsWorkflowRetry } from "./retryPolicy";
+import { PaymentsReconcileParams } from "./specs";
+import { type PaymentsWorkerEnv, reconcileWorkerConfig } from "./workerConfig";
+
+/**
+ * The prebuilt payments reconcile worker. `pithy payments provision` deploys one per environment; the adopter
+ * authors none of it. It hosts a single Workflow — the reconciliation pass — and fires it on a daily cron.
+ *
+ * **Why its own worker rather than the app worker's `scheduled()`.** The pass makes hundreds of authenticated
+ * calls to three stores and can rewrite any purchase row. Keeping it out of the request-serving deployment
+ * means it cannot compete with a checkout for CPU, and the app worker never needs the App Store Connect key
+ * or the Play service account on a path that serves a request. It is a Workflow rather than a plain scheduled
+ * pass because a Worker invocation is wall-clock bounded while a Workflow step is not: a catalog of ten
+ * thousand subscriptions is a hundred pages against rate-limited third-party APIs, and that is work you want
+ * journalled rather than restarted.
+ *
+ * ## A Workflow here runs with **no subject seam**, and that is structural
+ *
+ * Read this before adding the next Workflow to this worker. Payments splits the "who holds a purchase"
+ * decision in two: `billingSubject` is a two-value enum in `PaymentsConfig`, and `resolveSubject` is a
+ * **function** on `PaymentsOptions`, the non-config argument to the `payments()` factory. The split follows
+ * the round trip this file sits at the end of — `provision/resolvePaymentsConfig.ts` `JSON.stringify`s the
+ * config into the `PAYMENTS_CONFIG` var and {@link reconcileWorkerConfig} parses it back, and a function
+ * does not survive that.
+ *
+ * So this worker **always** runs with no adopter resolver, on every project, in every environment. There is
+ * nothing to run one against either: `resolvePaymentsSubject` takes a Hono context, and a cron fire has no
+ * request, no session, and no caller.
+ *
+ * **Every subject anything in here touches therefore comes off a row it read** — the pair stored on a
+ * purchase, the pair on a provider-account link, or the reference a checkout stamped and the store echoed
+ * back. That is not a gap waiting to be closed; it is what a durable repair pass has to do regardless, since
+ * the holder of a subscription bought eleven months ago is not whoever happens to be signed in tonight.
+ * A Workflow added here that wants to know who holds something reads the row, and if the row cannot say,
+ * the honest outcome is an orphan: recorded, replayable, granting nothing.
+ *
+ * This module imports `cloudflare:workers`, so it runs only in the Workers runtime and is excluded from the
+ * node `.describe()` meta-test.
+ */
+
+export type { PaymentsWorkerEnv } from "./workerConfig";
+
+// A standalone worker, not assembled by `createBackend`, so wire the shared secrets accessor directly. Without
+// this the `secrets` capability's `compose` hook never runs and every rail's credential read throws.
+configureSharedSecrets({ registry: paymentsSecretsRegistry });
+
+/**
+ * This deployment's store environment, from the `ENVIRONMENT` var — the same rule the app worker's routes use.
+ *
+ * Only a worker deployed to `prod` is production. The failure directions are not symmetric: treating
+ * production as sandbox refuses a repair that the next pass makes anyway, while treating sandbox as production
+ * would let a test transaction rewrite a real entitlement.
+ */
+function deploymentEnvironment(env: PaymentsWorkerEnv): PurchaseEnvironment {
+  return env.ENVIRONMENT === "prod" ? "production" : "sandbox";
+}
+
+/**
+ * The reconciliation pass, as a cron-triggered Workflow. One journalled step per page of purchases.
+ *
+ * Every step runs under {@link paymentsWorkflowRetry}: a store that could not be reached re-drives the
+ * page, and anything else fails it at once rather than spending a run's retry budget on an answer that
+ * will not change. See `retryPolicy.ts`.
+ */
+export class PaymentsReconcileWorkflow extends WorkflowEntrypoint<PaymentsWorkerEnv, PaymentsReconcileParams> {
+  override async run(event: WorkflowEvent<PaymentsReconcileParams>, step: WorkflowStep): Promise<ReconcileReport> {
+    // Parse rather than trust: an instance can be started by the cron, by `triggerPaymentsReconcile`, or by an
+    // operator through the Cloudflare dashboard, and only the first two have already been validated.
+    const params = PaymentsReconcileParams.parse(event.payload ?? {});
+    // Before anything else in the run: a config the build cannot read makes every step below meaningless,
+    // and failing on the first line is what puts the refusal at the top of the instance rather than six
+    // journalled steps in.
+    const config = reconcileWorkerConfig(this.env);
+
+    // A run has no request, so there is no `c.var.log` to inherit: the Workflow builds its own and binds the
+    // instance onto it. The instance id is what the dashboard and `wrangler workflows` key on, so binding it
+    // once here is what lets an operator read a whole pass — tally and every repair — as one correlated set.
+    const log = bindWorkflowContext(createWorkerLogger({ name: "payments:reconcile" }), {
+      workflow: event.workflowName,
+      instance: event.instanceId,
+      env: this.env.ENVIRONMENT ?? "unknown",
+    });
+
+    // Read at the point of need, through the one reader. The credentials are handed to the rail access builder
+    // and never cached beyond the run.
+    const secrets = await sharedSecretsStore(this.env, paymentsSecretsRegistry);
+    const credentials = secrets.get(PAYMENTS_PROVIDER_SECRET);
+
+    const report = await reconcilePayments(
+      {
+        d1: this.env.DB,
+        config,
+        environment: deploymentEnvironment(this.env),
+        // Built per page inside the step, so each page mints its own batch tokens rather than replaying an
+        // expired pair after a retry.
+        railAccess: (now) => batchedRailAccess({ config, credentials, now }),
+        now: () => new Date(),
+        emit: auditLogEmit(log),
+        /**
+         * The Paddle events sweep, supplied only when that rail is on.
+         *
+         * Undefined otherwise, and the difference is a statement rather than an optimization: a rail
+         * nobody sells through did not sweep, where a rail that swept and found nothing is a healthy
+         * integration. Collapsing the two makes "the webhooks are fine" indistinguishable from "we never
+         * looked", which is the exact ambiguity this pass exists to remove.
+         *
+         * Built here rather than inside `reconcilePayments`, because it needs Paddle's credentials and its
+         * own account, and that module deliberately knows nothing about any single rail.
+         */
+        ...(config.rails.paddle && config.paddle !== undefined
+          ? {
+              sweepPaddle: () =>
+                sweepPaddle({
+                  d1: this.env.DB,
+                  config,
+                  environment: deploymentEnvironment(this.env),
+                  credentials: railCredentials(credentials, "paddle"),
+                  paddleEnvironment: config.paddle?.environment ?? "sandbox",
+                  // The raw `ENVIRONMENT`, not the two-valued store environment: the shared-sandbox fence
+                  // separates `dev` from `staging`, and both are `sandbox` on the other axis.
+                  deployment: this.env.ENVIRONMENT,
+                  now: () => new Date(),
+                }),
+            }
+          : {}),
+      },
+      classifiedSteps(step, paymentsWorkflowRetry, NonRetryableError),
+      params,
+    );
+
+    logReconcileReport(log, report);
+    return report;
+  }
+}
+
+export default {
+  /**
+   * Cron entry: start one pass per fire, with empty parameters — the defaults are the scheduled behavior.
+   *
+   * Through the same dispatcher an on-demand pass uses, rather than `env.PAYMENTS_RECONCILE.create()`: the
+   * parameters are validated against the job's own schema before the binding is touched, and a host deployed
+   * without its binding logs a skip instead of throwing inside a cron nobody is watching.
+   */
+  async scheduled(_controller: unknown, env: PaymentsWorkerEnv): Promise<void> {
+    // The logger is the point of the sentence above. Without one the dispatcher logs its skip to the no-op,
+    // so a host deployed with `PAYMENTS_RECONCILE` absent or renamed fires at 04:00 every night, does nothing,
+    // and says nothing — the one failure mode a nightly repair job cannot afford, because silence is also what
+    // success looks like.
+    await triggerPaymentsReconcile(env as unknown as Record<string, unknown>, {}, createWorkerLogger());
+  },
+};

package/src/workflows/workerConfig.ts

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { fromZodError, InternalError, messageOf } from "@pithy-sh/core/src/error/pithyError";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import { PaymentsConfig } from "../config/config";
+
+/**
+ * The reconcile worker's env, and the one function that reads its config out of a var.
+ *
+ * **A sibling module rather than part of `worker.ts`, and the split is a rule rather than a preference.**
+ * `worker.ts` imports `cloudflare:workers`, so it resolves only inside the Workers runtime — and anything it
+ * exports is therefore unreachable from a node test, from the CLI, and from every meta-test that walks this
+ * repository's exports. `packages/cli/src/capabilities/configEntrypoints.test.ts` fails a runtime module that
+ * exports a pure value for exactly that reason (#172), and this function is a pure value: it takes a plain
+ * object and returns a parsed config, touching no binding and no runtime API.
+ *
+ * So it lives here, where anything may import it, and `worker.ts` imports it like any other caller.
+ */
+
+/** The reconcile worker's env: the app database, the secrets database, the master key, and its config. */
+export interface PaymentsWorkerEnv extends SecretsStoreEnv {
+  /** The app database the `pithy_payments_*` tables live in. */
+  DB: D1Database;
+  /** The resolved payments config as a JSON string, filled at provision. See {@link reconcileWorkerConfig}. */
+  PAYMENTS_CONFIG?: string;
+  /** This worker's own Workflow binding — how `scheduled()` starts an instance. */
+  PAYMENTS_RECONCILE?: { create(options?: { id?: string; params?: unknown }): Promise<unknown> };
+}
+
+/**
+ * The catalog this worker reconciles against, read back out of the `PAYMENTS_CONFIG` var.
+ *
+ * **A config this does not accept stops the run, and since `billingSubject` became required that includes
+ * an absent var.** It used to fall back to `{}` and every default — which was survivable while every field
+ * had one, and is not now. The holder kind is the one thing a pass cannot default: `user` is what a
+ * defaulted config would produce, and a pass that repaired an organization's subscriptions while believing
+ * it was reconciling users would resolve entitlements for the wrong holder and audit the repairs under it.
+ * Refusing is the loud version of the same fact, and it fires on the first cron rather than on the first
+ * support ticket.
+ *
+ * Named as a refusal rather than a stack trace, because the reader is an operator: the message says which
+ * var, the action says which command rewrites it. Both `PithyError`s, so the Workflow's failure reads the
+ * way every other failure in the kit does.
+ */
+export function reconcileWorkerConfig(env: PaymentsWorkerEnv): PaymentsConfig {
+  let value: unknown;
+  try {
+    // An empty var is absent, not malformed — a wrangler config with the key and no value is the same
+    // missing config as one without the key, and it deserves the refusal that names the missing key rather
+    // than one about JSON syntax.
+    value = env.PAYMENTS_CONFIG ? JSON.parse(env.PAYMENTS_CONFIG) : undefined;
+  } catch (cause) {
+    throw new InternalError({
+      message: "The reconcile worker's PAYMENTS_CONFIG var is not valid JSON.",
+      action: "Re-run `pithy payments provision` for this environment to rewrite it.",
+      detail: messageOf(cause),
+    });
+  }
+
+  const parsed = PaymentsConfig.safeParse(value ?? {});
+  if (!parsed.success) {
+    throw fromZodError(parsed.error, {
+      message: "The reconcile worker's PAYMENTS_CONFIG var is not a payments config this build can run.",
+      // The two halves of the repair, in the order they have to happen: the value is the adopter's, and the
+      // var is a copy of it. Fixing only the second is a provision that writes the same refusal back.
+      action:
+        "Set the missing keys in this Worker's pithy.config.ts — `billingSubject` is required — then re-run `pithy payments provision` for this environment.",
+    });
+  }
+  return parsed.data;
+}

package/src/workflows/wrangler.jsonc

@@ -0,0 +1,55 @@
+{
+  // The prebuilt payments reconcile worker. Like the storage, email, and media workers, this is a TEMPLATE,
+  // not a wrangler env-stanza file: staging and prod are genuinely separate workers. `pithy payments
+  // provision` resolves it into one complete config per environment — filling the `<...>` placeholders,
+  // deriving the `workflows` array and the cron from the capability's specs — and deploys each with
+  // `wrangler deploy --config <resolved>`. The adopter authors none of it.
+  // Resolved per project and env → <project>-staging-payments / <project>-prod-payments. Worker
+  // script names are account-scoped, so the project segment is what stops a second Pithy project's
+  // deploy overwriting this one's running worker instead of colliding with it.
+  "name": "pithy-payments",
+  "main": "./worker.ts",
+  // The compatibility date every Worker in this repository runs on. Stated once in the repository
+  // root's `compatibility.ts` and copied here because JSONC cannot import it —
+  // `cli/src/ci/compatibilityDates.test.ts` fails on any Worker older than it.
+  "compatibility_date": "2026-06-01",
+  "compatibility_flags": ["nodejs_compat"],
+
+  // No public URL. Every payments route lives in the app worker; this worker is reached only by its cron and
+  // by Workflow dispatch. It holds three stores' credentials and can rewrite any purchase row, so it stays
+  // off workers.dev.
+  "workers_dev": false,
+
+  // The app database (the pithy_payments_* tables) and the secrets database, read for the rails' credentials.
+  "d1_databases": [
+    { "binding": "DB", "database_name": "pithy-app", "database_id": "<filled-at-provision>" },
+    { "binding": "SECRETS", "database_name": "pithy-secrets", "database_id": "<filled-at-provision>" }
+  ],
+
+  // The master key for decrypting the provider credentials, read through the secretsStore accessor.
+  "secrets_store_secrets": [
+    {
+      "binding": "SECRETS_ENCRYPTION_KEYS",
+      "store_id": "<filled-at-provision>",
+      "secret_name": "<filled-at-provision>"
+    }
+  ],
+
+  // The one Workflow this worker hosts. Rewritten at provision from `workflows/specs.ts`, so the binding, the
+  // class name, and the per-environment deployed name come from the spec rather than from this block — it is
+  // here so the template reads as a complete config.
+  "workflows": [
+    { "binding": "PAYMENTS_RECONCILE", "name": "pithy-payments-reconcile", "class_name": "PaymentsReconcileWorkflow" }
+  ],
+
+  // The daily pass, at 04:00 UTC. Also rewritten at provision from the spec's `schedule`, for the same reason
+  // — and offset from storage's 03:00 sweep so two hosts in one account do not contend for the same minute.
+  "triggers": { "crons": ["0 4 * * *"] },
+
+  "vars": {
+    // The resolved PaymentsConfig as one JSON blob, filled at provision from the app's payments() config. The
+    // pass reads the catalog from it — a refreshed SKU has to map to a product before it can be projected.
+    "PAYMENTS_CONFIG": "<filled-at-provision>",
+    "ENVIRONMENT": "<filled-at-provision>"
+  }
+}