sporades 0.9.0 → 0.9.2

package/CHANGES.md

@@ -1,116 +1,64 @@
 # Changes
 
-## Unreleased - 2026-08-21
+- Expose the verified provider-free Team Billing projection to active Capsule
+  query and mutation contexts and to exact-Team Join admission. Current members
+  may be authorized for safe reads while all customer-directed commands remain
+  current-Team-admin operations; retained context handles are revoked.
+- Add an offline `sporades/server/team-billing-import` seam for exact,
+  provider-free import of verified legacy Subscription snapshots and replay
+  guards. Incomplete or conflicting evidence fails closed, including drift in
+  durable Event ordering, terminal-latch safety fields, and contradictory
+  Subscription Event/state tuples. The public adapter type now declares the
+  complete named-dialect, execution, prepared-statement, and transaction seam.
 
-Changes since v0.8.7.
+## Unreleased - 2026-08-24
+
+Changes since v0.9.0.
 
 ### 🚀 Features
 
-- Allow token-shaped Access-key metadata (7211528).
-- Implement verified Stripe event policy delivery (7a68cbe).
-- Implement signed Stripe callback admission (8721c85).
-- Add access key operator controls (08161a6).
-- Add durable Stripe Customer Portal sessions (8a3a604).
-- Preserve access key provenance in jobs (9d1cd62).
-- Add scoped access key file reads (a1033cf).
-- Add browser access key management (7859ecd).
-- Complete owner access key lifecycle (d9c72ab).
-- Implement durable one-time Stripe Checkout (79da915).
-- Add user-owned scoped access keys (2ede8b3).
-- Add declarative session auth admission (a62c566).
-- Preserve exact endpoint body bytes (0968c99).
+- Expose verified billing state to capsule policy (946f0736).
+- Add safe legacy Team Billing import seam (dab78ad9).
+- Add provider-safe Team Billing erasure (9d334c0c).
+- Add managed Team Billing convergence (ebdfd265).
+- Add explicitly configured Team Customer Portal (760e5c4d).
+- Add durable headless Team Checkout (4738b0fb).
+- Add headless Team Billing foundation (57670d13).
+- Add atomic Stripe consequence handling (04274543).
 
 ### 🐛 Bug Fixes
 
-- Fix Stripe callback and Vanilla policy gaps (6b5792f).
-- Bound hosted inspection diagnostics (84977d0).
-- Preserve bounded host inspection failures (5ff9e59).
-- Bind privileged key work to run lifetime (1c201e4).
-- Close operator audit and output gaps (16669ee).
-- Harden access key operator boundaries (a8a6e99).
-- Reject malformed schedule provenance (04d5528).
-- Bind scheduled jobs to privileged actors (f0945a8).
-- Validate scheduled job actor provenance (5f984a4).
-- Harden durable job provenance (5023593).
-- Redact file scope denial provenance (9947213).
-- Correlate access key response loss (a9ed599).
-- Recover access key management failures (e3d42d1).
-- Require sessions for owner security changes (79e99ae).
-- Close first-key transition races (90472d8).
-- Serialize access key owner transitions (effce34).
-- Privatize access key runtime state (f091dd8).
-- Preserve middleware access key state (8d27903).
-- Isolate lifecycle audit delivery (ebc095a).
-- Commit access key lifecycle audits (e6b0a6d).
-- Preserve access key provenance (4f87ed6).
-- Isolate access key admission (48fe0a5).
-- Preserve guarded handler type safety (9496593).
-- Harden declarative auth admission (1d35da1).
+- Prove Stripe test Team Billing lifecycle (2aedbbcb).
+- Fix packed blank Capsule typechecking (1662dd27).
+- Prevent Stripe retention repair starvation (671f9537).
 
 ### 📝 Documentation
 
-- Preserve legacy auth profiles in job provenance (549542e).
-- Revalidate owner Sessions and trust Cloudflare clients (ca43887).
-- Keep Stripe event idempotency stable across renames (a86758e).
-- Normalize access key report metadata (95bec68).
-- Fix access key endpoint examples (d3098bd).
-- Publish scoped access key guide (0cf7f8e).
-- Define completed ticket state (b4c4dc8).
-- Normalize access key ticket evidence (491a042).
-- Record access key adapter identities (14277b7).
-- Correct access key proof attribution (a8eadaa).
-- Record access key release completion (779256b).
-- Prove and pack the built-in Stripe payment contract (655e656).
-- Publish access key authority contract (b6efd20).
-- Close access key operator ticket (27877d5).
-- Close durable job provenance ticket (14bcd01).
-- Close access key file reads ticket (7a94f2a).
-- Close browser access key management ticket (42a8520).
-- Extend Stripe Checkout to subscriptions (8d1c72c).
-- Close access key lifecycle ticket (6f06be7).
-- Close scoped access key tracer (c041fa8).
-- Close auth admission ticket (75c817f).
-- Build dormant blank Capsule Stripe foundation (6c0e683).
-- Specify user-owned scoped access keys (8325d69).
+- Clarify private Team billing retention (8db4f2f8).
+- Expose safe Team billing quarantine inspection (0dd71f85).
+- Harden Team billing evidence validation (7b91b311).
+- Converge verified Team billing state atomically (f962d06c).
+- Document unrepresentable Stripe retention (27a852f1).
+- Prove Stripe contention across runtimes (1ed35c38).
+- Preserve cancellation and exact Stripe retention (c8591c52).
+- Defer atomic Stripe fence contention durably (47e93072).
+- Expose Team counts to atomic Stripe consequences (9f43dbe7).
+- Periodically recheck Stripe retention repairs (9e5908e8).
+- Recover classified Stripe retention repairs (f6c853f9).
+- Harden Stripe payload retention cleanup (0b163187).
+- Bound Stripe Event Job payload retention (cf2cf6eb).
+- Harden atomic Stripe consequence recovery (92b55f5d).
 
 ### 🧪 Tests
 
-- Revalidate linked Access-key owners (751ee7f).
-- Bound escaped Access-key operator envelopes (099a5a1).
-- Revalidate Sessions during Access-key rotation (79d3e6c).
-- Make Privileged Access-key writes audit-atomic (1737023).
-- Timestamp Access-key revocation after locking (3b70301).
-- Preserve valid Schedule diagnostic names (a002b25).
-- Close Access-key authority and issuance races (f118728).
-- Recheck Access-key expiry inside rotation locks (70d4c0c).
-- Enforce no-store after endpoint header merging (bf50484).
-- Bind File Access-key tests to live Sessions (7e63a82).
-- Require live Session authority for Access-key management (155f154).
-- Revalidate Sessions during Access-key issuance (3a9288e).
-- Harden Access-key operator and Hosted limits (0d5f10c).
-- Make Access-key operator audits atomic (3e972ac).
-- Verify acceptance container cleanup (82ac350).
-- Gate raw container cleanup fallback (235ac72).
-- Bind acceptance cleanup to container id (0dff342).
-- Report suite failures before missing proof (27d8f62).
-- Reconcile JUnit suite outcomes (a19bb41).
-- Recognize required JUnit suites (1dace92).
-- Tokenize junit cases once (1951edd).
-- Prove admitted jobs survive key retirement (717da14).
-- Harden Stripe Checkout authority boundaries (c94fc74).
-
-### 📦 Packaging
-
-- Separate documentation validation from full suite (3863ac1).
-- Harden release acceptance cleanup (b431ab4).
-- Keep release failures opaque (9041772).
-- Report bounded release failure details (b869c92).
-- Report release suite failures (5dea6d8).
-- Reconcile release junit evidence (2f9f8fe).
-- Fail closed on release evidence (6f5b0a7).
-- Require access key release evidence (ddd3b47).
-- Close access key release proof gaps (62cc34b).
-- Prove access key release contract (c29c725).
+- Preserve Team Portal capability across transient reads (7ffba828).
+- Revalidate Team Portal authority at every seam (fcb4380e).
+- Reconcile Checkout state after final lease expiry (c51ab5f7).
+- Terminally settle exhausted Team Checkout retries (6fcb803f).
+- Serialize Team Billing authority with Team lifecycle (987a4750).
+- Validate Team Billing projection semantics (e7f05b20).
+- Fail closed on Team Billing correlation drift (003e24af).
+- Classify near-ceiling Stripe settlement (92cba517).
 
 ## 0.8.5 - 2026-08-15
 

package/README.md

@@ -58,7 +58,32 @@ sporades host push --restart
   email-bound Join links, membership application roles, and explicit Team ACL
   decisions—without a hidden current Team or automatic data partitioning.
   Trusted `teams.admitJoin` policies may make atomic seat decisions from
-  read-only app state hidden by the joining user's ordinary row ACLs.
+  read-only app state hidden by the joining user's ordinary row ACLs and the
+  exact Team's provider-free verified billing projection.
+- **Headless Team Billing, app-rendered**: an optional `teamBilling` declaration
+  binds stable product keys to exact sandbox/live Stripe Prices and a fixed or
+  accepted-Team-member quantity policy. Sporades rechecks current Team-admin
+  authority plus the Capsule's transaction-bound policy on every operation and
+  exposes the closed, provider-free `teamBilling.get(teamId)` projection plus
+  durable `teamBilling.startCheckout(...)`, `teamBilling.openPortal(...)`, and
+  `teamBilling.requestPlanTransition(...)`. Portal owns compatible same-policy
+  switches; Sporades manages fixed-to-Team-counted transitions and keeps a
+  Team-counted Subscription converged after membership commits.
+  `teamBilling.prepareErasure(...)` durably expires or safely resolves every
+  issued Checkout and immediately cancels known or newly discovered live
+  Subscriptions before a transaction-bound server admission permits the app's
+  separate local deletion. Provider-free identity tombstones reject late
+  entitlement recreation; the Stripe Customer is not deleted.
+  Those commands may return only validated, short-lived Stripe-hosted URL
+  capabilities. Verified Checkout, Subscription, and failed-invoice evidence
+  converges through runtime-owned semantic ratchets and terminal latches;
+  malformed or ambiguous evidence fails closed without exposing provider
+  identifiers. The Capsule owns every component, route, message, and
+  entitlement decision.
+  Offline migration tools can import complete verified legacy snapshots and
+  provider-free replay guards through `sporades/server/team-billing-import`;
+  the seam performs no provider I/O and rejects incomplete or changed tuples,
+  including corrupted durable Event ordering or terminal-latch state.
 - **Realtime everything**: configuration free - automatic notifications, even for Postgress and AWS-S3
 
 ## Documentation
@@ -68,7 +93,8 @@ sporades host push --restart
 - [Feature reference](https://mgscox.github.io/sporades/guide/reference): exhaustive contracts and
   command lookup, split into focused topic pages.
 - [Built-in Teams](https://mgscox.github.io/sporades/reference/teams): collaboration model, Join
-  links, application roles, and explicit Team ACL decisions.
+  links, application roles, explicit Team ACL decisions, and the headless Team
+  Billing declaration and safe projection.
 - [Access-key server and operator reference](https://mgscox.github.io/sporades/reference/server-runtime#gate-handlers-with-requireauth):
   scoped Bearer admission, user-owned lifecycle, Credential provenance, and
   the bounded operator CLI.
@@ -169,9 +195,19 @@ Sporades currently includes:
   retries converge and no Capsule billing state changes automatically. The Job
   delivers one Verified Stripe event to the blank Capsule's single
   `stripeEvents: stripeEvent(...)` policy seam under the userless Privileged
-  audit lifecycle. Generated policy ignores unknown events and tells authors to
+  audit lifecycle. Capsules that need one serialized, all-or-nothing database
+  consequence can opt into `stripeEvent({ consequence: "atomic" }, handler)`;
+  the legacy declaration remains available for cooperative long-lived handlers.
+  Generated policy ignores unknown events and tells authors to
   make deliberate consequences idempotent and order-independent, reject stale
   later-arriving observations, and avoid logging or retaining raw provider data.
+  A successful reserved Stripe Event Job retains its verified payload for 30
+  days, then bounded runtime cleanup leaves only the digest-backed terminal
+  replay tombstone. Unresolved deliveries retain their retry/repair payload;
+  this includes legacy successes with absent or malformed completion timestamps,
+  plus canonical near-ceiling settlements whose exact deadline is
+  unrepresentable. Safe operator inspection distinguishes those cases without
+  exposing provider data.
   The catalogue owns each Price mode; browser input owns neither mode nor Stripe
   identity. Existing and non-blank Capsules remain unchanged.
 - Local Dev sessions with rebuilds, WebSocket reconnects, SQLite persistence,

package/bin/sporades-host-helper.js

@@ -177,8 +177,24 @@ var ACCESS_KEY_CLIENT_ADDRESS_HEADER = "x-sporades-client-address";
 // src/access-keys-runtime.ts
 var UNKNOWN_ACCESS_KEY_DIGEST = Buffer.from("4f7c77f7b9231094754542ed50fdfd62a2cf24a5e961b61f899b85b6fe33c72b", "hex");
 
+// src/team-billing-management.ts
+var CLAIM_TTL_MS = 5 * 60 * 1e3;
+
+// src/team-billing-convergence.ts
+var RANK = Object.freeze({ active: 20, cancelling: 30, "past-due": 40, cancelled: 50 });
+
+// src/team-billing-runtime.ts
+var CHECKOUT_CONTINUATION_TTL_DEFAULT_SECONDS = 10 * 60;
+var CHECKOUT_CONTINUATION_TTL_MAX_SECONDS = 30 * 60;
+
+// src/team-billing-erasure.ts
+var CLAIM_TTL_MS2 = 5 * 6e4;
+
 // src/jobs-runtime.ts
 var nodeCryptoModule = process.getBuiltinModule("node:crypto");
+var STRIPE_EVENT_PAYLOAD_RETENTION_MS = 30 * 24 * 60 * 60 * 1e3;
+var REDACTED_STRIPE_EVENT_PAYLOAD = JSON.stringify({ kind: "stripe-event", retained: false });
+var STRIPE_EVENT_PAYLOAD_SENTINEL_RECHECK_MS = 24 * 60 * 60 * 1e3;
 var JOB_AUTH_SNAPSHOT_MAX_BYTES = 8 * 1024;
 var MAX_JOB_TIMESTAMP_MS = Date.parse("9999-12-31T23:59:59.999Z");
 var MIN_JOB_TIMESTAMP_MS = Date.parse("0000-01-01T00:00:00.000Z");
@@ -440,6 +456,8 @@ var transactionBeforeCommitChecks2 = Symbol.for("sporades.database.transactionBe
 // src/server-runtime-source.ts
 var trustedReadTransactionAdapter = Symbol("sporades.trustedReadTransactionAdapter");
 var runtimeOwnedJobEnqueueHandler = Symbol("sporades.runtimeOwnedJobEnqueueHandler");
+var atomicStripeEventDefinitionBrand = Symbol.for("sporades.stripeEvent.atomicDefinition");
+var atomicStripeFenceContention = Symbol("sporades.atomicStripeFenceContention");
 function logPayloadMaxBytes(config = {}) {
   const configured = Number(config.logs?.payloadMaxBytes ?? config.logging?.payloadMaxBytes);
   return Number.isInteger(configured) && configured > 0 ? configured : 4096;
@@ -595,7 +613,7 @@ function writeEnvelope(result, failed = false) {
 }
 
 // src/cli/cli-version.ts
-var CLI_VERSION = "0.9.0";
+var CLI_VERSION = "0.9.2";
 
 // src/cli/schedule-inspection-envelope.ts
 var SCHEDULE_DIAGNOSTIC_FIELDS = /* @__PURE__ */ new Set([