@odla-ai/chapter 0.47.10 → 0.48.1

package/README.md

@@ -88,13 +88,13 @@ Chapter-owned application, admin, CRM, payment, and scheduling behavior.
   *or* an odla-db `admins` allowlist, plus a read-only `superAdmins` tier —
   selected by `auth.source`, defaulting per mode. Escalation guards
   (`canChangeRole`) are package-enforced.
-- **Correctness is packaged, not per-site.** Replay-deduplicated email
-  (`sendTemplated`/`isAlreadySent`; concurrent sends still need a serialized
-  outbox/provider idempotency for a true exactly-once guarantee), a non-prod
+- **Correctness is packaged, not per-site.** Durably claimed email
+  (`sendTemplated`/`isAlreadySent`; ambiguous non-idempotent provider outcomes
+  require evidence-based reconciliation rather than blind resend), a non-prod
   delivery fail-safe (`planDelivery`), stable application replay identity (one
   UI submission key and the same resumable canonical id), status-never-backwards
   (`canTransition`), Stripe webhook integrity (`verifyStripeSignature`) with the
-  webhook as the authoritative writer of paid/refunded,
+  verified Stripe events and refund reconciliation as the payment authority,
   one-subscription-per-application idempotency, meetings-as-canonical booking (a
   rebooking *reschedules* the event, preserving the Meet link), Google-edit
   adoption (`reconcileMeetings`), and a one-way CRM projection.
@@ -381,6 +381,12 @@ The same renderer can also replace the placeholder chooser inside
 `redirect_status` and `reschedule` values never choose a UI step. Supply
 `loadResume` when a host stores the capability elsewhere.
 
+Closed/refunded/declined applications return a scoped `409` with
+`code: "application_closed"`; `loadJoinResume` maps this to `step: "closed"`.
+The island shows a terminal notice without another form, checkout, or booking.
+Unknown continuation states and mismatched application ids are rejected rather
+than defaulting to payment. Temporary configuration failures remain retryable.
+
 Studio and automated previews can traverse that same state machine without
 creating an application, loading Stripe, charging a card, or booking a real
 calendar event. Supply deterministic `simulation` boundaries and keep the
@@ -609,6 +615,24 @@ The hub builds a complete `SignupControlDocument`, calls
 secret is vaulted separately on each side; it is never a Clerk token, ODLA key,
 or CRM network secret.
 
+For multiple authoritative runtimes sharing a data environment, set
+`signupControl.runtimeSecrets` to an explicit map such as
+`{ cory: "signup_control_cory", tori: "signup_control_tori" }`. Each value names
+a different follower vault key; paired hub credentials remain separate too.
+Unlisted runtimes and untargeted legacy deliveries then fail closed. Include
+`deliveryTarget: { appId, environment, runtime }` beside the envelope's
+`document` and `digest`. This transport identity is signed but excluded from
+the document digest, so both runtimes accept or replay the same reviewed state.
+The receipt attests the receiving runtime; the sender validates exact target,
+revision, digest, status, and timestamp. Delivery does not follow redirects and
+bounds receipt reads to 8 KiB and ten seconds.
+
+Provision the additive `signupControlHeads` namespace before deploying this
+receiver. Its transaction guard serializes concurrent first publications and
+stale work across runtimes. The hub must likewise allocate revisions atomically
+and freeze the document in the same transaction as its per-runtime outbox rows.
+No process should regenerate an old revision from the current catalog on retry.
+
 The document carries the source, exact chapter/environment/Stripe-mode target,
 monotonic revision, ordered and available tiers, immutable Stripe Price ids,
 the membership-page renderer document, and explicitly delegated application,
@@ -629,6 +653,12 @@ join-config, application tier validation, and checkout already read. Public
 application contract, and theme. Applicant requests therefore use local
 last-known-good state and never depend on the hub being reachable.
 
+A successful empty tier query retains legacy single-tier compatibility.
+Database failures, malformed responses, and missing stored prices fail closed;
+they never invent a free membership. Retiring all stored tiers leaves no offers
+instead of reviving the group's legacy price. Public Worker routes return
+`503` with `tiers_unavailable` for this failure rather than charging a fallback.
+
 #### One field contract for follower forms and CMS management
 
 Chapter owns field identity and storage authority; a hub such as Built Not
@@ -1502,18 +1532,141 @@ These bite silently — a smoke test won't catch them:
   method, auth, request, response shape, units, status, and header parity are
   proven. Equal values with different JSON contracts are not compatible. For a
   join flow, adopt `JoinIsland` end to end or keep an explicit tested adapter;
-  do not merely repoint an existing page at `/api/join-config`. `PaymentStep`
+  do not merely repoint an existing page at `/api/join-config`. `JoinIsland`
+  now posts to `/api/payments/quote?application=<id>` before exposing
+  membership payment consent. The quote uses the application's recorded tier,
+  not a URL selection, and includes its amount, currency, policy, and digest.
+  Optional signed `policy.tierPolicies` overrides supply refund/trust copy for
+  declared tier IDs. Checkout validates a supplied quote digest before provider
+  writes; a changed quote must be shown and accepted again. The accepted quote
+  is frozen with the checkout intent so later catalog edits cannot silently
+  change an in-progress purchase. Hosts upgrading the complete join client can
+  set `chapterWorker({ chapter, requirePaymentQuote: true })` to reject older
+  requests without a digest. The default preserves old published clients; new
+  membership `JoinIsland` clients always send the digest. Gift purchase and inert
+  simulation flows retain their separate contracts. The standalone `PaymentStep`
   obtains Stripe's `clientSecret`, `publishableKey`, and `lineItems` from
   `POST /api/payments/subscription`, not from the public join-config response.
+  Subscription setup verifies Stripe's immutable amount, currency, recurrence,
+  quantity model, and test/live mode before creating a customer or subscription.
+  A saved subscription is retrieved by ID on replay and checked against the
+  customer, runtime partition, original invoice, and Price; it is never recreated.
+  An ambiguous create with no saved provider ID stops after 23 hours with
+  `checkout_recovery_required`, before Stripe can prune its idempotency key.
+  Reconcile that exact purchase before retrying; do not clear its intent to force
+  another charge.
+  For intent-backed first invoices, the signed webhook also verifies the exact
+  subscription, customer, paid amount, currency, and invoice status before
+  advancing membership or applying an interview waiver. A webhook arriving
+  before the checkout-ready write returns a retryable response. Mismatched
+  evidence is quarantined without sending payment notices or granting access.
+  Renewal dates come from an unambiguous recurring invoice line, not whichever
+  line Stripe happens to list first; manual and proration/update invoices do not
+  renew membership.
+
+  The internal provider adapter can freeze separate, versioned percentage-coupon
+  terms alongside the base recurring Price. An optional extended initial term
+  charges a full up-front invoice item and defers recurring billing to the frozen
+  service end. This uses Stripe's trial anchor mechanically, **not** a free
+  membership: access still requires the verified paid invoice. The coupon must
+  match the exact app/environment/runtime and policy version; a missing coupon
+  is provisioned idempotently and restricted to the verified membership product,
+  so it cannot also discount a named seat.
+  Only first-invoice and continuing coupons are supported; arbitrary timed
+  discount expiry is rejected rather than silently becoming permanent. These
+  adapter terms are not a public join-config override. A host may opt into
+  `chapterWorker({ chapter, membershipAuthority: adapter.authority })`, where
+  `adapter = createMembershipWorkerAdapter({ chapterId, secretName, makeDb,
+  targetUrl, fetch, namedSeats })` comes from `@odla-ai/chapter/worker`.
+  The factory wires payment, approval, refund, renewal, current access, and
+  optional named-seat operations through the same exact runtime edge. `fetch`
+  and `targetUrl` resolve from the host environment; an absent configured
+  binding fails closed and never falls back to a different deployment.
+  All callbacks must target the same network authority scope, never a local
+  shadow ledger. They may use `requestMembershipCommercialOffer` and
+  `requestMembershipCheckoutBinding`, `requestMembershipPayment` and
+  `requestMembershipApproval` against an authenticated existing service,
+  or invoke the corresponding network commands in process. This API does not
+  require or provision a new app or Worker.
+
+  With that adapter configured, POST prepares a durable offer projection before
+  returning consent terms; GET only reads an existing quote. A lost issuer reply
+  reuses the persisted request identity. An unexpired quote survives later
+  catalog changes. An expired quote can be replaced only before a checkout
+  intent exists; changed terms require fresh consent. The base chapter Price
+  must match the authority offering's amount, currency and recurrence.
+  After consent, a durable network binding fixes the application, offer, Price
+  and quote before any Stripe I/O. Conflicting bindings, unavailable authority,
+  and legacy intents without an offer fail closed. An existing binding can
+  replay after offer expiry, but does not itself assert payment or grant access.
+  Never delete an ambiguous checkout intent to obtain a new quote or purchase.
+  Install the chapter projection schema before deploying the updated client;
+  install `createMembershipAuthorityIntegration()` only in the network owner's
+  existing database (BNF), alongside its policy and verified commercial-event
+  integrations. It creates eight deny-all collections with no activation seeds.
+  Pair it with `createMembershipAuthorityStorage(db, allowedSecretNames)` from
+  the Worker entry: this maps the command model's three `network*` collections
+  to `membershipRecord`, `membershipEntitlement`, and `membershipSeat`, leaving
+  the original shadow collections unchanged. Atomic guards and mutation IDs
+  are preserved. Do not mix this descriptor with raw `membershipOfferEntities`
+  or `membershipAuthorityEntities`, or use its storage without the descriptor.
+  `createMembershipAuthorityHandler` may be mounted in the existing BNF backend;
+  no additional app/database is required. It accepts only signed, exact-scope
+  commands, never arbitrary database operations or role grants. The storage
+  adapter is a defensive contract, not a security boundary against a compromised
+  host holding its unrestricted app key. Protected superadmin changes remain
+  exclusively in odla Studio. `memberSystemAvailability` requires explicit
+  `bnfBackendReachable` independently of `bnfFrontendReachable` and odla health;
+  absent backend health fails dependent workflows closed.
+  Network policy/cohort writes must fence `membershipAuthorityState.revision`.
+  Both the chapter and network Stripe destinations must subscribe to
+  `invoice.payment_succeeded` before enabling the adapter. Its membership flow
+  ignores `invoice.paid` because that event also includes out-of-band payments.
+  The network independently verifies the event, scope, provider references and
+  frozen amount before atomically creating a pending membership/entitlement.
+  A chapter webhook arriving first retries without advancing paid status.
+  Durable chapter Journey approval then obtains the network member number and
+  active entitlement before Clerk promotion; duplicate approvals do not spend
+  another number. Already-paid founding promises can exceed the soft target.
+  Full renewal/refund/seat lifecycle wiring and live provider journey proof
+  remain prerequisites for enabling this adapter in a host.
+
+  `drainMembershipEffects` recovers pending provider work and expires unpaid or
+  unaccepted seats within one exact configured runtime. Pair its
+  `deliverChapterEffect` callback with `deliverMembershipChapterEffect` and a
+  chapter `createMembershipChapterEffectRoute({ sender, secretName, origin,
+  readEffect: adapter.readEffect })`. The receiver reloads current network state
+  before inviting, granting or revoking; a stale queue item cannot specify an
+  arbitrary recipient or grant access. Missing adapters and ambiguous provider
+  receipts remain pending. `retryChapterApprovalEffects` separately repairs
+  durable, unfinished local approval work without starving later applicants.
+  Neither helper installs a cron or provisions infrastructure by itself.
+
+  The member area exposes the authenticated purchaser's named-seat checkout
+  only when configured. Recipient hosts pass `initialNamedSeatId` from the
+  invitation's `seat` query parameter and an authenticated `namedSeatClaimApi`
+  to `JoinIsland`; the recipient completes their own application and acceptance
+  without a second subscription checkout. A primary cancellation also governs
+  seat renewal; buying a seat does not restore canceled auto-renewal.
+
+  Delivery logs distinguish sent, logged-only, in-flight, uncertain and
+  retry-approved outcomes. The authenticated operator resolution route
+  `/api/admin/email/log/:id/resolve` records evidence against the exact attempt;
+  it never sends mail. Confirmed non-delivery permits only the original workflow
+  to retry its frozen payload. Non-production recipient redirection still applies.
 
 ### Install + scope notes
 
-- **Bootstrap the first admin according to the selected auth source.** Chapter
-  mode defaults to Clerk claims: set the first operator's Clerk
-  `public_metadata.role` to `admin`. If that operator also needs the
-  super-admin tier, prefer `auth: { superAdminSource: "odla" }` and grant their
-  app-scoped role on Database → Users in odla Studio. Existing sites retain the
-  legacy `superAdmins` table until they opt in. Hub mode defaults to table auth:
+- **Bootstrap the first admin according to the selected auth source.** Prefer
+  `auth: { source: "clerk", superAdminSource: "odla" }`: the backend resolves
+  `private_metadata.role` on each authorization check, ignores public/session
+  roles, and fails closed if Clerk is unavailable. Grant the operator's
+  app-scoped protected role on Database → Users in odla Studio, bound to the
+  exact Clerk subject ID (not email). This protected grant is separate from
+  their private Clerk `admin` role and is never imported from legacy metadata.
+  Existing Chapter sites retain claim/public-role defaults until an explicit,
+  coordinated migration; do not clear public roles while a peer runtime still
+  depends on them. Hub mode defaults to table auth:
   add the first operator's lowercase
   email to `admins` in Studio. Neither allowlist is ever written by a worker
   route or provisioning seed; that is deliberate, so the running app cannot
@@ -1541,9 +1694,17 @@ These bite silently — a smoke test won't catch them:
   - **Roster/identity:** `GET /people` (union of `$users` + applications by email,
     roles and backend-only profile signals from `clerkListUsers`),
     `GET /people/access`, `POST /people/role`, `POST /crm/sync`
-    (backfill/reproject), and
+    (empty body: backfill/reproject; `{ recordId }`: repair only that person's
+    missing application link). Targeted repair requires a unique application
+    and CRM person match in this chapter, preserves profile and lifecycle state,
+    and records an audited compare-and-swap update. Ambiguity fails closed. The
+    Stage panel offers this repair when an application link is missing. Also,
     `POST /clerk/private-profiles/sync?offset=0&limit=50` (bounded,
     resumable migration/repair from Chapter's former public profile keys).
+    New default chapter CRMs declare `applicationId` and `tier`; initial applicant
+    projection preserves these links even if optional enrichment is invalid.
+    Submission replays use the canonical stored application, and reject changed
+    email before account provisioning, notifications, or CRM projection.
   - **Pipeline/meetings:** `GET /dashboard` (flow counts, stage counts + weekly
     delta, agenda, live revenue), `GET /meetings` (reconciled agenda),
     `GET/PUT /scheduling`, `POST /meetings/:id/{reschedule,cancel}`,
@@ -1564,6 +1725,25 @@ These bite silently — a smoke test won't catch them:
   }});
   ```
 
+  Refund execution is subscription-scoped: the provider verifies the customer and
+  the admin route's exact application/chapter/environment/runtime metadata, then
+  resolves the subscription's first paid invoice. It never picks an arbitrary
+  customer charge or moves to a renewal when the original charge was refunded.
+  Modern invoice-payment records and legacy invoice charge/payment-intent fields
+  are supported; ambiguous payments or incomplete history fail closed. Retries
+  reuse a stable refund key and can finish cancellation even after the refund
+  webhook updates the application. A partial `charge.refunded` event is not a
+  terminal membership or gift event. Customer-only refund events are quarantined
+  for reconciliation rather than guessed from a customer's latest application.
+  Before reporting success, the refund command re-reads the exact charge and
+  verifies a completed full refund, then reconciles the application and CRM.
+  This also repairs older payments whose charge events lack application metadata;
+  a pending refund is not reported as complete. Closed billing has no renewal date.
+  New checkouts resolve legacy or modern InvoicePayments and verify/tag the exact
+  PaymentIntent before exposing its client secret. Missing, foreign, or ambiguous
+  payment evidence fails closed. Booking enforces the same payment and waiver
+  eligibility as the signup wizard, including on direct endpoint requests.
+
   The escalation rules (super-admin tier, self-demotion lockout) are **not** seams
   — `canChangeRole` package-enforces them so a site can't weaken them. `approve`
   is the caller `onboardingInvite` was missing.
@@ -1573,18 +1753,27 @@ These bite silently — a smoke test won't catch them:
   the odla→Clerk write half: `clerkGetUserByEmail`, `clerkGetUser`,
   `clerkListUsers` (auto-paginated — never a silent 100-user cap),
   `clerkSetRole`, `updateClerkUserMetadata`, and
-  `updateClerkUserMetadataByEmail`. An absent `public_metadata.role` reads as
-  the lowest rung (`"provisional"`); normalized `profile` and `applicationId`
-  reads come only from backend-only private metadata; and `clerkSetRole`
-  merge-`PATCH`es only the public role, so it cannot clobber the private profile.
-  All take an injectable `fetch` and the vault `clerk_secret_key`.
+  `updateClerkUserMetadataByEmail`. Role helpers accept a final metadata source
+  (`"private"` or legacy `"public"`, after the injectable `fetch`); use
+  `clerkRoleMetadata(chapter.auth)` so readers and writers agree. An absent
+  selected role reads as `"provisional"`. Private role writes merge only that
+  key and remove the legacy public role, preserving private profile data.
+  Helpers use the effective vault `clerk_secret_key`; no extra credential is
+  needed. `planPrivateRoleMigration` is a dev-only, dry-run preflight requiring
+  the complete active runtime inventory, paused role writers, compatible builds,
+  and an existing protected operator grant. It rejects conflicting roles and
+  never grants privileges or writes data. Follow the adoption runbook for
+  coordinated migration and same-session revocation tests.
 
 ### Multi-site acceptance tests
 
 `@odla-ai/chapter/testing` exports a schema-validated manifest, scenario planner,
 public join-contract probe, serial suite runner, and text report formatter.
-Declare every logical chapter and every authoritative developer runtime in the
-manifest; runtime identity is separate from Stripe test/live mode.
+Declare every logical chapter in the reviewed deployment scope and its exact
+developer runtime. Another developer's authoritative sandbox is not implicitly
+a deployment prerequisite or a target for writes. Keep sibling-runtime isolation
+tests without requiring deployment access to those siblings. Runtime identity is
+separate from Stripe test/live mode.
 
 - `probeChapterJoinContracts(manifest)` reads deployed health and catalog routes.
   It compares effective app/chapter/data-environment/runtime health headers with
@@ -1606,6 +1795,29 @@ manifest; runtime identity is separate from Stripe test/live mode.
 - Evidence is copied only after validation. Extra fields and rejected payloads
   are discarded; check labels must contain no personal data, and references must
   be opaque provider IDs or digests, never client secrets or raw provider objects.
+- `assessChapterReleaseEvidence(plan, proofs)` validates a separately reviewed
+  required-proof contract against exact source commits and dev Worker versions.
+  Missing features must remain requirements even if current feature flags are
+  off. Missing/duplicate proofs, wrong execution phases or runtimes, failed
+  assertions, absent provider references, and incomplete cleanup block review.
+  This checks evidence completeness, not whether a driver actually called a
+  provider; real driver execution and inspectable artifacts remain mandatory.
+  A complete result is only `readyForReview`; `productionAuthorized` is always
+  false, and this API never deploys anything.
+
+Host routes can reuse `resolveNetworkTargetTransport` from the Worker entry
+for public discovery as well as signed delivery. A declared service binding is
+authoritative: missing or invalid bindings throw `NetworkTargetTransportError`
+instead of falling back to a public URL. Hosts remain responsible for selecting
+the reviewed runtime/origin and bounding response size and duration.
+
+`ChapterAdmin.renderWorkspaceFrame` replaces packaged workspace geometry with
+a host-owned frame. It receives the already-composed active content, workspace
+list (including optional icons), current account and native route/navigation
+helpers. Custom headers remain outside the frame; auth and active-only mounting
+stay in Chapter. Hosts need no per-workspace renderer wrappers or duplicate
+navigation registry. Without the slot, existing tab and standalone layouts stay
+unchanged.
 
 ### Verify from the types, not this file