@pome-sh/cli 0.20.0 → 0.21.0

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

@@ -1,380 +0,0 @@
-# Stripe Twin Fidelity
-
-`@pome-sh/twin-stripe` is a high-fidelity test double of Stripe's
-**x402 machine payments** surface — not a universal Stripe clone. This
-page documents exactly which surfaces are faithful to real Stripe today,
-at what tier, and how fidelity is verified.
-
-Last verified: 2026-07-12.
-Stripe API version pinned: `2026-03-04.preview`.
-
-## What "fidelity" means here
-
-Each REST route and MCP tool is classified into one of three tiers:
-
-- **`semantic`** — the stateful behavior is implemented locally and
-  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 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.
-
-For the build / runtime / cloud consumer invariants the hosted snapshot
-build depends on (port `:3333`, `/healthz`, `STRIPE_CLONE_HOST`,
-`npm install`-able package, `node dist/src/server.js`), see
-[Runtime contract](./README.md#runtime-contract-for-snapshot-consumers)
-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 = 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
-{
-  "error": {
-    "type": "invalid_request_error",
-    "code": "endpoint_not_supported",
-    "message": "This endpoint is not supported by this Stripe twin clone.",
-    "fidelity": "unsupported",
-    "supported_surfaces": [
-      "Stripe-shaped REST under /v1/* (see FIDELITY.md)",
-      "GET /s/:sid/mcp/tools",
-      "POST /s/:sid/mcp/call",
-      "POST /s/:sid/mcp/tools/:name"
-    ]
-  }
-}
-```
-
-HTTP status: 501.
-
-## 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:
-
-- Returns 402 with the canonical `accepts` body when the request lacks
-  an `X-PAYMENT` header.
-- Decodes the second-leg `X-PAYMENT` (base64 JSON), validates `to` ∈
-  cached payTo book, validates `value` matches priced amount, calls
-  `simulate_crypto_deposit` to settle the matching PI, then proxies the
-  wrapped handler.
-- Caches per-route challenges (5 min TTL) so replays don't mint
-  duplicate PIs.
-- Idempotent: same `X-PAYMENT` header twice returns the same response,
-  doesn't double-create state on the twin.
-
-**Known deviation**: v0 does NOT cryptographically verify EIP-3009
-signatures. Loud comment block at the top of `src/x402.ts`. We accept
-any well-formed `X-PAYMENT` payload that matches our payTo book +
-amount.
-
-Tests: `x402.test.ts` (6 cases), `x402-replay.test.ts` (2 cases),
-plus the `examples/buyer-agent/` end-to-end demo against a running twin.
-
-## Concurrency contract
-
-- **PI confirm/settle race** (`pi-concurrency.test.ts`): 8 parallel
-  `simulate_crypto_deposit` calls on one PI deterministically produce
-  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 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
-  client with a typo in its first request can retry under the same key
-  against a fresh handler invocation (matches real Stripe, which
-  re-executes on 4xx for client errors).
-- **Idempotency-Key under an injected lost response**
-  (`after-handler-idempotency.test.ts`, F-1138): the status the rule
-  above reads is the one the HANDLER answered, not the one on the wire.
-  An `after_handler` failure-injection rule delivers its configured 4xx
-  while the mutation stays committed, and real Stripe writes the
-  idempotency record server-side in exactly that case — a retry under
-  the same key replays the response the client never saw rather than
-  mutating again. A genuine 4xx from a handler is still not cached.
-
-## Pome introspection (`/_pome/*`)
-
-These are pome-internal observation routes, not part of Stripe's
-surface:
-
-- `GET /healthz` → `{ ok, twin, implementation, fidelity, tools, tthw_seconds }`.
-  Snapshot probe. tthw_seconds tracks time since process start (DX
-  measurement per plan §21).
-- `GET /s/:sid/_pome/health` → per-session liveness.
-- `GET /s/:sid/_pome/state` → full domain state export (PIs, charges,
-  balance txns, events). For test assertions.
-- `GET /s/:sid/_pome/events` → recorder events (HTTP request/response
-  log). For test assertions.
-
-Admin (localhost-only):
-
-- `POST /admin/reset` — reset to default seed.
-- `POST /admin/seed` — load custom seed JSON.
-
-## Auth shapes accepted
-
-- `Authorization: Bearer sk_test_pome_<sid>` — Stripe-SDK-compatible.
-  Default seed mints `sk_test_pome_default` mapped to sid=`default`.
-- `Authorization: Bearer <jwt>` where the JWT carries a `sid` claim
-  matching the URL — pome's twin-github-style auth.
-- `Authorization: <jwt>` (no `Bearer` prefix) — backwards-compat with
-  twin-github MCP clients.
-
-When the URL is path-prefixed (`/s/:sid/...`), the resolved sid must
-match the `:sid` param. 403 otherwise. When the URL has no `:sid`
-prefix (the SDK-compat root mount, see below), the bearer alone
-resolves the session.
-
-## SDK-compatibility mount
-
-`/v1/*` routes also work at the root path with the sid resolved from
-the bearer. This matches Stripe's URL shape so `stripe-node`,
-`stripe-python`, and friends can use `host`/`port` overrides without
-monkey-patching the path. Concretely:
-
-```
-POST /v1/payment_intents                → uses bearer's sid
-POST /s/:sid/v1/payment_intents         → uses path sid (must match bearer)
-```
-
-Both shapes hit the same handlers and produce identical responses. The
-account-scoping invariant (F1) holds for both: a key for sid=A hitting
-the root mount cannot see sid=B's data. `/_pome/*` and `/admin/*` are
-not exposed at the root mount — those remain at `/s/:sid/_pome/*` and
-`/admin/*` respectively. Tested in `sdk-compat.test.ts`.
-
-## Stripe-Version header
-
-- `Stripe-Version: 2026-03-04.preview` → served as-is.
-- Header omitted → served as `2026-03-04.preview` with a default warning.
-- Older GA version → 400 `api_version_unsupported` (no shape coercion;
-  fail loudly so SDKs that pin GA versions can't accidentally consume
-  preview shapes).
-
-## Known divergences from real Stripe (v1)
-
-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; 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
-   float window).
-5. **No webhook delivery loop**. `event_deliveries` table not in v1.
-   Agents poll `GET /v1/events`.
-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 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
-   deprecated field. The 3 other list surfaces — `payment_intents`,
-   `charges`, `balance_transactions` — are verified green against real
-   Stripe test mode.
-10. **`/v1/events` is not L1-auto-verified**. The empty fidelity world has
-    no event history while a real test account accrues events from every
-    action, and the live event body embeds account-identifying fields, so
-    this surface is left `unverified` (the event object shape is exercised
-    at L2 via `simulate_crypto_deposit` instead).
-11. **`/v1/balance` is not L1-auto-verified**. Real Stripe returns an
-    account-currency zero entry plus `source_types` /
-    `refund_and_dispute_prefunding`; the twin's empty `usd` world can't
-    reproduce an account-specific balance, so it is left `unverified`
-    (balance arithmetic is exercised semantically at L2).
-12. **PaymentIntent `payment_method_options.crypto` carries x402 `mode`/`deposit_options`**.
-    The twin emits the x402 deposit-mode rail (`mode: "deposit"`,
-    `deposit_options.networks: ["base"]`) on every PaymentIntent. The official
-    `stripe@22.2.0` `PaymentMethodOptions.Crypto` type has only `setup_future_usage`;
-    `mode` / `deposit_options` are x402 extension fields the twin adds. They are
-    lifted past the compile-time shape anchor (FDRS-478) via a named-variable spread
-    so the rest of the PaymentIntent stays strictly shape-checked.
-13. **PaymentIntent `next_action` carries the x402 crypto deposit instruction blob**.
-    A `requires_action` PaymentIntent surfaces `next_action` as the deterministic
-    Base/USDC deposit instruction (address + amount) the buyer-agent funds. The
-    official `PaymentIntent.next_action` union has no crypto-deposit member, so this
-    payload is an opaque blob the compile anchor cannot field-check — registered here
-    so the x402 extension shape is on the public record.
-14. **Event `type`/`data` are lifted past the `EventBase` envelope anchor**. The
-    event serializer is anchored against the shared `Stripe.EventBase` envelope
-    (id / object / api_version / created / livemode / pending_webhooks / request),
-    not the giant `Stripe.Event` discriminated union. `type` (twin emits a free
-    `string`; upstream is the `Event.Type` literal union) and `data` (twin stores an
-    opaque parsed JSON blob; upstream `Event.Data.object` is a typed resource union)
-    are narrowed for the type anchor only (FDRS-454); runtime values unchanged.
-15. **Compile anchor pins `stripe@22.2.0` (dahlia), decoupled from the `2026-03-04.preview` wire version**.
-    The compile-time shape anchor (FDRS-478) pins the official `stripe` library at
-    `22.2.0` (apiVersion 2026-05-27.dahlia), intentionally DECOUPLED from the wire
-    apiVersion the twin serves (`2026-03-04.preview`). The anchor guards SHAPE only;
-    the wire version is tracked by this page + live capture. Concretely, the dahlia
-    types dropped the top-level `invoice` field from PaymentIntent and Charge, which
-    the twin still emits faithfully to its preview wire version (lifted past the
-    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.
-
-## Verification commands
-
-```bash
-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

@@ -1,280 +0,0 @@
-# Pome Twin: Stripe x402
-
-> One of four twins in this repository (GitHub, Stripe x402, Slack, Gmail).
-
-`@pome-sh/twin-stripe` is the only deterministic test double for **Stripe
-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. 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
-
-The fastest path is the hosted twin: log in to [pome.sh](https://pome.sh),
-click **Stripe x402** on the Twins page, and a per-session sandbox spawns
-in seconds. The dashboard hands you a `sk_test_pome_<sid>` API key + the
-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), the zero-install path needs only Node ≥ 24:
-
-```bash
-npx @pome-sh/cli twin start stripe      # starts on :3333
-curl http://127.0.0.1:3333/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:
-#   new Stripe('sk_test_pome_default', { host: '127.0.0.1', port: 3333, protocol: 'http' })
-# Or curl the same root path:
-curl -s -X POST http://127.0.0.1:3333/v1/payment_intents \
-  -H "Authorization: Bearer sk_test_pome_default" \
-  -H "Content-Type: application/json" \
-  -d '{"amount":1000,"currency":"usd","payment_method_types":["crypto"],"payment_method_options":{"crypto":{"mode":"deposit","deposit_options":{"networks":["base"]}}}}' \
-  | python3 -m json.tool
-```
-
-You'll get back a real-shaped Stripe `PaymentIntent` in `requires_action`
-state with a Base USDC deposit address. Settle it with the test helper:
-
-```bash
-curl -s -X POST "http://127.0.0.1:3333/v1/test_helpers/payment_intents/<pi_id>/simulate_crypto_deposit" \
-  -H "Authorization: Bearer sk_test_pome_default" \
-  -d '{}'
-# → status: succeeded, latest_charge: ch_..., balance updated, 5 events emitted
-```
-
-The same routes are also mounted under `/s/:sid/v1/*` for path-routed
-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.
-
-## What ships today
-
-| Surface | Count | Tier |
-| --- | --- | --- |
-| 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 |
-| 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.
-
-## Running the buyer agent demo
-
-```bash
-# Terminal 1
-npm run -w @pome-sh/twin-stripe dev
-
-# Terminal 2
-npm start --prefix packages/twin-stripe/examples/buyer-agent
-```
-
-You'll see:
-
-```
-🛒 pome twin-stripe buyer-agent demo
-✓ got 402 challenge: pay 10000 USDC on eip155:84532 to 0x...
-✓ paid + got resource
-✓ twin reports 1 PI(s) with status=succeeded
-✓ twin emitted all 5 expected events
-✓ x402 buyer flow completed end-to-end
-```
-
-The seller is a Hono app with `paymentMiddleware()` mounted at
-`GET /paid`. The buyer hits it without an `X-PAYMENT` header (gets 402),
-then constructs a header against the deposit address and retries
-(gets 200).
-
-## Auth — works with real Stripe SDKs
-
-Two auth shapes are accepted:
-
-1. **Stripe-style API key** — `Authorization: Bearer sk_test_pome_<sid>`.
-   The default seed mints `sk_test_pome_default` so the standard Stripe
-   SDK constructor works unchanged:
-
-   ```ts
-   import Stripe from "stripe";
-   const stripe = new Stripe("sk_test_pome_default", {
-     host: "127.0.0.1",
-     port: 3333,
-     protocol: "http",
-   });
-   await stripe.paymentIntents.create({
-     amount: 1000,
-     currency: "usd",
-     payment_method_types: ["crypto"],
-     payment_method_options: {
-       crypto: { mode: "deposit", deposit_options: { networks: ["base"] } },
-     },
-   });
-   ```
-
-2. **Pome JWT** — `Authorization: Bearer <jwt>` where the JWT's `sid`
-   claim matches the URL's `/s/:sid/...`. Used by pome-cloud's
-   path-routed proxy.
-
-Either way, the resolved session id must match the `:sid` in the URL.
-
-## MCP
-
-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          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
-create_refund
-retrieve_refund
-list_refunds
-```
-
-Call shapes:
-
-```bash
-curl -s -X POST http://127.0.0.1:3333/s/default/mcp/call \
-  -H "Authorization: Bearer sk_test_pome_default" \
-  -H 'content-type: application/json' \
-  -d '{"tool":"create_payment_intent","arguments":{"amount":1000,"currency":"usd","payment_method_types":["crypto"],"payment_method_options":{"crypto":{"mode":"deposit","deposit_options":{"networks":["base"]}}}}}'
-```
-
-## Runtime contract (for snapshot consumers)
-
-`pome-cloud` builds a Vercel Sandbox snapshot from this package's signed source
-artifact. The following constraints must hold for that build to succeed and for
-the resulting snapshot to boot. Changing any of these is a breaking change for
-hosted; land the producer change here first, then open the cloud consumer PR
-that pins and verifies the new signed digest.
-
-### Build
-
-- Package is `npm install`-able from `package.json` alone (no
-  `workspace:*` protocols, no package-manager-specific deps; no committed lockfile is
-  required, the snapshot build regenerates one on each rebuild).
-- `npm run build` exits 0 and emits `dist/src/server.js`.
-- Built output is loadable under Node 24 — the snapshot runs
-  `runtime: "node24"`. SQLite is the built-in `node:sqlite` (via the sdk's
-  `openTwinDatabase()`, F-703) — no native modules, no compiler toolchain.
-
-### Runtime
-
-- Server entry: `node dist/src/server.js` (cwd = package root).
-- Listens on `:3333`.
-- Honors `STRIPE_CLONE_HOST=0.0.0.0` env (default `127.0.0.1` is
-  unreachable via Vercel Sandbox port forwarding).
-- `GET /healthz` returns 200 within ~3s of process start (the snapshot
-  build sleeps 3s after `node dist/src/server.js` before probing).
-- All admin routes (`/admin/*`) are localhost-only.
-- Bearer auth at `Authorization: Bearer <jwt>` or `Bearer sk_test_pome_<sid>`.
-
-### Cloud consumer coordination
-
-- Bumping any of the above = publish a signed twin digest and open the matching
-  `pome-cloud` consumer PR.
-- The cloud-side snapshot build script lives at
-  `pome-cloud/notes/build-twin-stripe-template.ts`.
-- 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 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"`:
-
-- 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.
-
-Other deviations from real Stripe:
-
-- **Single API version.** Only `2026-03-04.preview` is served.
-- **No EIP-3009 signature verification on x402 payloads.** Agents that
-  send well-formed `X-PAYMENT` headers matching our payTo book + amount
-  succeed. Documented in `src/x402.ts` head comment.
-- **OFFSET-style list pagination** (Stripe uses cursor-based).
-- **Synchronous deposit settlement.** `simulate_crypto_deposit` flips
-  `requires_action → processing → succeeded` synchronously; no chain
-  delay simulation.
-- **Single deposit network** (Base) and **single token** (USDC). Tempo
-  + Solana from Stripe's matrix are deferred.
-
-## Local commands
-
-```bash
-npm install
-npm run dev                        # boot on :3333 with default seed
-npm run typecheck                  # tsc --noEmit
-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
-
-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";
-
-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
-
-// In your code under test
-import Stripe from "stripe";
-const stripe = new Stripe("sk_test_pome_default", {
-  host: "127.0.0.1", port: 3333, protocol: "http",
-});
-
-// Run your agent. Assert against the twin's recorder:
-const events = await fetch("http://127.0.0.1:3333/s/default/_pome/events").then(r => r.json());
-// or against the twin's domain state:
-const state = await fetch("http://127.0.0.1:3333/s/default/_pome/state").then(r => r.json());
-```
-
-Test against the **state of the world after the agent ran**, not byte-
-for-byte response shapes. PI numbers, IDs, timestamps, and SHAs are
-deterministic-enough for tests but not identical to real Stripe.
-
-## Pome Cloud (twin selector)
-
-The hosted dashboard exposes a **Stripe x402** button next to GitHub.
-Clicking it spawns a per-session Vercel Sandbox running this exact package.
-The agent in your session sees the same surface this README describes; URLs
-are path-routed (`https://twins.pome.sh/s/<sid>/...`).

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

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