@volter/twin-stripe 0.1.0

package/src/stripe-ui-conformance.ts

@@ -0,0 +1,125 @@
+// Stripe UI conformance — the declared UI surface inventory for a Stripe dashboard,
+// classified against THIS twin, and the read-only completeness check over it.
+//
+// Honesty: `status` is the current truth, verified by the structural cross-check in
+// stripe-ui-conformance.test.ts (which builds the actual mirror bundle and asserts
+// each 'rendered' surface's helper/label/class is really present — downgrading to
+// 'modeled' otherwise). `rendered` = the mirror shows it today; `modeled` = the twin
+// has the data but the mirror doesn't render it (a UI gap to close); `unmodeled` =
+// real Stripe shows it but the twin doesn't model it (a twin-model gap to close).
+//
+// Classified against the actual mirror (client/stripe-mirror.tsx + the pure helpers in
+// stripe-mirror-ui.ts). The mirror has nineteen sections — customers, payment_intents,
+// setup_intents, subscriptions, invoices, invoiceitems, products, prices, charges,
+// refunds, payment_methods, disputes, payouts, balance_transactions, balance,
+// connected accounts, transfers, events — plus a Connect account panel (enablement
+// flags + outstanding requirements) and a generic detail panel that renders EVERY
+// scalar field (key/value grid), EVERY
+// nested object/array (flattened), status pills, amount/currency formatting, recurring
+// labels, product image <img> thumbnails, clickable cross-references (outgoing +
+// incoming), a prominent payment-decline banner (last_payment_error) and a synthesized
+// balance summary. So anything the twin stores on those collections is shown.
+import { checkUiCompleteness, type UiSurface, type UiCompletenessReport } from '@volter/twin-tooling';
+
+/** What a real Stripe dashboard shows, classified vs the twin + its UI mirror. */
+export const STRIPE_UI_INVENTORY: UiSurface[] = [
+  // --- shell / cross-cutting surfaces the mirror provides everywhere ---
+  { key: 'sectionNav', label: 'Left-nav sections (Customers/Payments/Subs/Invoices/Products/Prices) with counts', status: 'rendered' },
+  { key: 'listDetailSplit', label: 'List + detail split per section', status: 'rendered' },
+  { key: 'sectionFilter', label: 'In-section text filter / search', status: 'rendered' },
+  { key: 'statusPill', label: 'Status pill with semantic tone (ok/warn/bad)', status: 'rendered' },
+  { key: 'amountFormatting', label: 'Currency-formatted amounts (zero-decimal aware)', status: 'rendered' },
+  { key: 'nestedFields', label: 'Nested object/array fields flattened (no "[object Object]")', status: 'rendered' },
+  { key: 'crossLinksOutgoing', label: 'Outgoing cross-links (this row → referenced objects)', status: 'rendered' },
+  { key: 'crossLinksIncoming', label: 'Incoming cross-links (objects referencing this row)', status: 'rendered' },
+  { key: 'metadata', label: 'Object metadata key/values', status: 'rendered' },
+
+  // --- customers ---
+  { key: 'customerName', label: 'Customer name', status: 'rendered' },
+  { key: 'customerEmail', label: 'Customer email', status: 'rendered' },
+  // Customer credit balance is now modeled (customer.balance + a balance-transaction ledger)
+  // and rendered as its own "Customer Balance" mirror section (amount + running ending_balance).
+  { key: 'customerBalance', label: 'Customer account balance (credit-balance ledger)', status: 'rendered' },
+  // Customer tax IDs (eu_vat / us_ein / …) are a modeled customer sub-resource with their
+  // own "Customer Tax IDs" mirror section (value + type + owning customer cross-link).
+  { key: 'customerTaxIds', label: 'Customer tax IDs (value / type)', status: 'rendered' },
+
+  // --- payments (payment_intents) ---
+  { key: 'paymentList', label: 'Payments list (amount + id)', status: 'rendered' },
+  { key: 'paymentStatus', label: 'Payment status (succeeded/requires_*/…)', status: 'rendered' },
+  { key: 'paymentAmount', label: 'Payment amount (formatted)', status: 'rendered' },
+  { key: 'paymentCustomerLink', label: 'Payment → customer cross-link', status: 'rendered' },
+  // test-card decline state: last_payment_error rendered as a prominent error banner.
+  { key: 'paymentDecline', label: 'Payment decline reason (last_payment_error banner)', status: 'rendered' },
+
+  // --- setup_intents (off-session card save) ---
+  { key: 'setupIntents', label: 'Setup intents list + status (requires_confirmation/succeeded)', status: 'rendered' },
+
+  // --- subscriptions ---
+  { key: 'subscriptionStatus', label: 'Subscription status (active/trialing/past_due/…)', status: 'rendered' },
+  { key: 'subscriptionCustomerLink', label: 'Subscription → customer cross-link', status: 'rendered' },
+  // items + period are nested objects the twin stores and the flattener renders.
+  { key: 'subscriptionItems', label: 'Subscription line items (nested)', status: 'rendered' },
+  { key: 'subscriptionPeriod', label: 'Billing-cycle / period fields', status: 'rendered' },
+
+  // --- invoices ---
+  { key: 'invoiceStatus', label: 'Invoice status (draft/open/paid/void/…)', status: 'rendered' },
+  { key: 'invoiceTotal', label: 'Invoice total / amount_due (formatted)', status: 'rendered' },
+  { key: 'invoiceLines', label: 'Invoice line items (nested list)', status: 'rendered' },
+  { key: 'invoiceCustomerLink', label: 'Invoice → customer cross-link', status: 'rendered' },
+  // invoiceitems are a full twin resource with their own list endpoint + nav section.
+  { key: 'invoiceItems', label: 'Invoice items list (pending line items)', status: 'rendered' },
+  // credit notes are a full twin resource (create/preview/void/list) with their own nav
+  // section + list/detail; rows show the credited amount + status, with an invoice cross-link.
+  { key: 'creditNotes', label: 'Credit notes list (credited amount + status)', status: 'rendered' },
+  { key: 'creditNoteLines', label: 'Credit note line items (nested)', status: 'rendered' },
+
+  // --- products ---
+  { key: 'productName', label: 'Product name', status: 'rendered' },
+  // images is an array of URLs; the detail view now renders them as <img> thumbnails.
+  { key: 'productImageThumbs', label: 'Product image thumbnails (rendered as <img>)', status: 'rendered' },
+
+  // --- prices ---
+  { key: 'priceUnitAmount', label: 'Price unit amount (formatted)', status: 'rendered' },
+  { key: 'priceRecurring', label: 'Price recurring interval ("every month")', status: 'rendered' },
+  { key: 'priceProductLink', label: 'Price → product cross-link', status: 'rendered' },
+
+  // --- collections the twin models, now each with its own nav section + list/detail ---
+  // charges, refunds and payment_methods are full twin resources with list endpoints;
+  // stripe-mirror.tsx now has a nav section + list/detail for each.
+  { key: 'charges', label: 'Charges list + status', status: 'rendered' },
+  { key: 'refunds', label: 'Refunds list (refund objects)', status: 'rendered' },
+  { key: 'paymentMethods', label: 'Saved payment methods (cards)', status: 'rendered' },
+
+  // disputes/payouts/balance_transactions/events are full twin resources with list +
+  // CRUD/action endpoints (stripe-twin.ts) and vendor-faithful schemas; the mirror now
+  // renders a nav section + list/detail for each.
+  { key: 'disputes', label: 'Disputes', status: 'rendered' },
+  { key: 'payouts', label: 'Payouts', status: 'rendered' },
+  { key: 'balanceTransactions', label: 'Balance transactions ledger', status: 'rendered' },
+  // the synthesized account balance summary (GET /v1/balance) has its own nav section
+  // with available/pending buckets per currency.
+  { key: 'balanceSummary', label: 'Account balance summary (available/pending)', status: 'rendered' },
+  { key: 'eventsLog', label: 'Events / activity log', status: 'rendered' },
+
+  // --- Connect (connected accounts + transfers) — full twin resources with their own
+  // nav sections + list/detail; the account detail surfaces the enablement flags +
+  // outstanding requirements, transfers cross-link to their destination account. ---
+  { key: 'connectAccounts', label: 'Connect / connected accounts list + detail', status: 'rendered' },
+  { key: 'connectAccountFlags', label: 'Connected-account enablement flags (charges/payouts/details_submitted)', status: 'rendered' },
+  { key: 'connectAccountRequirements', label: 'Connected-account outstanding onboarding requirements (currently_due)', status: 'rendered' },
+  { key: 'connectTransfers', label: 'Transfers list (platform → connected account)', status: 'rendered' },
+  { key: 'connectTransferDestinationLink', label: 'Transfer → destination connected-account cross-link', status: 'rendered' },
+
+  // --- Stripe Tax (tax rates + calculations) — full twin resources with their own nav
+  // sections + list/detail; rates show display_name/percentage/inclusive, calculations
+  // show amount_total + tax + their priced line_items (nested). ---
+  { key: 'taxRates', label: 'Tax rates list (display_name / percentage / inclusive)', status: 'rendered' },
+  { key: 'taxCalculations', label: 'Tax calculations list (amount_total + tax amount)', status: 'rendered' },
+  { key: 'taxCalculationLineItems', label: 'Tax calculation line items (nested, per-item tax)', status: 'rendered' },
+];
+
+/** Read-only completeness check over the declared Stripe UI inventory. */
+export function stripeUiConformance(): UiCompletenessReport {
+  return checkUiCompleteness('stripe', STRIPE_UI_INVENTORY);
+}

package/src/stripe-ui-structure.ts

@@ -0,0 +1,406 @@
+// Stripe MIRROR — structural DOM checklist (RUNG-5).
+//
+// Completeness (stripe-ui-conformance.ts) asks "does the mirror SHOW the data?".
+// Structure asks a stricter, proximity question: "does the mirror's rendered DOM have
+// the same structural LANDMARKS a real Stripe dashboard screen has?" — a left nav with
+// an item (and count) per collection, a list pane that emits a row per object, a detail
+// pane with a scalar key/value grid, nested objects rendered as indented lines (NOT
+// "[object Object]"), status pills, a cross-reference "Related" block of links,
+// product image <img> thumbnails, a prominent payment-decline banner (last_payment_error)
+// and the synthesized balance available/pending summary buckets.
+//
+// Each check's `present` is computed from the ACTUAL markup produced by
+// renderToStaticMarkup() of the mirror's own presentational components (exported from
+// client/stripe-mirror.tsx) over seeded, cross-referenced objects — so a check cannot
+// pass unless the component truly emits that structure. Read-only; deterministic.
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { checkUiStructure, type UiStructureReport } from '@volter/twin-tooling';
+import {
+  SECTIONS, SideNav, ListPane, Detail, type Section,
+} from '../client/stripe-mirror.tsx';
+import {
+  resolveCrossRefs, productImageUrls,
+  type StripeRow, type CrossRefs,
+} from './stripe-mirror-ui.ts';
+
+const SECTION_BY_KEY: Record<string, Section> = Object.fromEntries(SECTIONS.map((s) => [s.key, s]));
+
+// ── Seed: a small, cross-referenced slice of every shape a dashboard renders. ──────
+// One object per collection we assert on, wired with real Stripe reference fields so
+// the cross-ref resolver produces both outgoing and incoming "Related" links, and with
+// nested objects/arrays (subscription items, invoice lines, product images) so the
+// nested-line + thumbnail structure has something real to render.
+const CUSTOMER: StripeRow = {
+  id: 'cus_twin001', object: 'customer', name: 'Ada Lovelace', email: 'ada@example.com', currency: 'usd',
+  metadata: { plan: 'pro', seats: '5' },
+};
+const PRODUCT: StripeRow = {
+  id: 'prod_twin001', object: 'product', name: 'Analytics Suite', active: true,
+  images: ['https://files.stripe.com/img/one.png', 'https://files.stripe.com/img/two.png'],
+};
+const PRICE: StripeRow = {
+  id: 'price_twin001', object: 'price', product: 'prod_twin001', currency: 'usd', unit_amount: 4200,
+  recurring: { interval: 'month', interval_count: 1 },
+};
+const SUBSCRIPTION: StripeRow = {
+  id: 'sub_twin001', object: 'subscription', status: 'active', customer: 'cus_twin001', currency: 'usd',
+  items: {
+    object: 'list',
+    data: [
+      { id: 'si_twin001', object: 'subscription_item', quantity: 5, price: 'price_twin001' },
+    ],
+  },
+};
+const INVOICE: StripeRow = {
+  id: 'in_twin001', object: 'invoice', status: 'paid', customer: 'cus_twin001', subscription: 'sub_twin001',
+  currency: 'usd', total: 21000, amount_due: 21000,
+  lines: {
+    object: 'list',
+    data: [
+      { id: 'il_twin001', object: 'line_item', amount: 21000, quantity: 5, price: 'price_twin001' },
+    ],
+  },
+};
+const DISPUTE: StripeRow = {
+  id: 'dp_twin001', object: 'dispute', amount: 4200, currency: 'usd', reason: 'fraudulent',
+  status: 'warning_needs_response', charge: 'ch_twin001',
+};
+const PAYOUT: StripeRow = {
+  id: 'po_twin001', object: 'payout', amount: 16800, currency: 'usd', status: 'in_transit',
+  arrival_date: 1718409600,
+};
+// A declined payment_intent carries the vendor-faithful last_payment_error (test-card
+// decline state) the mirror lifts into a prominent banner.
+const DECLINED_PAYMENT: StripeRow = {
+  id: 'pi_twin009', object: 'payment_intent', amount: 4200, currency: 'usd', customer: 'cus_twin001',
+  status: 'requires_payment_method',
+  last_payment_error: { type: 'card_error', code: 'card_declined', decline_code: 'insufficient_funds', message: 'Your card has insufficient funds.', param: 'card' },
+};
+// The synthesized account balance summary (GET /v1/balance), presented as a one-row list.
+const BALANCE: StripeRow = {
+  id: 'balance', object: 'balance', livemode: false,
+  available: [{ amount: 16800, currency: 'usd', source_types: { card: 16800 } }],
+  pending: [{ amount: 4200, currency: 'usd', source_types: { card: 4200 } }],
+};
+// A Connect connected account, freshly created (not yet onboarded): charges/payouts
+// disabled, details not submitted, with outstanding `requirements.currently_due`.
+const ACCOUNT: StripeRow = {
+  id: 'acct_twin001', object: 'account', type: 'express', country: 'US', email: 'seller@example.com',
+  charges_enabled: false, payouts_enabled: false, details_submitted: false,
+  capabilities: { card_payments: 'inactive' },
+  requirements: { currently_due: ['external_account', 'tos_acceptance.date'], eventually_due: [], past_due: [], pending_verification: [] },
+};
+// A transfer from the platform balance to the connected account above (destination cross-ref).
+const TRANSFER: StripeRow = {
+  id: 'tr_twin001', object: 'transfer', amount: 16800, currency: 'usd', destination: 'acct_twin001',
+  reversed: false, amount_reversed: 0,
+};
+
+// A Stripe Tax rate (reusable) and a tax calculation with priced line_items (nested).
+const TAX_RATE: StripeRow = {
+  id: 'txr_twin001', object: 'tax_rate', display_name: 'Sales Tax', percentage: 8.5,
+  inclusive: false, active: true, jurisdiction: 'US',
+};
+const TAX_CALCULATION: StripeRow = {
+  id: 'taxcalc_twin001', object: 'tax.calculation', currency: 'usd', amount_total: 1100,
+  tax_amount_exclusive: 100, customer: 'cus_twin001',
+  line_items: {
+    object: 'list',
+    data: [
+      { id: 'tax_li_taxcalc_twin001_1', object: 'tax.calculation_line_item', amount: 1000, amount_tax: 100, reference: 'sku_1', tax_behavior: 'exclusive' },
+    ],
+  },
+};
+
+// A credit note crediting back a paid invoice, with a nested credit_note_line_item, and
+// cross-refs to its invoice + customer. The mirror's Credit Notes section renders it.
+const CREDIT_NOTE: StripeRow = {
+  id: 'cn_twin001', object: 'credit_note', amount: 5000, currency: 'usd', status: 'issued',
+  invoice: 'in_twin001', customer: 'cus_twin001', type: 'post_payment', number: 'in_twin001-CN-01',
+  lines: {
+    object: 'list',
+    data: [
+      { id: 'cnli_cn_twin001_1', object: 'credit_note_line_item', type: 'custom_line_item', amount: 5000, description: 'goodwill credit' },
+    ],
+  },
+};
+// A customer tax ID (EU VAT) on the customer above (customer cross-ref).
+const TAX_ID: StripeRow = {
+  id: 'txi_twin001', object: 'tax_id', type: 'eu_vat', value: 'DE123456789',
+  customer: 'cus_twin001', country: 'DE', verification: { status: 'pending' },
+};
+// A customer balance transaction (a -2000 credit) with its running ending_balance.
+const CUSTOMER_BALANCE_TXN: StripeRow = {
+  id: 'cbtxn_twin001', object: 'customer_balance_transaction', amount: -2000, currency: 'usd',
+  ending_balance: -2000, type: 'adjustment', customer: 'cus_twin001', credit_note: 'cn_twin001',
+};
+
+const DATA: Record<string, StripeRow[]> = {
+  customers: [CUSTOMER],
+  credit_notes: [CREDIT_NOTE],
+  tax_ids: [TAX_ID],
+  customer_balance_transactions: [CUSTOMER_BALANCE_TXN],
+  tax_rates: [TAX_RATE],
+  'tax/calculations': [TAX_CALCULATION],
+  products: [PRODUCT],
+  prices: [PRICE],
+  subscriptions: [SUBSCRIPTION],
+  invoices: [INVOICE],
+  disputes: [DISPUTE],
+  payouts: [PAYOUT],
+  payment_intents: [DECLINED_PAYMENT],
+  balance: [BALANCE],
+  accounts: [ACCOUNT],
+  transfers: [TRANSFER],
+};
+
+const noop = () => {};
+
+/** renderToStaticMarkup the left nav (one item + count per collection). */
+function renderNav(): string {
+  const counts = Object.fromEntries(SECTIONS.map((s) => [s.key, DATA[s.key]?.length ?? 0]));
+  return renderToStaticMarkup(
+    createElement(SideNav, { sections: SECTIONS, counts, activeKey: SECTIONS[0]!.key, onSelect: noop }),
+  );
+}
+
+/** renderToStaticMarkup the list pane for a collection (a row per object). */
+function renderList(collection: string, rows: StripeRow[]): string {
+  return renderToStaticMarkup(
+    createElement(ListPane, { section: SECTION_BY_KEY[collection]!, rows, currentId: rows[0]?.id, onSelect: noop }),
+  );
+}
+
+/** renderToStaticMarkup the detail pane for a row, with its resolved cross-refs. */
+function renderDetail(collection: string, row: StripeRow): string {
+  const refs: CrossRefs = resolveCrossRefs(collection, row, DATA);
+  return renderToStaticMarkup(
+    createElement(Detail, { collection, row, refs, onJump: noop }),
+  );
+}
+
+/**
+ * Build the structural checklist from the real rendered markup and run it.
+ * ~10 checks, every one asserting a Stripe-dashboard structural landmark.
+ */
+export function stripeUiStructure(): UiStructureReport {
+  const nav = renderNav();
+  const customersList = renderList('customers', DATA.customers!);
+  const subscriptionDetail = renderDetail('subscriptions', SUBSCRIPTION);
+  const invoiceDetail = renderDetail('invoices', INVOICE);
+  const productDetail = renderDetail('products', PRODUCT);
+  const customerDetail = renderDetail('customers', CUSTOMER);
+  const declinedPaymentDetail = renderDetail('payment_intents', DECLINED_PAYMENT);
+  const balanceDetail = renderDetail('balance', BALANCE);
+  const accountDetail = renderDetail('accounts', ACCOUNT);
+  const transferDetail = renderDetail('transfers', TRANSFER);
+  const taxRatesList = renderList('tax_rates', DATA.tax_rates!);
+  const taxCalculationDetail = renderDetail('tax/calculations', TAX_CALCULATION);
+  const creditNotesList = renderList('credit_notes', DATA.credit_notes!);
+  const creditNoteDetail = renderDetail('credit_notes', CREDIT_NOTE);
+  const taxIdsList = renderList('tax_ids', DATA.tax_ids!);
+  const customerBalanceTxnDetail = renderDetail('customer_balance_transactions', CUSTOMER_BALANCE_TXN);
+
+  // How many collection nav items the markup emits. The left nav now also renders the Home
+  // and Settings chrome buttons (which carry no per-collection count), so the per-collection
+  // landmark counts the items that carry a nav-count — exactly one per collection.
+  const navItems = (nav.match(/nav-count/g) ?? []).length;
+  const customerRows = (customersList.match(/list-row/g) ?? []).length;
+
+  const checks = [
+    {
+      key: 'navItemPerCollection',
+      label: 'Left nav emits a nav item per collection (Customers/Payments/Subscriptions/Invoices/Products/…)',
+      present: navItems === SECTIONS.length && nav.includes('class="side"'),
+    },
+    {
+      key: 'navCounts',
+      label: 'Each left-nav item carries a per-collection object count',
+      present: (nav.match(/nav-count/g) ?? []).length === SECTIONS.length,
+    },
+    {
+      key: 'listRowPerObject',
+      label: 'List pane emits one row per object in the section',
+      present: customerRows === DATA.customers!.length && customersList.includes('class="list"'),
+    },
+    {
+      key: 'detailScalarGrid',
+      label: 'Detail pane renders a scalar field key/value grid (<dl>/<dt>/<dd>)',
+      present: customerDetail.includes('<dl>') && customerDetail.includes('<dt>') && customerDetail.includes('<dd'),
+    },
+    {
+      key: 'detailHeaderId',
+      label: 'Detail pane shows the object id in its header',
+      present: customerDetail.includes('detail-head') && customerDetail.includes(CUSTOMER.id),
+    },
+    {
+      key: 'nestedLinesNotObjectObject',
+      label: 'Nested objects/arrays render as indented nested lines, never "[object Object]"',
+      present:
+        subscriptionDetail.includes('class="nested"') &&
+        subscriptionDetail.includes('nested-line') &&
+        !subscriptionDetail.includes('[object Object]') &&
+        !invoiceDetail.includes('[object Object]'),
+    },
+    {
+      key: 'nestedListItems',
+      label: 'Nested Stripe list wrappers (subscription items / invoice lines) flatten to their data rows',
+      present:
+        subscriptionDetail.includes('si_twin001') &&
+        invoiceDetail.includes('il_twin001'),
+    },
+    {
+      key: 'statusPill',
+      label: 'A status pill element renders for objects with a status (active/paid/…)',
+      present: subscriptionDetail.includes('class="pill') && invoiceDetail.includes('class="pill'),
+    },
+    {
+      key: 'relatedCrossRefBlock',
+      label: 'A cross-ref "Related" block renders outgoing reference links',
+      present:
+        invoiceDetail.includes('detail-block refs') &&
+        invoiceDetail.includes('>Related<') &&
+        invoiceDetail.includes('>References<') &&
+        (invoiceDetail.match(/ref-chip/g) ?? []).length >= 1,
+    },
+    {
+      key: 'relatedIncomingRefs',
+      label: 'The "Related" block renders incoming "Referenced by" links (objects pointing at this row)',
+      // The customer is pointed AT by the subscription + invoice → incoming chips.
+      present:
+        customerDetail.includes('detail-block refs') &&
+        customerDetail.includes('>Referenced by<') &&
+        (customerDetail.match(/ref-chip/g) ?? []).length >= 1,
+    },
+    {
+      key: 'crossRefResolvesTargetLabel',
+      label: 'Cross-ref links resolve the target object label (not just a bare id)',
+      // invoice → customer outgoing chip carries the resolved customer name.
+      present: invoiceDetail.includes('Ada Lovelace'),
+    },
+    {
+      key: 'productImageThumbs',
+      label: 'Product images render as <img> thumbnails',
+      present:
+        productDetail.includes('class="thumbs"') &&
+        (productDetail.match(/<img/g) ?? []).length === productImageUrls(PRODUCT.images).length &&
+        productImageUrls(PRODUCT.images).length > 0,
+    },
+    {
+      key: 'paymentDeclineBanner',
+      label: 'A declined payment_intent renders its last_payment_error as a prominent banner (decline reason + code)',
+      present:
+        declinedPaymentDetail.includes('class="pay-error"') &&
+        declinedPaymentDetail.includes('Payment error') &&
+        declinedPaymentDetail.includes('card_declined') &&
+        declinedPaymentDetail.includes('insufficient_funds') &&
+        // lifted out of the generic grid, not buried as a raw nested object
+        !declinedPaymentDetail.includes('[object Object]'),
+    },
+    {
+      key: 'balanceSummaryBuckets',
+      label: 'The balance section renders available/pending summary buckets with formatted amounts',
+      present:
+        balanceDetail.includes('class="balance-summary"') &&
+        balanceDetail.includes('balance-bucket available') &&
+        (balanceDetail.match(/balance-bucket/g) ?? []).length >= 2 &&
+        balanceDetail.includes('$168.00') &&
+        balanceDetail.includes('$42.00'),
+    },
+    {
+      key: 'connectAccountFlags',
+      label: 'A connected account renders its enablement flags (charges/payouts/details_submitted) as tone-carrying tiles',
+      present:
+        accountDetail.includes('class="connect-panel"') &&
+        (accountDetail.match(/connect-flag /g) ?? []).length >= 3 &&
+        accountDetail.includes('>Charges<') &&
+        accountDetail.includes('>Payouts<') &&
+        accountDetail.includes('>Details submitted<') &&
+        // a freshly-created account is not enabled → disabled state shown
+        accountDetail.includes('>disabled<'),
+    },
+    {
+      key: 'connectAccountRequirements',
+      label: 'A connected account renders its outstanding onboarding requirements (currently_due)',
+      present:
+        accountDetail.includes('class="connect-requirements"') &&
+        accountDetail.includes('Requirements currently due') &&
+        accountDetail.includes('external_account') &&
+        accountDetail.includes('tos_acceptance.date'),
+    },
+    {
+      key: 'transferDestinationCrossRef',
+      label: 'A transfer renders a cross-ref link to its destination connected account',
+      present:
+        transferDetail.includes('detail-block refs') &&
+        (transferDetail.match(/ref-chip/g) ?? []).length >= 1 &&
+        transferDetail.includes('acct_twin001'),
+    },
+    {
+      key: 'taxRatesListRow',
+      label: 'The Tax Rates section emits a list row per rate (display_name + percentage)',
+      present:
+        (taxRatesList.match(/list-row/g) ?? []).length === DATA.tax_rates!.length &&
+        taxRatesList.includes('Sales Tax') &&
+        taxRatesList.includes('8.5'),
+    },
+    {
+      key: 'taxCalculationLineItems',
+      label: 'A tax calculation renders its priced line_items as nested lines (per-item tax)',
+      present:
+        taxCalculationDetail.includes('class="nested"') &&
+        taxCalculationDetail.includes('tax_li_taxcalc_twin001_1') &&
+        !taxCalculationDetail.includes('[object Object]'),
+    },
+    {
+      key: 'taxCalculationTotals',
+      label: 'A tax calculation renders its amount_total and tax_amount_exclusive (currency-formatted)',
+      present:
+        taxCalculationDetail.includes('$11.00') &&
+        taxCalculationDetail.includes('$1.00'),
+    },
+    {
+      key: 'creditNotesListRow',
+      label: 'The Credit Notes section emits a list row per credit note (credited amount + status)',
+      present:
+        (creditNotesList.match(/list-row/g) ?? []).length === DATA.credit_notes!.length &&
+        creditNotesList.includes('$50.00') &&
+        creditNotesList.includes('issued'),
+    },
+    {
+      key: 'creditNoteLineItems',
+      label: 'A credit note renders its nested line_items (per-line credited amount), never "[object Object]"',
+      present:
+        creditNoteDetail.includes('class="nested"') &&
+        creditNoteDetail.includes('cnli_cn_twin001_1') &&
+        !creditNoteDetail.includes('[object Object]'),
+    },
+    {
+      key: 'creditNoteInvoiceCrossRef',
+      label: 'A credit note renders a cross-ref link to the invoice it credits',
+      present:
+        creditNoteDetail.includes('detail-block refs') &&
+        (creditNoteDetail.match(/ref-chip/g) ?? []).length >= 1 &&
+        creditNoteDetail.includes('in_twin001'),
+    },
+    {
+      key: 'customerTaxIdsListRow',
+      label: 'The Customer Tax IDs section emits a list row per tax ID (value + type)',
+      present:
+        (taxIdsList.match(/list-row/g) ?? []).length === DATA.tax_ids!.length &&
+        taxIdsList.includes('DE123456789') &&
+        taxIdsList.includes('eu_vat'),
+    },
+    {
+      key: 'customerBalanceTxnDetail',
+      label: 'A customer balance transaction renders its amount + running ending_balance (formatted) with a customer cross-ref',
+      present:
+        customerBalanceTxnDetail.includes('detail-block refs') &&
+        customerBalanceTxnDetail.includes('-$20.00') &&
+        (customerBalanceTxnDetail.match(/ref-chip/g) ?? []).length >= 1,
+    },
+  ];
+
+  return checkUiStructure('stripe', checks);
+}

package/test-fixtures/stripe-known-deviations.json

@@ -0,0 +1,85 @@
+{
+ "_doc": "Declared scope for the Stripe twin: published fields it does NOT emit, each with a reason. The spec-conformance gate (stripe-conformance.ts) treats a missing-required field as a BUG unless it is declared here. Applies across the Stripe objects the twin serves. Stripe is the twin we cannot dual-run live, so the published OpenAPI is the authority \u2014 keeping this list short and reasoned is how we stay honest about the gaps.",
+ "deviations": [
+  {
+   "path": "type",
+   "kind": "missing-required",
+   "reason": "Stripe's price.type (one_time|recurring) collides with the kernel's resource-type discriminator (every twin resource carries an internal `type`, which view() strips before emit). So a vendor `type` field cannot currently be emitted. Known limitation \u2014 a candidate for moving the kernel discriminator to a reserved key. Only `price` declares a required `type`; other served objects do not."
+  },
+  {
+   "path": "_price.type-list-filter",
+   "kind": "list-filter-approximated",
+   "reason": "GET /v1/prices?type=one_time|recurring cannot filter on the (stripped) price.type field for the same reason price.type is a declared missing-required deviation above. It is approximated by the presence of the vendor `recurring` object \u2014 recurring prices carry it, one-time prices do not \u2014 which is faithful for prices the twin itself created. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_invoice.subscription-list-filter",
+   "kind": "list-filter-unmodeled",
+   "reason": "GET /v1/invoices accepts a `subscription` filter param (Stripe documents it) but the twin does not auto-link invoices to subscriptions: invoices are created as standalone drafts, and modern Stripe nests the link under parent.subscription_details.subscription rather than a top-level field (the vendor schema has no top-level invoice.subscription). The filter therefore only matches when a caller has explicitly stored a `subscription` field on the invoice; otherwise it yields no matches. The param is accepted, not rejected \u2014 consistent with Stripe ignoring filters that match nothing. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_dispute.not-auto-created",
+   "kind": "resource-modeled-statefully",
+   "reason": "Disputes are modeled statefully via the action log (create/list/retrieve/update/close), NOT auto-raised from charges: the twin does not simulate an acquirer/cardholder raising a chargeback, so no dispute appears merely because a charge exists. A caller (or seeding) creates one referencing a charge via POST /v1/disputes. All 15 vendor-required dispute fields ARE emitted (amount, balance_transactions, charge, created, currency, enhanced_eligibility_types, evidence, evidence_details, is_charge_refundable, livemode, metadata, reason, status, plus id/object); `amount`/`charge` come from the caller (Stripe disputes always reference a charge). Closing is terminal (status -> lost), matching Stripe. evidence/evidence_details emit Stripe's canonical empty shapes (all-null evidence bag), not fabricated content. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_payout.created-not-settled",
+   "kind": "resource-modeled-statefully",
+   "reason": "Payouts are modeled statefully via the action log (create/list/retrieve/cancel). The twin does not simulate the bank-settlement timeline: a created payout starts `status=pending` and only transitions on an explicit POST /v1/payouts/:id/cancel (-> canceled); it does not auto-advance to in_transit/paid. arrival_date is stamped at creation time rather than a real future settlement date. All vendor-required payout fields are emitted; `amount`/`currency` come from the caller and are validated (positive integer + currency) like charges. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_balance.synthesized-from-ledger",
+   "kind": "resource-synthesized",
+   "reason": "GET /v1/balance is synthesized from the balance_transaction ledger, not stored: settled transactions (status=available) fold into the `available` array and unsettled ones (status=pending) into `pending`, summed by currency over each transaction's `net` (amount minus fee). This mirrors Stripe's available/pending arrays per currency. The per-currency source_types breakdown is approximated as all-`card`. With no ledger the balance is a valid zero (one usd entry). Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_balance_transaction.writable-for-seeding",
+   "kind": "resource-modeled-statefully",
+   "reason": "In real Stripe, balance_transactions are created only as side-effects of money movement (charges, refunds, payouts) and have no create endpoint. The twin exposes POST /v1/balance_transactions so the ledger can be seeded statefully, since the twin does not auto-generate a balance_transaction for every charge/refund/payout. `net` defaults to amount - fee. All vendor-required fields are emitted with faithful enum values (type/status/balance_type/reporting_category). Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_card.declines-test-set-only",
+   "kind": "behavior-modeled-subset",
+   "reason": "Charge/PaymentIntent-confirm card declines are modeled for Stripe's DOCUMENTED TEST CARDS only (PAN 4242\u20264242 + pm_card_visa/tok_visa succeed; 4000\u20260002 generic_decline, 4000\u20269995 insufficient_funds, 4000\u20260069 expired_card, 4000\u20260127 incorrect_cvc, 4000\u20260119 processing_error, plus the matching pm_card_*/tok_* tokens). A known declining card returns the real Stripe card-error envelope (HTTP 402, error.type=card_error, code, decline_code for card_declined, message, param=card, and the charge/payment_intent id) and leaves a confirmed PaymentIntent at status=requires_payment_method with last_payment_error set; a declined charge is not persisted. ANY card the twin does not recognize (real PANs, unknown test tokens, or no card at all) succeeds, deterministically \u2014 the twin is not a risk/fraud engine and does not simulate issuer behavior beyond Stripe's published test set. Resolution reads card[number]/source[number] (raw PAN) or payment_method/source/card (token id). Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_idempotency.stored-per-root",
+   "kind": "behavior-modeled-statefully",
+   "reason": "The Idempotency-Key request header is honored on POST: the first request with a key executes and its (status + body) response is persisted in the action log as an internal `_idempotency` resource; a replay with the SAME key returns the byte-identical stored response without re-applying the write (verified: two POSTs \u2192 one resource). Simplifications vs real Stripe: the stored response is keyed per twin-root (a fork has its own keyspace) rather than per Stripe account+key; there is no 24h expiry; and the twin does not detect a request-payload mismatch for a reused key (real Stripe 400s when the same key is reused with different params). Every executed POST is stored, including card-decline 402s (Stripe also persists those). `_idempotency` is twin-internal and never served as a Stripe object, so it is exempt from spec conformance. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_event.modeled-shape",
+   "kind": "resource-modeled-statefully",
+   "reason": "The Events API (GET /v1/events, GET /v1/events/:id) is modeled statefully via the action log. The twin separately emits live webhook events on writes (stripe-events.ts); the Events API here serves explicitly-recorded event objects with the faithful vendor shape (type, api_version, created, data.object, livemode, pending_webhooks). pending_webhooks defaults to 0 because the twin delivers webhooks synchronously. data.object defaults to an empty object when the caller does not supply a snapshot. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_checkout.hosted-page-pixels",
+   "kind": "non-goal-render-omitted",
+   "reason": "Checkout Sessions (POST/GET /v1/checkout/sessions, GET :id/line_items, POST :id/expire) and Customer Portal sessions (POST /v1/billing_portal/sessions, + billing_portal/configurations) are modeled as API OBJECTS with vendor-faithful shapes, ids (cs_/bps_/bpc_), status/payment_status enums, list envelope, and 400/404 errors. Rendering the Stripe-HOSTED Checkout / Customer Portal PAGE PIXELS is declared out of scope: the hosted HTML is Stripe's, not an API object. The twin models the Session object + redirect `url` (https://checkout.twin.local/... and https://billing.twin.local/...), which is the surface the unmodified `stripe` SDK and apps depend on. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_checkout.completion-modeled",
+   "kind": "behavior-modeled-statefully",
+   "reason": "Real Stripe completes a Checkout Session when the customer pays on the hosted page (there is no public REST verb to complete a session). The twin models that terminal transition via POST /v1/checkout/sessions/:id with status=complete (only valid from `open`), which faithfully creates+links a real twin object: a succeeded payment_intent (mode=payment, amount = amount_total) with payment_status\u2192paid, an active subscription (mode=subscription, when a customer is present) with payment_status\u2192paid, or a succeeded setup_intent (mode=setup). POST :id/expire transitions open\u2192expired (terminal). amount_subtotal/amount_total are computed by summing resolved line_items (an existing Price's unit_amount, or inline price_data.unit_amount, \u00d7 quantity). Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_tax.calculation-list-endpoint",
+   "kind": "endpoint-added-for-mirror",
+   "reason": "Real Stripe has NO list endpoint for tax calculations (POST creates a calculation, GET :id retrieves it, GET :id/line_items lists its items). The twin adds GET /v1/tax/calculations as a faithful-shaped list envelope (object:'list', data[]) purely so the dashboard mirror's Tax > Calculations section can render the calculations stored in twin state. Create/retrieve/line_items match Stripe exactly; the list is a twin convenience. The twin also models a DEFAULT 10% exclusive tax rate for calculations (real Stripe derives the rate from the customer's jurisdiction + registrations) so the returned amount_total/tax_amount_exclusive are deterministic and assertable. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_tax_id.flat-list-endpoint",
+   "kind": "list-endpoint-added",
+   "reason": "Real Stripe scopes tax IDs UNDER a customer (POST/GET /v1/customers/:id/tax_ids). The twin also exposes a flat GET /v1/tax_ids list (filterable by customer) so the dashboard mirror can render a Customer Tax IDs section; the canonical per-customer create/retrieve/list/delete are the faithful surface and all enforce 404 on a missing customer/tax_id. Deleted tax IDs (DELETE returns the deleted-object stub) are excluded from both lists. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_customer_balance_transaction.flat-list-endpoint",
+   "kind": "list-endpoint-added",
+   "reason": "Real Stripe scopes customer balance transactions UNDER a customer (POST/GET /v1/customers/:id/balance_transactions). The twin also exposes a flat GET /v1/customer_balance_transactions list so the mirror can render a Customer Balance section. ending_balance is the running balance after each txn (a negative amount is a credit), computed from the prior ledger, and the owning customer.balance is kept in sync. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_credit_note.single-amount-type",
+   "kind": "field-simplified",
+   "reason": "CreditNotes are modeled in the amount form (the credited cents) referencing a finalized invoice (POST /v1/credit_notes requires invoice (must exist) plus a positive amount); preview (GET /v1/credit_notes/preview), retrieve, /lines, void (terminal: status void) and list all round-trip. Stripe additionally supports per-invoice-line credits and a mixed type; the twin emits a single custom_line_item and picks pre_payment (unpaid invoice) or post_payment (paid invoice) for the vendor type. All 22 vendor-required credit_note fields are emitted. The vendor type field collides with the kernel discriminator and is stashed under the reserved _stripe_type key (restored by view()), like payout/account. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  }
+ ]
+}