@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/core/read/readServiceTypes.js

@@ -0,0 +1,59 @@
+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 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;
+// 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 const FLOWX_SWAP_QUOTE_QUANTITY_KIND = "flowx_swap_quote";
+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.parityPrice - right.parityPrice);
+    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].parityPrice
+        : (sorted[middle - 1].parityPrice + sorted[middle].parityPrice) / 2;
+    const mean = samples.reduce((sum, sample) => sum + sample.parityPrice, 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, parityPrice: roundDerivedParityPrice(min.parityPrice) },
+        max: { symbol: max.symbol, parityPrice: roundDerivedParityPrice(max.parityPrice) },
+        mean: { parityPrice: roundDerivedParityPrice(mean) },
+        median: { parityPrice: roundDerivedParityPrice(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 roundDerivedParityPrice(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",
+            spendability: balance.balance === "0" ? "zero_balance" : "spendable",
+            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,54 @@
+export function adapterNotImplementedCheck() {
+    return {
+        id: "adapter_not_implemented",
+        label: "Adapter review",
+        status: "fail",
+        message: "No review adapter is registered for this action plan; the review fails closed and signing remains blocked for this session.",
+        source: "adapter"
+    };
+}
+export function accountBoundReviewRequiredCheck() {
+    return {
+        id: "account_bound_review_required",
+        label: "Account-bound review",
+        status: "warning",
+        message: "Connect a wallet account to compute DeepBook review evidence and adapter lifecycle stages. This does not provide signing data, signing readiness, wallet handoff, or execution.",
+        source: "adapter"
+    };
+}
+export function signingViaLocalReviewOnlyCheck() {
+    return {
+        id: "signing_via_local_review_only",
+        label: "Wallet signing",
+        status: "warning",
+        message: "Wallet signing happens only on the local review page after every review evidence stage completes and the digest-gated handoff succeeds. 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: "This action plan is labelled for the DeepBook swap adapter but does not match the DeepBookV3 swap review identity.",
+        source: "adapter"
+    };
+}
+export function unsupportedFlowxSwapPlanIdentityCheck() {
+    return {
+        id: "flowx_swap_plan_identity_invalid",
+        label: "FlowX plan identity",
+        status: "fail",
+        message: "This action plan is labelled for the FlowX swap adapter but does not match the FlowXCLMM swap review identity.",
+        source: "adapter"
+    };
+}
+export function externalProposalReviewOnlyCheck() {
+    return {
+        id: "external_proposal_review_only",
+        label: "Non-signable review",
+        status: "fail",
+        message: "External proposal ingestion is read-only; it does not build transactions, request signatures, or create 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.walletReviewAdapterContract
+            ? { walletReviewAdapterContract: result.walletReviewAdapterContract }
+            : {}),
+        ...(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, walletReviewAdapterContract, ptbVisualization) {
+    return {
+        status: "ready_for_wallet_review",
+        checks,
+        adapterLifecycle,
+        humanReadableReview,
+        simulation,
+        walletReviewAdapterContract,
+        ...(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/localSession.js

@@ -0,0 +1,31 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+export const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
+export function createLocalSessionBase(now, ttlMs) {
+    const id = randomBytes(18).toString("base64url");
+    const token = randomBytes(32).toString("base64url");
+    const createdAt = now.toISOString();
+    return {
+        base: {
+            id,
+            tokenHash: hashToken(token),
+            createdAt,
+            expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+            lastActivityAt: createdAt
+        },
+        token
+    };
+}
+export function hashToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+export function tokenMatchesHash(tokenHash, token) {
+    const expected = Buffer.from(tokenHash, "hex");
+    const actual = Buffer.from(hashToken(token), "hex");
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+export function isLocalSessionExpired(session, now) {
+    return new Date(session.expiresAt).getTime() <= now.getTime();
+}
+export function cloneLocalSession(value) {
+    return structuredClone(value);
+}

package/dist/core/session/privateReviewArtifacts.js

@@ -0,0 +1,73 @@
+import { parseHumanReadableReviewEvidence } from "../action/humanReadableReviewEvidence.js";
+import { parseReviewTimeSimulationEvidence } from "../action/reviewTimeSimulationEvidence.js";
+export function clonePrivateReviewArtifacts(artifacts) {
+    return {
+        ...(artifacts.transactionMaterial
+            ? { transactionMaterial: { ...artifacts.transactionMaterial } }
+            : {}),
+        ...(artifacts.transactionMaterialDigest
+            ? { transactionMaterialDigest: { ...artifacts.transactionMaterialDigest } }
+            : {}),
+        ...(artifacts.swapQuotePolicy
+            ? {
+                swapQuotePolicy: {
+                    ...artifacts.swapQuotePolicy,
+                    quoteSource: { ...artifacts.swapQuotePolicy.quoteSource },
+                    sourceAmount: {
+                        ...artifacts.swapQuotePolicy.sourceAmount,
+                        asset: { ...artifacts.swapQuotePolicy.sourceAmount.asset }
+                    },
+                    expectedOutput: {
+                        ...artifacts.swapQuotePolicy.expectedOutput,
+                        asset: { ...artifacts.swapQuotePolicy.expectedOutput.asset }
+                    },
+                    minimumOutput: {
+                        ...artifacts.swapQuotePolicy.minimumOutput,
+                        asset: { ...artifacts.swapQuotePolicy.minimumOutput.asset }
+                    },
+                    protocolFee: {
+                        ...artifacts.swapQuotePolicy.protocolFee,
+                        asset: { ...artifacts.swapQuotePolicy.protocolFee.asset }
+                    }
+                }
+            }
+            : {}),
+        ...(artifacts.transactionObjectOwnership
+            ? {
+                transactionObjectOwnership: {
+                    ...artifacts.transactionObjectOwnership,
+                    objects: artifacts.transactionObjectOwnership.objects.map((object) => ({
+                        ...object,
+                        roles: [...object.roles]
+                    }))
+                }
+            }
+            : {}),
+        ...(artifacts.humanReadableReview
+            ? {
+                humanReadableReview: parseHumanReadableReviewEvidence(structuredClone(artifacts.humanReadableReview))
+            }
+            : {}),
+        ...(artifacts.reviewTimeSimulation
+            ? {
+                reviewTimeSimulation: parseReviewTimeSimulationEvidence(structuredClone(artifacts.reviewTimeSimulation))
+            }
+            : {})
+    };
+}
+export class InMemoryPrivateReviewArtifactStore {
+    artifacts = new Map();
+    get(reviewSessionId) {
+        const artifacts = this.artifacts.get(reviewSessionId);
+        return artifacts ? clonePrivateReviewArtifacts(artifacts) : undefined;
+    }
+    set(reviewSessionId, artifacts) {
+        this.artifacts.set(reviewSessionId, clonePrivateReviewArtifacts(artifacts));
+    }
+    delete(reviewSessionId) {
+        this.artifacts.delete(reviewSessionId);
+    }
+    clear() {
+        this.artifacts.clear();
+    }
+}

package/dist/core/session/sessionErrors.js

@@ -0,0 +1,9 @@
+export class SessionStoreError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}