@wowok/agent-mcp 2.6.0 → 2.6.3

package/dist/project/edit-planner.js

@@ -0,0 +1,1371 @@
+import { randomUUID, createHash } from "node:crypto";
+import { LocalProject, LocalMark, query_objects, query_table } from "@wowok/wowok";
+import { parseMachineTreeIndented, } from "../knowledge/machine-render.js";
+import { parseGuardTreeIndented, parseGuardTableJSON, } from "../knowledge/guard-render.js";
+const PLAN_TTL_MS = 10 * 60 * 1000;
+const planStore = new Map();
+function cleanupExpiredPlans() {
+    const now = Date.now();
+    for (const [id, plan] of planStore) {
+        if (now > plan.expires_at) {
+            planStore.delete(id);
+        }
+    }
+}
+const localProject = LocalProject.Instance();
+async function resolveProjectId(v) {
+    if (v.project_id)
+        return v.project_id;
+    if (v.project) {
+        const p = await localProject.getProjectByPrefix(v.project);
+        if (!p)
+            throw new Error(`Project not found by prefix: ${v.project}`);
+        return p.id;
+    }
+    throw new Error("Either 'project_id' or 'project' (prefix) is required for this action");
+}
+async function resolveObjectAddress(v) {
+    if (v.object_address) {
+        const addr = v.object_address;
+        const isHexAddress = /^0x[0-9a-fA-F]{32,64}$/.test(addr);
+        const isDraftSentinel = addr.startsWith("draft:");
+        if (!isHexAddress && !isDraftSentinel) {
+            throw new Error(`Invalid object_address format: '${addr.slice(0, 40)}'. ` +
+                `Expected a valid Sui address (0x + 32-64 hex chars) or 'draft:<name>' sentinel.`);
+        }
+        return addr;
+    }
+    if (v.object_name_add) {
+        const mark = await LocalMark.Instance().get(v.object_name_add);
+        if (mark?.address)
+            return mark.address;
+        throw new Error(`LocalMark name not found: ${v.object_name_add}`);
+    }
+    throw new Error("Either 'object_address' or 'object_name_add' is required");
+}
+function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function diffMachine(oldNodes, oldEdges, newNodes, newEdges) {
+    const added = [];
+    const removed = [];
+    const modified = [];
+    const oldNodeNames = new Set(oldNodes.map(n => n.name));
+    const newNodeNames = new Set(newNodes.map(n => n.name));
+    for (const name of newNodeNames) {
+        if (!oldNodeNames.has(name))
+            added.push(`node: ${name}`);
+    }
+    for (const name of oldNodeNames) {
+        if (!newNodeNames.has(name))
+            removed.push(`node: ${name}`);
+    }
+    const oldEdgeMap = new Map();
+    for (const e of oldEdges)
+        oldEdgeMap.set(`${e.from}->${e.to}`, e);
+    const newEdgeMap = new Map();
+    for (const e of newEdges)
+        newEdgeMap.set(`${e.from}->${e.to}`, e);
+    for (const [key, newEdge] of newEdgeMap) {
+        if (!oldEdgeMap.has(key)) {
+            added.push(`edge: ${key}`);
+        }
+        else {
+            const oldEdge = oldEdgeMap.get(key);
+            if (oldEdge.threshold !== newEdge.threshold) {
+                modified.push(`edge ${key}: threshold ${oldEdge.threshold} -> ${newEdge.threshold}`);
+            }
+            const oldFwdNames = new Set(oldEdge.forwards.map(f => f.name));
+            const newFwdNames = new Set(newEdge.forwards.map(f => f.name));
+            for (const fname of newFwdNames) {
+                if (!oldFwdNames.has(fname)) {
+                    added.push(`forward: ${key} / ${fname}`);
+                }
+                else {
+                    const oldFwd = oldEdge.forwards.find(f => f.name === fname);
+                    const newFwd = newEdge.forwards.find(f => f.name === fname);
+                    const changes = [];
+                    if (oldFwd.guard !== newFwd.guard)
+                        changes.push(`guard ${oldFwd.guard} -> ${newFwd.guard}`);
+                    if (oldFwd.permission_index !== newFwd.permission_index)
+                        changes.push(`perm ${oldFwd.permission_index} -> ${newFwd.permission_index}`);
+                    if (oldFwd.named_operator !== newFwd.named_operator)
+                        changes.push(`op ${oldFwd.named_operator} -> ${newFwd.named_operator}`);
+                    if (oldFwd.weight !== newFwd.weight)
+                        changes.push(`weight ${oldFwd.weight} -> ${newFwd.weight}`);
+                    if (changes.length > 0) {
+                        modified.push(`forward ${key} / ${fname}: ${changes.join(", ")}`);
+                    }
+                }
+            }
+            for (const fname of oldFwdNames) {
+                if (!newFwdNames.has(fname)) {
+                    removed.push(`forward: ${key} / ${fname}`);
+                }
+            }
+        }
+    }
+    for (const key of oldEdgeMap.keys()) {
+        if (!newEdgeMap.has(key))
+            removed.push(`edge: ${key}`);
+    }
+    const summary = `${added.length} added, ${removed.length} removed, ${modified.length} modified`;
+    return { added, removed, modified, summary };
+}
+function diffGuard(oldRoot, newRoot, oldTable, newTable) {
+    const added = [];
+    const removed = [];
+    const modified = [];
+    function walk(oldNode, newNode, path) {
+        if (!oldNode && newNode) {
+            added.push(`node: ${path} (${newNode.type})`);
+            return;
+        }
+        if (oldNode && !newNode) {
+            removed.push(`node: ${path} (${oldNode.type})`);
+            return;
+        }
+        if (!oldNode || !newNode)
+            return;
+        if (oldNode.type !== newNode.type) {
+            modified.push(`node ${path}: type ${oldNode.type} -> ${newNode.type}`);
+            return;
+        }
+        if (oldNode.type === "identifier" && newNode.type === "identifier") {
+            if (oldNode.identifier !== newNode.identifier) {
+                modified.push(`node ${path}: identifier ${oldNode.identifier} -> ${newNode.identifier}`);
+            }
+        }
+        if (oldNode.type === "context" && newNode.type === "context") {
+            if (oldNode.context !== newNode.context) {
+                modified.push(`node ${path}: context ${oldNode.context} -> ${newNode.context}`);
+            }
+        }
+        if (oldNode.type === "query" && newNode.type === "query") {
+            if (oldNode.query !== newNode.query) {
+                modified.push(`node ${path}: query ${oldNode.query} -> ${newNode.query}`);
+            }
+        }
+        const oldChildren = getGuardChildren(oldNode);
+        const newChildren = getGuardChildren(newNode);
+        const maxLen = Math.max(oldChildren.length, newChildren.length);
+        for (let i = 0; i < maxLen; i++) {
+            walk(oldChildren[i]?.node, newChildren[i]?.node, `${path}.${newChildren[i]?.label ?? oldChildren[i]?.label ?? i}`);
+        }
+    }
+    walk(oldRoot, newRoot, "root");
+    const oldTableMap = new Map(oldTable.map(t => [t.identifier, t]));
+    const newTableMap = new Map(newTable.map(t => [t.identifier, t]));
+    for (const [id, newEntry] of newTableMap) {
+        if (!oldTableMap.has(id)) {
+            added.push(`table: id[${id}]`);
+        }
+        else {
+            const oldEntry = oldTableMap.get(id);
+            const changes = [];
+            if (oldEntry.value_type !== newEntry.value_type)
+                changes.push(`type ${oldEntry.value_type} -> ${newEntry.value_type}`);
+            if (oldEntry.b_submission !== newEntry.b_submission)
+                changes.push(`submission ${oldEntry.b_submission} -> ${newEntry.b_submission}`);
+            if (JSON.stringify(oldEntry.value) !== JSON.stringify(newEntry.value))
+                changes.push(`value changed`);
+            if (changes.length > 0)
+                modified.push(`table id[${id}]: ${changes.join(", ")}`);
+        }
+    }
+    for (const id of oldTableMap.keys()) {
+        if (!newTableMap.has(id))
+            removed.push(`table: id[${id}]`);
+    }
+    const summary = `${added.length} added, ${removed.length} removed, ${modified.length} modified`;
+    return { added, removed, modified, summary };
+}
+function getGuardChildren(node) {
+    const children = [];
+    if (node.nodes)
+        node.nodes.forEach((c, i) => children.push({ node: c, label: `child[${i}]` }));
+    if (node.node)
+        children.push({ node: node.node, label: "child" });
+    if (node.nodeLeft)
+        children.push({ node: node.nodeLeft, label: "left" });
+    if (node.nodeRight)
+        children.push({ node: node.nodeRight, label: "right" });
+    if (node.parameters)
+        node.parameters.forEach((c, i) => children.push({ node: c, label: `param[${i}]` }));
+    if (node.historyIdx)
+        children.push({ node: node.historyIdx, label: "historyIdx" });
+    if (node.sessionIdx)
+        children.push({ node: node.sessionIdx, label: "sessionIdx" });
+    if (node.forwardIdx)
+        children.push({ node: node.forwardIdx, label: "forwardIdx" });
+    if (node.where)
+        children.push({ node: node.where, label: "where" });
+    if (node.find)
+        children.push({ node: node.find, label: "find" });
+    if (node.objectLeft)
+        children.push({ node: node.objectLeft, label: "objLeft" });
+    if (node.objectRight)
+        children.push({ node: node.objectRight, label: "objRight" });
+    if (node.recipient)
+        children.push({ node: node.recipient, label: "recipient" });
+    return children;
+}
+function validateMachine(nodes, edges) {
+    const warnings = [];
+    const blocking_errors = [];
+    const hasEntry = edges.some(e => e.from === "");
+    if (!hasEntry) {
+        blocking_errors.push({
+            id: "E-01",
+            description: "No entry forward found (no edge with from=''). Every Machine must have at least one entry forward.",
+            impact: "The Machine cannot start — no way to create the first Progress entry.",
+        });
+    }
+    const nodeNames = new Set(nodes.map(n => n.name));
+    for (const edge of edges) {
+        if (edge.from && !nodeNames.has(edge.from)) {
+            blocking_errors.push({
+                id: "E-02",
+                description: `Edge ${edge.from}->${edge.to} references unknown source node '${edge.from}'.`,
+                impact: "The on-chain Machine will reject this — all edge endpoints must exist as nodes.",
+            });
+        }
+        if (!nodeNames.has(edge.to)) {
+            blocking_errors.push({
+                id: "E-02",
+                description: `Edge ${edge.from}->${edge.to} references unknown target node '${edge.to}'.`,
+                impact: "The on-chain Machine will reject this — all edge endpoints must exist as nodes.",
+            });
+        }
+    }
+    if (nodes.length > 200) {
+        blocking_errors.push({
+            id: "E-03",
+            description: `Node count ${nodes.length} exceeds on-chain MAX_NODE_COUNT (200).`,
+            impact: "The on-chain Machine will reject this — split the workflow into multiple Machines.",
+        });
+    }
+    const nodesWithIncoming = new Set(edges.filter(e => e.from !== "").map(e => e.to));
+    const entryNodes = new Set(edges.filter(e => e.from === "").map(e => e.to));
+    for (const node of nodes) {
+        if (!nodesWithIncoming.has(node.name) && !entryNodes.has(node.name)) {
+            warnings.push({
+                id: "W-01",
+                description: `Node '${node.name}' has no incoming edges and is not an entry node (unreachable).`,
+                impact: "This node will never be reached during workflow execution.",
+            });
+        }
+    }
+    for (const edge of edges) {
+        if (edge.from === edge.to && edge.from !== "") {
+            warnings.push({
+                id: "W-02",
+                description: `Self-loop detected on node '${edge.from}' (revision cycle).`,
+                impact: "This is intentional for revision workflows, but ensure there's an exit forward to break the cycle.",
+            });
+        }
+    }
+    return { warnings, blocking_errors };
+}
+function validateGuard(root, table) {
+    const warnings = [];
+    const blocking_errors = [];
+    if (!root) {
+        blocking_errors.push({
+            id: "E-01",
+            description: "Guard tree has no root node.",
+            impact: "The on-chain Guard will reject this — every Guard must have a root computation node.",
+        });
+        return { warnings, blocking_errors };
+    }
+    const tableIds = new Set(table.map(t => t.identifier));
+    const referencedIds = new Set();
+    function collectIds(node) {
+        if (node.type === "identifier" && typeof node.identifier === "number") {
+            referencedIds.add(node.identifier);
+        }
+        for (const child of getGuardChildren(node)) {
+            collectIds(child.node);
+        }
+    }
+    collectIds(root);
+    for (const id of referencedIds) {
+        if (!tableIds.has(id)) {
+            blocking_errors.push({
+                id: "E-02",
+                description: `Identifier ${id} is referenced in the tree but not defined in the table.`,
+                impact: "The on-chain Guard will reject this — all identifier references must have a table entry.",
+            });
+        }
+    }
+    if (table.length > 256) {
+        blocking_errors.push({
+            id: "E-03",
+            description: `Table size ${table.length} exceeds on-chain MAX_TABLE_SIZE (256).`,
+            impact: "The on-chain Guard will reject this — reduce the number of table entries.",
+        });
+    }
+    const submissionSlots = table.filter(t => t.b_submission);
+    for (const slot of submissionSlots) {
+        if (!referencedIds.has(slot.identifier)) {
+            const label = slot.name ? `'${slot.name}' (id=${slot.identifier})` : `id=${slot.identifier}`;
+            warnings.push({
+                id: "W-01",
+                description: `Submission slot ${label} is declared in the table but never referenced by any identifier node in the tree.`,
+                impact: "This slot is dead — submitting a value for it has no effect on the guard result. Remove it or add an identifier reference.",
+            });
+        }
+    }
+    for (const entry of table) {
+        if (!referencedIds.has(entry.identifier)) {
+            if (entry.b_submission)
+                continue;
+            const label = entry.name ? `'${entry.name}' (id=${entry.identifier})` : `id=${entry.identifier}`;
+            warnings.push({
+                id: "W-02",
+                description: `Table entry ${label} is declared but never referenced by any identifier node in the tree.`,
+                impact: "This entry is orphaned — it consumes table space without affecting the guard result. Remove it to reduce table size.",
+            });
+        }
+    }
+    function maxDepth(node, depth) {
+        if (depth > 16)
+            return depth;
+        const children = getGuardChildren(node);
+        if (children.length === 0)
+            return depth;
+        return Math.max(...children.map(c => maxDepth(c.node, depth + 1)));
+    }
+    const depth = maxDepth(root, 1);
+    if (depth > 16) {
+        warnings.push({
+            id: "W-03",
+            description: `Guard tree depth ${depth} exceeds 16 (heuristic threshold for on-chain recursion safety).`,
+            impact: "Deep trees may hit on-chain stack/gas limits or fail audit. Consider flattening logic (e.g. split into multiple guards connected via rely) or simplifying nested computations.",
+        });
+    }
+    return { warnings, blocking_errors };
+}
+function prepareMachineCall(objectName, objectAddress, nodes, edges) {
+    const nodeMap = new Map();
+    for (const node of nodes) {
+        nodeMap.set(node.name, {
+            name: node.name,
+            description: node.description ?? null,
+            pairs: [],
+        });
+    }
+    for (const edge of edges) {
+        if (!nodeMap.has(edge.to)) {
+            nodeMap.set(edge.to, { name: edge.to, description: null, pairs: [] });
+        }
+        nodeMap.get(edge.to).pairs.push({
+            prev_node: edge.from,
+            threshold: edge.threshold,
+            forwards: edge.forwards.map(f => ({
+                name: f.name,
+                weight: f.weight,
+                namedOperator: f.named_operator ?? "",
+                permissionIndex: f.permission_index ?? 0,
+                guard: f.guard ? { guard: f.guard } : null,
+                retained_submission: f.retained_submission ?? null,
+            })),
+        });
+    }
+    const nodeList = Array.from(nodeMap.values());
+    const jsonContent = JSON.stringify(nodeList, null, 2);
+    return {
+        operation_type: "machine",
+        data: {
+            namedNew: { name: objectName ?? objectAddress },
+            node: {
+                json_or_markdown: jsonContent,
+            },
+            bReplace: true,
+        },
+    };
+}
+function prepareGuardCall(objectName, objectAddress, root, table, rely) {
+    const data = {
+        namedNew: { name: objectName ?? objectAddress },
+        root: {
+            type: "inline_json",
+            json: JSON.stringify(root, null, 2),
+        },
+        table: table.map(t => ({
+            identifier: t.identifier,
+            b_submission: t.b_submission,
+            value_type: typeof t.value_type === "string" ? t.value_type : t.value_type,
+            value: t.value,
+            name: t.name,
+        })),
+    };
+    if (rely && Array.isArray(rely.guards) && rely.guards.length > 0) {
+        data.rely = {
+            guards: rely.guards,
+            logic_or: rely.logic_or,
+        };
+    }
+    return {
+        operation_type: "guard",
+        data,
+    };
+}
+export async function handlePlanObjectEdit(v) {
+    cleanupExpiredPlans();
+    const projectId = await resolveProjectId(v);
+    const objectAddress = await resolveObjectAddress(v);
+    const objectKind = v.object_kind;
+    const editFormat = v.edit_format ?? "tree_outline";
+    const editedContent = v.edited_content;
+    if (!objectKind) {
+        throw new Error("'object_kind' is required for plan_object_edit (must be 'machine' or 'guard')");
+    }
+    if (!editedContent) {
+        throw new Error("'edited_content' is required for plan_object_edit");
+    }
+    const project = await localProject.getProject(projectId);
+    if (!project)
+        throw new Error(`Project not found (id: ${projectId})`);
+    let objectName = null;
+    try {
+        const mark = await LocalMark.Instance().get(objectAddress);
+        objectName = mark?.name ?? null;
+    }
+    catch {
+    }
+    const network = (project.network ?? "testnet");
+    let parsedResult;
+    if (objectKind === "machine") {
+        parsedResult = parseMachineTreeIndented(editedContent);
+    }
+    else {
+        parsedResult = parseGuardTreeIndented(editedContent);
+    }
+    if (!parsedResult.success || !parsedResult.data) {
+        const plan = {
+            plan_id: randomUUID(),
+            object_kind: objectKind,
+            object_address: objectAddress,
+            object_name: objectName,
+            expected_hash: sha256(editedContent),
+            edited_content: editedContent,
+            edit_format: editFormat,
+            diff: { added: [], removed: [], modified: [], summary: "parse failed — no diff computed" },
+            warnings: [],
+            blocking_errors: [{
+                    id: "E-PARSE",
+                    description: `Failed to parse edited content: ${parsedResult.errors.join("; ")}`,
+                    impact: "The edited content is malformed and cannot be applied. Fix the syntax and try again.",
+                }],
+            can_apply: false,
+            prepared_call: null,
+            created_at: Date.now(),
+            expires_at: Date.now() + PLAN_TTL_MS,
+            summary: `Parse failed — ${parsedResult.errors.length} error(s)`,
+        };
+        planStore.set(plan.plan_id, plan);
+        return {
+            action: "plan_object_edit",
+            plan_id: plan.plan_id,
+            object_kind: plan.object_kind,
+            object_address: plan.object_address,
+            object_name: plan.object_name,
+            expected_hash: plan.expected_hash,
+            diff: plan.diff,
+            warnings: plan.warnings,
+            blocking_errors: plan.blocking_errors,
+            can_apply: plan.can_apply,
+            prepared_call: plan.prepared_call,
+            expires_at: new Date(plan.expires_at).toISOString(),
+            summary: plan.summary,
+        };
+    }
+    const stateHash = sha256(JSON.stringify(parsedResult.data) + editedContent);
+    if (objectKind === "machine") {
+        const newNodes = parsedResult.data.nodes;
+        const newEdges = parsedResult.data.edges;
+        let oldNodes = [];
+        let oldEdges = [];
+        try {
+            const currentResult = await fetchCurrentMachine(objectAddress, network);
+            oldNodes = currentResult.nodes;
+            oldEdges = currentResult.edges;
+        }
+        catch {
+        }
+        const diff = diffMachine(oldNodes, oldEdges, newNodes, newEdges);
+        const validation = validateMachine(newNodes, newEdges);
+        const canApply = validation.blocking_errors.length === 0;
+        const preparedCall = canApply ? prepareMachineCall(objectName, objectAddress, newNodes, newEdges) : null;
+        const plan = {
+            plan_id: randomUUID(),
+            object_kind: objectKind,
+            object_address: objectAddress,
+            object_name: objectName,
+            expected_hash: stateHash,
+            edited_content: editedContent,
+            edit_format: editFormat,
+            diff,
+            warnings: validation.warnings,
+            blocking_errors: validation.blocking_errors,
+            can_apply: canApply,
+            prepared_call: preparedCall,
+            created_at: Date.now(),
+            expires_at: Date.now() + PLAN_TTL_MS,
+            summary: `Machine edit: ${diff.summary}. ${validation.blocking_errors.length} blocking error(s), ${validation.warnings.length} warning(s).`,
+        };
+        planStore.set(plan.plan_id, plan);
+        return {
+            action: "plan_object_edit",
+            plan_id: plan.plan_id,
+            object_kind: plan.object_kind,
+            object_address: plan.object_address,
+            object_name: plan.object_name,
+            expected_hash: plan.expected_hash,
+            diff: plan.diff,
+            warnings: plan.warnings,
+            blocking_errors: plan.blocking_errors,
+            can_apply: plan.can_apply,
+            prepared_call: plan.prepared_call,
+            expires_at: new Date(plan.expires_at).toISOString(),
+            summary: plan.summary,
+        };
+    }
+    const newRoot = parsedResult.data;
+    let newTable = [];
+    const tableJson = parseGuardTableJSON(editedContent);
+    if (tableJson && tableJson.length > 0) {
+        newTable = tableJson;
+    }
+    else {
+        const tableMatch = editedContent.match(/##\s*Table[^\n]*\n([\s\S]*?)(?=\n##\s|$)/i);
+        if (tableMatch) {
+            const tableLines = tableMatch[1].split("\n").filter(l => l.trim().startsWith("| "));
+            for (const line of tableLines.slice(2)) {
+                const cells = line.split("|").map(c => c.trim()).filter(Boolean);
+                if (cells.length >= 4) {
+                    newTable.push({
+                        identifier: parseInt(cells[0], 10),
+                        b_submission: cells[1] === "true",
+                        value_type: cells[2],
+                        value: cells[3] === "-" ? undefined : cells[3],
+                        name: cells[4] === "-" ? undefined : cells[4],
+                    });
+                }
+            }
+        }
+    }
+    let oldRoot = null;
+    let oldTable = [];
+    let oldRely = null;
+    try {
+        const currentResult = await fetchCurrentGuard(objectAddress, network);
+        oldRoot = currentResult.root;
+        oldTable = currentResult.table;
+        oldRely = currentResult.rely;
+    }
+    catch {
+    }
+    const diff = diffGuard(oldRoot ?? newRoot, newRoot, oldTable, newTable);
+    const validation = validateGuard(newRoot, newTable);
+    const canApply = validation.blocking_errors.length === 0;
+    const preparedCall = canApply ? prepareGuardCall(objectName, objectAddress, newRoot, newTable, oldRely) : null;
+    const plan = {
+        plan_id: randomUUID(),
+        object_kind: objectKind,
+        object_address: objectAddress,
+        object_name: objectName,
+        expected_hash: stateHash,
+        edited_content: editedContent,
+        edit_format: editFormat,
+        diff,
+        warnings: validation.warnings,
+        blocking_errors: validation.blocking_errors,
+        can_apply: canApply,
+        prepared_call: preparedCall,
+        created_at: Date.now(),
+        expires_at: Date.now() + PLAN_TTL_MS,
+        summary: `Guard edit: ${diff.summary}. ${validation.blocking_errors.length} blocking error(s), ${validation.warnings.length} warning(s).`,
+    };
+    planStore.set(plan.plan_id, plan);
+    return {
+        action: "plan_object_edit",
+        plan_id: plan.plan_id,
+        object_kind: plan.object_kind,
+        object_address: plan.object_address,
+        object_name: plan.object_name,
+        expected_hash: plan.expected_hash,
+        diff: plan.diff,
+        warnings: plan.warnings,
+        blocking_errors: plan.blocking_errors,
+        can_apply: plan.can_apply,
+        prepared_call: plan.prepared_call,
+        expires_at: new Date(plan.expires_at).toISOString(),
+        summary: plan.summary,
+    };
+}
+export async function handleApplyObjectEdit(v) {
+    cleanupExpiredPlans();
+    const planId = v.plan_id;
+    const expectedHash = v.expected_hash;
+    if (!planId) {
+        throw new Error("'plan_id' is required for apply_object_edit");
+    }
+    if (!expectedHash) {
+        throw new Error("'expected_hash' is required for apply_object_edit");
+    }
+    const plan = planStore.get(planId);
+    if (!plan) {
+        return {
+            action: "apply_object_edit",
+            plan_id: planId,
+            applied: false,
+            hash_match: false,
+            prepared_call: null,
+            error: `Plan not found (id: ${planId}). The plan may have expired (10-minute TTL) or never existed.`,
+            next_step: "Re-run plan_object_edit to create a new plan.",
+        };
+    }
+    if (Date.now() > plan.expires_at) {
+        planStore.delete(planId);
+        return {
+            action: "apply_object_edit",
+            plan_id: planId,
+            applied: false,
+            hash_match: false,
+            prepared_call: null,
+            error: `Plan expired at ${new Date(plan.expires_at).toISOString()}. Plans have a 10-minute TTL.`,
+            next_step: "Re-run plan_object_edit to create a new plan.",
+        };
+    }
+    const hashMatch = plan.expected_hash === expectedHash;
+    if (!hashMatch) {
+        return {
+            action: "apply_object_edit",
+            plan_id: planId,
+            applied: false,
+            hash_match: false,
+            prepared_call: null,
+            error: `Hash mismatch — the on-chain state may have changed between plan and apply, or the edited_content was modified. Expected: ${plan.expected_hash}, got: ${expectedHash}.`,
+            next_step: "Re-run plan_object_edit to create a fresh plan based on the current on-chain state.",
+        };
+    }
+    if (!plan.can_apply) {
+        return {
+            action: "apply_object_edit",
+            plan_id: planId,
+            applied: false,
+            hash_match: true,
+            prepared_call: null,
+            error: `Plan has ${plan.blocking_errors.length} blocking error(s). Fix them before applying: ${plan.blocking_errors.map(e => e.description).join("; ")}`,
+            next_step: "Fix the blocking errors in the edited content, then re-run plan_object_edit.",
+        };
+    }
+    return {
+        action: "apply_object_edit",
+        plan_id: planId,
+        applied: true,
+        hash_match: true,
+        prepared_call: plan.prepared_call,
+        error: null,
+        next_step: "Pass the prepared_call to onchain_operations to execute the edit on-chain. Review the call data before executing — it will modify the on-chain object.",
+    };
+}
+async function fetchCurrentMachine(machineAddress, network) {
+    const allFieldObjectIds = [];
+    let cursor = undefined;
+    for (;;) {
+        const tableResult = await query_table({
+            parent: machineAddress,
+            cursor: cursor ?? undefined,
+            network,
+        });
+        if (!tableResult?.items || tableResult.items.length === 0)
+            break;
+        for (const item of tableResult.items) {
+            if (item.object)
+                allFieldObjectIds.push(item.object);
+        }
+        if (!tableResult.hasNextPage || !tableResult.nextCursor)
+            break;
+        cursor = tableResult.nextCursor;
+    }
+    const nodeMap = new Map();
+    const edges = [];
+    if (allFieldObjectIds.length > 0) {
+        const BATCH = 50;
+        for (let i = 0; i < allFieldObjectIds.length; i += BATCH) {
+            const batch = allFieldObjectIds.slice(i, i + BATCH);
+            const nodeQueryResult = await query_objects({
+                objects: batch,
+                network,
+            });
+            for (const obj of nodeQueryResult?.objects ?? []) {
+                if (obj.type === "TableItem_MachineNode") {
+                    const nodeObj = obj;
+                    const nodeName = nodeObj.name;
+                    if (!nodeName)
+                        continue;
+                    if (!nodeMap.has(nodeName)) {
+                        nodeMap.set(nodeName, { name: nodeName, description: null });
+                    }
+                    const pairs = Array.isArray(nodeObj.value) ? nodeObj.value : [];
+                    for (const pair of pairs) {
+                        if (!pair || typeof pair !== "object")
+                            continue;
+                        const from = typeof pair.prev_node === "string" ? pair.prev_node : "";
+                        const to = nodeName;
+                        const threshold = typeof pair.threshold === "number" ? pair.threshold : 1;
+                        const forwardsRaw = Array.isArray(pair.forwards) ? pair.forwards : [];
+                        const forwards = forwardsRaw.map((f) => ({
+                            name: f.name ?? "",
+                            weight: f.weight ?? 1,
+                            named_operator: f.namedOperator ?? null,
+                            permission_index: f.permissionIndex ?? null,
+                            guard: f.guard?.guard ?? f.guard ?? null,
+                            retained_submission: f.retained_submission ?? null,
+                        }));
+                        edges.push({ from, to, threshold, forwards });
+                    }
+                }
+            }
+        }
+    }
+    for (const edge of edges) {
+        if (!nodeMap.has(edge.from))
+            nodeMap.set(edge.from, { name: edge.from, description: null });
+        if (!nodeMap.has(edge.to))
+            nodeMap.set(edge.to, { name: edge.to, description: null });
+    }
+    return { nodes: Array.from(nodeMap.values()), edges };
+}
+async function fetchCurrentGuard(guardAddress, network) {
+    const queryResult = await query_objects({
+        objects: [guardAddress],
+        network,
+    });
+    const guardData = queryResult?.objects?.[0] ?? null;
+    if (!guardData) {
+        throw new Error(`Guard ${guardAddress} not found on ${network}`);
+    }
+    const root = guardData.root ?? guardData.data?.root ?? null;
+    const table = guardData.table ?? guardData.data?.table ?? [];
+    const relies = guardData.relies ?? guardData.data?.relies ?? null;
+    const reliesLogicAnd = guardData.relies_logic_and ?? guardData.data?.relies_logic_and ?? null;
+    let rely = null;
+    if (Array.isArray(relies) && relies.length > 0) {
+        rely = {
+            guards: relies,
+            logic_or: typeof reliesLogicAnd === "boolean" ? !reliesLogicAnd : undefined,
+        };
+    }
+    return {
+        root: root,
+        table: Array.isArray(table) ? table.map((t) => ({
+            identifier: t.identifier,
+            name: t.name,
+            value_type: t.value_type,
+            b_submission: t.b_submission,
+            value: t.value,
+        })) : [],
+        rely,
+    };
+}
+function parsePatchOperation(opStr) {
+    const parts = opStr.trim().split(/\s+/);
+    if (parts.length < 2)
+        return null;
+    const [cmd, subcmd, ...rest] = parts;
+    if (cmd === "add" && subcmd === "node" && rest.length >= 1) {
+        return { type: "add_node", args: rest, raw: opStr };
+    }
+    if (cmd === "remove" && subcmd === "node" && rest.length >= 1) {
+        return { type: "remove_node", args: rest, raw: opStr };
+    }
+    if (cmd === "add" && subcmd === "edge" && rest.length >= 2) {
+        return { type: "add_edge", args: rest, raw: opStr };
+    }
+    if (cmd === "remove" && subcmd === "edge" && rest.length >= 2) {
+        return { type: "remove_edge", args: rest, raw: opStr };
+    }
+    if (cmd === "add" && subcmd === "forward" && rest.length >= 3) {
+        return { type: "add_forward", args: rest, raw: opStr };
+    }
+    if (cmd === "remove" && subcmd === "forward" && rest.length >= 3) {
+        return { type: "remove_forward", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "threshold" && rest.length >= 3) {
+        return { type: "set_threshold", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "guard" && rest.length >= 4) {
+        return { type: "set_guard", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "permission" && rest.length >= 4) {
+        return { type: "set_permission", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "operator" && rest.length >= 4) {
+        return { type: "set_operator", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "weight" && rest.length >= 4) {
+        return { type: "set_weight", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "retained_submission" && rest.length >= 4) {
+        return { type: "set_retained_submission", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "description" && rest.length >= 2) {
+        return { type: "set_description", args: rest, raw: opStr };
+    }
+    return null;
+}
+function applyPatchOperation(op, nodes, edges) {
+    switch (op.type) {
+        case "add_node": {
+            const name = op.args[0];
+            if (nodes.some(n => n.name === name)) {
+                return { success: false, error: `Node '${name}' already exists` };
+            }
+            nodes.push({ name, description: null });
+            return { success: true };
+        }
+        case "remove_node": {
+            const name = op.args[0];
+            const idx = nodes.findIndex(n => n.name === name);
+            if (idx === -1) {
+                return { success: false, error: `Node '${name}' not found` };
+            }
+            const hasEdges = edges.some(e => e.from === name || e.to === name);
+            if (hasEdges) {
+                return { success: false, error: `Node '${name}' has edges — remove them first` };
+            }
+            nodes.splice(idx, 1);
+            return { success: true };
+        }
+        case "add_edge": {
+            const [from, to] = op.args;
+            if (!nodes.some(n => n.name === to)) {
+                return { success: false, error: `Target node '${to}' not found` };
+            }
+            if (from !== "" && !nodes.some(n => n.name === from)) {
+                return { success: false, error: `Source node '${from}' not found` };
+            }
+            if (edges.some(e => e.from === from && e.to === to)) {
+                return { success: false, error: `Edge '${from}->${to}' already exists` };
+            }
+            edges.push({ from, to, threshold: 1, forwards: [] });
+            return { success: true };
+        }
+        case "remove_edge": {
+            const [from, to] = op.args;
+            const idx = edges.findIndex(e => e.from === from && e.to === to);
+            if (idx === -1) {
+                return { success: false, error: `Edge '${from}->${to}' not found` };
+            }
+            edges.splice(idx, 1);
+            return { success: true };
+        }
+        case "add_forward": {
+            const [from, to, fwdName] = op.args;
+            const edge = edges.find(e => e.from === from && e.to === to);
+            if (!edge) {
+                return { success: false, error: `Edge '${from}->${to}' not found` };
+            }
+            if (edge.forwards.some(f => f.name === fwdName)) {
+                return { success: false, error: `Forward '${fwdName}' already exists on edge '${from}->${to}'` };
+            }
+            edge.forwards.push({
+                name: fwdName,
+                weight: 1,
+                named_operator: null,
+                permission_index: null,
+                guard: null,
+                retained_submission: null,
+            });
+            return { success: true };
+        }
+        case "remove_forward": {
+            const [from, to, fwdName] = op.args;
+            const edge = edges.find(e => e.from === from && e.to === to);
+            if (!edge) {
+                return { success: false, error: `Edge '${from}->${to}' not found` };
+            }
+            const idx = edge.forwards.findIndex(f => f.name === fwdName);
+            if (idx === -1) {
+                return { success: false, error: `Forward '${fwdName}' not found on edge '${from}->${to}'` };
+            }
+            edge.forwards.splice(idx, 1);
+            return { success: true };
+        }
+        case "set_threshold": {
+            const [from, to, valStr] = op.args;
+            const val = parseInt(valStr, 10);
+            if (isNaN(val) || val < 1) {
+                return { success: false, error: `Invalid threshold value: ${valStr}` };
+            }
+            const edge = edges.find(e => e.from === from && e.to === to);
+            if (!edge) {
+                return { success: false, error: `Edge '${from}->${to}' not found` };
+            }
+            edge.threshold = val;
+            return { success: true };
+        }
+        case "set_guard": {
+            const [from, to, fwdName, guardAddr] = op.args;
+            const edge = edges.find(e => e.from === from && e.to === to);
+            if (!edge) {
+                return { success: false, error: `Edge '${from}->${to}' not found` };
+            }
+            const fwd = edge.forwards.find(f => f.name === fwdName);
+            if (!fwd) {
+                return { success: false, error: `Forward '${fwdName}' not found on edge '${from}->${to}'` };
+            }
+            fwd.guard = guardAddr === "none" ? null : guardAddr;
+            return { success: true };
+        }
+        case "set_permission": {
+            const [from, to, fwdName, permStr] = op.args;
+            const edge = edges.find(e => e.from === from && e.to === to);
+            if (!edge) {
+                return { success: false, error: `Edge '${from}->${to}' not found` };
+            }
+            const fwd = edge.forwards.find(f => f.name === fwdName);
+            if (!fwd) {
+                return { success: false, error: `Forward '${fwdName}' not found on edge '${from}->${to}'` };
+            }
+            const perm = parseInt(permStr, 10);
+            if (isNaN(perm) || perm < 0) {
+                return { success: false, error: `Invalid permission index: ${permStr} (must be a non-negative integer)` };
+            }
+            fwd.permission_index = perm;
+            return { success: true };
+        }
+        case "set_operator": {
+            const [from, to, fwdName, ...opRest] = op.args;
+            const namedOperator = opRest.join(" ");
+            const edge = edges.find(e => e.from === from && e.to === to);
+            if (!edge) {
+                return { success: false, error: `Edge '${from}->${to}' not found` };
+            }
+            const fwd = edge.forwards.find(f => f.name === fwdName);
+            if (!fwd) {
+                return { success: false, error: `Forward '${fwdName}' not found on edge '${from}->${to}'` };
+            }
+            if (namedOperator === "none") {
+                fwd.named_operator = null;
+            }
+            else {
+                fwd.named_operator = namedOperator;
+            }
+            return { success: true };
+        }
+        case "set_weight": {
+            const [from, to, fwdName, weightStr] = op.args;
+            const edge = edges.find(e => e.from === from && e.to === to);
+            if (!edge) {
+                return { success: false, error: `Edge '${from}->${to}' not found` };
+            }
+            const fwd = edge.forwards.find(f => f.name === fwdName);
+            if (!fwd) {
+                return { success: false, error: `Forward '${fwdName}' not found on edge '${from}->${to}'` };
+            }
+            const weight = parseInt(weightStr, 10);
+            if (isNaN(weight) || weight < 1) {
+                return { success: false, error: `Invalid weight: ${weightStr} (must be a positive integer)` };
+            }
+            fwd.weight = weight;
+            return { success: true };
+        }
+        case "set_retained_submission": {
+            const [from, to, fwdName, indicesStr] = op.args;
+            const edge = edges.find(e => e.from === from && e.to === to);
+            if (!edge) {
+                return { success: false, error: `Edge '${from}->${to}' not found` };
+            }
+            const fwd = edge.forwards.find(f => f.name === fwdName);
+            if (!fwd) {
+                return { success: false, error: `Forward '${fwdName}' not found on edge '${from}->${to}'` };
+            }
+            if (indicesStr === "none") {
+                fwd.retained_submission = null;
+                return { success: true };
+            }
+            const indices = indicesStr.split(",").map(s => {
+                const n = parseInt(s.trim(), 10);
+                if (isNaN(n) || n < 0)
+                    return -1;
+                return n;
+            });
+            if (indices.some(n => n < 0)) {
+                return { success: false, error: `Invalid retained_submission indices: ${indicesStr} (must be comma-separated non-negative integers or 'none')` };
+            }
+            fwd.retained_submission = indices;
+            return { success: true };
+        }
+        case "set_description": {
+            const [nodeName, ...descParts] = op.args;
+            const node = nodes.find(n => n.name === nodeName);
+            if (!node) {
+                return { success: false, error: `Node '${nodeName}' not found` };
+            }
+            const desc = descParts.join(" ");
+            node.description = desc === "none" ? null : desc;
+            return { success: true };
+        }
+        default:
+            return { success: false, error: `Unknown operation type: ${op.type}` };
+    }
+}
+export async function handlePatchMachineNodes(v) {
+    const projectId = await resolveProjectId(v);
+    const machineAddress = await resolveObjectAddress(v);
+    const operations = v.patch_operations ?? [];
+    if (operations.length === 0) {
+        throw new Error("'patch_operations' is required for patch_machine_nodes (non-empty array)");
+    }
+    const project = await localProject.getProject(projectId);
+    if (!project)
+        throw new Error(`Project not found (id: ${projectId})`);
+    let machineName = null;
+    try {
+        const mark = await LocalMark.Instance().get(machineAddress);
+        machineName = mark?.name ?? null;
+    }
+    catch {
+    }
+    const network = (project.network ?? "testnet");
+    const current = await fetchCurrentMachine(machineAddress, network);
+    const oldNodes = current.nodes.map(n => ({ ...n }));
+    const oldEdges = current.edges.map(e => ({
+        ...e,
+        forwards: e.forwards.map(f => ({ ...f })),
+    }));
+    const operationsFailed = [];
+    let operationsApplied = 0;
+    for (const opStr of operations) {
+        const op = parsePatchOperation(opStr);
+        if (!op) {
+            operationsFailed.push({
+                operation: opStr,
+                error: "Invalid operation format. See patch_operations schema for supported formats.",
+            });
+            continue;
+        }
+        const result = applyPatchOperation(op, current.nodes, current.edges);
+        if (result.success) {
+            operationsApplied++;
+        }
+        else {
+            operationsFailed.push({
+                operation: opStr,
+                error: result.error ?? "Unknown error",
+            });
+        }
+    }
+    const diff = diffMachine(oldNodes, oldEdges, current.nodes, current.edges);
+    const validation = validateMachine(current.nodes, current.edges);
+    const blocking_errors = [];
+    for (const fail of operationsFailed) {
+        blocking_errors.push({
+            id: "E-OP",
+            description: `Operation '${fail.operation}' failed: ${fail.error}`,
+            impact: "This operation was not applied. The patch cannot be executed on-chain until all operations succeed.",
+        });
+    }
+    for (const be of validation.blocking_errors) {
+        blocking_errors.push(be);
+    }
+    const canApply = blocking_errors.length === 0;
+    const preparedCall = canApply
+        ? prepareMachineCall(machineName, machineAddress, current.nodes, current.edges)
+        : null;
+    const summary = `Patch: ${operationsApplied} applied, ${operationsFailed.length} failed. ${diff.summary}.`;
+    return {
+        action: "patch_machine_nodes",
+        machine_address: machineAddress,
+        machine_name: machineName,
+        operations_applied: operationsApplied,
+        operations_failed: operationsFailed,
+        patched_nodes: current.nodes,
+        patched_edges: current.edges,
+        diff,
+        warnings: validation.warnings,
+        blocking_errors: blocking_errors.length > 0 ? blocking_errors : [],
+        can_apply: canApply,
+        prepared_call: preparedCall,
+        summary,
+    };
+}
+function parseGuardPatchOperation(opStr) {
+    const parts = opStr.trim().split(/\s+/);
+    if (parts.length < 2)
+        return null;
+    const [cmd, subcmd, ...rest] = parts;
+    if (cmd === "add" && subcmd === "table" && rest.length >= 4) {
+        return { type: "add_table", args: rest, raw: opStr };
+    }
+    if (cmd === "remove" && subcmd === "table" && rest.length >= 1) {
+        return { type: "remove_table", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "table_value" && rest.length >= 2) {
+        return { type: "set_table_value", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "table_name" && rest.length >= 2) {
+        return { type: "set_table_name", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "table_submission" && rest.length >= 2) {
+        return { type: "set_table_submission", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "root" && rest.length >= 1) {
+        return { type: "set_root", args: rest, raw: opStr };
+    }
+    if (cmd === "set" && subcmd === "rely" && rest.length >= 1) {
+        return { type: "set_rely", args: rest, raw: opStr };
+    }
+    return null;
+}
+function tryParseJSON(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return undefined;
+    }
+}
+function applyGuardPatchOperation(op, context) {
+    switch (op.type) {
+        case "add_table": {
+            const [idStr, name, valueTypeStr, bSubStr, ...valueParts] = op.args;
+            const identifier = parseInt(idStr, 10);
+            if (isNaN(identifier) || identifier < 0) {
+                return { success: false, error: `Invalid table identifier: ${idStr} (must be a non-negative integer)` };
+            }
+            if (context.table.some(t => t.identifier === identifier)) {
+                return { success: false, error: `Table identifier ${identifier} already exists` };
+            }
+            const b_submission = bSubStr === "true";
+            const value_type = /^[0-9]+$/.test(valueTypeStr)
+                ? parseInt(valueTypeStr, 10)
+                : valueTypeStr;
+            let value = undefined;
+            if (valueParts.length > 0) {
+                const valueStr = valueParts.join(" ");
+                if (valueStr !== "none") {
+                    value = tryParseJSON(valueStr);
+                    if (value === undefined) {
+                        value = valueStr;
+                    }
+                }
+            }
+            context.table.push({
+                identifier,
+                name: name === "none" ? undefined : name,
+                value_type,
+                b_submission,
+                value,
+            });
+            return { success: true };
+        }
+        case "remove_table": {
+            const [idStr] = op.args;
+            const identifier = parseInt(idStr, 10);
+            if (isNaN(identifier)) {
+                return { success: false, error: `Invalid table identifier: ${idStr}` };
+            }
+            const idx = context.table.findIndex(t => t.identifier === identifier);
+            if (idx === -1) {
+                return { success: false, error: `Table identifier ${identifier} not found` };
+            }
+            context.table.splice(idx, 1);
+            return { success: true };
+        }
+        case "set_table_value": {
+            const [idStr, ...valueParts] = op.args;
+            const identifier = parseInt(idStr, 10);
+            if (isNaN(identifier)) {
+                return { success: false, error: `Invalid table identifier: ${idStr}` };
+            }
+            const entry = context.table.find(t => t.identifier === identifier);
+            if (!entry) {
+                return { success: false, error: `Table identifier ${identifier} not found` };
+            }
+            const valueStr = valueParts.join(" ");
+            if (valueStr === "none") {
+                entry.value = undefined;
+            }
+            else {
+                const parsed = tryParseJSON(valueStr);
+                entry.value = parsed !== undefined ? parsed : valueStr;
+            }
+            return { success: true };
+        }
+        case "set_table_name": {
+            const [idStr, name, ...rest] = op.args;
+            const identifier = parseInt(idStr, 10);
+            if (isNaN(identifier)) {
+                return { success: false, error: `Invalid table identifier: ${idStr}` };
+            }
+            const entry = context.table.find(t => t.identifier === identifier);
+            if (!entry) {
+                return { success: false, error: `Table identifier ${identifier} not found` };
+            }
+            const fullName = rest.length > 0 ? [name, ...rest].join(" ") : name;
+            entry.name = fullName === "none" ? undefined : fullName;
+            return { success: true };
+        }
+        case "set_table_submission": {
+            const [idStr, bSubStr] = op.args;
+            const identifier = parseInt(idStr, 10);
+            if (isNaN(identifier)) {
+                return { success: false, error: `Invalid table identifier: ${idStr}` };
+            }
+            const entry = context.table.find(t => t.identifier === identifier);
+            if (!entry) {
+                return { success: false, error: `Table identifier ${identifier} not found` };
+            }
+            if (bSubStr !== "true" && bSubStr !== "false") {
+                return { success: false, error: `Invalid b_submission value: ${bSubStr} (must be 'true' or 'false')` };
+            }
+            entry.b_submission = bSubStr === "true";
+            return { success: true };
+        }
+        case "set_root": {
+            const jsonStr = op.args.join(" ");
+            const newRoot = tryParseJSON(jsonStr);
+            if (newRoot === undefined || typeof newRoot !== "object" || newRoot === null) {
+                return { success: false, error: `Invalid root JSON: '${jsonStr.slice(0, 80)}' (must be a valid JSON object)` };
+            }
+            if (typeof newRoot.type !== "string") {
+                return { success: false, error: `Root JSON must have a 'type' field (string). Got: ${JSON.stringify(Object.keys(newRoot)).slice(0, 80)}` };
+            }
+            return { success: true, newRoot: newRoot };
+        }
+        case "set_rely": {
+            const [relyStr] = op.args;
+            if (relyStr === "none") {
+                context.rely = null;
+                return { success: true };
+            }
+            const guards = relyStr.split(",").map(s => s.trim()).filter(s => s.length > 0);
+            if (guards.length === 0) {
+                return { success: false, error: `Invalid rely value: '${relyStr}' (expected 'none' or comma-separated addresses)` };
+            }
+            context.rely = {
+                guards,
+                logic_or: context.rely?.logic_or ?? false,
+            };
+            return { success: true };
+        }
+        default:
+            return { success: false, error: `Unknown Guard patch operation type: ${op.type}` };
+    }
+}
+export async function handlePatchGuardTree(v) {
+    const projectId = await resolveProjectId(v);
+    const guardAddress = await resolveObjectAddress(v);
+    const operations = v.patch_operations ?? [];
+    if (operations.length === 0) {
+        throw new Error("'patch_operations' is required for patch_guard_tree (non-empty array)");
+    }
+    const project = await localProject.getProject(projectId);
+    if (!project)
+        throw new Error(`Project not found (id: ${projectId})`);
+    let guardName = null;
+    try {
+        const mark = await LocalMark.Instance().get(guardAddress);
+        guardName = mark?.name ?? null;
+    }
+    catch {
+    }
+    const network = (project.network ?? "testnet");
+    const current = await fetchCurrentGuard(guardAddress, network);
+    const oldRoot = JSON.parse(JSON.stringify(current.root));
+    const oldTable = current.table.map(t => ({ ...t, value: t.value !== undefined ? JSON.parse(JSON.stringify(t.value)) : undefined }));
+    const oldRely = current.rely ? { ...current.rely, guards: [...current.rely.guards] } : null;
+    const operationsFailed = [];
+    let operationsApplied = 0;
+    let newRoot = current.root;
+    for (const opStr of operations) {
+        const op = parseGuardPatchOperation(opStr);
+        if (!op) {
+            operationsFailed.push({
+                operation: opStr,
+                error: "Invalid Guard patch operation format. See patch_operations schema for supported formats.",
+            });
+            continue;
+        }
+        const result = applyGuardPatchOperation(op, {
+            root: newRoot,
+            table: current.table,
+            rely: current.rely,
+        });
+        if (result.success) {
+            operationsApplied++;
+            if (result.newRoot) {
+                newRoot = result.newRoot;
+            }
+        }
+        else {
+            operationsFailed.push({
+                operation: opStr,
+                error: result.error ?? "Unknown error",
+            });
+        }
+    }
+    if (current.rely && Array.isArray(current.rely.guards)) {
+        const resolved = [];
+        for (const g of current.rely.guards) {
+            if (/^0x[0-9a-fA-F]{32,64}$/.test(g)) {
+                resolved.push(g);
+            }
+            else {
+                try {
+                    const mark = await LocalMark.Instance().get(g);
+                    if (mark?.address) {
+                        resolved.push(mark.address);
+                    }
+                    else {
+                        resolved.push(g);
+                    }
+                }
+                catch {
+                    resolved.push(g);
+                }
+            }
+        }
+        current.rely.guards = resolved;
+    }
+    const diff = diffGuard(oldRoot, newRoot, oldTable, current.table);
+    const validation = validateGuard(newRoot, current.table);
+    const blocking_errors = [];
+    for (const fail of operationsFailed) {
+        blocking_errors.push({
+            id: "E-OP",
+            description: `Operation '${fail.operation}' failed: ${fail.error}`,
+            impact: "This operation was not applied. The patch cannot be executed on-chain until all operations succeed.",
+        });
+    }
+    for (const be of validation.blocking_errors) {
+        blocking_errors.push(be);
+    }
+    const canApply = blocking_errors.length === 0;
+    const preparedCall = canApply
+        ? prepareGuardCall(guardName, guardAddress, newRoot, current.table, current.rely)
+        : null;
+    const summary = `Guard patch: ${operationsApplied} applied, ${operationsFailed.length} failed. ${diff.summary}.`;
+    return {
+        action: "patch_guard_tree",
+        guard_address: guardAddress,
+        guard_name: guardName,
+        operations_applied: operationsApplied,
+        operations_failed: operationsFailed,
+        patched_root: newRoot,
+        patched_table: current.table,
+        patched_rely: current.rely,
+        diff,
+        warnings: validation.warnings,
+        blocking_errors: blocking_errors.length > 0 ? blocking_errors : [],
+        can_apply: canApply,
+        prepared_call: preparedCall,
+        summary,
+    };
+}