@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/core/action/schemas.js

@@ -0,0 +1,529 @@
+import { z } from "zod";
+import { proposalReviewModelSchema } from "../proposal/schemas.js";
+import { suiAddressStringSchema } from "../suiAddress.js";
+import { makeRawU64StringSchema } from "../numeric/rawU64.js";
+import { normalizeCoinType } from "../read/coinMetadata.js";
+import { BLOCKED_REASONS, FAILURE_REASONS, REFRESH_REASONS } from "./types.js";
+import { ptbVisualizationArtifactSchema, walletReviewAdapterContractSchema } from "./signableAdapterContract.js";
+export const unknownRecordSchema = z.record(z.string(), z.unknown());
+export const failureReasonSchema = z.enum(FAILURE_REASONS);
+export const blockedReasonSchema = z.enum(BLOCKED_REASONS);
+export const refreshReasonSchema = z.enum(REFRESH_REASONS);
+export const reviewStatusSchema = z.enum([
+    "ready_for_wallet_review",
+    "refresh_required",
+    "blocked"
+]);
+export const internalSessionStatusSchema = z.enum([
+    "proposed",
+    "awaiting_wallet",
+    "wallet_connected",
+    "ready_for_wallet_review",
+    "refresh_required",
+    "blocked",
+    "signed_pending_result",
+    "success",
+    "failure",
+    "expired"
+]);
+export const executionPollingStatusSchema = z.enum([
+    "pending",
+    "awaiting_wallet",
+    "awaiting_signature",
+    "refresh_required",
+    "signed_pending_result",
+    "success",
+    "failure",
+    "expired",
+    "blocked"
+]);
+export const reviewCheckSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    status: z.enum(["pass", "warning", "fail"]),
+    message: z.string(),
+    source: z.enum(["registry", "quote", "wallet", "simulation", "adapter", "network", "proposal"])
+});
+const adapterLifecycleStageIdSchema = z.string().min(1);
+const HUMAN_READABLE_REVIEW_STAGE = "human_readable_review";
+const REVIEW_TIME_SIMULATION_STAGE = "review_time_simulation";
+export const adapterLifecycleSchema = z.object({
+    stageCatalogId: z.string().min(1),
+    adapterId: z.string(),
+    protocol: z.string(),
+    actionKind: z.string(),
+    completedStages: z.array(adapterLifecycleStageIdSchema),
+    missingStages: z.array(adapterLifecycleStageIdSchema)
+}).strict().superRefine((lifecycle, ctx) => {
+    const duplicateCompleted = findDuplicate(lifecycle.completedStages);
+    if (duplicateCompleted) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["completedStages"],
+            message: `completedStages contains duplicate stage '${duplicateCompleted}'`
+        });
+    }
+    const duplicateMissing = findDuplicate(lifecycle.missingStages);
+    if (duplicateMissing) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["missingStages"],
+            message: `missingStages contains duplicate stage '${duplicateMissing}'`
+        });
+    }
+    for (const stage of lifecycle.completedStages) {
+        if (lifecycle.missingStages.includes(stage)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["missingStages"],
+                message: `stage '${stage}' cannot be both completed and missing`
+            });
+        }
+    }
+});
+function findDuplicate(values) {
+    const seen = new Set();
+    for (const value of values) {
+        if (seen.has(value)) {
+            return value;
+        }
+        seen.add(value);
+    }
+    return undefined;
+}
+export const assetAmountSchema = z.object({
+    symbol: z.string(),
+    amount: z.string(),
+    coinType: z.string().optional(),
+    approx: z.boolean().optional()
+}).strict();
+export const displayIntentAssetAmountSchema = assetAmountSchema.extend({
+    amountKind: z.literal("display_intent").default("display_intent")
+});
+export const assetFlowPreviewSchema = z.object({
+    outgoing: z.array(displayIntentAssetAmountSchema),
+    expectedIncoming: z.array(displayIntentAssetAmountSchema),
+    minimumIncoming: z.array(displayIntentAssetAmountSchema).optional(),
+    fees: z.array(displayIntentAssetAmountSchema).optional()
+});
+export const assetFlowSchema = z.object({
+    outgoing: z.array(assetAmountSchema),
+    expectedIncoming: z.array(assetAmountSchema),
+    minimumIncoming: z.array(assetAmountSchema).optional(),
+    fees: z.array(assetAmountSchema).optional()
+});
+export const balanceChangeSchema = z.object({
+    before: z.array(assetAmountSchema),
+    after: z.array(assetAmountSchema),
+    delta: z.array(assetAmountSchema)
+});
+export const transactionSimulationGasCostSummarySchema = z.object({
+    computationCostRaw: makeRawU64StringSchema("computationCostRaw"),
+    storageCostRaw: makeRawU64StringSchema("storageCostRaw"),
+    storageRebateRaw: makeRawU64StringSchema("storageRebateRaw"),
+    nonRefundableStorageFeeRaw: makeRawU64StringSchema("nonRefundableStorageFeeRaw")
+}).strict();
+const transactionSimulationSummaryBaseSchema = z.object({
+    provider: z.literal("client.core.simulateTransaction"),
+    checksEnabled: z.boolean(),
+    success: z.boolean(),
+    gasCostSummary: transactionSimulationGasCostSummarySchema.optional(),
+    balanceChanges: z.array(unknownRecordSchema).optional(),
+    objectChanges: z.array(unknownRecordSchema).optional(),
+    error: z.string().optional()
+});
+export const transactionSimulationSummarySchema = transactionSimulationSummaryBaseSchema;
+export const successfulTransactionSimulationSummarySchema = transactionSimulationSummaryBaseSchema.extend({
+    checksEnabled: z.literal(true),
+    success: z.literal(true),
+    gasCostSummary: transactionSimulationGasCostSummarySchema,
+    balanceChanges: z.array(unknownRecordSchema),
+    objectChanges: z.array(unknownRecordSchema),
+    error: z.never().optional()
+}).strict();
+const swapHumanReadableReviewAmountSchema = z.object({
+    role: z.enum(["input", "expected_output", "minimum_output", "fee"]),
+    symbol: z.string(),
+    coinType: z.string().min(1).max(512).refine((value) => {
+        try {
+            normalizeCoinType(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, "Expected a Sui struct tag coin type"),
+    decimals: z.number().int().min(0).max(255),
+    rawAmount: makeRawU64StringSchema("rawAmount"),
+    rawAmountSource: z.literal("quote_policy_evidence"),
+    displayAmount: z.string().optional(),
+    displayAmountSource: z.literal("user_display_intent_not_signing_input").optional()
+}).strict().superRefine((amount, ctx) => {
+    if (amount.displayAmount !== undefined && amount.displayAmountSource === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["displayAmountSource"],
+            message: "displayAmountSource is required when displayAmount is present"
+        });
+    }
+    if (amount.displayAmount === undefined && amount.displayAmountSource !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["displayAmount"],
+            message: "displayAmount is required when displayAmountSource is present"
+        });
+    }
+});
+const humanReadableReviewPartySchema = z.object({
+    role: z.enum(["connected_account", "output_recipient"]),
+    address: suiAddressStringSchema
+}).strict();
+const swapHumanReadableReviewTargetSchema = z.object({
+    kind: z.literal("swap_output_asset"),
+    symbol: z.string(),
+    coinType: z.string().min(1).max(512).refine((value) => {
+        try {
+            normalizeCoinType(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, "Expected a Sui struct tag coin type"),
+    protocol: z.string(),
+    poolKey: z.string(),
+    direction: z.enum(["base_to_quote", "quote_to_base"])
+}).strict();
+const humanReadableReviewFactSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    source: z.union([
+        z.enum(["registry", "quote", "wallet", "simulation", "adapter", "network", "proposal"]),
+        z.enum(["transaction_material", "digest_commitment"])
+    ]),
+    summary: z.string()
+}).strict();
+const humanReadableReviewGapSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    reason: z.string()
+}).strict();
+export const humanReadableReviewEnvelopeSchema = z.object({
+    proposedAction: z.object({
+        title: z.string(),
+        summary: z.string(),
+        actionKind: z.string(),
+        adapterId: z.string(),
+        protocol: z.string(),
+        network: z.literal("sui:mainnet")
+    }).strict(),
+    recipients: z.array(humanReadableReviewPartySchema),
+    evidenceUsed: z.array(humanReadableReviewFactSchema),
+    missingEvidence: z.array(humanReadableReviewGapSchema),
+    requiredUserChoices: z.array(humanReadableReviewGapSchema),
+    unsupportedClaims: z.array(humanReadableReviewGapSchema),
+    freshness: z.object({
+        status: z.literal("current"),
+        evaluatedAt: z.string(),
+        expiresAt: z.string(),
+        reason: z.string()
+    }).strict(),
+    blockingChecks: z.array(reviewCheckSchema)
+}).strict();
+export const swapHumanReadableReviewProjectionSchema = z.object({
+    assetFlow: z.object({
+        outgoing: z.array(swapHumanReadableReviewAmountSchema),
+        expectedIncoming: z.array(swapHumanReadableReviewAmountSchema),
+        minimumIncoming: z.array(swapHumanReadableReviewAmountSchema),
+        fees: z.array(swapHumanReadableReviewAmountSchema)
+    }).strict(),
+    targets: z.array(swapHumanReadableReviewTargetSchema)
+}).strict();
+export const swapHumanReadableReviewSummarySchema = humanReadableReviewEnvelopeSchema
+    .extend({ kind: z.literal("swap_human_readable_review") })
+    .merge(swapHumanReadableReviewProjectionSchema);
+export const humanReadableReviewSummarySchema = z.discriminatedUnion("kind", [
+    swapHumanReadableReviewSummarySchema
+]);
+export const actionPlanSchema = z.object({
+    id: z.string(),
+    actionKind: z.string(),
+    adapterId: z.string(),
+    protocol: z.string(),
+    title: z.string(),
+    summary: z.string(),
+    assetFlowPreview: assetFlowPreviewSchema,
+    reviewModel: proposalReviewModelSchema.optional(),
+    adapterData: unknownRecordSchema,
+    createdAt: z.string(),
+    expiresAt: z.string().optional(),
+    registryVersion: z.string().optional(),
+    preliminaryChecks: z.array(reviewCheckSchema).optional()
+});
+const reviewStateBaseSchema = z.object({
+    planId: z.string(),
+    reviewSessionId: z.string(),
+    account: suiAddressStringSchema,
+    checks: z.array(reviewCheckSchema),
+    assetFlowActual: assetFlowSchema.optional(),
+    beforeAfterBalance: balanceChangeSchema.optional(),
+    simulation: transactionSimulationSummarySchema.optional(),
+    humanReadableReview: humanReadableReviewSummarySchema.optional(),
+    walletReviewAdapterContract: walletReviewAdapterContractSchema.optional(),
+    ptbVisualization: ptbVisualizationArtifactSchema.optional(),
+    adapterLifecycle: adapterLifecycleSchema.optional(),
+    updatedAt: z.string()
+});
+export const reviewStateStructuralInvariantSchema = z.discriminatedUnion("status", [
+    reviewStateBaseSchema.extend({
+        status: z.literal("ready_for_wallet_review"),
+        blockedReason: z.never().optional(),
+        refreshReason: z.never().optional()
+    }),
+    reviewStateBaseSchema.extend({
+        status: z.literal("refresh_required"),
+        refreshReason: refreshReasonSchema,
+        blockedReason: z.never().optional()
+    }),
+    reviewStateBaseSchema.extend({
+        status: z.literal("blocked"),
+        blockedReason: blockedReasonSchema,
+        refreshReason: z.never().optional()
+    })
+]).superRefine((state, ctx) => {
+    const lifecycle = state.adapterLifecycle;
+    if (lifecycle !== undefined) {
+        validatePublicEvidenceStageBinding(state, ctx);
+    }
+    if (state.humanReadableReview !== undefined && lifecycle === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["humanReadableReview"],
+            message: "humanReadableReview requires adapterLifecycle evidence stage provenance"
+        });
+    }
+    if (state.simulation !== undefined && lifecycle === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["simulation"],
+            message: "simulation requires adapterLifecycle evidence stage provenance"
+        });
+    }
+    if (state.ptbVisualization !== undefined) {
+        const stages = lifecycle?.completedStages ?? [];
+        const hasMaterialBinding = stages.includes("transaction_material_build_or_verify") && stages.includes("digest_commitment");
+        if (!hasMaterialBinding) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["ptbVisualization"],
+                message: "ptbVisualization requires completed transaction material and digest commitment lifecycle stages"
+            });
+        }
+    }
+    const contractCarryingState = state.status === "ready_for_wallet_review" ||
+        (state.status === "blocked" && state.blockedReason === "wallet_handoff_not_implemented");
+    if (state.walletReviewAdapterContract !== undefined && !contractCarryingState) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["walletReviewAdapterContract"],
+            message: "walletReviewAdapterContract is only valid on ready_for_wallet_review or a stored wallet_handoff_not_implemented state"
+        });
+    }
+    if (state.status === "ready_for_wallet_review" && lifecycle !== undefined) {
+        if (state.walletReviewAdapterContract === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["walletReviewAdapterContract"],
+                message: "ready_for_wallet_review requires an emitted wallet review contract"
+            });
+        }
+        if (lifecycle === undefined || lifecycle.missingStages.length !== 0) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["adapterLifecycle"],
+                message: "ready_for_wallet_review requires a completed adapterLifecycle with no missing stages"
+            });
+        }
+        if (state.humanReadableReview === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["humanReadableReview"],
+                message: "ready_for_wallet_review requires humanReadableReview public evidence"
+            });
+        }
+        if (state.simulation === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["simulation"],
+                message: "ready_for_wallet_review requires successful simulation public evidence"
+            });
+        }
+    }
+    if (state.status !== "blocked") {
+        return;
+    }
+    if (state.blockedReason === "wallet_handoff_not_implemented") {
+        if (state.walletReviewAdapterContract === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["walletReviewAdapterContract"],
+                message: "wallet_handoff_not_implemented requires an emitted wallet review contract"
+            });
+        }
+        if (lifecycle === undefined || lifecycle.missingStages.length !== 0) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["adapterLifecycle"],
+                message: "wallet_handoff_not_implemented requires a completed adapterLifecycle with no missing stages"
+            });
+        }
+        if (state.humanReadableReview === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["humanReadableReview"],
+                message: "wallet_handoff_not_implemented requires humanReadableReview public evidence"
+            });
+        }
+        if (state.simulation === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["simulation"],
+                message: "wallet_handoff_not_implemented requires successful simulation public evidence"
+            });
+        }
+    }
+    if (state.blockedReason === "producer_stage_missing" &&
+        lifecycle === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["adapterLifecycle"],
+            message: "producer_stage_missing requires adapterLifecycle with at least one missing stage"
+        });
+    }
+    if (state.blockedReason === "producer_stage_missing" &&
+        lifecycle !== undefined &&
+        lifecycle.missingStages.length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["blockedReason"],
+            message: "producer_stage_missing requires at least one adapterLifecycle.missingStages entry"
+        });
+    }
+    if (state.blockedReason === "wallet_review_contract_emit_missing" &&
+        state.walletReviewAdapterContract !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["walletReviewAdapterContract"],
+            message: "wallet_review_contract_emit_missing requires the wallet review contract to be absent"
+        });
+    }
+    if (state.blockedReason === "wallet_review_contract_emit_missing" &&
+        lifecycle === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["adapterLifecycle"],
+            message: "wallet_review_contract_emit_missing requires adapterLifecycle"
+        });
+    }
+    if (state.blockedReason === "wallet_review_contract_emit_missing" &&
+        lifecycle !== undefined &&
+        lifecycle.missingStages.length !== 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["blockedReason"],
+            message: "wallet_review_contract_emit_missing requires a completed adapterLifecycle with no missing stages"
+        });
+    }
+    if (state.blockedReason === "wallet_review_contract_emit_missing" &&
+        state.humanReadableReview === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["humanReadableReview"],
+            message: "wallet_review_contract_emit_missing requires humanReadableReview public evidence"
+        });
+    }
+    if (state.blockedReason === "wallet_review_contract_emit_missing" &&
+        state.simulation === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["simulation"],
+            message: "wallet_review_contract_emit_missing requires simulation public evidence"
+        });
+    }
+});
+export const reviewStateOutputSchema = reviewStateStructuralInvariantSchema;
+function validatePublicEvidenceStageBinding(state, ctx) {
+    const lifecycle = state.adapterLifecycle;
+    if (!lifecycle) {
+        return;
+    }
+    if (state.humanReadableReview !== undefined) {
+        requireLifecycleStageCompleted(ctx, lifecycle, HUMAN_READABLE_REVIEW_STAGE, ["humanReadableReview"]);
+    }
+    if (state.simulation !== undefined) {
+        requireLifecycleStageCompleted(ctx, lifecycle, REVIEW_TIME_SIMULATION_STAGE, ["simulation"]);
+        requireLifecycleStageCompleted(ctx, lifecycle, HUMAN_READABLE_REVIEW_STAGE, ["simulation"]);
+        requireSuccessfulSimulationProjection(ctx, state.simulation, ["simulation"]);
+    }
+    if (lifecycle.missingStages.includes(REVIEW_TIME_SIMULATION_STAGE) &&
+        state.simulation !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["simulation"],
+            message: "simulation public evidence cannot be present while review_time_simulation is missing"
+        });
+    }
+    if (lifecycle.missingStages.includes(HUMAN_READABLE_REVIEW_STAGE) &&
+        state.humanReadableReview !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["humanReadableReview"],
+            message: "humanReadableReview public evidence cannot be present while human_readable_review is missing"
+        });
+    }
+}
+function requireLifecycleStageCompleted(ctx, lifecycle, stage, path) {
+    if (!lifecycle.completedStages.includes(stage)) {
+        ctx.addIssue({
+            code: "custom",
+            path,
+            message: `${path.join(".")} requires completed adapterLifecycle stage '${stage}'`
+        });
+    }
+    if (lifecycle.missingStages.includes(stage)) {
+        ctx.addIssue({
+            code: "custom",
+            path,
+            message: `${path.join(".")} cannot be present while adapterLifecycle stage '${stage}' is missing`
+        });
+    }
+}
+function requireSuccessfulSimulationProjection(ctx, simulation, path) {
+    const parsed = successfulTransactionSimulationSummarySchema.safeParse(simulation);
+    if (!parsed.success) {
+        ctx.addIssue({
+            code: "custom",
+            path,
+            message: "simulation public evidence requires a successful checks-enabled review-time simulation projection"
+        });
+    }
+}
+const executionResultBaseSchema = z.object({
+    reviewSessionId: z.string(),
+    planId: z.string(),
+    explorerUrl: z.string().optional(),
+    summary: unknownRecordSchema.optional(),
+    recordedAt: z.string()
+});
+export const executionResultSchema = z.discriminatedUnion("status", [
+    executionResultBaseSchema.extend({
+        status: z.enum(["success", "signed_pending_result"]),
+        txDigest: z.string().min(1),
+        failureReason: z.never().optional()
+    }),
+    executionResultBaseSchema.extend({
+        status: z.literal("failure"),
+        txDigest: z.string().optional(),
+        failureReason: failureReasonSchema
+    })
+]);