@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/proof-risk.js

@@ -0,0 +1,207 @@
+import { MAX_PROOF_SIZE, MAX_SERVER_PUBKEY_SIZE, MAX_SERVER_SIGNATURE_SIZE, WOWOK_WTS_PROOF_TYPE, } from "@wowok/wowok";
+const R_PR_1_01 = {
+    rule: {
+        id: "R-PROOF-01",
+        level: "HIGH",
+        category: "structural",
+        title: `proof content exceeds MAX_PROOF_SIZE (${MAX_PROOF_SIZE} bytes)`,
+        description: `The 'proof' string field is bounded by MAX_PROOF_SIZE=${MAX_PROOF_SIZE} bytes (Move source: proof.move:27). ` +
+            `Exceeding this limit aborts with E_MAX_PROOF_SIZE (1). The proof content typically holds a merkle tree root ` +
+            `or similar compact cryptographic digest — large data should be stored in a Repository and referenced by address, ` +
+            `not inlined into the Proof object.`,
+        affected_stakeholders: ["creator"],
+        scenario: "Caller submits a proof string longer than 10240 bytes",
+        mitigation: `Keep proof content compact (merkle root, hash digest). For larger payloads, store data in a Repository ` +
+            `object and set about_address to the Repository address, or use item_count to indicate the off-chain data size.`,
+        related_move_error: "E_MAX_PROOF_SIZE (1)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.proof)
+            return null;
+        if (ctx.proof.length <= MAX_PROOF_SIZE)
+            return null;
+        return { ...R_PR_1_01.rule, evidence: `proof.length=${ctx.proof.length}, limit=${MAX_PROOF_SIZE}` };
+    },
+};
+const R_PR_1_02 = {
+    rule: {
+        id: "R-PROOF-02",
+        level: "MEDIUM",
+        category: "structural",
+        title: `server_pubkey exceeds MAX_SERVER_PUBKEY_SIZE (${MAX_SERVER_PUBKEY_SIZE} bytes)`,
+        description: `The 'server_pubkey' field is bounded by MAX_SERVER_PUBKEY_SIZE=${MAX_SERVER_PUBKEY_SIZE} bytes (Move source: proof.move:28). ` +
+            `Exceeding this limit aborts with E_MAX_SERVER_PUBKEY_SIZE (2). Typical public keys (Ed25519=32 bytes, RSA-2048=256 bytes, ` +
+            `BLS12-381 G1=48 bytes, G2=96 bytes) fit comfortably within this limit.`,
+        affected_stakeholders: ["creator"],
+        scenario: "Caller submits an oversized server public key (e.g. certificate chain instead of raw key)",
+        mitigation: "Submit only the raw public key bytes (hex-encoded), not a full certificate or JWK structure.",
+        related_move_error: "E_MAX_SERVER_PUBKEY_SIZE (2)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.server_pubkey)
+            return null;
+        if (ctx.server_pubkey.length <= MAX_SERVER_PUBKEY_SIZE)
+            return null;
+        return { ...R_PR_1_02.rule, evidence: `server_pubkey.length=${ctx.server_pubkey.length}, limit=${MAX_SERVER_PUBKEY_SIZE}` };
+    },
+};
+const R_PR_1_03 = {
+    rule: {
+        id: "R-PROOF-03",
+        level: "MEDIUM",
+        category: "structural",
+        title: `server_signature exceeds MAX_SERVER_SIGNATURE_SIZE (${MAX_SERVER_SIGNATURE_SIZE} bytes)`,
+        description: `The 'server_signature' field is bounded by MAX_SERVER_SIGNATURE_SIZE=${MAX_SERVER_SIGNATURE_SIZE} bytes ` +
+            `(Move source: proof.move:29). Exceeding this limit aborts with E_MAX_SERVER_SIGNATURE_SIZE (3). ` +
+            `Most signature schemes produce signatures well under this limit (Ed25519=64 bytes, ECDSA=64-72 bytes, ` +
+            `BLS12-381=96 bytes, RSA-2048=256 bytes).`,
+        affected_stakeholders: ["creator"],
+        scenario: "Caller submits an oversized signature (e.g. bundled with metadata)",
+        mitigation: "Submit only the raw signature bytes (hex-encoded), not bundled metadata or certificate chains.",
+        related_move_error: "E_MAX_SERVER_SIGNATURE_SIZE (3)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.server_signature)
+            return null;
+        if (ctx.server_signature.length <= MAX_SERVER_SIGNATURE_SIZE)
+            return null;
+        return { ...R_PR_1_03.rule, evidence: `server_signature.length=${ctx.server_signature.length}, limit=${MAX_SERVER_SIGNATURE_SIZE}` };
+    },
+};
+const R_PR_2_01 = {
+    rule: {
+        id: "R-PROOF-04",
+        level: "MEDIUM",
+        category: "semantic",
+        title: `proof_type in reserved range without authority (1-100 reserved for Wowok)`,
+        description: `proof_type=${WOWOK_WTS_PROOF_TYPE} is WOWOK_WTS_PROOF_TYPE (Will-To-Sign). Values 2-100 are reserved for ` +
+            `future Wowok-defined proof types. User-defined proof types must use values > 100. While the Move contract ` +
+            `does not currently enforce this range at the type level (it accepts any u64), using a reserved value without ` +
+            `authority creates semantic confusion: consumers may misinterpret the proof's verification rules.`,
+        affected_stakeholders: ["creator", "consumer", "verifier"],
+        scenario: "User creates a custom proof with proof_type=5 (a reserved value)",
+        mitigation: "Use proof_type > 100 for user-defined proof types. Use proof_type=1 only for WTS proofs signed by an " +
+            "off-chain server (with server_pubkey + server_signature). Document the verification rule for custom types.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.proof_type === undefined || ctx.proof_type === null)
+            return null;
+        const n = typeof ctx.proof_type === "string" ? BigInt(ctx.proof_type) : BigInt(ctx.proof_type);
+        if (n === BigInt(WOWOK_WTS_PROOF_TYPE) || n > 100n)
+            return null;
+        return { ...R_PR_2_01.rule, evidence: `proof_type=${ctx.proof_type} (reserved range 2-100)` };
+    },
+};
+const R_PR_2_02 = {
+    rule: {
+        id: "R-PROOF-05",
+        level: "LOW",
+        category: "semantic",
+        title: "about_address not provided — consumers cannot locate the referenced entity",
+        description: "about_address is the on-chain address of the entity being proved (e.g. a user, an order, a Repository). " +
+            "When null/undefined, the Proof has no on-chain binding — it is a free-standing cryptographic statement. " +
+            "Consumers (Repository, Service, etc.) that reference this Proof cannot automatically resolve which entity " +
+            "it applies to. This is acceptable for generic proofs but problematic for entity-bound attestations.",
+        affected_stakeholders: ["creator", "consumer"],
+        scenario: "Caller creates a Proof without about_address, then a Repository tries to bind it to a data entry",
+        mitigation: "Set about_address when the Proof attests to a specific on-chain entity. Leave it null only for " +
+            "free-standing cryptographic statements (e.g. a server's timestamp attestation).",
+        auto_fixable: true,
+    },
+    check: (ctx) => {
+        if (ctx.about_address)
+            return null;
+        return { ...R_PR_2_02.rule, evidence: "about_address=null/undefined" };
+    },
+};
+const R_PR_3_01 = {
+    rule: {
+        id: "R-PROOF-06",
+        level: "LOW",
+        category: "lifecycle",
+        title: "description missing — Proof hard to identify in queries and audit logs",
+        description: "description is a REQUIRED field (PF-D-2=A). The Move contract stores it as a String field and SDK " +
+            "passes it to create_wowok_proof. An empty description (\"\") is technically valid but makes the Proof " +
+            "hard to identify in query results and audit logs. Non-empty descriptions are strongly recommended.",
+        affected_stakeholders: ["creator", "verifier"],
+        scenario: "Caller passes description=\"\" to save typing",
+        mitigation: "Provide a one-line description like \"KYC attestation for user 0xabc\" or \"merkle root for batch #42\".",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.description === undefined)
+            return null;
+        if (ctx.description.length > 0)
+            return null;
+        return { ...R_PR_3_01.rule, evidence: "description=\"\" (empty)" };
+    },
+};
+const R_PR_3_02 = {
+    rule: {
+        id: "R-PROOF-07",
+        level: "HIGH",
+        category: "lifecycle",
+        title: "Proof is immutable — cannot modify after creation (freeze_object)",
+        description: "Proof is created via transfer::freeze_object(obj) in Move (proof.move:65). Once frozen, the object " +
+            "cannot be modified, transferred, or deleted. All fields (proof, server_pubkey, server_signature, " +
+            "about, proof_type, signer, time, description, item_count) are permanently fixed at the value set " +
+            "during create_wowok_proof(). To 'update' a Proof, create a new one and update references.",
+        affected_stakeholders: ["creator", "consumer"],
+        scenario: "Caller wants to update server_signature after key rotation — cannot, must create new Proof",
+        mitigation: "Verify all fields before calling create_wowok_proof. For scenarios requiring key rotation, " +
+            "create a new Proof and update the referencing object (Repository data, Service config, etc.) to " +
+            "point to the new Proof address.",
+        auto_fixable: false,
+    },
+    check: (ctx) => null,
+};
+const R_PR_4_01 = {
+    rule: {
+        id: "R-PROOF-08",
+        level: "INFO",
+        category: "knowledge",
+        title: "Knowledge layer & constant sync — RESOLVED",
+        description: "All 4 Proof constants (WOWOK_WTS_PROOF_TYPE, MAX_PROOF_SIZE, MAX_SERVER_PUBKEY_SIZE, " +
+            "MAX_SERVER_SIGNATURE_SIZE) are now synced to onchain-constants.ts (P-PROOF-P2-5). The MCP Knowledge " +
+            "layer now includes proof-risk.ts, proof-confirm.ts, proof-translation.ts (P-PROOF-P2-6). " +
+            "This risk rule is retained for historical audit and to detect future regressions.",
+        affected_stakeholders: ["system"],
+        scenario: "Future regression: someone removes a Proof constant from onchain-constants.ts",
+        mitigation: "Run the onchain-constants sync test to detect drift.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.constants_synced)
+            return null;
+        return { ...R_PR_4_01.rule, evidence: "constants_synced=false" };
+    },
+};
+export const PROOF_RISK_RULES = [
+    R_PR_1_01,
+    R_PR_1_02,
+    R_PR_1_03,
+    R_PR_2_01,
+    R_PR_2_02,
+    R_PR_3_01,
+    R_PR_3_02,
+    R_PR_4_01,
+];
+export function checkProofRisks(ctx) {
+    const risks = [];
+    for (const rule of PROOF_RISK_RULES) {
+        const r = rule.check(ctx);
+        if (r)
+            risks.push(r);
+    }
+    if (!risks.find(r => r.id === "R-PROOF-07")) {
+        risks.push(R_PR_3_02.rule);
+    }
+    return risks;
+}
+export function getProofRiskById(id) {
+    return PROOF_RISK_RULES.find(r => r.rule.id === id)?.rule;
+}

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

@@ -0,0 +1,52 @@
+export interface SemanticToProofSchemaRule {
+    id: string;
+    pattern_name: string;
+    proof_type_classification: "wts" | "custom_reserved" | "custom_user";
+    semantic_intent: string;
+    match_keywords: string[];
+    schema_elements: {
+        proof_type_value: number | string;
+        required_fields: string[];
+        optional_fields: string[];
+        about_address_recommendation: string;
+    };
+    constraints: string[];
+    example: Record<string, unknown>;
+}
+export declare const SEMANTIC_TO_PROOF_SCHEMA_RULES: SemanticToProofSchemaRule[];
+export interface ProofFieldTranslation {
+    field_name: string;
+    move_field?: string;
+    value_type: string;
+    semantic: string;
+    format_example: string;
+    validation_rules: string[];
+}
+export declare const PROOF_FIELD_TRANSLATIONS: ProofFieldTranslation[];
+export interface ProofConstraintRule {
+    id: string;
+    name: string;
+    description: string;
+    validation_logic: string;
+    failure_message: string;
+    related_field: string;
+}
+export declare const PROOF_CONSTRAINT_RULES: ProofConstraintRule[];
+export interface ProofExplainInput {
+    proof_type?: number | bigint | string;
+    proof?: string;
+    server_pubkey?: string;
+    server_signature?: string;
+    about_address?: string | null;
+    description?: string;
+    item_count?: number | bigint | string | null;
+}
+export interface ProofExplanation {
+    summary: string;
+    proof_type_classification: string;
+    binding: string;
+    size_status: string;
+    warnings: string[];
+    recommendations: string[];
+}
+export declare function explainProof(input: ProofExplainInput): ProofExplanation;

package/dist/knowledge/proof-translation.js

@@ -0,0 +1,283 @@
+import { WOWOK_WTS_PROOF_TYPE } from "@wowok/wowok";
+export const SEMANTIC_TO_PROOF_SCHEMA_RULES = [
+    {
+        id: "P-PROOF-01",
+        pattern_name: "Wowok WTS (Will-To-Sign) proof",
+        proof_type_classification: "wts",
+        semantic_intent: "An off-chain server attests to a fact (identity, timestamp, merkle root) and signs it with server_pubkey. " +
+            "On-chain consumers verify the signature off-chain and trust the Proof record as evidence.",
+        match_keywords: ["wts", "server-signed", "attestation", "kyc", "merkle root", "timestamp"],
+        schema_elements: {
+            proof_type_value: WOWOK_WTS_PROOF_TYPE,
+            required_fields: ["proof", "server_pubkey", "server_signature", "description"],
+            optional_fields: ["item_count", "about_address", "namedNew"],
+            about_address_recommendation: "Set about_address when the WTS proof attests to a specific on-chain entity (user address, Repository, etc.). " +
+                "Leave null for free-standing attestations (e.g. server timestamp).",
+        },
+        constraints: [
+            `proof_type must equal ${WOWOK_WTS_PROOF_TYPE} (WOWOK_WTS_PROOF_TYPE)`,
+            "server_pubkey must be the raw public key (hex-encoded), not a certificate",
+            "server_signature must sign the exact bytes of the 'proof' field (or a documented pre-image)",
+            "Off-chain verification logic must be documented for consumers",
+        ],
+        example: {
+            proof_type: WOWOK_WTS_PROOF_TYPE,
+            proof: "0xabc123...merkle_root_hex...",
+            server_pubkey: "0x04a1b2c3...ed25519_or_ecdsa_pubkey_hex...",
+            server_signature: "0x9d8e7f6...signature_hex...",
+            description: "KYC attestation for user 0xabc (merkle root of 1024 leaves)",
+            item_count: 1024,
+            about_address: "0xabc...user_address...",
+            namedNew: { name: "kyc_user_abc" },
+        },
+    },
+    {
+        id: "P-PROOF-02",
+        pattern_name: "Custom proof in Wowok reserved range (NOT recommended)",
+        proof_type_classification: "custom_reserved",
+        semantic_intent: "A custom proof type using a value in the reserved range 2-100. This is NOT recommended because future " +
+            "Wowok protocol upgrades may claim these values, breaking semantic compatibility. Use only if you have " +
+            "explicit Wowok authority to claim a reserved value.",
+        match_keywords: ["reserved", "custom reserved", "wowok-defined"],
+        schema_elements: {
+            proof_type_value: "2-100 (specific value documented by creator)",
+            required_fields: ["proof", "server_pubkey", "server_signature", "description", "proof_type"],
+            optional_fields: ["item_count", "about_address", "namedNew"],
+            about_address_recommendation: "Same as P-PROOF-01: set about_address for entity-bound attestations.",
+        },
+        constraints: [
+            "Caller must have explicit Wowok authority to claim a reserved proof_type value",
+            "Verification logic must be documented and stable across protocol upgrades",
+            "Future Wowok upgrades may reassign this value — callers must handle migration",
+        ],
+        example: {
+            proof_type: 5,
+            proof: "0x...custom_proof_format...",
+            server_pubkey: "0x...pubkey...",
+            server_signature: "0x...sig...",
+            description: "Custom reserved proof type (documented by authority X)",
+        },
+    },
+    {
+        id: "P-PROOF-03",
+        pattern_name: "User-defined proof type (>100)",
+        proof_type_classification: "custom_user",
+        semantic_intent: "A fully custom proof type using a value > 100. The creator defines the verification logic (off-chain). " +
+            "This is the recommended range for application-specific proof semantics that Wowok protocol does not cover.",
+        match_keywords: ["custom", "user-defined", "application-specific", "custom proof type"],
+        schema_elements: {
+            proof_type_value: ">100 (user-chosen, must be unique within application scope)",
+            required_fields: ["proof", "server_pubkey", "server_signature", "description", "proof_type"],
+            optional_fields: ["item_count", "about_address", "namedNew"],
+            about_address_recommendation: "Set about_address when the proof is bound to a specific on-chain entity. Leave null for off-chain-only proofs.",
+        },
+        constraints: [
+            "proof_type must be > 100 (user-defined range)",
+            "Application must document the verification logic and proof format",
+            "Ensure proof_type does not collide with other user-defined types in the same consumer scope",
+        ],
+        example: {
+            proof_type: 200,
+            proof: "0x...application_specific_proof_format...",
+            server_pubkey: "0x...pubkey...",
+            server_signature: "0x...sig...",
+            description: "Application-specific attestation (format documented at https://...)",
+            about_address: null,
+            namedNew: { name: "custom_attestation_001" },
+        },
+    },
+];
+export const PROOF_FIELD_TRANSLATIONS = [
+    {
+        field_name: "proof",
+        value_type: "string (hex-encoded)",
+        semantic: "The cryptographic proof content. Typically a merkle tree root, a hash digest, or a compact serialized attestation. " +
+            "Off-chain verifiers use this together with server_pubkey and server_signature to verify the proof's authenticity.",
+        format_example: "0xabc123...merkle_root_64hex...",
+        validation_rules: [
+            "Non-empty string",
+            "Length ≤ MAX_PROOF_SIZE (10240 bytes)",
+            "Move aborts with E_MAX_PROOF_SIZE (1) on overflow",
+        ],
+    },
+    {
+        field_name: "server_pubkey",
+        value_type: "string (hex-encoded)",
+        semantic: "The public key of the off-chain server that signed this proof. Consumers use this to verify server_signature " +
+            "off-chain. Submit the raw public key bytes, not a certificate chain or JWK structure.",
+        format_example: "0x04a1b2c3...ed25519_pubkey_64hex...",
+        validation_rules: [
+            "Non-empty string",
+            "Length ≤ MAX_SERVER_PUBKEY_SIZE (2048 bytes)",
+            "Move aborts with E_MAX_SERVER_PUBKEY_SIZE (2) on overflow",
+            "Must be a valid public key for the signature scheme used",
+        ],
+    },
+    {
+        field_name: "server_signature",
+        value_type: "string (hex-encoded)",
+        semantic: "The signature produced by the off-chain server using its private key. Verifiers check this against " +
+            "server_pubkey and the proof content (or a documented pre-image).",
+        format_example: "0x9d8e7f6...signature_hex...",
+        validation_rules: [
+            "Non-empty string",
+            "Length ≤ MAX_SERVER_SIGNATURE_SIZE (40480 bytes)",
+            "Move aborts with E_MAX_SERVER_SIGNATURE_SIZE (3) on overflow",
+        ],
+    },
+    {
+        field_name: "proof_type",
+        value_type: "u64 (number | bigint | numeric string)",
+        semantic: `Classifies the proof's verification logic. ${WOWOK_WTS_PROOF_TYPE}=WOWOK_WTS_PROOF_TYPE (Wowok Will-To-Sign, ` +
+            `signed by off-chain server). Values 2-100 are reserved for future Wowok-defined types. Values >100 are user-defined.`,
+        format_example: `1 (WTS), 200 (custom)`,
+        validation_rules: [
+            "Required field",
+            "Must be ≥ 1 (P-PROOF-P2-2: schema rejects 0 and non-numeric strings)",
+            "Value 1 = WOWOK_WTS_PROOF_TYPE",
+            "Values 2-100 require explicit Wowok authority",
+            "Values >100 are user-defined",
+        ],
+    },
+    {
+        field_name: "about_address",
+        move_field: "about",
+        value_type: "Option<address> (string | null)",
+        semantic: "The on-chain address of the entity being proved (e.g. a user, order, Repository). When null, the Proof is a " +
+            "free-standing cryptographic statement with no on-chain binding. SDK sends Option::none to Move when null/undefined.",
+        format_example: "0xabc...64hex_address... or null",
+        validation_rules: [
+            "Optional (null/undefined → Option::none) [PF-D-1=A]",
+            "When provided, must be a raw 0x-prefixed 64-hex address (NOT a name)",
+            "SDK isValidAddress check enforces format",
+        ],
+    },
+    {
+        field_name: "description",
+        value_type: "string",
+        semantic: "Human-readable description of this Proof. Required field (PF-D-2=A). Helps identify the Proof in query results " +
+            "and audit logs. Should be a one-line summary (e.g. \"KYC attestation for user 0xabc\").",
+        format_example: "KYC attestation for user 0xabc (merkle root of 1024 leaves)",
+        validation_rules: [
+            "Required field [PF-D-2=A]",
+            "Length ≤ MAX_DESCRIPTION_LENGTH (defined in common.ts)",
+            "SDK isValidDescription check enforces max length",
+        ],
+    },
+    {
+        field_name: "item_count",
+        move_field: "item_count",
+        value_type: "Option<u64> (number | bigint | numeric string | null)",
+        semantic: "Optional count of items in the off-chain data structure (e.g. number of leaves in a merkle tree). " +
+            "Used by consumers to interpret the proof content. When null, SDK sends Option::none to Move.",
+        format_example: "1024 or null",
+        validation_rules: [
+            "Optional (null/undefined → Option::none)",
+            "When provided, must be ≥ 0",
+        ],
+    },
+];
+export const PROOF_CONSTRAINT_RULES = [
+    {
+        id: "PROOF_C_01",
+        name: "proof content non-empty",
+        description: "The 'proof' field must be a non-empty string.",
+        validation_logic: "proof.length > 0",
+        failure_message: "proof field is empty",
+        related_field: "proof",
+    },
+    {
+        id: "PROOF_C_02",
+        name: "proof content within size limit",
+        description: `The 'proof' field must be ≤ MAX_PROOF_SIZE (10240 bytes).`,
+        validation_logic: "proof.length <= MAX_PROOF_SIZE",
+        failure_message: "proof exceeds MAX_PROOF_SIZE (10240 bytes) — E_MAX_PROOF_SIZE (1)",
+        related_field: "proof",
+    },
+    {
+        id: "PROOF_C_03",
+        name: "server_pubkey within size limit",
+        description: "The 'server_pubkey' field must be ≤ MAX_SERVER_PUBKEY_SIZE (2048 bytes).",
+        validation_logic: "server_pubkey.length <= MAX_SERVER_PUBKEY_SIZE",
+        failure_message: "server_pubkey exceeds MAX_SERVER_PUBKEY_SIZE (2048 bytes) — E_MAX_SERVER_PUBKEY_SIZE (2)",
+        related_field: "server_pubkey",
+    },
+    {
+        id: "PROOF_C_04",
+        name: "server_signature within size limit",
+        description: "The 'server_signature' field must be ≤ MAX_SERVER_SIGNATURE_SIZE (40480 bytes).",
+        validation_logic: "server_signature.length <= MAX_SERVER_SIGNATURE_SIZE",
+        failure_message: "server_signature exceeds MAX_SERVER_SIGNATURE_SIZE (40480 bytes) — E_MAX_SERVER_SIGNATURE_SIZE (3)",
+        related_field: "server_signature",
+    },
+    {
+        id: "PROOF_C_05",
+        name: "proof_type valid range",
+        description: `proof_type must be ≥ 1 (WOWOK_WTS_PROOF_TYPE=${WOWOK_WTS_PROOF_TYPE} is the minimum).`,
+        validation_logic: "proof_type >= 1",
+        failure_message: "proof_type must be ≥ 1 — schema rejects 0 and non-numeric strings",
+        related_field: "proof_type",
+    },
+    {
+        id: "PROOF_C_06",
+        name: "about_address format (when provided)",
+        description: "When about_address is non-null, it must be a valid 0x-prefixed 64-hex address.",
+        validation_logic: "about_address == null || /^0x[0-9a-fA-F]{64}$/.test(about_address)",
+        failure_message: "about_address is not a valid 0x-prefixed 64-hex address",
+        related_field: "about_address",
+    },
+];
+export function explainProof(input) {
+    const warnings = [];
+    const recommendations = [];
+    let classification = "unknown";
+    if (input.proof_type !== undefined && input.proof_type !== null) {
+        const n = typeof input.proof_type === "string" ? BigInt(input.proof_type) : BigInt(input.proof_type);
+        if (n === BigInt(WOWOK_WTS_PROOF_TYPE)) {
+            classification = `WTS proof (proof_type=${WOWOK_WTS_PROOF_TYPE}) — signed by off-chain server`;
+        }
+        else if (n > 1n && n <= 100n) {
+            classification = `Custom proof in reserved range (proof_type=${input.proof_type}) — NOT recommended without Wowok authority`;
+            warnings.push(`proof_type=${input.proof_type} is in reserved range 2-100 — future Wowok upgrades may reassign this value`);
+        }
+        else if (n > 100n) {
+            classification = `User-defined proof (proof_type=${input.proof_type}) — application-specific verification logic`;
+        }
+        else {
+            classification = `INVALID proof_type=${input.proof_type} (must be ≥ 1)`;
+            warnings.push("proof_type is < 1 — schema validation will reject");
+        }
+    }
+    const binding = input.about_address
+        ? `Entity-bound: about_address=${input.about_address.substring(0, 10)}... (proof attests to this on-chain entity)`
+        : "Free-standing: no on-chain entity binding (about_address=null)";
+    const sizeStatus = [];
+    if (input.proof) {
+        sizeStatus.push(`proof=${input.proof.length} bytes (limit 10240)`);
+    }
+    if (input.server_pubkey) {
+        sizeStatus.push(`server_pubkey=${input.server_pubkey.length} bytes (limit 2048)`);
+    }
+    if (input.server_signature) {
+        sizeStatus.push(`server_signature=${input.server_signature.length} bytes (limit 40480)`);
+    }
+    if (!input.description || input.description.length === 0) {
+        recommendations.push("Provide a non-empty description for audit log discoverability");
+    }
+    if (!input.about_address) {
+        recommendations.push("Consider setting about_address if this Proof attests to a specific on-chain entity");
+    }
+    if (input.item_count === undefined || input.item_count === null) {
+        recommendations.push("Consider setting item_count if the proof references a multi-item data structure");
+    }
+    const summary = `Proof is a ${classification}. ${binding}. ` +
+        (sizeStatus.length > 0 ? `Sizes: ${sizeStatus.join(", ")}.` : "");
+    return {
+        summary,
+        proof_type_classification: classification,
+        binding,
+        size_status: sizeStatus.join(", "),
+        warnings,
+        recommendations,
+    };
+}

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

@@ -0,0 +1,34 @@
+export type RegistrarRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export type RegistrarRiskCategory = "structural" | "semantic" | "lifecycle" | "cross_object" | "knowledge";
+export type RegistrarStakeholder = "user" | "referrer" | "voter" | "system";
+export interface RegistrarRisk {
+    id: string;
+    level: RegistrarRiskLevel;
+    category: RegistrarRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: RegistrarStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+    related_move_error?: string;
+    auto_fixable: boolean;
+}
+export interface RegistrarRiskCheckContext {
+    expects_singleton_migration?: boolean;
+    address_count?: number;
+    uses_reserved_vote_bits?: boolean;
+    expects_fresh_resource_on_register?: boolean;
+    expects_affiliation_event?: boolean;
+    relies_on_typed_value_convention?: boolean;
+    is_resource_transfer?: boolean;
+    expects_vote_time_only_on_like?: boolean;
+    constants_synced?: boolean;
+}
+export declare const REGISTRAR_RISK_RULES: {
+    rule: RegistrarRisk;
+    check: (ctx: RegistrarRiskCheckContext) => RegistrarRisk | null;
+}[];
+export declare const REGISTRAR_RISK_VERSION = "1.0.0";
+export declare function checkRegistrarRisks(ctx: RegistrarRiskCheckContext): RegistrarRisk[];
+export declare function getRegistrarRiskById(id: string): RegistrarRisk | undefined;