@circle-fin/app-kit 1.13.0 → 1.15.0

package/server.d.ts

@@ -0,0 +1,2467 @@
+/**
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from '/home/runner/_work/stablecoin-kits-private/stablecoin-kits-private/node_modules/zod/dist/types/index.d.ts';
+
+/**
+ * Module augmentation to register known token symbols.
+ *
+ * @remarks
+ * This file augments the `TokenSymbolRegistry` interface to provide
+ * type-safe autocomplete for built-in tokens.
+ *
+ * When imported, TypeScript will recognize 'USDC' as a valid
+ * `TokenSymbol` value with autocomplete support.
+ *
+ * Other packages or applications can create their own augmentations
+ * to add additional tokens.
+ *
+ * @example
+ * ```typescript
+ * import '@core/tokens' // Automatically includes this augmentation
+ *
+ * const symbol: TokenSymbol = 'USDC' // ✓ Autocomplete shows USDC
+ * ```
+ */
+declare module './types' {
+    /**
+     * Module augmentation: Adds known token symbols as valid keys
+     * to the TokenSymbolRegistry interface.
+     *
+     * Keys are explicitly listed to ensure IDE autocomplete works properly.
+     */
+    interface TokenSymbolRegistry {
+        USDC: true;
+        USDT: true;
+        EURC: true;
+        DAI: true;
+        USDE: true;
+        PYUSD: true;
+        WETH: true;
+        WBTC: true;
+        WSOL: true;
+        WAVAX: true;
+        WPOL: true;
+        ETH: true;
+        POL: true;
+        PLUME: true;
+        MON: true;
+        cirBTC: true;
+    }
+}
+
+/**
+ * Enumeration of all blockchains known to this library.
+ *
+ * This enum contains every blockchain that has a chain definition, regardless
+ * of whether bridging is currently supported. For chains that support bridging
+ * via CCTPv2, see {@link BridgeChain}.
+ *
+ * @enum
+ * @category Enums
+ * @description Provides string identifiers for each blockchain with a definition.
+ * @see {@link BridgeChain} for the subset of chains that support CCTPv2 bridging.
+ */
+declare enum Blockchain {
+    Algorand = "Algorand",
+    Algorand_Testnet = "Algorand_Testnet",
+    Aptos = "Aptos",
+    Aptos_Testnet = "Aptos_Testnet",
+    Arbitrum = "Arbitrum",
+    Arbitrum_Sepolia = "Arbitrum_Sepolia",
+    Arc = "Arc",
+    Arc_Testnet = "Arc_Testnet",
+    Avalanche = "Avalanche",
+    Avalanche_Fuji = "Avalanche_Fuji",
+    Base = "Base",
+    Base_Sepolia = "Base_Sepolia",
+    Celo = "Celo",
+    Celo_Alfajores_Testnet = "Celo_Alfajores_Testnet",
+    Codex = "Codex",
+    Codex_Testnet = "Codex_Testnet",
+    Cronos = "Cronos",
+    Cronos_Testnet = "Cronos_Testnet",
+    Edge = "Edge",
+    Edge_Testnet = "Edge_Testnet",
+    Ethereum = "Ethereum",
+    Ethereum_Sepolia = "Ethereum_Sepolia",
+    Hedera = "Hedera",
+    Hedera_Testnet = "Hedera_Testnet",
+    HyperEVM = "HyperEVM",
+    HyperEVM_Testnet = "HyperEVM_Testnet",
+    Injective = "Injective",
+    Injective_Testnet = "Injective_Testnet",
+    Ink = "Ink",
+    Ink_Testnet = "Ink_Testnet",
+    Linea = "Linea",
+    Linea_Sepolia = "Linea_Sepolia",
+    Monad = "Monad",
+    Monad_Testnet = "Monad_Testnet",
+    Morph = "Morph",
+    Morph_Testnet = "Morph_Testnet",
+    NEAR = "NEAR",
+    NEAR_Testnet = "NEAR_Testnet",
+    Noble = "Noble",
+    Noble_Testnet = "Noble_Testnet",
+    Optimism = "Optimism",
+    Optimism_Sepolia = "Optimism_Sepolia",
+    Pharos = "Pharos",
+    Pharos_Testnet = "Pharos_Testnet",
+    Plasma = "Plasma",
+    Plasma_Testnet = "Plasma_Testnet",
+    Polkadot_Asset_Hub = "Polkadot_Asset_Hub",
+    Polkadot_Westmint = "Polkadot_Westmint",
+    Plume = "Plume",
+    Plume_Testnet = "Plume_Testnet",
+    Polygon = "Polygon",
+    Polygon_Amoy_Testnet = "Polygon_Amoy_Testnet",
+    Sei = "Sei",
+    Sei_Testnet = "Sei_Testnet",
+    Solana = "Solana",
+    Solana_Devnet = "Solana_Devnet",
+    Sonic = "Sonic",
+    Sonic_Testnet = "Sonic_Testnet",
+    Stellar = "Stellar",
+    Stellar_Testnet = "Stellar_Testnet",
+    Sui = "Sui",
+    Sui_Testnet = "Sui_Testnet",
+    Unichain = "Unichain",
+    Unichain_Sepolia = "Unichain_Sepolia",
+    World_Chain = "World_Chain",
+    World_Chain_Sepolia = "World_Chain_Sepolia",
+    XDC = "XDC",
+    XDC_Apothem = "XDC_Apothem",
+    X_Layer = "X_Layer",
+    X_Layer_Testnet = "X_Layer_Testnet",
+    ZKSync_Era = "ZKSync_Era",
+    ZKSync_Sepolia = "ZKSync_Sepolia"
+}
+
+/**
+ * Module augmentation to register Blockchain enum values as ChainIdentifiers.
+ *
+ * @remarks
+ * This file augments the `ChainRegistry` interface to provide type-safe
+ * autocomplete for all `Blockchain` enum values from `@core/chains`.
+ *
+ * When this augmentation is imported (via `@core/tokens`), TypeScript will
+ * recognize all blockchain identifiers as valid `ChainIdentifier` values
+ * with IDE autocomplete support.
+ *
+ * The `Blockchain` enum values are converted to their string representations,
+ * enabling both enum values and string literals to be accepted as chain identifiers.
+ *
+ * @example
+ * ```typescript
+ * import { Blockchain } from '@core/chains'
+ * import type { ChainIdentifier } from '@core/tokens'
+ *
+ * // Using enum value
+ * const chain1: ChainIdentifier = Blockchain.Ethereum
+ *
+ * // Using string literal (with autocomplete!)
+ * const chain2: ChainIdentifier = 'Base'
+ *
+ * // Arbitrary strings also work (escape hatch for custom chains)
+ * const chain3: ChainIdentifier = 'my-custom-chain'
+ * ```
+ */
+
+declare module './types' {
+    /**
+     * Module augmentation: Adds all Blockchain enum values as valid keys
+     * to the ChainRegistry interface for type-safe chain identifier support.
+     *
+     * This ensures both enum property access (e.g., Blockchain.Ethereum) and plain
+     * string literals (e.g., 'Ethereum') are accepted by TypeScript as chain keys,
+     * providing robust autocomplete and error checking.
+     *
+     * NOTE:
+     * - This interface intentionally has no body. It merges a mapped Record type
+     *   into ChainRegistry solely for type augmentation.
+     * - This empty-body construct is a necessary TypeScript idiom for module
+     *   augmentation with Record types—directly listing mapped keys is not
+     *   feasible in interface extensions.
+     *
+     * eslint-disable-next-line directives below suppress linter complaints about
+     * the empty interface/mapping, which are benign and required for this pattern.
+     */
+    interface ChainRegistry extends Record<`${Blockchain}`, true> {
+    }
+}
+
+/**
+ * Creates a union type that preserves IDE autocomplete for known literals
+ * while still accepting any string at runtime.
+ *
+ * @remarks
+ * This pattern uses `Record<never, never>` (an empty record type) to prevent
+ * TypeScript from widening string literals to just `string`. This gives us
+ * the best of both worlds: autocomplete for known values and flexibility
+ * for arbitrary strings.
+ *
+ * @typeParam T - The known string literal union to preserve.
+ */
+type LiteralUnion<T extends string> = T | (string & Record<never, never>);
+/**
+ * Registry for known chain identifiers (augmentation target).
+ *
+ * @remarks
+ * This empty interface exists solely for module augmentation. Extend it to
+ * register chain identifiers for type-safe token definitions.
+ *
+ * **Why an interface?** TypeScript only allows module augmentation on
+ * interfaces, not type aliases.
+ *
+ * **Note:** This is NOT the EVM "chain ID" (numeric like 1 for Ethereum).
+ * It's a human-readable identifier like "Ethereum", "Solana", "Base".
+ *
+ * **Usage**
+ *
+ * Without augmentation, `ChainIdentifier` defaults to `string`.
+ * With `@core/chains` imported, you get autocomplete for all `Blockchain` values.
+ *
+ * **Custom Chains**
+ *
+ * ```typescript
+ * declare module '@core/tokens' {
+ *   interface ChainRegistry {
+ *     MyChain: true
+ *     MyTestnet: true
+ *   }
+ * }
+ * // Now ChainIdentifier includes 'MyChain' | 'MyTestnet' | ...
+ * ```
+ *
+ * The value (`true`) is a placeholder—only the keys matter.
+ *
+ * NOTE: The eslint-disable below suppresses warnings about empty interfaces.
+ * This is intentional—the interface exists solely as an augmentation target.
+ */
+interface ChainRegistry {
+}
+/**
+ * Union of all registered chain identifiers.
+ *
+ * @remarks
+ * Derived from `ChainRegistry` keys:
+ * - Without augmentation: `string`
+ * - With `@core/chains`: `'Ethereum' | 'Solana' | ...` plus any string
+ *
+ * Uses `LiteralUnion` to preserve IDE autocomplete while allowing
+ * arbitrary strings at runtime.
+ *
+ * @example
+ * ```typescript
+ * const chain: ChainIdentifier = 'Ethereum'  // Autocomplete works
+ * const custom: ChainIdentifier = 'my-chain' // Also valid
+ * ```
+ */
+type ChainIdentifier = keyof ChainRegistry extends never ? string : LiteralUnion<Extract<keyof ChainRegistry, string>>;
+/**
+ * Maps chain identifiers to their token locators.
+ *
+ * @remarks
+ * The key is a chain identifier (type-safe when `KnownChainIdentifiers` is
+ * augmented). This enables a single token definition to work across chains.
+ *
+ * When `@core/chains` is imported, you get autocomplete for known chains
+ * like `Ethereum`, `Base`, `Solana`, etc.
+ *
+ * @example
+ * ```typescript
+ * import { Blockchain } from '@core/chains'
+ *
+ * const usdcLocators: ChainLocatorMap = {
+ *   [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *   [Blockchain.Solana]: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   [Blockchain.Base]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+ * }
+ *
+ * // Or with string keys (always works)
+ * const locators: ChainLocatorMap = {
+ *   'ethereum': '0xa0b86991...',
+ *   'my-custom-chain': '0x1234...',
+ * }
+ * ```
+ */
+type ChainLocatorMap = Record<ChainIdentifier, string>;
+/**
+ * Complete definition of a token including metadata and chain locators.
+ *
+ * @remarks
+ * This is the canonical representation of a token in the registry.
+ * It includes the symbol, decimals, and chain-specific locators.
+ *
+ * @example
+ * ```typescript
+ * const usdc: TokenDefinition = {
+ *   symbol: 'USDC',
+ *   decimals: 6,
+ *   locators: {
+ *     [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *     [Blockchain.Solana]: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   },
+ * }
+ * ```
+ */
+interface TokenDefinition {
+    /**
+     * The token symbol (e.g., "USDC", "EURC").
+     */
+    readonly symbol: string;
+    /**
+     * The default number of decimal places for the token.
+     * Used when no chain-specific override exists in {@link chainDecimals}.
+     * @example 6 for USDC, 18 for most ERC20 tokens
+     */
+    readonly decimals: number;
+    /**
+     * Chain-specific locators for the token.
+     * Keys are chain identifiers, values are the token address/locator on that chain.
+     * Not all chains need to be present - tokens may only exist on a subset of chains.
+     */
+    readonly locators: Partial<ChainLocatorMap>;
+    /**
+     * Optional per-chain decimal overrides.
+     *
+     * Some tokens have different decimal places on different chains
+     * (e.g., USDe is 18 decimals on EVM but 9 decimals on Solana).
+     * When present, the value for a specific chain takes precedence
+     * over the default {@link decimals}.
+     */
+    readonly chainDecimals?: Partial<Record<ChainIdentifier, number>>;
+}
+/**
+ * A raw token locator selector with explicit decimals.
+ *
+ * @remarks
+ * Use this form when working with arbitrary tokens not in the registry.
+ * The `locator` is the chain-specific address, and `decimals` is required
+ * unless using lenient mode.
+ *
+ * @example
+ * ```typescript
+ * // Selecting a custom token by address
+ * const selector: RawTokenSelector = {
+ *   locator: '0x1234567890abcdef1234567890abcdef12345678',
+ *   decimals: 18,
+ * }
+ * ```
+ */
+interface RawTokenSelector {
+    /**
+     * The chain-specific token locator (address, program ID, etc.).
+     */
+    readonly locator: string;
+    /**
+     * The number of decimal places.
+     * Required in strict mode, optional in lenient mode.
+     */
+    readonly decimals?: number;
+}
+/**
+ * Registry for known token symbols (augmentation target).
+ *
+ * @remarks
+ * This empty interface exists solely for module augmentation. Extend it to
+ * register token symbols for type-safe selection.
+ *
+ * **Why an interface?** TypeScript only allows module augmentation on
+ * interfaces, not type aliases.
+ *
+ * **Usage**
+ *
+ * Without augmentation, `TokenSymbol` defaults to `string`.
+ *
+ * ```typescript
+ * declare module '@core/tokens' {
+ *   interface TokenSymbolRegistry {
+ *     USDC: true
+ *     EURC: true
+ *   }
+ * }
+ * // Now TokenSymbol includes 'USDC' | 'EURC' | ...
+ * ```
+ *
+ * NOTE: The eslint-disable below suppresses warnings about empty interfaces.
+ * This is intentional—the interface exists solely as an augmentation target.
+ */
+interface TokenSymbolRegistry {
+}
+/**
+ * Union type of all registered token symbols.
+ *
+ * @remarks
+ * This type is derived from the keys of `TokenSymbolRegistry`:
+ * - **Without augmentation** — Simply `string` (any value)
+ * - **With augmentation** — `'USDC' | 'USDT' | ...` plus any string
+ *
+ * Uses `LiteralUnion` to preserve autocomplete for known values while
+ * still accepting any string at runtime.
+ *
+ * @example
+ * ```typescript
+ * // With symbols.augment imported - autocomplete works
+ * const symbol: TokenSymbol = 'USDC'
+ *
+ * // Custom strings still accepted
+ * const symbol: TokenSymbol = 'MY_TOKEN'
+ * ```
+ */
+type TokenSymbol = keyof TokenSymbolRegistry extends never ? string : LiteralUnion<Extract<keyof TokenSymbolRegistry, string>>;
+/**
+ * Token selector accepted by adapters and the static
+ * {@link TokenRegistry.resolve} method.
+ *
+ * @remarks
+ * Keep this alias at adapter and registry boundaries so their accepted token
+ * forms remain explicit even when other product surfaces define narrower
+ * token inputs.
+ */
+type RegistryTokenSelector = TokenSymbol | RawTokenSelector;
+/**
+ * The resolved token information after registry lookup.
+ *
+ * @remarks
+ * This is the result of resolving a `TokenSelector` against a chain.
+ * It always contains the locator and decimals, and optionally the symbol
+ * if the token was resolved from the registry.
+ */
+interface ResolvedToken {
+    /**
+     * The token symbol, if known.
+     * Present when resolved from registry, absent for raw locators.
+     */
+    readonly symbol?: string;
+    /**
+     * The number of decimal places for the token.
+     */
+    readonly decimals: number;
+    /**
+     * The chain-specific token locator (address, program ID, etc.).
+     */
+    readonly locator: string;
+}
+/**
+ * Interface for the token registry.
+ *
+ * @remarks
+ * The registry is the sole source of truth for token information.
+ * It supports both symbol-based and raw locator-based token selection.
+ *
+ * @example
+ * ```typescript
+ * import { createTokenRegistry } from '@core/tokens'
+ *
+ * // Create registry (includes built-in tokens like USDC)
+ * const registry = createTokenRegistry()
+ *
+ * // Resolve by symbol
+ * const usdc = registry.resolve('USDC', 'Ethereum')
+ * console.log(usdc.locator) // '0xa0b86991...'
+ *
+ * // Resolve raw locator
+ * const custom = registry.resolve({ locator: '0x...', decimals: 18 }, 'Ethereum')
+ * ```
+ */
+interface TokenRegistry {
+    /**
+     * Resolve a token selector to concrete token information for a chain.
+     *
+     * @param selector - The token to resolve. Accepts a symbol or raw locator.
+     * @param chainId - The chain identifier to resolve for.
+     * @returns The resolved token information.
+     * @throws When the token cannot be resolved (unknown symbol, missing decimals, etc.).
+     */
+    resolve(selector: RegistryTokenSelector, chainId: ChainIdentifier): ResolvedToken;
+    /**
+     * Resolve a token by chain-specific locator (address/program ID).
+     *
+     * @param address - The token locator to resolve.
+     * @param chainId - The chain identifier to resolve for.
+     * @returns The resolved token information.
+     * @throws When no registry token matches the locator on the chain.
+     */
+    resolveByAddress(address: string, chainId: ChainIdentifier): ResolvedToken;
+    /**
+     * Get a token definition by symbol.
+     *
+     * @param symbol - The token symbol (e.g., "USDC").
+     * @returns The token definition, or undefined if not found.
+     */
+    get(symbol: string): TokenDefinition | undefined;
+    /**
+     * Check if a symbol is registered.
+     *
+     * @param symbol - The token symbol to check.
+     * @returns True if the symbol is in the registry.
+     */
+    has(symbol: string): boolean;
+    /**
+     * Get all registered token symbols.
+     *
+     * @returns An array of registered symbol strings.
+     */
+    symbols(): string[];
+    /**
+     * Get all registered token definitions.
+     *
+     * @returns An array of all TokenDefinition objects in the registry.
+     */
+    entries(): TokenDefinition[];
+}
+
+/**
+ * Valid recoverability values for error handling strategies.
+ *
+ * - FATAL errors are thrown immediately (invalid inputs, insufficient funds)
+ * - RETRYABLE errors are returned when a flow fails to start but could work later
+ * - RESUMABLE errors are returned when a flow fails mid-execution but can be continued
+ */
+declare const RECOVERABILITY_VALUES: readonly ["RETRYABLE", "RESUMABLE", "FATAL"];
+/**
+ * Error handling strategy for different types of failures.
+ *
+ * - FATAL errors are thrown immediately (invalid inputs, insufficient funds)
+ * - RETRYABLE errors are returned when a flow fails to start but could work later
+ * - RESUMABLE errors are returned when a flow fails mid-execution but can be continued
+ */
+type Recoverability = (typeof RECOVERABILITY_VALUES)[number];
+/**
+ * Array of valid error type values for validation.
+ * Derived from ERROR_TYPES const object.
+ */
+declare const ERROR_TYPE_VALUES: ("INPUT" | "BALANCE" | "ONCHAIN" | "RPC" | "NETWORK" | "RATE_LIMIT" | "SERVICE" | "LIQUIDITY" | "UNKNOWN")[];
+/**
+ * Error type indicating the category of the error.
+ */
+type ErrorType = (typeof ERROR_TYPE_VALUES)[number];
+/**
+ * Structured error details with consistent properties for programmatic handling.
+ *
+ * This interface provides a standardized format for all errors in the
+ * App Kits system, enabling developers to handle different error
+ * types consistently and provide appropriate user feedback.
+ *
+ * @example
+ * ```typescript
+ * const error: ErrorDetails = {
+ *   code: 1001,
+ *   name: "INPUT_NETWORK_MISMATCH",
+ *   type: "INPUT",
+ *   recoverability: "FATAL",
+ *   message: "Source and destination networks must be different",
+ *   cause: {
+ *     trace: { sourceChain: "ethereum", destChain: "ethereum" }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const error: ErrorDetails = {
+ *   code: 9001,
+ *   name: "BALANCE_INSUFFICIENT_TOKEN",
+ *   type: "BALANCE",
+ *   recoverability: "FATAL",
+ *   message: "Insufficient USDC balance on Ethereum",
+ *   cause: {
+ *     trace: { token: "USDC", chain: "Ethereum" }
+ *   }
+ * }
+ * ```
+ */
+interface ErrorDetails {
+    /** Numeric identifier following standardized ranges (see error code registry) */
+    code: number;
+    /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
+    name: string;
+    /** Error category indicating where the error originated */
+    type: ErrorType;
+    /** Error handling strategy */
+    recoverability: Recoverability;
+    /** User-friendly explanation with context */
+    message: string;
+    /** Raw error details, context, or the original error that caused this one. */
+    cause?: {
+        /**
+         * Free-form error payload from the underlying system.
+         *
+         * The shape is **not uniform across error codes**: most codes set `trace`
+         * to the raw underlying error, while a few set a structured wrapper object
+         * `{ rawError, ...extras }` (e.g. `INPUT_AMOUNT_OUT_OF_RANGE` and
+         * `LIQUIDITY_INSUFFICIENT` add `minAmount` / `maxAmount` / `token`).
+         * Consumers must branch on `error.code` before reading structured fields off
+         * `trace`, and should treat the raw error as the fallback for all other codes.
+         */
+        trace?: unknown;
+    };
+}
+/**
+ * Simplified error information structure for logging and events.
+ *
+ * @remarks
+ * This lightweight type is used for error reporting in events, logs, and
+ * observability systems. It provides essential error context without the
+ * full ErrorDetails structure. Used across retry mechanisms, adapters,
+ * and other subsystems that need to record error information.
+ *
+ * @example
+ * ```typescript
+ * import { ErrorInfo } from '@core/errors'
+ *
+ * const info: ErrorInfo = {
+ *   name: 'NETWORK_TIMEOUT',
+ *   message: 'Request timed out after 5000ms',
+ *   code: 3002
+ * }
+ * ```
+ */
+interface ErrorInfo {
+    /** Error name (e.g., 'TypeError', 'KitError', 'NETWORK_TIMEOUT'). */
+    name: string;
+    /** Error message describing what went wrong. */
+    message: string;
+    /** Optional error code if the error has one (e.g., KitError codes). */
+    code?: number;
+    /** Error category (e.g., INPUT, RPC, ONCHAIN, BALANCE, NETWORK, UNKNOWN). Only set for KitError instances. */
+    type?: string;
+}
+
+declare class KitError extends Error implements ErrorDetails {
+    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
+    readonly code: number;
+    /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
+    readonly name: string;
+    /** Error category indicating where the error originated */
+    readonly type: ErrorType;
+    /** Error handling strategy */
+    readonly recoverability: Recoverability;
+    /** Raw error details, context, or the original error that caused this one. */
+    readonly cause?: {
+        /** Free-form error payload from underlying system */
+        trace?: unknown;
+    };
+    /**
+     * Create a new KitError instance.
+     *
+     * @param details - The error details object containing all required properties.
+     * @throws \{TypeError\} When details parameter is missing or invalid.
+     */
+    constructor(details: ErrorDetails);
+}
+
+/**
+ * Structured fields that can be attached to log entries.
+ */
+type LogFields = Record<string, unknown>;
+/**
+ * Logger interface providing structured logging with child scoping.
+ *
+ * @remarks
+ * This interface defines a minimal, framework-agnostic logging contract.
+ * The underlying implementation uses pino for transport handling (console,
+ * file, remote, JSON, pretty, etc.) but consumers only interact with this
+ * stable interface.
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from '@core/runtime'
+ *
+ * const logger = createLogger({ level: 'debug' })
+ *
+ * // Simple message
+ * logger.info('Server started')
+ *
+ * // Message with structured fields
+ * logger.info('Request received', { method: 'POST', path: '/api/transfer' })
+ *
+ * // Create child logger with context
+ * const requestLogger = logger.child({ requestId: 'abc-123' })
+ * requestLogger.debug('Processing transfer')
+ * // Output includes: requestId in all subsequent logs
+ * ```
+ */
+interface Logger {
+    /**
+     * Log a debug-level message.
+     * @param message - The log message.
+     * @param fields - Optional structured fields.
+     * @returns void
+     */
+    debug(message: string, fields?: LogFields): void;
+    /**
+     * Log an info-level message.
+     * @param message - The log message.
+     * @param fields - Optional structured fields.
+     * @returns void
+     */
+    info(message: string, fields?: LogFields): void;
+    /**
+     * Log a warning-level message.
+     * @param message - The log message.
+     * @param fields - Optional structured fields.
+     * @returns void
+     */
+    warn(message: string, fields?: LogFields): void;
+    /**
+     * Log an error-level message.
+     * @param message - The log message.
+     * @param fields - Optional structured fields.
+     * @returns void
+     */
+    error(message: string, fields?: LogFields): void;
+    /**
+     * Create a child logger with additional contextual bindings.
+     *
+     * @param tags - Key-value pairs to add to the child logger's context.
+     *   Undefined values are filtered out automatically.
+     * @returns A new Logger instance with merged bindings.
+     *
+     * @example
+     * ```typescript
+     * const requestLogger = logger.child({ requestId: 'req-123' })
+     * const userLogger = requestLogger.child({ userId: 'user-456' })
+     * // All logs from userLogger include both requestId and userId
+     * ```
+     */
+    child(tags: LogFields): Logger;
+}
+
+/**
+ * Handler function for event subscriptions.
+ */
+type EventHandler = (event: Event) => void | Promise<void>;
+/**
+ * Event bus for publishing and subscribing to events.
+ *
+ * @remarks
+ * Supports wildcard topic subscriptions:
+ * - `*` matches exactly one segment
+ * - `**` matches zero or more segments
+ *
+ * @example
+ * ```typescript
+ * const bus = createEventBus()
+ *
+ * // Subscribe to all events
+ * bus.on((event) => console.log(event))
+ *
+ * // Subscribe to specific topic
+ * bus.on('tx.wait.started', (event) => console.log(event))
+ *
+ * // Subscribe with wildcard
+ * bus.on('tx.wait.*', (event) => console.log(event))
+ * bus.on('tx.**', (event) => console.log(event))
+ *
+ * // Emit events
+ * bus.emit({ name: 'tx.wait.started', data: { txId: '0x123' } })
+ * ```
+ */
+interface EventBus {
+    /**
+     * Emit an event to all matching subscribers.
+     *
+     * @param event - The event to emit.
+     * @remarks
+     * Synchronous and never throws. Handler errors are isolated.
+     */
+    emit(event: Event): void;
+    /**
+     * Create a child event bus with scoped tags.
+     *
+     * @param tags - Tags to merge into all emitted events.
+     * @returns A new EventBus with merged tags.
+     */
+    child(tags: Tags): EventBus;
+    /**
+     * Subscribe to all events.
+     *
+     * @param handler - Function called for every event.
+     * @returns Unsubscribe function.
+     */
+    on(handler: EventHandler): () => void;
+    /**
+     * Subscribe to events matching a pattern.
+     *
+     * @param pattern - Topic pattern (supports `*` and `**` wildcards).
+     * @param handler - Function called for matching events.
+     * @returns Unsubscribe function.
+     *
+     * @remarks
+     * Wildcard semantics:
+     * - `*` matches exactly one segment (no dots)
+     * - `**` matches zero or more segments (only valid at end)
+     *
+     * @example
+     * ```typescript
+     * bus.on('*', handler)             // matches 'tx', 'user' (single segment only)
+     * bus.on('tx.wait.*', handler)     // matches tx.wait.started, tx.wait.failed
+     * bus.on('tx.wait.**', handler)    // matches tx.wait, tx.wait.started, tx.wait.foo.bar
+     * bus.on('**', handler)            // matches all events
+     * ```
+     */
+    on(pattern: string, handler: EventHandler): () => void;
+}
+
+/**
+ * Lifecycle event types and constants for pipeline phase tracking.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Terminal state of a lifecycle phase.
+ *
+ * @remarks
+ * Exported as a discriminated union so typed consumers of the event
+ * stream (agents, dashboards, test assertions) can exhaustively switch
+ * on phase outcomes instead of string-comparing event names.
+ *
+ * @remarks
+ * Carried on every lifecycle event's `data.status` (see
+ * {@link LifecycleEventData}) so consumers can switch on the outcome
+ * without re-deriving it from the event name.
+ *
+ * @example
+ * ```typescript
+ * import type { LifecycleEventData } from '@core/runtime'
+ *
+ * function handle(data: LifecycleEventData) {
+ *   switch (data.status) {
+ *     case 'started':   return // ...
+ *     case 'succeeded': return // ...
+ *     case 'failed':    return // ...
+ *   }
+ * }
+ * ```
+ */
+type OperationPhaseStatus = 'started' | 'succeeded' | 'failed';
+/**
+ * Data payload for lifecycle events.
+ *
+ * @remarks
+ * These events are emitted by pipeline middleware to track phase execution.
+ * Field availability by event:
+ * - `op.phase.started`: `status`, `meta`, `inputSummary`
+ * - `op.phase.succeeded`: `status`, `meta`, `inputSummary`, `durationMs`
+ * - `op.phase.failed`: `status`, `meta`, `inputSummary`, `durationMs`, `error`
+ */
+interface LifecycleEventData {
+    /**
+     * Terminal status of the phase, mirroring the {@link OperationPhaseStatus}
+     * discriminant carried by the event name. Present on every lifecycle
+     * event so typed consumers can `switch (data.status)` without parsing
+     * the event name.
+     */
+    status: OperationPhaseStatus;
+    /** Metadata from the pipeline context. */
+    meta?: Record<string, unknown> | undefined;
+    /** Shallow summary of input (type + keys) to avoid PII exposure. */
+    inputSummary?: {
+        type: string;
+        keys?: string[];
+    } | undefined;
+    /** Duration of the phase in milliseconds (only for succeeded/failed). */
+    durationMs?: number;
+    /** Error information (only for failed events). */
+    error?: ErrorInfo | undefined;
+}
+
+/**
+ * Augmentable event type registry for the App Kits ecosystem.
+ *
+ * @remarks
+ * This module provides a type-safe event system using TypeScript's
+ * module augmentation pattern. Packages can extend `KitEventMap`
+ * to register their own event types.
+ *
+ * **How to Augment:**
+ *
+ * Other packages can add their own event types by augmenting the
+ * `KitEventMap` interface:
+ *
+ * ```typescript
+ * // In your package's types file (e.g., my-package/src/types.ts)
+ * declare module '@core/runtime' {
+ *   interface KitEventMap {
+ *     'tx.wait.started': { txId: string }
+ *     'tx.wait.completed': { txId: string; confirmations: number }
+ *     'tx.wait.failed': { txId: string; error: string }
+ *   }
+ * }
+ * ```
+ *
+ * After augmentation, the event system will be fully typed:
+ *
+ * ```typescript
+ * // Type-safe event emission
+ * emit('tx.wait.started', { txId: '0x123' })  // ✓ OK
+ * emit('tx.wait.started', { wrong: 'field' }) // ✗ Type error
+ * emit('unknown.event', {})                    // ✗ Type error (if strict)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // bridge-kit/src/events.ts
+ * declare module '@core/runtime' {
+ *   interface KitEventMap {
+ *     'bridge.transfer.initiated': {
+ *       sourceChain: string
+ *       destChain: string
+ *       amount: string
+ *     }
+ *     'bridge.transfer.completed': {
+ *       txHash: string
+ *       duration: number
+ *     }
+ *   }
+ * }
+ * ```
+ */
+/**
+ * The core event map interface for module augmentation.
+ *
+ * @remarks
+ * This interface pre-registers the lifecycle events that are always
+ * emitted by the pipeline middleware. Packages can extend it via
+ * TypeScript's declaration merging to register additional event types.
+ *
+ * **Pre-registered events:**
+ * - `op.phase.started` - Emitted when a pipeline phase begins
+ * - `op.phase.succeeded` - Emitted when a pipeline phase completes successfully
+ * - `op.phase.failed` - Emitted when a pipeline phase throws an error
+ *
+ * @example
+ * ```typescript
+ * // Add your own events via module augmentation
+ * declare module '@core/runtime' {
+ *   interface KitEventMap {
+ *     'my.custom.event': { payload: string }
+ *   }
+ * }
+ * ```
+ */
+interface KitEventMap {
+    'op.phase.started': LifecycleEventData;
+    'op.phase.succeeded': LifecycleEventData;
+    'op.phase.failed': LifecycleEventData;
+}
+/**
+ * Generic event map type for event-related constraints.
+ *
+ * @remarks
+ * Use this when you need to accept any event map without requiring
+ * the specific `KitEventMap` augmentations.
+ *
+ * Uses `any` to accept both interface and type declarations.
+ * `unknown` would reject interfaces without index signatures.
+ */
+type EventMap = Record<string, any>;
+
+/**
+ * Type-level event pattern matching utilities.
+ *
+ * @remarks
+ * These types provide compile-time pattern matching for event keys,
+ * mirroring the runtime matcher semantics:
+ * - Delimiter: `.`
+ * - `*` matches exactly one segment
+ * - `**` matches zero or more segments (only valid as last segment)
+ * - Exact matching otherwise
+ * - Invalid patterns (empty segments, `**` not last) yield `never`
+ *
+ * See `matching.test-d.ts` for type-level tests.
+ */
+
+/**
+ * Extract string keys from an event map.
+ *
+ * @typeParam M - The event map type.
+ * @returns Union of string keys from the map.
+ */
+type Keys<M extends EventMap> = Extract<keyof M, string>;
+/**
+ * Filter keys that match a pattern.
+ *
+ * @typeParam K - Union of string keys to filter.
+ * @typeParam P - Pattern to match against.
+ * @returns Union of keys that match the pattern, or `never` if pattern is invalid.
+ *
+ * @example
+ * ```typescript
+ * type Events = {
+ *   'tx.wait.started': { txId: string }
+ *   'tx.wait.failed': { error: string }
+ *   'tx.send.completed': { hash: string }
+ * }
+ *
+ * // Match single segment wildcard
+ * type WaitEvents = MatchKeys<keyof Events, 'tx.wait.*'>
+ * // = 'tx.wait.started' | 'tx.wait.failed'
+ *
+ * // Match multi-segment wildcard
+ * type AllTxEvents = MatchKeys<keyof Events, 'tx.**'>
+ * // = 'tx.wait.started' | 'tx.wait.failed' | 'tx.send.completed'
+ *
+ * // Match all events
+ * type All = MatchKeys<keyof Events, '**'>
+ * // = keyof Events
+ * ```
+ */
+type MatchKeys<K extends string, P extends string> = ParsePattern<P> extends never ? never : ParsePattern<P> extends infer PSegs extends string[] ? K extends unknown ? MatchKey<K, PSegs> : never : never;
+/**
+ * Split a string by '.' delimiter into a tuple of segments.
+ * Returns `never` if any segment is empty (handles `.a`, `a.`, `a..b`).
+ */
+type SplitDot<S extends string> = S extends '' ? [] : S extends `${infer Head}.${infer Tail}` ? Head extends '' ? never : Tail extends '' ? never : SplitDot<Tail> extends infer Rest ? Rest extends never ? never : Rest extends string[] ? [Head, ...Rest] : never : never : [S];
+/**
+ * Validate that `**` only appears as the last segment (or is the entire pattern).
+ * Returns `true` if valid, `false` if invalid.
+ */
+type ValidateGlob<Segs extends string[]> = Segs extends [] ? true : Segs extends [infer Head extends string, ...infer Tail extends string[]] ? Head extends '**' ? Tail extends [] ? true : false : ValidateGlob<Tail> : true;
+/**
+ * Parse and validate a pattern string.
+ * Returns the segments tuple if valid, `never` if invalid.
+ */
+type ParsePattern<P extends string> = SplitDot<P> extends infer Segs ? Segs extends never ? never : Segs extends string[] ? ValidateGlob<Segs> extends true ? Segs : never : never : never;
+/**
+ * Match a single key against parsed pattern segments.
+ * Returns the key if it matches, `never` otherwise.
+ */
+type MatchKey<K extends string, PSegs extends string[]> = SplitDot<K> extends infer KSegs ? KSegs extends never ? never : KSegs extends string[] ? MatchSegments<KSegs, PSegs> extends true ? K : never : never : never;
+/**
+ * Recursively match key segments against pattern segments.
+ *
+ * Rules:
+ * - If pattern exhausted: key must also be exhausted
+ * - If pattern head is `**`: match (since it's validated to be last)
+ * - If pattern head is `*`: consume one key segment
+ * - Otherwise: exact segment match required
+ */
+type MatchSegments<KSegs extends string[], PSegs extends string[]> = PSegs extends [] ? KSegs extends [] ? true : false : PSegs extends [infer PHead extends string, ...infer PTail extends string[]] ? PHead extends '**' ? true : KSegs extends [
+    infer KHead extends string,
+    ...infer KTail extends string[]
+] ? PHead extends '*' ? MatchSegments<KTail, PTail> : PHead extends KHead ? MatchSegments<KTail, PTail> : false : false : false;
+
+/**
+ * Type-safe wrapper for the untyped EventBus.
+ *
+ * @remarks
+ * This module provides compile-time type safety for event emission
+ * and subscription while maintaining zero runtime overhead.
+ */
+
+/**
+ * A strongly-typed event with known name and data types.
+ *
+ * @typeParam Name - The event name literal type.
+ * @typeParam Data - The event payload type.
+ */
+type TypedEvent<Name extends string, Data> = Omit<Event, 'name' | 'data'> & {
+    name: Name;
+    data: Data;
+};
+/**
+ * Create a discriminated union of typed events from an event map.
+ *
+ * @typeParam M - The event map.
+ * @typeParam K - The keys to include (defaults to all keys).
+ *
+ * @remarks
+ * This creates a proper discriminated union where TypeScript can narrow
+ * the `data` type based on checking the `name` field.
+ */
+type EventUnion<M extends EventMap, K extends Keys<M> = Keys<M>> = {
+    [N in K]: TypedEvent<N, M[N]>;
+}[K];
+/**
+ * Handler for typed events.
+ */
+type TypedEventHandler<E> = (event: E) => void | Promise<void>;
+
+/**
+ * Metrics type definitions for the Runtime module.
+ *
+ * @remarks
+ * Define a minimal, pluggable metrics interface that can be backed by any
+ * metrics library (hot-shots, dd-trace, prom-client, etc.).
+ *
+ * The interface supports:
+ * - Counters for monotonically increasing values
+ * - Histograms for distributions (latencies, sizes)
+ * - Timers as a convenience wrapper for timing operations
+ * - Label scoping via `child()` for dimensional metrics
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * metrics.counter('requests.total').inc({ method: 'POST' })
+ * metrics.histogram('request.duration').observe({ status: 200 }, 42.5)
+ *
+ * // Timer convenience
+ * const stop = metrics.timer('db.query').start({ table: 'users' })
+ * await query()
+ * stop() // Records duration automatically
+ *
+ * // Scoping adds base labels to all metrics
+ * const scoped = metrics.child({ service: 'bridge', env: 'prod' })
+ * scoped.counter('transfers').inc() // Includes service + env labels
+ * ```
+ */
+/**
+ * Labels for dimensional metrics.
+ *
+ * @remarks
+ * Labels (also called tags in some systems) are key-value pairs that
+ * provide dimensions for metric aggregation and filtering.
+ * Values must be primitives for serialization compatibility.
+ *
+ * @example
+ * ```typescript
+ * const labels: MetricLabels = {
+ *   chain: 'Ethereum',
+ *   status: 'success',
+ *   retries: 3,
+ *   cached: true,
+ * }
+ * ```
+ */
+type MetricLabels = Record<string, string | number | boolean>;
+/**
+ * A counter metric for monotonically increasing values.
+ *
+ * @remarks
+ * Use counters for values that only go up: request counts, error counts,
+ * bytes processed, etc. The value resets only on process restart.
+ *
+ * @see {@link Metrics.counter} to obtain a Counter instance.
+ *
+ * @example
+ * ```typescript
+ * const counter = metrics.counter('http.requests')
+ *
+ * // Increment by 1
+ * counter.inc()
+ * counter.inc({ method: 'GET' })
+ *
+ * // Increment by specific value
+ * counter.inc(5)
+ * counter.inc({ method: 'POST' }, 3)
+ * ```
+ */
+interface Counter {
+    /**
+     * Increment the counter value.
+     *
+     * @param labelsOrValue - The labels object or increment value.
+     *   When a number, increments by that amount with no labels.
+     *   When an object, uses as labels with optional value in second param.
+     * @param value - The increment value when first arg is labels. Default: 1.
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * counter.inc()                          // +1, no labels
+     * counter.inc(5)                         // +5, no labels
+     * counter.inc({ method: 'GET' })         // +1, with labels
+     * counter.inc({ method: 'POST' }, 3)     // +3, with labels
+     * ```
+     */
+    inc(labelsOrValue?: MetricLabels | number, value?: number): void;
+}
+/**
+ * A histogram metric for recording value distributions.
+ *
+ * @remarks
+ * Use histograms for values that vary and need percentile analysis:
+ * request durations, response sizes, queue depths, etc.
+ *
+ * @see {@link Metrics.histogram} to obtain a Histogram instance.
+ *
+ * @example
+ * ```typescript
+ * const histogram = metrics.histogram('http.duration')
+ *
+ * // Record a value
+ * histogram.observe(42.5)
+ * histogram.observe({ status: 200 }, 42.5)
+ * ```
+ */
+interface Histogram {
+    /**
+     * Record an observation value.
+     *
+     * @param labelsOrValue - The labels object or observed value.
+     *   When a number, records that value with no labels.
+     *   When an object, uses as labels with value in second param.
+     * @param value - The observed value when first arg is labels. Default: 0.
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * histogram.observe(42.5)                    // Value only
+     * histogram.observe({ status: 200 }, 42.5)  // With labels
+     * ```
+     */
+    observe(labelsOrValue?: MetricLabels | number, value?: number): void;
+}
+/**
+ * A timer metric for measuring operation durations.
+ *
+ * @remarks
+ * Timers provide a convenience wrapper that automatically records durations
+ * to an underlying histogram. Call `start()` to begin timing and the
+ * returned function to stop and record the elapsed time in milliseconds.
+ *
+ * @see {@link Metrics.timer} to obtain a Timer instance.
+ *
+ * @example
+ * ```typescript
+ * const timer = metrics.timer('db.query')
+ *
+ * // Start timing
+ * const stop = timer.start({ table: 'users' })
+ * await performQuery()
+ * stop() // Records duration in milliseconds
+ * ```
+ */
+interface Timer {
+    /**
+     * Start timing an operation.
+     *
+     * @param labels - The optional labels for the timing observation.
+     * @returns A stop function that records the duration when called.
+     *
+     * @example
+     * ```typescript
+     * const stop = timer.start({ operation: 'fetch' })
+     * await fetchData()
+     * stop() // Records elapsed time
+     * ```
+     */
+    start(labels?: MetricLabels): () => void;
+}
+/**
+ * Main metrics interface for instrumentation.
+ *
+ * @remarks
+ * This interface is designed to be thin and pluggable. Implementations
+ * can delegate to any metrics library:
+ *
+ * - **hot-shots**: StatsD/DogStatsD client
+ * - **dd-trace**: Datadog APM
+ * - **prom-client**: Prometheus
+ * - **opentelemetry-js**: OpenTelemetry
+ *
+ * The `child()` method creates a scoped metrics instance that automatically
+ * includes base labels on all metric operations.
+ *
+ * @see {@link createMockMetrics} for testing.
+ * @see {@link noopMetrics} for a no-op implementation.
+ *
+ * @example
+ * ```typescript
+ * // Create a scoped metrics instance
+ * const appMetrics = metrics.child({
+ *   service: 'app-kit',
+ *   version: '1.0.0',
+ * })
+ *
+ * // All metrics include service + version labels
+ * appMetrics.counter('transfers.initiated').inc({ chain: 'ethereum' })
+ * ```
+ */
+interface Metrics {
+    /**
+     * Get or create a counter metric by name.
+     *
+     * @param name - The metric name (e.g., 'http.requests.total').
+     * @returns A Counter instance for the given name.
+     *
+     * @example
+     * ```typescript
+     * const counter = metrics.counter('requests.total')
+     * counter.inc({ method: 'GET' })
+     * ```
+     */
+    counter(name: string): Counter;
+    /**
+     * Get or create a histogram metric by name.
+     *
+     * @param name - The metric name (e.g., 'http.request.duration').
+     * @returns A Histogram instance for the given name.
+     *
+     * @example
+     * ```typescript
+     * const histogram = metrics.histogram('request.duration')
+     * histogram.observe({ status: 200 }, 42.5)
+     * ```
+     */
+    histogram(name: string): Histogram;
+    /**
+     * Get or create a timer metric by name.
+     *
+     * @param name - The metric name (e.g., 'db.query.duration').
+     * @returns A Timer instance for the given name.
+     *
+     * @example
+     * ```typescript
+     * const stop = metrics.timer('db.query').start()
+     * await query()
+     * stop()
+     * ```
+     */
+    timer(name: string): Timer;
+    /**
+     * Create a child metrics instance with scoped labels.
+     *
+     * @param labels - The base labels to include on all metric operations.
+     * @returns A new Metrics instance with merged labels.
+     *
+     * @remarks
+     * Labels from the child are merged with any labels passed to individual
+     * metric operations. Call-site labels take precedence for the same key.
+     *
+     * @example
+     * ```typescript
+     * const scoped = metrics.child({ chain: 'Ethereum' })
+     * scoped.counter('transfers').inc({ status: 'success' })
+     * // Labels: { chain: 'Ethereum', status: 'success' }
+     * ```
+     */
+    child(labels: MetricLabels): Metrics;
+}
+
+/**
+ * Core type definitions for the runtime package.
+ *
+ * @remarks
+ * This module defines the foundational types used throughout the SDK:
+ *
+ * - {@link Runtime} - Complete runtime with all services (clock, logger, metrics, events)
+ * - {@link ExecutionContext} - Context for middleware with observability surface
+ * - {@link Clock}, {@link Tags}, {@link Event} - Supporting types
+ *
+ * **Naming Convention**
+ *
+ * | Input Type | Resolved Type | Description |
+ * |------------|---------------|-------------|
+ * | `Partial<Runtime>` | `Runtime` | Runtime services |
+ * | `OperationMeta` | `OperationContext` | WHAT - operation target |
+ * | `InvocationMeta` | `InvocationContext` | WHO/HOW - call chain |
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Clock interface for time operations.
+ *
+ * @remarks
+ * Abstracting time allows tests to control timing without real delays.
+ * Production code uses {@link defaultClock}, tests use mock implementations.
+ *
+ * @example
+ * ```typescript
+ * import { defaultClock, type Clock } from '@core/runtime'
+ *
+ * const start = defaultClock.now()
+ * // ... do work ...
+ * const elapsed = defaultClock.since(start)
+ * ```
+ */
+interface Clock {
+    /**
+     * Return the current timestamp in milliseconds since Unix epoch.
+     *
+     * @returns Current time in milliseconds.
+     */
+    now(): number;
+    /**
+     * Calculate elapsed time since a given timestamp.
+     *
+     * @param start - The start timestamp in milliseconds.
+     * @returns Elapsed time in milliseconds (`now() - start`).
+     */
+    since: (start: number) => number;
+}
+/**
+ * Contextual metadata tags for logging and metrics.
+ *
+ * @remarks
+ * Tags are key-value pairs attached to log entries and metrics.
+ * Values can be primitives or undefined (undefined values are filtered out).
+ *
+ * Common tags include:
+ * - `opId` - Operation identifier for correlation
+ * - `chain` - Blockchain network name
+ * - `phase` - Current pipeline phase
+ *
+ * @example
+ * ```typescript
+ * import type { Tags } from '@core/runtime'
+ *
+ * const tags: Tags = {
+ *   opId: 'op-abc123',
+ *   chain: 'Ethereum',
+ *   phase: 'validate',
+ *   optional: undefined, // Will be filtered out
+ * }
+ * ```
+ */
+type Tags = Record<string, string | number | boolean | undefined>;
+/**
+ * A structured event emitted by the runtime.
+ *
+ * @remarks
+ * Events provide a standardized way to capture lifecycle moments,
+ * actions, and state changes throughout the SDK.
+ */
+interface Event {
+    /** The event name/identifier. */
+    name: string;
+    /** Log level for the event. */
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    /** Timestamp (epoch ms) when the event occurred. */
+    at?: number;
+    /** Contextual tags for filtering/categorization. */
+    tags?: Tags;
+    /** Arbitrary payload data associated with the event. */
+    data?: unknown;
+}
+/**
+ * Complete runtime with all services guaranteed present.
+ *
+ * @remarks
+ * The runtime is the container for all cross-cutting concerns: logging,
+ * timing, events, and metrics. All services are guaranteed to be available.
+ *
+ * **Creating a Runtime**
+ *
+ * Use {@link createRuntime} to create a fully-configured runtime:
+ * ```typescript
+ * import { createRuntime } from '@core/runtime'
+ *
+ * const runtime = createRuntime()
+ * runtime.logger.info('Hello')
+ * runtime.metrics.counter('requests').inc()
+ * ```
+ *
+ * **Partial Runtime Input**
+ *
+ * When accepting runtime configuration as input, use `Partial<Runtime>`:
+ * ```typescript
+ * function myFunction(options: { runtime?: Partial<Runtime> }) {
+ *   const runtime = createRuntime(options.runtime)
+ *   // ...
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createRuntime, type Runtime } from '@core/runtime'
+ *
+ * const runtime: Runtime = createRuntime()
+ *
+ * // All services are guaranteed present
+ * runtime.logger.info('Processing request')
+ * runtime.metrics.counter('requests').inc()
+ * runtime.events.emit({ name: 'request.received' })
+ * const now = runtime.clock.now()
+ * ```
+ */
+interface Runtime {
+    /**
+     * Clock for time operations.
+     *
+     * @remarks
+     * Provides the current timestamp. Use {@link defaultClock} for production
+     * or custom clocks for deterministic testing.
+     */
+    clock: Clock;
+    /**
+     * Logger for structured logging.
+     *
+     * @remarks
+     * Provides debug, info, warn, error methods with structured data support.
+     */
+    logger: Logger;
+    /**
+     * Metrics collector for observability.
+     *
+     * @remarks
+     * Provides counters, histograms, and timers for application metrics.
+     */
+    metrics: Metrics;
+    /**
+     * Event bus for pub/sub events.
+     *
+     * @remarks
+     * Enables decoupled event emission and subscription across the SDK.
+     */
+    events: EventBus;
+}
+/**
+ * A component in the call chain.
+ *
+ * @remarks
+ * Each caller identifies itself with a type (app, kit, provider, adapter)
+ * and a name/version. This enables proper attribution in logs, metrics, and traces.
+ *
+ * @example
+ * ```typescript
+ * import type { Caller } from '@core/runtime'
+ *
+ * const appCaller: Caller = { type: 'app', name: 'MyDApp', version: '1.0.0' }
+ * const kitCaller: Caller = { type: 'kit', name: 'BridgeKit', version: '2.0.0' }
+ * ```
+ */
+interface Caller {
+    /**
+     * Type of component in the call hierarchy.
+     *
+     * @remarks
+     * Common types: `app`, `kit`, `provider`, `adapter`
+     */
+    readonly type: string;
+    /** Name of the component (e.g., 'BridgeKit', 'cctp-v2'). */
+    readonly name: string;
+    /** Version of the component (e.g., '1.0.0'). */
+    readonly version?: string | undefined;
+}
+/**
+ * User input for invocation metadata.
+ *
+ * @remarks
+ * Defines **WHO** called and **HOW** to observe: trace correlation, runtime override,
+ * and caller chain. This is the user-facing input type, resolved to `InvocationContext`.
+ *
+ * Passed as the optional invocation argument to actions and primitives.
+ *
+ * @example
+ * ```typescript
+ * import type { InvocationMeta } from '@core/runtime'
+ *
+ * // Minimal - just traceId
+ * const meta: InvocationMeta = { traceId: 'abc-123' }
+ *
+ * // Full - with runtime override and caller chain
+ * const meta: InvocationMeta = {
+ *   traceId: 'abc-123',
+ *   runtime: myRuntime,
+ *   callers: [
+ *     { type: 'app', name: 'MyDApp', version: '1.0.0' },
+ *   ],
+ * }
+ * ```
+ */
+interface InvocationMeta {
+    /**
+     * Trace ID for distributed tracing correlation.
+     *
+     * @remarks
+     * If not provided, generated automatically.
+     */
+    readonly traceId?: string | undefined;
+    /**
+     * Runtime override (complete replacement).
+     *
+     * @remarks
+     * When provided, this runtime completely replaces the default runtime.
+     * Must be a complete Runtime instance (e.g., from `createRuntime()`).
+     * If not provided, the default runtime is used.
+     */
+    readonly runtime?: Runtime | undefined;
+    /**
+     * Token registry override (complete replacement).
+     *
+     * @remarks
+     * When provided, this registry completely replaces the default token registry.
+     * Enables kits to pass their token registry to adapters.
+     * If not provided, the default token registry is used.
+     */
+    readonly tokens?: TokenRegistry | undefined;
+    /**
+     * Call chain - each caller appends itself.
+     *
+     * @remarks
+     * Ordered from outermost (first) to innermost (last).
+     * Example: [app, kit, provider]
+     */
+    readonly callers?: readonly Caller[] | undefined;
+    /**
+     * Cooperative cancellation signal for the invocation.
+     *
+     * @remarks
+     * When provided, the signal is threaded onto the resolved
+     * {@link InvocationContext} so operations can forward it to
+     * cancellable work (e.g. `fetch`, timers, adapter calls). Optional and
+     * backwards-compatible: callers that do not support cancellation simply
+     * omit it. Aborting the signal is the caller's responsibility; the
+     * runtime only propagates it.
+     */
+    readonly signal?: AbortSignal | undefined;
+}
+
+/**
+ * Operation primitives.
+ *
+ * @remarks
+ * Operations are the unit of public surface a kit exposes. Each operation
+ * has a name, a parameter shape, an optional Zod schema, and a `run`
+ * function bound to a {@link KitContext}.
+ *
+ * The critical type-level concern here is preservation of per-operation
+ * parameter generics so that `AdapterContext`-driven conditional typing
+ * (notably {@link AddressField} narrowing on user-controlled vs.
+ * developer-controlled adapters) survives end-to-end through
+ * {@link createKit}'s method surface.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The bound, callable shape of a kit operation.
+ *
+ * @typeParam TParams - The operation's parameter shape.
+ * @typeParam TResult - The operation's result shape.
+ *
+ * @remarks
+ * Parameter generics are preserved on this type and on every container
+ * that holds it. Containers must avoid `KitOperation<unknown, unknown>`
+ * (generic erasure); use mapped types or `infer` instead.
+ */
+interface KitOperation<TParams = unknown, TResult = unknown> {
+    readonly name: string;
+    (params: TParams, invocation?: InvocationMeta): Promise<TResult>;
+}
+
+/**
+ * Kit event subscription surface, backed by `runtime.events`.
+ *
+ * @remarks
+ * kit-base no longer ships a bespoke event bus. Instead, the kit's
+ * public `on` / `off` are a thin, strongly-typed wrapper over the
+ * single `EventBus` owned by the kit's {@link Runtime}. This is the same
+ * bus the operation middleware (lifecycle/retry) and any providers /
+ * adapters in the call tree emit on — so one subscription observes the
+ * whole tree. Wildcard (`*`) and namespace (`**`) patterns work via the
+ * `EventBus` matcher.
+ *
+ * Mirrors `createAdapterEvents` from `@core/adapter-base` and augments
+ * the same `@core/runtime` `KitEventMap`. Kits register their event keys
+ * by augmenting that interface (see the package README).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Strongly-typed event subscription surface attached to every
+ * {@link Kit} and `CompositeKit` instance.
+ *
+ * @remarks
+ * `on` returns an unsubscribe function (modern pattern). `off` accepts
+ * the original handler reference and removes it for callers that prefer
+ * explicit cleanup. Both are typed against the augmentable
+ * {@link KitEventMap} from `@core/runtime`.
+ *
+ * @typeParam M - The event map (defaults to {@link KitEventMap}).
+ *
+ * @example
+ * ```ts
+ * // Subscribe to a specific event
+ * kit.on('kit.bridge.completed', (event) => console.log(event.data))
+ *
+ * // Subscribe with a namespace pattern
+ * kit.on('kit.bridge.*', (event) => console.log(event.name, event.data))
+ *
+ * // Subscribe to the runtime lifecycle events the middleware emits
+ * kit.on('op.phase.*', (event) => console.log(event.name))
+ *
+ * // Unsubscribe via the returned function or via off()
+ * const unsub = kit.on('kit.bridge.failed', handler)
+ * unsub()
+ * ```
+ */
+interface KitEventSubscription<M extends EventMap = KitEventMap> {
+    /**
+     * Subscribe to all events.
+     *
+     * @param handler - Handler receiving any event as a discriminated union.
+     * @returns Unsubscribe function.
+     */
+    on(handler: TypedEventHandler<EventUnion<M>>): () => void;
+    /**
+     * Subscribe to a specific event by exact name.
+     *
+     * @typeParam K - The event name literal.
+     * @param name - The event name.
+     * @param handler - Handler receiving the typed event.
+     * @returns Unsubscribe function.
+     */
+    on<K extends Keys<M>>(name: K, handler: TypedEventHandler<TypedEvent<K, M[K]>>): () => void;
+    /**
+     * Subscribe to events matching a glob pattern.
+     *
+     * @typeParam P - The pattern string (supports `*` and `**` wildcards).
+     * @param pattern - The pattern to match event names against.
+     * @param handler - Handler receiving matched events as a discriminated union.
+     * @returns Unsubscribe function.
+     */
+    on<P extends string>(pattern: P, handler: TypedEventHandler<EventUnion<M, MatchKeys<Keys<M>, P>>>): () => void;
+    /**
+     * Remove a previously registered handler.
+     *
+     * @param handler - The handler function reference to remove.
+     */
+    off(handler: TypedEventHandler<EventUnion<M>>): void;
+    /**
+     * Remove subscriptions registered with this handler reference.
+     *
+     * @remarks
+     * Removal is **by handler reference**, mirroring `createControllerEvents`
+     * and the `@core/adapter-base` event surfaces. The `name` is accepted
+     * for symmetry with {@link on}, but every subscription for `handler` is
+     * removed regardless of the event name it was registered under. Unknown
+     * handlers are a no-op.
+     *
+     * @typeParam K - The event name literal.
+     * @param name - The event name (accepted for symmetry; not used to
+     *   scope removal).
+     * @param handler - The handler function reference to remove.
+     */
+    off<K extends Keys<M>>(name: K, handler: TypedEventHandler<TypedEvent<K, M[K]>>): void;
+}
+
+/**
+ * Session wire format shared by the server kit (which mints sessions)
+ * and the client kit (which consumes them to launch the widget).
+ *
+ * @remarks
+ * The server kit speaks to `wallets-api` and unwraps its envelope into
+ * the shape exported below. The same shape is what the client kit
+ * consumes via `onrampKit.mountIframe({ session, container })` /
+ * `onrampKit.openWindow({ session })`, so a host application can pass
+ * the server result through verbatim — no manual mapping.
+ *
+ * @packageDocumentation
+ */
+/**
+ * One session as returned by the Onramp session endpoint
+ * (`POST /v1/stablecoinKits/sessions`), after the server kit unwraps
+ * the `{ data }` envelope.
+ *
+ * @remarks
+ * This is a **plain type**, not a runtime schema. The kit does not
+ * validate the session response against a closed shape — an additive
+ * change to the Onramp API (a new field, a new optional) must never
+ * break minting. The index signature keeps the type tolerant of extra
+ * fields on the wire. Note that `createSession` applies an outbound
+ * allow-list before returning: only the modeled fields below cross the
+ * server→browser trust boundary, so unmodeled upstream fields are
+ * dropped rather than forwarded.
+ *
+ * Field-by-field rationale:
+ *
+ * - `sessionId` — opaque, server-issued identifier; surfaced on every
+ *   widget event for cross-side correlation.
+ * - `sessionToken` — short-lived bearer credential the widget URL
+ *   embeds. Never sent back by the client; it is redeemed inside the
+ *   widget origin only.
+ * - `widgetUrl` — fully composed launch URL (origin + path + token +
+ *   `destinationWallet`). The server kit prefers to compose this itself
+ *   so the client kit has no exposure to the widget origin. The client
+ *   still accepts a bare `sessionToken` and composes a URL locally as a
+ *   fallback. `getOnrampUrl` is the single place that enforces the
+ *   https-scheme / origin-pin safety checks before the URL reaches the
+ *   DOM — that is a security boundary, not response validation.
+ * - `destinationWallet` — the wallet that receives funds. The widget
+ *   requires it as a launch query param, so the server kit echoes the
+ *   `destinationAddress` it was minted with here (and bakes it into
+ *   `widgetUrl`). Used by the client fallback path when it has to
+ *   compose the URL from a bare `sessionToken`.
+ * - `expiresAt` — RFC 3339 timestamp. The client refuses to launch an
+ *   expired session and throws an `INPUT` `KitError` so the host can
+ *   re-mint.
+ * - `traceId` — the trace id the server stamped when minting. Echoed
+ *   back so the client can tag widget events with the same id.
+ */
+interface OnrampSession {
+    /**
+     * Opaque server-issued session identifier.
+     *
+     * @remarks
+     * Surfaced on every widget event for cross-side correlation.
+     */
+    readonly sessionId: string;
+    /**
+     * Short-lived bearer credential the widget URL embeds.
+     *
+     * @remarks
+     * Redeemed inside the widget origin only — never sent back by the
+     * client kit.
+     */
+    readonly sessionToken: string;
+    /**
+     * Fully composed launch URL (origin + path + token +
+     * `destinationWallet`).
+     *
+     * @remarks
+     * The server kit prefers to compose this itself; the client falls
+     * back to composing locally from `sessionToken` when absent.
+     */
+    readonly widgetUrl?: string;
+    /**
+     * Wallet address that will receive funds at the end of the onramp
+     * flow.
+     *
+     * @remarks
+     * Echoed verbatim from the `destinationAddress` the server kit
+     * minted with. Used by the client kit's URL-composition fallback
+     * when `widgetUrl` is absent.
+     */
+    readonly destinationWallet?: string;
+    /**
+     * RFC 3339 expiry timestamp.
+     *
+     * @remarks
+     * The client refuses to launch an expired session and throws an
+     * `INPUT` `KitError` so the host can re-mint.
+     */
+    readonly expiresAt: string;
+    /**
+     * Trace identifier stamped by the server kit at minting time.
+     *
+     * @remarks
+     * Echoed back so the client can tag widget events with the same
+     * id.
+     */
+    readonly traceId?: string;
+    /**
+     * Index signature keeping the type tolerant of additive fields.
+     *
+     * @remarks
+     * The kit does not assert a closed shape, so the type accepts extra
+     * fields. At runtime, however, `createSession` rebuilds the result
+     * from an allow-list of the modeled fields above and does **not**
+     * forward unmodeled upstream fields across the server→browser
+     * boundary.
+     */
+    readonly [key: string]: unknown;
+}
+/**
+ * Session shape always returned by `onrampServerKit.createSession()`.
+ *
+ * @remarks
+ * The server kit normalises {@link OnrampSession} so that `widgetUrl`
+ * and `traceId` are guaranteed to be populated by the time the host
+ * passes the session through to the client. Use this alias when
+ * declaring SSR / serializer contracts that round-trip the value
+ * unchanged.
+ */
+interface MintedOnrampSession extends OnrampSession {
+    /**
+     * Fully composed launch URL — guaranteed present.
+     */
+    readonly widgetUrl: string;
+    /**
+     * Trace identifier stamped by the server kit — guaranteed present.
+     */
+    readonly traceId: string;
+}
+
+/**
+ * Wire-format schema for the `createSession` request body.
+ *
+ * @remarks
+ * Lives in the shared `protocol/` subtree so both the server kit (which
+ * validates inbound parameters before calling wallets-api) and the
+ * client kit (which POSTs the same shape to a host-owned session
+ * endpoint via {@link fetchOnrampSession}) speak the exact same
+ * contract.
+ *
+ * Validation is intentionally conservative: only the fields the kit
+ * actually consumes (or rejects on shape grounds) are checked. Free-
+ * form fields like `metadata` pass through so wallets-api can layer
+ * its own validation on top without the SDK lagging behind.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Zod schema for {@link OnrampSessionRequest}.
+ */
+declare const onrampSessionRequestSchema: z.ZodObject<{
+    appUserId: z.ZodString;
+    destinationAddress: z.ZodString;
+    destinationChain: z.ZodOptional<z.ZodString>;
+    amount: z.ZodOptional<z.ZodString>;
+    currency: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    assets: z.ZodOptional<z.ZodObject<{
+        tokens: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        chains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        pairs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            token: z.ZodString;
+            chain: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            token: string;
+            chain: string;
+        }, {
+            token: string;
+            chain: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        tokens?: string[] | undefined;
+        chains?: string[] | undefined;
+        pairs?: {
+            token: string;
+            chain: string;
+        }[] | undefined;
+    }, {
+        tokens?: string[] | undefined;
+        chains?: string[] | undefined;
+        pairs?: {
+            token: string;
+            chain: string;
+        }[] | undefined;
+    }>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    appUserId: string;
+    destinationAddress: string;
+    destinationChain?: string | undefined;
+    amount?: string | undefined;
+    currency?: string | undefined;
+    email?: string | undefined;
+    assets?: {
+        tokens?: string[] | undefined;
+        chains?: string[] | undefined;
+        pairs?: {
+            token: string;
+            chain: string;
+        }[] | undefined;
+    } | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    appUserId: string;
+    destinationAddress: string;
+    destinationChain?: string | undefined;
+    amount?: string | undefined;
+    currency?: string | undefined;
+    email?: string | undefined;
+    assets?: {
+        tokens?: string[] | undefined;
+        chains?: string[] | undefined;
+        pairs?: {
+            token: string;
+            chain: string;
+        }[] | undefined;
+    } | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+/**
+ * The wire-format request body accepted by the onramp `createSession`
+ * operation.
+ *
+ * @remarks
+ * Shared between the server kit (`onrampServerKit.createSession`) and
+ * the client-side REST fetcher (`fetchOnrampSession({ url, body })`).
+ *
+ * - `appUserId`: opaque host-controlled identifier (most hosts use their
+ *   internal primary key). Required so wallets-api can correlate a
+ *   session with the host's user record.
+ * - `destinationAddress`: wallet that receives funds at the end of the
+ *   onramp flow. The widget displays this as a confirmation step but
+ *   the SDK does not validate it on the client beyond
+ *   "non-empty string" — wallets-api owns chain-specific validation.
+ * - `destinationChain`: optional. Defaults to "Ethereum" inside
+ *   wallets-api. Pass to pre-select a chain in the widget.
+ * - `amount`, `currency`: optional pre-fills.
+ * - `email`: optional KYC routing hint.
+ * - `assets`: optional host-app scoping for the asset selector (which
+ *   token/chain pairs the widget offers). See {@link OnrampAssetSelection}.
+ *   Baked into the launch URL at mint time; never forwarded to wallets-api.
+ * - `metadata`: free-form passthrough — useful for re-stitching the
+ *   session back to the host's order ledger.
+ *
+ * Note: the embedding-domain allowlist entry (`referrerDomain`) is **not**
+ * part of this request. It is a server-only concern configured on
+ * {@link OnrampServerKitOptions.referrerDomain} so it can never be set from
+ * a client-submitted body.
+ */
+type OnrampSessionRequest = z.infer<typeof onrampSessionRequestSchema>;
+
+/**
+ * `createSession` type surface.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Parameters accepted by `onrampServerKit.createSession()`.
+ *
+ * @remarks
+ * - `appUserId`: opaque host-controlled identifier (most hosts use their
+ *   internal primary key). Required so wallets-api can correlate a
+ *   session with the host's user record.
+ * - `destinationAddress`: wallet that receives funds at the end of the
+ *   onramp flow. The widget displays this as a confirmation step but
+ *   the SDK does not validate it on the client beyond
+ *   "non-empty string" — wallets-api owns chain-specific validation.
+ * - `destinationChain`: optional. Defaults to "Ethereum" inside
+ *   wallets-api. Pass to pre-select a chain in the widget.
+ * - `amount`, `currency`: optional pre-fills.
+ * - `email`: optional KYC routing hint.
+ * - `metadata`: free-form passthrough — useful for re-stitching the
+ *   session back to the host's order ledger.
+ */
+type CreateSessionParams = OnrampSessionRequest;
+/**
+ * Strongly-typed handle to the `createSession` kit operation.
+ *
+ * @remarks
+ * Exposed as a public type so host applications can pass the operation
+ * around (e.g. dependency-injected into a route handler) without
+ * losing param/result inference.
+ */
+type CreateSessionOperation = KitOperation<CreateSessionParams, MintedOnrampSession>;
+
+/**
+ * Shared types for the onramp server kit factory and its operations.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options accepted by {@link createOnrampServerKit}.
+ *
+ * @remarks
+ * Apart from the credential, every field carries a sensible production
+ * default and is exposed strictly so test rigs and staging environments
+ * can override individual primitives without forking the SDK.
+ */
+interface OnrampServerKitOptions {
+    /**
+     * Long-lived API credential issued by Circle to the host
+     * application's server.
+     *
+     * @remarks
+     * Use the value exactly as issued by the Circle console. Keys look like
+     * `<ENV>_API_KEY:<keyId>:<keySecret>`. The kit sends it verbatim as a
+     * bearer token (`Authorization: Bearer <value>`), so do not strip or
+     * re-add the prefix.
+     *
+     * Must never be shipped to a browser. Use the resulting `sessionToken`
+     * client-side instead.
+     */
+    readonly apiKey: string;
+    /**
+     * Override the wallets-api base URL.
+     *
+     * @remarks
+     * Defaults to {@link DEFAULT_API_BASE_URL}. Override for staging
+     * environments or local emulators.
+     */
+    readonly baseUrl?: string | undefined;
+    /**
+     * Override the hosted onramp widget origin.
+     *
+     * @remarks
+     * Defaults to {@link DEFAULT_WIDGET_BASE_URL}. The server kit uses
+     * this to compose `OnrampSession.widgetUrl` when wallets-api does
+     * not return one. Override for staging environments.
+     */
+    readonly widgetBaseUrl?: string | undefined;
+    /**
+     * Bare hostname of the page that embeds the widget in an iframe, e.g.
+     * `'portal.arc.io'`. Forwarded to the proxy, which seals it into the
+     * session JWT and passes it to Transak as the `referrerDomain` claim so
+     * the host page is authorized as a frame ancestor of Transak's inner
+     * iframe (its `frame-ancestors` CSP).
+     *
+     * @remarks
+     * Set it whenever you embed the widget in an iframe on your own site;
+     * omit it when the widget runs as a top-level page or popup. Value
+     * rules:
+     *
+     * - Hostname only — no scheme, port, path, or wildcard. Correct:
+     *   `'portal.arc.io'`. Wrong: `'https://portal.arc.io'`,
+     *   `'portal.arc.io:443'`, `'portal.arc.io/buy'`, `'*.arc.io'`.
+     * - For a subdomain, pass the exact host the page is served from
+     *   (`'buy.arc.io'`), not the apex domain.
+     *
+     * This is a **server-only construction option**, not a per-session
+     * parameter, precisely so it is derived from your own trusted config
+     * (e.g. a per-environment constant) and can never be taken from a
+     * client-submitted session request or an `Origin`/`Referer` header — a
+     * client-supplied value would let a caller widen the frame-ancestor
+     * allowlist.
+     */
+    readonly referrerDomain?: string | undefined;
+    /**
+     * Per-request timeout in milliseconds for outbound HTTP calls.
+     *
+     * @remarks
+     * Defaults to {@link DEFAULT_REQUEST_TIMEOUT_MS} (15 s). Set to `0`
+     * to disable timeouts (not recommended outside tests).
+     */
+    readonly requestTimeoutMs?: number | undefined;
+    /**
+     * Override the `fetch` implementation used for outbound HTTP.
+     *
+     * @remarks
+     * Defaults to `globalThis.fetch`. Provide a custom function in
+     * environments without a global `fetch`, in tests, or when you want
+     * to thread Node's `undici` configuration explicitly.
+     */
+    readonly fetch?: typeof globalThis.fetch | undefined;
+    /**
+     * Optional extra HTTP headers merged onto every outbound request.
+     *
+     * @remarks
+     * Useful for routing labels, internal proxy auth, or experiment
+     * flags. The kit ignores reserved headers (`Authorization`,
+     * `Content-Type`, `Accept`) to keep the wire format predictable.
+     */
+    readonly extraHeaders?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * The fully-assembled server kit instance returned by
+ * {@link createOnrampServerKit}.
+ *
+ * @remarks
+ * The shape mirrors {@link Kit} from `@core/kit-base` — operation
+ * methods plus the {@link KitEventSubscription} `on` / `off` pair backed
+ * by the kit's runtime bus — but is hand-rolled so the public type stays
+ * narrow (just `createSession`) without leaking the broader
+ * operation-factory mapped-type machinery.
+ */
+interface OnrampServerKit extends KitEventSubscription {
+    /**
+     * Mint a short-lived session for the embedded onramp widget.
+     *
+     * @see {@link CreateSessionOperation}
+     */
+    readonly createSession: CreateSessionOperation;
+}
+
+/**
+ * Options accepted by {@link createSessionRouteHandler}.
+ */
+interface CreateSessionRouteHandlerOptions {
+    /**
+     * Authorize the inbound request before the session is minted.
+     *
+     * @remarks
+     * Receives the raw {@link Request}. The handler is **fail-closed**:
+     * only an explicit `true` or `undefined` (the "no opinion" return)
+     * allows the request through. Any other value — `false`, `null`,
+     * `0`, `''`, or an unexpected object from a plain-JS caller — short-
+     * circuits with a `401`. Throw a {@link KitError} to surface a
+     * custom status (see {@link createSessionRouteHandler} for the
+     * type → status map).
+     *
+     * Common patterns:
+     *
+     * - Read your own host session cookie and assert the user is logged
+     *   in.
+     * - Verify a CSRF token from the request headers.
+     * - Apply rate limiting per-user before incurring the wallets-api
+     *   round-trip.
+     *
+     * @example
+     * ```ts
+     * createSessionRouteHandler(server, {
+     *   authorize: async (request) => {
+     *     const session = await getHostSession(request)
+     *     return session?.user != null
+     *   },
+     * })
+     * ```
+     */
+    readonly authorize?: ((request: Request) => boolean | undefined | Promise<boolean | undefined>) | undefined;
+    /**
+     * Side-channel hook for logging / metrics on every failure path.
+     *
+     * @remarks
+     * Invoked with the original error (typed `unknown`) and the inbound
+     * {@link Request}. Errors thrown from this hook are swallowed to
+     * keep the response path deterministic; emit metrics here, do not
+     * mutate state.
+     *
+     * Return value is ignored. The handler still maps the error to an
+     * HTTP response in the usual way.
+     */
+    readonly onError?: ((error: unknown, request: Request) => void | Promise<void>) | undefined;
+}
+/**
+ * Fetch-API request handler returned by
+ * {@link createSessionRouteHandler}.
+ */
+type SessionRouteHandler = (request: Request) => Promise<Response>;
+/**
+ * Build a drop-in route handler that wraps
+ * {@link OnrampServerKit.createSession}.
+ *
+ * @remarks
+ * **Security — read before deploying.** This handler is
+ * **unauthenticated by default**: without an `authorize` hook it will
+ * mint a session for any caller that POSTs a well-formed body, which
+ * burns your API-key quota and lets anyone drive the onramp flow with
+ * an attacker-chosen `destinationAddress`. Always pass an `authorize`
+ * callback (host-session check, CSRF token, and/or per-user rate
+ * limiting) in production. The kit cannot supply a safe default
+ * because authentication is host-specific.
+ *
+ * Behaviour:
+ *
+ * - Accepts `POST` only (returns `405` otherwise).
+ * - Validates the JSON body via {@link parseOnrampSessionRequest};
+ *   `400` on shape mismatch.
+ * - Calls `serverKit.createSession(body)` and returns the resulting
+ *   session as JSON (`200`).
+ * - Maps thrown {@link KitError}s to HTTP status:
+ *   `INPUT` → 400, `NETWORK` → 504, `RATE_LIMIT` → 429,
+ *   `SERVICE` / `RPC` → 502, `UNKNOWN` and everything else → 500.
+ * - Sets `Cache-Control: no-store` on every response — session
+ *   tokens are short-lived and must never be cached by intermediaries.
+ * - **Never** echoes the upstream wallets-api response body in the
+ *   error payload (the underlying `createSession` operation already
+ *   scrubs it); only `{ code, name, type, message }` from the
+ *   `KitError` is exposed to the client.
+ *
+ * Hosts that need bespoke error handling, response shaping, or non-
+ * Fetch-API runtimes (Express, Fastify) should keep calling
+ * `serverKit.createSession()` directly.
+ *
+ * @param serverKit - An {@link OnrampServerKit} returned by
+ *   {@link createOnrampServerKit}.
+ * @param options - Optional hooks (auth, error logging).
+ * @returns A `(request: Request) => Promise<Response>` handler.
+ *
+ * @example Next.js App Router (one-liner)
+ * ```ts
+ * // app/api/onramp/sessions/route.ts
+ * import {
+ *   createOnrampServerKit,
+ *   createSessionRouteHandler,
+ * } from '@circle-fin/onramp-kit/server'
+ *
+ * const server = createOnrampServerKit({ apiKey: process.env.ONRAMP_API_KEY! })
+ * export const POST = createSessionRouteHandler(server)
+ * ```
+ *
+ * @example With an authn check
+ * ```ts
+ * import { auth } from '@/lib/auth'
+ *
+ * export const POST = createSessionRouteHandler(server, {
+ *   authorize: async (request) => {
+ *     const session = await auth(request)
+ *     return session?.user != null
+ *   },
+ * })
+ * ```
+ */
+declare function createSessionRouteHandler(serverKit: OnrampServerKit, options?: CreateSessionRouteHandlerOptions): SessionRouteHandler;
+
+/**
+ * Identity for the server surface.
+ *
+ * @remarks
+ * Shares the same `name` and `version` as {@link ONRAMP_KIT_IDENTITY}
+ * but is exported under a distinct symbol so callers that import both
+ * surfaces in the same module get clean autocompletion (`OnrampKit` vs
+ * `OnrampServerKit`).
+ */
+declare const ONRAMP_SERVER_KIT_IDENTITY: {
+    readonly name: "onramp-kit";
+    readonly version: string;
+};
+
+/**
+ * Coerce an unknown value into an {@link OnrampSession}.
+ *
+ * @param value - Value of unknown shape, typically the JSON-decoded
+ *   body of a host-app session endpoint.
+ * @returns The session, with the `{ data }` envelope unwrapped when
+ *   present.
+ *
+ * @throws KitError - `INPUT_INVALID_SESSION` (code `1904`) when the
+ *   value (after envelope unwrapping) is not a non-null object — i.e.
+ *   not a usable session at all.
+ *
+ * @remarks
+ * This helper does **not** assert a closed session schema — by design.
+ * The kit never pins the Onramp API response to a fixed shape, so an
+ * additive API change (a new field, a new optional) cannot break it.
+ * The only checks are unwrapping the `{ data: session }` envelope (some
+ * hosts proxy it straight through) and a minimal structural guard that
+ * the result is a non-null object, so the returned value is at least
+ * minimally backed rather than an unchecked cast. The security-critical
+ * checks (https scheme, origin pin, expiry) still run later in
+ * `getOnrampUrl`, right before the URL reaches the DOM.
+ *
+ * @example
+ * ```ts
+ * const session = parseOnrampSession(await response.json())
+ * onramp.mountIframe({ session, container })
+ * ```
+ */
+declare function parseOnrampSession(value: unknown): OnrampSession;
+/**
+ * Parse an unknown value as an {@link OnrampSessionRequest}.
+ *
+ * @param value - Value of unknown shape, typically the JSON-decoded
+ *   request body received by a host-app session minting endpoint.
+ * @returns The validated request body.
+ *
+ * @throws KitError - When the value does not satisfy the request
+ *   schema.
+ *
+ * @example
+ * ```ts
+ * app.post('/api/onramp/sessions', async (req, res) => {
+ *   const body = parseOnrampSessionRequest(await req.json())
+ *   const session = await onrampServerKit.createSession(body)
+ *   res.json(session)
+ * })
+ * ```
+ */
+declare function parseOnrampSessionRequest(value: unknown): OnrampSessionRequest;
+
+/**
+ * Factory for `@circle-fin/app-kit/server`.
+ *
+ * @remarks
+ * Composes the server-only sub-kits that AppKit ships. Today there
+ * is one: `onramp`, an {@link OnrampServerKit} that mints onramp
+ * sessions using the host's long-lived `apiKey`. The factory is the
+ * only place that touches the secret — by keeping it behind a
+ * dedicated `/server` entry, bundlers reliably exclude it from
+ * browser builds.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Onramp slice of {@link AppServerKitConfig}.
+ *
+ * @remarks
+ * Re-exported here as a named type so consumers do not need to
+ * reach into `@circle-fin/onramp-kit/server` for the option shape.
+ */
+type AppServerKitOnrampConfig = OnrampServerKitOptions;
+/**
+ * Options accepted by {@link createAppServerKit}.
+ *
+ * @example
+ * ```typescript
+ * import { createAppServerKit } from '@circle-fin/app-kit/server'
+ *
+ * const server = createAppServerKit({
+ *   onramp: {
+ *     apiKey: process.env.ONRAMP_API_KEY!,
+ *     // Required when embedding the widget in an iframe — the bare
+ *     // hostname of your embedding page.
+ *     referrerDomain: 'portal.arc.io',
+ *   },
+ * })
+ * ```
+ */
+interface AppServerKitConfig {
+    /**
+     * Configuration for the onramp server kit (session minting).
+     *
+     * @remarks
+     * `apiKey` is required. If you embed the widget in an iframe, also set
+     * `referrerDomain` (the bare hostname of your embedding page) — it has
+     * no default and authorizes that page as a frame ancestor of the
+     * provider's iframe. All remaining fields carry sensible production
+     * defaults — see {@link OnrampServerKitOptions}.
+     */
+    readonly onramp: AppServerKitOnrampConfig;
+}
+/**
+ * Fully-assembled server kit for `@circle-fin/app-kit/server`.
+ *
+ * @remarks
+ * Hand-rolled namespace surface so additional server-only kits can
+ * slot in over time without leaking implementation types into the
+ * public API.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createAppServerKit,
+ *   createSessionRouteHandler,
+ * } from '@circle-fin/app-kit/server'
+ *
+ * const server = createAppServerKit({
+ *   onramp: { apiKey: process.env.ONRAMP_API_KEY! },
+ * })
+ *
+ * export const POST = createSessionRouteHandler(server.onramp)
+ * ```
+ */
+interface AppServerKit {
+    /**
+     * Server-side onramp surface — mints sessions for the embedded
+     * onramp widget.
+     *
+     * @remarks
+     * Pass `server.onramp` straight to `createSessionRouteHandler` to
+     * mount the canonical session endpoint, or call
+     * `server.onramp.createSession(params)` from a custom handler.
+     */
+    readonly onramp: OnrampServerKit;
+}
+/**
+ * Build the app server kit.
+ *
+ * @param config - {@link AppServerKitConfig}.
+ * @returns A frozen {@link AppServerKit} ready to mint sessions.
+ *
+ * @throws KitError - When `config` is not an object, `config.onramp`
+ *   is missing / non-object, or the wrapped onramp factory rejects
+ *   its options (invalid `apiKey`, malformed URL overrides, etc.).
+ *
+ * @remarks
+ * Stateless beyond closures. Cache one instance per app.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createAppServerKit,
+ *   createSessionRouteHandler,
+ * } from '@circle-fin/app-kit/server'
+ *
+ * const server = createAppServerKit({
+ *   onramp: { apiKey: process.env.ONRAMP_API_KEY! },
+ * })
+ *
+ * // Wire the session route in one line:
+ * export const POST = createSessionRouteHandler(server.onramp)
+ * ```
+ */
+declare function createAppServerKit(config: AppServerKitConfig): AppServerKit;
+
+export { KitError, ONRAMP_SERVER_KIT_IDENTITY, createAppServerKit, onrampSessionRequestSchema as createSessionParamsSchema, createSessionRouteHandler, parseOnrampSession, parseOnrampSessionRequest };
+export type { AppServerKit, AppServerKitConfig, AppServerKitOnrampConfig, CreateSessionOperation, CreateSessionParams, CreateSessionRouteHandlerOptions, MintedOnrampSession, OnrampServerKit, OnrampServerKitOptions, OnrampSession, OnrampSessionRequest, SessionRouteHandler };