@agent-cards/checkout 0.18.0 → 0.21.0

package/dist/stripe-checkout.js

@@ -1,140 +0,0 @@
-import { classifyStripeCheckoutRequest, createStripeCheckoutTokenizationStub, encodeStripeCheckoutContext, isStripeCheckoutEndpoint, STRIPE_CHECKOUT_CONTEXT_HEADER, captureStripeCheckoutBilling, attachStripeCheckoutBilling, validateStripeCheckoutIdentity, stripeCheckoutValidationCode, STRIPE_CHECKOUT_VALIDATION_CODES, } from './stripe-checkout.generated.js';
-class StripeCheckoutRejectionError extends Error {
-    stage;
-    reason;
-    phase;
-    validationCode;
-    constructor(message, stage, reason, phase, validationCode) {
-        super(message);
-        this.stage = stage;
-        this.reason = reason;
-        this.phase = phase;
-        this.validationCode = validationCode;
-    }
-}
-export function stripeCheckoutReadinessError(reason) {
-    return new StripeCheckoutRejectionError('checkout_interception_not_ready', 'readiness', reason);
-}
-/** A valid competing request must not retire the request that already claimed this step. */
-export class StripeCheckoutClaimConflictError extends StripeCheckoutRejectionError {
-    constructor(phase) {
-        super(phase === 'tokenization' ? 'Native Stripe Checkout preparation is already claimed.'
-            : 'Native Stripe Checkout confirmation is already claimed.', 'claim', phase === 'tokenization' ? 'duplicate_tokenization' : 'duplicate_confirmation', phase);
-    }
-}
-/** The two native browser requests belong to one attachment and one grant.
- * Processor rules and form transformations live in the generated shared core.
- * The local stub contains no selected-card data and starts no authorization.
- */
-export class StripeCheckoutGate {
-    state = 'fresh';
-    billing;
-    binding;
-    constructor(options) {
-        if (!options.stripeCheckout)
-            return;
-        const { sessionId, publishableKey, environment } = options.stripeCheckout;
-        validateStripeCheckoutIdentity({ environment, sessionId, publishableKey });
-        if (options.executionMode !== 'autopilot' || !/^apg_[A-Za-z0-9_-]{1,128}(?![\s\S])/.test(options.grantId ?? '')
-            || !Number.isSafeInteger(options.amount) || Number(options.amount) <= 0 || options.currency !== 'usd')
-            throw new Error('Native Stripe Checkout requires a mode-bound session, grant and numeric USD amount.');
-        this.binding = Object.freeze({ environment, sessionId, publishableKey, amountCents: options.amount,
-            syntheticPaymentMethodId: `pm_agentcard_checkout_${crypto.randomUUID().replaceAll('-', '')}` });
-    }
-    matches(url) { return !!this.binding && isStripeCheckoutEndpoint(url); }
-    isEnabled() { return !!this.binding; }
-    isPrepared() { return this.state !== 'fresh'; }
-    invalidate() { this.state = 'stopped'; this.billing = undefined; }
-    /** Observability only: this endpoint label never participates in a payment decision. */
-    describeRejection(error, rawUrl, stage, phase = 'unknown') {
-        let family = 'other';
-        try {
-            const url = new URL(rawUrl);
-            if (url.origin === 'https://api.stripe.com' && url.pathname === '/v1/payment_methods')
-                family = 'payment_methods';
-            else if (isStripeCheckoutEndpoint(rawUrl))
-                family = 'payment_page_confirm';
-        }
-        catch { /* No untrusted URL or parser error leaves this method. */ }
-        const fallback = {
-            request_read: 'request_unavailable', classification: 'request_validation_failed', claim: 'preparation_unavailable',
-            readiness: 'readiness_unavailable', document: 'document_unavailable', stub_response: 'stub_response_failed',
-        };
-        const rejection = error instanceof StripeCheckoutRejectionError ? error : undefined;
-        const reason = rejection?.reason ?? fallback[stage];
-        return { version: 1, processor: 'stripe', endpoint_family: family,
-            phase: rejection?.phase ?? phase, stage: rejection?.stage ?? stage, reason,
-            ...(reason === 'request_validation_failed' ? { validation_code: rejection?.validationCode ?? STRIPE_CHECKOUT_VALIDATION_CODES.unclassified } : {}),
-            gate_state: this.state, disposition: error instanceof StripeCheckoutClaimConflictError ? 'active_claim_preserved' : 'checkout_stopped' };
-    }
-    assertClaim(step) {
-        if (this.state !== (step.phase === 'tokenization' ? 'stubbed' : 'submitted'))
-            throw new StripeCheckoutRejectionError('Native Stripe Checkout preparation is unavailable.', 'claim', 'claim_invalidated', step.phase);
-    }
-    /** Check the actual top-level hosted document before preparing either step. */
-    assertDocument(raw) {
-        if (!this.binding)
-            return;
-        const url = new URL(raw);
-        if (url.origin !== 'https://checkout.stripe.com' || url.username || url.password
-            || ![`/c/pay/${this.binding.sessionId}`, `/pay/${this.binding.sessionId}`, `/g/pay/${this.binding.sessionId}`, `/f/pay/${this.binding.sessionId}`].includes(url.pathname)) {
-            this.invalidate();
-            throw new StripeCheckoutRejectionError('Native Stripe Checkout document changed.', 'document', 'document_changed');
-        }
-    }
-    claim(request) {
-        if (!this.binding)
-            return null;
-        if (request.method.toUpperCase() !== 'POST')
-            return null;
-        let phase;
-        try {
-            phase = classifyStripeCheckoutRequest(request, this.binding);
-        }
-        catch (error) {
-            throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'classification', 'request_validation_failed', 'unknown', stripeCheckoutValidationCode(error));
-        }
-        if (!phase)
-            return null;
-        const diagnosticPhase = phase.phase === 'tokenization' ? 'tokenization' : phase.phase === 'final' ? 'final' : 'unknown';
-        if (Object.keys(request.headers).some(name => name.toLowerCase() === STRIPE_CHECKOUT_CONTEXT_HEADER))
-            throw new StripeCheckoutRejectionError('Native Stripe Checkout already carries a context.', 'claim', 'context_already_present', diagnosticPhase);
-        if (phase.phase === 'tokenization') {
-            if (this.state === 'stubbed' || this.state === 'submitted')
-                throw new StripeCheckoutClaimConflictError('tokenization');
-            if (this.state !== 'fresh')
-                throw new StripeCheckoutRejectionError('Native Stripe Checkout preparation is unavailable.', 'claim', 'preparation_unavailable', 'tokenization');
-            this.state = 'stopped';
-            let response;
-            try {
-                this.billing = captureStripeCheckoutBilling(request, this.binding);
-                response = createStripeCheckoutTokenizationStub(request, this.binding);
-            }
-            catch (error) {
-                const code = stripeCheckoutValidationCode(error);
-                if (code !== STRIPE_CHECKOUT_VALIDATION_CODES.unclassified)
-                    throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'classification', 'request_validation_failed', 'tokenization', code);
-                throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'stub_response', 'stub_response_failed', 'tokenization');
-            }
-            this.state = 'stubbed';
-            return { phase: 'tokenization', response };
-        }
-        if (phase.phase === 'final' && this.state === 'submitted')
-            throw new StripeCheckoutClaimConflictError('final');
-        if (phase.phase !== 'final' || this.state !== 'stubbed')
-            throw new StripeCheckoutRejectionError('Native Stripe Checkout has no matching prepared request.', 'claim', 'preparation_missing', diagnosticPhase);
-        let final;
-        try {
-            final = attachStripeCheckoutBilling(request, this.billing, this.binding);
-        }
-        catch (error) {
-            this.invalidate();
-            throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'classification', 'request_validation_failed', 'final', stripeCheckoutValidationCode(error));
-        }
-        this.state = 'submitted';
-        this.billing = undefined;
-        return { phase: 'final', request: { ...final, headers: { ...final.headers,
-                    [STRIPE_CHECKOUT_CONTEXT_HEADER]: encodeStripeCheckoutContext({ version: 1,
-                        session_id: this.binding.sessionId, synthetic_payment_method_id: this.binding.syntheticPaymentMethodId }) } } };
-    }
-}

package/dist/substitute.d.ts

@@ -1,38 +0,0 @@
-/**
- * The cse half of a replay: put the vault's ciphertext into the paused body.
- *
- * On a client-side-encrypted processor (Adyen) the cardholder's device does
- * not call the processor. It encrypts the card under the processor's public
- * key and reports the ciphertext; the paused request then continues from the
- * agent's own browser with those blobs in place of the dummy ones. Everything
- * else in the body (session data, risk data, browser info, origin) stays the
- * browser's own, so the processor's origin allowlist and risk checks see the
- * request they expected.
- *
- * Deliberately narrow: only keys that ALREADY exist as strings at the named
- * path are overwritten. A key is never added, a sibling is touched only when
- * the API names it in `remove` (Adyen's `brand`, which adyen-web derived from
- * the dummy digits the agent typed: left in place it describes the wrong card
- * and Adyen refuses the mismatch), and a body that does not carry the fields
- * is refused rather than guessed at.
- */
-export interface Substitutions {
-    encoding: 'json';
-    /** Dotted path to the object that holds the fields, e.g. `paymentMethod`. */
-    at: string;
-    /** Field name -> ciphertext, exactly as the vault reported it. */
-    fields: Record<string, string>;
-    /**
-     * Sibling keys at `at` to delete when present (never an error when absent):
-     * values the page SDK derived from the agent's dummy card that would
-     * contradict the swapped ciphertext. Served by the API per processor.
-     */
-    remove?: string[];
-}
-declare class SubstitutionErrorShape extends Error {
-    constructor(message: string);
-}
-export type SubstitutionError = SubstitutionErrorShape;
-export declare const SubstitutionError: typeof SubstitutionErrorShape;
-export declare const substituteEncryptedFields: (body: string, sub: Substitutions) => string;
-export {};

package/dist/substitute.js

@@ -1,23 +0,0 @@
-/**
- * The cse half of a replay: put the vault's ciphertext into the paused body.
- *
- * On a client-side-encrypted processor (Adyen) the cardholder's device does
- * not call the processor. It encrypts the card under the processor's public
- * key and reports the ciphertext; the paused request then continues from the
- * agent's own browser with those blobs in place of the dummy ones. Everything
- * else in the body (session data, risk data, browser info, origin) stays the
- * browser's own, so the processor's origin allowlist and risk checks see the
- * request they expected.
- *
- * Deliberately narrow: only keys that ALREADY exist as strings at the named
- * path are overwritten. A key is never added, a sibling is touched only when
- * the API names it in `remove` (Adyen's `brand`, which adyen-web derived from
- * the dummy digits the agent typed: left in place it describes the wrong card
- * and Adyen refuses the mismatch), and a body that does not carry the fields
- * is refused rather than guessed at.
- */
-// The implementation is bundled from the internal core; the published SDK
-// keeps its existing public types and does not require another package at runtime.
-import { substituteEncryptedFields as sharedSubstitute, SubstitutionError as SharedSubstitutionError, } from './substitutions.generated.js';
-export const SubstitutionError = SharedSubstitutionError;
-export const substituteEncryptedFields = sharedSubstitute;

package/dist/substitutions.generated.d.ts

@@ -1,10 +0,0 @@
-declare var SubstitutionError: {
-    new (message: any): {
-        name: string;
-        message: string;
-        stack?: string;
-        cause?: unknown;
-    };
-};
-declare function substituteEncryptedFields(body: any, sub: any): string;
-export { SubstitutionError, substituteEncryptedFields };

package/dist/substitutions.generated.js

@@ -1,66 +0,0 @@
-// @ts-nocheck
-// Generated from @agent-cards/payment-core. Do not edit.
-// artifact-sha256: a74db713f1742d9bc5dc8efc78b364d2a69b255ee8da7f98345242f02114e6ce
-// src/substitutions.js
-var SubstitutionError = class extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "SubstitutionError";
-    }
-};
-var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-function isPlainObject(v) {
-    return !!v && typeof v === "object" && !Array.isArray(v);
-}
-function substituteEncryptedFields(body, sub) {
-    if (!sub || sub.encoding !== "json") {
-        throw new SubstitutionError(`unsupported substitution encoding: ${String(sub?.encoding)}`);
-    }
-    if (typeof sub.at !== "string" || !sub.at)
-        throw new SubstitutionError("substitutions name no path");
-    if (!isPlainObject(sub.fields) || Object.keys(sub.fields).length === 0) {
-        throw new SubstitutionError("substitutions carry no fields");
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(body);
-    }
-    catch {
-        throw new SubstitutionError("the paused body is not JSON");
-    }
-    if (!isPlainObject(parsed))
-        throw new SubstitutionError("the paused body is not a JSON object");
-    let node = parsed;
-    for (const step of sub.at.split(".")) {
-        if (!step || FORBIDDEN_KEYS.has(step))
-            throw new SubstitutionError(`refusing substitution path ${sub.at}`);
-        const next = node[step];
-        if (!isPlainObject(next))
-            throw new SubstitutionError(`the paused body has no object at ${sub.at}`);
-        node = next;
-    }
-    for (const [key, value] of Object.entries(sub.fields)) {
-        if (FORBIDDEN_KEYS.has(key))
-            throw new SubstitutionError(`refusing substitution field ${key}`);
-        if (typeof value !== "string" || value.length === 0)
-            throw new SubstitutionError(`substitution for ${key} is not a string`);
-        if (typeof node[key] !== "string")
-            throw new SubstitutionError(`the paused body has no string field ${sub.at}.${key}`);
-    }
-    const remove = sub.remove ?? [];
-    if (!Array.isArray(remove))
-        throw new SubstitutionError("substitutions.remove is not a list");
-    for (const key of remove) {
-        if (typeof key !== "string" || !key || FORBIDDEN_KEYS.has(key))
-            throw new SubstitutionError(`refusing removal of ${String(key)}`);
-        if (key in sub.fields)
-            throw new SubstitutionError(`substitution field ${key} is also listed for removal`);
-    }
-    for (const [key, value] of Object.entries(sub.fields))
-        node[key] = value;
-    for (const key of remove)
-        if (Object.prototype.hasOwnProperty.call(node, key))
-            delete node[key];
-    return JSON.stringify(parsed);
-}
-export { SubstitutionError, substituteEncryptedFields };

package/examples/existing-browser.mjs

@@ -1,63 +0,0 @@
-// Existing Kernel / Browserbase / custom Chromium session; does not create or close the provider's browser.
-// Run: CHECKOUT_DRIVER=/absolute/path/to/instinct-driver.mjs node examples/existing-browser.mjs
-// The driver owns the existing agent, its approved purchase and merchant-specific order verification.
-import { pathToFileURL } from 'node:url';
-import { chromium } from 'playwright-core';
-import { VaultClient, attachToPlaywright } from '../dist/index.js';
-
-const driverPath = process.env.CHECKOUT_DRIVER;
-if (!driverPath?.startsWith('/')) throw new Error('CHECKOUT_DRIVER must name an absolute path to your integration module.');
-const driver = await import(pathToFileURL(driverPath).href);
-for (const method of ['prepareCheckout', 'submitCheckout', 'resolveMerchantResult', 'onUserAction', 'finishAfterPayment']) {
-  if (typeof driver[method] !== 'function') throw new Error(`Your driver must implement ${method}.`);
-}
-if (!process.env.CHECKOUT_CDP_URL) throw new Error('Set CHECKOUT_CDP_URL to your existing session connection URL. Never log it.');
-for (const name of ['AGENTCARD_CLIENT_ID', 'AGENTCARD_CLIENT_SECRET']) {
-  if (!process.env[name]) throw new Error(`Set ${name} for your Agentcard organization.`);
-}
-const browser = await chromium.connectOverCDP(process.env.CHECKOUT_CDP_URL);
-try {
-const context = browser.contexts()[0];
-if (!context) throw new Error('The provider returned no default browser context.');
-const pages = context.pages();
-const index = Number(process.env.CHECKOUT_PAGE_INDEX ?? 0);
-const page = pages[index];
-if (!page) throw new Error('CHECKOUT_PAGE_INDEX must select the existing agent checkout tab.');
-
-const vault = new VaultClient({ clientId: process.env.AGENTCARD_CLIENT_ID, clientSecret: process.env.AGENTCARD_CLIENT_SECRET });
-await vault.syncRegistry();
-const checkout = await driver.prepareCheckout(page); // user, merchant, amountCents+currency, exact paymentEndpoints
-const controller = await attachToPlaywright(page, {
-  ...checkout,
-  vault,
-  requireMerchantResult: true,
-  onUserAction: action => driver.onUserAction(action, { page }),
-  resolveMerchantResult: state => driver.resolveMerchantResult({ page, state }),
-  // State has no PAN, replay body, approval capability, or provider connection URL.
-  onStateChange: state => console.log(JSON.stringify(state)),
-});
-
-// Must return after dispatching the click; do not block on a navigation that awaits user approval.
-await driver.submitCheckout(page);
-const deadline = Date.now() + 15 * 60_000;
-while (Date.now() < deadline) {
-  let state = controller.getState();
-  if (['awaiting_merchant', 'requires_user_action', 'outcome_unknown'].includes(state.status)) {
-    state = await controller.reconcile();
-  }
-  if (state.status === 'completed' && state.orderId) {
-    await driver.finishAfterPayment({ page, orderId: state.orderId });
-    break;
-  }
-  if (['declined', 'timed_out', 'cancelled', 'unsupported', 'failed'].includes(state.status)) break;
-  await new Promise(resolve => setTimeout(resolve, 1000));
-}
-if (controller.getState().status !== 'completed') {
-  controller.cancel(); // local stop only; reconcile any still-valid approval before creating a new one
-  process.exitCode = 2;
-}
-} finally {
-  // Disconnect this CDP client. The existing agent retains ownership of its provider session.
-  // Do not call page.close(), context.close(), or a provider session-delete API here.
-  await browser.close();
-}

package/examples/preflight/classify-direct.mjs

@@ -1,21 +0,0 @@
-// Run from an installed SDK or from this package after npm run build.
-// Optional argument: observations JSON path. Uses this SDK's bundled capabilities.
-import { readFile } from 'node:fs/promises';
-import {
-  normalizeCheckoutSignals,
-  assessCheckoutSupport,
-} from '@agent-cards/checkout/preflight';
-
-try {
-  const observations = JSON.parse(await readFile(
-    process.argv[2] ?? new URL('./stripe-script.observations.json', import.meta.url), 'utf8',
-  ));
-  const snapshot = normalizeCheckoutSignals(observations);
-  const result = assessCheckoutSupport(snapshot, { scenario: 'one_time' });
-
-  // Read support_scope and checkout_flow_status with status before continuing.
-  console.log(JSON.stringify({ snapshot, result }, null, 2));
-} catch {
-  console.error('Could not assess the observations. Check the JSON file against PREFLIGHT.md.');
-  process.exitCode = 1;
-}

package/examples/preflight/classify-kernel.mjs

@@ -1,30 +0,0 @@
-// Run from an installed SDK or from this package after npm run build.
-// Optional arguments: observations JSON path, profile JSON path, adapter version.
-import { readFile } from 'node:fs/promises';
-import {
-  normalizeCheckoutSignals,
-  assessCheckoutSupport,
-} from '@agent-cards/checkout/preflight';
-
-const [observationsPath, profilePath, adapterVersion = 'example-native-adapter'] = process.argv.slice(2);
-
-try {
-  const observations = JSON.parse(await readFile(
-    observationsPath ?? new URL('./stripe-script.observations.json', import.meta.url), 'utf8',
-  ));
-  const profile = JSON.parse(await readFile(
-    profilePath ?? new URL('./kernel-profile.empty.json', import.meta.url), 'utf8',
-  ));
-  const snapshot = normalizeCheckoutSignals(observations);
-  const result = assessCheckoutSupport(snapshot, {
-    scenario: 'one_time',
-    integration: { id: 'kernel_native', version: adapterVersion },
-    profile,
-  });
-
-  // Normalized snapshots contain reviewed rule IDs rather than raw asset URLs.
-  console.log(JSON.stringify({ snapshot, result }, null, 2));
-} catch {
-  console.error('Could not assess the observations. Check the JSON files and adapter version against PREFLIGHT.md.');
-  process.exitCode = 1;
-}

package/examples/preflight/inspect-browser.mjs

@@ -1,44 +0,0 @@
-// Read an existing checkout tab. Does not navigate, click, fill, or attach payment interception.
-// Install playwright-core in the consuming project before running this example.
-import { readFile } from 'node:fs/promises';
-import { chromium } from 'playwright-core';
-import { inspectCheckout } from '@agent-cards/checkout/playwright';
-
-let browser;
-try {
-  if (!process.env.CHECKOUT_CDP_URL) throw new Error('missing_connection');
-  const integration = process.env.CHECKOUT_INTEGRATION ?? 'kernel_native';
-  if (!['kernel_native', 'direct_sdk'].includes(integration)) throw new Error('invalid_integration');
-  const pageIndex = Number(process.env.CHECKOUT_PAGE_INDEX ?? 0);
-  if (!Number.isSafeInteger(pageIndex) || pageIndex < 0) throw new Error('invalid_page_index');
-
-  const profile = integration === 'kernel_native' && process.env.CHECKOUT_PROFILE
-    ? JSON.parse(await readFile(process.env.CHECKOUT_PROFILE, 'utf8'))
-    : undefined;
-  const options = integration === 'direct_sdk'
-    ? { scenario: 'one_time' }
-    : {
-      scenario: 'one_time',
-      integration: { id: 'kernel_native', version: process.env.CHECKOUT_ADAPTER_VERSION ?? null },
-      profile,
-    };
-
-  browser = await chromium.connectOverCDP(process.env.CHECKOUT_CDP_URL, { timeout: 15_000 });
-  const page = browser.contexts()[0]?.pages()[pageIndex];
-  if (!page) throw new Error('page_not_found');
-
-  const result = await inspectCheckout(page, options);
-  console.log(JSON.stringify(result, null, 2));
-} catch {
-  // A browser connection URL can contain a credential. Do not print connection errors.
-  console.error('Could not inspect the checkout. Check the CDP connection, page index, integration, and optional profile.');
-  process.exitCode = 1;
-} finally {
-  if (browser) {
-    // Disconnect this CDP client; the existing agent keeps its browser session.
-    await browser.close().catch(() => {
-      console.error('Could not disconnect the inspection client. Close this local process before inspecting again.');
-      process.exitCode = 1;
-    });
-  }
-}

package/examples/preflight/kernel-native/README.md

@@ -1,112 +0,0 @@
-# Qualify Kernel native coverage
-
-You can detect a checkout's PSP before entering card details with `@agent-cards/checkout@0.9.0`. Kernel native support needs a separate profile for the native adapter that actually runs the checkout. The direct SDK's coverage does not establish Kernel's native coverage.
-
-No qualified native profile accompanies this kit. The inventory covers all 23 PSPs in the checkout catalog and reports `unknown` for every native runtime status. Kernel's pinned documentation lists Stripe, Shopify, Square, Recurly, and Razorpay. The other processors are unestablished, rather than explicitly unsupported. See the endpoint constraints and source hashes in [documented-adapters.json](./documented-adapters.json).
-
-## Use the detector now
-
-Install the published detector in your application:
-
-```bash
-npm install --save-exact @agent-cards/checkout@0.9.0
-node node_modules/@agent-cards/checkout/examples/preflight/classify-kernel.mjs
-```
-
-The example reads synthetic Stripe observations and an empty native profile. The detector identifies Stripe and returns `unknown` for native support. The example needs no credentials and submits no payment. Follow [PREFLIGHT.md](../../../PREFLIGHT.md) to collect observations from a browser or supply normalized JSON from Kernel.
-
-The qualification commands below are available in this source kit. The published `0.9.0` detector does not contain the new qualification commands. From the checkout package directory, build the source kit with Node.js 22 or later:
-
-```bash
-cd apps/agent-cards/packages/checkout
-npm run build
-node examples/preflight/kernel-native/qualification.mjs inventory
-```
-
-The inventory pairs each canonical PSP and mode with its documentation status. `documentation: "documented"` records a statement in the pinned source; `status: "unknown"` records the absence of qualified runtime evidence. The documentation baseline grants no permission to send card data anywhere.
-
-The checker compares PSP membership and payment modes with the SDK's separate request registry before comparing the saved inventory. Removing a processor from both the preflight catalog and the inventory still fails this check.
-
-When an installed SDK package includes this kit, run the commands directly from that package:
-
-```bash
-node node_modules/@agent-cards/checkout/examples/preflight/kernel-native/qualification.mjs inventory --check
-```
-
-## Identify the native build
-
-Kernel must provide access to the native adapter source and build, or a test deployment whose adapter identity can be independently checked. Record the actual adapter's version and SHA-256 artifact digest in a runtime JSON file with the fields `version` and `artifact_sha256`.
-
-Obtain the runtime identity from the deployed artifact or a trusted deployment record. Do not copy the identity from the test report, use the client SDK's npm version, or use the CLI version. Public API and client documentation do not currently supply a native adapter build identity.
-
-Kernel must also provide a way to exercise that build with the intended payment environment. A documented sandbox processor hostname does not establish that the native card API permits sandbox testing. Agree on the supported test environment before preparing an execution run.
-
-## Declare only tested coverage
-
-Start from [kernel-profile.empty.json](../kernel-profile.empty.json). Set `integration.version` to the independently identified native adapter version. Keep unqualified declarations absent so that the detector returns `unknown`.
-
-A `processor_entries` declaration covers a PSP, mode, and scenario. A flow entry in `entries` also binds the specific flow, operation, and operation version. A successful test of one checkout flow cannot justify processor-wide coverage. The reviewer must check that the tests cover the whole declaration being released.
-
-Every declaration in this kit needs explicit `limitations`, including supported declarations. Use `unsupported` only for an established native exclusion, with evidence and a useful explanation. Shared Vault exclusions still apply; a profile cannot override them. The checker refuses supported subscription renewals and hosted-form scenarios other than `one_time`.
-
-A profile is trusted application configuration. Never accept a profile from a merchant page. Continue to supply the actual running adapter version separately when calling `assessCheckoutSupport`.
-
-## Test the native path
-
-Run each declared case through Kernel's native Agentcard interception and approval path. A browser connected over CDP while the direct checkout SDK performs interception tests the direct SDK. Synthetic fixtures and unit tests verify the checker; they do not qualify a native adapter.
-
-Each supported declaration requires the following passed checks and retained evidence:
-
-| Check ID | What the evidence must establish |
-| --- | --- |
-| `native_recognition` | The identified native build recognizes the intended request layout and processor operation. |
-| `approval_pause_resume` | The payment pauses for approval and resumes once after approval. |
-| `processor_replay` | The approved request reaches the processor through the native path and its response returns to the merchant. |
-| `merchant_confirmation` | The merchant confirms the intended payment outcome; approval or token creation alone is insufficient. |
-| `unrecognized_request_passthrough` | A request outside the declared native recognition rules follows the documented unrecognized-request behavior. |
-| `decline_or_error` | A processor refusal or error reaches the caller as a failure rather than a successful purchase. |
-| `no_duplicate_submission` | Timeout, retry, and repeated approval handling do not produce duplicate submissions. |
-| `authentication_or_explicit_exclusion` | Required authentication completes, or the profile states and the evidence establishes the excluded authentication cases. |
-
-Supported `save_card` declarations also require `stored_card_consent` and `merchant_card_saved`. Supported `subscription_initial` declarations also require `stored_card_consent` and `merchant_subscription_confirmation`. An unsupported declaration requires `native_exclusion` instead of the support checks.
-
-Retain sanitized evidence files without card details, credentials, or approval secrets. Store evidence under one directory and reference each file by a relative path and its SHA-256 digest.
-
-## Bind the execution report
-
-The report records `schema_version: 1`, `execution: "kernel_native"`, the adapter's `version` and `artifact_sha256`, the harness commit, and the reviewer's identity. `harness_commit` must be a full 40-character Git commit. `reviewed_by` identifies the person accountable for checking the native execution evidence.
-
-The report's `catalog_sha256` and `profile_sha256` bind the exact catalog and profile JSON. Compute both using the exported `digest` function in `qualification.mjs`. The function sorts object keys recursively before hashing JSON; a hash of a pretty-printed file is different. Evidence digests hash the file's exact bytes.
-
-The report contains exactly one `claims` entry per profile declaration. Each entry has a `key` and `checks`. Use these key formats:
-
-```text
-processor:<psp>:<mode>:<scenario>
-flow:<flow>:<operation>:<operation_version>:<mode>:<scenario>
-```
-
-Each check contains `id`, `outcome: "passed"`, and `evidence: { "path": "relative-file", "sha256": "file-digest" }`. Failed, missing, duplicate, and extra checks prevent qualification. The checker also rejects evidence that escapes the evidence directory or differs from its retained digest.
-
-## Check a candidate release
-
-After a reviewed native execution run has produced the profile, report, independent runtime identity, and retained evidence, run:
-
-```bash
-node examples/preflight/kernel-native/qualification.mjs release \
-  --profile /tmp/kernel-native-validation/profile.json \
-  --report /tmp/kernel-native-validation/report.json \
-  --runtime /tmp/kernel-native-validation/runtime.json \
-  --evidence-dir /tmp/kernel-native-validation/evidence
-```
-
-The command prints `status: "qualified"` only when the supplied records satisfy the checks. The command does not publish a package, deploy the adapter, or install the profile in an application. Requalify after a change to the native build, profile, or catalog.
-
-The checker verifies consistency and retained file bytes. A matching digest does not prove that a native execution happened, that the stated deployment identity is truthful, or that the evidence supports every declared case. A trusted reviewer must establish those facts before accepting the profile.
-
-Without a complete candidate, the command exits with status `1`. The following stderr was captured by running `node examples/preflight/kernel-native/qualification.mjs release` without its required files:
-
-```text
-Native qualification failed. Check the arguments, catalog, build identity, profile, and retained evidence against README.md.
-```
-
-Supply the completed files with the command above. Keep native results `unknown` until the execution evidence and independent build identity are available.