@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/core/action/swapHumanReadableReviewProjection.js

@@ -0,0 +1,124 @@
+import { assertPreSimulationHumanReadableReviewBoundaryClaims, createHumanReadableReviewEvidence, verifyHumanReadableReviewEvidence } from "./humanReadableReviewEvidence.js";
+import { parseSuiAddress } from "../suiAddress.js";
+export function createSwapHumanReadableReviewEvidence(input) {
+    return verifySwapHumanReadableReviewEvidence({
+        transactionMaterial: input.transactionMaterial,
+        transactionMaterialDigest: input.transactionMaterialDigest,
+        swapQuotePolicy: input.swapQuotePolicy,
+        transactionObjectOwnership: input.transactionObjectOwnership,
+        evidence: createHumanReadableReviewEvidence({
+            transactionMaterial: input.transactionMaterial,
+            transactionMaterialDigest: input.transactionMaterialDigest,
+            adapterId: input.adapterId,
+            protocol: input.protocol,
+            actionKind: input.actionKind,
+            review: input.review,
+            derivedAt: input.derivedAt
+        }),
+        now: input.derivedAt
+    });
+}
+export function verifySwapHumanReadableReviewEvidence(input) {
+    const evidence = verifyHumanReadableReviewEvidence({
+        transactionMaterial: input.transactionMaterial,
+        transactionMaterialDigest: input.transactionMaterialDigest,
+        evidence: input.evidence,
+        now: input.now
+    });
+    if (evidence.review.kind !== "swap_human_readable_review") {
+        throw new Error("swap human-readable review evidence requires a swap_human_readable_review projection");
+    }
+    if (input.swapQuotePolicy.adapterId !== evidence.adapterId ||
+        input.swapQuotePolicy.protocol !== evidence.protocol ||
+        input.swapQuotePolicy.actionKind !== evidence.actionKind) {
+        throw new Error("swap human-readable review evidence must match swap quote policy adapter identity");
+    }
+    for (const artifact of [input.swapQuotePolicy, input.transactionObjectOwnership]) {
+        if (artifact.materialId !== input.transactionMaterial.materialId ||
+            artifact.reviewSessionId !== input.transactionMaterial.reviewSessionId ||
+            artifact.planId !== input.transactionMaterial.planId ||
+            artifact.account !== input.transactionMaterial.account ||
+            artifact.expiresAt !== input.transactionMaterial.expiresAt) {
+            throw new Error("swap human-readable review evidence requires quote policy and object ownership artifacts for the same material");
+        }
+    }
+    if (input.transactionObjectOwnership.transactionDigest !== input.transactionMaterialDigest.transactionDigest) {
+        throw new Error("swap human-readable review evidence requires object ownership bound to the same transaction digest");
+    }
+    assertSwapHumanReadableReviewProjectsQuotePolicy(evidence, input.swapQuotePolicy);
+    assertSwapHumanReadableReviewParties(evidence);
+    assertSwapHumanReadableReviewEvidenceSources(evidence);
+    assertSwapHumanReadableReviewBoundaryClaims(evidence);
+    assertPreSimulationHumanReadableReviewBoundaryClaims(evidence);
+    return evidence;
+}
+function assertSwapHumanReadableReviewProjectsQuotePolicy(evidence, swapQuotePolicy) {
+    assertSingleAmountProjection("outgoing", evidence.review.assetFlow.outgoing, "input", swapQuotePolicy.sourceAmount);
+    assertSingleAmountProjection("expected incoming", evidence.review.assetFlow.expectedIncoming, "expected_output", swapQuotePolicy.expectedOutput);
+    assertSingleAmountProjection("minimum incoming", evidence.review.assetFlow.minimumIncoming, "minimum_output", swapQuotePolicy.minimumOutput);
+    assertSingleAmountProjection("fee", evidence.review.assetFlow.fees, "fee", swapQuotePolicy.protocolFee);
+    if (evidence.review.targets.length !== 1) {
+        throw new Error("swap human-readable review targets must contain exactly one swap output asset target");
+    }
+    const target = evidence.review.targets[0];
+    if (target.kind !== "swap_output_asset" ||
+        target.symbol !== swapQuotePolicy.expectedOutput.asset.symbol ||
+        target.coinType !== swapQuotePolicy.expectedOutput.asset.coinType ||
+        target.protocol !== swapQuotePolicy.protocol ||
+        target.poolKey !== swapQuotePolicy.quoteSource.poolKey ||
+        target.direction !== swapQuotePolicy.quoteSource.direction) {
+        throw new Error("swap human-readable review target must match swap quote policy output asset and quote source");
+    }
+}
+function assertSwapHumanReadableReviewParties(evidence) {
+    const recipientsByRole = new Map();
+    for (const recipient of evidence.review.recipients) {
+        if (recipientsByRole.has(recipient.role)) {
+            throw new Error(`swap human-readable review recipients contains duplicate role '${recipient.role}'`);
+        }
+        const normalizedAddress = parseSuiAddress(recipient.address);
+        if (!normalizedAddress) {
+            throw new Error("swap human-readable review recipients must contain valid Sui addresses");
+        }
+        recipientsByRole.set(recipient.role, normalizedAddress);
+    }
+    if (recipientsByRole.size !== 2) {
+        throw new Error("swap human-readable review recipients must contain exactly the connected account and output recipient");
+    }
+    if (recipientsByRole.get("connected_account") !== evidence.account ||
+        recipientsByRole.get("output_recipient") !== evidence.account) {
+        throw new Error("swap human-readable review recipients must match the reviewed account");
+    }
+}
+function assertSwapHumanReadableReviewEvidenceSources(evidence) {
+    for (const source of ["quote", "wallet"]) {
+        requireFactSource(evidence.review.evidenceUsed, source);
+    }
+}
+function assertSwapHumanReadableReviewBoundaryClaims(evidence) {
+    requireGapId("unsupportedClaims", evidence.review.unsupportedClaims, "no_route_recommendation");
+}
+function assertSingleAmountProjection(label, amounts, role, expected) {
+    if (amounts.length !== 1) {
+        throw new Error(`swap human-readable review ${label} must contain exactly one amount`);
+    }
+    const amount = amounts[0];
+    if (amount.role !== role ||
+        amount.rawAmount !== expected.raw ||
+        amount.rawAmountSource !== "quote_policy_evidence" ||
+        amount.symbol !== expected.asset.symbol ||
+        amount.coinType !== expected.asset.coinType ||
+        amount.decimals !== expected.asset.decimals) {
+        throw new Error(`swap human-readable review ${label} amount must match swap quote policy evidence`);
+    }
+}
+function requireFactSource(facts, source) {
+    if (!facts.some((fact) => fact.source === source)) {
+        throw new Error(`swap human-readable review evidenceUsed must include source '${source}'`);
+    }
+}
+function requireGapId(label, gaps, id) {
+    if (!gaps.some((gap) => gap.id === id)) {
+        throw new Error(`swap human-readable review ${label} must include '${id}'`);
+    }
+}

package/dist/core/action/swapQuotePolicyEvidence.js

@@ -0,0 +1,278 @@
+import { z } from "zod";
+import { adapterEvidenceClaimSchema, adapterRawQuantitySchema, adapterSourceOfTruthSchema } from "./signableAdapterContract.js";
+import { parseRawU64 } from "../numeric/rawU64.js";
+import { normalizedSuiAddressSchema } from "../suiAddress.js";
+import { normalizeCoinType } from "../read/coinMetadata.js";
+export const SWAP_QUOTE_POLICY_EVIDENCE_VERSION = "swap-quote-policy-v1";
+const BPS_DENOMINATOR = 10000n;
+const isoUtcStringSchema = z.string().refine((value) => {
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) && parsed.toISOString() === value;
+}, "Expected ISO 8601 UTC timestamp");
+const coinTypeSchema = z.string().min(1).max(512).refine((value) => {
+    try {
+        normalizeCoinType(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, "Expected a Sui struct tag coin type").transform((value) => normalizeCoinType(value));
+const quotePolicyAssetSchema = z.object({
+    symbol: z.string().min(1).max(64),
+    coinType: coinTypeSchema,
+    decimals: z.number().int().min(0).max(255),
+    unitSource: z.enum(["deepbook_mainnetCoins_scalar", "flowx_pinned_registry", "sui_core_getCoinMetadata"])
+}).strict();
+const quotePolicyRawAmountSchema = z.object({
+    raw: z.string().min(1),
+    asset: quotePolicyAssetSchema
+}).strict();
+export const swapQuotePolicyEvidenceSchema = z.object({
+    evidenceVersion: z.literal(SWAP_QUOTE_POLICY_EVIDENCE_VERSION),
+    materialId: z.string().min(1),
+    reviewSessionId: z.string().min(1),
+    planId: z.string().min(1),
+    account: normalizedSuiAddressSchema,
+    kind: z.literal("swap_quote_policy"),
+    adapterId: z.string().min(1).max(120),
+    protocol: z.string().min(1).max(120),
+    actionKind: z.string().min(1).max(120),
+    network: z.literal("sui:mainnet"),
+    quoteEvidenceId: z.string().min(1).max(120),
+    quoteSource: z.object({
+        provider: z.string().min(1).max(120),
+        poolKey: z.string().min(1).max(120),
+        direction: z.enum(["base_to_quote", "quote_to_base"]),
+        fetchedAt: isoUtcStringSchema,
+        sourceMoveFunction: z.string().min(1).max(160)
+    }).strict(),
+    policySource: z.literal("adapter_policy_from_quote_evidence"),
+    maxSlippageBps: z.number().int().min(1).max(10_000),
+    staleAfterMs: z.number().int().min(1),
+    sourceAmount: quotePolicyRawAmountSchema,
+    expectedOutput: quotePolicyRawAmountSchema,
+    minimumOutput: quotePolicyRawAmountSchema,
+    protocolFee: quotePolicyRawAmountSchema,
+    derivedAt: isoUtcStringSchema,
+    expiresAt: isoUtcStringSchema
+}).strict();
+export function createSwapQuotePolicyEvidence(input) {
+    return verifySwapQuotePolicyEvidence({
+        transactionMaterial: input.materialHandle,
+        evidence: {
+            evidenceVersion: SWAP_QUOTE_POLICY_EVIDENCE_VERSION,
+            materialId: input.materialHandle.materialId,
+            reviewSessionId: input.materialHandle.reviewSessionId,
+            planId: input.materialHandle.planId,
+            account: input.materialHandle.account,
+            kind: "swap_quote_policy",
+            adapterId: input.adapterId,
+            protocol: input.protocol,
+            actionKind: input.actionKind,
+            network: "sui:mainnet",
+            quoteEvidenceId: input.quoteEvidenceId,
+            quoteSource: input.quoteSource,
+            policySource: "adapter_policy_from_quote_evidence",
+            maxSlippageBps: input.maxSlippageBps,
+            staleAfterMs: input.staleAfterMs,
+            sourceAmount: input.sourceAmount,
+            expectedOutput: input.expectedOutput,
+            minimumOutput: input.minimumOutput,
+            protocolFee: input.protocolFee,
+            derivedAt: input.derivedAt.toISOString(),
+            expiresAt: input.materialHandle.expiresAt
+        },
+        now: input.derivedAt
+    });
+}
+export function parseSwapQuotePolicyEvidence(value) {
+    return swapQuotePolicyEvidenceSchema.parse(value);
+}
+export function verifySwapQuotePolicyEvidence(input) {
+    const evidence = parseSwapQuotePolicyEvidence(input.evidence);
+    const now = input.now ?? new Date();
+    const nowMs = now.getTime();
+    if (!Number.isFinite(nowMs)) {
+        throw new Error("now must be a valid Date");
+    }
+    if (evidence.materialId !== input.transactionMaterial.materialId ||
+        evidence.reviewSessionId !== input.transactionMaterial.reviewSessionId ||
+        evidence.planId !== input.transactionMaterial.planId ||
+        evidence.account !== input.transactionMaterial.account ||
+        evidence.expiresAt !== input.transactionMaterial.expiresAt) {
+        throw new Error("swap quote policy evidence must match material identity");
+    }
+    const fetchedAtMs = Date.parse(evidence.quoteSource.fetchedAt);
+    const derivedAtMs = Date.parse(evidence.derivedAt);
+    const expiresAtMs = Date.parse(evidence.expiresAt);
+    if (fetchedAtMs > derivedAtMs) {
+        throw new Error("swap quote policy evidence fetchedAt must not be after derivedAt");
+    }
+    if (Date.parse(evidence.quoteSource.fetchedAt) + evidence.staleAfterMs !== expiresAtMs) {
+        throw new Error("swap quote policy evidence expiresAt must equal fetchedAt plus staleAfterMs");
+    }
+    if (derivedAtMs > nowMs) {
+        throw new Error("swap quote policy evidence derivedAt must not be in the future");
+    }
+    if (expiresAtMs <= derivedAtMs || expiresAtMs <= nowMs) {
+        throw new Error("swap quote policy evidence must not be expired");
+    }
+    const expectedOutput = parseRawU64(evidence.expectedOutput.raw, "expectedOutput.raw", { positive: true });
+    const minimumOutput = parseRawU64(evidence.minimumOutput.raw, "minimumOutput.raw", { positive: true });
+    parseRawU64(evidence.sourceAmount.raw, "sourceAmount.raw", { positive: true });
+    parseRawU64(evidence.protocolFee.raw, "protocolFee.raw");
+    const computedMinimum = (expectedOutput * (BPS_DENOMINATOR - BigInt(evidence.maxSlippageBps))) / BPS_DENOMINATOR;
+    if (minimumOutput !== computedMinimum) {
+        throw new Error("swap quote policy minimumOutput.raw must match expectedOutput.raw and maxSlippageBps");
+    }
+    if (!sameAsset(evidence.expectedOutput.asset, evidence.minimumOutput.asset)) {
+        throw new Error("swap quote policy minimum output asset must match expected output asset");
+    }
+    const contractMapping = mapSwapQuotePolicyEvidenceToContractDraft(evidence);
+    if (contractMapping.status === "unsupported") {
+        throw new Error(`swap quote policy evidence is not contract-mappable: ${contractMapping.reason}`);
+    }
+    return evidence;
+}
+export function mapSwapQuotePolicyEvidenceToContractDraft(evidenceInput) {
+    const evidence = parseSwapQuotePolicyEvidence(evidenceInput);
+    const outputUnitSource = mapUnitSource(evidence.expectedOutput.asset.unitSource);
+    if (!outputUnitSource) {
+        return { status: "unsupported", reason: "unsupported output unit source" };
+    }
+    const quoteSourceId = "swap_quote_policy";
+    const outputUnitSourceId = "swap_quote_output_unit";
+    const outputUnitClaimId = "swap_quote_output_unit_claim";
+    const expectedAmountClaimId = "swap_quote_expected_output_claim";
+    const minimumAmountClaimId = "swap_quote_minimum_output_claim";
+    const quoteMinOutClaimId = "swap_quote_min_out_claim";
+    const slippagePolicyClaimId = "swap_quote_slippage_policy_claim";
+    const outputAsset = {
+        symbol: evidence.expectedOutput.asset.symbol,
+        coinType: evidence.expectedOutput.asset.coinType
+    };
+    const sourceOfTruth = [
+        adapterSourceOfTruthSchema.parse({
+            id: quoteSourceId,
+            kind: "quote_evidence",
+            network: "sui:mainnet",
+            source: `${evidence.protocol} quote policy for ${evidence.adapterId}`,
+            verifiedAt: evidence.derivedAt,
+            fields: ["quoteEvidenceId", "rawAmount", "minOutRaw", "asset", "amountRole", "maxSlippageBps"]
+        }),
+        adapterSourceOfTruthSchema.parse({
+            id: outputUnitSourceId,
+            kind: outputUnitSource.sourceOfTruthKind,
+            network: "sui:mainnet",
+            source: outputUnitSource.sourceDescription,
+            verifiedAt: evidence.derivedAt,
+            fields: ["coinType", "decimals"]
+        })
+    ];
+    const evidenceClaims = [
+        adapterEvidenceClaimSchema.parse({
+            id: expectedAmountClaimId,
+            factKind: "raw_quantity_amount",
+            sourceEvidenceId: quoteSourceId,
+            role: "expected_output",
+            asset: outputAsset,
+            rawAmount: evidence.expectedOutput.raw
+        }),
+        adapterEvidenceClaimSchema.parse({
+            id: minimumAmountClaimId,
+            factKind: "raw_quantity_amount",
+            sourceEvidenceId: quoteSourceId,
+            role: "minimum_output",
+            asset: outputAsset,
+            rawAmount: evidence.minimumOutput.raw
+        }),
+        adapterEvidenceClaimSchema.parse({
+            id: outputUnitClaimId,
+            factKind: "unit_metadata",
+            sourceEvidenceId: outputUnitSourceId,
+            source: outputUnitSource.unitClaimSource,
+            coinType: outputAsset.coinType,
+            decimals: evidence.expectedOutput.asset.decimals
+        }),
+        adapterEvidenceClaimSchema.parse({
+            id: quoteMinOutClaimId,
+            factKind: "quote_min_out",
+            sourceEvidenceId: quoteSourceId,
+            quoteEvidenceId: evidence.quoteEvidenceId,
+            minOutRaw: evidence.minimumOutput.raw
+        }),
+        adapterEvidenceClaimSchema.parse({
+            id: slippagePolicyClaimId,
+            factKind: "slippage_policy",
+            sourceEvidenceId: quoteSourceId,
+            policySource: "adapter_policy_from_quote_evidence",
+            maxSlippageBps: evidence.maxSlippageBps,
+            minOutRaw: evidence.minimumOutput.raw
+        })
+    ];
+    const rawQuantities = [
+        adapterRawQuantitySchema.parse({
+            id: "swap_quote_expected_output",
+            role: "expected_output",
+            asset: outputAsset,
+            rawAmount: evidence.expectedOutput.raw,
+            unit: {
+                decimals: evidence.expectedOutput.asset.decimals,
+                source: outputUnitSource.unitClaimSource,
+                sourceField: "expectedOutput.asset.decimals",
+                unitClaimId: outputUnitClaimId
+            },
+            amountClaimId: expectedAmountClaimId
+        }),
+        adapterRawQuantitySchema.parse({
+            id: "swap_quote_minimum_output",
+            role: "minimum_output",
+            asset: outputAsset,
+            rawAmount: evidence.minimumOutput.raw,
+            unit: {
+                decimals: evidence.expectedOutput.asset.decimals,
+                source: outputUnitSource.unitClaimSource,
+                sourceField: "minimumOutput.asset.decimals",
+                unitClaimId: outputUnitClaimId
+            },
+            amountClaimId: minimumAmountClaimId
+        })
+    ];
+    return {
+        status: "mapped",
+        sourceOfTruth,
+        evidenceClaims,
+        rawQuantities
+    };
+}
+function sameAsset(left, right) {
+    return (left.symbol === right.symbol &&
+        left.coinType === right.coinType &&
+        left.decimals === right.decimals &&
+        left.unitSource === right.unitSource);
+}
+function mapUnitSource(unitSource) {
+    if (unitSource === "deepbook_mainnetCoins_scalar") {
+        return {
+            sourceOfTruthKind: "pinned_sdk_registry",
+            unitClaimSource: "pinned_sdk_metadata",
+            sourceDescription: "Pinned DeepBook mainnet coin metadata scalar used for quote raw units"
+        };
+    }
+    if (unitSource === "flowx_pinned_registry") {
+        return {
+            sourceOfTruthKind: "pinned_sdk_registry",
+            unitClaimSource: "pinned_sdk_metadata",
+            sourceDescription: "Pinned FlowX mainnet registry (chain-verified) used for quote raw units"
+        };
+    }
+    if (unitSource === "sui_core_getCoinMetadata") {
+        return {
+            sourceOfTruthKind: "verified_mainnet_onchain_metadata",
+            unitClaimSource: "verified_mainnet_onchain_metadata",
+            sourceDescription: "Sui mainnet getCoinMetadata result used for quote raw units"
+        };
+    }
+    return undefined;
+}

package/dist/core/action/transactionObjectOwnershipEvidence.js

@@ -0,0 +1,247 @@
+import { z } from "zod";
+import { isValidStructTag, normalizeStructTag } from "@mysten/sui/utils";
+import { adapterEvidenceClaimSchema, adapterGasObjectOwnershipLinkSchema, adapterObjectOwnershipEvidenceSchema, adapterSourceOfTruthSchema, SUI_GAS_COIN_TYPE } from "./signableAdapterContract.js";
+import { normalizedSuiAddressSchema, suiTransactionDigestSchema } from "../suiAddress.js";
+export const TRANSACTION_OBJECT_OWNERSHIP_EVIDENCE_VERSION = "transaction-object-ownership-v1";
+export const TRANSACTION_OBJECT_ROLES = [
+    "gas_object",
+    "imm_or_owned_object",
+    "shared_object",
+    "receiving_object"
+];
+export const TRANSACTION_OBJECT_OWNERSHIP_STATUSES = [
+    "owned_by_account",
+    "not_owned_by_account",
+    "shared_object",
+    "immutable_object",
+    "object_owner",
+    "consensus_address_owner",
+    "unknown_owner"
+];
+const isoUtcStringSchema = z.string().refine((value) => {
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) && parsed.toISOString() === value;
+}, "Expected ISO 8601 UTC timestamp");
+const moveStructTagSchema = z.string().min(1).max(512).refine((value) => isValidStructTag(value), "Expected valid Move struct tag").transform((value) => normalizeStructTag(value));
+export const transactionObjectOwnershipFactSchema = z.object({
+    objectId: normalizedSuiAddressSchema,
+    roles: z.array(z.enum(TRANSACTION_OBJECT_ROLES)).min(1),
+    ownership: z.enum(TRANSACTION_OBJECT_OWNERSHIP_STATUSES),
+    ownerKind: z.string().min(1).max(80),
+    ownerAccount: normalizedSuiAddressSchema.optional(),
+    objectType: moveStructTagSchema,
+    source: z.literal("stored_transaction_data_and_mainnet_object_read")
+}).strict().superRefine((value, ctx) => {
+    if (new Set(value.roles).size !== value.roles.length) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["roles"],
+            message: "roles must be unique"
+        });
+    }
+});
+export const transactionObjectOwnershipEvidenceSchema = z.object({
+    evidenceVersion: z.literal(TRANSACTION_OBJECT_OWNERSHIP_EVIDENCE_VERSION),
+    materialId: z.string().min(1),
+    reviewSessionId: z.string().min(1),
+    planId: z.string().min(1),
+    account: normalizedSuiAddressSchema,
+    transactionDigest: suiTransactionDigestSchema,
+    objectCount: z.number().int().min(1),
+    objects: z.array(transactionObjectOwnershipFactSchema).min(1),
+    verifiedAt: isoUtcStringSchema,
+    expiresAt: isoUtcStringSchema
+}).strict().superRefine((value, ctx) => {
+    if (value.objectCount !== value.objects.length) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["objectCount"],
+            message: "objectCount must equal objects.length"
+        });
+    }
+    if (new Set(value.objects.map((object) => object.objectId)).size !== value.objects.length) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["objects"],
+            message: "objects must have unique objectId values"
+        });
+    }
+    const verifiedAtMs = Date.parse(value.verifiedAt);
+    const expiresAtMs = Date.parse(value.expiresAt);
+    if (expiresAtMs <= verifiedAtMs) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["expiresAt"],
+            message: "expiresAt must be after verifiedAt"
+        });
+    }
+});
+export function parseSuiCoinObjectType(objectType) {
+    if (!isValidStructTag(objectType)) {
+        return { status: "not_coin" };
+    }
+    const normalized = normalizeStructTag(objectType);
+    const coinPrefix = `${normalizeStructTag("0x2::coin::Coin<0x2::sui::SUI>").split("<")[0]}<`;
+    if (!normalized.startsWith(coinPrefix) || !normalized.endsWith(">")) {
+        return { status: "not_coin" };
+    }
+    const coinType = normalized.slice(coinPrefix.length, -1);
+    if (!isValidStructTag(coinType)) {
+        return { status: "not_coin" };
+    }
+    return {
+        status: "coin",
+        objectType: normalized,
+        coinType: normalizeStructTag(coinType)
+    };
+}
+export function parseTransactionObjectOwnershipEvidence(value) {
+    return transactionObjectOwnershipEvidenceSchema.parse(value);
+}
+export function verifyTransactionObjectOwnershipEvidence(input) {
+    const evidence = parseTransactionObjectOwnershipEvidence(input.evidence);
+    const now = input.now ?? new Date();
+    const nowMs = now.getTime();
+    if (!Number.isFinite(nowMs)) {
+        throw new Error("now must be a valid Date");
+    }
+    if (evidence.materialId !== input.transactionMaterial.materialId ||
+        evidence.reviewSessionId !== input.transactionMaterial.reviewSessionId ||
+        evidence.planId !== input.transactionMaterial.planId ||
+        evidence.account !== input.transactionMaterial.account ||
+        evidence.expiresAt !== input.transactionMaterial.expiresAt ||
+        evidence.transactionDigest !== input.transactionMaterialDigest.transactionDigest) {
+        throw new Error("transaction object ownership evidence must match material and digest identity");
+    }
+    if (input.transactionMaterialDigest.materialId !== input.transactionMaterial.materialId ||
+        input.transactionMaterialDigest.reviewSessionId !== input.transactionMaterial.reviewSessionId ||
+        input.transactionMaterialDigest.planId !== input.transactionMaterial.planId ||
+        input.transactionMaterialDigest.account !== input.transactionMaterial.account ||
+        input.transactionMaterialDigest.expiresAt !== input.transactionMaterial.expiresAt) {
+        throw new Error("transaction material digest must match material identity before ownership evidence is accepted");
+    }
+    const materialCreatedAtMs = Date.parse(input.transactionMaterial.createdAt);
+    const verifiedAtMs = Date.parse(evidence.verifiedAt);
+    const expiresAtMs = Date.parse(evidence.expiresAt);
+    if (verifiedAtMs < materialCreatedAtMs || verifiedAtMs > nowMs || verifiedAtMs >= expiresAtMs) {
+        throw new Error("transaction object ownership verifiedAt must be between material creation, now, and material expiry");
+    }
+    if (expiresAtMs <= nowMs) {
+        throw new Error("transaction object ownership evidence must not be expired");
+    }
+    const contractMapping = mapTransactionObjectOwnershipEvidenceToContractDraft(evidence);
+    if (contractMapping.status === "unsupported") {
+        throw new Error(`transaction object ownership evidence is not contract-mappable: ${contractMapping.reason}`);
+    }
+    return evidence;
+}
+export function mapTransactionObjectOwnershipEvidenceToContractDraft(evidenceInput) {
+    const evidence = parseTransactionObjectOwnershipEvidence(evidenceInput);
+    const sourceEvidenceId = "tx_object_ownership_source";
+    const claims = [];
+    const objects = [];
+    const gasObjectOwnershipLinks = [];
+    for (const [index, object] of evidence.objects.entries()) {
+        const mapped = mapOwnershipFactForContract(object);
+        if (mapped.status === "unsupported") {
+            return {
+                ...mapped,
+                objectId: object.objectId,
+                roles: object.roles,
+                ownership: object.ownership
+            };
+        }
+        const evidenceClaimId = `tx_object_ownership:${index}`;
+        claims.push(adapterEvidenceClaimSchema.parse({
+            id: evidenceClaimId,
+            factKind: "object_ownership",
+            sourceEvidenceId,
+            objectId: object.objectId,
+            ownerAccount: evidence.account,
+            ownership: mapped.ownership
+        }));
+        objects.push({
+            objectId: object.objectId,
+            role: mapped.role,
+            ownership: mapped.ownership,
+            evidenceClaimId
+        });
+        if (mapped.role === "gas_coin" && mapped.ownership === "owned_by_account") {
+            gasObjectOwnershipLinks.push(adapterGasObjectOwnershipLinkSchema.parse({
+                objectId: object.objectId,
+                ownerAccount: evidence.account,
+                ownershipClaimId: evidenceClaimId
+            }));
+        }
+    }
+    if (gasObjectOwnershipLinks.length === 0) {
+        return {
+            status: "unsupported",
+            reason: "contract mapping requires at least one owned Coin<SUI> gas object ownership link",
+            objectId: evidence.objects[0]?.objectId ?? "unknown",
+            roles: evidence.objects[0]?.roles ?? [],
+            ownership: evidence.objects[0]?.ownership ?? "unknown_owner"
+        };
+    }
+    if (!objects.some((object) => object.role !== "gas_coin")) {
+        return {
+            status: "unsupported",
+            reason: "contract mapping requires the full transaction object set, not gas-only ownership evidence",
+            objectId: evidence.objects[0]?.objectId ?? "unknown",
+            roles: evidence.objects[0]?.roles ?? [],
+            ownership: evidence.objects[0]?.ownership ?? "unknown_owner"
+        };
+    }
+    return {
+        status: "mapped",
+        sourceOfTruth: adapterSourceOfTruthSchema.parse({
+            id: sourceEvidenceId,
+            kind: "wallet_account_read",
+            network: "sui:mainnet",
+            source: "Stored local transaction data object refs plus Sui mainnet object owner reads",
+            verifiedAt: evidence.verifiedAt,
+            fields: ["ownerAccount", "objects"]
+        }),
+        evidenceClaims: claims,
+        objectOwnership: adapterObjectOwnershipEvidenceSchema.parse({
+            checkedAt: evidence.verifiedAt,
+            ownerAccount: evidence.account,
+            objects
+        }),
+        gasObjectOwnershipLinks
+    };
+}
+function mapOwnershipFactForContract(fact) {
+    if (fact.roles.includes("gas_object")) {
+        const coinObject = parseSuiCoinObjectType(fact.objectType);
+        return fact.ownership === "owned_by_account" &&
+            coinObject.status === "coin" &&
+            coinObject.coinType === SUI_GAS_COIN_TYPE
+            ? { status: "mapped", role: "gas_coin", ownership: "owned_by_account" }
+            : { status: "unsupported", reason: "gas objects must be owned by the connected account and be Coin<SUI> objects" };
+    }
+    if (fact.roles.includes("shared_object")) {
+        return fact.ownership === "shared_object"
+            ? { status: "mapped", role: "shared_object", ownership: "shared_object" }
+            : { status: "unsupported", reason: "shared object refs must have shared ownership facts" };
+    }
+    if (fact.roles.includes("receiving_object")) {
+        return fact.ownership === "owned_by_account"
+            ? { status: "mapped", role: "receiving_object", ownership: "owned_by_account" }
+            : { status: "unsupported", reason: "receiving object refs must be owned by the connected account" };
+    }
+    if (fact.roles.includes("imm_or_owned_object")) {
+        if (fact.ownership === "immutable_object") {
+            return { status: "mapped", role: "protocol_object", ownership: "immutable_or_package" };
+        }
+        const coinObject = parseSuiCoinObjectType(fact.objectType);
+        if (fact.ownership === "owned_by_account" && coinObject.status === "coin") {
+            return { status: "mapped", role: "input_coin", ownership: "owned_by_account" };
+        }
+        return {
+            status: "unsupported",
+            reason: "owned ImmOrOwnedObject refs must be Coin<T> objects before contract mapping can call them input coins"
+        };
+    }
+    return { status: "unsupported", reason: "object ownership role is not contract-mappable" };
+}