@zktx.io/sui-mcp 0.5.0

package/README.md

@@ -0,0 +1,288 @@
+# Sui MCP
+
+Sui MCP is a local-first Sui review and evidence layer for AI clients.
+
+It turns a supported Sui action into an internal Review card where you inspect
+verified transaction facts and a PTB graph, then request approval in your own
+wallet. The backend builds or verifies the material, binds the reviewed account
+and digest, and uses WalletConnect for a sign-only request. It verifies the
+wallet's returned bytes and signature before one submission to Sui mainnet.
+
+The AI and card never receive executable transaction bytes or signatures.
+Neither a review nor a wallet connection is standing transaction permission.
+Only an explicit user action and that transaction's wallet approval authorize
+the request. Lost replies are resolved by reading the known digest; they do not
+cause another signing or submission request. Request failures and unknown
+outcomes are separate from independently observed chain success/failure.
+
+Account, Receipt and Chart cards provide read-only evidence independently of
+signing. Connect and Review also run inside the MCP host. Settings currently
+uses a local token page. Human-readable review is not a guarantee of safety or
+of complete interpretation of every transaction detail; the raw PTB structure
+and addresses remain inspectable.
+
+Users can ask ordinary questions:
+
+- "Can I cover a 1000 dollar payment with my assets?"
+- "How much are my USD-denominated assets together?"
+- "What is the shortfall?"
+
+This document describes `@zktx.io/sui-mcp@0.5.0`. Confirm that version is
+published before using npm installation commands. For a local build, follow
+[Developer Checkout Setup](docs/MCP_SETUP.md#developer-checkout-setup).
+
+## Product Scope in Two Layers
+
+- **Implemented:** Sui mainnet read evidence, non-signable external proposal review, and account-bound DeepBook swap review using protocol-agnostic adapters. Five internal cards use the same SQLite state and permission model. The backend verifies stored material, ownership, quote/policy provenance, human-readable facts, simulation and PTB evidence before an explicit user request. WalletConnect carries bytes only between the backend and wallet; ordinary MCP responses expose facts, request status and observed execution results. Settings remains a local token page; an internal Settings card is not implemented.
+- **Never (permanently unsupported at every layer):** no private-key custody, no MCP or AI autonomous execution, no forwarding of opaque external transaction bytes to a wallet, no silent settlement-token or route choice, no fiat cash-out, no P&L, no peg guarantee.
+
+DeepBook provides the current scoped Sui conversion, price, and orderbook
+evidence through the shared protocol adapter contracts. Wallet and Sui balance reads
+describe held assets. They do not define the whole product.
+
+Sui MCP does not custody funds, hold private keys, or autonomously trade
+on behalf of users.
+By current design, it does not rank venues, choose routes, make best-price
+recommendations, or silently choose settlement tokens for users.
+
+Account-bound transaction building, signing requests and chain observation stay
+in the local backend. The Review card displays evidence and current permitted
+actions. Public review JSON, model-facing card data and backups never contain transaction
+bytes, signatures, SDK keys or signing permission. Reopening a card reads its
+stored state and never replays a financial request.
+
+The current release flow is:
+
+```text
+The user states an intent in natural language.
+Sui MCP resolves the supported Sui mainnet evidence surface.
+The AI answers only from returned evidence and boundaries.
+Supported swap transaction material build is an account-bound review step, not
+part of the natural-language intent evidence answer.
+```
+
+The current release implements intent evidence for supported Sui mainnet reads.
+It can also create a read-only, non-signable local review session from a
+structured external payment or Sui action proposal. External proposal ingestion
+does not trust external transaction material or send anything for wallet signing.
+
+For setup, see [docs/MCP_SETUP.md](docs/MCP_SETUP.md).
+For the MCP API reference, see [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).
+For the AI-client answer playbook, see [docs/AGENT_BEHAVIOR.md](docs/AGENT_BEHAVIOR.md).
+For manual maintainer and developer utilities, see [docs/UTILITY_INDEX.md](docs/UTILITY_INDEX.md).
+
+User-question flows for USD-denominated coverage, balance totals, and shortfall answers live in [docs/AGENT_BEHAVIOR.md](docs/AGENT_BEHAVIOR.md). The response fields for those answers live in [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).
+
+## What Works Today
+
+The current release can run as a local stdio MCP server and expose mainnet Sui DeFi evidence:
+
+- wallet balances with verified display units;
+- coin-balance classification;
+- USD-denominated settlement asset groups derived from pinned DeepBook SDK registry metadata;
+- intent evidence with response summaries for natural-language USD-denominated payment coverage, balance-total, and shortfall questions;
+- DeepBook pools, tokens, mid price, orderbook context, raw quotes, display-amount quotes, and account inventory;
+- user-requested bounded Sui transaction digest lookup, account activity scans, sent-function activity scans with known-wallet-only persistence, and stored normalized activity summaries;
+- read-only external proposal review sessions that display proposed action, asset flow, recipient or target, freshness, missing evidence, user choices, unsupported claims, and non-signable reason;
+- local Sui MCP review evidence and review-session status reads;
+- account-bound DeepBook review with verified material, digest, ownership, policy, human-readable facts, simulation and PTB visualization, followed by explicit card selection and wallet approval through the backend;
+- separately recorded request state and chain success/failure, shown in the Review card and available through ordinary reads;
+- a Receipt card for server-read facts about any transaction digest, independent of signing.
+
+It also includes:
+
+- a local review server bound to `127.0.0.1`;
+- a local SQLite store for active account read context and review evidence;
+- MCP output checks that reject forbidden executable, signing, token, seed, and
+  key-material field names from responses.
+
+## Screens
+
+**Wallet connection.** Connect one Sui mainnet wallet and use one of its approved
+addresses. A manage card shows Connect wallet when no connection is active;
+opening it alone does not pair. A connect-intent card starts pairing after its
+View confirms permission and current state. Each disconnection requires the
+user to confirm its exact target. Connection is not transaction approval.
+
+
+**Review and result.** The internal Review card automatically prepares and renews verified conditions for one selected wallet/account. Users inspect its transaction graph, amounts and costs, then choose Request wallet approval and approve in their wallet. One wallet connection is used at a time; choose among its approved addresses when needed. Conflicting saved connections must be resolved through targeted disconnection. Failed preparation has an explicit retry. Receipt and completed Review show the executed transaction graph, actual asset changes and net network fee. Supplementary facts are in one Details slide; earlier estimates in Review remain distinct from actual chain results. Missing graph or receipt data is marked unavailable. Cards use a single document layout without nested card panels.
+
+**DeepBook USDC chart.** `ui.open_chart` opens an internal MCP Apps card with
+official DeepBookV3 Indexer candles and volume for one selected USDC pool.
+The saved result shows the selected pair, interval, UTC period and source time. Limited and empty results are identified.
+
+## Current Limits
+
+### Not Implemented
+
+External proposal execution is not implemented. Further local analysis views
+beyond the current inline review receipt and internal Receipt card are
+not implemented. Transaction material review, backend WalletConnect requests under user control,
+signature verification, single submission and independent receipt observation
+are implemented for the account-bound DeepBook swap review
+through a plan-factory registry.
+
+External proposal ingestion is implemented only for read-only local review
+sessions. It accepts structured proposal facts, rejects forbidden executable or
+signing fields, recognized Sui private-key strings, valid English BIP39
+mnemonic phrases, obvious sensitive markers, and suspicious raw secret-like
+payloads before storage, and records why the review is non-signable.
+
+A blocked review lacks required evidence for that session. Only a complete
+`TransactionReviewData` binds human-readable facts and simulation to the exact
+reviewed digest. This is pre-signing evidence, not authority or guaranteed
+execution. The backend checks returned bytes and the selected account's
+signature before submitting. See [the adapter contract](docs/SIGNABLE_ADAPTER_CONTRACT.md).
+
+Fiat cash-out, P&L, tax, and cost-basis support are not part of the current release.
+
+### Permanent Safety and Correctness Boundaries
+
+These are product boundaries and must not be relaxed by ordinary feature work:
+
+- Sui MCP does not custody funds, hold private keys, or autonomously trade.
+- It does not treat USDC, USDT, or any USD-denominated settlement asset as fiat
+  USD, a bank cash-out amount, or a USDC/USD peg guarantee.
+- It does not turn quote-only conversion candidates into payment coverage, shortfall evidence, funding readiness, payment execution readiness, or signing readiness.
+
+### Out of Scope by Current Design
+
+These product behaviors are out of scope in the current release by design:
+
+- It does not silently choose USDC, USDT, or another settlement token for a
+  user. It can report supported settlement asset groups and can use a settlement
+  token only when the user selected it explicitly.
+- It does not rank venues, choose routes, or make best-price recommendations.
+
+### Quote Response Limits
+
+Quote tools such as `read.quote_deepbook_action` and
+`read.quote_deepbook_display_amount` return scoped quote facts and raw quote
+evidence only.
+
+Their semantics mark quote output as price evidence, not payment coverage or shortfall evidence. Coverage and shortfall answers come from `read.preview_intent_evidence.responseSummary`.
+
+For quote responses alone, these conclusions are unsupported:
+
+- payment coverage is not available;
+- shortfall contribution is not available;
+- route-dependent payment support is not available;
+- final min-out values are not available;
+- route recommendations are not available;
+- venue comparisons are not available;
+- effective-price claims are not available;
+- price-impact calculations are not available;
+- quote-vs-mid slippage is not available;
+- fiat cash-out estimates are not available;
+- external market lookups are not available;
+- USDC/USD peg assumptions are not available;
+- P&L is not available;
+- cost basis is not available;
+- actionable signing data is not available.
+
+## Install
+
+Use the checkout setup above for unpublished changes. A local commit or successful
+package check does not publish a release.
+
+This release uses npm package `@zktx.io/sui-mcp` and MCP Registry name
+`io.github.zktx-mcp/sui-mcp`. Once the requested version is published,
+install through your client's registry support or run `npx -y @zktx.io/sui-mcp`.
+For per-client configuration (Claude Code, Claude Desktop, Codex, Cursor) and
+running from a local checkout, see [docs/MCP_SETUP.md](docs/MCP_SETUP.md).
+
+### Package and repository transition
+
+The package for this release is `@zktx.io/sui-mcp@0.5.0`, and its repository is
+`zktx-mcp/sui-mcp`. The previous package is `@zktx.io/say-ur-intent` (through
+0.4.4). The older `@stelis/say-ur-intent@0.4.0` is also a separate package.
+Existing installations and MCP client registrations do not change names
+automatically. Before switching, confirm the new package with
+`npm view @zktx.io/sui-mcp@0.5.0 version`; renaming the repository does not publish
+an npm package or MCP Registry entry.
+
+Use the full scoped package name: the unscoped `sui-mcp` package is a different
+project. Keep the MCP registration name `sui-mcp`, without a suffix. This release
+starts with a new local data directory and does not import or
+convert data from the previous package. See the
+[setup guide](docs/MCP_SETUP.md#switching-the-installed-package) for installation
+and shared-server restart instructions.
+
+After the MCP server is connected, use [docs/MCP_SETUP.md](docs/MCP_SETUP.md#first-use-flow) for first-use setup, [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) for API fields and statuses, and [docs/AGENT_BEHAVIOR.md](docs/AGENT_BEHAVIOR.md) for user-question flow and response wording.
+
+## Mainnet-Only Product Surface
+
+Product docs, registry, AI responses, UX copy, and signable actions are mainnet-only.
+
+Unsupported protocol experiments are not product functionality and are not included in the package docs, MCP resources, registry support lists, UX copy, or signable-action lists.
+
+## MCP Tools
+
+The canonical MCP API reference lives in [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).
+
+The server also exposes `read.get_server_status`. It returns the package version, evidence policy version, `implementedToolsCount`, and implemented tool list at runtime.
+
+DeepBook pool-price context is exposed through `read.get_deepbook_mid_price`. Use `docs/MCP_TOOLS.md` for the response fields and unsupported conclusions.
+
+Tool names use dot prefixes because the MCP spec recommends ASCII letters, digits, underscore, hyphen, and dot for tool names. `action.prepare_sui_action_review` returns a `reviewSessionId` and an internal `card`; it does not return executable transaction bytes.
+
+## Documentation Map
+
+The server exposes only a subset of repository documents as MCP resources.
+
+Runtime-facing MCP resources currently include:
+
+- this README;
+- `docs/MCP_SETUP.md`;
+- `docs/MCP_TOOLS.md`;
+- `docs/WALLET_CONNECTION.md`;
+- `docs/AGENT_BEHAVIOR.md`;
+- `protocols/deepbook-v3.md`;
+- `protocols/deepbook-margin.md`.
+
+Protocol resources are explanatory references. Current support is declared by `read.get_server_status`, `read.list_supported_protocols`, concrete tool schemas, and concrete tool responses, not by protocol Markdown alone.
+
+Development-only or release-review documents can define contributor rules and checks.
+
+AI client answer behavior must be mirrored in runtime-facing instructions, resources, prompts, schemas, or returned evidence fields before it is treated as product behavior.
+
+- `README.md`: Public entry document: product purpose, current release boundary, setup path, and documentation map.
+- `docs/MCP_SETUP.md`: Setup guide: installation, MCP client connection, first-use flow, settings, and troubleshooting.
+- `docs/MCP_TOOLS.md`: API reference: tool contracts, response fields, statuses, follow-up fields, and output boundaries.
+- `docs/AGENT_BEHAVIOR.md`: Answer playbook: user-question flows, tool selection, and response wording boundaries.
+- `docs/WALLET_CONNECTION.md`: Wallet connection reference: active read context, private SDK ownership and user-approved transaction requests.
+- `protocols/deepbook-v3.md`: Protocol reference only; use MCP tool responses and read.list_supported_protocols for current support.
+- `protocols/deepbook-margin.md`: Protocol reference only; no margin MCP read tools or signable actions are exposed in this release.
+- `docs/golden-scenarios/INTENT_EVIDENCE_MATRIX.md`: current-release question, tool-path, and standard-answer matrix for AI client release review.
+- `docs/golden-scenarios/BEHAVIOR_MATRIX.md`: broader behavior scenario matrix for supported and unsupported user prompts.
+- `docs/TRANSACTION_ACTIVITY_LOG.md`: transaction activity evidence, storage, scan, and summary boundaries.
+- `docs/UTILITY_INDEX.md`: manual maintainer and developer utilities. Utility rows are not MCP tools unless they explicitly name an MCP tool, and source-checkout scripts are not packaged product commands.
+- `docs/LOCAL_DB_ARCHITECTURE.md`: local SQLite storage boundaries for maintainers.
+- `docs/SDK_API.md`: pinned SDK API notes and source-verification boundaries.
+- `docs/FRONTEND_POLICY.md`: review-app frontend implementation policy for coding agents.
+- `docs/SIGNABLE_ADAPTER_CONTRACT.md`: wallet-review adapter and PTB visualization contract. It defines the pre-signing review evidence and commitment boundary; wallet signing requires a user card action and approval in the wallet; the backend alone handles bytes.
+- `AGENTS.md`: root repository development contract and non-negotiable product boundaries for coding agents working on this codebase.
+- `docs/AGENT_DEVELOPMENT_POLICY.md`: detailed binding development, review, documentation, source-of-truth, and completion policies for coding agents.
+
+## Contract Name Registry
+
+The PTB visualization in the Review card can show human-readable labels in place
+of raw addresses, with a toggle back to raw addresses. A label is identity display only, not a
+safety, trust, route-quality, or signing-readiness signal, and only registered
+addresses are relabeled.
+
+Two pinned, context-aware registries in
+[`src/core/action/contractNameRegistry.ts`](src/core/action/contractNameRegistry.ts)
+drive this:
+
+- packages, relabeled only in `<address>::` path position — the DeepBook swap
+  package by its Move Registry (MVR) name `@deepbook/core`, and the Sui framework
+  packages by their Move aliases (`std`, `sui`, `sui_system`);
+- well-known Sui system objects, relabeled only as a bare object id — `Clock`,
+  `SuiSystemState`, `Random`, `DenyList`, `CoinRegistry`, and the address-based
+  balance `AccumulatorRoot`.
+
+If you maintain a Sui DeFi protocol that has a registered MVR name and want its
+package to display that name in the review graph, open a pull request adding your
+mainnet package address and MVR name to the package registry. Every unregistered
+address keeps its raw form.

package/dist/adapters/adapterLifecycleValidators.js

@@ -0,0 +1,5 @@
+import { DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID, validateDeepbookSwapReviewLifecycle } from "./deepbook/deepbookReviewLifecycle.js";
+import { createAdapterLifecycleValidator } from "../core/action/adapterLifecycleValidation.js";
+export const validateSupportedAdapterLifecycle = createAdapterLifecycleValidator({
+    [DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID]: validateDeepbookSwapReviewLifecycle
+});

package/dist/adapters/adapterPromptSurfaces.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { DEEPBOOK_SWAP_ACTION_KIND, DEEPBOOK_SWAP_ADAPTER_ID } from "./deepbook/deepbookSwapIntent.js";
+/**
+ * One slash-prompt surface contributed by a review adapter.
+ *
+ * Prompt names follow action-first naming: `<action>-<protocolSlug>`
+ * (for example `swap-deep`). Users reach for the verb before the venue, so
+ * action-first keeps autocomplete grouped by what the user wants to do. When
+ * an action has exactly one registered protocol, the bare action name (for
+ * example `swap`) is also registered as a shorthand.
+ *
+ * The surface carries only protocol-specific copy. Boundary language (no
+ * signing data, no transaction bytes, local-review-only signing) is owned by
+ * the platform and appended at registration time; adapters cannot weaken it.
+ */
+export const adapterPromptSurfaceSchema = z
+    .object({
+    adapterId: z.string().min(1),
+    action: z
+        .string()
+        .regex(/^[a-z][a-z0-9]*$/, "action must be a lowercase slug, e.g. swap"),
+    protocolSlug: z
+        .string()
+        .regex(/^[a-z][a-z0-9]*$/, "protocolSlug must be a lowercase slug, e.g. deep"),
+    title: z.string().min(1),
+    description: z.string().min(1),
+    intentArgDescription: z.string().min(1),
+    exampleIntents: z.array(z.string().min(1)).min(1),
+    toolName: z.string().min(1)
+})
+    .strict();
+export function promptNameFor(surface) {
+    return `${surface.action}-${surface.protocolSlug}`;
+}
+/**
+ * Bare action prompts (`swap`) are always registered. With a single
+ * registered protocol they go straight to that protocol; with several they
+ * carry an optional `protocol` argument (completion suggests the slugs) and
+ * instruct the model to ask the user which protocol to use - never to pick a
+ * venue silently.
+ */
+export function actionGroups(surfaces) {
+    const byAction = new Map();
+    for (const surface of surfaces) {
+        byAction.set(surface.action, [...(byAction.get(surface.action) ?? []), surface]);
+    }
+    return byAction;
+}
+export const ADAPTER_PROMPT_SURFACES = [
+    {
+        adapterId: DEEPBOOK_SWAP_ADAPTER_ID,
+        action: DEEPBOOK_SWAP_ACTION_KIND,
+        protocolSlug: "deep",
+        title: "DeepBook Swap Review",
+        description: 'Prepare a reviewable DeepBook mainnet swap from a one-line intent, e.g. "10 sui to usdc".',
+        intentArgDescription: 'Swap intent in one line, any language, e.g. "10 sui to usdc" or "10 수이 usdc로 환전"',
+        exampleIntents: ["10 sui to usdc", "10 수이 usdc로 환전"],
+        toolName: "action.prepare_sui_action_review"
+    }
+];

package/dist/adapters/deepbook/deepbookHumanReviewProducer.js

@@ -0,0 +1,178 @@
+import { transactionFundingSummary } from "../../core/action/transactionFunding.js";
+import { createSwapHumanReadableReviewEvidence } from "../../core/action/swapHumanReadableReviewProjection.js";
+import { failReviewCheck, passReviewCheck } from "../../core/review/reviewComputationResult.js";
+export function createDeepbookSwapHumanReadableReviewProducer() {
+    return (input) => {
+        try {
+            assertDeepbookHumanReviewSources(input);
+            const review = buildDeepbookHumanReadableReview(input);
+            const evidence = createSwapHumanReadableReviewEvidence({
+                transactionMaterial: input.transactionMaterial,
+                transactionMaterialDigest: input.transactionMaterialDigest,
+                swapQuotePolicy: input.swapQuotePolicy,
+                transactionObjectOwnership: input.transactionObjectOwnership,
+                adapterId: input.plan.adapterId,
+                protocol: input.plan.protocol,
+                actionKind: input.plan.actionKind,
+                review,
+                derivedAt: input.now
+            });
+            return {
+                status: "completed",
+                evidence,
+                checks: [
+                    passReviewCheck("deepbook_human_readable_review_evidence", "Readable transaction details", "Prepared the amounts and transaction details for this account from the verified quote, transaction and object owners. These details do not authorize wallet approval or guarantee execution.", "adapter")
+                ]
+            };
+        }
+        catch (error) {
+            return {
+                status: "blocked",
+                blockedReason: classifyHumanReviewFailure(error),
+                checks: [
+                    failReviewCheck("deepbook_human_readable_review_failed", "Readable transaction details", error instanceof Error ? error.message : "The transaction details could not be prepared for this account.", "adapter")
+                ]
+            };
+        }
+    };
+}
+function buildDeepbookHumanReadableReview(input) {
+    const sourceAmount = amountFromQuotePolicy("input", input.swapQuotePolicy.sourceAmount, {
+        displayAmount: input.requestedIntent.from.amountDisplay,
+        displayAmountSource: "user_display_intent_not_signing_input"
+    });
+    const expectedOutput = amountFromQuotePolicy("expected_output", input.swapQuotePolicy.expectedOutput);
+    const minimumOutput = amountFromQuotePolicy("minimum_output", input.swapQuotePolicy.minimumOutput);
+    const protocolFee = amountFromQuotePolicy("fee", input.swapQuotePolicy.protocolFee);
+    return {
+        kind: "swap_human_readable_review",
+        proposedAction: {
+            title: input.plan.title,
+            summary: input.plan.summary,
+            actionKind: input.plan.actionKind,
+            adapterId: input.plan.adapterId,
+            protocol: input.plan.protocol,
+            network: "sui:mainnet"
+        },
+        assetFlow: {
+            outgoing: [sourceAmount],
+            expectedIncoming: [expectedOutput],
+            minimumIncoming: [minimumOutput],
+            fees: [protocolFee]
+        },
+        recipients: [
+            { role: "connected_account", address: input.account },
+            { role: "output_recipient", address: input.account }
+        ],
+        targets: [
+            {
+                kind: "swap_output_asset",
+                symbol: input.swapQuotePolicy.expectedOutput.asset.symbol,
+                coinType: input.swapQuotePolicy.expectedOutput.asset.coinType,
+                protocol: input.plan.protocol,
+                poolKey: input.swapQuotePolicy.quoteSource.poolKey,
+                direction: input.swapQuotePolicy.quoteSource.direction
+            }
+        ],
+        evidenceUsed: [
+            { id: "transaction_funding", label: "Transaction funding", source: "transaction_material",
+                summary: transactionFundingSummary(input.transactionObjectOwnership.funding) },
+            {
+                id: "deepbook_quote_policy",
+                label: "Quote and slippage rules",
+                source: "quote",
+                summary: "The quote and its rules supply the send amount, expected and minimum receive amounts, trading fee, and slippage limit shown here. They do not choose a route or establish permission to sign."
+            },
+            {
+                id: "transaction_material_digest",
+                label: "Transaction identity (digest)",
+                source: "digest_commitment",
+                summary: "This review is tied to the exact unsigned transaction stored by Sui MCP through its verification digest. The private transaction bytes are not included in the card."
+            },
+            {
+                id: "transaction_object_ownership",
+                label: "Object ownership",
+                source: "wallet",
+                summary: "The transaction objects and their owners were checked using the stored transaction and Sui mainnet data."
+            }
+        ],
+        missingEvidence: [
+            {
+                id: "review_time_simulation",
+                label: "Review-time simulation",
+                reason: "At this step, the stored transaction has not yet been simulated to check its effects, balance changes, object types, and transaction details."
+            }
+        ],
+        requiredUserChoices: [
+            {
+                id: "wallet_authorization_later",
+                label: "Wallet approval required",
+                reason: "The backend requests a signature only after your explicit Review card action; nothing is signed without your approval in the wallet."
+            }
+        ],
+        unsupportedClaims: [
+            {
+                id: "no_signing_readiness",
+                label: "Wallet approval not established",
+                reason: "These review details alone do not establish permission to request a wallet signature."
+            },
+            {
+                id: "no_execution_readiness",
+                label: "Execution not confirmed",
+                reason: "At this step, simulation, wallet approval, signing, and confirmation of the transaction result are not complete."
+            },
+            {
+                id: "no_route_recommendation",
+                label: "No route recommendation",
+                reason: "The account-bound swap review uses an explicit direct pool path and does not rank venues or recommend routes."
+            }
+        ],
+        freshness: {
+            status: "current",
+            evaluatedAt: input.now.toISOString(),
+            expiresAt: input.transactionMaterial.expiresAt,
+            reason: "These details expire with the transaction and quote used to prepare them."
+        },
+        blockingChecks: [
+            failReviewCheck("deepbook_review_time_simulation_missing", "Review-time simulation", "Review-time simulation evidence is still required before any wallet handoff, signing, or execution.", "simulation")
+        ]
+    };
+}
+function assertDeepbookHumanReviewSources(input) {
+    if (input.swapQuotePolicy.adapterId !== input.plan.adapterId ||
+        input.swapQuotePolicy.protocol !== input.plan.protocol ||
+        input.swapQuotePolicy.actionKind !== input.plan.actionKind) {
+        throw new Error("human-readable review quote policy identity must match the action plan");
+    }
+    if (input.swapQuotePolicy.quoteSource.poolKey !== input.poolResolution.poolKey) {
+        throw new Error("human-readable review pool target must match swap quote policy poolKey");
+    }
+    if (input.swapQuotePolicy.quoteSource.direction !== input.quotePolicy.direction) {
+        throw new Error("human-readable review target direction must match swap quote policy direction");
+    }
+}
+function classifyHumanReviewFailure(error) {
+    const message = error instanceof Error ? error.message : "";
+    if (/object ownership/i.test(message)) {
+        return "object_resolution_failed";
+    }
+    if (/asset|target|pool|direction|protocol|adapter/i.test(message)) {
+        return "asset_mismatch";
+    }
+    if (/amount|quote|slippage|min/i.test(message)) {
+        return "amount_mismatch";
+    }
+    return "unsupported_action";
+}
+function amountFromQuotePolicy(role, amount, display) {
+    return {
+        role,
+        symbol: amount.asset.symbol,
+        coinType: amount.asset.coinType,
+        decimals: amount.asset.decimals,
+        rawAmount: amount.raw,
+        rawAmountSource: "quote_policy_evidence",
+        ...(display?.displayAmount ? { displayAmount: display.displayAmount } : {}),
+        ...(display?.displayAmountSource ? { displayAmountSource: display.displayAmountSource } : {})
+    };
+}

package/dist/adapters/deepbook/deepbookQuotePolicy.js

@@ -0,0 +1,112 @@
+import { parseDeepbookRawU64 } from "../../core/read/deepbookReadHelpers.js";
+export const DEEPBOOK_REVIEW_QUOTE_STALE_AFTER_MS = 30_000;
+// Same-machine pipelines capture `now` before the network quote fetch, so the
+// fetch timestamp can land a few hundred milliseconds "in the future". Treat
+// skew within this tolerance as a fresh quote (age 0) and record the skew;
+// anything beyond it is a real clock-integrity violation and refuses.
+export const DEEPBOOK_QUOTE_FUTURE_SKEW_TOLERANCE_MS = 5_000;
+export const DEEPBOOK_MAX_SLIPPAGE_BPS = 1000;
+export const DEEPBOOK_MIN_SLIPPAGE_BPS = 1;
+const BPS_DENOMINATOR = 10000n;
+export function deriveDeepbookSwapQuotePolicy(input) {
+    assertSlippageBps(input.maxSlippageBps);
+    const staleAfterMs = input.staleAfterMs ?? DEEPBOOK_REVIEW_QUOTE_STALE_AFTER_MS;
+    if (!Number.isInteger(staleAfterMs) || staleAfterMs < 1) {
+        throw new Error("staleAfterMs must be a positive integer");
+    }
+    const fetchedAtMs = parseIsoUtcTimestampMs(input.fetchedAt, "fetchedAt");
+    const nowMs = parseValidDateMs(input.now, "now");
+    const rawQuoteAgeMs = nowMs - fetchedAtMs;
+    const direction = directionFromRawQuote(input.rawQuote);
+    if (rawQuoteAgeMs < -DEEPBOOK_QUOTE_FUTURE_SKEW_TOLERANCE_MS) {
+        return {
+            status: "refresh_required",
+            refreshReason: "quote_stale",
+            reason: "quote_timestamp_in_future",
+            direction,
+            fetchedAt: input.fetchedAt,
+            quoteAgeMs: 0,
+            staleAfterMs,
+            clockSkewMs: -rawQuoteAgeMs
+        };
+    }
+    const clockSkewMs = rawQuoteAgeMs < 0 ? -rawQuoteAgeMs : undefined;
+    const quoteAgeMs = rawQuoteAgeMs < 0 ? 0 : rawQuoteAgeMs;
+    if (quoteAgeMs > staleAfterMs) {
+        return {
+            status: "refresh_required",
+            refreshReason: "quote_stale",
+            reason: "quote_stale",
+            direction,
+            fetchedAt: input.fetchedAt,
+            quoteAgeMs,
+            staleAfterMs
+        };
+    }
+    const expectedOut = parseUnsignedRaw(input.rawQuote.directionalOutput.raw, "directionalOutput.raw");
+    if (expectedOut === 0n) {
+        return unavailableQuote(input, direction, quoteAgeMs, staleAfterMs, "zero_expected_output");
+    }
+    const minOut = (expectedOut * (BPS_DENOMINATOR - BigInt(input.maxSlippageBps))) / BPS_DENOMINATOR;
+    if (minOut === 0n) {
+        return unavailableQuote(input, direction, quoteAgeMs, staleAfterMs, "zero_min_out");
+    }
+    return {
+        status: "ok",
+        direction,
+        quoteFresh: true,
+        fetchedAt: input.fetchedAt,
+        quoteAgeMs,
+        staleAfterMs,
+        ...(clockSkewMs !== undefined ? { clockSkewMs } : {}),
+        feeMode: input.feeMode ?? "deep",
+        maxSlippageBps: input.maxSlippageBps,
+        sourceAmountRaw: parsePositiveRaw(input.rawQuote.inputAmount.raw, "inputAmount.raw").toString(),
+        expectedOutRaw: expectedOut.toString(),
+        minOutRaw: minOut.toString(),
+        deepAmountRaw: parseUnsignedRaw(input.rawQuote.deepRequired.raw, "deepRequired.raw").toString()
+    };
+}
+function assertSlippageBps(value) {
+    if (!Number.isInteger(value) || value < DEEPBOOK_MIN_SLIPPAGE_BPS || value > DEEPBOOK_MAX_SLIPPAGE_BPS) {
+        throw new Error(`maxSlippageBps must be an integer from ${DEEPBOOK_MIN_SLIPPAGE_BPS} to ${DEEPBOOK_MAX_SLIPPAGE_BPS}`);
+    }
+}
+function parseIsoUtcTimestampMs(value, field) {
+    const parsed = new Date(value);
+    const timestampMs = parsed.getTime();
+    if (!Number.isFinite(timestampMs) || parsed.toISOString() !== value) {
+        throw new Error(`${field} must be an ISO 8601 UTC timestamp`);
+    }
+    return timestampMs;
+}
+function parseValidDateMs(value, field) {
+    if (!(value instanceof Date)) {
+        throw new Error(`${field} must be a valid Date`);
+    }
+    const timestampMs = value.getTime();
+    if (!Number.isFinite(timestampMs)) {
+        throw new Error(`${field} must be a valid Date`);
+    }
+    return timestampMs;
+}
+function directionFromRawQuote(rawQuote) {
+    return rawQuote.sourceMoveFunction.startsWith("pool::get_quote_quantity_out") ? "base_to_quote" : "quote_to_base";
+}
+function unavailableQuote(input, direction, quoteAgeMs, staleAfterMs, reason) {
+    return {
+        status: "refresh_required",
+        refreshReason: "quote_unavailable",
+        reason,
+        direction,
+        fetchedAt: input.fetchedAt,
+        quoteAgeMs,
+        staleAfterMs
+    };
+}
+function parsePositiveRaw(value, field) {
+    return parseDeepbookRawU64(value, field, { positive: true });
+}
+function parseUnsignedRaw(value, field) {
+    return parseDeepbookRawU64(value, field);
+}