@wowok/agent-mcp 2.3.16 → 2.4.1

package/dist/knowledge/guard-puzzle.js

@@ -0,0 +1,804 @@
+export function checkPuzzleCompleteness(puzzle) {
+    const dimensions = {
+        intent: isIntentComplete(puzzle.intent),
+        binding: isBindingComplete(puzzle.binding),
+        data_sources: isDataSourcesComplete(puzzle.data_sources),
+        query: isQueryComplete(puzzle.queries),
+        logic: isLogicComplete(puzzle.logic),
+        constraints: isConstraintsComplete(puzzle.constraints),
+    };
+    const missing = Object.keys(dimensions).filter((k) => !dimensions[k]);
+    const missing_details = [];
+    if (!dimensions.intent) {
+        missing_details.push("A. Intent: protected action, validation rule, or failure conditions not clarified");
+    }
+    if (!dimensions.binding) {
+        missing_details.push("B. Binding: Host Object, binding field, or circular reference mode not determined");
+    }
+    if (!dimensions.data_sources) {
+        missing_details.push("C. Data sources: data sources not declared by 4 classifications (on-chain constant / witness-derived / submitted object / system context)");
+    }
+    if (!dimensions.query) {
+        missing_details.push("D. Query: query instruction not determined (if the Guard needs to query on-chain data)");
+    }
+    if (!dimensions.logic) {
+        missing_details.push("E. Logic: computation tree root or rely composition not designed");
+    }
+    if (!dimensions.constraints) {
+        missing_details.push("F. Constraints: creation-time 10 + runtime 6 constraint checks not completed");
+    }
+    const complete = missing.length === 0;
+    const next_step = recommendNextStep(puzzle, missing);
+    return { dimensions, missing, missing_details, complete, next_step };
+}
+function isIntentComplete(intent) {
+    return !!intent && !!intent.action && !!intent.rule_sentence && intent.failure_conditions.length > 0;
+}
+function isBindingComplete(binding) {
+    return !!binding && !!binding.host_object && !!binding.binding_field;
+}
+function isDataSourcesComplete(data_sources) {
+    if (!data_sources)
+        return false;
+    const hasType1 = data_sources.on_chain_constants.length > 0;
+    const hasType2 = data_sources.witness_derived.length > 0;
+    const hasType3Obj = data_sources.submitted_objects.length > 0;
+    const hasType3Val = data_sources.submitted_values.length > 0;
+    const hasType4 = data_sources.system_contexts.length > 0;
+    if (!hasType1 && !hasType2 && !hasType3Obj && !hasType3Val && !hasType4) {
+        return false;
+    }
+    const unboundedSubmission = data_sources.submitted_objects.some((e) => !e.binding_constraint);
+    if (unboundedSubmission)
+        return false;
+    return true;
+}
+function isQueryComplete(queries) {
+    return true;
+}
+function isLogicComplete(logic) {
+    return !!logic && !!logic.root && logic.root.return_type === "Bool";
+}
+function isConstraintsComplete(constraints) {
+    if (!constraints)
+        return false;
+    return Object.values(constraints).every((v) => v === true);
+}
+function recommendNextStep(puzzle, missing) {
+    if (missing.includes("intent")) {
+        return {
+            round: "R1",
+            action: "Capture validation intent",
+            questions: [
+                "What action do you want to protect? (buy/forward/claim/vote/dispute/write/allocate)",
+                "Describe the validation rule in one sentence",
+                "List the conditions under which the Guard should FAIL",
+            ],
+        };
+    }
+    if (missing.includes("binding")) {
+        return {
+            round: "R5",
+            action: "Determine binding target",
+            questions: [
+                "Which Host Object will the Guard bind to? (Service/Machine/Arbitration/Reward/Repository)",
+                "Which field will it bind to? (buy_guard/order_allocators/Forward.guard/...)",
+                "Does the Guard need to reference the Host Object? (circular reference mode)",
+            ],
+        };
+    }
+    if (missing.includes("data_sources")) {
+        return {
+            round: "R2",
+            action: "Declare data sources by 4 classifications",
+            questions: [
+                "Type1 (on-chain constant): Which already-published on-chain objects does the Guard need to query? (Service/Machine/Reward addresses)",
+                "Type2 (witness-derived): Do you need to derive Progress/Machine/Service from Order/Arb? (choose witness 100-108)",
+                "Type3 (submitted object): Which object addresses does the caller need to submit? (Order/Reward/Progress) — constraint rules must be designed",
+                "Type3 (submitted value): Which scalar values does the caller need to submit? (amount/weight/node name)",
+                "Type4 (system context): Do you need Signer (identity) / Clock (time) / Guard (self-reference)?",
+                "Do you need to query EntityRegistrar(0xaab) or EntityLinker(0xaaa)?",
+            ],
+        };
+    }
+    if (missing.includes("query")) {
+        return {
+            round: "R3",
+            action: "Design query nodes",
+            questions: [
+                "Which on-chain objects does the Guard need to query?",
+                "Which instruction ID does each query use? (look up from GUARDQUERY)",
+                "Do you need convert_witness to convert objects? (linked to Type2 declaration)",
+            ],
+        };
+    }
+    if (missing.includes("logic")) {
+        return {
+            round: "R3",
+            action: "Design computation tree",
+            questions: [
+                "What is the root node? (must return Bool)",
+                "Which data source nodes are there? (by 4 classifications: identifier/context/query)",
+                "Which intermediate conversion nodes are there? (calc_*/convert_*/vec_*)",
+                "Do you need rely to compose with other Guards?",
+            ],
+        };
+    }
+    if (missing.includes("constraints")) {
+        return {
+            round: "R6",
+            action: "Pre-creation review",
+            questions: ["Run the creation-time 10 + runtime 6 constraint checklist"],
+        };
+    }
+    return {
+        round: "R7",
+        action: "Prepare for on-chain creation",
+        questions: ["All dimensions are complete; ready to generate the semantic confirmation text"],
+    };
+}
+export function generateConfirmationText(puzzle) {
+    if (!puzzle.intent || !puzzle.binding || !puzzle.data_sources || !puzzle.logic) {
+        return "[Puzzle incomplete] Cannot generate confirmation text; please complete all dimensions first";
+    }
+    const lines = [];
+    lines.push("═══════════════════════════════════════════════════════");
+    lines.push("  Guard Semantic Confirmation Report (User Review Edition)");
+    lines.push("═══════════════════════════════════════════════════════");
+    lines.push("");
+    lines.push("[Intent]");
+    lines.push(`Protected action: ${puzzle.intent.action}`);
+    lines.push(`Validation rule: ${puzzle.intent.rule_sentence}`);
+    lines.push("Failure conditions:");
+    puzzle.intent.failure_conditions.forEach((c, i) => {
+        lines.push(`  ${i + 1}. ${c}`);
+    });
+    lines.push("");
+    lines.push("[Binding]");
+    lines.push(`Host Object: ${puzzle.binding.host_object}`);
+    if (puzzle.binding.host_object_name) {
+        lines.push(`Host Object name: ${puzzle.binding.host_object_name}`);
+    }
+    lines.push(`Binding field: ${puzzle.binding.binding_field}`);
+    lines.push(`Circular reference: ${puzzle.binding.circular_reference ? "Yes (Guard references Host Object)" : "No"}`);
+    lines.push(`Host Object state: ${puzzle.binding.host_object_state}`);
+    lines.push("");
+    lines.push("[Data sources (4 classifications)]");
+    printDataSources(lines, puzzle.data_sources);
+    lines.push("");
+    if (puzzle.queries && puzzle.queries.length > 0) {
+        lines.push("[Query instructions]");
+        lines.push("┌──────┬──────────────────────────┬────────────┬──────────┬──────────┐");
+        lines.push("│ ID   │ Query instruction        │ Target obj │ Params   │ Return   │");
+        lines.push("├──────┼──────────────────────────┼────────────┼──────────┼──────────┤");
+        puzzle.queries.forEach((q) => {
+            const id = String(q.query_id).padEnd(4);
+            const name = q.query_name.length > 24 ? q.query_name.slice(0, 23) + "…" : q.query_name.padEnd(24);
+            const obj = q.object_type.padEnd(10);
+            const params = (q.parameters.length === 0 ? "(none)" : q.parameters.join(",")).padEnd(8);
+            const ret = q.return_type.padEnd(8);
+            lines.push(`│ ${id} │ ${name} │ ${obj} │ ${params} │ ${ret} │`);
+        });
+        lines.push("└──────┴──────────────────────────┴────────────┴──────────┴──────────┘");
+        lines.push("");
+    }
+    lines.push("[Computation tree]");
+    lines.push(`root: ${puzzle.logic.root.node_type} (returns: ${puzzle.logic.root.return_type})`);
+    lines.push(`  ${puzzle.logic.root.description}`);
+    if (puzzle.logic.root.children) {
+        printLogicTree(lines, puzzle.logic.root.children, 1);
+    }
+    lines.push("");
+    if (puzzle.logic.rely) {
+        lines.push("[rely composition]");
+        lines.push(`Dependent Guards: ${puzzle.logic.rely.guards.join(", ")}`);
+        lines.push(`Logic: ${puzzle.logic.rely.logic_or ? "OR (any passes)" : "AND (all must pass)"}`);
+        lines.push(`rep verification: ${puzzle.logic.rely.rep_verified.every((v) => v) ? "all passed" : "some unverified"}`);
+        lines.push("");
+    }
+    if (puzzle.constraints) {
+        lines.push("[Constraint checklist (creation-time 22 + runtime 11 = 33; MCP layer static check 16)]");
+        const creationChecks = [
+            ["01", "All identifiers exist in the table", puzzle.constraints.pitfall_01_identifiers_in_table],
+            ["02", "Comparison node types are compatible", puzzle.constraints.pitfall_02_type_compatibility],
+            ["03", "Query instruction ID and parameter count are correct", puzzle.constraints.pitfall_03_query_instruction_valid],
+            ["04", "convert_witness type is correct", puzzle.constraints.pitfall_04_witness_correct],
+            ["05", "Time-lock tests use small values", puzzle.constraints.pitfall_05_time_lock_test_safe],
+            ["06", "Old Guard exported before iteration", puzzle.constraints.pitfall_06_exported_before_recreate],
+            ["07", "root returns Bool", puzzle.constraints.pitfall_07_root_returns_bool],
+            ["08", "rely dependency rep=true", puzzle.constraints.pitfall_08_rely_rep_true],
+            ["09", "voting_guard GuardIdentifier numeric", puzzle.constraints.pitfall_09_voting_weight_numeric],
+            ["10", "Arbitration not paused", puzzle.constraints.pitfall_10_arbitration_not_paused],
+        ];
+        const runtimeChecks = [
+            ["R1", "Guard immutable=true to verify", puzzle.constraints.runtime_01_guard_immutable],
+            ["R2", "submission type bytes match table declaration", puzzle.constraints.runtime_02_submission_type_match],
+            ["R3", "b_submission=true entry found in submission", puzzle.constraints.runtime_03_submission_complete],
+            ["R4", "submission total bytes ≤ 256", puzzle.constraints.runtime_04_submission_size],
+            ["R5", "witness derivation source object has related field", puzzle.constraints.runtime_05_witness_source_valid],
+            ["R6", "query target object exists and types match", puzzle.constraints.runtime_06_query_object_valid],
+        ];
+        lines.push("  Creation-time constraints:");
+        creationChecks.forEach(([num, desc, pass]) => {
+            lines.push(`  ${pass ? "✓" : "✗"} [${num}] ${desc}`);
+        });
+        lines.push("  Runtime constraints:");
+        runtimeChecks.forEach(([num, desc, pass]) => {
+            lines.push(`  ${pass ? "✓" : "✗"} [${num}] ${desc}`);
+        });
+        lines.push("");
+    }
+    lines.push("[Risk warnings]");
+    lines.push("  ⚠ Guard cannot be modified or deleted after creation (CREATE-only)");
+    lines.push("  ⚠ On-chain execution will consume gas");
+    lines.push("  ⚠ To modify after creation: export → edit → create new → rebind");
+    lines.push("");
+    lines.push("[Test plan (gen_passport static test)]");
+    lines.push("  Expected pass scenario: submit data meeting conditions → PASS → Passport generated");
+    lines.push("  Expected fail scenario: submit data not meeting conditions → FAIL → verify logic direction");
+    lines.push("");
+    lines.push("[Post-creation actions (important)]");
+    lines.push("  1. Use guard2file to export the Guard backup (JSON file) for later rebuild or migration");
+    lines.push("  2. Record the Guard object ID for subsequent binding and invocation");
+    lines.push("  3. If the Guard binds to a Host Object, ensure the Host Object is published after Guard creation");
+    lines.push("  4. Verify the Guard logic direction via gen_passport static test");
+    lines.push("");
+    const allCreationPass = creationChecksForReadiness(puzzle);
+    lines.push("[Creation readiness signal]");
+    lines.push(`  Puzzle completeness: ${allCreationPass ? "✓ All passed — ready for on-chain CREATE" : "✗ Some items not passed — please fix first"}`);
+    lines.push("");
+    lines.push("═══════════════════════════════════════════════════════");
+    lines.push("  Please review the Guard semantic confirmation report above");
+    lines.push("  After confirming no issues, reply \"confirm creation\" to execute on-chain CREATE");
+    lines.push("  If modifications are needed, please point out the parts to adjust");
+    lines.push("═══════════════════════════════════════════════════════");
+    return lines.join("\n");
+}
+function creationChecksForReadiness(puzzle) {
+    if (!puzzle.intent || !puzzle.binding || !puzzle.data_sources || !puzzle.logic || !puzzle.constraints) {
+        return false;
+    }
+    const c = puzzle.constraints;
+    const creationPass = c.pitfall_01_identifiers_in_table &&
+        c.pitfall_02_type_compatibility &&
+        c.pitfall_03_query_instruction_valid &&
+        c.pitfall_04_witness_correct &&
+        c.pitfall_05_time_lock_test_safe &&
+        c.pitfall_06_exported_before_recreate &&
+        c.pitfall_07_root_returns_bool &&
+        c.pitfall_08_rely_rep_true &&
+        c.pitfall_09_voting_weight_numeric &&
+        c.pitfall_10_arbitration_not_paused;
+    const runtimePass = c.runtime_01_guard_immutable &&
+        c.runtime_02_submission_type_match &&
+        c.runtime_03_submission_complete &&
+        c.runtime_04_submission_size &&
+        c.runtime_05_witness_source_valid &&
+        c.runtime_06_query_object_valid;
+    return creationPass && runtimePass;
+}
+function printDataSources(lines, ds) {
+    if (ds.on_chain_constants.length > 0) {
+        lines.push("  Type1 — On-chain constant objects (OnChainConstant, b_submission=false):");
+        ds.on_chain_constants.forEach((e) => {
+            const sysMark = e.is_system_address ? " [system address]" : "";
+            lines.push(`    [id=${e.identifier}] ${e.object_type}(${e.object_address})${sysMark} — ${e.name}`);
+        });
+    }
+    if (ds.witness_derived.length > 0) {
+        lines.push("  Type2 — Witness-derived objects (WitnessDerived, convert_witness 100-108):");
+        ds.witness_derived.forEach((e) => {
+            const srcKind = e.source_b_submission ? "submitted" : "constant";
+            lines.push(`    [id=${e.identifier}] ${e.source_type}(${srcKind}) → ${e.target_type} via ${e.witness_name}(${e.witness_type}) — ${e.name}`);
+        });
+    }
+    if (ds.submitted_objects.length > 0) {
+        lines.push("  Type3 — Submitted objects (SubmittedObject, b_submission=true):");
+        ds.submitted_objects.forEach((e) => {
+            lines.push(`    [id=${e.identifier}] ${e.expected_object_type}(${e.value_type}) — ${e.name}`);
+            if (e.binding_constraint) {
+                lines.push(`      Constraint: ${e.binding_constraint}`);
+            }
+        });
+    }
+    if (ds.submitted_values.length > 0) {
+        lines.push("  Type3 — Submitted values (SubmittedValue, b_submission=true, scalar):");
+        ds.submitted_values.forEach((e) => {
+            lines.push(`    [id=${e.identifier}] ${e.value_type} — ${e.name}`);
+            if (e.binding_constraint) {
+                lines.push(`      Constraint: ${e.binding_constraint}`);
+            }
+        });
+    }
+    if (ds.system_contexts.length > 0) {
+        lines.push("  Type4 — System contexts (SystemContext, not in table):");
+        ds.system_contexts.forEach((e) => {
+            lines.push(`    context(${e.context_type}) — ${e.usage}`);
+        });
+    }
+    if (ds.on_chain_constants.length === 0 &&
+        ds.witness_derived.length === 0 &&
+        ds.submitted_objects.length === 0 &&
+        ds.submitted_values.length === 0 &&
+        ds.system_contexts.length === 0) {
+        lines.push("  (No data sources declared)");
+    }
+}
+function printLogicTree(lines, nodes, depth) {
+    const indent = "  ".repeat(depth + 1);
+    nodes.forEach((node, i) => {
+        const prefix = i === nodes.length - 1 ? "└── " : "├── ";
+        lines.push(`${indent}${prefix}${node.node_type} (${node.return_type}) — ${node.description}`);
+        if (node.references_identifier !== undefined) {
+            lines.push(`${indent}    → table[${node.references_identifier}]`);
+        }
+        if (node.query) {
+            lines.push(`${indent}    → query(${node.query.query_id}: ${node.query.query_name})`);
+        }
+        if (node.children) {
+            printLogicTree(lines, node.children, depth + 1);
+        }
+    });
+}
+export function initPuzzleFromIntent(intent) {
+    return {
+        current_round: "R1",
+        intent: {
+            action: intent.action ?? "custom",
+            rule_sentence: intent.rule_sentence ?? "",
+            failure_conditions: intent.failure_conditions ?? [],
+        },
+    };
+}
+export function inferBindingFromAction(action) {
+    const map = {
+        buy: { host_object: "Service", binding_field: "buy_guard" },
+        forward: { host_object: "Machine", binding_field: "Forward.guard" },
+        allocate: { host_object: "Service", binding_field: "order_allocators" },
+        claim_reward: { host_object: "Reward", binding_field: "guard" },
+        vote: { host_object: "Arbitration", binding_field: "voting_guard" },
+        dispute: { host_object: "Arbitration", binding_field: "usage_guard" },
+        write_repository: { host_object: "Repository", binding_field: "write_guard" },
+        submit_progress: { host_object: "Progress", binding_field: "submission" },
+        gen_passport: { host_object: "Standalone", binding_field: "none" },
+        custom: {},
+    };
+    return map[action] ?? {};
+}
+export function emptyDataSources() {
+    return {
+        on_chain_constants: [],
+        witness_derived: [],
+        submitted_objects: [],
+        submitted_values: [],
+        system_contexts: [],
+    };
+}
+export const WITNESS_NAME_MAP = {
+    100: { name: "TypeOrderProgress", source: "Order", target: "Progress" },
+    101: { name: "TypeOrderMachine", source: "Order", target: "Machine" },
+    102: { name: "TypeOrderService", source: "Order", target: "Service" },
+    103: { name: "TypeProgressMachine", source: "Progress", target: "Machine" },
+    104: { name: "TypeArbOrder", source: "Arb", target: "Order" },
+    105: { name: "TypeArbArbitration", source: "Arb", target: "Arbitration" },
+    106: { name: "TypeArbProgress", source: "Arb", target: "Progress" },
+    107: { name: "TypeArbMachine", source: "Arb", target: "Machine" },
+    108: { name: "TypeArbService", source: "Arb", target: "Service" },
+};
+export function getWitnessInfo(witness_type) {
+    return WITNESS_NAME_MAP[witness_type];
+}
+function traverseRoot(node, collectors) {
+    if (!node)
+        return;
+    if (node.type === "identifier" && typeof node.identifier === "number") {
+        collectors.referencedIdentifiers.add(node.identifier);
+    }
+    if (node.type === "context" && node.context) {
+        collectors.contexts.add(node.context);
+    }
+    if (node.type === "query" && node.object) {
+        const objId = node.object.identifier;
+        collectors.referencedIdentifiers.add(objId);
+        const witnessCode = node.object.convert_witness;
+        if (typeof witnessCode === "number" && witnessCode >= 100 && witnessCode <= 108) {
+            collectors.witnessCodes.push({ code: witnessCode, objectIdentifier: objId });
+        }
+        collectors.queries.push({
+            query: node.query ?? "",
+            objectIdentifier: objId,
+            convertWitness: witnessCode,
+            parametersCount: node.parameters?.length ?? 0,
+        });
+        if (node.parameters) {
+            for (const param of node.parameters) {
+                traverseRoot(param, collectors);
+            }
+        }
+    }
+    if (node.nodes) {
+        for (const child of node.nodes) {
+            traverseRoot(child, collectors);
+        }
+    }
+    if (node.node) {
+        traverseRoot(node.node, collectors);
+    }
+    if (node.nodeLeft) {
+        traverseRoot(node.nodeLeft, collectors);
+    }
+    if (node.nodeRight) {
+        traverseRoot(node.nodeRight, collectors);
+    }
+}
+function buildLogicTree(node) {
+    if (!node)
+        return undefined;
+    const logicNode = {
+        node_type: node.type,
+        return_type: inferNodeType(node.type),
+        description: describeNode(node),
+    };
+    if (node.type === "identifier" && typeof node.identifier === "number") {
+        logicNode.references_identifier = node.identifier;
+    }
+    if (node.type === "query" && node.object) {
+        logicNode.query = {
+            query_id: typeof node.query === "number" ? node.query : 0,
+            query_name: typeof node.query === "string" ? node.query : String(node.query ?? ""),
+            object_type: "",
+            parameters: [],
+            return_type: "",
+            purpose: "",
+        };
+        if (node.object.convert_witness) {
+            const wInfo = getWitnessInfo(node.object.convert_witness);
+            if (wInfo) {
+                logicNode.query.witness = {
+                    witness_type: node.object.convert_witness,
+                    witness_name: wInfo.name,
+                    source_type: wInfo.source,
+                    target_type: wInfo.target,
+                    scenario: "",
+                };
+            }
+        }
+    }
+    if (node.nodes) {
+        const children = node.nodes
+            .map((c) => buildLogicTree(c))
+            .filter((c) => c !== undefined);
+        if (children.length > 0) {
+            logicNode.children = children;
+        }
+    }
+    if (node.node) {
+        const child = buildLogicTree(node.node);
+        if (child) {
+            logicNode.children = [child];
+        }
+    }
+    if (node.nodeLeft) {
+        const child = buildLogicTree(node.nodeLeft);
+        if (child) {
+            logicNode.children = [...(logicNode.children ?? []), child];
+        }
+    }
+    if (node.nodeRight) {
+        const child = buildLogicTree(node.nodeRight);
+        if (child) {
+            logicNode.children = [...(logicNode.children ?? []), child];
+        }
+    }
+    return logicNode;
+}
+function inferNodeType(nodeType) {
+    const boolTypes = [
+        "logic_equal", "logic_not", "logic_and", "logic_or",
+        "logic_as_u256_greater", "logic_as_u256_lesser", "logic_as_u256_equal",
+        "logic_as_u256_greater_or_equal", "logic_as_u256_lesser_or_equal",
+        "logic_string_contains", "logic_string_nocase_contains", "logic_string_nocase_equal",
+        "calc_string_contains", "calc_string_nocase_contains", "calc_string_nocase_equal",
+        "vec_contains_bool", "vec_contains_address", "vec_contains_string",
+        "vec_contains_string_nocase", "vec_contains_number",
+        "query_reward_record_exists",
+    ];
+    if (boolTypes.includes(nodeType))
+        return "Bool";
+    const u256Types = [
+        "calc_number_add", "calc_number_subtract", "calc_number_multiply",
+        "calc_number_divide", "calc_number_mod",
+        "convert_address_number", "convert_string_number",
+    ];
+    if (u256Types.includes(nodeType))
+        return "U256";
+    const u64Types = [
+        "calc_string_length", "calc_string_indexof", "calc_string_nocase_indexof",
+        "vec_length", "vec_indexof_bool", "vec_indexof_address", "vec_indexof_string",
+        "vec_indexof_string_nocase", "vec_indexof_number",
+        "query_reward_record_count",
+        "query_progress_history_session_count",
+        "query_progress_history_session_forward_count",
+        "query_progress_history_session_forward_retained_submission_count",
+    ];
+    if (u64Types.includes(nodeType))
+        return "U64";
+    const addressTypes = ["convert_number_address"];
+    if (addressTypes.includes(nodeType))
+        return "Address";
+    const stringTypes = ["convert_number_string"];
+    if (stringTypes.includes(nodeType))
+        return "String";
+    const safeTypes = ["convert_safe_u8", "convert_safe_u16", "convert_safe_u32", "convert_safe_u64", "convert_safe_u128", "convert_safe_u256"];
+    if (safeTypes.includes(nodeType)) {
+        return nodeType.replace("convert_safe_", "U");
+    }
+    if (nodeType === "value_type")
+        return "U8";
+    if (nodeType === "query")
+        return "query_defined";
+    if (nodeType === "identifier")
+        return "table_defined";
+    if (nodeType === "context")
+        return "context_defined";
+    return "unknown";
+}
+function describeNode(node) {
+    switch (node.type) {
+        case "identifier":
+            return `Reference to table[${node.identifier ?? "?"}]`;
+        case "context":
+            return `System context: ${node.context ?? "?"}`;
+        case "query":
+            return `Query instruction ${node.query ?? "?"} (target: table[${node.object?.identifier ?? "?"}])`;
+        case "logic_equal":
+            return "Equality comparison (==)";
+        case "logic_not":
+            return "Logical NOT (!)";
+        case "logic_and":
+            return "Logical AND";
+        case "logic_or":
+            return "Logical OR";
+        case "logic_as_u256_greater":
+            return "Numeric greater than (>)";
+        case "logic_as_u256_lesser":
+            return "Numeric less than (<)";
+        case "logic_as_u256_equal":
+            return "Numeric equality (==)";
+        case "logic_as_u256_greater_or_equal":
+            return "Numeric greater than or equal (>=)";
+        case "logic_as_u256_lesser_or_equal":
+            return "Numeric less than or equal (<=)";
+        case "calc_number_add":
+            return "Numeric addition (+)";
+        case "calc_number_subtract":
+            return "Numeric subtraction (-)";
+        case "calc_number_multiply":
+            return "Numeric multiplication (*)";
+        case "calc_number_divide":
+            return "Numeric division (/)";
+        case "calc_number_mod":
+            return "Numeric modulo (%)";
+        case "vec_contains_address":
+            return "Whitelist check (vec_contains_address)";
+        case "vec_length":
+            return "Vector length";
+        case "convert_safe_u64":
+            return "Safe conversion to U64";
+        default:
+            return node.type;
+    }
+}
+function deriveConstraints(table, root, rely, collectors) {
+    const pitfall01 = Array.from(collectors.referencedIdentifiers).every((id) => table.some((t) => t.identifier === id));
+    const pitfall02 = root !== undefined;
+    const pitfall03 = true;
+    const pitfall04 = collectors.witnessCodes.every((w) => w.code >= 100 && w.code <= 108);
+    const pitfall05 = true;
+    const pitfall06 = true;
+    const pitfall07 = root !== undefined;
+    const pitfall08 = rely ? rely.guards.length <= 4 : true;
+    const pitfall09 = true;
+    const pitfall10 = true;
+    const runtime01 = true;
+    const runtime02 = true;
+    const runtime03 = true;
+    const submissionEntries = table.filter((t) => t.b_submission);
+    const runtime04 = submissionEntries.length <= 256;
+    const runtime05 = true;
+    const runtime06 = true;
+    return {
+        pitfall_01_identifiers_in_table: pitfall01,
+        pitfall_02_type_compatibility: pitfall02,
+        pitfall_03_query_instruction_valid: pitfall03,
+        pitfall_04_witness_correct: pitfall04,
+        pitfall_05_time_lock_test_safe: pitfall05,
+        pitfall_06_exported_before_recreate: pitfall06,
+        pitfall_07_root_returns_bool: pitfall07,
+        pitfall_08_rely_rep_true: pitfall08,
+        pitfall_09_voting_weight_numeric: pitfall09,
+        pitfall_10_arbitration_not_paused: pitfall10,
+        runtime_01_guard_immutable: runtime01,
+        runtime_02_submission_type_match: runtime02,
+        runtime_03_submission_complete: runtime03,
+        runtime_04_submission_size: runtime04,
+        runtime_05_witness_source_valid: runtime05,
+        runtime_06_query_object_valid: runtime06,
+    };
+}
+export function derivePuzzleFromCallData(input) {
+    const table = input.table ?? [];
+    const root = input.root;
+    const rely = input.rely;
+    const bindingHint = input.binding_hint;
+    const collectors = {
+        referencedIdentifiers: new Set(),
+        queries: [],
+        contexts: new Set(),
+        witnessCodes: [],
+    };
+    if (root) {
+        traverseRoot(root, collectors);
+    }
+    let intent;
+    if (bindingHint) {
+        intent = {
+            action: bindingHint.action,
+            rule_sentence: bindingHint.rule_sentence ?? "",
+            failure_conditions: bindingHint.failure_conditions ?? [],
+        };
+    }
+    let binding;
+    if (bindingHint) {
+        binding = {
+            host_object: bindingHint.host_object,
+            binding_field: bindingHint.binding_field,
+            circular_reference: bindingHint.circular_reference ?? false,
+            host_object_state: "unknown",
+        };
+    }
+    const witnessCodesByIdentifier = new Map();
+    for (const w of collectors.witnessCodes) {
+        witnessCodesByIdentifier.set(w.objectIdentifier, w.code);
+    }
+    const onChainConstants = [];
+    const witnessDerived = [];
+    const submittedObjects = [];
+    const submittedValues = [];
+    for (const item of table) {
+        const isReferencedByQuery = collectors.referencedIdentifiers.has(item.identifier);
+        const witnessCode = witnessCodesByIdentifier.get(item.identifier);
+        if (witnessCode !== undefined) {
+            const wInfo = getWitnessInfo(witnessCode);
+            if (wInfo) {
+                witnessDerived.push({
+                    identifier: item.identifier,
+                    source_type: wInfo.source,
+                    witness_type: witnessCode,
+                    witness_name: wInfo.name,
+                    target_type: wInfo.target,
+                    source_b_submission: item.b_submission,
+                    name: item.name || `${wInfo.source}→${wInfo.target} via ${wInfo.name}`,
+                });
+                continue;
+            }
+        }
+        if (!item.b_submission) {
+            const valueStr = typeof item.value === "string" ? item.value.toLowerCase() : "";
+            const isSystemAddr = valueStr === "0xaab" || valueStr === "0xaaa";
+            onChainConstants.push({
+                identifier: item.identifier,
+                object_address: typeof item.value === "string" ? item.value : String(item.value ?? ""),
+                object_type: item.object_type ?? "",
+                name: item.name || `constant #${item.identifier}`,
+                is_system_address: isSystemAddr,
+            });
+        }
+        else {
+            const valueTypeStr = typeof item.value_type === "string"
+                ? item.value_type.toLowerCase()
+                : String(item.value_type);
+            if (valueTypeStr === "address") {
+                submittedObjects.push({
+                    identifier: item.identifier,
+                    expected_object_type: item.object_type ?? "",
+                    value_type: "Address",
+                    name: item.name || `submitted object #${item.identifier}`,
+                    binding_constraint: item.object_type
+                        ? `must be an on-chain object address of type ${item.object_type}`
+                        : "must be a valid on-chain object address",
+                });
+            }
+            else {
+                submittedValues.push({
+                    identifier: item.identifier,
+                    value_type: typeof item.value_type === "string" ? item.value_type : String(item.value_type),
+                    name: item.name || `submitted value #${item.identifier}`,
+                    binding_constraint: `value type must be ${item.value_type}`,
+                });
+            }
+        }
+    }
+    const systemContexts = [];
+    for (const ctxType of collectors.contexts) {
+        const usageMap = {
+            Signer: "Current transaction signer address verification",
+            Clock: "On-chain timestamp (used for time-lock/time-window)",
+            Guard: "Guard self object ID self-reference",
+        };
+        systemContexts.push({
+            context_type: ctxType,
+            usage: usageMap[ctxType] ?? "",
+        });
+    }
+    const dataSources = {
+        on_chain_constants: onChainConstants,
+        witness_derived: witnessDerived,
+        submitted_objects: submittedObjects,
+        submitted_values: submittedValues,
+        system_contexts: systemContexts,
+    };
+    const queries = collectors.queries.map((q) => {
+        const wInfo = q.convertWitness !== undefined ? getWitnessInfo(q.convertWitness) : undefined;
+        return {
+            query_id: typeof q.query === "number" ? q.query : 0,
+            query_name: typeof q.query === "string" ? q.query : String(q.query),
+            object_type: "",
+            parameters: [],
+            return_type: "",
+            witness: wInfo ? {
+                witness_type: q.convertWitness,
+                witness_name: wInfo.name,
+                source_type: wInfo.source,
+                target_type: wInfo.target,
+                scenario: "",
+            } : undefined,
+            purpose: "",
+        };
+    });
+    let logic;
+    if (root) {
+        const logicRoot = buildLogicTree(root);
+        if (logicRoot) {
+            logicRoot.return_type = "Bool";
+            let logicRely;
+            if (rely && rely.guards.length > 0) {
+                logicRely = {
+                    guards: rely.guards,
+                    logic_or: rely.logic_or ?? false,
+                    rep_verified: rely.guards.map(() => true),
+                };
+            }
+            logic = { root: logicRoot, rely: logicRely };
+        }
+    }
+    const constraints = deriveConstraints(table, root, rely, collectors);
+    const puzzle = {
+        current_round: "R7",
+        intent,
+        binding,
+        data_sources: dataSources,
+        queries,
+        logic,
+        constraints,
+    };
+    return puzzle;
+}
+export function getPuzzleStatusBooleans(puzzle) {
+    const completeness = checkPuzzleCompleteness(puzzle);
+    return {
+        intent: completeness.dimensions.intent,
+        binding: completeness.dimensions.binding,
+        data: completeness.dimensions.data_sources,
+        query: completeness.dimensions.query,
+        logic: completeness.dimensions.logic,
+        constraints: completeness.dimensions.constraints,
+    };
+}
+export function getPendingQuestions(puzzle) {
+    const completeness = checkPuzzleCompleteness(puzzle);
+    if (completeness.complete) {
+        return [];
+    }
+    return completeness.next_step.questions;
+}