@agent-cards/checkout 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## Unreleased
+## 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.

package/PREFLIGHT.md

@@ -0,0 +1,294 @@
+# 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. |
+
+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` |
+| Moneris | `token` |
+| Bambora | `token` |
+| Global Payments | `token` |
+
+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.
+
+| 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. |
+
+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-11.2"`. 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.
+
+## 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 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` | Inspect the new checkout state after navigation finishes. |
+| `invalid_observation` | Validate raw observations against the packaged schema. |
+| `invalid_url` | Correct the malformed or oversized asset location before normalization. |
+| `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.
+
+## 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.

package/README.md

@@ -33,6 +33,10 @@ npm i @agent-cards/checkout
 Upgrading from 0.2.x? Read the [migration notes](./CHANGELOG.md), especially
 the unknown-outcome, cancellation and browser-context requirements.
 
+To inspect a checkout before card entry with SDK `0.9.0` or later, read [Check checkout support](./PREFLIGHT.md).
+The read-only helper detects all 23 registered PSPs and reports processor support separately
+from an identified checkout flow. Kernel native coverage requires its own capability profile.
+
 ## Use it
 
 Two lines against a CDP session you already have:
@@ -56,7 +60,7 @@ await attachToCdp(cdp, pageSessionId, {
   merchant: 'vanman.shop',
   amount: 583,                     // your hint, an integer in the currency's smallest unit (or a decimal string: '5.83')
   currency: 'usd',                 // "$5.83" is derived for the approval screen
-  onApprovalUrl: (url) => sendToUser(url),   // iMessage, SMS, push, your call
+  onApprovalUrl: (url) => sendToUser(url),   // SMS, push, email, iMessage: your call
 });
 ```
 
@@ -427,7 +431,7 @@ const preparation = await checkout.prepare({
 await page.getByRole('button', { name: 'Pay', exact: true }).click();
 ```
 
-`prepare()` is available on both Playwright and raw CDP controllers. It requires `amount` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The phone page must stay open. Its selected card, merchant origin, declared merchant, amount, currency, processor and environment bind one fresh request. The amount's authority is `agent`; a card token does not enforce the merchant's eventual charge amount.
+`prepare()` is available on both Playwright and raw CDP controllers. It requires `amount` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The approval page on the cardholder's device must stay open. Its selected card, merchant origin, declared merchant, amount, currency, processor and environment bind one fresh request. The amount's authority is `agent`; a card token does not enforce the merchant's eventual charge amount.
 
 | Processor | `environment` | Fresh native request |
 | --- | --- | --- |
@@ -443,7 +447,7 @@ Braintree's native `ClientConfiguration` GraphQL query can run before, during or
 
 Readiness lasts up to 30 seconds (`preparation.expiresAt`) and appears as `ready_to_submit`, with `paymentStatus: 'not_started'`. Trigger the caller-owned Pay action immediately after the promise resolves. Expiry, navigation, cancellation, an early request or a changed checkout fails closed. A preparation and its attachment are single use; reconcile any bound authorization before creating a new attachment. The SDK never clicks Pay, reuses a stale request, changes native request deadlines, or automatically retries a failed prepared checkout.
 
-After Pay, the processor's native deadline still covers fresh authorization binding, device replay and token handoff. A disconnected/backgrounded phone or slow transport can still miss it. A subsequent SCA challenge has its own lifetime after token handoff. If the merchant request aborts or its frame closes, the attachment blocks further requests and tries to retire the pre-replay authorization; a started replay or unconfirmed cancellation remains unknown. Without `prepare()`, approval loading and human interaction still share the native deadline, so delayed approval cannot finish that request.
+After Pay, the processor's native deadline still covers fresh authorization binding, device replay and token handoff. A disconnected or backgrounded cardholder device, or a slow transport, can still miss it. A subsequent SCA challenge has its own lifetime after token handoff. If the merchant request aborts or its frame closes, the attachment blocks further requests and tries to retire the pre-replay authorization; a started replay or unconfirmed cancellation remains unknown. Without `prepare()`, approval loading and human interaction still share the native deadline, so delayed approval cannot finish that request.
 
 Lost authorization polling, local approval timeouts, or interrupted browser
 handoffs produce `outcome_unknown` and block automatic retry. The thrown
@@ -517,3 +521,12 @@ coverage classifications, `recognized_traffic_share` is traffic-weighted, and
 `purchase_success_rate` stays null without observed merchant outcomes. Do not
 substitute the assessor for a browser/merchant validation run or use native
 Kernel adapter coverage as evidence for this SDK's coverage.
+### Autopilot execution metadata
+
+When the cardholder has enabled an eligible spending rule in their vault, the same authorization can run through autopilot. The SDK keeps polling the existing authorization and returns optional `executionMode: 'autopilot' | 'user_approval'` and `grantId` metadata. Older API responses remain supported.
+
+`authorize()` accepts optional `executionMode` and `grantId` routing hints, sent as `execution_mode` and `grant_id`. These never establish permission to spend; the protected payment service checks the cardholder's signed rule. Autopilot suppresses `onApprovalUrl` while it is executing. A definite fallback to user approval delivers the existing authorization's URL once. A lost outcome remains `PaymentOutcomeUnknownError`; it does not create or submit a second payment.
+
+Use `executionMode: 'user_approval'` to require the existing confirmation flow. Without a selected card or grant, the backend can use exactly one eligible rule; ambiguous card selection keeps confirmation. A `grantId` restricts selection to that rule. The initial executor supports only the configured controlled Stripe test flow, and production remains disabled.
+
+The adapters also send the observed top-level HTTPS `merchantOrigin`, such as `https://shop.example`, without a path, query or trailing slash. Direct `authorize()` callers can supply that origin explicitly. It is a routing hint; the protected adapter independently verifies the processor account, payee and amount. If a browser cannot provide its top-level URL, an explicit `merchantOrigin` option can supply the hint; otherwise the regular approval path remains available.

package/dist/braintree.d.ts

@@ -1,10 +1,2 @@
-/** Classify native Braintree GraphQL requests without changing their bytes. */
-export type BraintreeEnvironment = 'production' | 'sandbox';
-export type BraintreeRequestKind = 'configuration' | 'tokenization' | 'invalid';
-export declare function braintreeEnvironment(url: string): BraintreeEnvironment | undefined;
-/** Bounded duplicate-aware JSON for fresh-card preparation bodies. */
-export declare function readTokenizationJson(body: string | null): Record<string, unknown> | null;
-/** Undefined belongs to another processor; invalid Braintree requests stay blocked. */
-export declare function classifyBraintreeRequest(url: string, method: string, body: string | null): BraintreeRequestKind | undefined;
-/** Preparation accepts guest tokenization only; ordinary interception stays broader. */
-export declare function isPreparedBraintreeRequest(body: string | null): boolean;
+export { braintreeEnvironment, classifyBraintreeRequest, isPreparedBraintreeRequest, readTokenizationJson } from './braintree.generated.js';
+export type { BraintreeEnvironment, BraintreeRequestKind } from './braintree.generated.js';

package/dist/braintree.generated.d.ts

@@ -0,0 +1,10 @@
+/** Classify native Braintree GraphQL requests without changing their bytes. */
+export type BraintreeEnvironment = 'production' | 'sandbox';
+export type BraintreeRequestKind = 'configuration' | 'tokenization' | 'invalid';
+export declare function braintreeEnvironment(url: string): BraintreeEnvironment | undefined;
+/** Bounded duplicate-aware JSON for fresh-card preparation bodies. */
+export declare function readTokenizationJson(body: string | null): Record<string, unknown> | null;
+/** Undefined belongs to another processor; invalid Braintree requests stay blocked. */
+export declare function classifyBraintreeRequest(url: string, method: string, body: string | null): BraintreeRequestKind | undefined;
+/** Preparation accepts guest tokenization only; ordinary interception stays broader. */
+export declare function isPreparedBraintreeRequest(body: string | null): boolean;