@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/passport-translation.js

@@ -0,0 +1,516 @@
+import { PASSPORT_ERROR_CODES, MAX_GUARD_COUNT_PASSPORT, MAX_SUBMISSION_SIZE_PASSPORT, } from "./passport-ledger.js";
+export const SEMANTIC_TO_SCHEMA_RULES = [
+    {
+        id: "P-PASS-01",
+        pattern_name: "Create Passport",
+        semantic_intent: "Create a new verification carrier object bound to the current transaction",
+        match_keywords: ["create", "new", "passport", "instantiate"],
+        schema_fields: ["(SubmissionCall)"],
+        example_json: {
+            type: "submission",
+            guard: [],
+            submission: [],
+        },
+        reverse_explanation: "Passport created via passport::new(clock, ctx). tx_hash bound to tx_context::digest(ctx). No Guard added yet.",
+    },
+    {
+        id: "P-PASS-02",
+        pattern_name: "Add impack Guard",
+        semantic_intent: "Add a Guard that affects the final verification result (impack=true)",
+        match_keywords: ["impack", "affect", "decisive", "critical guard"],
+        schema_fields: ["guard[].object", "guard[].impack=true"],
+        example_json: {
+            guard: [
+                { object: "kyc_guard", impack: true },
+            ],
+            submission: [
+                {
+                    guard: "kyc_guard",
+                    submission: [
+                        { identifier: 0, value: "0x1234...", value_type: "address" },
+                    ],
+                },
+            ],
+        },
+        reverse_explanation: "guard[].impack=true marks this Guard as affecting final result. At least 1 impack Guard required (else E_IMPACK_GUARD_NOT_FOUND). Failure aborts overall result to false.",
+    },
+    {
+        id: "P-PASS-03",
+        pattern_name: "Add non-impack Guard",
+        semantic_intent: "Add a Guard that only records per-Guard result (impack=false)",
+        match_keywords: ["non-impack", "record", "audit", "log"],
+        schema_fields: ["guard[].object", "guard[].impack=false"],
+        example_json: {
+            guard: [
+                { object: "audit_log_guard", impack: false },
+            ],
+            submission: [],
+        },
+        reverse_explanation: "guard[].impack=false marks this Guard as audit-only. Its result is recorded but does NOT affect final result. Useful for logging / secondary checks.",
+    },
+    {
+        id: "P-PASS-04",
+        pattern_name: "Add Guard with relies dependency",
+        semantic_intent: "Add a Guard that depends on other Guards (AND/OR logic)",
+        match_keywords: ["relies", "depend", "dependency", "and", "or"],
+        schema_fields: ["guard[].object", "guard[].impack", "(relies read from Guard object)"],
+        example_json: {
+            guard: [
+                { object: "guard_a", impack: true },
+                { object: "guard_b", impack: true },
+            ],
+            submission: [],
+        },
+        reverse_explanation: "relies is read from guard::relies(guard) — NOT set in Passport JSON. Must add relied Guards first (E_RELIES_GUARD_NOT_ADDED). relies_logic_and=true=AND, false=OR. No transitive dependencies allowed.",
+    },
+    {
+        id: "P-PASS-05",
+        pattern_name: "Verify Passport (one-time)",
+        semantic_intent: "Trigger one-time verification of all Guards; result is immutable after this call",
+        match_keywords: ["verify", "validation", "submit"],
+        schema_fields: ["(verify operation)"],
+        example_json: {
+            operation: "verify",
+        },
+        reverse_explanation: "passport::verify(self, ctx). One-time — has_verified set to true. Computes per-Guard result via relies logic, then impack Guards decide final result. Aborts E_HAS_VERIFIED if called twice.",
+    },
+    {
+        id: "P-PASS-06",
+        pattern_name: "Freeze Passport (permanent)",
+        semantic_intent: "Permanently freeze the Passport as immutable (cannot be destroyed after)",
+        match_keywords: ["freeze", "freezen", "permanent"],
+        schema_fields: ["(freezen operation)"],
+        example_json: {
+            operation: "freezen",
+        },
+        reverse_explanation: "passport::freezen(self) calls transfer::freeze_object(self). Passport becomes immutable and publicly readable. Cannot be destroyed after freezing. SDK exports as `freeze` (correct spelling).",
+    },
+    {
+        id: "P-PASS-07",
+        pattern_name: "Query result",
+        semantic_intent: "Get the final verification result (requires has_verified=true + tx_hash match)",
+        match_keywords: ["result", "query", "outcome"],
+        schema_fields: ["(result query)"],
+        example_json: {
+            operation: "result_query",
+        },
+        reverse_explanation: "passport::result(self, ctx) : bool. Aborts E_NOT_VERIFIED (5) if not yet verified; E_TX_NOT_MATCH (8) if called from a different transaction. Must be called in the same tx as verify().",
+    },
+    {
+        id: "P-PASS-08",
+        pattern_name: "Query specific Guard result (result_for_guard)",
+        semantic_intent: "Hard-verify that a specific impack Guard passed (aborts E_VERIFY_FAILED if not)",
+        match_keywords: ["result_for_guard", "hard-verify", "specific guard"],
+        schema_fields: ["(result_for_guard query)"],
+        example_json: {
+            operation: "result_for_guard",
+            guard: "kyc_guard",
+        },
+        reverse_explanation: "passport::result_for_guard(self, guard, ctx). Aborts E_NOT_IMPACK_GUARD (6) if guard is not impack; E_VERIFY_FAILED (7) if overall result=false. Used by consumers to enforce specific Guard checks.",
+    },
+    {
+        id: "P-PASS-09",
+        pattern_name: "Query impack Guard list (result_for_permission)",
+        semantic_intent: "Get the list of impack Guard addresses (lazy-filled on first call)",
+        match_keywords: ["result_for_permission", "impack list", "impack addresses"],
+        schema_fields: ["(result_for_permission query)"],
+        example_json: {
+            operation: "result_for_permission",
+        },
+        reverse_explanation: "passport::result_for_permission(self, ctx) : vector<address>. Lazy-fills self.impack on first call. Aborts E_VERIFY_FAILED (7) if overall result=false. Used by Permission/Allocation to get authorized Guard list.",
+    },
+    {
+        id: "P-PASS-10",
+        pattern_name: "Get submission value",
+        semantic_intent: "Read the submitted value for a (guard, identifier) pair",
+        match_keywords: ["submission_get", "read", "fetch submission"],
+        schema_fields: ["(submission_get query)"],
+        example_json: {
+            operation: "submission_get",
+            guard: "voting_guard",
+            identifier: 0,
+        },
+        reverse_explanation: "passport::submission_get(self, guard, identifier) : vector<u8>. Read-only — no tx_hash check. Returns the BCS-encoded value. Aborts E_SUBMISSION_NOT_FOUND (10) if no entry exists.",
+    },
+    {
+        id: "P-PASS-11",
+        pattern_name: "Destroy Passport",
+        semantic_intent: "Permanently delete the Passport to release storage (must be before freeze)",
+        match_keywords: ["destroy", "delete", "remove"],
+        schema_fields: ["(destroy operation)"],
+        example_json: {
+            operation: "destroy",
+        },
+        reverse_explanation: "passport::destroy(self) calls object::delete(id). Must be called BEFORE freeze (frozen objects are immutable, cannot be destroyed). Move ownership protects: only signer holding the object can call.",
+    },
+    {
+        id: "P-PASS-12",
+        pattern_name: "Clear all Guards (pre-verify only)",
+        semantic_intent: "Remove all Guards from Passport (only allowed before verify)",
+        match_keywords: ["guard_clear", "clear", "reset"],
+        schema_fields: ["(guard_clear operation)"],
+        example_json: {
+            operation: "guard_clear",
+        },
+        reverse_explanation: "passport::guard_clear(self, ctx). Aborts E_HAS_VERIFIED (4) if already verified; E_DIGEST_NOT_MATCH (11) if tx_hash mismatch. Useful for resetting configuration before verify.",
+    },
+];
+export const SCHEMA_TO_SEMANTIC_RULES = [
+    {
+        element_type: "field",
+        type_name: "object",
+        semantic_explanation: "Passport object reference (address). For create, no object yet; for operate, the existing Passport address.",
+    },
+    {
+        element_type: "field",
+        type_name: "guard",
+        semantic_explanation: "Array of {object, impack}. Each entry references a Guard object and marks whether it affects final result. Count ≤ MAX_GUARD_COUNT_PASSPORT=20.",
+    },
+    {
+        element_type: "field",
+        type_name: "guard[].object",
+        semantic_explanation: "Guard object address. Must be unique within the Passport (duplicate addresses overwrite existing config). Resolved via LocalMark before on-chain call.",
+    },
+    {
+        element_type: "field",
+        type_name: "guard[].impack",
+        semantic_explanation: "Boolean. true=affects final result (at least 1 required); false=audit-only. impack Guards failing → overall result=false immediately.",
+    },
+    {
+        element_type: "field",
+        type_name: "submission",
+        semantic_explanation: "Array of {guard, submission[]}. Each submission is {identifier, value, value_type}. identifier is u8 (0-255) matching Guard.table[].identifier.",
+    },
+    {
+        element_type: "field",
+        type_name: "submission[].identifier",
+        semantic_explanation: "u8 (0-255). References Guard.table[identifier]. Must be marked b_submission=true in the Guard.",
+    },
+    {
+        element_type: "field",
+        type_name: "submission[].value",
+        semantic_explanation: "Value matching submission[].value_type. BCS-serialized on-chain; total serialized size per submission ≤ MAX_SUBMISSION_SIZE_PASSPORT=256 bytes.",
+    },
+    {
+        element_type: "field",
+        type_name: "submission[].value_type",
+        semantic_explanation: "Type string: 'address' | 'u64' | 'bool' | 'string' | 'vector<u8>' etc. Must match Guard.table[identifier].value_type.",
+    },
+    {
+        element_type: "op",
+        type_name: "create (new)",
+        semantic_explanation: "passport::new(clock, ctx) → Passport. Binds tx_hash = tx_context::digest(ctx). signer = tx_context::sender(ctx). time = clock::timestamp_ms(clock).",
+    },
+    {
+        element_type: "op",
+        type_name: "guard_add",
+        semantic_explanation: "passport::guard_add(self, guard, identifiers, values, impack, ctx). Pre-verify only. Reads guard::relies(guard) for dependency info. Aborts E_RELIES_GUARD_NOT_ADDED if relies missing.",
+    },
+    {
+        element_type: "op",
+        type_name: "verify",
+        semantic_explanation: "passport::verify(self, ctx) : bool. One-time. Computes per-Guard result via relies, then impack Guards decide final result. Sets has_verified=true.",
+    },
+    {
+        element_type: "op",
+        type_name: "freezen",
+        semantic_explanation: "passport::freezen(self). Permanent freeze (transfer::freeze_object). Cannot destroy after. Historical typo: Move function name is 'freezen' (not 'freeze'), retained for compatibility. SDK exports as `freeze`.",
+    },
+    {
+        element_type: "op",
+        type_name: "destroy",
+        semantic_explanation: "passport::destroy(self). Releases storage (object::delete). Must be before freeze. Move ownership protects: only object holder can call.",
+    },
+    {
+        element_type: "impack",
+        type_name: "impack=true",
+        semantic_explanation: "Guard affects final result. At least 1 required (E_IMPACK_GUARD_NOT_FOUND). Failure → overall result=false, immediate return.",
+    },
+    {
+        element_type: "impack",
+        type_name: "impack=false",
+        semantic_explanation: "Guard is audit-only. Per-Guard result is recorded but does NOT affect final result. Useful for logging / secondary checks.",
+    },
+    {
+        element_type: "relies_logic",
+        type_name: "AND (relies_logic_and=true)",
+        semantic_explanation: "All relied Guards must pass. Short-circuits on first false. Initial value = true; result = true AND rely1.result AND rely2.result ...",
+    },
+    {
+        element_type: "relies_logic",
+        type_name: "OR (relies_logic_and=false)",
+        semantic_explanation: "Any relied Guard may pass. Short-circuits on first true. Initial value = false; result = false OR rely1.result OR rely2.result ...",
+    },
+    {
+        element_type: "lifecycle",
+        type_name: "new → guard_add → verify → use → freeze/destroy",
+        semantic_explanation: "5-stage lifecycle. verify is one-time. freeze and destroy are mutually exclusive terminal states. All write ops (guard_add/verify) require tx_hash match.",
+    },
+];
+export const PASSPORT_CONSTRAINT_RULES = [
+    {
+        id: "T-PASS-01",
+        category: "structural",
+        rule: "Passport is created via the SubmissionCall mechanism, not the standard Call pattern (schema/call/base.ts SubmissionCallSchema)",
+        applies_to: ["SubmissionCall", "passport::new"],
+    },
+    {
+        id: "T-PASS-02",
+        category: "logic",
+        rule: "Guards with guard[].impack=true decide the final result; at least 1 impack Guard is required (E_IMPACK_GUARD_NOT_FOUND=9)",
+        applies_to: ["guard[].impack", "verify operation"],
+    },
+    {
+        id: "T-PASS-03",
+        category: "logic",
+        rule: "Depended-on Guards must be added first (topological order); guard_add checks relies, missing relies aborts E_RELIES_GUARD_NOT_ADDED=2",
+        applies_to: ["guard_add operation", "guard::relies(guard)"],
+    },
+    {
+        id: "T-PASS-04",
+        category: "lifecycle",
+        rule: "After verify, config cannot be modified (has_verified is one-time); second calls to guard_add/guard_clear/verify abort E_HAS_VERIFIED=4",
+        applies_to: ["verify operation", "has_verified field"],
+    },
+    {
+        id: "T-PASS-05",
+        category: "lifecycle",
+        rule: "tx_hash binding ensures Passport cannot be reused across transactions; write functions and result queries check tx_hash match",
+        applies_to: ["tx_hash field", "guard_add", "verify", "result"],
+    },
+    {
+        id: "T-PASS-06",
+        category: "structural",
+        rule: "submission data must match Guard identifier type; BCS serialization ≤ MAX_SUBMISSION_SIZE_PASSPORT=256 bytes",
+        applies_to: ["submission[].value_type", "submission[].identifier"],
+    },
+    {
+        id: "T-PASS-07",
+        category: "lifecycle",
+        rule: "result query must be in the same transaction (tx_hash matches current transaction); otherwise E_TX_NOT_MATCH=8",
+        applies_to: ["result operation", "result_for_guard", "result_for_permission"],
+    },
+    {
+        id: "T-PASS-08",
+        category: "lifecycle",
+        rule: "After freeze, Passport is permanently retained (cannot be destroyed); freezen calls transfer::freeze_object",
+        applies_to: ["freezen operation", "destroy operation"],
+    },
+    {
+        id: "T-PASS-09",
+        category: "lifecycle",
+        rule: "destroy must happen before freeze (destroyable when not frozen); after freezing the object becomes immutable and cannot be received by value",
+        applies_to: ["destroy operation", "freezen operation"],
+    },
+    {
+        id: "T-PASS-10",
+        category: "operational",
+        rule: "explainPassport must translate impack and result status; use passport.object (not passport.id) as the object identifier",
+        applies_to: ["explainPassport function", "ObjectPassportSchema"],
+    },
+    {
+        id: "T-PASS-11",
+        category: "logic",
+        rule: "relies logic (AND/OR) must be reflected in explainPassport; relies_logic_and=true=AND, false=OR",
+        applies_to: ["explainPassport function", "guard::relies(guard)"],
+    },
+    {
+        id: "T-PASS-12",
+        category: "structural",
+        rule: "Guard count ≤ MAX_GUARD_COUNT_PASSPORT=20; submission serialized size ≤ MAX_SUBMISSION_SIZE_PASSPORT=256 bytes",
+        applies_to: ["guard array", "submission array"],
+    },
+];
+export const PASSPORT_TRANSLATION_VERSION = "1.0.0";
+export function matchSemanticPattern(userIntent) {
+    const lower = userIntent.toLowerCase();
+    return SEMANTIC_TO_SCHEMA_RULES.filter(rule => rule.match_keywords.some(kw => lower.includes(kw.toLowerCase())));
+}
+export function explainPassport(passport) {
+    const lines = [];
+    lines.push(`Passport ${passport.object}`);
+    lines.push(`  Signer: ${passport.signer}`);
+    lines.push(`  Time: ${new Date(passport.time).toISOString()}`);
+    lines.push(`  Verified: ${passport.has_verified}`);
+    if (passport.has_verified) {
+        lines.push(`  Result: ${passport.result ? "PASS ✅" : "FAIL ❌"}`);
+    }
+    lines.push(`  Guards: ${passport.info.length}/${MAX_GUARD_COUNT_PASSPORT}`);
+    if (passport.info.length > 0) {
+        lines.push(`  Guard details:`);
+        for (const g of passport.info) {
+            const impackDesc = g.impack ? "IMPACK" : "non-impack";
+            const resultDesc = g.result ? "PASS" : "FAIL";
+            lines.push(`    - Guard ${g.guard}: ${resultDesc} (${impackDesc})`);
+        }
+    }
+    if (passport.impack_guard && passport.impack_guard.length > 0) {
+        lines.push(`  impack_guard list (lazy-filled): ${passport.impack_guard.join(", ")}`);
+    }
+    if (passport.tx_hash) {
+        lines.push(`  tx_hash: ${passport.tx_hash}`);
+    }
+    return lines.join("\n");
+}
+export function passportJsonToSemantic(data) {
+    const lines = [];
+    if (data.type === "submission" || (data.guard && data.guard.length > 0)) {
+        lines.push("Operation: CREATE Passport via SubmissionCall");
+        if (data.guard && data.guard.length > 0) {
+            const impackCount = data.guard.filter(g => g.impack).length;
+            const nonImpackCount = data.guard.length - impackCount;
+            lines.push(`- Guards: ${data.guard.length}/${MAX_GUARD_COUNT_PASSPORT} (${impackCount} impack, ${nonImpackCount} non-impack)`);
+            if (impackCount === 0) {
+                lines.push("  ⚠️ No impack Guard — verify will abort E_IMPACK_GUARD_NOT_FOUND (9)");
+            }
+            data.guard.forEach((g, i) => {
+                const impackDesc = g.impack ? "IMPACK (affects result)" : "non-impack (audit-only)";
+                lines.push(`  [${i}] ${g.object} — ${impackDesc}`);
+            });
+        }
+        if (data.submission && data.submission.length > 0) {
+            lines.push(`- Submissions: ${data.submission.length} guard(s) with submission data`);
+            for (const s of data.submission) {
+                const totalSize = s.submission.reduce((sum, item) => sum + estimateSubmissionSize(item.value_type), 0);
+                const sizeWarn = totalSize > MAX_SUBMISSION_SIZE_PASSPORT
+                    ? ` ⚠️ ${totalSize} > ${MAX_SUBMISSION_SIZE_PASSPORT} bytes (E_SUBMISSION_SIZE_EXCEEDED)`
+                    : "";
+                lines.push(`  - guard=${s.guard}: ${s.submission.length} item(s), estimated size=${totalSize} bytes${sizeWarn}`);
+            }
+        }
+    }
+    else if (data.operation) {
+        lines.push(`Operation: ${data.operation.toUpperCase()}`);
+        switch (data.operation) {
+            case "verify":
+                lines.push("- One-time verification; sets has_verified=true, computes final result");
+                lines.push("- Aborts E_HAS_VERIFIED (4) if already verified");
+                break;
+            case "freezen":
+                lines.push("- Permanent freeze (transfer::freeze_object)");
+                lines.push("- Cannot be destroyed after freezing");
+                break;
+            case "destroy":
+                lines.push("- Permanent deletion (object::delete)");
+                lines.push("- Must be called BEFORE freeze");
+                break;
+            case "guard_clear":
+                lines.push("- Removes all Guards from Passport");
+                lines.push("- Only allowed before verify (E_HAS_VERIFIED if verified)");
+                break;
+            case "result_query":
+                lines.push("- Returns final verification result (bool)");
+                lines.push("- Requires has_verified=true (E_NOT_VERIFIED) and tx_hash match (E_TX_NOT_MATCH)");
+                break;
+            case "result_for_guard":
+                lines.push(`- Hard-verifies Guard ${data.guard_target} is impack and passed`);
+                lines.push("- Aborts E_NOT_IMPACK_GUARD (6) if not impack; E_VERIFY_FAILED (7) if result=false");
+                break;
+            case "result_for_permission":
+                lines.push("- Returns impack Guard address list (lazy-filled)");
+                lines.push("- Aborts E_VERIFY_FAILED (7) if overall result=false");
+                break;
+            case "submission_get":
+                lines.push(`- Reads submission value for (guard=${data.guard_target}, identifier=${data.identifier})`);
+                lines.push("- Read-only, no tx_hash check");
+                lines.push("- Aborts E_SUBMISSION_NOT_FOUND (10) if no entry");
+                break;
+        }
+    }
+    else {
+        lines.push("⚠️ Cannot determine operation: provide 'type: submission' with guard[], or 'operation' field");
+    }
+    return lines.join("\n");
+}
+export function semanticToPassportJson(intent) {
+    switch (intent.action) {
+        case "create": {
+            if (!intent.guards || intent.guards.length === 0) {
+                throw new Error("Create action requires at least 1 Guard in intent.guards");
+            }
+            if (intent.guards.length > MAX_GUARD_COUNT_PASSPORT) {
+                throw new Error(`Guard count ${intent.guards.length} exceeds MAX_GUARD_COUNT_PASSPORT=${MAX_GUARD_COUNT_PASSPORT}`);
+            }
+            const hasImpack = intent.guards.some(g => g.impack);
+            if (!hasImpack) {
+                throw new Error("At least 1 Guard must have impack=true (else verify aborts E_IMPACK_GUARD_NOT_FOUND=9)");
+            }
+            return {
+                type: "submission",
+                guard: intent.guards.map(g => ({ object: g.object, impack: g.impack })),
+                submission: intent.guards
+                    .filter(g => g.submission && g.submission.length > 0)
+                    .map(g => ({ guard: g.object, submission: g.submission })),
+            };
+        }
+        case "verify":
+            return { operation: "verify" };
+        case "freeze":
+            return { operation: "freezen" };
+        case "destroy":
+            return { operation: "destroy" };
+        case "guard_clear":
+            return { operation: "guard_clear" };
+        case "query_result":
+            return { operation: "result_query" };
+        case "query_guard_result":
+            if (!intent.targetGuard)
+                throw new Error("query_guard_result requires intent.targetGuard");
+            return { operation: "result_for_guard", guard_target: intent.targetGuard };
+        case "query_impack_list":
+            return { operation: "result_for_permission" };
+        case "get_submission":
+            if (!intent.targetGuard)
+                throw new Error("get_submission requires intent.targetGuard");
+            if (intent.targetIdentifier === undefined)
+                throw new Error("get_submission requires intent.targetIdentifier");
+            return {
+                operation: "submission_get",
+                guard_target: intent.targetGuard,
+                identifier: intent.targetIdentifier,
+            };
+    }
+}
+export function explainField(fieldName) {
+    return SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "field" && r.type_name === fieldName);
+}
+export function explainOp(opName) {
+    return SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "op" && r.type_name === opName);
+}
+export function explainImpack(impackValue) {
+    return SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "impack" && r.type_name === `impack=${impackValue}`);
+}
+export function explainReliesLogic(logicAnd) {
+    const name = logicAnd ? "AND (relies_logic_and=true)" : "OR (relies_logic_and=false)";
+    return SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "relies_logic" && r.type_name === name);
+}
+export function getConstraintsByCategory(category) {
+    return PASSPORT_CONSTRAINT_RULES.filter(r => r.category === category);
+}
+export function explainError(code) {
+    const descriptions = {
+        [PASSPORT_ERROR_CODES.E_GUARD_COUNT_EXCEEDED]: "Guard count exceeds MAX_GUARD_COUNT_PASSPORT (20) — remove non-essential Guards or merge similar ones",
+        [PASSPORT_ERROR_CODES.E_RELIES_GUARD_NOT_ADDED]: "Relied Guard not yet added — add relied Guards in topological order before adding the dependent Guard",
+        [PASSPORT_ERROR_CODES.E_SUBMISSION_SIZE_EXCEEDED]: "Submission serialized size exceeds MAX_SUBMISSION_SIZE_PASSPORT (256 bytes) — use Repository reference for large data",
+        [PASSPORT_ERROR_CODES.E_HAS_VERIFIED]: "Passport already verified — verify is one-time; create a new Passport to re-verify",
+        [PASSPORT_ERROR_CODES.E_NOT_VERIFIED]: "result() called before verify() — call verify() first in the same transaction",
+        [PASSPORT_ERROR_CODES.E_NOT_IMPACK_GUARD]: "result_for_guard called on non-impack Guard — only impack Guards can be hard-verified",
+        [PASSPORT_ERROR_CODES.E_VERIFY_FAILED]: "result_for_guard / result_for_permission called when overall result=false — fix Guard configuration or submission data",
+        [PASSPORT_ERROR_CODES.E_TX_NOT_MATCH]: "result() called from a different transaction — Passport is tx_hash-bound, must query in the same tx as verify()",
+        [PASSPORT_ERROR_CODES.E_IMPACK_GUARD_NOT_FOUND]: "verify() found no impack Guard — at least 1 Guard must have impack=true",
+        [PASSPORT_ERROR_CODES.E_SUBMISSION_NOT_FOUND]: "submission_get found no entry for (guard, identifier) — check Guard.table[identifier].b_submission=true",
+        [PASSPORT_ERROR_CODES.E_DIGEST_NOT_MATCH]: "guard_add / verify / guard_clear called from a different transaction — Passport is tx_hash-bound",
+    };
+    return descriptions[code] ?? `Unknown Passport error code: ${code}`;
+}
+function estimateSubmissionSize(valueType) {
+    switch (valueType) {
+        case "bool": return 1;
+        case "u8": return 1;
+        case "u64": return 8;
+        case "address": return 32;
+        case "string": return 32;
+        case "vector<u8>": return 32;
+        default: return 64;
+    }
+}

package/dist/knowledge/payment-risk.d.ts

@@ -0,0 +1,33 @@
+export type PaymentRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export type PaymentRiskCategory = "structural" | "semantic" | "lifecycle" | "permission" | "cross_object" | "knowledge";
+export type PaymentStakeholder = "signer" | "recipient" | "consumer" | "system";
+export interface PaymentRisk {
+    id: string;
+    level: PaymentRiskLevel;
+    category: PaymentRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: PaymentStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+    related_move_error?: string;
+    auto_fixable: boolean;
+}
+export interface PaymentRiskCheckContext {
+    recipient_count?: number;
+    uses_unsafe_unwrap?: boolean;
+    expects_mutation?: boolean;
+    payment_info_variant?: "payment_info" | "payment_info2" | "payment_info_with_guard" | "payment_info2_with_guard";
+    expects_user_recipient_registered?: boolean;
+    uses_signer_for_provenance?: boolean;
+    coin_field_lint_reviewed?: boolean;
+    constants_synced?: boolean;
+}
+export declare const PAYMENT_RISK_RULES: {
+    rule: PaymentRisk;
+    check: (ctx: PaymentRiskCheckContext) => PaymentRisk | null;
+}[];
+export declare const PAYMENT_RISK_VERSION = "1.0.0";
+export declare function checkPaymentRisks(ctx: PaymentRiskCheckContext): PaymentRisk[];
+export declare function getPaymentRiskById(id: string): PaymentRisk | undefined;