@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/adapters/deepbook/deepbookReviewEvidence.js

@@ -0,0 +1,507 @@
+import { deepbookSwapActionPlanDataSchema } from "./deepbookSwapIntent.js";
+import { deriveDeepbookSwapQuotePolicy } from "./deepbookQuotePolicy.js";
+import { deepbookSwapReviewLifecycleStageLabel, newDeepbookSwapReviewLifecycle } from "./deepbookReviewLifecycle.js";
+import { createSwapQuotePolicyEvidence } from "../../core/action/swapQuotePolicyEvidence.js";
+import { publicHumanReadableReviewFromEvidence } from "../../core/action/humanReadableReviewEvidence.js";
+import { publicTransactionSimulationSummaryFromEvidence } from "../../core/action/reviewTimeSimulationEvidence.js";
+import { ReadServiceInputError } from "../../core/read/readServiceTypes.js";
+import { resolveDeepbookPoolForSymbols } from "../../core/read/deepbookRegistry.js";
+import { blockedAdapterLifecycleReviewResult, failReviewCheck, passReviewCheck, producerStageMissingReviewResult, refreshRequiredAdapterLifecycleReviewResult, walletReviewContractEmitMissingResult, walletReviewContractEmittedResult } from "../../core/review/reviewComputationResult.js";
+import { assembleWalletReviewAdapterContract } from "../../core/action/walletReviewContractAssembler.js";
+export async function computeDeepbookSwapReviewEvidence(input) {
+    const lifecycle = newDeepbookSwapReviewLifecycle(input.plan);
+    const checks = [];
+    const now = input.now ?? new Date();
+    const intentStage = await runDeepbookReviewStage({
+        lifecycle,
+        checks,
+        stage: "intent_normalized",
+        run: () => normalizeIntentStage(input.plan)
+    });
+    if (!intentStage.ok) {
+        return { result: intentStage.result };
+    }
+    const requestedIntent = intentStage.evidence;
+    const poolStage = await runDeepbookReviewStage({
+        lifecycle,
+        checks,
+        stage: "pool_resolved",
+        run: () => resolvePoolStage(requestedIntent)
+    });
+    if (!poolStage.ok) {
+        return { result: poolStage.result };
+    }
+    const poolResolution = poolStage.evidence;
+    const quoteStage = await runDeepbookReviewStage({
+        lifecycle,
+        checks,
+        stage: "quote_evidence_fetched",
+        run: () => quoteEvidenceStage(input, requestedIntent, poolResolution)
+    });
+    if (!quoteStage.ok) {
+        return { result: quoteStage.result };
+    }
+    const { quote, feeMode } = quoteStage.evidence;
+    const policyStage = await runDeepbookReviewStage({
+        lifecycle,
+        checks,
+        stage: "quote_policy_derived",
+        run: () => quotePolicyStage(input, requestedIntent, quote, feeMode, now)
+    });
+    if (!policyStage.ok) {
+        return { result: policyStage.result };
+    }
+    const quotePolicy = policyStage.evidence;
+    if (!input.transactionMaterialProducer) {
+        return {
+            result: missingProducerStageBlockedResult(lifecycle.snapshot(), checks)
+        };
+    }
+    const materialStage = await runDeepbookReviewStage({
+        lifecycle,
+        checks,
+        stage: "transaction_material_build_or_verify",
+        run: () => input.transactionMaterialProducer({
+            reviewSessionId: input.reviewSessionId,
+            plan: input.plan,
+            account: input.account,
+            requestedIntent,
+            poolResolution,
+            quote,
+            quotePolicy,
+            now
+        })
+    });
+    if (!materialStage.ok) {
+        return { result: materialStage.result };
+    }
+    if (!input.transactionMaterialDigestProducer) {
+        return {
+            result: missingProducerStageBlockedResult(lifecycle.snapshot(), checks)
+        };
+    }
+    const digestStage = await runDeepbookReviewStage({
+        lifecycle,
+        checks,
+        stage: "digest_commitment",
+        run: () => input.transactionMaterialDigestProducer({
+            materialHandle: materialStage.evidence,
+            now
+        })
+    });
+    if (!digestStage.ok) {
+        return { result: digestStage.result };
+    }
+    let swapQuotePolicy;
+    try {
+        swapQuotePolicy = createSwapQuotePolicyEvidence({
+            materialHandle: materialStage.evidence,
+            adapterId: input.plan.adapterId,
+            protocol: input.plan.protocol,
+            actionKind: input.plan.actionKind,
+            quoteEvidenceId: `deepbook_raw_quote:${input.plan.id}`,
+            quoteSource: {
+                provider: input.plan.protocol,
+                poolKey: poolResolution.poolKey,
+                direction: quotePolicy.direction,
+                fetchedAt: quotePolicy.fetchedAt,
+                sourceMoveFunction: quote.rawQuote.sourceMoveFunction
+            },
+            maxSlippageBps: quotePolicy.maxSlippageBps,
+            staleAfterMs: quotePolicy.staleAfterMs,
+            sourceAmount: quotePolicyAmount(quote.rawQuote.inputAmount),
+            expectedOutput: quotePolicyAmount(quote.rawQuote.directionalOutput),
+            minimumOutput: {
+                raw: quotePolicy.minOutRaw,
+                asset: quotePolicyAmount(quote.rawQuote.directionalOutput).asset
+            },
+            protocolFee: quotePolicyAmount(quote.rawQuote.deepRequired),
+            // The pipeline anchor `now` is captured before the network quote fetch,
+            // so anchor derivedAt at the quote timestamp when the fetch lands later.
+            derivedAt: new Date(Math.max(now.getTime(), Date.parse(quotePolicy.fetchedAt)))
+        });
+    }
+    catch (error) {
+        checks.push(failReviewCheck("deepbook_quote_policy_material_binding_failed", "Quote policy material binding", error instanceof Error ? error.message : "DeepBook quote policy evidence did not match the stored transaction material.", "quote"));
+        return {
+            result: blockedAdapterLifecycleReviewResult("amount_mismatch", checks, lifecycle.snapshot())
+        };
+    }
+    const privateArtifacts = {
+        transactionMaterial: materialStage.evidence,
+        transactionMaterialDigest: digestStage.evidence,
+        swapQuotePolicy
+    };
+    // Render the PTB visualization as soon as material and digest exist, so the
+    // review page can draw the transaction even when a later stage stops the
+    // review. The artifact is commitment-bound at production and carries no
+    // digest or bytes.
+    let ptbVisualization;
+    if (input.ptbVisualizationProducer) {
+        const rendered = await input.ptbVisualizationProducer({
+            transactionMaterial: materialStage.evidence,
+            transactionMaterialDigest: digestStage.evidence,
+            adapterId: input.plan.adapterId,
+            planId: input.plan.id,
+            now
+        });
+        if (rendered.status === "rendered") {
+            ptbVisualization = rendered.artifact;
+            checks.push(ptbVisualizationRenderedCheck());
+        }
+        else {
+            checks.push(ptbVisualizationUnavailableCheck(rendered.reason));
+        }
+    }
+    const withPtb = (result) => ptbVisualization ? { ...result, ptbVisualization } : result;
+    if (!input.transactionObjectOwnershipProducer) {
+        return {
+            result: withPtb(missingProducerStageBlockedResult(lifecycle.snapshot(), checks)),
+            privateArtifacts
+        };
+    }
+    const ownershipStage = await runDeepbookReviewStage({
+        lifecycle,
+        checks,
+        stage: "object_ownership",
+        run: () => input.transactionObjectOwnershipProducer({
+            materialHandle: materialStage.evidence,
+            materialDigest: digestStage.evidence,
+            now
+        })
+    });
+    if (!ownershipStage.ok) {
+        return {
+            result: withPtb(ownershipStage.result),
+            ...(ownershipStage.result.status === "refresh_required" ? {} : { privateArtifacts })
+        };
+    }
+    privateArtifacts.transactionObjectOwnership = ownershipStage.evidence;
+    if (!input.humanReadableReviewProducer) {
+        return {
+            result: withPtb(missingProducerStageBlockedResult(lifecycle.snapshot(), checks)),
+            privateArtifacts
+        };
+    }
+    const humanReviewStage = await runDeepbookReviewStage({
+        lifecycle,
+        checks,
+        stage: "human_readable_review",
+        run: () => input.humanReadableReviewProducer({
+            plan: input.plan,
+            account: input.account,
+            requestedIntent,
+            poolResolution,
+            quotePolicy,
+            transactionMaterial: materialStage.evidence,
+            transactionMaterialDigest: digestStage.evidence,
+            swapQuotePolicy,
+            transactionObjectOwnership: ownershipStage.evidence,
+            now
+        })
+    });
+    if (!humanReviewStage.ok) {
+        return {
+            result: withPtb(humanReviewStage.result),
+            privateArtifacts
+        };
+    }
+    privateArtifacts.humanReadableReview = humanReviewStage.evidence;
+    if (!input.reviewTimeSimulationProducer) {
+        return {
+            result: withPtb(missingProducerStageBlockedResult(lifecycle.snapshot(), checks, {
+                humanReadableReview: publicHumanReadableReviewFromEvidence(humanReviewStage.evidence)
+            })),
+            privateArtifacts
+        };
+    }
+    const simulationStage = await runDeepbookReviewStage({
+        lifecycle,
+        checks,
+        stage: "review_time_simulation",
+        run: () => input.reviewTimeSimulationProducer({
+            transactionMaterial: materialStage.evidence,
+            transactionMaterialDigest: digestStage.evidence,
+            now
+        })
+    });
+    if (!simulationStage.ok) {
+        return {
+            // Keep the public projection paired with the stored private evidence:
+            // the human-readable review stays visible while simulation asks for a
+            // refresh, and the store's projection binding stays satisfied.
+            result: withPtb({
+                ...simulationStage.result,
+                humanReadableReview: publicHumanReadableReviewFromEvidence(humanReviewStage.evidence)
+            }),
+            privateArtifacts
+        };
+    }
+    privateArtifacts.reviewTimeSimulation = simulationStage.evidence;
+    const assembly = assembleWalletReviewAdapterContract({
+        adapterId: input.plan.adapterId,
+        protocol: input.plan.protocol,
+        actionKind: input.plan.actionKind,
+        provenance: {
+            kind: "mcp_action_request",
+            sourceId: input.plan.id,
+            capturedAt: input.plan.createdAt
+        },
+        quotePolicy: swapQuotePolicy,
+        objectOwnership: ownershipStage.evidence,
+        humanReadableReview: humanReviewStage.evidence,
+        reviewTimeSimulation: simulationStage.evidence,
+        transactionMaterialCommitment: digestStage.evidence.transactionDigest,
+        now
+    });
+    if (assembly.status === "emitted") {
+        checks.push(contractEmittedCheck());
+        return {
+            result: walletReviewContractEmittedResult(checks, lifecycle.snapshot(), publicHumanReadableReviewFromEvidence(humanReviewStage.evidence), publicTransactionSimulationSummaryFromEvidence(simulationStage.evidence), assembly.contract, ptbVisualization),
+            privateArtifacts
+        };
+    }
+    checks.push(contractEmitDeclinedCheck(assembly.reason));
+    return {
+        result: walletReviewContractEmitMissingResult(checks, lifecycle.snapshot(), publicHumanReadableReviewFromEvidence(humanReviewStage.evidence), publicTransactionSimulationSummaryFromEvidence(simulationStage.evidence)),
+        privateArtifacts
+    };
+}
+async function runDeepbookReviewStage(input) {
+    const outcome = await input.run();
+    input.checks.push(...outcome.checks);
+    if (outcome.status === "completed") {
+        input.lifecycle.complete(input.stage);
+        return { ok: true, evidence: outcome.evidence };
+    }
+    const adapterLifecycle = input.lifecycle.snapshot();
+    if (outcome.status === "blocked") {
+        return {
+            ok: false,
+            result: blockedAdapterLifecycleReviewResult(outcome.blockedReason, input.checks, adapterLifecycle)
+        };
+    }
+    return {
+        ok: false,
+        result: refreshRequiredAdapterLifecycleReviewResult(outcome.refreshReason, input.checks, adapterLifecycle)
+    };
+}
+function normalizeIntentStage(plan) {
+    const parsedData = deepbookSwapActionPlanDataSchema.safeParse(plan.adapterData);
+    if (!parsedData.success) {
+        return {
+            status: "blocked",
+            blockedReason: "unsupported_action",
+            checks: [
+                failReviewCheck("deepbook_requested_intent_invalid", "Requested DeepBook intent", "The action plan does not contain a valid DeepBook swap display intent.", "adapter")
+            ]
+        };
+    }
+    const requestedIntent = parsedData.data.requestedIntent;
+    return {
+        status: "completed",
+        evidence: requestedIntent,
+        checks: [
+            passReviewCheck("deepbook_display_intent", "Display intent", `Requested display intent is ${requestedIntent.from.amountDisplay} ${requestedIntent.from.symbol} to ${requestedIntent.to.symbol} with max slippage ${requestedIntent.maxSlippageBps} bps. This display amount is not signing input.`, "adapter")
+        ]
+    };
+}
+function resolvePoolStage(requestedIntent) {
+    try {
+        const poolResolution = resolveDeepbookPoolForSymbols({
+            sourceSymbol: requestedIntent.from.symbol,
+            targetSymbol: requestedIntent.to.symbol
+        });
+        return {
+            status: "completed",
+            evidence: poolResolution,
+            checks: [
+                passReviewCheck("deepbook_pool_resolution", "DeepBook pool", `Resolved direct DeepBook pool ${poolResolution.poolKey} for ${poolResolution.sourceSymbol} to ${poolResolution.targetSymbol}; direction is ${poolResolution.direction}.`, "registry")
+            ]
+        };
+    }
+    catch (error) {
+        return {
+            status: "blocked",
+            blockedReason: "asset_mismatch",
+            checks: [
+                failReviewCheck("deepbook_pool_resolution_failed", "DeepBook pool", error instanceof Error ? error.message : "DeepBook pool resolution failed.", "registry")
+            ]
+        };
+    }
+}
+async function quoteEvidenceStage(input, requestedIntent, poolResolution) {
+    try {
+        const fetchQuote = (feeMode) => input.quoteSource.quoteDeepbookDisplayAmount({
+            poolKey: poolResolution.poolKey,
+            direction: poolResolution.direction,
+            amountDisplay: requestedIntent.from.amountDisplay,
+            simulationSender: input.account,
+            feeMode
+        });
+        let feeMode = "deep";
+        let feeModeMessage = "Fee mode is deep: no DEEP balance source is wired, so the review quotes DeepBook fees in DEEP.";
+        let quote = await fetchQuote("deep");
+        if (input.deepBalanceSource) {
+            const deepBalanceRaw = BigInt(await input.deepBalanceSource(input.account));
+            const deepRequiredRaw = BigInt(quote.rawQuote.deepRequired.raw);
+            if (deepBalanceRaw >= deepRequiredRaw) {
+                feeModeMessage = `Fee mode is deep: account DEEP balance ${deepBalanceRaw} raw covers the required ${deepRequiredRaw} raw fee.`;
+            }
+            else {
+                feeMode = "input_coin";
+                quote = await fetchQuote("input_coin");
+                feeModeMessage = `Fee mode is input_coin: account DEEP balance ${deepBalanceRaw} raw is below the required ${deepRequiredRaw} raw fee, so the swap pays the taker fee in the source coin at the protocol fee penalty. The quoted output already reflects that fee.`;
+            }
+        }
+        return {
+            status: "completed",
+            evidence: { quote, feeMode },
+            checks: [
+                passReviewCheck("deepbook_raw_quote_evidence", "Raw quote evidence", `Fetched raw DeepBook quote evidence at ${quote.fetchedAt} from ${quote.rawQuote.sourceMoveFunction}; expected output before slippage is ${quote.rawQuote.directionalOutput.raw} ${quote.rawQuote.directionalOutput.symbol} raw units and DEEP fee evidence is ${quote.rawQuote.deepRequired.raw} raw units.`, "quote"),
+                passReviewCheck("deepbook_fee_mode", "Fee mode", feeModeMessage, "quote")
+            ]
+        };
+    }
+    catch (error) {
+        return quoteSourceFailureOutcome(error);
+    }
+}
+function quotePolicyStage(input, requestedIntent, quote, feeMode, now) {
+    let policy;
+    try {
+        policy = deriveDeepbookSwapQuotePolicy({
+            rawQuote: quote.rawQuote,
+            fetchedAt: quote.fetchedAt,
+            maxSlippageBps: requestedIntent.maxSlippageBps,
+            feeMode,
+            now
+        });
+    }
+    catch (error) {
+        return {
+            status: "blocked",
+            blockedReason: "amount_mismatch",
+            checks: [
+                failReviewCheck("deepbook_quote_policy_invalid", "Quote policy", error instanceof Error ? error.message : "DeepBook quote policy could not be derived.", "quote")
+            ]
+        };
+    }
+    if (policy.status === "refresh_required") {
+        return {
+            status: "refresh_required",
+            refreshReason: policy.refreshReason,
+            checks: [
+                failReviewCheck("deepbook_quote_policy_refresh_required", "Quote policy", `Quote policy requires refresh: ${policy.reason}. Quote age is ${policy.quoteAgeMs}ms with stale threshold ${policy.staleAfterMs}ms.`, "quote")
+            ]
+        };
+    }
+    return {
+        status: "completed",
+        evidence: policy,
+        checks: [
+            passReviewCheck("deepbook_quote_policy", "Quote policy", `Derived review policy from raw quote evidence: feeMode ${policy.feeMode}, sourceAmountRaw ${policy.sourceAmountRaw}, expectedOutRaw ${policy.expectedOutRaw}, minOutRaw ${policy.minOutRaw}, deepAmountRaw ${policy.deepAmountRaw}, quoteAgeMs ${policy.quoteAgeMs}. These values are review evidence only and are not transaction bytes, signing data, or signing readiness.`, "quote")
+        ]
+    };
+}
+function quotePolicyAmount(amount) {
+    return {
+        raw: amount.raw,
+        asset: {
+            symbol: amount.symbol,
+            coinType: amount.coinType,
+            decimals: amount.decimals,
+            unitSource: amount.unitSource
+        }
+    };
+}
+function quoteSourceFailureCheck(error) {
+    if (error instanceof ReadServiceInputError) {
+        return failReviewCheck("deepbook_quote_source_failed", "Quote source", error.message, "quote");
+    }
+    return failReviewCheck("deepbook_quote_source_failed", "Quote source", error instanceof Error ? error.message : "DeepBook quote source failed.", "quote");
+}
+function quoteSourceFailureOutcome(error) {
+    const checks = [quoteSourceFailureCheck(error)];
+    if (error instanceof ReadServiceInputError) {
+        if (error.kind === "input_invalid") {
+            return { status: "blocked", blockedReason: "amount_mismatch", checks };
+        }
+        if (error.kind === "registry_miss") {
+            return { status: "blocked", blockedReason: "asset_mismatch", checks };
+        }
+        if (error.kind === "quote_unavailable") {
+            return { status: "refresh_required", refreshReason: "quote_unavailable", checks };
+        }
+    }
+    return { status: "blocked", blockedReason: "object_resolution_failed", checks };
+}
+function missingProducerStageCheck(adapterLifecycle) {
+    const nextMissing = adapterLifecycle.missingStages[0];
+    if (nextMissing === undefined) {
+        return contractEmitMissingCheck();
+    }
+    const nextMissingLabel = nextMissing ? deepbookSwapReviewLifecycleStageLabel(nextMissing) : undefined;
+    return {
+        id: `deepbook_${nextMissing}_missing`,
+        label: nextMissingLabel ?? "Producer stage",
+        status: "fail",
+        message: `DeepBook account-bound review has not completed ${nextMissingLabel}. This is required before wallet handoff, signing, or execution, and no transaction bytes or signing readiness are available.`,
+        source: "adapter"
+    };
+}
+function missingProducerStageBlockedResult(adapterLifecycle, checks, fields = {}) {
+    const nextMissing = adapterLifecycle.missingStages[0];
+    if (nextMissing === undefined) {
+        if (!fields.humanReadableReview || !fields.simulation) {
+            throw new Error("wallet_review_contract_emit_missing requires human-readable review and simulation public evidence");
+        }
+        return walletReviewContractEmitMissingResult([...checks, contractEmitMissingCheck()], adapterLifecycle, fields.humanReadableReview, fields.simulation);
+    }
+    return producerStageMissingReviewResult([...checks, missingProducerStageCheck(adapterLifecycle)], adapterLifecycle, fields.humanReadableReview ? { humanReadableReview: fields.humanReadableReview } : {});
+}
+function ptbVisualizationRenderedCheck() {
+    return {
+        id: "deepbook_ptb_visualization",
+        label: "PTB visualization",
+        status: "pass",
+        message: "Rendered a Mermaid PTB visualization artifact from the stored local transaction material. Visualization only; it is not wallet authorization, not signing data, not signing readiness, and not execution readiness.",
+        source: "adapter"
+    };
+}
+function ptbVisualizationUnavailableCheck(reason) {
+    return {
+        id: "deepbook_ptb_visualization_unavailable",
+        label: "PTB visualization",
+        status: "warning",
+        message: `PTB visualization is unavailable for this review: ${reason}. The emitted wallet review contract remains valid; visualization is optional review evidence.`,
+        source: "adapter"
+    };
+}
+function contractEmittedCheck() {
+    return {
+        id: "deepbook_wallet_review_contract_emitted",
+        label: "Wallet review contract emit",
+        status: "pass",
+        message: "DeepBook account-bound review assembled and schema-validated a wallet review contract from verified review evidence. The local review page can now request the digest-gated handoff for user-controlled wallet signing; MCP output stays free of signing data.",
+        source: "adapter"
+    };
+}
+function contractEmitDeclinedCheck(reason) {
+    return {
+        id: "deepbook_wallet_review_contract_emit_missing",
+        label: "Wallet review contract emit",
+        status: "fail",
+        message: `DeepBook account-bound review could not assemble the wallet review contract from the current review evidence: ${reason}. Signing stays blocked.`,
+        source: "adapter"
+    };
+}
+function contractEmitMissingCheck() {
+    return {
+        id: "deepbook_wallet_review_contract_emit_missing",
+        label: "Wallet review contract emit",
+        status: "fail",
+        message: "DeepBook account-bound review completed review-time simulation, but this review did not assemble a wallet review contract, so signing stays blocked for this session.",
+        source: "adapter"
+    };
+}

package/dist/adapters/deepbook/deepbookReviewLifecycle.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { DEEPBOOK_SWAP_ACTION_KIND, DEEPBOOK_SWAP_ADAPTER_ID, DEEPBOOK_SWAP_PROTOCOL } from "./deepbookSwapIntent.js";
+export const DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID = "deepbook_swap_review_v1";
+export const DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGES = [
+    "intent_normalized",
+    "pool_resolved",
+    "quote_evidence_fetched",
+    "quote_policy_derived",
+    "transaction_material_build_or_verify",
+    "digest_commitment",
+    "object_ownership",
+    "human_readable_review",
+    "review_time_simulation"
+];
+export const deepbookSwapReviewLifecycleStageSchema = z.enum(DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGES);
+export const deepbookSwapReviewLifecycleSchema = z.object({
+    stageCatalogId: z.literal(DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID),
+    adapterId: z.literal(DEEPBOOK_SWAP_ADAPTER_ID),
+    protocol: z.literal(DEEPBOOK_SWAP_PROTOCOL),
+    actionKind: z.literal(DEEPBOOK_SWAP_ACTION_KIND),
+    completedStages: z.array(deepbookSwapReviewLifecycleStageSchema),
+    missingStages: z.array(deepbookSwapReviewLifecycleStageSchema)
+}).strict().superRefine((lifecycle, ctx) => {
+    const expectedCompleted = DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGES.slice(0, lifecycle.completedStages.length);
+    const expectedMissing = DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGES.slice(lifecycle.completedStages.length);
+    if (!sameStringArray(lifecycle.completedStages, expectedCompleted)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["completedStages"],
+            message: "completedStages must be the canonical DeepBook swap review lifecycle prefix"
+        });
+    }
+    if (!sameStringArray(lifecycle.missingStages, expectedMissing)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["missingStages"],
+            message: "missingStages must be the canonical DeepBook swap review lifecycle remainder"
+        });
+    }
+});
+const DEEPBOOK_SWAP_REVIEW_STAGE_LABELS = {
+    intent_normalized: "Intent normalized",
+    pool_resolved: "DeepBook pool resolved",
+    quote_evidence_fetched: "DeepBook quote evidence fetched",
+    quote_policy_derived: "Quote policy derived",
+    transaction_material_build_or_verify: "Transaction material build or verify",
+    digest_commitment: "Digest commitment",
+    object_ownership: "Object ownership",
+    human_readable_review: "Human-readable review",
+    review_time_simulation: "Review-time simulation"
+};
+export function newDeepbookSwapReviewLifecycle(plan) {
+    const completedStages = [];
+    return {
+        complete(stage) {
+            const expectedStage = DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGES[completedStages.length];
+            if (stage !== expectedStage) {
+                throw new Error(`DeepBook swap review lifecycle stage '${stage}' cannot complete before '${expectedStage ?? "none"}'.`);
+            }
+            completedStages.push(stage);
+        },
+        snapshot() {
+            return deepbookSwapReviewLifecycleSchema.parse({
+                stageCatalogId: DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID,
+                adapterId: plan.adapterId,
+                protocol: plan.protocol,
+                actionKind: plan.actionKind,
+                completedStages: [...completedStages],
+                missingStages: DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGES.filter((stage) => !completedStages.includes(stage))
+            });
+        }
+    };
+}
+export function deepbookSwapReviewLifecycleStageLabel(stage) {
+    return DEEPBOOK_SWAP_REVIEW_STAGE_LABELS[stage];
+}
+export function validateDeepbookSwapReviewLifecycle(lifecycle) {
+    deepbookSwapReviewLifecycleSchema.parse(lifecycle);
+}
+function sameStringArray(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
+}

package/dist/adapters/deepbook/deepbookSwapIntent.js

@@ -0,0 +1,79 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { accountBoundReviewRequiredCheck, signingViaLocalReviewOnlyCheck } from "../../core/review/reviewChecks.js";
+import { canonicalDeepbookSymbol } from "../../core/read/deepbookRegistry.js";
+export const DEEPBOOK_SWAP_ACTION_KIND = "swap";
+export const DEEPBOOK_SWAP_ADAPTER_ID = "deepbook-swap";
+export const DEEPBOOK_SWAP_PROTOCOL = "DeepBookV3";
+export const deepbookSwapIntentInputSchema = z.object({
+    type: z.literal(DEEPBOOK_SWAP_ACTION_KIND),
+    from: z.object({
+        symbol: z.string().min(1),
+        amount: z.string().min(1)
+    }),
+    to: z.object({
+        symbol: z.string().min(1)
+    }),
+    maxSlippageBps: z.number().int().min(1).max(1000)
+});
+export const deepbookSwapRequestedIntentSchema = z.object({
+    type: z.literal(DEEPBOOK_SWAP_ACTION_KIND),
+    from: z.object({
+        symbol: z.string().min(1),
+        amountDisplay: z.string().min(1)
+    }),
+    to: z.object({
+        symbol: z.string().min(1)
+    }),
+    maxSlippageBps: z.number().int().min(1).max(1000)
+});
+export function createDeepbookSwapActionPlan(intent, now) {
+    const requestedIntent = normalizeDeepbookSwapRequestedIntent(intent);
+    return {
+        id: `plan_${randomUUID()}`,
+        actionKind: DEEPBOOK_SWAP_ACTION_KIND,
+        adapterId: DEEPBOOK_SWAP_ADAPTER_ID,
+        protocol: DEEPBOOK_SWAP_PROTOCOL,
+        title: `Review ${requestedIntent.from.amountDisplay} ${requestedIntent.from.symbol} to ${requestedIntent.to.symbol}`,
+        summary: "Account-bound DeepBook review evidence is computed after a wallet account is connected. The review URL displays the proposal and local review evidence; when every evidence stage completes, the review page offers user-controlled wallet signing through a digest-gated handoff. This MCP response contains no sign action, signing data, transaction bytes, or signing readiness.",
+        assetFlowPreview: {
+            outgoing: [
+                { symbol: requestedIntent.from.symbol, amount: requestedIntent.from.amountDisplay, amountKind: "display_intent" }
+            ],
+            expectedIncoming: [
+                { symbol: requestedIntent.to.symbol, amount: "unknown", amountKind: "display_intent", approx: true }
+            ]
+        },
+        adapterData: {
+            requestedIntent
+        },
+        createdAt: now.toISOString(),
+        preliminaryChecks: [accountBoundReviewRequiredCheck(), signingViaLocalReviewOnlyCheck()]
+    };
+}
+export const deepbookSwapActionPlanDataSchema = z.object({
+    requestedIntent: deepbookSwapRequestedIntentSchema
+});
+export const deepbookSwapActionPlanIdentitySchema = z.object({
+    actionKind: z.literal(DEEPBOOK_SWAP_ACTION_KIND),
+    adapterId: z.literal(DEEPBOOK_SWAP_ADAPTER_ID),
+    protocol: z.literal(DEEPBOOK_SWAP_PROTOCOL)
+}).passthrough();
+export function isDeepbookSwapActionPlanIdentity(plan) {
+    return deepbookSwapActionPlanIdentitySchema.safeParse(plan).success;
+}
+export function normalizeDeepbookSwapRequestedIntent(input) {
+    const fromSymbol = canonicalDeepbookSymbol(input.from.symbol) ?? input.from.symbol.trim();
+    const toSymbol = canonicalDeepbookSymbol(input.to.symbol) ?? input.to.symbol.trim();
+    return {
+        type: DEEPBOOK_SWAP_ACTION_KIND,
+        from: {
+            symbol: fromSymbol,
+            amountDisplay: input.from.amount
+        },
+        to: {
+            symbol: toSymbol
+        },
+        maxSlippageBps: input.maxSlippageBps
+    };
+}