@volter/twin-polar 2.0.37 → 3.0.0

package/dist/journeys/customer-life.outline.md

@@ -0,0 +1,69 @@
+# polar customer life: outline
+
+## The customer
+
+**Volter** takes its money in through one Polar organization (../journeys/demand.json). Two of its products call it.
+**Volter World's platform** bills through its biller (twin-world `apps/billing` at `96ca4478bb39`, `@polar-sh/sdk`): at
+boot it finds or makes its meters and its Team plan by name; an org upgrades on Polar's hosted checkout, its org id the
+customer's external id; the biller reads an org's plan and usage from Polar's customer state by that id, reports usage
+as events each carrying its own id so a retry never counts twice, and opens the customer portal for Manage billing.
+**Open Autonomy** takes patronage (open-autonomy `apps/platform/src/polar.ts` at `0841076bed91`, REST over fetch): it
+makes each project tier's monthly and one-time products, sends a patron to Polar's checkout, and learns of a paid order
+twice, from the signed `order.paid` webhook and from its thanks page, which reads the checkout, its orders and the
+order's customer back.
+
+The World clock starts 2026-01-01. This organization, its credentials and records are in production; buyers receive only checkout URLs or their own session tokens.
+
+## People and programs
+
+| who | holds | how |
+|---|---|---|
+| Lena Ortiz, Volter's operator | authority over this organization's token and webhook settings | makes the platform's Organization Access Token (door), registers Open Autonomy's webhook endpoint (API) |
+| the platform's biller | the organization's OAT, granted read/write scope over its meters, products, checkouts, customers, customer sessions and events | @polar-sh/sdk |
+| Open Autonomy's platform | the organization's OAT, granted products/checkouts write, orders/customers read and webhook settings scope; endpoint secret for verification | fetch |
+| Ada (Acme Robotics, Acme Labs), Globex's admin | their own org's billing page; authorization over only their checkout and customer session | the biller's checkout and Manage billing |
+| Grace, Heidi | their card on Polar's page; authorization over only their checkout | Polar's hosted checkout, from Open Autonomy's give button |
+
+## The arc
+
+### 1. Setting up (Mon 5 Jan)
+Lena makes the platform's token. The biller boots: it lists the meters (`meters:list`), finds none and makes `world_hours` (the sum of
+each `world.hour` event's units) and `worlds_provisioned` (a count) (`meters:create`); it lists the products
+(`products:list`), finds none and makes the Team plan (`products:create`): $49 a month, 2 cents a world-hour beyond
+the plan on the hours meter, a 14-day trial. At its next boot it finds both by name.
+
+### 2. An org upgrades (Tue 6 Jan)
+The biller reads Acme's billing by its org id (`customers:get_state_external`): Polar has no such customer (404), so
+Acme is on Free. Ada chooses Team: the biller opens a checkout with Acme's org id as the customer's external id
+(`checkouts:create`); Ada opens its url, Polar's checkout page (`checkouts:client_get`), and supplies payment details
+(`checkouts:client_confirm`), back to the billing page. The trial starts without an immediate charge. Acme's state now holds the Team subscription, trialing.
+
+### 3. Usage (Wed 14 Jan)
+Acme creates a World and the biller reports it. Two hours later the biller reports the completed world-hours (`events:ingest`); a retried tick sends the last hour again and
+Polar counts it a duplicate. Acme's state shows two world-hours consumed.
+
+### 4. Manage billing (Mon 2 Feb)
+Ada opens Manage billing: the biller makes a customer session for Acme by its org id (`customer-sessions:create`), and
+she follows its returned portal URL and sees her subscription, now active after its trial ended, and purchase history. Polar charged her when the trial ended on 20 January; calendar-month renewals create subsequent paid orders. Next day Globex, on Free, is refused a session the same way; support asks Lena to create Globex its customer by its org id; then the biller can create its session. The biller's isNotFound check accepts status 404 or an error message containing not found or 404. Polar documents this validation as 422; whether its fallback runs depends on the actual error message. This session error does not match, so support intervenes.
+
+### 5. Patronage (Tue 10 to Thu 12 Feb)
+Lena registers Open Autonomy's webhook endpoint when patronage launches, for order.created and order.paid; future events of the whole organization reach it, including billing orders it cannot settle without patronage metadata. Open Autonomy makes acme/rover's first tier, monthly and once (`products:create`). Grace gives once: Open Autonomy
+opens her checkout (`checkouts:create`), back to its thanks page with `{CHECKOUT_ID}`; she leaves the tab for 25 hours while talking to the maintainer, tries to pay after expiry (410), returns to the application for a fresh checkout, pays and
+returns on Wednesday 11 February with the checkout's id. Polar tells Open Autonomy the order was made and is paid (`order.created`,
+`order.paid`, signed with the endpoint's secret). The thanks page reads the checkout back (`checkouts:get`), its orders
+(`orders:list`) and the order's customer (`customers:get`). Next day, Thursday 12 February, Heidi gives monthly: her paid order is the first of a subscription.
+
+### 6. A leaked token (Thu 16 Apr)
+The platform's token is revoked on the settings page; the old one is refused and a new one works.
+
+### 7. A vendor-backed refresh reads the organization back
+With the new token, a World rooted at this organization reads back what the manifest refreshes: the webhook endpoints
+(`webhooks:list_webhook_endpoints`, its secret), the checkouts newest first (`checkouts:list`: Heidi's succeeded), the
+subscriptions the latest started first (`subscriptions:list`: Heidi's active, Acme's Team), the customers newest first
+(`customers:list`) and the usage events (`events:list`: Acme's World and two hours, the
+retried hour not a third).
+
+## What the life does not do
+The meters' and webhook endpoints' reads by id and changes, checkouts' update, orders' reads by id, the
+subscriptions' changes, benefits, discounts, refunds, checkout links, the customer portal's email sign-in, settings, cancellation, invoices and payment-method changes, and its API, and every
+other operation no application of the demand calls.

package/dist/journeys/customer-life.outline.verdict.json

@@ -0,0 +1,41 @@
+{
+  "sha256": "367d63fa0038e0258dc0e473b5adb706e45d5f210c86766a5ba8b6e0449973e6",
+  "plausible": true,
+  "bar": "829132787d94a2d4",
+  "judge": {
+    "agent": "Contributor 16",
+    "model": "GPT-6 (Codex)",
+    "review": "Independent read-only review, 2026-10-01; did not author these files"
+  },
+  "authors": [
+    "Contributor 39"
+  ],
+  "rounds": 1,
+  "ruledSteps": [
+    "0",
+    "1",
+    "2",
+    "3",
+    "4",
+    "5",
+    "7"
+  ],
+  "rulings": "REJECTED. Exhaustive one-round review against every item of the current judging bar and the vendored spec, published pages, and cached application commits.\nO0. Act 0 (frame): the actor table states what each actor holds but omits its grant. Add the organization's full operational grant for the OAT (the scopes of the served operations), Lena's authority over that organization's token and webhook settings, and each buyer's authorization solely over their checkout or customer session. State the environment consistently with the life. Do not give a buyer the organization's token.\nO1. Act 1: delete the two authentication refusals. Neither has a cause carried out in the story, and they draw the same authentication cause twice consecutively. Keep the legitimate token issuance and successful biller boot.\nO2. Act 2: delete the failed confirmation retry after the successful checkout in the same sitting; the bar explicitly rejects a failing repeat of a request that succeeded earlier in the sitting. Say Ada supplies payment details and starts the trial, without being charged yet (Polar Trials); remove the claim that she pays immediately.\nO3. Act 3: establish that Acme first creates its World, then two hours pass before the reported completed world-hours. The current life creates the World at 15:00 but reports hour identifiers for 10:00 and 11:00 on that same day, before the World existed. Retain the successful duplicate-event retry, which does not fail.\nO4. Act 4: delete the disconnected Acme Labs duplicate-email refusal. No preceding application action initiates a second organization's customer creation. Keep the Globex missing-session, support intervention and successful retry whose cause is carried out. Correct 'the biller only retries 404' to describe the actual isNotFound check at the cached commit: status 404 OR a message matching not found/404; whether a 422 invokes fallback depends on its actual message.\nO5. Act 5: checkout TTL is 24 hours in Polar's published config, read by models/checkout.py get_expires_at, not 1 hour. Make Grace leave the open page for 25 hours before submitting its displayed form; her fresh payment is Wednesday 11 February. Move Heidi to Thursday 12 February, retaining the later 16 April date. Delete the unknown-checkout refusal: the story gives no person or application a cause to manufacture that ID.\nO7. Act 7: keep one complete read per resource by the newly rooted World, which does not already hold the organization. Delete the extra customer-email and event-name filtered reads; after complete lists this same actor has no need for them, and they form an option tour rather than refresh work.\nAll other acts were checked. Sources: docs/contributing/architecture.md What a judge rejects and Writing a life; polar/spec/openapi.json.gz security and Checkout schemas; https://polar.sh/docs/features/subscriptions/trials; https://github.com/polarsource/polar/blob/main/server/polar/config.py CHECKOUT_TTL_SECONDS; https://github.com/polarsource/polar/blob/main/server/polar/models/checkout.py get_expires_at; cached twin-world 96ca4478bb39 apps/billing/src/polar.ts isNotFound/portalFor.",
+  "doubts": [
+    "The customer-life frame calls this a year although it ends in April, and the full life does not show leaving the vendor; this is a scope/wording doubt rather than a ruling under the explicit rejection list."
+  ],
+  "applied": {
+    "from": "aab106c801689aad8142bf21fab02224423c1c5d8ff099f23977716ae893787c",
+    "wasPlausible": false,
+    "steps": [
+      "0",
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "7"
+    ],
+    "rulings": "REJECTED. Exhaustive one-round review against every item of the current judging bar and the vendored spec, published pages, and cached application commits.\nO0. Act 0 (frame): the actor table states what each actor holds but omits its grant. Add the organization's full operational grant for the OAT (the scopes of the served operations), Lena's authority over that organization's token and webhook settings, and each buyer's authorization solely over their checkout or customer session. State the environment consistently with the life. Do not give a buyer the organization's token.\nO1. Act 1: delete the two authentication refusals. Neither has a cause carried out in the story, and they draw the same authentication cause twice consecutively. Keep the legitimate token issuance and successful biller boot.\nO2. Act 2: delete the failed confirmation retry after the successful checkout in the same sitting; the bar explicitly rejects a failing repeat of a request that succeeded earlier in the sitting. Say Ada supplies payment details and starts the trial, without being charged yet (Polar Trials); remove the claim that she pays immediately.\nO3. Act 3: establish that Acme first creates its World, then two hours pass before the reported completed world-hours. The current life creates the World at 15:00 but reports hour identifiers for 10:00 and 11:00 on that same day, before the World existed. Retain the successful duplicate-event retry, which does not fail.\nO4. Act 4: delete the disconnected Acme Labs duplicate-email refusal. No preceding application action initiates a second organization's customer creation. Keep the Globex missing-session, support intervention and successful retry whose cause is carried out. Correct 'the biller only retries 404' to describe the actual isNotFound check at the cached commit: status 404 OR a message matching not found/404; whether a 422 invokes fallback depends on its actual message.\nO5. Act 5: checkout TTL is 24 hours in Polar's published config, read by models/checkout.py get_expires_at, not 1 hour. Make Grace leave the open page for 25 hours before submitting its displayed form; her fresh payment is Wednesday 11 February. Move Heidi to Thursday 12 February, retaining the later 16 April date. Delete the unknown-checkout refusal: the story gives no person or application a cause to manufacture that ID.\nO7. Act 7: keep one complete read per resource by the newly rooted World, which does not already hold the organization. Delete the extra customer-email and event-name filtered reads; after complete lists this same actor has no need for them, and they form an option tour rather than refresh work.\nAll other acts were checked. Sources: docs/contributing/architecture.md What a judge rejects and Writing a life; polar/spec/openapi.json.gz security and Checkout schemas; https://polar.sh/docs/features/subscriptions/trials; https://github.com/polarsource/polar/blob/main/server/polar/config.py CHECKOUT_TTL_SECONDS; https://github.com/polarsource/polar/blob/main/server/polar/models/checkout.py get_expires_at; cached twin-world 96ca4478bb39 apps/billing/src/polar.ts isNotFound/portalFor."
+  }
+}

package/dist/journeys/customer-life.verdict.json

@@ -0,0 +1,71 @@
+{
+  "sha256": "43b29c38cd6db33bfe8abb8e733875726f0a56b8843c528297ce55230def4965",
+  "plausible": true,
+  "bar": "829132787d94a2d4",
+  "judge": {
+    "agent": "Contributor 16",
+    "model": "GPT-6 (Codex)",
+    "review": "Independent read-only review, 2026-10-01; did not author these files"
+  },
+  "authors": [
+    "Contributor 39"
+  ],
+  "rounds": 1,
+  "ruledSteps": [
+    "2",
+    "3",
+    "14",
+    "15",
+    "16",
+    "19",
+    "20",
+    "21",
+    "23",
+    "26",
+    "35",
+    "36",
+    "37",
+    "39",
+    "40",
+    "46",
+    "47",
+    "48",
+    "49",
+    "51",
+    "60",
+    "62"
+  ],
+  "rulings": "REJECTED. Exhaustive one-round review of original steps 0 through 62, including credentials, temporal state, captured paths, request content, demanded calls and refusals.\nL1. Steps 2,3: delete both uncaused authentication refusals (the same cause twice consecutively). Record any resulting defensive-branch coverage with a vendor-backed reason rather than contriving a replacement refusal.\nL2. Steps 14,15,16: in 14 capture the form action from the hosted page (the runner supports text:<regex>). In 15 submit that captured action instead of constructing co_url + /pay, and rename the action as supplying payment details and starting a free trial with no immediate charge. Delete 16: a failing repeat of the completed request in this sitting is expressly rejected by the bar; a 'lost response' written only in its title does not override that rule.\nL3. Steps 19,20,21,23: after 19 add a two-hour wait to let the newly created World run. In 20 report completed hour IDs for 2026-01-14T15 and 2026-01-14T16, not T10/T11 preceding creation at 15:00. In 21 retry the actual T16 event. Reduce 23's wait from 27030m to 26910m so it still reaches 2 February 09:30.\nL4. Step 26: delete the disconnected duplicate-email customer creation (no Labs billing/portal request causes it). Keep 28–30, whose refusal has a concrete missing-customer cause and subsequent support intervention.\nL5. Steps 35,36,37,39,40,47,48,49,51: after 35 GET its captured pco_url and capture its displayed Pay form action before Grace leaves the tab. Set 36's wait to 1500m (25 hours), reflecting the vendor's 24-hour TTL. Submit the captured stale form action in 37. In 39 GET pco_url returned by 38 rather than rebuilding buy.polar.sh from the secret; capture its new form action and submit it in 40. Set 47 to Thursday 12 February with wait 1380m (23 hours after Grace returns at Wednesday 11 February 10:30). After 48 GET its returned mco_url and capture the displayed form action; submit it in 49. Set 51's wait to 90720m to retain Thursday 16 April 09:30. The new page-read after 35 and after 48 belong to those original step numbers for apply-rulings. Fix the twin TTL along with the life, using Polar's published config/model source; never hide the twin's 1-hour expiry defect in expectations.\nL6. Step 46: delete the fabricated unknown-checkout refusal; no actor has caused this request beyond the author choosing a fake id.\nL7. Steps 60,62: delete the filtered email/name read-backs after this same refresh actor already retrieved the complete collections in 59/61. Preserve the full refresh lists 56–59,61.\nAll remaining original steps passed the bar. Vendor sources: polar/spec/openapi.json.gz CheckoutProductsCreate and CheckoutConfirmStripe; https://polar.sh/docs/features/checkout/session; https://polar.sh/docs/features/subscriptions/trials; https://github.com/polarsource/polar/blob/main/server/polar/config.py CHECKOUT_TTL_SECONDS = 24 hours; model checkout.py uses that value. Dates were independently calculated from 2026-01-01 and all waits. Demand verified from cached twin-world 96ca4478bb39 and open-autonomy 0841076bed91.",
+  "doubts": [
+    "The customer-life frame calls this a year although it ends in April, and the full life does not show leaving the vendor; this is a scope/wording doubt rather than a ruling under the explicit rejection list."
+  ],
+  "applied": {
+    "from": "0e480c8fa63a647b2677bfd55a059975f365695fbcc86e89f64e8589b515559a",
+    "wasPlausible": false,
+    "steps": [
+      "2",
+      "3",
+      "14",
+      "15",
+      "16",
+      "19",
+      "20",
+      "21",
+      "23",
+      "26",
+      "35",
+      "36",
+      "37",
+      "39",
+      "40",
+      "46",
+      "47",
+      "48",
+      "49",
+      "51",
+      "60",
+      "62"
+    ],
+    "rulings": "REJECTED. Exhaustive one-round review of original steps 0 through 62, including credentials, temporal state, captured paths, request content, demanded calls and refusals.\nL1. Steps 2,3: delete both uncaused authentication refusals (the same cause twice consecutively). Record any resulting defensive-branch coverage with a vendor-backed reason rather than contriving a replacement refusal.\nL2. Steps 14,15,16: in 14 capture the form action from the hosted page (the runner supports text:<regex>). In 15 submit that captured action instead of constructing co_url + /pay, and rename the action as supplying payment details and starting a free trial with no immediate charge. Delete 16: a failing repeat of the completed request in this sitting is expressly rejected by the bar; a 'lost response' written only in its title does not override that rule.\nL3. Steps 19,20,21,23: after 19 add a two-hour wait to let the newly created World run. In 20 report completed hour IDs for 2026-01-14T15 and 2026-01-14T16, not T10/T11 preceding creation at 15:00. In 21 retry the actual T16 event. Reduce 23's wait from 27030m to 26910m so it still reaches 2 February 09:30.\nL4. Step 26: delete the disconnected duplicate-email customer creation (no Labs billing/portal request causes it). Keep 28–30, whose refusal has a concrete missing-customer cause and subsequent support intervention.\nL5. Steps 35,36,37,39,40,47,48,49,51: after 35 GET its captured pco_url and capture its displayed Pay form action before Grace leaves the tab. Set 36's wait to 1500m (25 hours), reflecting the vendor's 24-hour TTL. Submit the captured stale form action in 37. In 39 GET pco_url returned by 38 rather than rebuilding buy.polar.sh from the secret; capture its new form action and submit it in 40. Set 47 to Thursday 12 February with wait 1380m (23 hours after Grace returns at Wednesday 11 February 10:30). After 48 GET its returned mco_url and capture the displayed form action; submit it in 49. Set 51's wait to 90720m to retain Thursday 16 April 09:30. The new page-read after 35 and after 48 belong to those original step numbers for apply-rulings. Fix the twin TTL along with the life, using Polar's published config/model source; never hide the twin's 1-hour expiry defect in expectations.\nL6. Step 46: delete the fabricated unknown-checkout refusal; no actor has caused this request beyond the author choosing a fake id.\nL7. Steps 60,62: delete the filtered email/name read-backs after this same refresh actor already retrieved the complete collections in 59/61. Preserve the full refresh lists 56–59,61.\nAll remaining original steps passed the bar. Vendor sources: polar/spec/openapi.json.gz CheckoutProductsCreate and CheckoutConfirmStripe; https://polar.sh/docs/features/checkout/session; https://polar.sh/docs/features/subscriptions/trials; https://github.com/polarsource/polar/blob/main/server/polar/config.py CHECKOUT_TTL_SECONDS = 24 hours; model checkout.py uses that value. Dates were independently calculated from 2026-01-01 and all waits. Demand verified from cached twin-world 96ca4478bb39 and open-autonomy 0841076bed91."
+  }
+}

package/dist/journeys/decisions.json

@@ -0,0 +1,149 @@
+{
+ "about": "polar's decision table (the P3 procedure). Polar is the money in of Volter's platform (twin-world apps/billing over @polar-sh/sdk) and of Open Autonomy's patronage (apps/platform/src/polar.ts over fetch): an organization's meters and products, checkouts paid on the hosted checkout page (which make the order and, for a recurring product, the subscription), customers and their state by the application's own id, customer sessions for the portal, usage events against the meters, and the signed webhooks of the organization's endpoints. The core serves the meters and the webhook endpoints' list (plain objects); every answer that embeds another object or write that makes others is a handler. Every other operation is the gap, those of a declared resource listed in the manifest's unmodeled.",
+ "decisions": [
+  {
+   "operation": "meters:list",
+   "demand": "Twin's biller finds its meters by name at boot (apps/billing/src/polar.ts:27)",
+   "mechanism": "core",
+   "why": "a plain list of stored meters, newest first, filtered by name"
+  },
+  {
+   "operation": "meters:create",
+   "demand": "Twin's biller makes a missing meter (apps/billing/src/polar.ts:32)",
+   "mechanism": "core",
+   "why": "a plain create: the meter as given, with what the server assigns (created_at, organization_id, archived_at, metadata)"
+  },
+  {
+   "operation": "products:list",
+   "demand": "Twin's biller finds its Team product by name at boot (apps/billing/src/polar.ts:40)",
+   "mechanism": "handler",
+   "why": "the full stored products, including minted full prices and their meter references, filtered by archive/recurrence/query"
+  },
+  {
+   "operation": "products:create",
+   "demand": "Twin's biller makes its Team product (apps/billing/src/polar.ts:43); Open Autonomy makes each tier's monthly and one-time product (apps/platform/src/polar.ts:40)",
+   "mechanism": "handler",
+   "why": "each price is given an id, a price of no known amount type is refused (422), and the product answers its prices by amount type"
+  },
+  {
+   "operation": "checkouts:create",
+   "demand": "Twin's biller opens the Team checkout for an org (apps/billing/src/polar.ts:93); Open Autonomy opens a patron's checkout (apps/platform/src/polar.ts:81)",
+   "mechanism": "handler",
+   "why": "the session for the first product at its first price, open for 24 hours, with its client secret and the hosted page's url; no product, an unknown one or an unknown customer is refused (422)"
+  },
+  {
+   "operation": "checkouts:get",
+   "demand": "Open Autonomy's thanks page reads the checkout back (apps/platform/src/polar.ts:129)",
+   "mechanism": "handler",
+   "why": "the stored whole checkout including its product, prices and URL; an unknown id is 404"
+  },
+  {
+   "operation": "checkouts:client_get",
+   "demand": "the hosted checkout page every checkout's url opens (Twin apps/billing/src/polar.ts:94, Open Autonomy apps/platform/src/polar.ts:88)",
+   "mechanism": "handler",
+   "why": "the page reads its session by the client secret, the organization beside it (CheckoutPublic)"
+  },
+  {
+   "operation": "checkouts:client_confirm",
+   "demand": "the hosted checkout page's Pay (the same flows)",
+   "mechanism": "handler",
+   "why": "the customer is found or made, the order made and paid (order.created, order.paid), a recurring product's subscription started (trialing through its trial), and the checkout stores succeeded while confirmation answers confirmed plus its customer session token; an expired checkout is 410, one not open 403"
+  },
+  {
+   "operation": "orders:list",
+   "demand": "Open Autonomy's thanks page lists the checkout's orders (apps/platform/src/polar.ts:133)",
+   "mechanism": "handler",
+   "why": "each order embeds its customer, product, subscription and items; filtered by checkout, customer, product, subscription and status"
+  },
+  {
+   "operation": "customers:create",
+   "demand": "Twin's biller makes an org's customer before its portal session (apps/billing/src/polar.ts:104)",
+   "mechanism": "handler",
+   "why": "an individual customer, its email required; an email or external id another customer holds is refused (422)"
+  },
+  {
+   "operation": "customers:get",
+   "demand": "Open Autonomy reads a paid order's customer for the patron's name (apps/platform/src/polar.ts:103)",
+   "mechanism": "handler",
+   "why": "the stored whole CustomerIndividual through ctx.own; an unknown id is 404"
+  },
+  {
+   "operation": "customers:get_state_external",
+   "demand": "Twin's biller reads an org's plan and usage (apps/billing/src/polar.ts:74)",
+   "mechanism": "handler",
+   "why": "computed: the customer with its active or trialing subscriptions and each meter's consumed units folded from its events; no customer with the id is 404 (the biller's Free)"
+  },
+  {
+   "operation": "customer-sessions:create",
+   "demand": "Twin's biller opens the customer portal for an org (apps/billing/src/polar.ts:100)",
+   "mechanism": "handler",
+   "why": "a token for the customer named by id or external id, an hour long, and its customer_portal_url; no such customer is refused (422, the validation error the spec documents)"
+  },
+  {
+   "operation": "events:ingest",
+   "demand": "Twin's biller reports usage (apps/billing/src/polar.ts:114)",
+   "mechanism": "handler",
+   "why": "a batch: an external_id already ingested is a duplicate, not a second event; the customer named by its external id; answers inserted and duplicates"
+  },
+  {
+   "operation": "webhooks:create_webhook_endpoint",
+   "demand": "Open Autonomy's order.paid and order.created webhooks (apps/platform/src/polar.ts:160) reach it only through the endpoint its operator registers, whose secret it is given (apps/platform/src/polar.ts:155)",
+   "mechanism": "handler",
+   "why": "the endpoint's signing secret is drawn from the World and answered once; url, format and events are required (422)"
+  },
+  {
+   "operation": "customers:list",
+   "demand": "the vendor-backed refresh reads customer back (the manifest's refresh of customer)",
+   "mechanism": "handler",
+   "why": "the customer's whole: Polar's id, the application's external id, its email; newest first, by email, query or a live subscription"
+  },
+  {
+   "operation": "events:list",
+   "demand": "the vendor-backed refresh reads event back (the manifest's refresh of event)",
+   "mechanism": "handler",
+   "why": "each usage event in its stored vendor shape with its resolved customer (UserEvent), newest first, by customer, name or a meter's filter"
+  },
+  {
+   "operation": "checkouts:list",
+   "demand": "the vendor-backed refresh reads Checkout back (the manifest's refresh of Checkout)",
+   "mechanism": "handler",
+   "why": "each checkout with its product and prices embedded (checkoutView, as checkouts:get answers it), newest first"
+  },
+  {
+   "operation": "subscriptions:list",
+   "demand": "the vendor-backed refresh reads Subscription back (the manifest's refresh of Subscription)",
+   "mechanism": "handler",
+   "why": "each subscription with its customer, product and prices embedded (subscriptionView), the latest started first"
+  },
+  {
+   "operation": "webhooks:list_webhook_endpoints",
+   "demand": "the vendor-backed refresh reads WebhookEndpoint back (the manifest's refresh of WebhookEndpoint)",
+   "mechanism": "core",
+   "why": "a plain object: the endpoint as its create stored and answered it, newest first (the manifest's order), paged by the core"
+  },
+  {
+   "operation": "door:accessTokens",
+   "demand": "every application's POLAR_ACCESS_TOKEN (Twin apps/billing/src/polar.ts:15, Open Autonomy apps/platform/src/polar.ts:20)",
+   "mechanism": "door",
+   "why": "an Organization Access Token is made on the organization's settings page; the API makes none"
+  },
+  {
+   "operation": "door:revokeToken",
+   "demand": "a token the organization no longer trusts, refused from then on",
+   "mechanism": "door",
+   "why": "a token is revoked on the settings page; the API revokes none"
+  },
+  {
+   "operation": "door:appCredentials",
+   "demand": "the token the World's application holds at boot (the descriptor's credentialDoor)",
+   "mechanism": "door",
+   "why": "the runtime issues the application's token as the settings page would make it"
+  },
+  {
+   "operation": "door:deliveries",
+   "demand": "what Open Autonomy's /webhooks/polar was sent (apps/platform/src/polar.ts:153)",
+   "mechanism": "door",
+   "why": "the webhooks the World delivered, as the receiving server got them (headers and body), in order"
+  }
+ ]
+}

package/dist/journeys/demand.json

@@ -0,0 +1,45 @@
+{
+ "measured": "the applications in scope (twin-world's generated/demand.json, vendor polar: Twin and Open Autonomy) read at the demand scan's clones (~/.cache/twin-demand): volter-ai/twin-world at 96ca4478bb39 (apps/billing, the Volter platform's biller over @polar-sh/sdk) and open-autonomy-org/open-autonomy at 0841076bed91 (apps/platform/src/polar.ts, patronage over Polar's REST API with fetch). Every other scoped application (RH2, Volter Harness, Substrate, Workbench, Volter Browsers, tabnode, almostcdp, localrouter, Volter Editor, the videogame.ai site, Dub, Rallly, Postiz, Twenty, LibreChat, Cal.com) names no Polar host, SDK or POLAR_ variable at run time (Dub's only match is a seed data file, LibreChat's its lockfile). Ruled out: Open Autonomy's apps/platform/test (a mock), world.ts (the World's seed: it names the twin's URL and signs no call), twin-world's scripts and cookbook (they stand the stack up; the calls are the biller's). The platform's own callers in twin-world (packages/, cookbook/, scripts/, docs/contributing/architecture.md) name the pack only to link it into a World and call no operation, door or screen of it.",
+ "applications": [
+  {
+   "name": "volter-ai/twin-world apps/billing",
+   "commit": "96ca4478bb39",
+   "client": "@polar-sh/sdk",
+   "backend": [
+    { "call": "meters.list", "operation": "meters:list", "evidence": "apps/billing/src/polar.ts:27" },
+    { "call": "meters.create", "operation": "meters:create", "evidence": "apps/billing/src/polar.ts:32" },
+    { "call": "products.list", "operation": "products:list", "evidence": "apps/billing/src/polar.ts:40" },
+    { "call": "products.create", "operation": "products:create", "evidence": "apps/billing/src/polar.ts:43" },
+    { "call": "customers.getStateExternal", "operation": "customers:get_state_external", "evidence": "apps/billing/src/polar.ts:74" },
+    { "call": "checkouts.create", "operation": "checkouts:create", "evidence": "apps/billing/src/polar.ts:93" },
+    { "call": "customerSessions.create", "operation": "customer-sessions:create", "evidence": "apps/billing/src/polar.ts:100" },
+    { "call": "customers.create", "operation": "customers:create", "evidence": "apps/billing/src/polar.ts:104" },
+    { "call": "events.ingest", "operation": "events:ingest", "evidence": "apps/billing/src/polar.ts:114" }
+   ],
+   "flows": [
+    { "flow": "the hosted checkout: the org's admin is sent to the checkout's url, pays, and returns to the billing page", "evidence": "apps/billing/src/polar.ts:94" },
+    { "flow": "the customer portal: the org's admin is sent to the session's customer_portal_url (Manage billing)", "evidence": "apps/billing/src/polar.ts:101" }
+   ]
+  },
+  {
+   "name": "open-autonomy-org/open-autonomy apps/platform",
+   "commit": "0841076bed91",
+   "client": "fetch (Polar's REST API)",
+   "backend": [
+    { "call": "POST /v1/products/", "operation": "products:create", "evidence": "apps/platform/src/polar.ts:40" },
+    { "call": "POST /v1/checkouts/", "operation": "checkouts:create", "evidence": "apps/platform/src/polar.ts:81" },
+    { "call": "GET /v1/customers/{id}", "operation": "customers:get", "evidence": "apps/platform/src/polar.ts:103" },
+    { "call": "GET /v1/checkouts/{id}", "operation": "checkouts:get", "evidence": "apps/platform/src/polar.ts:129" },
+    { "call": "GET /v1/orders/?checkout_id=", "operation": "orders:list", "evidence": "apps/platform/src/polar.ts:133" }
+   ],
+   "events": [
+    { "event": "order.paid", "evidence": "apps/platform/src/polar.ts:160 (Standard Webhooks, verified at apps/platform/src/polar.ts:144)" },
+    { "event": "order.created", "evidence": "apps/platform/src/polar.ts:160" }
+   ],
+   "flows": [
+    { "flow": "the hosted checkout: a patron is sent (303) to the checkout's url, pays, and returns to the thanks page with {CHECKOUT_ID} filled", "evidence": "apps/platform/src/polar.ts:88" },
+    { "flow": "the webhook endpoint: the operator registers the platform's /webhooks/polar and gives it the endpoint's secret (POLAR_WEBHOOK_SECRET), without which no order.paid reaches it", "evidence": "apps/platform/src/polar.ts:155" }
+   ]
+  }
+ ]
+}

package/dist/journeys/score.json

@@ -0,0 +1,249 @@
+{
+  "vendor": "polar",
+  "life": {
+    "steps": 59,
+    "verdict": "plausible",
+    "judge": "Contributor 16",
+    "authors": [
+      "Contributor 39"
+    ]
+  },
+  "failures": [],
+  "flags": [],
+  "coverage": {
+    "vendor": "polar",
+    "missing": 27,
+    "stale": [],
+    "code": {
+      "lines": 763,
+      "run": 750,
+      "recorded": 2,
+      "missing": 11
+    },
+    "state": {
+      "declared": 9,
+      "reached": 2,
+      "recorded": 0,
+      "missing": [
+        "refusal Checkout.status: checkouts:client_confirm confirmed|succeeded|failed|expired → (stays)",
+        "move Checkout.status: vendor confirmed → succeeded",
+        "move Checkout.status: time open → expired",
+        "refusal Subscription.status: checkouts:client_confirm active|trialing → (stays)",
+        "move Subscription.status: vendor incomplete → active",
+        "move Subscription.status: vendor incomplete → trialing",
+        "move Subscription.status: time trialing → active"
+      ],
+      "undeclared": [
+        "Checkout.status: confirmed → succeeded by checkout.update",
+        "Checkout.status: confirmed → succeeded by checkouts:client_confirm",
+        "Checkout.status: open → expired by checkout.update",
+        "Order.status: pending → paid by checkouts:client_confirm",
+        "Order.status: pending → paid by order.pay",
+        "Subscription.status: incomplete → active by checkouts:client_confirm",
+        "Subscription.status: incomplete → active by subscription.activate",
+        "Subscription.status: incomplete → trialing by subscription.activate",
+        "Subscription.status: trialing → active by subscription.update"
+      ]
+    },
+    "files": [
+      {
+        "file": "semantics/doors.ts",
+        "lines": {
+          "found": 28,
+          "hit": 28
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/states.ts",
+        "lines": {
+          "found": 34,
+          "hit": 34
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/customers.ts",
+        "lines": {
+          "found": 34,
+          "hit": 32
+        },
+        "missing": [
+          {
+            "from": 60,
+            "to": 60,
+            "fn": "duplicateExternal"
+          },
+          {
+            "from": 66,
+            "to": 66,
+            "fn": "duplicateEmail"
+          }
+        ]
+      },
+      {
+        "file": "semantics/customer-sessions.ts",
+        "lines": {
+          "found": 7,
+          "hit": 7
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/webhooks.ts",
+        "lines": {
+          "found": 17,
+          "hit": 17
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/shared.ts",
+        "lines": {
+          "found": 245,
+          "hit": 236
+        },
+        "missing": [
+          {
+            "from": 331,
+            "to": 339,
+            "fn": "compareClause"
+          }
+        ]
+      },
+      {
+        "file": "semantics/around.ts",
+        "lines": {
+          "found": 12,
+          "hit": 12
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/products.ts",
+        "lines": {
+          "found": 34,
+          "hit": 34
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/orders.ts",
+        "lines": {
+          "found": 7,
+          "hit": 7
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/subscriptions.ts",
+        "lines": {
+          "found": 10,
+          "hit": 10
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/clock.ts",
+        "lines": {
+          "found": 17,
+          "hit": 17
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/events.ts",
+        "lines": {
+          "found": 37,
+          "hit": 37
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/index.ts",
+        "lines": {
+          "found": 27,
+          "hit": 27
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/tenant.ts",
+        "lines": {
+          "found": 2,
+          "hit": 2
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/checkouts.ts",
+        "lines": {
+          "found": 85,
+          "hit": 85
+        },
+        "missing": []
+      },
+      {
+        "file": "screens/checkout.ts",
+        "lines": {
+          "found": 21,
+          "hit": 21
+        },
+        "missing": []
+      },
+      {
+        "file": "screens/portal.ts",
+        "lines": {
+          "found": 13,
+          "hit": 13
+        },
+        "missing": []
+      },
+      {
+        "file": "manifest.ts",
+        "lines": {
+          "found": 101,
+          "hit": 101
+        },
+        "missing": []
+      },
+      {
+        "file": "index.ts",
+        "lines": {
+          "found": 7,
+          "hit": 7
+        },
+        "missing": []
+      },
+      {
+        "file": "server.ts",
+        "lines": {
+          "found": 4,
+          "hit": 2
+        },
+        "missing": []
+      },
+      {
+        "file": "fetch.ts",
+        "lines": {
+          "found": 21,
+          "hit": 21
+        },
+        "missing": []
+      }
+    ]
+  },
+  "examples": {
+    "done": true,
+    "replayed": true,
+    "verdict": "plausible",
+    "failures": [],
+    "line": "examples: 31 published, 0 of patch-removed operations, 0 of operations the twin does not serve, 31 replayed, 0 recorded; 0 failing   done: yes"
+  },
+  "breadth": {
+    "operations": 186,
+    "gap": 166,
+    "handler": 17,
+    "core": 3
+  }
+}