Economy

0.18.xMinor

• BREAKING: the American spellings replace the British ones in the order-cancel and subscription-cancel APIs.

  • OrderCancelledEvent is now OrderCanceledEvent, and SubscriptionCancelledEvent is now SubscriptionCanceledEvent.
  • The order-cancel handler payload field cancelledAt is now canceledAt.
  • The stale-order sweeper summary fields cancelled and cancelledOrderIds are now canceled and canceledOrderIds.
  • The subscription webhook event type 'subscription.cancelled' is now 'subscription.canceled'. A custom adapter must emit the new value.
  • Stored values are unchanged: an order's status is still 'cancelled'.

• Admin labels, field descriptions, demo content and messages now use American spellings.

0.17.xMinor

• Single-product checkout now accepts a buyer-chosen amount (one-time, monthly or yearly) and a buyer without an account; no existing call changes.

  • Custom amounts. A Price opts in with allowCustomAmount, minAmountCents and maxAmountCents (validated on save), plus an optional externalProductId. createCheckoutSessionAction and createSubscriptionCheckoutAction take priceId, amountCents, coverFees and expectedTotalCents, and re-check every number on the server against the Price: the amount and its bounds, the currency, the fee cover and the total the buyer was shown. A custom amount is charged through an inline price, with recurring for monthly and yearly gifts, so no Stripe Price is needed.
  • Guest checkout. A guest buyer replaces memberId/memberEmail. One-time guest orders point at the site's placeholder member (guestCustomerId) and record the buyer as contactEmail; recurring guest subscriptions have no member and a unique guest:<uuid> userId. Only product types listed in guestProductTypes can be bought as a guest. A failed guest session cancels its pending Order at once.
  • Fee cover is a plain percentage plus an optional fixed part (feeCover: { percentBps, fixedCents? }), off unless the caller passes coverFees: true.
  • New helpers. ensureGuestMember finds or creates the placeholder member. claimGuestOrders moves a verified buyer's past guest orders and subscriptions to their new member. @wabbit/tome-economy/giving exports the side-effect-free rules (computeFeeCoverCents, validateGiftAmount, isGuestUserId) for forms.
  • Webhooks. checkout.completed gains mode, customerEmail and customerRef. A guest order with no email gets the one the buyer paid with. Every completion still looks for its Order first, in every session mode, so a subscription-mode session that has an Order completes exactly as before; only when there is none does a subscription-mode completion record the email and customer id on its Subscriptions row instead of logging a missing Order. That record is skipped when the configured subscriptions collection has no providerRef field, and its errors never affect the webhook. The order-complete event gains buyerKind: 'guest' for guest orders.
  • Adapters. StripeAdapter sends submit_type: 'donate' for one-time and subscription gifts, price_data.product when a provider product is given, and inline recurring prices; it declares the new supportsInlineRecurringPrice. For custom adapter authors: CreateCheckoutSessionArgs.customerEmail and CreateSubscriptionSessionArgs.customerEmail/stripePriceId are now optional at the type level (still always sent on every pre-existing path).
  • Schema. Prices gain four optional fields and Subscriptions gain contactEmail. Postgres consumers generate and run a migration; MongoDB consumers need none.

  Subscription lifecycle handlers that grant access should skip userIds for which isGuestUserId is true.

0.16.xMinor

• BREAKING: A full refund now revokes the access the order granted by default, and the Orders default edit view becomes the Order Overview.

  Migration: Pass refundAccess: false to createEconomyLayer / createOrdersCollection to keep refunds from touching access, and admin: { overview: false } to keep the previous Orders edit view. SQL adapters generate a migration (on Postgres: the orders_refunds array table and new payments columns); MongoDB needs none.

  Run backfillOrderRefunds from @wabbit/tome-economy/scripts once per consumer (dry run by default).

  • Orders gain a server-written refunds[] array, one row per provider refund or admin refund edit: providerRefundId, amountCents, currency, refundedAt, source, refundedBy, reason, note, sourceEventId, accessResult.
  • The webhook upserts rows by refund id in the same update that records the replay keys; an admin raising refundedCents appends an admin row with the acting user; admins can edit only reason and note.
  • StripeAdapter reads refunds.list({ charge }) on charge.refunded (Stripe's expired_uncaptured_charge maps to other; a list failure leaves the cumulative path running).
  • On checkout completion StripeAdapter retrieves the PaymentIntent once to fill the new Payments fields paymentIntentRef, chargeRef, card (brand, last4, expiry, wallet; never the number or fingerprint) and livemode.
  • Refund access policy, configured by refundAccess: a full refund revokes the entitlements the order granted (writing the catalog revocation audit fields by slug) and calls each product type's revokeAccess hook, unless another order still justifies the access. Partial refunds change nothing. exceptProductTypes and isStillJustified tune it.
  • The policy runs before the order-refunded dispatch, which now carries actorId and refunds.
  • admin.overview (default true) installs the Order Overview as the Orders default edit view; @wabbit/tome-economy/admin ships orderOverviewViewConfig and OrderOverviewView.
  • react and @payloadcms/ui are new optional peer dependencies.

0.15.xMinor

• Adds createCartCheckoutAction, a parallel multi-line checkout for physical goods; createCheckoutSessionAction behaves as before for every existing caller.

  All additive and optional:

  • Cart checkout. createCartCheckoutAction turns N cart lines into N provider line items, one pending Order and one hosted session with a fixed shipping option. Every line's price is resolved server-side from the newest active one-time Price for (product, variantSku); the caller sends identities and quantities, never amounts. A member buyer passes the same identity gate as the single-item action; a guest buyer is recorded against a configured placeholder member (guestCustomerId) with contactEmail. An optional inventory guard reserves stock after the Order is written, and a failed reservation or session cancels the Order at once. Promotion codes pass through.
  • Variant guard. createCheckoutSessionAction throws the new VariantPriceRequiredError, before writing anything, when the Price it resolves names a variantSku. Products whose Prices carry no variantSku resolve exactly as before. Not marked BREAKING: a Price only carries a variantSku to sell a variant through the cart, which did not exist before this release, so no existing single-item checkout can reach the guard.
  • Fields. Orders gain optional shippingCents (default 0), contactEmail and items[].variantSku; Prices gain an optional display-only compareAtCents. Postgres consumers generate and run a migration for the new columns; MongoDB consumers need none.
  • Provider seam. CheckoutLineItem gains displayName?/imageUrl?; CreateCheckoutSessionArgs gains shippingAddressCollection?, shippingOptions? and expiresAt?; PaymentProviderAdapter gains supportsCartShipping? and getCheckoutSession?. StripeAdapter implements both and sends each new Stripe parameter only when its argument is present.
  • Webhooks. checkout.completed carries shippingCents?, written onto the Order only when it is non-zero or the Order already holds a quote. A new checkout.expired event is acknowledged and ignored unless cancelOnExpiry is set (true, or a list of metadata.kind values); only pending Orders are ever canceled. The completion step is exported as completeCheckoutOrder.
  • Order-cancel bus. registerOrderCancelHandler / onOrderCancelDispatch fire once when an Order enters cancelled; with no handler registered the dispatch is silent.
  • Pending-order sweeper. expireStalePendingOrders (and createExpireStalePendingOrdersTask) settles or cancels stale pending Orders of the metadata.kind values a consumer names. Economy registers nothing; Orders of unnamed kinds are never touched.

0.14.xMinor

• Refund accounting is cumulative and replay-safe; checkout completion is idempotent; the order-refunded event carries what a consumer needs to act on it.

  1. A replayed partial refund, or a second partial, no longer marks the Order fully refunded. The refund branch of createStripeWebhookHandler decided full-or-partial by whether a succeeded Payment still existed, and marked that Payment refunded on any refund, so the second refund event for an order (a redelivery of the first, or a genuine second partial) always read as full. It now decides by amount: the Order's refundedCents takes the provider's cumulative refunded amount (Stripe's charge amount_refunded, the larger of what is recorded and what the event reports, never a running sum), and the Order is refunded when that reaches or passes totalCents, partially-refunded when it is above 0 and below. Each applied event id is recorded on the Order, and an event already applied, or one reporting no more than the recorded amount, writes nothing. Status only moves forward (refunded stays refunded). An event with no refund amount now writes nothing and logs a warning; it used to set a refund status with 0 refunded.
  2. A `checkout.completed` replayed after a refund no longer re-grants. For an Order already completed, refunded or partially-refunded the branch writes nothing: no status change, no second Payment, no order-complete dispatch, and the onOrderComplete option does not run. For a pending Order, a Payment already recorded for the same session or Order is reused instead of duplicated.
  3. `OrderRefundedEvent` gains `previousStatus`, `newStatus`, `previousRefundedCents`, `full`, `sourceEventId` and `order` (the six existing fields are unchanged). registerOrderRefundHandler keeps its signature; onOrderRefundDispatch(order, transition?) takes an optional second argument (new OrderRefundTransition type). A refund handler that throws synchronously is now caught and logged like a rejecting one, and a missing Order.customer dispatches userId: '' instead of throwing.
  4. `WebhookEvent`'s `refund` member gains three optional fields: eventId (the provider event id; StripeAdapter now sets it from the Stripe event), refundAmountBasis: 'cumulative' | 'delta' (omitted = cumulative, the previous reading) and refundId. A delta event's amount is added to the Order's total, replay-guarded by eventId and refundId.

  Schema changes — Postgres consumers must generate and run a migration before deploying (payload migrate:create, then payload migrate): orders.refundEventIds (json), payments.refundedCents (number, default 0), and a new partially-refunded value on the Payments status select (an enum change). MongoDB needs nothing.

  PaymentStatus gains 'partially-refunded'; code that switches exhaustively on it needs the new case. A partial refund now leaves its Payment partially-refunded, where it used to become refunded.

  Consumer follow-up: a site that watched the Orders collection in its own afterChange to react to refunds can move that logic to registerOrderRefundHandler and branch on event.full.

  @wabbit/tome-economy-authnet: mapAuthorizeNetWebhookEvent marks net.authorize.payment.refund.created as refundAmountBasis: 'delta' (an Authorize.net refund transaction carries that one refund's amount, not a running total) and adds eventId (the notificationId) and refundId (the refund transId). With this economy release, two partial refunds on an Authorize.net order now sum, and a redelivered notification is ignored.

  Upgrade both packages together: an older economy ignores the new fields and keeps its previous behavior, and this economy reading an older authnet's events treats each refund amount as a running total.

0.13.xMinor

• BREAKING: economy's collection admin gate now delegates to core's sessionHasCapabilityOrLegacyAdmin(req, 'economy:admin') (core has been a required peer since 2026-09-06).

  The default access of Orders, Payments, Prices, Subscriptions, VendorEarnings, PayoutAccounts and Payouts therefore also admits super-admin (populated roles, role: string[], or the legacy 'superadmin'/'super-admin' strings) and any role granted the economy:admin capability — previously only a legacy roles: string[] containing 'admin' passed. Consumers who override access are unaffected.

  Internally the gate is async and takes the request. All 51 inline as CollectionSlug casts are replaced with core's typedSlug() (no runtime change).

• Stripe webhook handler: the "setup.completed with no hook registered" and "subscription.payment_failed (dunning)" notices log through payload.logger.info instead of console.info.

• runPayoutBatch reads relationship ids with core's relationId instead of a local copy, which also handles numeric (Postgres) ids.

0.12.xMinor

• Handler registration accepts an optional key, so a module evaluated in more than one bundle registers exactly one handler.

  Every economy dispatcher keeps its handler list on globalThis under a Symbol.for(...) key, because bundlers — notably Next.js — load the module in more than one server bundle. That is what stops registration writing into one copy while dispatch reads an empty other copy.

  The unaddressed half is that registration then also runs once per bundle, and a bare push() stacked a second copy of the same handler each time. The dispatchers fan out through Promise.allSettled, so the copies run concurrently, and any consumer handler doing a check-then-act (find, then create if absent) had every copy pass the check and write.

  The failure surfaces as a silent duplicate rather than an error.

  registerOrderCompleteHandler, registerOrderRefundHandler, and the four subscription lifecycle registrations now take an optional second argument. Passing { key: 'my-app/grants' } replaces whatever was previously registered under that key instead of appending beside it, which also does the right thing under HMR — the newest closure wins.

  Omitting the key preserves the previous append-every-time behavior exactly, so no existing caller changes semantics.

  Two implementation details are deliberate. The handler list keeps holding bare handler functions, with the key map stored under its own symbol, because Symbol.for keys are process-global and an older copy of this package loaded as a nested dependency must still be able to dispatch the same list.

  And an unsubscribe returned by a superseded registration is a no-op rather than tearing down its replacement, which matters for callers like @wabbit/tome-affiliates that bundle several unsubscribes together.

  Found from a live double-grant: a consumer site granted two entitlement rows for one purchase on 2026-09-20 because its consumer-side guard against re-registering was a module-local let while the registry it guarded was global. @wabbit/tome-affiliates avoids the same trap only by hand-rolling its own globalThis-keyed entry around the register calls; the key option is that pattern made available to every consumer.

0.11.xMinor

• Four additive economy seams — the prerequisite PRs the `@wabbit/tome-affiliates` layer spec (2026-09-14, §9 a-d) needs to build on.

  1. Checkout metadata passthrough. CheckoutSessionInput gains metadata?: Record<string, string>. Reserved keys orderId, productId, memberId, productType (exported as RESERVED_CHECKOUT_METADATA_KEYS) are computed by the action itself; a caller-supplied key that collides with one now throws the new ReservedCheckoutMetadataKeyError before any Payload or adapter call, instead of silently colliding. The merged metadata reaches the adapter's session metadata (and so payment_intent_data.metadata) AND the pending Order's own metadata field, written at Order-creation time. createSubscriptionCheckoutAction's metadata was already required and already passed arbitrary extra keys through, so it needed no change for the same affiliate-attribution use case.
  2. Paid-amount truth on Orders. Orders.totalCents/discountCents were frozen at list price from createCheckoutSessionAction's pending-Order write (discountCents hardcoded 0) and never corrected once Stripe applied a promo. createStripeWebhookHandler's checkout.completed branch now overwrites totalCents with the session's real amount_total on completion, plus two NEW Orders fields written when the session resolves them: taxCents (from total_details.amount_tax) and promotionCodeRef (the applied Stripe promotion code id, from session.discounts[0].promotion_code). discountCents is likewise overwritten from total_details.amount_discount when resolvable. This is also the fix for the refund branch's isPartial comparison, which reads the same order.totalCents field — no separate code change was needed there once it carries the real charged amount instead of list price. WebhookEvent's checkout.completed member gains subtotalCents/discountCents/taxCents/promotionCodeRef, all optional (undefined on a hand-built event that doesn't carry them; every real Stripe session does).
  3. Order refund dispatcher. NEW event bus mirroring the order-complete one exactly: registerOrderRefundHandler(handler), onOrderRefundDispatch(order), event shape OrderRefundedEvent { orderId, userId, status: 'refunded' | 'partially-refunded', refundedCents, totalCents, refundedAt }. No layer previously had a refund signal from economy; consumers reinvented their own afterChange watch. NEW Orders field refundedCents (default 0) carries the provider's cumulative refund amount, written by the webhook handler's refund branch. The Orders afterChange hook dispatches when status is refunded/partially-refunded AND (the status just transitioned OR refundedCents increased) — the second arm makes a partial-then-full refund dispatch twice; the first arm alone makes a webhook redelivery reporting the same cumulative amount a no-op.
  4. Renewal amount on the renewal event. SubscriptionRenewedEvent gains amountCents?, currency?, paymentId?. The webhook handler now writes the renewal Payment row BEFORE dispatching (previously: dispatch first, write after) so the dispatch can carry that row's id. amountCents/currency come straight from the source WebhookEvent and so are present whenever it resolved them, independent of the ledger write's own success; only paymentId is omitted if that write fails — the entitlement dispatch itself is never gated on it, preserving the existing "a ledger-write hiccup cannot turn a successful grant into a Stripe retry" guarantee.

  Consumer follow-up: none required — every change here is additive, and OrderCompletedEvent is unchanged (frozen contract, shared-contracts-v3 §4).

• Payouts extension — the provider-neutral payout seam the `@wabbit/tome-affiliates` layer spec (2026-09-14, §9 e) needs, generalized from the April vendor Payouts design.

  Opt in with createEconomyLayer({ payouts: true }) (default off; existing consumers are unaffected). Adds the payout-accounts and payouts collections with GDPR registration (redact and retain), a PayoutProviderAdapter interface with ManualPayoutAdapter and StripeConnectPayoutAdapter (v1 Connect account with Express dashboard and transfers capability, account-link onboarding, separate transfers from the platform balance with a request idempotency key, balance lookup, account.updated and transfer.reversed webhook mapping), createPayoutWebhookHandler, runPayoutBatch (released payouts first, per-payee minimum, waiting-payout guard, balance check before any write, first-payout review, failed attempts free their key for a later retry), and getPayeeAnnualTotals.

0.10.xMinor

• Subscriptions collection + subscription checkout, and an open payment-provider seam — the two prerequisite PRs the `@wabbit/tome-directory` layer spec (§14 a/b) needs to build on.

  1. New `Subscriptions` collection + `createSubscriptionCheckoutAction`. createEconomyLayer now includes a Subscriptions collection by default (subscriptions: false to opt out, or a SubscriptionsCollectionConfig to override slugs/relationship targets) with fields provider, providerRef, customerRef, account/member (both optional relationships), price, status (active|trialing|past_due|canceled|expired), currentPeriodStart/currentPeriodEnd, cancelAtPeriodEnd, metadata. createSubscriptionCheckoutAction is the recurring-billing counterpart of createCheckoutSessionAction — same required auth identity gate, same CheckoutIdentityMismatchError — routes a Price with interval: 'month' | 'year' through adapter.createSubscriptionSession (throwing the new SubscriptionCheckoutUnsupportedError for a one-time Price or an adapter without recurring-billing support), creates the Subscriptions row eagerly (mirroring the pending-Order-before-redirect pattern), and calls an optional persistCustomerRef callback so a consumer can save the provider customer id onto its own record. createSubscriptionPortalAction and cancelSubscriptionAction round out the surface, both feature-detecting the adapter's optional createPortalSession/cancelSubscription.
  2. `createStripeWebhookHandler`'s `subscription.renewed` branch now writes a renewal Payment row and upserts the Subscriptions row. Previously that branch dispatched the entitlement events but created no ledger row at all, unlike checkout.completed — a monthly Price yielded a working entitlement grant but an invisible billing history. The upsert resolves the row by providerRef (a direct hit on every renewal after the first) and falls back to a metadata.userId/metadata.productId match (the first renewal, before providerRef is finalized from the checkout-session id to the real provider subscription id); a subscription provisioned outside this package's checkout action gets a best-effort row rather than a silently dropped event. subscription.cancelled/subscription.payment_failed now also update the row's status. Because a renewal has no Order, Payments.order is now optional and a new Payments.subscription relationship carries the link instead — existing one-time-checkout Payment rows are unaffected (that write path still always sets order).
  3. Provider seam opened up (Stripe's own policy disqualifies it for the launching vertical, so a second real adapter, `@wabbit/tome-economy-authnet`, was always coming). PaymentProvider widens from the closed 'stripe' | 'free' | 'manual' to 'stripe' | 'free' | 'manual' | 'authorizenet' | (string & {}); the Orders/Payments/Subscriptions provider fields convert from a closed Payload select to text + an open validate (any non-empty string; known values are documented for the admin UI only — see collections/commerce/providerField.ts). createStripeWebhookHandler reads the signature header via adapter.webhookSignatureHeader ?? 'stripe-signature' (new optional PaymentProviderAdapter member) instead of hardcoding Stripe's header name, and every Payment write now stamps adapter.provider instead of a hardcoded 'stripe'. PaymentProviderAdapter also gains optional cancelSubscription(args) and refund(args), both implemented on StripeAdapter (the pre-existing StripeAdapter.cancelSubscription(subscriptionId, atPeriodEnd) positional signature is now the interface's { providerRef, atPeriodEnd? } object shape — a breaking change to that one method's own signature, safe because nothing in this repo called it yet).
  4. `@wabbit/tome-core` is now a REQUIRED peer. The "genuinely optional" posture this package documented through 0.9.0 no longer held even before this change — createCheckoutSessionAction.ts already carried a static, module-scope import { resolveMemberFromSession } from '@wabbit/tome-core/identity', so any consumer using that action already required core at runtime regardless of what peerDependenciesMeta claimed. initEconomy now imports registerLayer statically (its try/catch exists only for the "already registered" HMR/repeat-call case, matching every sibling initXLayer), and createEconomyLayer now actually applies the shared access/hooks/extraFields/fieldOverrides/omitFields/fieldOrder vocabulary from @wabbit/tome-core/utilities/layerFactoryConfig to every collection it returns — previously accepted on EconomyLayerConfig but explicitly documented as inert pending this exact trigger. access/adminGate.ts's own promotion trigger ("the day core becomes a required peer") has therefore fired, but delegating that gate's implementation to core's sessionHasCapabilityOrLegacyAdmin primitive is a separate, larger change this PR deliberately does not bundle — recorded in that file's header rather than half-done silently.

  Consumer follow-ups: a site wiring @wabbit/tome-accounts's forthcoming billing group (prerequisite PR (c)) as persistCustomerRef gets provider-agnostic customer-ref persistence on first subscription checkout for free. @wabbit/tome-economy-authnet (prerequisite PR (b)'s stated reason for the provider seam) can now implement PaymentProviderAdapter in full, including webhookSignatureHeader: 'X-ANET-Signature' and cancelSubscription/refund.

0.9.xMinor

• 7d0949f4: Three additive checkout/webhook seams, surfaced by the first non-LMS consumer (2026-09-04).

  1. `items[].productType` is now stamped at checkout. Orders has declared the field since 0.3.0 and onOrderCompleteDispatch reads it, but createCheckoutSessionAction never wrote it, so every non-course product was dispatched to order-complete handlers as 'course' and consumers had to re-stamp the line item themselves. The action now denormalises the catalog product's type onto the line item and into the provider session metadata (metadata.productType). Products with no type are unchanged (the key is omitted, never written empty).

  1. Promotion codes and site-applied discounts pass through to Stripe Checkout. CheckoutSessionInput and CreateCheckoutSessionArgs gain optional allowPromotionCodes?: boolean (Stripe allow_promotion_codes) and discounts?: Array<{ coupon?: string; promotionCode?: string }> (Stripe discounts). Both are absent from the adapter call and the Stripe request on the default path, so existing sessions are byte-identical. Stripe forbids the two keys together: when both are given, discounts is applied and the code box is suppressed for that session. FreeAdapter ignores both.

  1. `createStripeWebhookHandler` gains `onSetupCompleted`. The adapter has emitted setup.completed (a mode: 'setup' Checkout Session: card saved, nothing charged) since 0.6.0, but the handler dropped it, and wabbit-site-core worked around that by classifying a cloned request ahead of the handler. The handler now calls onSetupCompleted(event) when configured. It writes nothing itself (there is no Order or Payment for a setup session; the consumer owns the pledge row), a throwing hook is logged and the route still answers 200, and with no hook registered the event is acknowledged and ignored exactly as before. The event type is exported as SetupCompletedWebhookEvent.

  Consumer follow-ups: wabbit-site-core can retire the request-clone peek in src/app/api/webhooks/stripe/route.ts by passing onSetupCompleted: (e) => handleSetupCompleted(payload, e); the other consumer can drop its consumer-side items[].productType re-stamp and pass allowPromotionCodes: true for the founder/early-bird codes.

0.8.xMinor

• Breaking (0.x) — `createCheckoutSessionAction`'s returned action now takes a required second argument.

  The action creates Orders with overrideAccess: true and previously trusted the memberId/memberEmail it was handed. The auth contract lived only in a JSDoc usage example, so a consumer that forgot to resolve the session — or resolved it and then passed a client-supplied id — shipped an IDOR: any signed-in customer could mint a pending Order against another member, with that member's id carried into the payment provider's metadata.

  A comment cannot fail a build, so the check is now at runtime.

  The returned function is action(input, auth). auth is { user } — pass a Payload req.user-like object verbatim.

  Before the Order is written or the adapter called, the action resolves the session user's member row (via @wabbit/tome-core/identity's resolveMemberFromSession, one find on the members collection) and asserts that row is input.memberId. A user id is never compared to a member id: they are different collections, and every shipping consumer — tome-starter, wabbit-site-core — passes a members-row id.

  input.memberEmail must match the session's email or the resolved member's, case-insensitively. A failure throws the new exported CheckoutIdentityMismatchError (.reason is 'missing-auth' | 'no-member' | 'id-mismatch' | 'email-mismatch', .code is 'checkout-identity-mismatch'); map it to a 403.

  Writes keep overrideAccess: true — that bypass is now safe precisely because the caller's identity is proven rather than assumed.

  Consumer edit — in your 'use server' wrapper, resolve the session server-side and stop taking the member from the client:

  - export async function enrollAction(productId: string, memberId: string, memberEmail: string) {
  + export async function enrollAction(productId: string) {
      const payload = await getPayload({ config })
  +   const { user } = await payload.auth({ headers: await headers() })
  +   if (!user) throw new Error('Not signed in')
  +   // orders.customer -> members. Resolve the buyer's member row from the
  +   // session; the action re-derives it independently and must agree.
  +   const member = (await payload.find({
  +     collection: 'members', where: { user: { equals: user.id } }, limit: 1, depth: 0, overrideAccess: true,
  +   })).docs[0]
  +   if (!member) throw new Error('No member profile for this account')
      const action = createCheckoutSessionAction({ adapter, payload, baseUrl })
  -   return action({ productId, memberId, memberEmail })
  +   return action(
  +     { productId, memberId: String(member.id), memberEmail: user.email },
  +     { user },
  +   )
    }

  A genuinely anonymous flow (guest checkout, or a server-to-server job that authorized the purchase upstream) opts out with { allowUnauthenticatedCaller: true }, which is documented as dangerous and does NOT relax the id/email assertions when a user is present.

  New exports: CheckoutIdentityMismatchError, CheckoutCallerIdentity, CheckoutIdentityFailureReason.

  Also: the TODO(post-v0): add pending-order expiry mechanism (Risk R4) is now a stated accepted risk with explicit build triggers (pending Orders accumulating in production, a second write path creating pending Orders, or checkout exposed to unauthenticated callers) instead of an open-ended TODO. No implementation change.

  Tests: 15 assertions covering a user whose member row is the memberId (ids differ across collections), a user with no member row, id mismatch (throws before any read, write or adapter call), missing auth, absent session, the explicit unauthenticated opt-in, and the opt-in NOT overriding a present-but-wrong user.

• Admin gate → core primitive.

  "Is this user an admin?" was answered five incompatible ways across the platform (2026-09-01 sale-readiness audit §5.2); these four packages carried a deliberate clone of the same pre-can() role-string check, crowdfund's and fulfillment's headers both saying "matching economy verbatim". No behavior change is intended for the legacy path, and tests pin it rather than prose asserting it.

  crowdfund, fulfillment, rpg now call sessionHasCapabilityOrLegacyAdmin() from @wabbit/tome-core/auth/repScoping, and compose the owner-scoped WHERE through ownershipOrBypass() from @wabbit/tome-core/access. All three declare @wabbit/tome-core as a required, explicitly non-optional peer, so these are plain static imports.

  The legacy path is unchanged: a roles array containing 'admin' is an admin, an unauthenticated request is not, and a non-admin session still resolves to { [ownerField]: { equals: user.id } }. Deliberately widened: capability grants (crowdfund:admin / fulfillment:admin / rpg:admin) and core's superadmin / super-admin legacy aliases now pass too — the point of adopting the shared primitive.

  The Access functions are async now; Payload's Access type has always allowed a Promise, and the capability path needs an await. hasAdminRole stays exported from crowdfund and fulfillment as a @deprecated back-compat shim with byte-identical semantics; CROWDFUND_ADMIN_CAPABILITY and FULFILLMENT_ADMIN_CAPABILITY are new named exports.

  economy deliberately does NOT adopt the core primitive, and the reason is a constraint rather than an oversight: @wabbit/tome-core is a declared OPTIONAL peer here, the README states in two places that core is genuinely optional, and the only core reference in src/ is a guarded lazy require() in initEconomy. A static import of a core access primitive from a collection factory would silently convert that optional peer into a required one.

  Instead the ten inline checks across Orders (×3), Payments (×2), Prices (×4) and VendorEarnings (×1) collapse into one internal isEconomyAdmin() in src/access/adminGate.ts, implementation moved not rewritten, with a written promotion trigger: the day core becomes a required peer of this package, delete the body and delegate. Orders' unique extra req.user.collection === 'users' condition is preserved exactly and pinned by a test.

  New suites: crowdfund/tests/access.test.ts (14), fulfillment/tests/access.test.ts (16), economy/tests/admin-gate.test.ts (11). Existing collections.test.ts assertions in crowdfund and fulfillment were updated to await the now-async access results — asserted VALUES unchanged. rpg has no test harness, so its change is covered by typecheck only.

  The forcing function ships with the consolidation: eslint.config.mjs gains a no-restricted-syntax warn-ratchet banning hand-rolled .roles.includes(...) admin checks in access/**, collections/** and *access*.ts, pointing at sessionHasCapabilityOrLegacyAdmin / can. The repo-wide count is 0 (down from 13), with three written eslint-disable exemptions: the two deprecated back-compat exports and economy's single gate.

• One LayerFactoryConfig every layer factory's config extends, and one factory verb.

  Fourteen layer packages end in the same one call a consumer writes into payload.config.ts, and no two agreed on what config may contain: full seam vocabulary in three (org, lms, ledger), partial in six, NONE in six (2026-09-01 sale-readiness audit §5.3). A site that learned adminGroup from org and hooks from sc discovered, package by package, that six factories accept neither — not because the seam had been rejected, but because nothing said it existed.

  New in core (a NEW exports-map subpath, hence the minor): @wabbit/tome-core/utilities/layerFactoryConfig exports the LayerFactoryConfig interface — adminGroup, access (per-collection override map), hooks (appended via mergeHooks, never replacing), extraFields, fieldOverrides, omitFields, fieldOrder, slugs — and applyLayerFactoryConfig(collections, config), which honors the whole vocabulary in one call and one fixed order (adminGroup → access → hooks → field shape, the last delegated to fields/fieldShape's applyFieldShape so the order cannot drift between layers). Pure: new array, new objects, identity return on an empty config.

  It is a separate subpath from ./utilities/layerRegistry deliberately — that module is in core's sideEffects array, and a pure type/vocabulary module should not drag a declared side-effecting module into every factory's type graph.

  The slug convention is documented rather than forced, because both live shapes are right for what they do: a typed slugs?: Partial<XSlugs> map for the slugs a layer OWNS (org, sc, accounts — the typed key set makes a typo a compile error, and a homomorphic mapped type satisfies the base's Record<string, string | undefined>), and named <name>Slug?: string scalars for relationship targets in OTHER layers (memberSlug, mediaSlug, eventSlug, rolesSlug) — those are pointers out of a layer, not entries in its key set.

  *Every `createLayer config now extends it.** Twelve extend LayerFactoryConfig directly and APPLY it through applyLayerFactoryConfig (accounts, catalog, crm, crowdfund, deals, fulfillment, lms, marketing, org, sc) or through a targeted application (chrome). Additive in every case: for the six that accepted none of the seams (deals, economy, gamification, marketing, plus forms/intake, see below), the fields are new; for the rest, adminGroup` and friends keep their existing meaning and the applier is a no-op when they are omitted.

  Two packages accept the vocabulary but do NOT yet apply it, and say so in their type's JSDoc in the required form ("accepted, not yet applied — trigger: …"). economy and gamification both declare @wabbit/tome-core as an OPTIONAL peer and hold zero runtime imports of it — gamification reaches registerLayer through a lazy require() in a try/catch for exactly this reason.

  applyLayerFactoryConfig is a runtime VALUE, so importing it at module scope would convert an optional peer into a required one and break every site that installs those packages without core; copying the applier locally is barred by assert:no-forked-primitives. The trigger is stated: the day core becomes a required peer, delete the note and add one line.

  Both take the type via import type, which is erased at runtime.

  Two packages drop seams EXPLICITLY rather than accept-and-ignore. chrome extends Omit<LayerFactoryConfig, 'access' | 'hooks' | 'extraFields' | 'fieldOverrides' | 'omitFields' | 'fieldOrder' | 'slugs'> because it returns Payload GLOBALS, not collections — those seven are keyed by collection slug and typed against CollectionConfig, and chrome's slugs already have direct per-surface knobs (header.slug, footer.slug) a parallel map could contradict.

  The one seam it keeps, adminGroup, IS applied: globals carry admin.group exactly as collections do. rpg extends Omit<LayerFactoryConfig, 'access'> because CharacterSheetsConfig is a single collection's config that doubles as the layer factory's config, and its own access already means "this collection's access object" — one level shallower than the base's slug-keyed map.

  Two meanings under one name is the confusion this interface exists to end.

  Factory-verb convergence. Three verbs were live. createWorkflowLayer(config?) is new in @wabbit/tome-workflow (a new export — hence the minor) and returns a spreadable, deliberately EMPTY CollectionConfig[]: this layer is an engine, not a collection set, so the empty array is the honest answer and lets ...createWorkflowLayer() compose exactly like every sibling.

  Its WorkflowLayerConfig omits every seam for the same reason, and exists as the stable place a real option will land. createGamificationLayer and createRpgLayer are pure aliases of registerGamificationLayer / registerRpgLayer.

  initWorkflow, registerGamificationLayer and registerRpgLayer are all @deprecated with sunset at each package's next major; none is removed.

  Forcing function: scripts/assert-layer-factory-contract.mjs + pnpm assert:layer-factory-contract, wired into platform-discipline.yml after assert:layer-version (source reading only, pre-build). Every exported create*Layer must take a config parameter whose type resolves to LayerFactoryConfig — through extends, an intersection, or an explicit Omit<…> — with verb aliases followed to their register*/init* target.

  Before this change it reported 12 violations and 0 conforming; it now reports 15 conforming, 0 violations. Deliberately NOT checked: whether a factory actually applies what it accepts, because a machine cannot tell a documented deferral from an accident, and a gate that forced silent application would be worse than one that forces a stated deferral. docs/guides/create-a-new-layer-package.md gains a "The factory contract" section stating the rule and the three permitted responses.

  Three factories are ALLOWLISTED with a reason each: createAiLayer returns credential wiring and owns no collections, so every seam is meaningless to it; createFormsLayer and createIntakeLayer are owned by the forms+intake access wave running in parallel, whose changes rewrite the same files.

  Peer floors: accounts, catalog, chrome, crm, deals, economy, fulfillment, gamification, marketing and rpg raise @wabbit/tome-core to >=1.14.0 <2.0.0. The new subpaths do not exist below that, and a too-low floor is how ERR_PACKAGE_PATH_NOT_EXPORTED reached crowdfund's consumers once already.

  These are marked patch because the config widening is purely additive; the raised required-peer floor is the reason a release manager may prefer to cut them as minors instead.

• Manifest metadata: homepage, bugs, engines.

  All 46 publishable manifests were missing the three fields a consumer sees before any code (2026-09-01 sale-readiness audit §6). Metadata only — no source, no build, no runtime change.

  • homepage deep-links to that package README on GitHub (.../tree/main/packages/<dir>#readme). Without it a registry page links to the monorepo root and the reader has to guess which of 46 folders they want.
  • bugs.url points at the repo issue tracker, so a paying customer has a place to report a defect that is not email.
  • engines.node is >=22, matching the root engines and .nvmrc set the same day. This is a real floor, not decoration: CI on Node 20 could not expand the glob the block packs use for node --test, and a package installed on Node 20 fails at a runtime the installer cannot connect back to the version.

  The forcing function ships with the change: scripts/assert-manifest-metadata.mjs (root pnpm assert:manifest-metadata, wired into platform-discipline.yml beside assert:license-metadata) fails when any publishable manifest lacks description, repository.directory matching its own folder, homepage, bugs, engines.node equal to the repo floor, license, files or sideEffects. It reported 138 violations before this change and 0 after.

0.7.xMinor

• Track C I3: opt-in catalog-product-variants collection (default OFF — bare createCatalogLayer() is unchanged; enable via variants: true|{slug}, the entitlements-style knob) with SKU-axis options, semantic-duplicate hook, weight/dimensions.

  Economy Prices gain an optional variantSku TEXT field (advisory by design, non-unique); the checkout price query is untouched and now test-pinned.

0.6.xMinor

• Optional adapter methods for crowdfund settlement (B2 precedent — additive interface members): createSetupSession (hosted Checkout mode:'setup'), chargeSavedPaymentMethod (off-session PaymentIntent with Stripe idempotency-key request option; declined/SCA failures returned as typed results), releaseSavedPaymentMethod.

  WebhookEvent union gains setup.completed, discriminated on session mode — mode:'payment'/'subscription' mappings pinned field-for-field unchanged.

• Track C I0 hygiene: dist ships extensioned specifiers (fix-dist-extensions --strict wired into build; assert-node-loadable preflight added — both dists now raw-Node loadable, PASS 2/2).

  Stale registerLayer versions corrected (catalog said 1.1.1 at 1.4.0; economy said 0.2.3 at 0.5.0) and test-pinned to package.json so future bumps can't silently drift. Economy gains its vitest harness (first tests in the package — the settlement logic landing in I1 requires it).

0.5.xMinor

• Naming convergence (all additive; every old name keeps working as a @deprecated alias until that package's next major).

  create* is canonical for collection/layer factories (define* stays reserved for the blocks descriptor system): crm/deals/marketing/intake/forms gain create*Collection names for their former define*Collection factories. Layer entries converge on createXLayer(config?) → bundle: createCrmLayer/createDealsLayer/createMarketingLayer/createCatalogLayer/createEconomyLayer/createChromeLayer/createLmsLayer/createAiLayer (+ createFormsLayer/createIntakeLayer), returning bare CollectionConfig[] where the layer contributes only collections or an honest named bundle where it hands back more (chrome: { globals }; lms/ai: { collections, hooks }); void-returning initCatalog/initEconomy stay as the single registration call sites, delegated to internally.

  Naming note for forms consumers: createFormsCollection (singular factory) vs createFormsCollections (plural composer) vs createFormsLayer (layer entry) — each docblock states the distinction.

• Every package now declares an explicit sideEffects field (38 added; motion/engine/forms already correct).

  Registration-bearing modules (render files' registerRenderer, blocks/*/index.ts defineBlock self-registration, widget register.ts files, productHooks, permission self-registrations, print templates, chrome built-in variants) are listed so bundlers can tree-shake everything else WITHOUT dropping import-time registrations — previously the field was unset, which blocked cross-module tree-shaking through the barrels entirely. Never blanket false on a package with registration or CSS.

0.4.xMinor

• Add an opt-in subscription.payment_failed dispatch seam for dunning.

  New exports: registerSubscriptionPaymentFailedHandler, onSubscriptionPaymentFailedDispatch, and the SubscriptionPaymentFailedEvent / SubscriptionPaymentFailedHandler types. The Stripe webhook handler now dispatches failed renewal charges to registered consumer handlers (in addition to the existing observability log) instead of dropping them, so a consumer can flag the billing record past_due, alert the team, and email the customer.

  No-ops when no handler is registered, so existing consumers are unaffected.

0.3.xMinor

• Add subscription / recurring-billing support to the Stripe provider and webhook handler.

  New optional adapter methods createSubscriptionSession and createPortalSession, plus subscription/customer helpers; the webhook handler now maps the subscription lifecycle (invoice.paid -> renewed, customer.subscription.updated(cancel_at_period_end) + .deleted -> canceled, invoice.payment_failed -> payment_failed) and dispatches via a new onSubscriptionComplete event bus. Adds Prices.interval (one-time / month / year) and Orders.items[].productType.

  Fully additive — one-time Checkout and the existing order/webhook path are unchanged.

0.2.x

1.0.x