@wowok/agent-mcp 2.4.3 → 2.5.0

package/dist/knowledge/progress-translation.js

@@ -0,0 +1,401 @@
+import { isProgressBuiltinPermission, getBuiltinPermissionByIndex, } from "./progress-ledger.js";
+export const PROGRESS_SEMANTIC_TO_SCHEMA_RULES = [
+    {
+        id: "P-PR-01",
+        pattern_name: "Advance Progress (next / order_next)",
+        semantic_intent: "Push Progress forward via a Forward definition; accumulate weight, possibly complete session",
+        match_keywords: ["next", "advance", "proceed", "complete forward"],
+        schema_fields: ["object", "operate(operation, op='next')"],
+        example_json: {
+            object: "0xPROGRESS_ADDRESS",
+            operate: {
+                operation: { next_node_name: "shipped", forward: "ship" },
+                op: "next",
+                message: "Order shipped via FedEx, tracking 12345",
+            },
+        },
+        reverse_explanation: "operate.op='next' → calls progress::next or order_next (if task bound). " +
+            "Move accumulates forward.weight; on reaching threshold, session → history and current = next_node_name.",
+    },
+    {
+        id: "P-PR-02",
+        pattern_name: "Hold Progress (block forward)",
+        semantic_intent: "Lock a Forward so no one else can advance it until unhold",
+        match_keywords: ["hold", "lock", "block", "pause forward"],
+        schema_fields: ["object", "operate(operation, op='hold', message)"],
+        example_json: {
+            object: "0xPROGRESS_ADDRESS",
+            operate: {
+                operation: { next_node_name: "revision_required", forward: "request_revision" },
+                op: "hold",
+                message: "Please revise section 3",
+            },
+        },
+        reverse_explanation: "operate.op='hold' → calls progress::hold or order_hold. session_hold sets Holder.who = sender; " +
+            "other callers will hit E_NOT_THE_HOLDER if they try to advance.",
+    },
+    {
+        id: "P-PR-03",
+        pattern_name: "Self-unhold (release own hold)",
+        semantic_intent: "Release a forward that I previously held",
+        match_keywords: ["unhold", "release", "self release"],
+        schema_fields: ["object", "operate(operation, op='unhold')"],
+        example_json: {
+            object: "0xPROGRESS_ADDRESS",
+            operate: {
+                operation: { next_node_name: "reviewing", forward: "resubmit" },
+                op: "unhold",
+                message: "Revised content uploaded",
+            },
+        },
+        reverse_explanation: "operate.op='unhold' → calls progress::hold(bHold=false) or order_hold(bHold=false). " +
+            "Move's session_hold releases the lock (sender == Holder.who). " +
+            "After release, the forward can be re-locked or accomplished by eligible callers.",
+    },
+    {
+        id: "P-PR-04",
+        pattern_name: "Admin force-unhold (224 permission)",
+        semantic_intent: "Force-release a held forward using 224 permission, bypassing holder check",
+        match_keywords: ["adminUnhold", "force unhold", "admin release"],
+        schema_fields: ["object", "operate(operation, op='adminUnhold')"],
+        example_json: {
+            object: "0xPROGRESS_ADDRESS",
+            operate: {
+                operation: { next_node_name: "arb_decided", forward: "decide" },
+                op: "adminUnhold",
+                message: "Admin override: holder unresponsive for 7 days",
+            },
+        },
+        reverse_explanation: "operate.op='adminUnhold' → calls progress::unhold. Move checks sender_has_permission_idcheck(224); " +
+            "if true, force release (bForce=true). If false, falls back to holder-match check.",
+    },
+    {
+        id: "P-PR-05",
+        pattern_name: "Bind task (one-time, immutable)",
+        semantic_intent: "Associate an Order/Reward address with this Progress (only once per Progress)",
+        match_keywords: ["task_set", "bind task", "set task"],
+        schema_fields: ["object", "task"],
+        example_json: {
+            object: "0xPROGRESS_ADDRESS",
+            task: "0xORDER_ADDRESS",
+        },
+        reverse_explanation: "Calls progress::task_set. Move asserts option::is_none(&self.task); if already set, E_TASK_ALREADY_SET aborts. " +
+            "There is NO task_unset — once bound, the Progress is permanently tied to that Order/Reward.",
+    },
+    {
+        id: "P-PR-06",
+        pattern_name: "Manage context repositories",
+        semantic_intent: "Add/remove/clear Repository objects as query context (≤ 30 total)",
+        match_keywords: ["repository", "context"],
+        schema_fields: ["object", "repository(op, objects)"],
+        example_json: {
+            object: "0xPROGRESS_ADDRESS",
+            repository: { op: "add", objects: ["0xREPO1", "0xREPO2"] },
+        },
+        reverse_explanation: "op=add: appends (idempotent via vector::contains). op=remove: drops listed addresses. " +
+            "op=clear: empties the list. op=set: clears then adds. Count must stay ≤ MAX_CONTEXT_REPOSITORY_COUNT (30).",
+    },
+    {
+        id: "P-PR-07",
+        pattern_name: "Manage named_operator namespace",
+        semantic_intent: "Add/set/remove addresses for a named operator role (Forward gate)",
+        match_keywords: ["named_operator", "operator"],
+        schema_fields: ["object", "progress_namedOperator(op, name, operators)"],
+        example_json: {
+            object: "0xPROGRESS_ADDRESS",
+            progress_namedOperator: {
+                op: "add",
+                name: "logistics",
+                operators: ["0xADDR1", "0xADDR2"],
+            },
+        },
+        reverse_explanation: "op=add: appends (deduped). op=set: REPLACES the address list. op=remove: drops listed addresses. " +
+            "Up to 60 named_operator names per Progress; up to 80 addresses per name.",
+    },
+    {
+        id: "P-PR-08",
+        pattern_name: "Owner receive (terminal node unwrap)",
+        semantic_intent: "Owner receives Receiving<K> objects or CoinWrapper<T> coins at a terminal node",
+        match_keywords: ["owner_receive", "unwrap", "withdraw"],
+        schema_fields: ["(SDK does not expose this in CallProgress_Data — direct move call required)"],
+        example_json: {
+            _note: "Not exposed in CallProgress_Data; direct Move call:",
+            target: "progress::owner_receive<T>",
+            arguments: ["progress", "machine", "permission", "received", "payment"],
+        },
+        reverse_explanation: "Calls progress::owner_receive (225 permission). Unwraps CoinWrapper<T> via Payment.unwrap_with_check, " +
+            "forwards coin/object to Permission owner. Typically triggered at terminal nodes (deposit_refunded, completed, enforced).",
+    },
+];
+export const PROGRESS_SCHEMA_TO_SEMANTIC_RULES = [
+    {
+        element_type: "field",
+        type_name: "object",
+        semantic_explanation: "Progress object address. Always required for operate calls (Progress is created indirectly via service::buy).",
+    },
+    {
+        element_type: "field",
+        type_name: "task",
+        semantic_explanation: "Bind a task (Order/Reward) address. ONE-TIME only — E_TASK_ALREADY_SET on re-set.",
+    },
+    {
+        element_type: "field",
+        type_name: "repository",
+        semantic_explanation: "Context Repository list management. op=add/set/remove/clear. Total ≤ MAX_CONTEXT_REPOSITORY_COUNT (30).",
+    },
+    {
+        element_type: "field",
+        type_name: "progress_namedOperator",
+        semantic_explanation: "named_operator namespace management. name='' is the OrderHolder special namespace. ≤ 60 names, ≤ 80 addresses each.",
+    },
+    {
+        element_type: "field",
+        type_name: "operate",
+        semantic_explanation: "Forward advancement / hold / unhold. Contains operation (next_node_name + forward) and hold/adminUnhold/message flags.",
+    },
+    {
+        element_type: "field",
+        type_name: "operate.operation.next_node_name",
+        semantic_explanation: "Target node name. Must exist in Machine and be reachable from current via a Forward definition.",
+    },
+    {
+        element_type: "field",
+        type_name: "operate.operation.forward",
+        semantic_explanation: "Forward name. Must be one of the forwards defined from current → next_node_name in the Machine.",
+    },
+    {
+        element_type: "field",
+        type_name: "operate.op",
+        semantic_explanation: "Operation type: 'next' = advance forward; 'hold' = lock forward (Holder.who = sender); 'unhold' = self-release own hold; 'adminUnhold' = force release via 224 permission (bypasses holder check).",
+    },
+    {
+        element_type: "field",
+        type_name: "operate.message",
+        semantic_explanation: "Deliverable message (≤ MAX_LONG_NAME_LENGTH). Stored in Holder.msg / delivered on accomplishment.",
+    },
+    {
+        element_type: "op",
+        type_name: "next",
+        semantic_explanation: "Plain forward advance. Use when no bound Order, OR caller is named_operator (not OrderHolder).",
+    },
+    {
+        element_type: "op",
+        type_name: "order_next",
+        semantic_explanation: "Order-bound forward advance. Caller must satisfy order.has_op_permission (order owner/agent).",
+    },
+    {
+        element_type: "op",
+        type_name: "hold",
+        semantic_explanation: "Lock forward. Holder.who = sender; subsequent callers hit E_NOT_THE_HOLDER.",
+    },
+    {
+        element_type: "op",
+        type_name: "order_hold",
+        semantic_explanation: "Order-bound hold. Same as hold but uses order.has_op_permission for OrderHolder verification.",
+    },
+    {
+        element_type: "op",
+        type_name: "unhold",
+        semantic_explanation: "Self-release (sender == Holder.who) OR admin force-release (224 permission).",
+    },
+    {
+        element_type: "op",
+        type_name: "namedOperator_add",
+        semantic_explanation: "Append addresses to a named_operator (deduped; fails if name new and ≥ 60 names).",
+    },
+    {
+        element_type: "op",
+        type_name: "namedOperator_set",
+        semantic_explanation: "REPLACE the address list for a named_operator name (or create if name new).",
+    },
+    {
+        element_type: "op",
+        type_name: "namedOperator_remove",
+        semantic_explanation: "Drop listed addresses from a named_operator name (no-op if name doesn't exist).",
+    },
+    {
+        element_type: "phase",
+        type_name: "creation",
+        semantic_explanation: "Indirect: service::buy → progress::new_imp (bypasses 220 assertion via package-internal entry).",
+    },
+    {
+        element_type: "phase",
+        type_name: "task_binding",
+        semantic_explanation: "One-time task_set (222). E_TASK_ALREADY_SET on any retry.",
+    },
+    {
+        element_type: "phase",
+        type_name: "forward_advance",
+        semantic_explanation: "Dynamic permission: IsNamedOperator OR Forward.permissionIndex OR Forward.guard (Passport). NOT 220-225.",
+    },
+    {
+        element_type: "phase",
+        type_name: "completed",
+        semantic_explanation: "session.weights ≥ threshold → push to history, current = next_node. Atomic.",
+    },
+];
+export const PROGRESS_CONSTRAINT_RULES = [
+    {
+        id: "MC-PR-01",
+        category: "structural",
+        rule: "Machine must be published before Progress creation (machine::on_progress_new asserts published state)",
+        applies_to: ["creation"],
+    },
+    {
+        id: "MC-PR-02",
+        category: "structural",
+        rule: "Progress.machine is immutable after creation (E_MACHINE_NOT_MATCH on every op)",
+        applies_to: ["operate", "task", "repository", "progress_namedOperator"],
+    },
+    {
+        id: "MC-PR-03",
+        category: "structural",
+        rule: "named_operator count < MAX_NAMED_OPERATOR_COUNT (60); E_MAX_NAMED_OPERATOR_COUNT on overflow",
+        applies_to: ["progress_namedOperator.op=add (new name)"],
+    },
+    {
+        id: "MC-PR-04",
+        category: "structural",
+        rule: "named_operator addresses < MAX_NAMED_OPERATOR_ADDRESS_COUNT (80); E_MAX_NAMED_OPERATOR_ADDRESS_COUNT on overflow",
+        applies_to: ["progress_namedOperator.operators"],
+    },
+    {
+        id: "MC-PR-05",
+        category: "structural",
+        rule: "context_repository count < MAX_CONTEXT_REPOSITORY_COUNT (30); E_MAX_CONTEXT_REPOSITORY_COUNT on overflow",
+        applies_to: ["repository.op=add", "repository.op=set"],
+    },
+    {
+        id: "MC-PR-06",
+        category: "semantic",
+        rule: "task_set is one-time: E_TASK_ALREADY_SET blocks any re-assignment",
+        applies_to: ["task"],
+    },
+    {
+        id: "MC-PR-07",
+        category: "semantic",
+        rule: "operate.op must be one of: next | hold | unhold | adminUnhold (schema-enforced enum)",
+        applies_to: ["operate.op"],
+    },
+    {
+        id: "MC-PR-08",
+        category: "semantic",
+        rule: "operate.message must satisfy common::LONG_NAME (≤ MAX_LONG_NAME_LENGTH)",
+        applies_to: ["operate.message"],
+    },
+    {
+        id: "MC-PR-09",
+        category: "permission",
+        rule: "Forward advance uses DYNAMIC permission: namedOperator OR Forward.permissionIndex OR Forward.guard — NOT 220-225",
+        applies_to: ["operate (next/hold/unhold)"],
+    },
+    {
+        id: "MC-PR-10",
+        category: "permission",
+        rule: "220-225 builtin indexes are MANAGEMENT-ONLY (named_operator/task/repository/unhold/owner_receive)",
+        applies_to: ["progress_namedOperator", "task", "repository", "operate.op='adminUnhold'"],
+    },
+    {
+        id: "MC-PR-11",
+        category: "permission",
+        rule: "adminUnhold (224) bypasses holder check — grant only to dedicated recovery addresses",
+        applies_to: ["operate.op='adminUnhold'"],
+    },
+    {
+        id: "MC-PR-12",
+        category: "lifecycle",
+        rule: "Forward already accomplished → E_FORWARD_ALREADY_ACCOMPLISHED on re-hold (idempotent completion)",
+        applies_to: ["operate.op='hold'"],
+    },
+    {
+        id: "MC-PR-13",
+        category: "lifecycle",
+        rule: "unhold by non-holder requires 224 permission; else E_NOT_THE_HOLDER",
+        applies_to: ["operate.op='unhold'"],
+    },
+    {
+        id: "MC-PR-14",
+        category: "cross_object",
+        rule: "order_next/order_hold require progress.task == order address (E_ORDER_NOT_MATCH)",
+        applies_to: ["operate (order variant)"],
+    },
+    {
+        id: "MC-PR-15",
+        category: "cross_object",
+        rule: "context_repository_add creates Registrar affiliation — remove before deleting Repository",
+        applies_to: ["repository.op=add"],
+    },
+    {
+        id: "MC-PR-16",
+        category: "cross_object",
+        rule: "Forward.guard (Some) requires *_with_passport variant; plain next() aborts E_NEED_PASSPORT",
+        applies_to: ["operate (guarded forward)"],
+    },
+];
+export const PROGRESS_TRANSLATION_VERSION = "1.0.0";
+export function matchSemanticPattern(userIntent) {
+    const lower = userIntent.toLowerCase();
+    return PROGRESS_SEMANTIC_TO_SCHEMA_RULES.filter(rule => rule.match_keywords.some(kw => lower.includes(kw.toLowerCase())));
+}
+export function explainProgressCallData(data) {
+    const lines = [];
+    if (!data.object) {
+        lines.push("Operation: CREATE Progress (indirect — service::buy → new_imp)");
+    }
+    else {
+        lines.push(`Operation: OPERATE Progress at ${data.object}`);
+    }
+    if (data.task) {
+        lines.push(`- ⚠️ task_set: ${data.task} (one-time, immutable — E_TASK_ALREADY_SET on re-set)`);
+    }
+    if (data.repository) {
+        const r = data.repository;
+        const objCount = r.objects?.length ?? 0;
+        lines.push(`- Repository ${r.op}: ${objCount} object(s)`);
+    }
+    if (data.progress_namedOperator) {
+        const n = data.progress_namedOperator;
+        const opCount = n.operators?.length ?? 0;
+        const nameDisplay = n.name === "" ? "(OrderHolder namespace)" : `"${n.name}"`;
+        lines.push(`- namedOperator ${n.op} ${nameDisplay}: ${opCount} address(es)`);
+    }
+    if (data.operate) {
+        const o = data.operate;
+        lines.push(`- Operation: ${o.operation.forward} → ${o.operation.next_node_name}`);
+        if (o.op) {
+            lines.push(`  op=${o.op}`);
+        }
+        if (o.op === "hold") {
+            lines.push(`  ⚠️ hold: lock this forward (Holder.who = sender)`);
+        }
+        else if (o.op === "adminUnhold") {
+            lines.push(`  ⚠️ adminUnhold: force release via 224 permission (bypasses holder check)`);
+        }
+        else if (o.op === "unhold") {
+            lines.push(`  ℹ️ unhold: self-release own hold (sender must == Holder.who)`);
+        }
+        else {
+            lines.push(`  Submit result (advance forward, accumulate weight toward threshold)`);
+        }
+        if (o.message) {
+            lines.push(`  Message: "${o.message}"`);
+        }
+    }
+    return lines.join("\n");
+}
+export function explainField(fieldName) {
+    return PROGRESS_SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "field" && r.type_name === fieldName);
+}
+export function explainOp(opName) {
+    return PROGRESS_SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "op" && r.type_name === opName);
+}
+export function getConstraintsByCategory(category) {
+    return PROGRESS_CONSTRAINT_RULES.filter(r => r.category === category);
+}
+export function explainPermissionIndex(index) {
+    if (isProgressBuiltinPermission(index)) {
+        const entry = getBuiltinPermissionByIndex(index);
+        return `${entry.name} (${index}) — ${entry.description}`;
+    }
+    return `Custom/dynamic permission index (${index}) — resolved via Forward.permissionIndex in Machine`;
+}

package/dist/knowledge/proof-confirm.d.ts

@@ -0,0 +1,31 @@
+export type ConfirmSeverity = "block" | "warn" | "info";
+export interface ProofConfirmItem {
+    id: string;
+    severity: ConfirmSeverity;
+    title: string;
+    description: string;
+    passed: boolean;
+    evidence?: string;
+    fix_hint?: string;
+}
+export interface ProofCreationCheckInput {
+    description?: string;
+    proof?: string;
+    server_pubkey?: string;
+    server_signature?: string;
+    proof_type?: number | bigint | string;
+    item_count?: number | bigint | string | null;
+    about_address?: string | null;
+    namedNew?: {
+        name: string;
+        tag?: string;
+    } | null;
+}
+export declare function preCheckProofCreation(input: ProofCreationCheckInput): ProofConfirmItem[];
+export declare function canCreateProof(input: ProofCreationCheckInput): {
+    canCreate: boolean;
+    blockers: ProofConfirmItem[];
+    warnings: ProofConfirmItem[];
+    info: ProofConfirmItem[];
+};
+export declare function formatProofCreationSummary(input: ProofCreationCheckInput): string;

package/dist/knowledge/proof-confirm.js

@@ -0,0 +1,187 @@
+import { MAX_PROOF_SIZE, MAX_SERVER_PUBKEY_SIZE, MAX_SERVER_SIGNATURE_SIZE, WOWOK_WTS_PROOF_TYPE, } from "@wowok/wowok";
+function checkDescription(input) {
+    const passed = !!input.description && input.description.length > 0;
+    return {
+        id: "C-PROOF-01",
+        severity: passed ? "info" : "warn",
+        title: "description is provided and non-empty",
+        description: "description is a REQUIRED field (PF-D-2=A). Move contract stores it as String; SDK enforces isValidDescription. " +
+            "Empty string (\"\") is technically valid but makes the Proof hard to identify in queries.",
+        passed,
+        evidence: input.description === undefined ? "undefined" : `length=${input.description.length}`,
+        fix_hint: "Provide a one-line description like \"KYC attestation for user 0xabc\".",
+    };
+}
+function checkProofContent(input) {
+    const len = input.proof?.length ?? 0;
+    const passed = len > 0 && len <= MAX_PROOF_SIZE;
+    return {
+        id: "C-PROOF-02",
+        severity: passed ? "info" : "block",
+        title: `proof content within MAX_PROOF_SIZE (${MAX_PROOF_SIZE} bytes)`,
+        description: "The 'proof' string field must be non-empty and ≤ MAX_PROOF_SIZE bytes. Move aborts with E_MAX_PROOF_SIZE (1) on overflow. " +
+            "Typically holds a merkle root or compact digest — large data should go in a Repository.",
+        passed,
+        evidence: `length=${len}, limit=${MAX_PROOF_SIZE}`,
+        fix_hint: `Keep proof content compact. Current overflow: ${Math.max(0, len - MAX_PROOF_SIZE)} bytes.`,
+    };
+}
+function checkServerPubkey(input) {
+    const len = input.server_pubkey?.length ?? 0;
+    const passed = len > 0 && len <= MAX_SERVER_PUBKEY_SIZE;
+    return {
+        id: "C-PROOF-03",
+        severity: passed ? "info" : "block",
+        title: `server_pubkey within MAX_SERVER_PUBKEY_SIZE (${MAX_SERVER_PUBKEY_SIZE} bytes)`,
+        description: "server_pubkey must be non-empty and ≤ MAX_SERVER_PUBKEY_SIZE bytes. Move aborts with E_MAX_SERVER_PUBKEY_SIZE (2). " +
+            "Submit raw public key bytes (hex-encoded), not a certificate chain.",
+        passed,
+        evidence: `length=${len}, limit=${MAX_SERVER_PUBKEY_SIZE}`,
+        fix_hint: "Submit only the raw public key (Ed25519=32B, RSA-2048=256B, BLS12-381 G1=48B, G2=96B).",
+    };
+}
+function checkServerSignature(input) {
+    const len = input.server_signature?.length ?? 0;
+    const passed = len > 0 && len <= MAX_SERVER_SIGNATURE_SIZE;
+    return {
+        id: "C-PROOF-04",
+        severity: passed ? "info" : "block",
+        title: `server_signature within MAX_SERVER_SIGNATURE_SIZE (${MAX_SERVER_SIGNATURE_SIZE} bytes)`,
+        description: "server_signature must be non-empty and ≤ MAX_SERVER_SIGNATURE_SIZE bytes. Move aborts with E_MAX_SERVER_SIGNATURE_SIZE (3). " +
+            "Submit raw signature bytes, not bundled metadata.",
+        passed,
+        evidence: `length=${len}, limit=${MAX_SERVER_SIGNATURE_SIZE}`,
+        fix_hint: "Submit only the raw signature (Ed25519=64B, ECDSA=64-72B, BLS12-381=96B, RSA-2048=256B).",
+    };
+}
+function checkProofType(input) {
+    if (input.proof_type === undefined || input.proof_type === null) {
+        return {
+            id: "C-PROOF-05",
+            severity: "block",
+            title: "proof_type is provided",
+            description: `proof_type is a required u64. ${WOWOK_WTS_PROOF_TYPE}=WOWOK_WTS_PROOF_TYPE (WTS proof); 2-100 reserved for Wowok; >100 user-defined.`,
+            passed: false,
+            evidence: "undefined",
+            fix_hint: `Use ${WOWOK_WTS_PROOF_TYPE} for WTS proofs, or >100 for custom types.`,
+        };
+    }
+    const n = typeof input.proof_type === "string" ? BigInt(input.proof_type) : BigInt(input.proof_type);
+    const passed = n >= 1n;
+    const severity = passed
+        ? (n > 1n && n <= 100n ? "warn" : "info")
+        : "block";
+    return {
+        id: "C-PROOF-05",
+        severity,
+        title: `proof_type valid (${WOWOK_WTS_PROOF_TYPE}=WTS, 2-100 reserved, >100 user-defined)`,
+        description: `proof_type must be ≥ 1 (P-PROOF-P2-2). Value ${WOWOK_WTS_PROOF_TYPE}=WOWOK_WTS_PROOF_TYPE (WTS proof signed by off-chain server). ` +
+            `Values 2-100 are reserved for future Wowok-defined types — using them without authority creates semantic confusion.`,
+        passed,
+        evidence: `proof_type=${input.proof_type}`,
+        fix_hint: passed ? undefined : `Use ≥ 1. For custom types, use > 100.`,
+    };
+}
+function checkAboutAddress(input) {
+    const addr = input.about_address;
+    if (addr === null || addr === undefined || addr === "") {
+        return {
+            id: "C-PROOF-06",
+            severity: "info",
+            title: "about_address is null → free-standing Proof (no on-chain entity binding)",
+            description: "about_address=null is valid (PF-D-1=A, SDK sends Option::none). Use this for free-standing cryptographic statements. " +
+                "For entity-bound attestations, set about_address to the on-chain entity address (raw 0x-prefixed, not a name).",
+            passed: true,
+            evidence: "null/empty → Option::none",
+        };
+    }
+    const isValid = /^0x[0-9a-fA-F]{64}$/.test(addr);
+    return {
+        id: "C-PROOF-06",
+        severity: isValid ? "info" : "block",
+        title: "about_address is a valid raw 0x-prefixed address (or null)",
+        description: "When provided, about_address must be a raw address (NOT a name). SDK isValidAddress check enforces 0x-prefixed 64-hex format. " +
+            "Name resolution is NOT performed at the SDK layer for this field.",
+        passed: isValid,
+        evidence: `about_address=${addr.substring(0, 10)}...`,
+        fix_hint: "Use 0x-prefixed 64-hex address. Names are not accepted.",
+    };
+}
+function checkItemCount(input) {
+    if (input.item_count === undefined || input.item_count === null) {
+        return {
+            id: "C-PROOF-07",
+            severity: "info",
+            title: "item_count is optional (null → Option::none)",
+            description: "item_count is an optional u64. Use it to indicate the number of items in the off-chain data structure (e.g. merkle tree leaf count). " +
+                "When null, SDK sends Option::none to Move.",
+            passed: true,
+            evidence: "optional/none",
+        };
+    }
+    const n = typeof input.item_count === "string" ? BigInt(input.item_count) : BigInt(input.item_count);
+    const passed = n >= 0n;
+    return {
+        id: "C-PROOF-07",
+        severity: passed ? "info" : "block",
+        title: "item_count is a non-negative u64 (or null)",
+        description: "When provided, item_count must be ≥ 0. Used to indicate off-chain data structure size (e.g. merkle leaf count).",
+        passed,
+        evidence: `item_count=${input.item_count}`,
+    };
+}
+function checkNamedNew(input) {
+    const has = !!input.namedNew;
+    return {
+        id: "C-PROOF-08",
+        severity: has ? "info" : "warn",
+        title: "namedNew is provided (recommended for discoverability)",
+        description: "namedNew={name, tag?} is optional but recommended. Without it, the Proof is created without a local mark, " +
+            "making it harder to reference in subsequent operations. The 'name' should be descriptive (e.g. \"kyc_user_abc\").",
+        passed: has,
+        evidence: has ? `name=${input.namedNew.name}` : "not provided",
+        fix_hint: "Provide namedNew={name: \"descriptive_name\"} for easier subsequent reference.",
+    };
+}
+export function preCheckProofCreation(input) {
+    return [
+        checkDescription(input),
+        checkProofContent(input),
+        checkServerPubkey(input),
+        checkServerSignature(input),
+        checkProofType(input),
+        checkAboutAddress(input),
+        checkItemCount(input),
+        checkNamedNew(input),
+    ];
+}
+export function canCreateProof(input) {
+    const items = preCheckProofCreation(input);
+    return {
+        canCreate: items.every(i => i.severity !== "block" || i.passed),
+        blockers: items.filter(i => i.severity === "block" && !i.passed),
+        warnings: items.filter(i => i.severity === "warn" && !i.passed),
+        info: items.filter(i => i.severity === "info"),
+    };
+}
+export function formatProofCreationSummary(input) {
+    const { canCreate, blockers, warnings, info } = canCreateProof(input);
+    const lines = [];
+    lines.push(canCreate ? "✓ Proof creation pre-check PASSED" : "✗ Proof creation pre-check FAILED");
+    lines.push("");
+    if (blockers.length > 0) {
+        lines.push("BLOCKERS (must fix before creation):");
+        blockers.forEach(b => lines.push(`  [${b.id}] ${b.title} — ${b.evidence ?? ""}`));
+        lines.push("");
+    }
+    if (warnings.length > 0) {
+        lines.push("WARNINGS (review recommended):");
+        warnings.forEach(w => lines.push(`  [${w.id}] ${w.title} — ${w.evidence ?? ""}`));
+        lines.push("");
+    }
+    if (info.length > 0) {
+        lines.push("INFO:");
+        info.forEach(i => lines.push(`  [${i.id}] ${i.title}`));
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,33 @@
+export type ProofRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export type ProofRiskCategory = "structural" | "semantic" | "lifecycle" | "knowledge";
+export type ProofStakeholder = "creator" | "consumer" | "verifier" | "system";
+export interface ProofRisk {
+    id: string;
+    level: ProofRiskLevel;
+    category: ProofRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: ProofStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+    related_move_error?: string;
+    auto_fixable: boolean;
+}
+export interface ProofRiskCheckContext {
+    proof?: string;
+    server_pubkey?: string;
+    server_signature?: string;
+    proof_type?: number | bigint | string;
+    about_address?: string | null;
+    description?: string;
+    item_count?: number | bigint | string | null;
+    has_named_new?: boolean;
+    constants_synced?: boolean;
+}
+export declare const PROOF_RISK_RULES: {
+    rule: ProofRisk;
+    check: (ctx: ProofRiskCheckContext) => ProofRisk | null;
+}[];
+export declare function checkProofRisks(ctx: ProofRiskCheckContext): ProofRisk[];
+export declare function getProofRiskById(id: string): ProofRisk | undefined;