@zktx.io/sui-mcp 0.5.0

package/dist/core/read/readServiceTypes.js

@@ -0,0 +1,88 @@
+export const MAX_DEEPBOOK_ORDERBOOK_TICKS = 50;
+export const MAX_DEEPBOOK_ACCOUNT_OPEN_ORDER_IDS = 100;
+export const DEEPBOOK_MID_PRICE_TYPE = "deepbook_mid_price";
+export const DEEPBOOK_MID_PRICE_DIRECTION = "quote_per_base";
+export const DEEPBOOK_MID_PRICE_PRECISION = "deepbook_v3_to_fixed_9_js_number";
+export const DEEPBOOK_MID_PRICE_SEMANTICS_KIND = "deepbook_mid_price_snapshot";
+export const WALLET_BALANCE_QUANTITY_KIND = "sui_wallet_balance_snapshot";
+export const DEEPBOOK_ACCOUNT_QUANTITY_KIND = "deepbook_display_number";
+export const DEEPBOOK_QUOTE_QUANTITY_KIND = "deepbook_quote_display_amount";
+export const DEEPBOOK_RAW_QUOTE_QUANTITY_KIND = "deepbook_quote_raw_u64";
+export const DEEPBOOK_USDC_PRICE_HISTORY_QUANTITY_KIND = "deepbook_official_indexer_candles";
+export const INTENT_EVIDENCE_QUANTITY_KIND = "sui_intent_evidence_report";
+export const SETTLEMENT_ASSET_GROUP_PARITY_QUANTITY_KIND = "settlement_asset_group_parity_snapshot";
+export const SUI_USD_SETTLEMENT_ASSET_GROUP_ID = "SUI_USD_SETTLEMENT_ASSETS";
+export const MAX_WALLET_BALANCE_SCAN_PAGES = 20;
+export const MAX_DEEPBOOK_USDC_PRICE_HISTORY_BARS = 1_008;
+export const DEEPBOOK_USDC_PRICE_HISTORY_UNSUPPORTED_CLAIMS = [
+    "fiat_usd_cash_out",
+    "usd_peg_assumption",
+    "global_market_price",
+    "historical_mid_price",
+    "live_quote",
+    "route_recommendation",
+    "best_route",
+    "transaction_building",
+    "signing_readiness",
+    "profit_or_pnl",
+    "cost_basis",
+    "independent_chain_recomputation"
+];
+export const DEEPBOOK_USDC_CANDLE_AVAILABILITY = [
+    "available",
+    "no_candles_in_range"
+];
+export const DEEPBOOK_USDC_PRICE_HISTORY_UNSUPPORTED_PAIR_REASONS = [
+    "selector_not_in_official_indexer",
+    "selector_resolves_to_multiple_usdc_pools"
+];
+export const DEEPBOOK_USDC_PRICE_HISTORY_SOURCE_UNAVAILABLE_REASONS = [
+    "official_indexer_not_configured",
+    "pool_list_unavailable",
+    "candle_fetch_failed",
+    "official_indexer_invalid_payload"
+];
+// Internal placeholder for sender-independent DeepBook market reads. The pinned Sui gRPC
+// resolver uses the same dummy sender when no transaction sender is provided.
+export const DEFAULT_DEEPBOOK_SIMULATION_SENDER = "0x0000000000000000000000000000000000000000000000000000000000000000";
+export const NOT_INSPECTED_ASSET_CLASSES = [
+    {
+        assetClass: "staked_or_locked_asset",
+        reason: "requires_separate_stake_read_not_inspected"
+    },
+    {
+        assetClass: "deepbook_balance_manager_or_open_order",
+        reason: "requires_separate_deepbook_account_read_not_inspected"
+    },
+    {
+        assetClass: "lp_vault_or_position",
+        reason: "requires_separate_protocol_read_not_inspected"
+    },
+    {
+        assetClass: "nft_or_object_asset",
+        reason: "requires_separate_object_read_not_inspected"
+    }
+];
+export const INTENT_EVIDENCE_TARGET_ASSET_SELECTION_SOURCES = [
+    "user_explicit",
+    "prior_user_explicit_context"
+];
+export class ReadServiceInputError extends Error {
+    kind;
+    details;
+    constructor(kind, message, details) {
+        super(message);
+        this.kind = kind;
+        this.details = details;
+    }
+}
+export class ReadServiceCacheError extends Error {
+    kind = "metadata_cache_unavailable";
+    details;
+    cause;
+    constructor(operation, cause) {
+        super("Coin metadata cache is unavailable");
+        this.details = { resource: "coin_metadata_cache", operation };
+        this.cause = cause;
+    }
+}

package/dist/core/read/settlementParityFormatting.js

@@ -0,0 +1,82 @@
+import { SETTLEMENT_ASSET_GROUP_PARITY_QUANTITY_KIND } from "./readServiceTypes.js";
+export function settlementAssetGroupParityQuantitySemantics() {
+    return {
+        kind: SETTLEMENT_ASSET_GROUP_PARITY_QUANTITY_KIND,
+        allowedUse: "settlement_asset_group_internal_parity_evidence",
+        referenceAssetRole: "measurement_reference_not_settlement_choice",
+        priceSource: "deepbook_mid_price_snapshot",
+        fiatUsdCashOutAvailable: false,
+        externalMarketPriceConversionAvailable: false,
+        externalMarketLookupAvailable: false,
+        usdPegAssumptionAvailable: false,
+        settlementTokenSelectionAvailable: false,
+        paymentExecutionReadinessAvailable: false,
+        routeRecommendationAvailable: false,
+        profitAndLossAvailable: false,
+        costBasisAvailable: false,
+        notFor: [
+            "settlement_token_selection",
+            "fiat_usd_cash_out",
+            "external_market_price_conversion",
+            "external_market_lookup",
+            "usd_peg_assumption",
+            "bank_cash_out_estimate",
+            "payment_execution_readiness",
+            "route_recommendation",
+            "best_route",
+            "transaction_building",
+            "signing_readiness",
+            "profit_or_pnl",
+            "cost_basis"
+        ]
+    };
+}
+export function settlementAssetGroupParityStatistics(samples, unavailableAssetCount) {
+    const sorted = [...samples].sort((left, right) => left.priceInReferenceAsset - right.priceInReferenceAsset);
+    const min = sorted[0];
+    const max = sorted[sorted.length - 1];
+    const middle = Math.floor(sorted.length / 2);
+    const median = sorted.length % 2 === 1
+        ? sorted[middle].priceInReferenceAsset
+        : (sorted[middle - 1].priceInReferenceAsset + sorted[middle].priceInReferenceAsset) / 2;
+    const mean = samples.reduce((sum, sample) => sum + sample.priceInReferenceAsset, 0) / samples.length;
+    return {
+        status: "available",
+        sampleCount: samples.length,
+        unavailableAssetCount,
+        parityDirection: "reference_asset_per_group_asset",
+        calculation: "computed_from_available_direct_deepbook_mid_price_snapshots",
+        min: { symbol: min.symbol, priceInReferenceAsset: roundPriceInReferenceAsset(min.priceInReferenceAsset) },
+        max: { symbol: max.symbol, priceInReferenceAsset: roundPriceInReferenceAsset(max.priceInReferenceAsset) },
+        mean: { priceInReferenceAsset: roundPriceInReferenceAsset(mean) },
+        median: { priceInReferenceAsset: roundPriceInReferenceAsset(median) }
+    };
+}
+export function settlementAssetGroupParityResponseSummary(input) {
+    return {
+        questionKind: "settlement_asset_group_parity",
+        conclusionKind: "parity_statistics_available",
+        assetGroupId: input.assetGroupId,
+        referenceAssetSymbol: input.referenceAssetSymbol,
+        referenceAssetRole: "measurement_reference_not_settlement_choice",
+        parityDirection: input.statistics.parityDirection,
+        min: input.statistics.min,
+        max: input.statistics.max,
+        mean: input.statistics.mean,
+        median: input.statistics.median,
+        excludedFromConclusion: [
+            "settlement_token_selection",
+            "fiat_usd_cash_out",
+            "payment_execution_readiness",
+            "route_recommendation",
+            "best_route",
+            "transaction_building",
+            "signing_readiness",
+            "profit_or_pnl",
+            "cost_basis"
+        ]
+    };
+}
+export function roundPriceInReferenceAsset(price) {
+    return Number(price.toFixed(9));
+}

package/dist/core/read/walletReadHelpers.js

@@ -0,0 +1,99 @@
+import { DEEPBOOK_SCALAR_UNIT_SOURCE, DISPLAY_AMOUNT_SOURCE, SUI_METADATA_UNIT_SOURCE, formatRawAmount, normalizeCoinType } from "./coinMetadata.js";
+import { findDeepbookCoinEntry } from "./deepbookRegistry.js";
+import { WALLET_BALANCE_QUANTITY_KIND } from "./readServiceTypes.js";
+export const SUI_COIN_TYPE = normalizeCoinType("0x2::sui::SUI");
+export function walletBalanceQuantitySemantics() {
+    return {
+        kind: WALLET_BALANCE_QUANTITY_KIND,
+        allowedUse: "current_coin_balance_snapshot",
+        currentBalanceSnapshot: true,
+        transactionHistoryAvailable: false,
+        transactionReceiptProofAvailable: false,
+        transactionBalanceDeltaAvailable: false,
+        acquisitionSourceAvailable: false,
+        objectProvenanceAvailable: false,
+        fiatUsdCashOutAvailable: false,
+        profitAndLossAvailable: false,
+        costBasisAvailable: false,
+        notFor: [
+            "transaction_history",
+            "transaction_receipt_proof",
+            "specific_transaction_balance_delta",
+            "acquisition_source",
+            "object_provenance",
+            "fiat_usd_cash_out",
+            "profit_or_pnl",
+            "cost_basis",
+            "signing_data"
+        ]
+    };
+}
+export function classifyWalletBalance(balance, coins) {
+    const roles = [];
+    let normalizedCoinType;
+    try {
+        normalizedCoinType = normalizeCoinType(balance.coinType);
+    }
+    catch {
+        normalizedCoinType = undefined;
+    }
+    if (normalizedCoinType === SUI_COIN_TYPE) {
+        roles.push("gas_candidate");
+    }
+    if (normalizedCoinType && findDeepbookCoinEntry(normalizedCoinType, coins)) {
+        roles.push("deepbook_registered");
+    }
+    return {
+        balance,
+        classification: {
+            assetClass: "coin_balance",
+            balanceStatus: balance.balance === "0" ? "zero" : "nonzero",
+            roles
+        }
+    };
+}
+export function unitFromMetadataRecord(record, cacheStatus) {
+    return {
+        status: "available",
+        source: SUI_METADATA_UNIT_SOURCE,
+        decimals: record.decimals,
+        symbol: record.symbol,
+        name: record.name,
+        cacheStatus
+    };
+}
+export function unitFromDeepbook(unit) {
+    return {
+        status: "available",
+        source: DEEPBOOK_SCALAR_UNIT_SOURCE,
+        decimals: unit.decimals,
+        symbol: unit.symbol,
+        name: unit.name
+    };
+}
+export function withUnavailableUnit(balance, reason) {
+    return withResolvedUnit(balance, unavailableUnit(reason));
+}
+export function unavailableUnit(reason) {
+    return {
+        status: "unavailable",
+        reason
+    };
+}
+export function withResolvedUnit(balance, unit) {
+    if (unit.status === "unavailable") {
+        return {
+            ...balance,
+            unit
+        };
+    }
+    return {
+        ...balance,
+        unit,
+        display: {
+            amount: formatRawAmount(balance.balance, unit.decimals),
+            symbol: unit.symbol,
+            source: DISPLAY_AMOUNT_SOURCE
+        }
+    };
+}

package/dist/core/review/reviewChecks.js

@@ -0,0 +1,45 @@
+export function adapterNotImplementedCheck() {
+    return {
+        id: "adapter_not_implemented",
+        label: "Supported transaction type",
+        status: "fail",
+        message: "No installed protocol adapter can review this transaction type. Wallet approval is unavailable.",
+        source: "adapter"
+    };
+}
+export function accountBoundReviewRequiredCheck() {
+    return {
+        id: "account_bound_review_required",
+        label: "Review for your account",
+        status: "warning",
+        message: "This transaction has not been checked for a connected wallet account. Wallet approval and submission are unavailable.",
+        source: "adapter"
+    };
+}
+export function signingViaLocalReviewOnlyCheck() {
+    return {
+        id: "signing_via_local_review_only",
+        label: "Wallet signing",
+        status: "warning",
+        message: "Wallet signing requires completed review evidence, an explicit user action in the internal Review card and approval in the wallet; the backend verifies the returned transaction digest and signer. MCP responses never contain signing data, transaction bytes, or signing readiness.",
+        source: "adapter"
+    };
+}
+export function unsupportedDeepbookSwapPlanIdentityCheck() {
+    return {
+        id: "deepbook_swap_plan_identity_invalid",
+        label: "DeepBook plan identity",
+        status: "fail",
+        message: "The proposed transaction does not match the supported DeepBook swap format.",
+        source: "adapter"
+    };
+}
+export function externalProposalReviewOnlyCheck() {
+    return {
+        id: "external_proposal_review_only",
+        label: "View-only proposal",
+        status: "fail",
+        message: "This external proposal is for viewing only. It does not prepare a transaction, request a signature or allow wallet actions.",
+        source: "adapter"
+    };
+}

package/dist/core/review/reviewComputation.js

@@ -0,0 +1,38 @@
+import { rejectAdapterLifecycle } from "../action/adapterLifecycleValidation.js";
+import { adapterNotImplementedCheck, externalProposalReviewOnlyCheck } from "./reviewChecks.js";
+import { blockedReviewResult, mapReviewComputationResultToState } from "./reviewComputationResult.js";
+export async function computeReviewState(input, deps = {}) {
+    const computed = await computeReviewStateWithPrivateArtifacts(input, deps);
+    return computed.state;
+}
+export async function computeReviewStateWithPrivateArtifacts(input, deps = {}) {
+    const computed = await computeReviewOutput(input, deps);
+    const state = mapReviewComputationResultToState({
+        reviewSessionId: input.reviewSessionId,
+        planId: input.plan.id,
+        account: input.account,
+        now: input.now
+    }, computed.result, deps.validateAdapterLifecycle ?? rejectAdapterLifecycle);
+    return {
+        state,
+        ...(computed.privateArtifacts ? { privateArtifacts: computed.privateArtifacts } : {})
+    };
+}
+export async function computeReviewResult(input, deps = {}) {
+    return (await computeReviewOutput(input, deps)).result;
+}
+async function computeReviewOutput(input, deps = {}) {
+    if (input.plan.adapterId === "external-proposal-review") {
+        return {
+            result: blockedReviewResult("proposal_review_only", input.plan.reviewModel?.blockingChecks ?? [externalProposalReviewOnlyCheck()])
+        };
+    }
+    const computeAdapterEvidence = deps.adapters?.[input.plan.adapterId];
+    if (computeAdapterEvidence) {
+        return computeAdapterEvidence(input);
+    }
+    return {
+        result: blockedReviewResult("adapter_not_implemented", [adapterNotImplementedCheck()])
+    };
+}
+export { adapterNotImplementedCheck, externalProposalReviewOnlyCheck };

package/dist/core/review/reviewComputationResult.js

@@ -0,0 +1,87 @@
+import { parseLifecycleValidatedReviewState } from "../action/reviewStateValidation.js";
+export function mapReviewComputationResultToState(identity, result, validateAdapterLifecycle) {
+    const base = {
+        planId: identity.planId,
+        reviewSessionId: identity.reviewSessionId,
+        account: identity.account,
+        checks: result.checks,
+        updatedAt: result.updatedAt ?? (identity.now ?? new Date()).toISOString(),
+        ...(result.assetFlowActual ? { assetFlowActual: result.assetFlowActual } : {}),
+        ...(result.beforeAfterBalance ? { beforeAfterBalance: result.beforeAfterBalance } : {}),
+        ...(result.simulation ? { simulation: result.simulation } : {}),
+        ...(result.humanReadableReview ? { humanReadableReview: result.humanReadableReview } : {}),
+        ...(result.transactionReviewData
+            ? { transactionReviewData: result.transactionReviewData }
+            : {}),
+        ...(result.ptbVisualization ? { ptbVisualization: result.ptbVisualization } : {}),
+        ...(result.adapterLifecycle ? { adapterLifecycle: result.adapterLifecycle } : {})
+    };
+    if (result.status === "ready_for_wallet_review") {
+        return parseMappedReviewState({
+            ...base,
+            status: "ready_for_wallet_review"
+        }, validateAdapterLifecycle);
+    }
+    if (result.status === "refresh_required") {
+        return parseMappedReviewState({
+            ...base,
+            status: "refresh_required",
+            refreshReason: result.refreshReason
+        }, validateAdapterLifecycle);
+    }
+    return parseMappedReviewState({
+        ...base,
+        status: "blocked",
+        blockedReason: result.blockedReason
+    }, validateAdapterLifecycle);
+}
+function parseMappedReviewState(state, validateAdapterLifecycle) {
+    return parseLifecycleValidatedReviewState(state, validateAdapterLifecycle);
+}
+export function blockedReviewResult(blockedReason, checks, fields = {}) {
+    return {
+        status: "blocked",
+        blockedReason,
+        checks,
+        ...fields
+    };
+}
+export function blockedAdapterLifecycleReviewResult(blockedReason, checks, adapterLifecycle) {
+    return blockedReviewResult(blockedReason, checks, { adapterLifecycle });
+}
+export function producerStageMissingReviewResult(checks, adapterLifecycle, fields = {}) {
+    return blockedReviewResult("producer_stage_missing", checks, {
+        adapterLifecycle,
+        ...fields
+    });
+}
+export function walletReviewContractEmitMissingResult(checks, adapterLifecycle, humanReadableReview, simulation) {
+    return blockedReviewResult("wallet_review_contract_emit_missing", checks, {
+        adapterLifecycle,
+        humanReadableReview,
+        simulation
+    });
+}
+export function walletReviewContractEmittedResult(checks, adapterLifecycle, humanReadableReview, simulation, transactionReviewData, ptbVisualization) {
+    return {
+        status: "ready_for_wallet_review",
+        checks,
+        adapterLifecycle,
+        humanReadableReview,
+        simulation,
+        transactionReviewData,
+        ...(ptbVisualization ? { ptbVisualization } : {})
+    };
+}
+export function refreshRequiredReviewResult(refreshReason, checks, fields = {}) {
+    return {
+        status: "refresh_required",
+        refreshReason,
+        checks,
+        ...fields
+    };
+}
+export function refreshRequiredAdapterLifecycleReviewResult(refreshReason, checks, adapterLifecycle) {
+    return refreshRequiredReviewResult(refreshReason, checks, { adapterLifecycle });
+}
+export { failReviewCheck, passReviewCheck } from "../action/reviewCheckResults.js";

package/dist/core/session/cardSession.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+export const walletDisplaySchema = z.object({
+    connectionId: z.string().min(1), pairingUri: z.string().startsWith("wc:"), expiresAt: z.string().datetime()
+}).strict();
+export const cardKindSchema = z.enum(["account", "receipt", "chart", "connect", "review"]);
+export const cardStateSchema = z.object({
+    cardId: z.string().min(1), kind: cardKindSchema,
+    state: z.enum(["ready", "running", "closed"]),
+    revision: z.number().int().nonnegative(),
+    createdAt: z.string().datetime(), expiresAt: z.string().datetime(),
+    input: z.record(z.string(), z.unknown()),
+    data: z.unknown().optional(),
+    reason: z.enum(["completed", "expired", "failed", "server_restarted", "cancelled"]).optional(),
+    error: z.string().optional()
+}).strict();
+export const cardSnapshotSchema = cardStateSchema.extend({
+    pollAfterMs: z.number().int().positive(),
+    inputRemainingMs: z.number().int().nonnegative()
+});
+// Private display values from a receipt already read by the backend. These are
+// individual on-chain inputs, never a serialized transaction or a signature.
+export const receiptDisplaySchema = z.object({
+    // Sui syntax is validated by the backend producer/projection. The View checks
+    // equality with its selected digest and does not load an SDK to recompute it.
+    transactionDigest: z.string().min(1),
+    pureInputs: z.array(z.object({
+        index: z.number().int().nonnegative(),
+        bytes: z.string().regex(/^0x(?:[0-9a-f]{2})*$/i)
+    }).strict()).refine((items) => new Set(items.map((item) => item.index)).size === items.length, "Duplicate input index."),
+    ptbGraph: z.object({ mermaid: z.object({ text: z.string(), namedText: z.string() }).strict() }).strict().optional()
+}).strict();

package/dist/core/session/cardSessionStore.js

@@ -0,0 +1,204 @@
+import { isDeepStrictEqual } from "node:util";
+import { parseCardInput } from "../read/readCardInputs.js";
+import { projectReadCardResult } from "../read/readCardResult.js";
+import { WALLET_CONNECTION_POLL_SECONDS, WalletUnavailableError } from "./walletConnection.js";
+import { EXECUTION_POLLING_INTERVAL_SECONDS } from "./status.js";
+import { createLocalSessionBase, DEFAULT_SESSION_TTL_MS, tokenMatchesHash } from "./localSession.js";
+import { assertNoForbiddenMcpFields } from "../action/forbiddenFields.js";
+import { cardSnapshotSchema } from "./cardSession.js";
+import { WorkflowConflict } from "./sqliteWalletWorkflowStore.js";
+import { parseWorkflowAction } from "./workflowView.js";
+export class CardError extends Error {
+}
+export class CardStore {
+    options;
+    stopped = false;
+    constructor(options) {
+        this.options = options;
+        this.assertCurrent();
+        options.records.recover(options.ownerId, this.now());
+    }
+    now() { return this.options.now?.() ?? new Date(); }
+    assertCurrent() {
+        if (this.stopped)
+            throw new CardError("This card cannot be checked right now.");
+        this.options.assertCurrent?.();
+    }
+    async create(kind, input, execute = false) {
+        this.assertCurrent();
+        const business = kind === "connect" || kind === "review";
+        if (business && (!this.options.workflow || execute))
+            throw new CardError("This type of card is unavailable.");
+        const parsed = execute ? parseCardInput(kind, input) : undefined;
+        let preparation = { status: "ready" };
+        if (business) {
+            preparation = await this.options.workflow.prepare(kind, input);
+            this.assertCurrent();
+        }
+        else if (!execute && this.options.prepare) {
+            try {
+                preparation = await this.options.prepare(kind);
+            }
+            catch {
+                preparation = { status: "failed", error: "The choices for this card could not be loaded." };
+            }
+            // Preparation may finish after reset/import or shutdown. Never create a
+            // card in replacement data from that stale continuation.
+            this.assertCurrent();
+        }
+        assertNoForbiddenMcpFields({ input, preparation });
+        const { base, token } = createLocalSessionBase(this.now(), DEFAULT_SESSION_TTL_MS);
+        const record = { ownerId: this.options.ownerId, tokenHash: base.tokenHash,
+            scope: kind === "connect" ? "connect" : kind === "review" ? input.mode === "manage" ? "review_manage" : "review" : "read",
+            ...(kind === "review" && input.mode === "manage" && typeof input.attemptId === "string" ? { operationId: input.attemptId } : {}),
+            state: { cardId: base.id, kind, state: preparation.status === "failed" ? "closed" : "ready", revision: 0,
+                createdAt: base.createdAt, expiresAt: base.expiresAt, input,
+                ...(preparation.status === "failed" ? { reason: "failed", error: preparation.error } :
+                    preparation.data === undefined ? {} : { data: preparation.data }) } };
+        this.options.records.create(record);
+        if (preparation.status === "failed")
+            this.reportFailure(record, "input_preparation");
+        const result = parsed === undefined ? await this.describe(record, false) : await this.submit({
+            cardId: base.id, permission: token, revision: 0, input: parsed
+        });
+        return { ...result, permission: token };
+    }
+    async read(input) { return this.describe(this.require(input), true); }
+    async readSaved(cardId) { return (await this.describe(this.current(cardId), false)).snapshot; }
+    async describe(record, uiObservation) {
+        if (record.state.kind !== "connect" && record.state.kind !== "review")
+            return this.response(record);
+        if (!this.options.workflow)
+            throw new CardError("Wallet actions are unavailable.");
+        const view = await this.options.workflow.describe(record, uiObservation);
+        const current = view.evaluated.record;
+        if (!current)
+            throw new CardError("Saved card data is unavailable.");
+        const snapshot = cardSnapshotSchema.parse({ ...current.state, data: view.data,
+            inputRemainingMs: view.evaluated.inputRemainingMs,
+            pollAfterMs: (current.state.kind === "review" ? EXECUTION_POLLING_INTERVAL_SECONDS : WALLET_CONNECTION_POLL_SECONDS) * 1000 });
+        assertNoForbiddenMcpFields(snapshot);
+        return { snapshot, ...(view.walletDisplay ? { walletDisplay: view.walletDisplay } : {}),
+            ...(view.receiptDisplay ? { receiptDisplay: view.receiptDisplay, displayAttemptId: view.displayAttemptId } : {}) };
+    }
+    async act(input) {
+        const record = this.require(input);
+        if ((record.state.kind !== "connect" && record.state.kind !== "review") || !this.options.workflow) {
+            return this.conflict(record, "This card does not accept wallet workflow actions.");
+        }
+        let parsed;
+        try {
+            parsed = parseWorkflowAction(input.input);
+        }
+        catch {
+            return { ...await this.describe(record, false), error: { code: "invalid_card_input", message: "The requested wallet action is not supported by this card." } };
+        }
+        if (record.acceptedInput !== undefined && isDeepStrictEqual(record.acceptedInput, parsed))
+            return this.describe(record, false);
+        if (record.state.revision !== input.revision)
+            return { ...await this.describe(record, false),
+                error: { code: "card_conflict", message: "This request does not match the card's current state." } };
+        try {
+            await this.options.workflow.act(record, parsed);
+        }
+        catch (error) {
+            if (!(error instanceof WorkflowConflict) && !(error instanceof WalletUnavailableError))
+                throw error;
+            return { ...await this.describe(this.current(input.cardId), false), error: {
+                    code: error instanceof WalletUnavailableError ? "wallet_unavailable" : "card_conflict", message: error.message
+                } };
+        }
+        return this.describe(this.current(input.cardId), false);
+    }
+    async submit(input) {
+        const record = this.require(input);
+        if (record.state.kind === "connect" || record.state.kind === "review")
+            throw new CardError("This card does not accept data selections.");
+        let parsed;
+        try {
+            parsed = parseCardInput(record.state.kind, input.input);
+        }
+        catch {
+            return { ...this.response(record), error: { code: "invalid_card_input", message: "The selected information is not valid for this card." } };
+        }
+        if (record.acceptedInput !== undefined) {
+            if (isDeepStrictEqual(record.acceptedInput, parsed))
+                return this.response(record);
+            return this.conflict(record, "This card already accepted a different selection.");
+        }
+        if (record.state.state !== "ready" || record.ownerId !== this.options.ownerId || record.state.revision !== input.revision) {
+            return this.conflict(record, "This selection does not match the current card.");
+        }
+        const admitted = this.options.records.admit(record, parsed, this.options.ownerId, () => this.now());
+        if (!admitted)
+            return this.conflict(this.require(input), "The card changed or expired before this selection was accepted.");
+        let source;
+        try {
+            source = await this.options.execute(record.state.kind, parsed);
+        }
+        catch {
+            return this.fail(admitted, "read_service", "The requested data could not be read.");
+        }
+        this.assertCurrent();
+        let projected;
+        try {
+            projected = projectReadCardResult(record.state.kind, parsed, source);
+        }
+        catch {
+            return this.fail(admitted, "result_validation", "The returned data could not be prepared for this card.");
+        }
+        const complete = { ...admitted, ...("receiptDisplay" in projected ? { receiptDisplay: projected.receiptDisplay } : {}),
+            state: { ...admitted.state, data: projected.data, state: "closed", reason: "completed", revision: admitted.state.revision + 1 } };
+        // Do not report success or replay the source call if this commit fails.
+        try {
+            this.options.records.replace(admitted, complete);
+        }
+        catch {
+            return this.fail(admitted, "result_storage", "The result could not be saved. This request will not be repeated automatically.");
+        }
+        return this.response(this.current(record.state.cardId));
+    }
+    stop() { this.stopped = true; }
+    fail(record, stage, message) {
+        this.assertCurrent();
+        this.reportFailure(record, stage);
+        this.options.records.replace(record, { ...record, state: { ...record.state,
+                state: "closed", reason: "failed", error: message, revision: record.state.revision + 1 } });
+        return this.response(this.current(record.state.cardId));
+    }
+    reportFailure(record, stage) {
+        try {
+            this.options.logger?.error("Card read failed", { cardId: record.state.cardId, kind: record.state.kind, stage });
+        }
+        catch { /* Logging does not own the operation's state. */ }
+    }
+    conflict(record, message) {
+        return { ...this.response(record), error: { code: "card_conflict", message } };
+    }
+    current(id) {
+        this.assertCurrent();
+        const record = this.options.records.get(id);
+        if (!record)
+            throw new CardError("Saved card data is unavailable.");
+        return record;
+    }
+    require(input) {
+        this.assertCurrent();
+        const record = this.options.records.get(input.cardId);
+        if (!record || !tokenMatchesHash(record.tokenHash, input.permission))
+            throw new CardError("Card access is unavailable.");
+        return record;
+    }
+    snapshot(record, evaluatedAt) {
+        const snapshot = cardSnapshotSchema.parse({ ...record.state,
+            pollAfterMs: WALLET_CONNECTION_POLL_SECONDS * 1000,
+            inputRemainingMs: record.state.state === "ready" ? Math.max(0, Date.parse(record.state.expiresAt) - Date.parse(evaluatedAt)) : 0 });
+        assertNoForbiddenMcpFields(snapshot);
+        return snapshot;
+    }
+    response(record) {
+        const evaluated = this.options.records.evaluate(record, () => this.now());
+        record = evaluated.record;
+        return { snapshot: this.snapshot(record, evaluated.evaluatedAt), ...(record.receiptDisplay === undefined ? {} : { receiptDisplay: record.receiptDisplay }) };
+    }
+}