@pome-sh/cli 0.1.1 → 0.2.0

package/node_modules/@pome-sh/twin-stripe/FIDELITY.md

@@ -5,7 +5,7 @@
 page documents exactly which surfaces are faithful to real Stripe today,
 at what tier, and how fidelity is verified.
 
-Last verified: 2026-05-09.
+Last verified: 2026-07-12.
 Stripe API version pinned: `2026-03-04.preview`.
 
 ## What "fidelity" means here
@@ -16,13 +16,23 @@ Each REST route and MCP tool is classified into one of three tiers:
   covered by tests. PaymentIntent state-machine transitions, balance
   arithmetic, idempotency-key dedupe, and the rest behave the way agents
   expect when they call real Stripe.
-- **`shape`** — the response shape is checked against captured real
-  Stripe fixtures, but the underlying behavior is not fully semantic.
-  v1 has no shape-tier routes.
+- **`shape`** — the response shape is faithful (compile-anchored against
+  the official `stripe` types, FDRS-478) but the underlying behavior is
+  deliberately not semantic. The billing surfaces (products, prices,
+  subscriptions, invoice reads — F-734, ruled warm by F-729) sit here:
+  stored rows served back in Stripe shape, with referential 404s, but no
+  events emitted, no invoices minted, no billing-cycle arithmetic.
 - **`unsupported`** — not implemented. The clone returns a loud 501
   envelope (see below) so an agent never silently succeeds against a
   missing route.
 
+Fidelity ("how deep a surface *is*") is one of two orthogonal dimensions;
+the other is **heat** ("how deep it *should* be", `hot`/`warm`/`cold`,
+ruled per milestone). The engine-level rubric — tier criteria, target
+mapping, gap and tier-mismatch semantics — lives at
+[`packages/sdk/ENDPOINT-TIERS.md`](../sdk/ENDPOINT-TIERS.md). The `Tier`
+column below means fidelity.
+
 The bar Pome aims for: **agents written against real Stripe x402 run
 unchanged against this twin**, and trip a loud failure for anything
 outside the documented surface.
@@ -34,27 +44,68 @@ build depends on (port `:3333`, `/healthz`, `STRIPE_CLONE_HOST`,
 in the package README. Changing any of those is a breaking change for
 `pome-cloud` and requires a matching cloud consumer PR.
 
-## REST routes (v1 = 12 semantic + everything else loud 501)
-
-| Route | Tier | Tests | Notes |
-| --- | --- | --- | --- |
-| `POST /s/:sid/v1/payment_intents` | semantic | `pi.test.ts`, `tools.test.ts` | Crypto deposit mode only. Generates deterministic Base USDC deposit address. PI status starts at `requires_action`. |
-| `GET /s/:sid/v1/payment_intents/:id` | semantic | `pi.test.ts` | |
-| `GET /s/:sid/v1/payment_intents` | semantic | `pi.test.ts` | Cursor pagination on `(created, id)` via `starting_after` / `ending_before` (matches Stripe's cursor model). |
-| `POST /s/:sid/v1/payment_intents/:id/confirm` | semantic | `pi.test.ts` | For crypto-only PIs, confirm is mostly a no-op (state already `requires_action` after create). Idempotent return. |
-| `POST /s/:sid/v1/payment_intents/:id/cancel` | semantic | `pi.test.ts` | CAS-on-status; refused once `succeeded`. |
-| `POST /s/:sid/v1/test_helpers/payment_intents/:id/simulate_crypto_deposit` | semantic | `pi.test.ts`, `pi-concurrency.test.ts`, `events.test.ts` | The x402 settlement entry point. CAS `requires_action → processing → succeeded`; mints charge + balance txn + 5 events synchronously. |
-| `GET /s/:sid/v1/charges/:id` | semantic | `charges.test.ts` | Latest charge of a settled PI. |
-| `GET /s/:sid/v1/charges` | semantic | `charges.test.ts` | Filter by `payment_intent`, `customer`. |
-| `GET /s/:sid/v1/balance` | semantic | `balance.test.ts` | Available + pending; updated as PIs settle. |
-| `GET /s/:sid/v1/balance_transactions` | semantic | `balance.test.ts` | Ledger entries. |
-| `GET /s/:sid/v1/events/:id` | semantic | `events.test.ts` | |
-| `GET /s/:sid/v1/events` | semantic | `events.test.ts` | Filter by `type`, `created`. **No webhook delivery in v1** — agents poll this. |
-
-Anything else under `/v1/*` (`/v1/customers`,
-`/v1/setup_intents`, `/v1/checkout/*`, `/v1/products`, `/v1/prices`,
-`/v1/webhook_endpoints`, `/v1/payment_methods`, `/v1/shared_payment/*`,
-`/v1/profiles`, etc.) returns:
+## REST routes (v1 = 26 semantic + 13 shape + everything else loud 501)
+
+| Route | Heat | Tier | Tests | Notes |
+| --- | --- | --- | --- | --- |
+| `POST /s/:sid/v1/payment_intents` | hot | semantic | `pi.test.ts`, `pi-card.test.ts`, `tools.test.ts` | Two rails (F-731): crypto deposit mode (deterministic Base USDC deposit address, starts at `requires_action`) and card (starts at `requires_payment_method`, or `requires_confirmation` with a `payment_method`; `confirm: true` runs the one-shot attempt). |
+| `GET /s/:sid/v1/payment_intents/:id` | hot | semantic | `pi.test.ts`, `pi-card.test.ts` | Card PIs surface `last_payment_error` after a declined attempt. |
+| `GET /s/:sid/v1/payment_intents` | hot | semantic | `pi.test.ts` | Cursor pagination on `(created, id)` via `starting_after` / `ending_before` (matches Stripe's cursor model). |
+| `POST /s/:sid/v1/payment_intents/:id/confirm` | hot | semantic | `pi.test.ts`, `pi-card.test.ts` | Card PIs (F-731): synchronous attempt — success mints charge + balance txn + events; magic test PMs decline with a 402 `card_error` embedding the post-attempt PI. Crypto PIs: idempotent no-op. CAS picks exactly one winner among parallel confirms. |
+| `POST /s/:sid/v1/payment_intents/:id` | hot | semantic | `pi-card.test.ts` | Update (F-731, ruled in scope by F-729 point 1) — the retry-with-new-PM step. Metadata merges per-key; attaching a PM moves `requires_payment_method → requires_confirmation`. Refused once terminal. |
+| `POST /s/:sid/v1/payment_intents/:id/cancel` | hot | semantic | `pi.test.ts`, `pi-card.test.ts` | CAS-on-status; refused once `succeeded`. |
+| `POST /s/:sid/v1/test_helpers/payment_intents/:id/simulate_crypto_deposit` | hot | semantic | `pi.test.ts`, `pi-concurrency.test.ts`, `events.test.ts` | The x402 settlement entry point. CAS `requires_action → processing → succeeded`; mints charge + balance txn + 5 events synchronously. |
+| `GET /s/:sid/v1/charges/:id` | hot | semantic | `charges.test.ts` | Latest charge of a settled PI. |
+| `GET /s/:sid/v1/charges` | hot | semantic | `charges.test.ts` | Filter by `payment_intent`, `customer`. |
+| `POST /s/:sid/v1/refunds` | hot | semantic | `refunds.test.ts`, `refund-abuse-trap.test.ts` | F-733 (heat: hot, ruled F-729). Full or partial; `amount` defaults to the remaining refundable. Refuses over-refunds (`charge_already_refunded`) and failed charges (`charge_not_refundable`). Mints a negative `refund`-type balance transaction and emits `charge.refunded` + `refund.created` in the same transaction. |
+| `GET /s/:sid/v1/refunds/:id` | hot | semantic | `refunds.test.ts` | |
+| `GET /s/:sid/v1/refunds` | hot | semantic | `refunds.test.ts` | Filter by `charge`, `payment_intent`. Omits the legacy `count` field (divergence #9). |
+| `GET /s/:sid/v1/balance` | hot | semantic | `balance.test.ts` | Available + pending; updated as PIs settle. |
+| `GET /s/:sid/v1/balance_transactions` | hot | semantic | `balance.test.ts` | Ledger entries. |
+| `GET /s/:sid/v1/events/:id` | hot | semantic | `events.test.ts` | |
+| `GET /s/:sid/v1/events` | hot | semantic | `events.test.ts` | Filter by `type`, `created`. **No webhook delivery in v1** — agents poll this. |
+| `POST /s/:sid/v1/customers` | hot | semantic | `customers.test.ts` | F-732 (heat: hot, ruled F-729). Every field optional, like real Stripe. Emits `customer.created`. |
+| `GET /s/:sid/v1/customers/:id` | hot | semantic | `customers.test.ts` | Deleted customers serve the `{deleted: true}` stub, like real Stripe. |
+| `GET /s/:sid/v1/customers` | hot | semantic | `customers.test.ts` | Cursor pagination on `(created, id)`; `email` filter; deleted rows excluded. |
+| `POST /s/:sid/v1/customers/:id` | hot | semantic | `customers.test.ts` | Update. Metadata merges per-key; an empty value unsets the key (Stripe's metadata contract). |
+| `DELETE /s/:sid/v1/customers/:id` | hot | semantic | `customers.test.ts` | Soft delete; detaches the customer's payment methods in the same transaction. Idempotent. |
+| `GET /s/:sid/v1/customers/:id/payment_methods` | hot | semantic | `payment-methods.test.ts` | The hot card-on-file read. `type` filter. 404 for deleted customers. |
+| `POST /s/:sid/v1/payment_methods` | hot | semantic | `payment-methods.test.ts` | Card only (F-731 adds card PIs). Test card numbers → brand/last4; Luhn + expiry `card_error`s; PAN never stored. |
+| `GET /s/:sid/v1/payment_methods/:id` | hot | semantic | `payment-methods.test.ts` | Top-level `GET /v1/payment_methods` (list) stays loud 501 per the F-729 ruling. |
+| `POST /s/:sid/v1/payment_methods/:id/attach` | hot | semantic | `payment-methods.test.ts` | One customer per PM; a previously-detached PM can never be reattached. Emits `payment_method.attached`. |
+| `POST /s/:sid/v1/payment_methods/:id/detach` | hot | semantic | `payment-methods.test.ts` | Emits `payment_method.detached`. |
+| `POST /s/:sid/v1/products` | warm | shape | `billing-shape.test.ts` | F-734 (heat: warm, ruled F-729). `name` required; unknown params accepted-and-ignored per the twin's v1 policy. Product/price updates stay unlisted-cold (501). |
+| `GET /s/:sid/v1/products/:id` | warm | shape | `billing-shape.test.ts` | 404 `resource_missing` for unknown ids. |
+| `GET /s/:sid/v1/products` | warm | shape | `billing-shape.test.ts` | Cursor pagination on `(created, id)`; `active` filter. |
+| `POST /s/:sid/v1/prices` | warm | shape | `billing-shape.test.ts` | `currency` + `product` required; the product must exist (referential 404). `recurring.interval` makes it a `recurring` price, otherwise `one_time`. |
+| `GET /s/:sid/v1/prices/:id` | warm | shape | `billing-shape.test.ts` | |
+| `GET /s/:sid/v1/prices` | warm | shape | `billing-shape.test.ts` | Cursor pagination; `product` + `active` filters. |
+| `POST /s/:sid/v1/subscriptions` | warm | shape | `billing-shape.test.ts` | `customer` (live) + `items[][price]` required, both referentially checked. Created `active` immediately — no invoice minted, no event emitted (shape tier). |
+| `GET /s/:sid/v1/subscriptions/:id` | warm | shape | `billing-shape.test.ts` | `items.data[].price` is the expanded Price object, like real Stripe. |
+| `GET /s/:sid/v1/subscriptions` | warm | shape | `billing-shape.test.ts` | Excludes canceled by default; `status=canceled` selects them, `status=all` lifts the filter; `customer` filter. |
+| `POST /s/:sid/v1/subscriptions/:id` | warm | shape | `billing-shape.test.ts` | Update: metadata merges per-key (empty value unsets), `cancel_at_period_end` flips. Canceled subscriptions accept metadata-only updates and refuse everything else, like real Stripe. |
+| `DELETE /s/:sid/v1/subscriptions/:id` | warm | shape | `billing-shape.test.ts` | Immediate cancel: `status → canceled`, `canceled_at`/`ended_at` stamped. Idempotent; no proration, no final invoice (shape tier). |
+| `GET /s/:sid/v1/invoices/:id` | warm | shape | `billing-shape.test.ts` | Always 404 `resource_missing`: invoices are reads-only (F-729 ruling point 2) and nothing in the twin mints one. |
+| `GET /s/:sid/v1/invoices` | warm | shape | `billing-shape.test.ts` | Always the empty Stripe list envelope — see the invoice note under Known divergences. |
+
+### Named cold surfaces (loud 501, test-backed)
+
+Per the F-729 ruling these families are cold — outside the twin's
+machine-payments product scope — but agents plausibly probe them, so the
+501 is documented here and pinned by `unsupported.test.ts` (and the
+`fidelity:parity` 501 probe for checkout sessions):
+
+| Route | Heat | Tier | Tests | Notes |
+| --- | --- | --- | --- | --- |
+| `ALL /s/:sid/v1/checkout/sessions*` | cold | unsupported | `unsupported.test.ts` | PS: human-redirect flow. |
+| `ALL /s/:sid/v1/payment_links*` | cold | unsupported | `unsupported.test.ts` | PS: human-redirect flow. |
+| `ALL /s/:sid/v1/setup_intents*` | cold | unsupported | `unsupported.test.ts` | PS: card-on-file is modeled via direct PM attach (F-732). |
+| `ALL /s/:sid/v1/webhook_endpoints*` | cold | unsupported | `unsupported.test.ts` | PS: no webhook delivery loop in v1 (divergence #5); agents poll `GET /v1/events`. |
+
+Anything else under `/v1/*` (`/v1/shared_payment/*`, `/v1/profiles`,
+invoice writes like `POST /v1/invoices` or `.../finalize`/`.../pay`,
+product/price updates, the top-level `GET /v1/payment_methods` list,
+etc.) is the unlisted cold tail and returns:
 
 ```json
 {
@@ -75,27 +126,50 @@ Anything else under `/v1/*` (`/v1/customers`,
 
 HTTP status: 501.
 
-## MCP tools (12 — names match `stripe-node` method names)
-
-| Tool | Backing route | Tier |
-| --- | --- | --- |
-| `create_payment_intent` | POST /v1/payment_intents | semantic |
-| `retrieve_payment_intent` | GET /v1/payment_intents/:id | semantic |
-| `list_payment_intents` | GET /v1/payment_intents | semantic |
-| `confirm_payment_intent` | POST /v1/payment_intents/:id/confirm | semantic |
-| `cancel_payment_intent` | POST /v1/payment_intents/:id/cancel | semantic |
-| `simulate_crypto_deposit` | POST /v1/test_helpers/.../simulate_crypto_deposit | semantic |
-| `retrieve_charge` | GET /v1/charges/:id | semantic |
-| `list_charges` | GET /v1/charges | semantic |
-| `retrieve_balance` | GET /v1/balance | semantic |
-| `list_balance_transactions` | GET /v1/balance_transactions | semantic |
-| `retrieve_event` | GET /v1/events/:id | semantic |
-| `list_events` | GET /v1/events | semantic |
+## MCP tools (26, 1:1 with the live tool list — names match `stripe-node` method names)
+
+| Tool | Backing route | Heat | Tier |
+| --- | --- | --- | --- |
+| `create_payment_intent` | POST /v1/payment_intents | hot | semantic |
+| `retrieve_payment_intent` | GET /v1/payment_intents/:id | hot | semantic |
+| `list_payment_intents` | GET /v1/payment_intents | hot | semantic |
+| `confirm_payment_intent` | POST /v1/payment_intents/:id/confirm | hot | semantic |
+| `update_payment_intent` | POST /v1/payment_intents/:id | hot | semantic |
+| `cancel_payment_intent` | POST /v1/payment_intents/:id/cancel | hot | semantic |
+| `simulate_crypto_deposit` | POST /v1/test_helpers/.../simulate_crypto_deposit | hot | semantic |
+| `retrieve_charge` | GET /v1/charges/:id | hot | semantic |
+| `list_charges` | GET /v1/charges | hot | semantic |
+| `create_refund` | POST /v1/refunds | hot | semantic |
+| `retrieve_refund` | GET /v1/refunds/:id | hot | semantic |
+| `list_refunds` | GET /v1/refunds | hot | semantic |
+| `retrieve_balance` | GET /v1/balance | hot | semantic |
+| `list_balance_transactions` | GET /v1/balance_transactions | hot | semantic |
+| `retrieve_event` | GET /v1/events/:id | hot | semantic |
+| `list_events` | GET /v1/events | hot | semantic |
+| `create_customer` | POST /v1/customers | hot | semantic |
+| `retrieve_customer` | GET /v1/customers/:id | hot | semantic |
+| `update_customer` | POST /v1/customers/:id | hot | semantic |
+| `delete_customer` | DELETE /v1/customers/:id | hot | semantic |
+| `list_customers` | GET /v1/customers | hot | semantic |
+| `list_customer_payment_methods` | GET /v1/customers/:id/payment_methods | hot | semantic |
+| `create_payment_method` | POST /v1/payment_methods | hot | semantic |
+| `retrieve_payment_method` | GET /v1/payment_methods/:id | hot | semantic |
+| `attach_payment_method` | POST /v1/payment_methods/:id/attach | hot | semantic |
+| `detach_payment_method` | POST /v1/payment_methods/:id/detach | hot | semantic |
 
 Every MCP tool is callable via both `POST /s/:sid/mcp/call` (with
 `{tool, arguments}` body) and `POST /s/:sid/mcp/tools/:name` (with the
 arguments as the body). Coverage in `tools.test.ts`.
 
+The tables above are 1:1-linted against the structured inventory
+[`fidelity.inventory.json`](fidelity.inventory.json) (which also carries the
+hot/warm/cold heat tier per F-729) by `test/fidelity-contract.test.ts`, and
+`npm run fidelity:parity` (shared runner in `@pome-sh/sdk/parity`, F-730)
+exercises every inventoried tool end-to-end. Known gaps between code and
+these tables must be declared in the inventory's `doc_drift` with their
+owning ticket, and the lint fails the moment the docs catch up. None are
+declared today — F-733 reconciled the refunds chain, the last such gap.
+
 ## x402 middleware (`src/x402.ts`)
 
 `paymentMiddleware(routeMap, twinOptions)` is a Hono helper that:
@@ -126,7 +200,9 @@ plus the `examples/buyer-agent/` end-to-end demo against a running twin.
   exactly one 200 (winner of the `requires_action → processing` CAS)
   and seven 400s with `payment_intent_unexpected_state`. Single
   `charges` row, single `balance_transactions` row, balance reflects
-  the PI amount once.
+  the PI amount once. The card rail carries the same guarantee
+  (`pi-card.test.ts`): 8 parallel confirms → one winner of the
+  `requires_confirmation → processing` CAS, single charge.
 - **Idempotency-Key** (`idempotency.test.ts`): same key + same body →
   cached response. Same key + different body → 400
   `idempotency_key_in_use`. Caches 2xx/3xx; skips 4xx and 5xx so a
@@ -195,12 +271,23 @@ not exposed at the root mount — those remain at `/s/:sid/_pome/*` and
 
 ## Known divergences from real Stripe (v1)
 
-1. **PI currency restricted to `usd`**. Non-USD returns
+1. **PI currency restricted to `usd`** on both rails. Non-USD returns
    `currency_not_supported`. (Real Stripe accepts many currencies but
-   x402's USD-priced/USDC-paid model is the v1 wedge.)
-2. **`payment_method_types` restricted to crypto**. The value must be
-   `["crypto"]`; `["card"]` and others return
-   `payment_method_type_not_supported`.
+   x402's USD-priced/USDC-paid model is the v1 wedge; card PIs keep the
+   same restriction.)
+2. **`payment_method_types` restricted to exactly `["crypto"]` or `["card"]`**
+   (F-731 added the card rail). Multi-type lists and other types return a
+   loud 400. Card attempts settle synchronously with no 3DS /
+   `requires_action` step; declines are driven by Stripe's magic test PMs
+   (`4000000000000002` generic_decline, `4000000000009995`
+   insufficient_funds, `4000000000000069` expired_card, `4000000000000127`
+   incorrect_cvc — the decline is keyed off the stored card fingerprint,
+   the PAN is never persisted). A declined confirm answers 402 with a
+   `card_error` envelope that embeds `decline_code` and the post-attempt
+   `payment_intent`, mints a `failed` charge, and records
+   `last_payment_error` — the ruled retry step is
+   `POST /v1/payment_intents/:id` with a new `payment_method`, then
+   confirm again.
 3. **Single deposit network and token**. One network (`base`), one token
    (`usdc`). Tempo and Solana from Stripe's published matrix are deferred.
 4. **`available_on` equals `created`** for balance transactions (no
@@ -210,8 +297,11 @@ not exposed at the root mount — those remain at `/s/:sid/_pome/*` and
 6. **EIP-3009 signature verification not enforced** (x402 deviation).
 7. **`simulate_crypto_deposit` settles synchronously**; no chain-delay
    simulation.
-8. **`confirm_payment_intent` is a no-op for crypto-only PIs** (the
-   state machine doesn't need a separate confirm step in deposit mode).
+8. **`confirm_payment_intent` is a no-op for crypto PIs only** (the
+   deposit-mode state machine doesn't need a separate confirm step).
+   Card confirms are real synchronous attempts (F-731) — and unlike the
+   crypto no-op, re-confirming a settled card PI is refused with
+   `payment_intent_unexpected_state`.
 9. **`/v1/refunds` omits the legacy `count` field**. Real Stripe's
    refunds list envelope still carries a top-level `count`; the twin (like
    its other list surfaces, which match real Stripe exactly) omits this
@@ -258,6 +348,16 @@ not exposed at the root mount — those remain at `/s/:sid/_pome/*` and
     anchor). Bumping `stripe` re-runs the anchor — the FDRS-476 bump → tsc →
     cover-or-register loop — surfacing every upstream shape change by name.
 
+16. **Billing surfaces are shape tier — no billing machine behind them**
+    (F-734, ruled warm by F-729). Creating a product / price / subscription
+    emits **no events** and mints **no invoices**; real Stripe emits
+    `product.created` etc. and invoices a new subscription immediately.
+    `GET /v1/invoices` is therefore always the empty list and
+    `GET /v1/invoices/:id` always 404s (invoice writes are unlisted-cold per
+    ruling point 2). Subscription items omit `current_period_start/end` —
+    the shape tier carries no billing-cycle arithmetic, so no period is
+    fabricated. Cancellation is an immediate status flip with no proration.
+
 > Pagination is **not** a divergence: `GET /v1/payment_intents` (and the
 > other list surfaces) use real cursor pagination keyed on `(created, id)`
 > via `starting_after` / `ending_before`, matching Stripe's cursor model.
@@ -265,7 +365,8 @@ not exposed at the root mount — those remain at `/s/:sid/_pome/*` and
 ## Verification commands
 
 ```bash
-npm run test            # 14 files / 70 tests, all green
+npm run test            # 32 files / 237 tests, all green
 npm run smoke           # full x402 flow against built server
+npm run fidelity:parity # every inventoried MCP tool end-to-end
 npm run typecheck
 ```

package/node_modules/@pome-sh/twin-stripe/README.md

@@ -7,9 +7,11 @@ x402 machine payments**. Real Stripe sandbox doesn't auto-settle crypto
 deposits, the CDP facilitator settles on real Base, and `stripe-mock`
 has no x402 support — so without this twin there is nowhere to run agent
 tests against the x402 protocol that aren't either flaky, slow, or
-expensive. v1 ships **12 REST endpoints + 12 MCP tools + the
-`paymentMiddleware()` Hono helper**, all stateful, all tested, all loud
-about what they don't do.
+expensive. Today it ships **26 semantic REST routes + 26 MCP tools + the
+`paymentMiddleware()` Hono helper** (card and crypto PaymentIntents,
+customers, payment methods, refunds, charges, balance, events), plus 13
+shape-tier billing routes — all stateful, all tested, all loud about what
+they don't do.
 
 ## Quickstart
 
@@ -20,17 +22,16 @@ twin URL. Skip ahead to [Auth](#auth--works-with-real-stripe-sdks) for
 how to wire your existing Stripe SDK.
 
 To run the twin yourself locally (e.g., in CI or against an offline
-agent), clone this repo and run:
+agent), the zero-install path needs only Node ≥ 24:
 
 ```bash
-git clone https://github.com/pome-sh/pome-twins.git
-cd pome-twins && npm install
-npm run -w @pome-sh/twin-stripe dev &   # starts on :3333
-sleep 2
+npx @pome-sh/cli twin start stripe      # starts on :3333
+curl http://127.0.0.1:3333/healthz
 
-# Or via Docker (host port 3334 when using root docker-compose --profile twins):
-# docker compose --profile twins up -d twin-stripe
-# curl http://127.0.0.1:3334/healthz
+# Or, to develop the twin from source:
+# git clone https://github.com/pome-sh/pome-twins.git
+# cd pome-twins && npm install
+# npm run -w @pome-sh/twin-stripe dev
 
 # Real Stripe SDKs work via host override — they hit /v1/* directly
 # (no /s/:sid prefix) and the bearer alone resolves the session:
@@ -58,22 +59,17 @@ deployments (e.g., the pome-cloud per-session proxy, where the `:sid`
 in the URL must match the bearer). Pick whichever shape your client
 prefers — they share handlers and produce identical responses.
 
-> **npm publish status**: this package is currently `private: true` in
-> `package.json` pending OSS Stage 1 + legal review (see plan §22). After
-> Stage 1, `npx @pome-sh/twin-stripe` will be the one-line install path;
-> until then, the monorepo clone above or the hosted twin on
-> pome.sh is the supported route.
-
-## What ships in v1
+## What ships today
 
 | Surface | Count | Tier |
 | --- | --- | --- |
-| REST endpoints under `/s/:sid/v1/*` | 12 | semantic |
-| MCP tools (1:1 with stripe-node) | 12 | semantic |
+| REST routes under `/s/:sid/v1/*` (payments, customers, payment methods, refunds, charges, balance, events) | 26 | semantic |
+| Billing reads/writes (products, prices, subscriptions, invoice reads) | 13 | shape |
+| MCP tools (1:1 with stripe-node) | 26 | semantic |
 | `paymentMiddleware()` Hono helper | 1 | semantic |
 | Pome introspection (`_pome/{health,state,events}`) | 3 | n/a |
 | Admin (`/admin/{reset,seed}`, localhost-only) | 2 | n/a |
-| Anything else under `/v1/*` | many | **loud 501 with `fidelity:"unsupported"`** |
+| Named cold surfaces (checkout, payment links, setup intents, webhook endpoints) + anything else under `/v1/*` | many | **loud 501 with `fidelity:"unsupported"`** |
 
 See [FIDELITY.md](./FIDELITY.md) for the full route table and known
 deviations from real Stripe.
@@ -137,19 +133,20 @@ Either way, the resolved session id must match the `:sid` in the URL.
 
 ## MCP
 
-15 tools available at `GET /s/:sid/mcp/tools`. Tool names match
+26 tools available at `GET /s/:sid/mcp/tools`. Tool names match
 `stripe-node` method names so an agent's mental model translates 1:1:
 
 ```
-create_payment_intent
-retrieve_payment_intent
-list_payment_intents
-confirm_payment_intent
-cancel_payment_intent
-simulate_crypto_deposit
-retrieve_charge
-list_charges
-retrieve_balance
+create_payment_intent          create_customer
+retrieve_payment_intent        retrieve_customer
+list_payment_intents           update_customer
+update_payment_intent          delete_customer
+confirm_payment_intent         list_customers
+cancel_payment_intent          list_customer_payment_methods
+simulate_crypto_deposit        create_payment_method
+retrieve_charge                retrieve_payment_method
+list_charges                   attach_payment_method
+retrieve_balance               detach_payment_method
 list_balance_transactions
 retrieve_event
 list_events
@@ -205,14 +202,19 @@ that pins and verifies the new signed digest.
 - The snapshot manifest at `pome-cloud/infra/twin-stripe-snapshot.json`
   records the OSS git sha and signed OCI digest each snapshot was built from.
 
-## What v1 does NOT do
+## What it does NOT do
+
+Shape tier (faithful response shape, deliberately no billing semantics —
+no events emitted, no invoices minted, no billing-cycle arithmetic):
+
+- Products, prices, subscriptions, invoice reads (F-734).
 
 Loud 501 with `fidelity: "unsupported"`:
 
-- All `/v1/shared_payment/*` (SPT) — deferred to v2.
-- Customer / payment-method CRUD — not on the x402 path.
-- Setup intents, refunds, products, prices, checkout sessions — v2.
-- Webhook delivery loop — agents poll `GET /v1/events` in v1.
+- Checkout sessions, payment links, setup intents, webhook endpoints —
+  named cold surfaces, test-backed.
+- All `/v1/shared_payment/*` (SPT) — deferred.
+- Webhook delivery loop — agents poll `GET /v1/events`.
 - Profiles, Connect, Issuing, Treasury, Tax, Climate, Identity — out forever
   for this twin.
 
@@ -235,26 +237,21 @@ Other deviations from real Stripe:
 npm install
 npm run dev                        # boot on :3333 with default seed
 npm run typecheck                  # tsc --noEmit
-npm run test                       # vitest, 17 files / 87 tests
+npm run test                       # vitest, 32 files / 237 tests
 npm run build                      # tsc → dist/src/server.js
 node dist/src/server.js            # production-shape boot
 ```
 
 ## Use it as a Stripe test double in your tests
 
-Until the package is on npm (post-Stage-1), the cleanest way is to clone
-this monorepo and shell out to `npm run dev` from your test setup:
+The cleanest way is to boot the published twin from your test setup; all
+it needs is Node ≥ 24:
 
 ```ts
 // In your test setup
 import { spawn } from "node:child_process";
-import { join } from "node:path";
-
-// Path to where you cloned pome-sh/pome-twins on disk
-const POME_REPO = process.env.POME_REPO ?? "/path/to/pome-twins";
 
-const twin = spawn("npm", ["run", "dev"], {
-  cwd: join(POME_REPO, "packages/twin-stripe"),
+const twin = spawn("npx", ["@pome-sh/cli", "twin", "start", "stripe"], {
   env: { ...process.env, PORT: "3333", STRIPE_CLONE_DB: ":memory:" },
 });
 // wait for /healthz before running your suite

package/node_modules/@pome-sh/twin-stripe/dist/scripts/fidelity-parity.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@pome-sh/twin-stripe/dist/scripts/fidelity-parity.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// fidelity:parity — declarative parity scenario for twin-stripe (F-730).
+// The runner lives in @pome-sh/sdk/parity; this file is scenario data only:
+// the crypto-deposit money chain (create PI → confirm → settle → charge →
+// refund → ledger → events), a second PI for the cancel path, the
+// customer-management chain (F-732: customer CRUD + card-on-file
+// attach/detach), and the card collect-payment chain (F-731: card PI →
+// update-with-PM → confirm → succeeded), covering every MCP tool in
+// fidelity.inventory.json. The refund steps assert the F-733 semantics:
+// the ledger link on the refund body and the post-refund available
+// balance. The loud-501 probe pins the
+// Stripe-shaped unsupported envelope on /v1/checkout/sessions (it moved
+// off /v1/customers when F-732 made customers a supported surface).
+import { join } from "node:path";
+import { loadFidelityInventory, runParityCli } from "@pome-sh/sdk/parity";
+import { createTwinStripeApp } from "../src/twin.js";
+import { listTools } from "../src/tools.js";
+const createPi = {
+    amount: 20000,
+    currency: "usd",
+    payment_method_types: ["crypto"],
+    payment_method_options: { crypto: { mode: "deposit", deposit_options: { networks: ["base"] } } },
+};
+const steps = [
+    {
+        tool: "create_payment_intent",
+        arguments: createPi,
+        capture: (body, state) => {
+            state.pi = body.id;
+        },
+    },
+    { tool: "retrieve_payment_intent", arguments: (state) => ({ id: state.pi }) },
+    { tool: "confirm_payment_intent", arguments: (state) => ({ id: state.pi }) },
+    {
+        tool: "simulate_crypto_deposit",
+        arguments: (state) => ({ id: state.pi }),
+        capture: (body, state) => {
+            state.charge = body.latest_charge;
+        },
+    },
+    { tool: "list_payment_intents", arguments: { limit: 10 } },
+    { tool: "retrieve_charge", arguments: (state) => ({ id: state.charge }) },
+    { tool: "list_charges", arguments: (state) => ({ payment_intent: state.pi }) },
+    {
+        tool: "create_refund",
+        arguments: (state) => ({ charge: state.charge, amount: 7500 }),
+        capture: (body, state) => {
+            state.refund = body.id;
+        },
+        verify: (body) => typeof body.balance_transaction === "string"
+            ? undefined
+            : "a refund should link its negative refund-type balance transaction (F-733)",
+    },
+    { tool: "retrieve_refund", arguments: (state) => ({ id: state.refund }) },
+    { tool: "list_refunds", arguments: (state) => ({ charge: state.charge }) },
+    {
+        tool: "retrieve_balance",
+        verify: (body) => {
+            const usd = body.available?.find((b) => b.currency === "usd");
+            // 20000 settled minus the 7500 refund above.
+            return usd?.amount === 12500
+                ? undefined
+                : `available balance should reflect the refund (expected 12500, got ${usd?.amount})`;
+        },
+    },
+    {
+        tool: "list_balance_transactions",
+        arguments: { limit: 10 },
+        verify: (body) => {
+            const data = body.data ?? [];
+            return data.some((t) => t.type === "refund" && t.amount === -7500)
+                ? undefined
+                : "the ledger should carry the negative refund-type entry (F-733)";
+        },
+    },
+    {
+        tool: "list_events",
+        arguments: { limit: 10 },
+        capture: (body, state) => {
+            state.event = body.data?.[0]?.id;
+        },
+    },
+    { tool: "retrieve_event", arguments: (state) => ({ id: state.event }) },
+    // Second PI: the cancel path (a settled PI refuses cancellation)
+    {
+        tool: "create_payment_intent",
+        arguments: createPi,
+        capture: (body, state) => {
+            state.pi2 = body.id;
+        },
+    },
+    { tool: "cancel_payment_intent", arguments: (state) => ({ id: state.pi2 }) },
+    // Customer-management chain (F-732): CRUD + card-on-file attach/detach.
+    {
+        tool: "create_customer",
+        arguments: { name: "Parity Customer", email: "parity@example.com", metadata: { a: "1" } },
+        capture: (body, state) => {
+            state.customer = body.id;
+        },
+    },
+    { tool: "retrieve_customer", arguments: (state) => ({ id: state.customer }) },
+    {
+        tool: "update_customer",
+        arguments: (state) => ({ id: state.customer, name: "Parity Customer II", metadata: { a: "", b: "2" } }),
+        verify: (body) => {
+            const metadata = body.metadata ?? {};
+            if (metadata.a !== undefined)
+                return "metadata key 'a' should have been unset by the empty value";
+            if (metadata.b !== "2")
+                return "metadata key 'b' should have been merged in";
+            return undefined;
+        },
+    },
+    { tool: "list_customers", arguments: { limit: 10 } },
+    {
+        tool: "create_payment_method",
+        arguments: { type: "card", card: { number: "4242424242424242", exp_month: 12, exp_year: 2032 } },
+        capture: (body, state) => {
+            state.pm = body.id;
+        },
+    },
+    { tool: "retrieve_payment_method", arguments: (state) => ({ id: state.pm }) },
+    {
+        tool: "attach_payment_method",
+        arguments: (state) => ({ id: state.pm, customer: state.customer }),
+        verify: (body) => body.customer ? undefined : "attach should set customer",
+    },
+    {
+        tool: "list_customer_payment_methods",
+        arguments: (state) => ({ customer: state.customer }),
+        verify: (body) => (body.data?.length ?? 0) === 1
+            ? undefined
+            : "customer should list exactly the attached PM",
+    },
+    {
+        tool: "detach_payment_method",
+        arguments: (state) => ({ id: state.pm }),
+        verify: (body) => body.customer === null ? undefined : "detach should clear customer",
+    },
+    { tool: "delete_customer", arguments: (state) => ({ id: state.customer }) },
+    // Card collect-payment chain (F-731): create bare card PI → attach a PM
+    // via update (the ruled retry step) → confirm → synchronous settle.
+    {
+        tool: "create_payment_intent",
+        arguments: { amount: 12000, currency: "usd", payment_method_types: ["card"] },
+        capture: (body, state) => {
+            state.cardPi = body.id;
+        },
+        verify: (body) => body.status === "requires_payment_method"
+            ? undefined
+            : "a card PI without a PM should start in requires_payment_method",
+    },
+    {
+        tool: "create_payment_method",
+        arguments: { type: "card", card: { number: "4242424242424242", exp_month: 12, exp_year: 2033 } },
+        capture: (body, state) => {
+            state.cardPm = body.id;
+        },
+    },
+    {
+        tool: "update_payment_intent",
+        arguments: (state) => ({ id: state.cardPi, payment_method: state.cardPm }),
+        verify: (body) => body.status === "requires_confirmation"
+            ? undefined
+            : "attaching a PM should move the card PI to requires_confirmation",
+    },
+    {
+        tool: "confirm_payment_intent",
+        arguments: (state) => ({ id: state.cardPi }),
+        verify: (body) => body.status === "succeeded"
+            ? undefined
+            : "confirming a good card should settle synchronously",
+    },
+];
+await runParityCli({
+    app: createTwinStripeApp(),
+    twin: "stripe",
+    inventory: loadFidelityInventory(join(import.meta.dirname, "..", "fidelity.inventory.json")),
+    liveToolNames: listTools().map((tool) => tool.name),
+    steps,
+    restProbes: [
+        { surface: "unsupported-rest", path: "/v1/checkout/sessions", status: 501, expectUnsupportedEnvelope: true },
+    ],
+});
+//# sourceMappingURL=fidelity-parity.js.map