@agent-cards/checkout 0.19.0 → 0.22.0

package/cdp.d.ts

@@ -0,0 +1 @@
+export * from '@agent-cards/sdk/cdp';

package/cdp.js

@@ -0,0 +1,2 @@
+// @agent-cards/checkout is the older name of @agent-cards/sdk; this entry is that package's, re-exported for one release.
+export * from '@agent-cards/sdk/cdp';

package/index.d.ts

@@ -0,0 +1 @@
+export * from '@agent-cards/sdk';

package/index.js

@@ -0,0 +1,2 @@
+// @agent-cards/checkout is the older name of @agent-cards/sdk; this entry is that package's, re-exported for one release.
+export * from '@agent-cards/sdk';

package/package.json

@@ -1,48 +1,48 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.19.0",
-  "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
+  "version": "0.22.0",
+  "description": "The older name of @agent-cards/sdk, Agentcard's SDK. Every export is re-exported from there for one release; install @agent-cards/sdk directly.",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "index.js",
+  "types": "index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
-    "./cdp": "./dist/cdp.js",
-    "./playwright": "./dist/playwright.js",
-    "./preflight": "./dist/preflight.js",
-    "./preflight/catalog.json": "./dist/preflight-catalog.json",
-    "./preflight/schemas.json": "./dist/preflight-schemas.json"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./cdp": {
+      "types": "./cdp.d.ts",
+      "default": "./cdp.js"
+    },
+    "./playwright": {
+      "types": "./playwright.d.ts",
+      "default": "./playwright.js"
+    },
+    "./preflight": {
+      "types": "./preflight.d.ts",
+      "default": "./preflight.js"
+    }
   },
   "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "examples",
-    "PREFLIGHT.md"
+    "index.js",
+    "index.d.ts",
+    "cdp.js",
+    "cdp.d.ts",
+    "playwright.js",
+    "playwright.d.ts",
+    "preflight.js",
+    "preflight.d.ts",
+    "README.md"
   ],
+  "dependencies": {
+    "@agent-cards/sdk": "0.22.0"
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "_comment_build": "The public SDK keeps zero runtime dependencies. Its build vendors deterministic metadata and substitution artifacts from the internal payment core; TypeScript remains pinned.",
-    "build": "node ../payment-core/scripts/build.mjs && node scripts/generate-payment-core.mjs && npx -y -p typescript@5.9.3 tsc && node scripts/generate-preflight-contract.mjs",
-    "prepublishOnly": "pnpm build",
-    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs pre-claim.test.mjs autopilot.test.mjs stripe-checkout.test.mjs payment-core.test.mjs prepared-processor.test.mjs merchant-hosted.test.mjs merchant-total.test.mjs sandbox-declaration.test.mjs minimum-delay.test.mjs paysafe.test.mjs payu.test.mjs attachment.test.mjs worker-targets.test.mjs mercado-checkout.test.mjs mercado-polling.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs && node --test kernel-native-qualification.test.mjs && node --test ../vault/scripts/recurly-validation/watch-duty-sdk-result.test.mjs",
-    "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs && node checkout-com-browser.test.mjs && node paysafe-preparation-browser.test.mjs && node owned-shop-browser.test.mjs && node spreedly-browser.test.mjs && node worker-browser.test.mjs && node adyen-merchant-hosted-browser.test.mjs && node fiserv-browser.test.mjs",
-    "check:payment-core": "node scripts/generate-payment-core.mjs --check",
-    "test:preflight": "node --test preflight-package.test.mjs preflight-collector.test.mjs kernel-native-qualification.test.mjs",
-    "test:preflight:browser": "node preflight-browser.test.mjs",
-    "pack:preview": "node scripts/pack-preflight-preview.mjs",
-    "test:preflight:schemas": "node --test preflight-schemas.test.mjs",
-    "check:kernel-native": "node examples/preflight/kernel-native/qualification.mjs inventory --check"
+    "test": "node --test alias.test.mjs"
   },
-  "keywords": [
-    "payments",
-    "agents",
-    "browser-automation",
-    "pci",
-    "checkout"
-  ],
   "engines": {
     "node": ">=22"
   },

package/playwright.d.ts

@@ -0,0 +1 @@
+export * from '@agent-cards/sdk/playwright';

package/playwright.js

@@ -0,0 +1,2 @@
+// @agent-cards/checkout is the older name of @agent-cards/sdk; this entry is that package's, re-exported for one release.
+export * from '@agent-cards/sdk/playwright';

package/preflight.d.ts

@@ -0,0 +1 @@
+export * from '@agent-cards/sdk/preflight';

package/preflight.js

@@ -0,0 +1,2 @@
+// @agent-cards/checkout is the older name of @agent-cards/sdk; this entry is that package's, re-exported for one release.
+export * from '@agent-cards/sdk/preflight';

package/CHANGELOG.md

@@ -1,132 +0,0 @@
-# Changelog
-
-## Unreleased
-
-- Approve a Fiserv Commerce Hub checkout before Pay with `prepare({ psp: 'fiserv', environment: 'production' | 'sandbox', merchantProfile })`, where `merchantProfile` names the key Agentcard reviewed for the merchant (`agentcard_sandbox` in the sandbox) and the checkout's `merchant` is that key's merchant (`Agentcard sandbox`; any other name is refused with reason `merchant_profile_mismatch`). The sync asks the API for `capabilities=fiserv_card_capture`, and the API serves Fiserv's recognizer only for a company Agentcard turned Fiserv on for, so only that company's SDK arms Fiserv's card capture. The SDK pauses the card frame's capture, and it continues from your browser with the envelope the cardholder's device sealed around the approved card, written at `source.encryptionData` by the new `substituteFiservEnvelope`. A card capture with no preparation is refused as `preparation_required` before anyone is asked. Fastlane, ACH, gift and EBT captures continue untouched; every other body on the endpoint counts as a card capture, one the SDK cannot prove card-free included. `authorize()` requires a preparation for any Fiserv request, whatever the served registry says. Autopilot never pays Fiserv. Fiserv stays off until Agentcard turns it on for your company: `prepare()` then fails with reason `processor_unavailable`. A Fiserv preparation the API refuses before it exists names the refusal as the error's reason (every other processor keeps `preparation_unconfirmed`), and an envelope read after its window raises `PaymentOutcomeUnknownError` with reason `cse_substitutions_expired`. Matching API and Vault releases are required.
-
-- Run an Adyen merchant-hosted checkout against your own Adyen TEST account from a test-mode client. `sandboxMerchants` on `VaultClient` declares your own HTTPS endpoint as taking the card request of a profile this build reviewed, under your own `test_` client key; both adapters pause that endpoint whatever the profile's status, `prepare({ psp: 'adyen', environment: 'sandbox', merchantProfile })` and the create carry the declaration and name its host as the merchant, and the continuation keeps every body rule of the profile. A declared profile id takes the place of the reviewed profile on that client. The endpoint must be HTTPS on a public domain name outside every processor's host, Adyen's and Agentcard's domains and every reviewed merchant's domain, or the constructor throws a `TypeError`. The API accepts a declaration only from a test-mode client of an organization Agentcard has turned declarations on for, and reads its key from Adyen's TEST platform, and the Vault encrypts only Adyen's documented test cards under it. `prepare()` throws `sandbox_declaration_refused` and `sandbox_declaration_invalid` as `CheckoutPreparationError` reasons. The matching API and Vault releases are required.
-
-- Pause Adyen merchants that take the card on their own server, through the merchant profiles Agentcard reviewed (Dunelm and Cinemark). Every profile this build reviewed is armed from the start in `observe`, so a sync that has not run or failed never lets the agent's dummy card through; `syncRegistry()` asks for each profile's status on your client, and a profile turns enabled only when the API serves it enabled with the same rules this build reviewed. Both adapters pause the profile's endpoint and its siblings from attach. Both profiles ship in `observe`: a card request there is aborted before it reaches the merchant and reported as `merchant_profile_observed` (the SHA-256 of the body's key paths, never a value) and `unsupported_checkout`, and no authorization is created. A body neither adapter can read counts as a card request there. Once Agentcard enables a profile for your client and your SDK build, `prepare({ psp: 'adyen', environment, merchantProfile })` pays its card request: the create names only the profile id, the API keeps only the SHA-256 of the paused body it checks, the request continues from your browser with the Vault's ciphertext only when the live body hashes to that one (a refused continuation retires the approval), and a `5xx` final answer, a network failure, the page closing or the page's retry after hand-off reports `payment_outcome_unknown`. A card request the profile cannot finish is aborted with the reason, and one without a preparation is aborted as `preparation_required` before any pause, prompt or authorization (the controller reads `failed` with that reason). Events name these endpoints by their templated URL. The matching API release serves the profiles; an older API serves none and nothing changes. `ReplayResponse` gains `MerchantHostedReplay` (`mode: 'cse'`, `kind: 'merchant_hosted'`), so code that reads `substitutions.at` on every `cse` replay now branches on `kind`.
-
-- Refuse Adyen test-platform payments with a typed error, for Adyen Sessions checkouts too. `AdyenTestPlatformRefusedError` (an `ApprovalDeclinedError`) carries `adyen_test_environment_refused` at create or before the card is sent, or `adyen_test_platform_requires_documented_test_card`, where the SDK used to throw a generic error. The controller state changes with it: refused at create, it reads `failed` with the code as its reason (it read `checkout_failed`), and the `failed` event reads `AdyenTestPlatformRefusedError: adyen_test_environment_refused` (it read `CheckoutApiError: adyen_test_environment_refused`); declined before the card is sent, it reads `declined` with the code as its reason (it read `approval_declined`), and the event names the code. A refused preparation throws `CheckoutPreparationError` with the API's code as its reason instead of `preparation_unconfirmed`.
-
-- Pay a Stripe Checkout Elements page with a vaulted card. A page built with `stripe.initCheckout` (Checkout Elements) sends the card inline in the Checkout Session confirm, `/v1/payment_pages/{cs_...}/confirm`, which the SDK never recognized, so the placeholder card reached Stripe and the purchase failed. The confirm now pauses for the cardholder's approval like a PaymentIntent confirm, and the phone sends the real card. The API refuses it unless the amount you pass equals the total the Session will charge (`expected_amount`). Hosted and embedded Checkout confirm the same endpoint with the payment method they created first; that confirm carries no card and continues untouched, as before, even after the approval. `syncRegistry()` asks for `features=checkout_sessions`: the API serves the Checkout Session endpoint only to an SDK that lets such a request through ahead of its holds.
-
-- Let a page pay with the Stripe card token the cardholder just approved. A page that tokenizes first (`stripe.createPaymentMethod`, `createToken`, `createSource`, `createConfirmationToken`) and then confirms the payment in the browser with what came back (`confirmCardPayment` with `payment_method: 'pm_...'`, `confirmPayment` with the confirmation token) used to fail: the SDK held that card-free confirmation, because the token alone could pay any amount. The SDK now asks the API (`VaultClient.checkStripeContinuation`), which reads the payment from Stripe and allows it only for the approved amount and currency, on the same Stripe account, paid with exactly the approved token. Allowed, the page's own request continues untouched, the SDK emits `stripe_payment_continued`, and the controller reads `awaiting_merchant` with reason `stripe_payment_continued`. One confirmation continues per approval; later ones stay held, and a refused one is `blocked` with the API's code (at most three checks per approval). The matching API release is required; an older API refuses, which leaves the hold as it was.
-
-- Pause Stripe confirmation tokens and card sources. A page that calls `stripe.createConfirmationToken` (collect the card, confirm on your own server) or the older `stripe.createSource` sends the card to `/v1/confirmation_tokens` or `/v1/sources`; the SDK never recognized either, so the placeholder card reached Stripe and the purchase failed. Both now pause for the cardholder's approval, and the page receives a real confirmation token or card source. A confirmation token for a saved method, or a bank source, carries no card and continues untouched. The matching API serves these endpoints only to an SDK that asks for `features=card_fields`, which this release does. They are not eligible for auto-approval yet.
-
-- Refuse a Stripe confirmation that carries no card at once. A page that pays with a method it created itself confirms with `payment_method=pm_...`; the SDK used to pause that request and ask the cardholder to approve something their card could not complete. The SDK now reads the body after its holds: a Stripe request without `card[number]` or `payment_method_data[card][number]` is refused at once with a `blocked` event (`request_without_card`) and never reaches the API. A confirmation that follows an approved card token keeps its existing hold. `VaultClient.withoutCard(url, body)` exposes the judgement, and `syncRegistry()` asks for `features=card_fields` (an older API ignores it). The matching API refuses a Stripe request with no card as `400 card_fields_missing`.
-
-- Approve a Paysafe Checkout 1.8.0 fresh-card checkout before Pay with `prepare({ psp: 'paysafe', environment: 'production' | 'sandbox' })`. Phone approval finishes before the hosted checkout starts its card request. One matching request consumes the approval; saved cards and other Paysafe APIs do not use preparation. Matching API, Vault and database releases are required. A token does not confirm merchant payment.
-
-- Keep the cardholder's approval when the merchant page gives up on its own card request. A page whose script times out its tokenization while the person is still deciding (Braintree after 60 seconds, Square after about 10) no longer cancels the approval: the SDK reports `merchant_request_lost`, answers the page's next request for the same purchase from the same authorization, and reads `ready_to_submit` with reason `awaiting_merchant_retry` when the approval lands before the page asks again, so one more Pay click completes the purchase with no second prompt. The wait for that request is bounded by `merchantRetryWaitMs` (two minutes by default, never past the approval window); an approval the page never asks for again is retired through the API as `merchant_never_retried` and the controller reads `declined` with that reason. Applies to `token` and `cse` checkouts; hosted forms, prepared checkouts and native Stripe Checkout keep cancelling. `VaultClient.cancelAuthorization` takes the reason and `checkoutModeOf` reads a request's mode. The matching API and Vault releases are required for the new reason; an older API answers its retirement as unknown, which the SDK holds.
-
-- Approve a Checkout.com guest card checkout before Pay with `prepare({ psp: 'checkout_com', environment: 'production' | 'sandbox' })`. Phone approval finishes before Flow starts its 12-second tokenization deadline. One fresh card request on the matching API or CAG host consumes the approval; saved-card, wallet and reusable-token requests are refused. Matching API, Vault and database releases are required. A token does not establish merchant payment completion.
-
-- Approve an Adyen Sessions checkout before Pay with `prepare({ psp: 'adyen', environment: 'production' | 'sandbox' })`. The cardholder approves and picks the card first; when the merchant's Sessions `/payments` request pauses, the device encrypts the approved card under the merchant's Adyen key and the request continues from your browser, so Adyen Web's own 60-second request timeout covers only the pause, the bind and the encryption. `sandbox` is Adyen's test host with a `test_` client key; `production` is the live host families with a `live_` key. A stored-card, single-blob or store-the-card request never uses the approval. The matching API, Vault and database migration are required.
-
-- Approve Spreedly's native hosted-card checkout with `prepare({ psp: 'spreedly', environment: 'shared' })`. The Vault tokenizes the selected card over the encrypted relay and returns the native response. Matching API, Vault, relay and database releases are required; tokenization alone does not confirm payment. Saved-card updates and other Spreedly flows remain unsupported.
-
-- Identify hosted, regional, and versioned processor variants seen on live checkouts: Adyen secured fields on the regional live hosts and any release, the Square card element frame, dLocal Smart Fields releases, Mercado Pago secure fields and the guest Checkout Pro card form, and the Rapyd hosted checkout page. The Tranzila terminal-root page, the Authorize.Net hosted payment form, and Worldpay hosted payment pages identify their processor and return `unknown` with `processor_variant_unverified`. The catalog is `2026-09-15.1`; issue native profiles against it.
-
-- Report a sole script-only candidate as `psp` only when the observation is complete. On a partial scan the script stays in `candidates` as `undetermined`, so a co-loaded SDK is never presented as the selected processor.
-
-- Detect visible card controls in nested frames from field metadata only, never values. When those controls sit on a site no evidenced processor owns, the collector reports `card_entry_unrecognized`, the observation is incomplete, and the result stays `unknown`. Callers supplying their own observations can report the same reason.
-
-- Match discovery rules on the origin and path only. A long query string on an unrelated wallet or widget frame no longer invalidates the observation. `invalid_url` covers unparsable locations, an origin and path over `4096` characters, or a raw location over `65536` characters.
-
-- Compare committed frame URLs with committed frame URLs. A script-created frame that inherits the merchant URL through `document.open()` no longer reports `navigation_changed`; real navigations, added frames, and removed frames still do.
-
-- Read frames one nesting level at a time with up to eight frames in flight, and release frame handles while the document read proceeds. Frame-heavy checkouts over a remote CDP connection fit the default 1,500 ms budget far more often. `collection.timeoutMs` remains available for slower connections.
-
-- Complete a merchant-confirmed payment when the merchant supplies no order or receipt ID. Return `{ status: 'completed', confirmation: { kind: 'merchant_payment', authorizationId } }` from the merchant resolver using the current checkout authorization. The resolver must verify the original payment request, amount, currency, selected card and merchant success; HTTP 200 or a success page alone is insufficient. The completed state carries `confirmation` without inventing `orderId`, clears stale reasons and continues to block another payment. Existing completion results with a genuine `orderId` keep working.
-
-- Approve a Recurly checkout before its native card request starts. Call `prepare` with `psp: 'recurly'` and `environment: 'shared'`, then submit the merchant's form once. The same selected card and approved purchase bind a new-card POST on the US or EU endpoint. The matching API, database migration and Vault release are required. Token issuance and merchant payment completion remain separate results.
-
-- Keep the selected card's issuer in guest Mercado Pago Checkout Pro in Mexico. The Vault resolves the card's eight-digit prefix against the merchant's captured checkout configuration over browser TLS. The SDK returns the original card-token response and corrects one native card association. Missing configuration, ambiguous issuers, changed checkout context, and a different card brand or type stop continuation. The matching API, Vault and encrypted relay release is required. Other Mercado Pago checkout families and merchant payment completion need separate validation.
-
-- Prepare controlled hosted Stripe Checkout in TEST mode with an explicit `stripeCheckout` attachment option and Autopilot grant. Dummy tokenization stays local; the browser's native final confirmation uses the generated shared core and enclave execution path. The matching backend and executor flags default off. This does not enable production Autopilot or establish a completed merchant order.
-
-## 0.9.0
-
-- Inspect checkout assets before entering card details with `collectCheckoutSignals` and `inspectCheckout`, or assess sanitized observations with `assessCheckoutSupport`. Results identify the PSP, retain evidence and report `supported`, `unsupported` or `unknown` for the selected integration.
-- Build a Kernel native integration against exported JSON schemas, a versioned capability profile and runnable local examples before deployment. Missing native capabilities remain `unknown`; direct SDK coverage does not establish native coverage.
-- Detect all 23 registered PSPs and report processor implementation support separately from checkout-flow identification. `support_scope` states what `status` covers; `checkout_flow_status` preserves unknown or ambiguous flow evidence. The bundled profile covers one-time processor requests, while flow-specific support requires matching evidence.
-- Keep inspection advisory and read-only. Known payment-format exclusions and integration-specific limitations remain visible. Existing authorization and payment request checks still apply; the helper does not establish merchant purchase success.
-
-## 0.8.0
-
-- Clear an earlier failure or authentication reason when the merchant confirms a completed order. The final checkout state retains the authorization, order and payment mode without carrying a stale error.
-
-- Pass execution routing metadata through authorization and browser attachment with `executionMode`, `grantId` and `merchantOrigin`. The exported `ExecutionMetadata` type describes the result; the matching API and Vault determine whether the user approves the purchase or an existing grant applies. Autopilot execution remains limited to the configured controlled Stripe test flow, with production Autopilot disabled.
-- Share generated processor metadata with the payment core while keeping the published SDK free of runtime package dependencies.
-
-## 0.7.0
-
-- A company can put rules on the Vault purchases it chooses (a merchant list, a currency, a spend cap, a time window) by attaching a named preset to a stored card. A purchase the rules refuse now surfaces as `PresetRefusedError`, a typed decline: at stage `create` no authorization exists and nobody was asked; at stage `pre_replay` the authorization is `declined` with the rule's reason. It carries `code`, `presetName`, `rule`, `preset`, `attachment` (the card with its last four digits) and the rule's own statement; when several presets refuse the same purchase, `refusals` names every one and the other fields are the first. The adapters quiet the page's retry as for any decline, and a create-time refusal is never treated as a permanent misconfiguration.
-- Requires the matching API and Vault release.
-
-## 0.6.0
-
-- Recognize Paysafe Checkout 1.8's exact hosted tokenization endpoints and preserve its native credential and correlation headers. The matching API registry and Vault deployment are required.
-- Recognize Checkout.com card tokenization at `card-acquisition-gateway.checkout.com/tokens` and its sandbox counterpart alongside the existing API hosts. The matching backend registry and Vault deployment are required; this entry does not establish native merchant payment completion.
-- Prepare Worldpay, Bambora and Mercado Pago checkout before the merchant's first Pay action. Use `psp: 'worldpay'` with `environment: 'production' | 'sandbox'`, or `psp: 'bambora' | 'mercado_pago'` with `environment: 'shared'`. Shared endpoints do not establish processor test mode. The merchant's credentials and checkout configuration determine that mode.
-- Keep the existing selected-card, merchant, document, amount, currency and one-use consent checks. The native request begins only after approval, and approval readiness lasts at most 30 seconds. The SDK does not extend processor deadlines or automatically retry after payment uncertainty. Matching API, Vault and preparation migration are required.
-- Bound Playwright and CDP setup with `attachmentTimeoutMs`, defaulting to 30 seconds. A stalled setup throws a sanitized `CheckoutAttachmentError`; late acknowledgements cannot start approval or retry setup, and concurrent setup failures report once. Close the failed checkout page and start a fresh context before trying again.
-- Preserve the original setup failure across attached frames: a transport failure reports `unavailable`, a deadline reports `timeout`, and an observed page closure reports `closed`.
-- Reject processor URLs with credentials or nondefault ports consistently across SDK and API discovery. Registry synchronization updates endpoint recognition; upgrading the SDK is required for the new preparation and setup behavior.
-
-The matching Vault/API release adds Mollie card-token and supported Airwallex intent-confirmation replay through browser-owned TLS, preserves Worldpay's native session media type and Bambora's `cvd` field, and reports Nuvei's unambiguous validation error as processor refusal. Local regression and Chromium fixture results do not establish native processor acceptance or a completed merchant purchase.
-
-## 0.5.0
-
-- Prepare Braintree card checkout with `controller.prepare({ psp: 'braintree', environment: 'production' | 'sandbox' })` before the merchant's first Pay action. The cardholder approves and unlocks first; one fresh native request then uses that approval without another notification. The matching API and Vault release is required.
-- Let native Braintree client-configuration queries pass without consuming consent. Prepared checkout accepts one card-tokenization mutation for the approved processor and environment. Other operations, ambiguous GraphQL payloads and legacy REST fallback cannot use the preparation.
-- Keep the native request timeout and one-use, card, merchant, amount, currency and document bindings. Approval readiness lasts at most 30 seconds. Tokenization amounts remain display-only; a token does not establish a paid order.
-- Add a real Chromium fixture with approval delayed 61 seconds before a fresh 60-second XHR, plus cancellation, request classification and binding regressions. The isolated fixture contacts no payment processor and is not live purchase proof.
-
-## 0.4.1
-
-- Stop describing every processor request rejection as a card decline or proof that nothing was charged. `ProcessorRefusedError` keeps its existing class and code, with neutral wording and an optional `processorError` containing bounded Razorpay reason, source, step and payment/order identifiers from the matching API/Vault release. Older failure records cannot recover details that were not retained.
-- Hold further card requests within the attachment after a processor refusal, including when the merchant retries after the approval cooldown. Reconcile the merchant payment; only an explicit `retryAfterMerchantFailure({ status: 'failed' })` releases this hold and permits an immediate new attempt. This also applies to clear card declines. Ordinary user declines keep their approval cooldown. Do not automatically replace the attachment to bypass reconciliation.
-- Add deterministic refusal, diagnostic sanitization and retry-guard regressions. These tests do not establish a successful Razorpay purchase or processor capture.
-
-## 0.4.0
-
-- Add `controller.prepare({ psp: 'square', environment: 'production' | 'sandbox' })` to both browser adapters. The caller awaits cardholder consent and unlock before starting its first native Pay action. This requires the matching preparation API and Vault deployment.
-- Bind one fresh request to the selected card, declared merchant, merchant origin, amount, currency and Square environment. Readiness expires after at most 30 seconds; preparation failure, expiry, cancellation, navigation and reuse fail closed. Binding creates no second approval link or SMS. Square token amounts remain display-only.
-- Preserve native request deadlines and merchant-abort protections. The SDK never clicks Pay, changes Square timers or retries an abandoned prepared checkout. The post-submit relay and token handoff must still fit Square's native deadline; a disconnected or slow cardholder device can miss it.
-- Recover a lost bind acknowledgement through preparation metadata for cancellation and reconciliation only. Started replay or unconfirmed cleanup remains unknown. A parent CDP page disconnect now also stops a pending request in a child iframe.
-- Add preparation lifecycle tests and an isolated Chromium fixture that waits more than ten seconds before any card request, then permits one fresh request. These fixtures use no real processor and do not establish native Square or production checkout acceptance.
-
-## 0.3.1
-
-- Detect a merchant request abort or owning frame/page closure while approval is pending. The attachment holds an unknown outcome and blocks automatic retries; an expired request is never reported as an authorized handoff.
-- Retire pending authorizations through the org-scoped cancellation endpoint when the merchant request disappears. Cancellation can win only before the processor-send boundary; started or completed replay remains unknown to this operation. A late creation response is drained so its authorization ID can be cancelled without exposing another approval link.
-- Square token mode uses the vault's verified browser TLS relay. The relay keeps TLS termination and card plaintext on the cardholder device and Square. SDK 0.2.1 can complete a prompt approval but does not contain the native-timeout lifecycle fixes; upgrade to 0.3.1 for Square checkout.
-- Square's native tokenization request still expires after about 10 seconds, including approval and token handoff. Delayed approval cannot complete that checkout; a later SCA challenge has its own lifetime after handoff. This release does not extend the deadline or retry a payment after timeout. Reconcile the merchant outcome and explicitly begin another checkout when required.
-
-## 0.3.0
-
-### Browser checkout lifecycle
-
-- `attachToPlaywright` and `attachToCdp` now return a `CheckoutController` with state, cancellation, merchant reconciliation, user-action hooks and explicit retry after a merchant-confirmed failure. Existing callers may continue to ignore the return value.
-- `requireMerchantResult: true` holds further card requests after handoff until the application's merchant integration confirms the outcome. Approval or tokenization alone does not establish a successful order.
-- Stripe `/v1/payment_methods` and `/v1/tokens` handoffs hold further recognized card requests, even without `requireMerchantResult`. Tokenization does not bind a specific PaymentIntent, amount or currency, so automatic token-to-intent continuation is unsupported. Direct card-bearing PaymentIntent confirms retain their existing backend amount verification. Unknown merchant-server endpoints require explicit `paymentEndpoints` guards; server-side charges remain outside this browser guard.
-- Exact `paymentEndpoints` guards abort unsupported payment endpoints identified by the integrator. Unknown endpoints outside those guards remain untouched.
-- An existing-browser example covers the direct SDK connection used with Browserbase, Kernel or a compatible custom Chromium/CDP session. Cloud-provider sessions and real merchant/3DS flows still require separate validation; Kernel's native Vault integration is a separate path.
-
-### Migration from 0.2.x
-
-- Handle `PaymentOutcomeUnknownError` separately from decline or safe expiry. Lost create/poll responses, malformed post-create responses and local deadlines can leave an approval or payment outstanding. Reconcile the merchant order before starting another attempt; do not retry because a local timer elapsed.
-- `timeoutMs` now bounds authentication, authorization creation and polling together. `cancel()` stops this attachment locally; it does not revoke an approval link or cancel a processor payment. A cancelled attachment cannot restart.
-- An attachment that issued an unbound Stripe token cannot reset with `retryAfterMerchantFailure`, including when browser delivery is uncertain. Reconcile the merchant outcome and use a separately validated flow; do not reuse the token in a new attachment.
-- Hosted-form submissions remain blocked until an explicit merchant-confirmed failure permits retry. The short duplicate-request cooldown is not proof that retry is safe.
-- Initial raw-CDP interception setup errors now reject attachment. A child target that cannot be armed stays paused for operator recovery. Supply a browser-level, session-aware CDP connection for raw CDP; a page-scoped Playwright `CDPSession` is insufficient.
-- Playwright attachment rejects contexts with active service workers. Create checkout contexts with `serviceWorkers: 'block'`; checking an existing context cannot prevent later worker registration.
-- Observer callback failures no longer interrupt payment handoff. Event failure summaries omit processor/API response bodies and request query strings.
-
-### Verification
-
-Deterministic transport and lifecycle tests cover failure recovery and retry guards. Local Chromium fixtures cover nested cross-origin frames, same-page post-payment work, and blocking immediate Stripe payment-method-to-intent fetch chains for both adapters, including an unrelated first intent and changed amount/currency. All payment endpoints in those fixtures are local stubs; they do not establish production provider or processor coverage.

package/PREFLIGHT.md

@@ -1,312 +0,0 @@
-# Check checkout support
-
-Inspect a loaded checkout before entering card details or submitting payment. The preflight helper identifies payment processors from page assets and reports what the selected integration can support. Each result distinguishes processor support from an identified checkout flow, so your agent can show the available integration without promising a successful purchase.
-
-The helper works locally without Agentcard credentials or an approval. The classifier makes no network requests. The browser collector reads checkout assets without filling fields, clicking Pay, or installing payment interception.
-
-## Install checkout inspection
-
-Use Node.js 22 or later. Install `@agent-cards/checkout@0.9.0` in a separate project:
-
-```bash
-mkdir checkout-preflight-example
-cd checkout-preflight-example
-npm init -y
-npm install --save-exact @agent-cards/checkout@0.9.0
-node node_modules/@agent-cards/checkout/examples/preflight/classify-kernel.mjs
-```
-
-The example identifies a Stripe script and returns `unknown` for Kernel native. The included native profile has no capability entries. No deployment, Agentcard account, card, or merchant account is needed.
-
-Compare the same observation against the direct SDK:
-
-```bash
-node node_modules/@agent-cards/checkout/examples/preflight/classify-direct.mjs
-```
-
-The direct example returns `supported` with `support_scope: "processor_integration"` and `checkout_flow_status: "unknown"`. The result means the SDK implements Stripe card requests; the observed script has not established which Stripe checkout flow the merchant uses. The [recorded direct result](./examples/preflight/stripe-script.direct.result.json) comes from running the example against the built package.
-
-The package includes `PREFLIGHT.md`, runnable examples, TypeScript declarations, and JSON contract files:
-
-| Package export | Contents |
-| --- | --- |
-| `@agent-cards/checkout/preflight` | Browser-independent normalization and assessment functions. |
-| `@agent-cards/checkout/playwright` | Read-only collection and inspection functions, plus the existing Playwright exports. |
-| `@agent-cards/checkout/preflight/catalog.json` | Versioned detection rules, processor capabilities, flow capabilities, and exclusions. |
-| `@agent-cards/checkout/preflight/schemas.json` | JSON schemas for observations, snapshots, capability profiles, options, and results. |
-
-## Build a local preview
-
-For an unpublished change, build an optional preview archive from its source checkout:
-
-```bash
-cd apps/agent-cards/packages/checkout
-npm run pack:preview -- --out /tmp/checkout-preflight-preview
-```
-
-The packaging command rebuilds the SDK and refuses uncommitted changes by default. Add `--allow-dirty` only when testing a local working copy; the manifest marks that archive accordingly. The command packages files locally and does not publish to npm or deploy a service.
-
-Install the resulting archive in your test project. Replace the path below with the archive's actual location:
-
-```bash
-npm install --save-exact /absolute/path/to/agent-cards-checkout-preview.tgz
-```
-
-Retain the archive and its `preview-manifest.json`. The manifest records its source commit, archive checksum, and whether it includes uncommitted changes. A local preview is not a production release. Share the archive and manifest directly when the recipient cannot access the repository's build artifacts.
-
-## Use your own observations
-
-Kernel can keep its existing browser inspection and feed asset observations to the classifier. The pure JSON example runs with its included fixture, or accepts observation and profile file paths followed by the actual adapter version:
-
-```bash
-node node_modules/@agent-cards/checkout/examples/preflight/classify-kernel.mjs observations.json kernel-profile.json kernel-adapter-1
-```
-
-Use the functions directly from JavaScript:
-
-```js
-import {
-  normalizeCheckoutSignals,
-  assessCheckoutSupport,
-} from '@agent-cards/checkout/preflight';
-
-const snapshot = normalizeCheckoutSignals(observations);
-const result = assessCheckoutSupport(snapshot, {
-  scenario: 'one_time',
-  integration: { id: 'kernel_native', version: adapterVersion },
-  profile: kernelProfile,
-});
-```
-
-Pass the adapter version from the running integration, separately from the profile. The version comparison cannot detect an outdated profile if the caller copies the profile's version into the runtime options without checking the actual adapter.
-
-The included [raw observations](./examples/preflight/stripe-script.observations.json) are synthetic input. The included [recorded result](./examples/preflight/stripe-script.result.json) comes from running the example against the built package. The query string in the input is absent from the normalized snapshot and result.
-
-The [Mollie fixture](./examples/preflight/mollie-hosted.observations.json) identifies an active hosted Components page. Its [recorded native result](./examples/preflight/mollie-hosted.result.json) still returns `unknown` with `integration_flow_undeclared` because the native profile has no entry for that flow.
-
-| Observation field | Meaning |
-| --- | --- |
-| `signals[].kind` | `document`, `frame`, `script`, `iframe`, or `form`. |
-| `signals[].url` | The observed document or asset location; normalize locally before sharing or logging. |
-| `signals[].frame_id` | A stable integer for the containing frame during this scan. Use `0` for the top document. |
-| `signals[].parent_frame_id` | The parent frame's identifier, or `null` for the top document. |
-| `signals[].visible` | `true`, `false`, or `null` when visibility is undetermined. Do not mark scripts active merely because they loaded. |
-| `observation.complete` | Whether the scan finished without missing observations. |
-| `observation.truncated` | Whether a collection limit discarded observations. |
-| `observation.reasons` | Documented collection reason codes for an incomplete observation. Report `card_entry_unrecognized` when your own collector sees visible card controls in a nested frame on a site no evidenced processor owns. |
-
-The normalized snapshot contains `schema_version: 1`, `catalog_version`, rule identifiers, frame relationships, and collection status. Raw URLs do not survive normalization. The assessment returns PSP candidates with reviewed evidence, support status and its scope, any identified flow, reason codes, and limitations. `scenario_defaulted` records whether the caller omitted the scenario and accepted `one_time`.
-
-## Inspect an existing page
-
-Call the collector with a Playwright page that your agent already owns:
-
-```js
-import { inspectCheckout } from '@agent-cards/checkout/playwright';
-
-const result = await inspectCheckout(page, {
-  scenario: 'one_time',
-  integration: { id: 'kernel_native', version: adapterVersion },
-  profile: kernelProfile,
-});
-```
-
-For a checkout that will use the direct SDK, omit the native integration and profile:
-
-```js
-const result = await inspectCheckout(page, { scenario: 'one_time' });
-```
-
-The [existing-browser example](./examples/preflight/inspect-browser.mjs) connects to a CDP browser and inspects its selected tab. Supply the browser connection URL through `CHECKOUT_CDP_URL` using your normal secret configuration; do not log the URL.
-
-```bash
-npm install playwright-core
-node node_modules/@agent-cards/checkout/examples/preflight/inspect-browser.mjs
-```
-
-| Environment variable | Meaning |
-| --- | --- |
-| `CHECKOUT_CDP_URL` | Required connection URL for an existing Chromium browser. |
-| `CHECKOUT_PAGE_INDEX` | Tab index in the first browser context; defaults to `0`. |
-| `CHECKOUT_INTEGRATION` | `kernel_native` by default, or `direct_sdk` when the SDK handles payment. |
-| `CHECKOUT_ADAPTER_VERSION` | The running Kernel native adapter version. Missing versions preserve `unknown`. |
-| `CHECKOUT_PROFILE` | Optional path to the trusted native capability profile JSON. An absent profile preserves `unknown`. |
-
-The example disconnects its inspection connection afterward. The existing agent keeps ownership of its browser session. No Agentcard payment interceptor is installed.
-
-## Choose the payment integration
-
-| Integration | Choose when | Capability source |
-| --- | --- | --- |
-| `direct_sdk` | Your checkout uses `@agent-cards/checkout`, including when the SDK connects to a Kernel browser over CDP. | Capabilities bundled with the installed SDK. |
-| `kernel_native` | Your checkout uses Kernel's native Agentcard integration. | A versioned profile supplied by your application. |
-
-Kernel native support remains `unknown` until a compatible profile explicitly declares the detected processor or identified flow. The direct SDK's coverage does not establish Kernel native coverage. The detector can identify the PSP before that profile exists, so Kernel can build its result display and observation collector immediately.
-
-The direct SDK result uses `integration.version: "bundled"` to name the capabilities shipped with this helper. `bundled` is not a version claim about a different SDK installation. Use the helper from the same package that handles payment, or provide an explicit profile for the implementation you run.
-
-## Check processor coverage
-
-The catalog includes reviewed discovery rules and direct SDK implementation capabilities for every processor in the canonical checkout registry:
-
-| Processor | Payment mode |
-| --- | --- |
-| Shopify | `token` |
-| Stripe | `token` |
-| Braintree | `token` |
-| Checkout.com | `token` |
-| Adyen | `cse` |
-| Tranzila | `hosted_form` |
-| Square | `token` |
-| Authorize.Net | `token` |
-| Worldpay | `token` |
-| Nuvei | `token` |
-| Airwallex | `token` |
-| Rapyd | `token` |
-| dLocal | `token` |
-| EBANX | `token` |
-| Mercado Pago | `token` |
-| PayU | `token` |
-| Razorpay | `token` |
-| Mollie | `token` |
-| Paysafe | `token` |
-| Recurly | `token` |
-| Spreedly | `token` |
-| Moneris | `token` |
-| Bambora | `token` |
-| Global Payments | `token` |
-
-Fiserv Commerce Hub is not in the table. Agentcard keeps Fiserv off until it turns it on for a company, so the bundled profile declares no Fiserv support. Fiserv's assets still identify `fiserv`: `payment-fields.js` and `checkout.js` on `commercehub-checkout.fiservapps.com` and the card frame on `commercehub-secure-data-capture.fiservapps.com`, with their `-cert` hosts. The result stays `unknown`, and a page that loads a Fiserv asset beside another processor's reads as `ambiguous`. A company that Agentcard turned Fiserv on for pays it through `prepare()`, as the [README](./README.md) describes.
-
-The bundled direct SDK profile declares processor support for `one_time` purchases. The catalog carries each processor's request limitations and known exclusions. A detection rule does not cover every product or regional variant sold under the processor's name. For example, Moneris Hosted Tokenization and Moneris Checkout use different payment paths; the implemented adapter covers Hosted Tokenization.
-
-The catalog also carries reviewed hosted, regional, and versioned variants observed on live checkouts: Adyen secured fields on the regional live hosts and any release, the Square card element frame, dLocal Smart Fields releases, Mercado Pago secure fields and the guest Checkout Pro card form, and the Rapyd hosted checkout page. A variant the implemented adapter does not admit, such as the Tranzila terminal-root page, the Authorize.Net hosted payment form, or a Worldpay hosted payment page, identifies its processor and returns `unknown` with `processor_variant_unverified`. A new fingerprint never declares payment support by itself.
-
-Adyen's `supported` covers the Sessions payment request on Adyen's own hosts. Some Adyen merchants post the four encrypted fields to their own server instead, and their pages load the same secured fields, so an inspection identifies Adyen on both and cannot tell the two flows apart. The SDK pays a merchant's own endpoint only through a merchant profile Agentcard reviewed for it; the reviewed profiles (Dunelm and Cinemark) are in `observe`, so the SDK aborts their card requests and nothing is charged. The `actual_payment_request_validation` requirement is where that difference shows: check the paused request's host before treating an Adyen result as payable.
-
-| Observed checkout | Classification |
-| --- | --- |
-| A compatible Stripe script, `one_time`, direct SDK | `supported` at `processor_integration` scope; `checkout_flow_status` remains `unknown`. |
-| Active Mollie hosted Components checkout with its component script, `one_time`, direct SDK | `supported` at `checkout_flow` scope; `checkout_flow_status` is `identified`. |
-| A detected processor with an empty Kernel native profile | `unknown`; the native adapter has not declared processor or flow support. |
-| Competing processors without enough evidence to select one | `unknown`, with `checkout_flow_status: "ambiguous"`. |
-| An incomplete observation | `unknown`; inspect again after the checkout settles. |
-| A single processor script during an incomplete scan | `unknown`; `psp` stays `null` and the script remains in `candidates` as `undetermined` until a complete scan confirms it. |
-| Visible card controls in a nested frame on a site no evidenced processor owns | `unknown` with `card_entry_unrecognized`; a co-loaded SDK script is listed as a candidate, not as the processor. |
-
-Processor support does not establish which payment method the merchant selected. Many SDKs also load wallets or fraud checks before a card form appears. Read `checkout_flow_status` and the returned limitations alongside `status`; never present `supported` alone as a promise that a merchant purchase will succeed.
-
-## Declare native capabilities
-
-Start with the [empty native profile](./examples/preflight/kernel-profile.empty.json). Keep `entries` and `processor_entries` empty until you have verified the adapter's payment behavior. An empty profile exercises the contract while preserving `unknown`. An omitted processor or flow declaration is not an explicit exclusion.
-
-Supply profiles from trusted application configuration. A merchant page must never choose its own capabilities or claim a supported flow. A native profile cannot override a shared Vault exclusion.
-
-| Profile field | What the caller supplies |
-| --- | --- |
-| `schema_version` | The contract schema version expected by the installed classifier. |
-| `profile_version` | A revision that changes when the profile's declarations change. |
-| `catalog_version` | The exact compatible catalog version from the installed package. |
-| `integration.id` | `kernel_native` for Kernel's native Agentcard integration. |
-| `integration.version` | The adapter version whose behavior the profile declares. |
-| `entries` | Explicit flow, operation revision, mode, scenario, status, and optional limitations. |
-| `processor_entries` | Optional declarations with `psp`, `mode`, `scenario`, `status`, and optional `limitations`. Missing or empty declarations preserve `unknown` for processor-only evidence. |
-| `expires_at` | Optional expiration time for a time-bounded profile. |
-
-Declare processor support and flow support separately. A flow entry cannot establish support for a generic script whose flow remains unidentified. A processor entry permits a result at `processor_integration` scope; the entry does not turn an unidentified checkout into an identified flow.
-
-Take PSP identifiers, payment modes, flow identifiers, operation identifiers, and operation revisions from the packaged catalog. Verify each combination against the named adapter version before adding a `supported` entry. Use `unsupported` only for a known exclusion. A profile with a wrong schema, incompatible catalog, mismatched adapter version, or expired timestamp preserves `unknown`.
-
-The JSON contract uses `schema_version: 1`. The catalog bundled with this release uses `catalog_version: "2026-09-15.1"`. Keep the snapshot, classifier, and profile on the same catalog version. Re-normalize observations with the installed package after changing the catalog. Review the adapter declarations before issuing a compatible profile; changing the version string alone does not validate new behavior.
-
-Kernel can integrate the JSON contract immediately and supply its validated native capabilities later. No deployed Agentcard endpoint or payment request is required for that work.
-
-## Review native evidence
-
-Use the [native qualification kit](./examples/preflight/kernel-native/README.md) to review every catalog processor before declaring native support. The kit records pinned Kernel documentation separately from runtime evidence and checks that a release profile names the tested native build.
-
-The current inventory leaves every native runtime status `unknown`. Kernel documents five adapters; the remaining processors have no declaration in those sources. Documentation, client SDK versions, and direct SDK test results cannot establish native support.
-
-## Interpret the result
-
-| Status | Meaning | Next step |
-| --- | --- | --- |
-| `supported` | The selected integration supports the detected processor or identified flow for the scenario named in the result. | Read `support_scope`, `checkout_flow_status`, and the limitations, then continue through normal approval and request checks. |
-| `unsupported` | Shared constraints or the selected profile explicitly exclude the identified processor, flow, or scenario. | Read the reason and choose another payment flow or integration. |
-| `unknown` | The observation or integration capabilities cannot establish support. | Inspect again after the payment method loads or changes. Preserve `unknown` if the evidence remains insufficient. |
-
-| Result field | Meaning |
-| --- | --- |
-| `support_scope: "processor_integration"` | The status describes the processor implementation. The merchant's exact checkout flow can remain unknown. |
-| `support_scope: "checkout_flow"` | The status describes the identified flow and its declared operation. |
-| `support_scope: null` | The evidence or capability profile cannot establish a support classification. |
-| `checkout_flow_status: "identified"` | The observations identify one reviewed checkout flow. Check `status` to learn whether the selected integration supports that flow. |
-| `checkout_flow_status: "unknown"` | The observations do not identify the exact checkout flow. Processor support can still be known. |
-| `checkout_flow_status: "ambiguous"` | Competing evidence prevents a single flow assessment. Inspect after the payment method is selected. |
-
-A loaded PSP script establishes a possible processor, not necessarily the active card flow. The helper returns candidates rather than picking the first script. A sole script candidate becomes `psp` only when the observation is complete. When a visible card-entry frame belongs to no evidenced processor's site, the collector reports `card_entry_unrecognized` and the script stays a candidate. A missing fingerprint does not establish lack of support.
-
-Every assessment is an advisory hint. The existing payment request checks still apply. A supported flow can require authentication or merchant configuration, and only the merchant's payment result establishes whether a purchase succeeded.
-
-## Handle assessment reasons
-
-| Reason code | Meaning and next step |
-| --- | --- |
-| `processor_supported_by_integration` | The selected integration declares this processor and scenario. The result covers the implementation; check the flow status before continuing. |
-| `integration_processor_unsupported` | The selected adapter explicitly excludes this processor and scenario. Choose another integration or payment method. |
-| `integration_processor_undeclared` | The profile makes no processor-level claim for this scenario. Preserve `unknown` until the adapter capability is validated. |
-| `processor_variant_unverified` | The detected SDK variant has no verified match to the implemented processor adapter. Preserve `unknown` and validate that variant before proceeding. |
-| `payment_signal_inactive` | The matching evidence belongs to hidden or inactive payment content. Inspect the visible checkout. |
-| `hosted_form_plain_sale_only` | The hosted form supports a one-time sale, not card storage or a subscription setup. Use a one-time sale or another supported integration. |
-| `renewal_managed_by_merchant` | The merchant charges recurring renewals outside the Vault checkout. Verify the merchant's billing and payment outcome. |
-| `flow_supported_by_integration` | The selected integration declares this flow and scenario. Continue through normal authorization and request checks. |
-| `vault_flow_unsupported` | The shared Vault constraints exclude this flow. Choose another flow. |
-| `integration_flow_unsupported` | The selected adapter explicitly excludes this flow and scenario. Choose another integration or flow. |
-| `integration_flow_undeclared` | The profile makes no claim about this flow and scenario. Preserve `unknown` until the adapter behavior is validated. |
-| `checkout_flow_unidentified` | PSP evidence does not establish the active card flow. Inspect again after the relevant payment controls load. |
-| `flow_corroboration_missing` | A hosted payment location lacks the required matching component evidence in that document. Inspect after the component loads; the result remains `unknown` while that required evidence is missing. |
-| `psp_not_detected` | No reviewed fingerprint matched. Preserve `unknown`; absence of a match is not proof of lack of support. |
-| `ambiguous_checkout` | The observations identify competing candidates or flows. Inspect after the payment method is selected. |
-| `observation_incomplete` | The scan missed observations or reached a limit. Read `observation.reasons`, then inspect again. |
-| `integration_version_missing` | The caller did not identify the running adapter version. Supply that version. |
-| `integration_profile_missing` | The selected integration has no profile. Supply a compatible profile after validating its declarations. |
-| `integration_profile_invalid` | The profile is malformed or contains conflicting entries. Validate the profile against the packaged schema and classifier. |
-| `integration_profile_incompatible` | The profile names an incompatible catalog, flow, operation, or mode. Review its declarations against the installed catalog. |
-| `integration_profile_mismatch` | The profile describes a different integration or adapter version. Use the profile for the running adapter. |
-| `integration_profile_expired` | The profile's expiration has passed. Revalidate and replace the profile. |
-| `catalog_incompatible` | The snapshot uses a different catalog. Normalize the observations again with the installed helper. |
-| `invalid_snapshot` | The snapshot does not match the supported contract. Regenerate it through `normalizeCheckoutSignals`. |
-| `invalid_options` | Assessment options are malformed or include unsupported fields. Validate against the packaged options schema. |
-
-Collection reasons explain why an observation is partial:
-
-| Collection reason | Next step |
-| --- | --- |
-| `collection_timeout` | Inspect after the checkout settles, or increase the time budget within the supported limit. |
-| `frame_limit` | Preserve `unknown` when the page has more frames than the configured limit. |
-| `signal_limit` | Preserve `unknown` when the page exceeds the observation limit. |
-| `snapshot_limit` | Preserve `unknown` when the observations exceed the size budget. |
-| `frame_unavailable` | Inspect again after the frame is available. |
-| `navigation_changed` | A frame's committed URL changed, a frame was added or removed, or an http(s) document's URL changed during the scan. A script-created frame that inherits the merchant URL is not a navigation. Inspect the new checkout state after navigation finishes. |
-| `card_entry_unrecognized` | Visible card controls sit in a nested frame on a site that no evidenced processor owns, or no processor evidence was found at all. Treat listed candidates as unconfirmed and inspect again after the payment method is selected. Identification needs a reviewed fingerprint for that frame. |
-| `invalid_observation` | Validate raw observations against the packaged schema. |
-| `invalid_url` | The location could not be parsed, its origin and path exceed `4096` characters, or the raw location exceeds `65536` characters. Matching reads the origin and path only, so a long query string on an unrelated frame never invalidates an observation. |
-| `collection_incomplete` | Inspect again after the underlying collection problem is resolved. |
-
-## Keep observations current
-
-Inspect the checkout after its payment controls load. Inspect again after navigation, a payment-method switch, or a checkout refresh. The first release collects one snapshot per call and does not monitor the page continuously.
-
-Incomplete frame inspection and collection limits remain visible in the result. Hidden or unused payment assets cannot establish an active supported flow. The collector does not inspect closed shadow roots or controls that have not loaded.
-
-Collect only the documented asset observations when using your own browser tools. Do not include card input values, cookies, script bodies, page HTML, or arbitrary JavaScript globals. Keep full checkout URLs and their query strings out of logs and shared fixtures. The public evidence uses reviewed rule identifiers and sanitized asset locations.
-
-The default collection budget is `1500` milliseconds, with at most `64` frames, `2048` signals, and `262144` serialized snapshot bytes. Set lower bounds through `collection.timeoutMs`, `collection.maxFrames`, `collection.maxSignals`, or `collection.maxSnapshotBytes` on `inspectCheckout`. The maximum time budget is `10000` milliseconds; the remaining limits cannot exceed their defaults. The minimum snapshot budget is `512` bytes.
-
-Frames are read one nesting level at a time with up to eight frames in flight, and each frame handle is released while its document read proceeds. A remote CDP connection therefore pays about three round trips per nesting level plus one per eight frames, rather than four round trips per frame. Over a remote connection, allow `3000` to `5000` milliseconds through `collection.timeoutMs`, inspect after the payment controls have loaded, and read `observation.reasons` before retrying. A longer budget cannot repair a scan that started before the checkout settled.
-
-## Validate without a purchase
-
-The included fixture is synthetic and contains no card information. Fixture classifications validate the detector contract; they are not evidence of a real payment or of a merchant's coverage.
-
-Kernel can compare its own browser observations with the same fixture results before configuring native capabilities. Record a real checkout's preflight result only during a separately authorized checkout, then compare the naturally observed payment request. No card submission is needed to exercise the preflight helper itself.