@wowok/agent-mcp 2.3.18 → 2.4.1

package/dist/knowledge/guard-puzzle.js

@@ -2,7 +2,7 @@ export function checkPuzzleCompleteness(puzzle) {
     const dimensions = {
         intent: isIntentComplete(puzzle.intent),
         binding: isBindingComplete(puzzle.binding),
-        data: isDataComplete(puzzle.data),
+        data_sources: isDataSourcesComplete(puzzle.data_sources),
         query: isQueryComplete(puzzle.queries),
         logic: isLogicComplete(puzzle.logic),
         constraints: isConstraintsComplete(puzzle.constraints),
@@ -10,22 +10,22 @@ export function checkPuzzleCompleteness(puzzle) {
     const missing = Object.keys(dimensions).filter((k) => !dimensions[k]);
     const missing_details = [];
     if (!dimensions.intent) {
-        missing_details.push("A. 意图：未明确被保护动作、验证规则或失败条件");
+        missing_details.push("A. Intent: protected action, validation rule, or failure conditions not clarified");
     }
     if (!dimensions.binding) {
-        missing_details.push("B. 绑定：未确定 Host Object、绑定字段或循环引用模式");
+        missing_details.push("B. Binding: Host Object, binding field, or circular reference mode not determined");
     }
-    if (!dimensions.data) {
-        missing_details.push("C. 数据：未声明 table 条目（常量/提交）或 convert_witness");
+    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. 查询：未确定查询指令（如果 Guard 需要查询链上数据）");
+        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. 逻辑：未设计计算树 root 或 rely 组合");
+        missing_details.push("E. Logic: computation tree root or rely composition not designed");
     }
     if (!dimensions.constraints) {
-        missing_details.push("F. 约束：未完成 10 项 Common Pitfalls 检查");
+        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);
@@ -37,8 +37,21 @@ function isIntentComplete(intent) {
 function isBindingComplete(binding) {
     return !!binding && !!binding.host_object && !!binding.binding_field;
 }
-function isDataComplete(data) {
-    return !!data && data.entries.length > 0;
+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;
@@ -55,186 +68,262 @@ function recommendNextStep(puzzle, missing) {
     if (missing.includes("intent")) {
         return {
             round: "R1",
-            action: "捕获验证意图",
+            action: "Capture validation intent",
             questions: [
-                "你要保护什么动作？（buy/forward/claim/vote/dispute/write/allocate）",
-                "用一句话描述验证规则",
-                "列出 Guard 应该 FAIL 的情况",
+                "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: "确定绑定目标",
+            action: "Determine binding target",
             questions: [
-                "Guard 将绑定到哪个 Host Object？（Service/Machine/Arbitration/Reward/Repository）",
-                "绑定到哪个字段？（buy_guard/order_allocators/Forward.guard/...）",
-                "Guard 是否需要引用 Host Object？（循环引用模式）",
+                "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")) {
+    if (missing.includes("data_sources")) {
         return {
             round: "R2",
-            action: "声明数据表",
+            action: "Declare data sources by 4 classifications",
             questions: [
-                "Guard 需要哪些常量数据？（已知且不变的值）",
-                "Guard 需要哪些提交数据？（运行时由 caller 提供）",
-                "每个提交数据的 value_type 是什么？",
-                "是否需要查询 EntityRegistrar(0xaab) 或 EntityLinker(0xaaa)？",
+                "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: "设计查询节点",
+            action: "Design query nodes",
             questions: [
-                "Guard 需要查询哪些链上对象？",
-                "每个查询使用哪个指令 ID？（从 GUARDQUERY 查询）",
-                "是否需要 convert_witness 转换对象？",
+                "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: "设计计算树",
+            action: "Design computation tree",
             questions: [
-                "root 节点是什么？（必须返回 Bool）",
-                "数据源节点有哪些？（identifier/context/query）",
-                "中间转换节点有哪些？（calc_*/convert_*/vec_*）",
-                "是否需要 rely 组合其他 Guard？",
+                "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: "预创建审查",
-            questions: ["运行 10 项 Common Pitfalls 检查清单"],
+            action: "Pre-creation review",
+            questions: ["Run the creation-time 10 + runtime 6 constraint checklist"],
         };
     }
     return {
         round: "R7",
-        action: "准备链上创建",
-        questions: ["所有维度已补全，准备生成语义确认文本"],
+        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 || !puzzle.logic) {
-        return "【拼图未完整】无法生成确认文本，请先补全所有维度";
+    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 语义确认报告（用户审核版）");
+    lines.push("  Guard Semantic Confirmation Report (User Review Edition)");
     lines.push("═══════════════════════════════════════════════════════");
     lines.push("");
-    lines.push("【意图】");
-    lines.push(`被保护动作: ${puzzle.intent.action}`);
-    lines.push(`验证规则: ${puzzle.intent.rule_sentence}`);
-    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("【绑定】");
+    lines.push("[Binding]");
     lines.push(`Host Object: ${puzzle.binding.host_object}`);
     if (puzzle.binding.host_object_name) {
-        lines.push(`Host Object 名称: ${puzzle.binding.host_object_name}`);
+        lines.push(`Host Object name: ${puzzle.binding.host_object_name}`);
     }
-    lines.push(`绑定字段: ${puzzle.binding.binding_field}`);
-    lines.push(`循环引用: ${puzzle.binding.circular_reference ? "是（Guard 引用 Host Object）" : "否"}`);
-    lines.push(`Host Object 状态: ${puzzle.binding.host_object_state}`);
+    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("【数据表】");
-    lines.push("┌─────┬──────────┬──────────┬───────────────┬─────────────────────────┐");
-    lines.push("│ ID  │ 类型     │ 提交/常量│ 值/占位       │ 名称描述                │");
-    lines.push("├─────┼──────────┼──────────┼───────────────┼─────────────────────────┤");
-    puzzle.data.entries.forEach((e) => {
-        const id = String(e.identifier).padEnd(3);
-        const type = e.value_type.padEnd(8);
-        const src = (e.b_submission ? "提交" : "常量").padEnd(8);
-        const val = (e.b_submission ? "(运行时)" : String(e.value ?? "")).padEnd(13);
-        const name = e.name.length > 23 ? e.name.slice(0, 22) + "…" : e.name.padEnd(23);
-        lines.push(`│ ${id} │ ${type} │ ${src} │ ${val} │ ${name} │`);
-    });
-    lines.push("└─────┴──────────┴──────────┴───────────────┴─────────────────────────┘");
-    if (puzzle.data.witnesses.length > 0) {
-        lines.push("");
-        lines.push("【对象转换 (convert_witness)】");
-        puzzle.data.witnesses.forEach((w) => {
-            lines.push(`  ${w.witness_type} (${w.witness_name}): ${w.source_type} → ${w.target_type}`);
-            lines.push(`    场景: ${w.scenario}`);
-        });
-    }
+    lines.push("[Data sources (4 classifications)]");
+    printDataSources(lines, puzzle.data_sources);
     lines.push("");
     if (puzzle.queries && puzzle.queries.length > 0) {
-        lines.push("【查询指令】");
+        lines.push("[Query instructions]");
         lines.push("┌──────┬──────────────────────────┬────────────┬──────────┬──────────┐");
-        lines.push("│ ID   │ 查询指令                 │ 目标对象   │ 参数     │ 返回类型 │");
+        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 ? "(无)" : q.parameters.join(",")).padEnd(8);
+            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("【计算树】");
-    lines.push(`root: ${puzzle.logic.root.node_type} (返回: ${puzzle.logic.root.return_type})`);
+    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 组合】");
-        lines.push(`依赖 Guard: ${puzzle.logic.rely.guards.join(", ")}`);
-        lines.push(`逻辑: ${puzzle.logic.rely.logic_or ? "OR（任一通过即可）" : "AND（全部必须通过）"}`);
-        lines.push(`rep 验证: ${puzzle.logic.rely.rep_verified.every((v) => v) ? "全部通过" : "有未验证"}`);
+        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("【约束检查清单 (10 项 Common Pitfalls)】");
-        const checks = [
-            ["01", "所有 identifier 在 table 中存在", puzzle.constraints.pitfall_01_identifiers_in_table],
-            ["02", "比较节点类型兼容", puzzle.constraints.pitfall_02_type_compatibility],
-            ["03", "查询指令 ID 和参数数量正确", puzzle.constraints.pitfall_03_query_instruction_valid],
-            ["04", "convert_witness 类型正确", puzzle.constraints.pitfall_04_witness_correct],
-            ["05", "时间锁测试用小值", puzzle.constraints.pitfall_05_time_lock_test_safe],
-            ["06", "迭代前已导出旧 Guard", puzzle.constraints.pitfall_06_exported_before_recreate],
-            ["07", "root 返回 Bool", puzzle.constraints.pitfall_07_root_returns_bool],
-            ["08", "rely 依赖 rep=true", puzzle.constraints.pitfall_08_rely_rep_true],
+        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 未暂停", puzzle.constraints.pitfall_10_arbitration_not_paused],
+            ["10", "Arbitration not paused", puzzle.constraints.pitfall_10_arbitration_not_paused],
         ];
-        checks.forEach(([num, desc, pass]) => {
+        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("【风险提示】");
-    lines.push("  ⚠ Guard 创建后不可修改、不可删除（CREATE-only）");
-    lines.push("  ⚠ 链上执行将消耗 gas");
-    lines.push("  ⚠ 创建后如需修改，需 export → 编辑 → 新建 → 重新绑定");
+    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("【测试计划 (gen_passport 静态测试)】");
-    lines.push("  预期通过场景: 提交符合条件的数据 → PASS → 生成 Passport");
-    lines.push("  预期失败场景: 提交不符合条件的数据 → FAIL → 验证逻辑方向正确");
+    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("  请审核以上 Guard 语义确认报告");
-    lines.push("  确认无误后回复「确认创建」以执行链上 CREATE");
-    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) => {
@@ -276,3 +365,440 @@ export function inferBindingFromAction(action) {
     };
     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;
+}