@wowok/agent-mcp 2.6.0 → 2.6.3

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

@@ -1,4 +1,17 @@
 import type { GuardScene } from "./guard-ledger.js";
+export declare const GUARD_COGNITIVE_PRINCIPLES: readonly [{
+    readonly id: "P1";
+    readonly title: "Guard validation always precedes the operation";
+    readonly statement: string;
+    readonly code_evidence: string;
+    readonly legitimate_exception: string;
+    readonly scope: "Applies when a Guard queries state of the SAME object the operation mutates.";
+}, {
+    readonly id: "P2";
+    readonly title: "Guard is CREATE-only and immutable";
+    readonly statement: string;
+    readonly scope: "Applies to all Guard lifecycle decisions.";
+}];
 export type GuardStakeholder = "customer" | "provider" | "arbitrator" | "claimant" | "system";
 export type RiskLevel = "critical" | "high" | "medium" | "low";
 export type DataSourceClass = "type1_onchain_constant" | "type2_witness_derived" | "type3_submitted_object" | "type4_system_context" | "cross_type";

package/dist/knowledge/guard-risk.js

@@ -1,4 +1,24 @@
 import { GUARDQUERY } from "@wowok/wowok";
+export const GUARD_COGNITIVE_PRINCIPLES = [
+    {
+        id: "P1",
+        title: "Guard validation always precedes the operation",
+        statement: "Guard validation ALWAYS occurs BEFORE the operation it guards. " +
+            "A Guard must NOT depend on data that the current operation will modify.",
+        code_evidence: "progress.move next_with_passport_imp: result_for_guard (line 471) " +
+            "runs before session_accomplish (line 481) which sets self.current (line 443).",
+        legitimate_exception: "Querying progress.current of a DIFFERENT Progress object (cross-machine) " +
+            "is safe and reasonable — that progress is not modified by the current operation.",
+        scope: "Applies when a Guard queries state of the SAME object the operation mutates.",
+    },
+    {
+        id: "P2",
+        title: "Guard is CREATE-only and immutable",
+        statement: "After creation, Guard table/root/rely cannot be modified. " +
+            "To change logic, create a new Guard and rebind references.",
+        scope: "Applies to all Guard lifecycle decisions.",
+    },
+];
 function rootStr(ctx) {
     return JSON.stringify(ctx.root).toLowerCase();
 }
@@ -1681,6 +1701,43 @@ const RISK_RULES = [
             };
         },
     },
+    {
+        id: "R-X1-15",
+        data_source_class: "cross_type",
+        trigger: "Guard root contains a progress.current query (id=1253 or name='progress.current'); " +
+            "if bound to a forward of the SAME Progress object, the guard evaluates before state transition",
+        check: (ctx) => {
+            const queryIds = extractQueryIds(ctx.root);
+            if (!queryIds.includes(1253))
+                return null;
+            return {
+                id: "R-X1-15",
+                data_source_class: "cross_type",
+                level: "medium",
+                category: "logic_gap",
+                title: "Guard queries progress.current — verify it is NOT the same Progress object the hosting operation mutates",
+                description: "Cognitive Principle P1: Guard validation ALWAYS occurs BEFORE the operation. " +
+                    "This Guard contains a progress.current query. If this Guard is bound to a forward " +
+                    "of the SAME Progress object it queries, the Guard will see the PRE-transition value " +
+                    "(source node, not target node) and may always fail. " +
+                    "Querying a DIFFERENT Progress object (e.g. another Machine's progress) is a valid " +
+                    "and reasonable design pattern — the principle does not apply in that case. " +
+                    "Allocator-bound guards are also unaffected because allocation.alloc() runs AFTER " +
+                    "the state transition completes.",
+                affected_stakeholders: ["provider"],
+                scenario: "Forward guard checks progress.current == target_node of the same Progress — " +
+                    "always fails because guard runs before session_accomplish sets the new current node",
+                mitigation: "1) If this Guard queries the SAME Progress object the forward operates on: " +
+                    "remove the guard from the forward, bind it ONLY to the Allocator (which runs after transition); " +
+                    "OR change the check to verify the SOURCE node instead of the target node. " +
+                    "2) If this Guard queries a DIFFERENT Progress object (cross-machine): no action needed — " +
+                    "this is a legitimate pattern. " +
+                    "3) Refer to GUARD_COGNITIVE_PRINCIPLES P1 for the full principle and code evidence.",
+                evidence: `Root contains progress.current query (id=1253). ` +
+                    `Query IDs detected: [${queryIds.join(", ")}].`,
+            };
+        },
+    },
 ];
 function deriveStakeholders(sceneId) {
     switch (sceneId) {

package/dist/knowledge/guard-submission-prompt.d.ts

@@ -0,0 +1,31 @@
+export interface SubmissionFieldPrompt {
+    identifier: number;
+    name: string;
+    value_type: string;
+    required: boolean;
+    suggested_value?: string;
+    suggestion_reason?: string;
+    description: string;
+}
+export interface GuardSubmissionPrompt {
+    guard_address: string;
+    guard_name?: string;
+    operation: string;
+    required_fields: SubmissionFieldPrompt[];
+    context: string;
+    fill_example: string;
+}
+export interface SubmissionContext {
+    operation: string;
+    network?: string;
+    signer?: string;
+    progress_address?: string;
+    progress_current?: string;
+    order_address?: string;
+    service_address?: string;
+    machine_address?: string;
+    allocation_address?: string;
+    extra?: Record<string, string>;
+}
+export declare function generateGuardSubmissionPrompt(guardRef: string, ctx: SubmissionContext): Promise<GuardSubmissionPrompt | undefined>;
+export declare function formatSubmissionPrompt(prompt: GuardSubmissionPrompt): string;

package/dist/knowledge/guard-submission-prompt.js

@@ -0,0 +1,171 @@
+import { query_objects, LocalMark } from "@wowok/wowok";
+function inferValue(fieldName, valueType, ctx) {
+    const name = fieldName.toLowerCase();
+    if (name.includes("order") || name.includes("task")) {
+        if (ctx.order_address) {
+            return { value: ctx.order_address, reason: "Inferred from operation's order_address context" };
+        }
+        if (ctx.progress_address) {
+            return { value: ctx.progress_address, reason: "Progress.task is typically the order — query Progress to get the actual task address" };
+        }
+    }
+    if (name.includes("signer") || name.includes("sender") || name.includes("caller")) {
+        if (ctx.signer) {
+            return { value: ctx.signer, reason: "Inferred from env.account (the signing account)" };
+        }
+    }
+    if (name.includes("service")) {
+        if (ctx.service_address) {
+            return { value: ctx.service_address, reason: "Inferred from operation's service_address context" };
+        }
+    }
+    if (name.includes("machine")) {
+        if (ctx.machine_address) {
+            return { value: ctx.machine_address, reason: "Inferred from operation's machine_address context" };
+        }
+    }
+    if (name.includes("progress") || name.includes("node") || name.includes("current")) {
+        if (ctx.progress_current) {
+            return { value: ctx.progress_current, reason: "Inferred from Progress.current node name" };
+        }
+    }
+    if (name.includes("allocation") || name.includes("allocator")) {
+        if (ctx.allocation_address) {
+            return { value: ctx.allocation_address, reason: "Inferred from operation's allocation_address context" };
+        }
+    }
+    if (ctx.extra) {
+        for (const [key, val] of Object.entries(ctx.extra)) {
+            if (name.includes(key.toLowerCase())) {
+                return { value: val, reason: `Inferred from extra context: ${key}` };
+            }
+        }
+    }
+    return undefined;
+}
+function describeField(name, valueType) {
+    const n = name.toLowerCase();
+    if (n.includes("order"))
+        return `Order object address (type: ${valueType})`;
+    if (n.includes("signer") || n.includes("sender"))
+        return `Transaction signer address (type: ${valueType})`;
+    if (n.includes("service"))
+        return `Service object address (type: ${valueType})`;
+    if (n.includes("machine"))
+        return `Machine object address (type: ${valueType})`;
+    if (n.includes("progress"))
+        return `Progress object address (type: ${valueType})`;
+    if (n.includes("node") || n.includes("current"))
+        return `Current node name (type: ${valueType})`;
+    if (n.includes("amount") || n.includes("price") || n.includes("balance"))
+        return `Amount in smallest unit (type: ${valueType})`;
+    if (n.includes("allocation"))
+        return `Allocation object address (type: ${valueType})`;
+    return `Field "${name}" (type: ${valueType})`;
+}
+export async function generateGuardSubmissionPrompt(guardRef, ctx) {
+    let guardAddress = guardRef;
+    let guardName;
+    if (!guardRef.startsWith("0x")) {
+        try {
+            const mark = await LocalMark.Instance().get(guardRef);
+            if (mark?.address) {
+                guardAddress = mark.address;
+                guardName = guardRef;
+            }
+            else {
+                return undefined;
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    let guardObj;
+    try {
+        const result = await query_objects({
+            objects: [guardAddress],
+            network: ctx.network,
+        });
+        guardObj = result?.objects?.[0];
+    }
+    catch {
+        return undefined;
+    }
+    if (!guardObj)
+        return undefined;
+    const table = guardObj.table ?? guardObj.b_table ?? [];
+    if (!Array.isArray(table) || table.length === 0)
+        return undefined;
+    const submissionItems = table.filter((item) => item.b_submission === true);
+    if (submissionItems.length === 0)
+        return undefined;
+    const requiredFields = submissionItems.map((item) => {
+        const fieldName = item.name ?? `identifier_${item.identifier}`;
+        const valueType = typeof item.value_type === "number"
+            ? ValueTypeNames[item.value_type] ?? String(item.value_type)
+            : String(item.value_type);
+        const inferred = inferValue(fieldName, valueType, ctx);
+        return {
+            identifier: item.identifier,
+            name: fieldName,
+            value_type: valueType,
+            required: true,
+            suggested_value: inferred?.value,
+            suggestion_reason: inferred?.reason,
+            description: describeField(fieldName, valueType),
+        };
+    });
+    const fillLines = requiredFields.map((f) => {
+        const val = f.suggested_value ?? `<${f.value_type}_value>`;
+        return `      { identifier: ${f.identifier}, name: "${f.name}", value_type: "${f.value_type}", value: ${val} }`;
+    });
+    const fillExample = `submission: {
+    guard: "${guardName ?? guardAddress}",
+    submission: [
+${fillLines.join(",\n")}
+    ]
+  }`;
+    return {
+        guard_address: guardAddress,
+        guard_name: guardName,
+        operation: ctx.operation,
+        required_fields: requiredFields,
+        context: `Operation "${ctx.operation}" requires Guard "${guardName ?? guardAddress}" verification. ` +
+            `The Guard has ${requiredFields.length} field(s) that need submission data (b_submission=true). ` +
+            `Fill the submission with the required values and retry the operation using call_with_submission. ` +
+            `Each field has an identifier (number), name, and expected value_type. ` +
+            `The suggested_value (if provided) is inferred from the operation context — verify before using.`,
+        fill_example: fillExample,
+    };
+}
+export function formatSubmissionPrompt(prompt) {
+    const lines = [];
+    lines.push("GUARD SUBMISSION REQUIRED — operation cannot proceed without submission data.");
+    lines.push(`Guard: ${prompt.guard_name ?? prompt.guard_address} (${prompt.guard_address})`);
+    lines.push(`Operation: ${prompt.operation}`);
+    lines.push("");
+    lines.push("Required fields (fill these in the submission):");
+    for (const f of prompt.required_fields) {
+        lines.push(`  [${f.identifier}] ${f.name} (${f.value_type}) — ${f.description}`);
+        if (f.suggested_value) {
+            lines.push(`      Suggested: ${f.suggested_value} (${f.suggestion_reason})`);
+        }
+        else {
+            lines.push(`      No suggestion — derive value from context or ask user.`);
+        }
+    }
+    lines.push("");
+    lines.push("Fill example (use in the next call with submission):");
+    lines.push(prompt.fill_example);
+    return lines.join("\n");
+}
+const ValueTypeNames = {
+    0: "Bool",
+    1: "Address",
+    2: "U64",
+    3: "String",
+    4: "Vec",
+    5: "U256",
+    6: "Object",
+};

package/dist/knowledge/guard-templates.js

@@ -740,6 +740,284 @@ export const GUARD_TEMPLATES = [
         example_use_case: "Food delivery: if delivery delayed > 30min at node 'delayed' (history count=5), restaurant Treasury auto-compensates $5 to customer with PaymentInfo(for_object=order, for_guard=this, index=5, remark='delayed'). Customer submits Payment via Passport, guard verifies index matches current history count AND remark matches current node name.",
         verifier_constraint_level: "level3_scene_combined",
     },
+    {
+        id: "tpl_forward_content_subscription_deliver",
+        scene_id: "machine_forward_guard",
+        name: "Content subscription delivery verification (Substack-style)",
+        description: "Forward guard for content subscription delivery flow. Verifies that (1) the order is at the expected pre-delivery node " +
+            "(e.g. 'Ordered'), AND (2) the Signer holds the author's permission index on the bound Permission object. " +
+            "Prevents unauthorized parties from publishing content on behalf of the author. " +
+            "Designed for Substack-style content subscription: Paid → ContentPublished → Completed (success path), " +
+            "with Cancelled and Disputed branches using separate guards (tpl_forward_content_subscription_cancel, " +
+            "tpl_forward_content_subscription_refund).",
+        recommended_patterns: ["P06", "P09"],
+        parameters: [
+            {
+                name: "expected_pre_delivery_node",
+                type: "string",
+                description: "Expected current node name BEFORE delivery (e.g. 'Ordered')",
+                required: true,
+                default: "Ordered",
+                constraint: "Must exactly match the name defined in Machine nodes (case-sensitive). This is the node from which the 'Deliver' forward advances.",
+            },
+            {
+                name: "permission_object",
+                type: "address",
+                description: "Permission object address bound to the Machine (author role lives here)",
+                required: true,
+                constraint: "Must be the same Permission object bound to the Machine. Use name (not address) if Permission is not yet created.",
+            },
+            {
+                name: "author_permission_index",
+                type: "number",
+                description: "Permission index reserved for the author role (who can publish content)",
+                required: true,
+                default: "1000",
+                constraint: "Must match the index configured in the Permission object. Substack convention: 1000=author, 1500=arbitrator, reader uses namedOperator='' (no specific operator).",
+            },
+        ],
+        example_table: [
+            {
+                identifier: 0,
+                b_submission: true,
+                value_type: "Address",
+                object_type: "Order",
+                name: "Order object address (submitted by verifier at runtime)",
+                binding_constraint: "Must be an Order belonging to the bound Service; progress.current must match expected_pre_delivery_node",
+            },
+            {
+                identifier: 1,
+                b_submission: false,
+                value_type: "String",
+                value: "${expected_pre_delivery_node}",
+                name: "Expected pre-delivery node name (e.g. 'Ordered')",
+            },
+            {
+                identifier: 2,
+                b_submission: false,
+                value_type: "Address",
+                value: "${permission_object}",
+                name: "Permission object address (bound to Machine, holds author role)",
+            },
+            {
+                identifier: 3,
+                b_submission: false,
+                value_type: "U64",
+                value: "${author_permission_index}",
+                name: "Author permission index (e.g. 1000)",
+            },
+        ],
+        example_root: {
+            type: "logic_and",
+            nodes: [
+                {
+                    type: "logic_string_nocase_equal",
+                    nodes: [
+                        { type: "query", query: "progress.current", object: { identifier: 0, convert_witness: "OrderProgress" }, parameters: [] },
+                        { type: "identifier", identifier: 1 },
+                    ],
+                },
+                {
+                    type: "logic_equal",
+                    nodes: [
+                        { type: "context", context: "Signer" },
+                        {
+                            type: "query",
+                            query: "permission.permitted",
+                            object: { identifier: 2 },
+                            parameters: [{ type: "context", context: "Signer" }, { type: "identifier", identifier: 3 }],
+                        },
+                    ],
+                },
+            ],
+        },
+        applicable_industries: ["subscription", "content", "newsletter", "media"],
+        relevant_risks: ["R-C2-01", "R-C2-03", "R-X1-08"],
+        creation_notes: [
+            "VERIFIED QUERY NAMES: progress.current (id 1253, String) — current node name; permission.permitted (Permission object query, returns Address of permitted operator for the given index)",
+            "SUBSTACK DEPLOYMENT: this guard was used in Substack v2 Service. Original v1 Service was published without arbitrations — had to be recreated as v2 with arbitrations bound BEFORE publish (F-S-21).",
+            "AUTHOR ROLE: permission index 1000 = author (publish + cancel). namedOperator='' for reader role (open — any subscriber). Arbitrator uses index 1500.",
+            "FORWARD DESIGN: 'Deliver' forward advances from 'Ordered' → 'ContentPublished'. Threshold=1, weight=1, permissionIndex=1000 (author only).",
+            "GUARD-FIRST-WINS: when 'Ordered' has competing forwards (Deliver|Cancel|Dispute), each with its own guard, the first guard to verify wins. Subscribers cannot double-claim by triggering multiple forwards.",
+            "IMMUTABILITY: Forward.guard cannot be modified after Machine publish. Verify all 3 guards (deliver/cancel/refund) are correctly bound BEFORE publishing the Machine.",
+            "CIRCULAR REF: if Permission is not yet created, use its name (not address) in value field — Guard resolves names at evaluation time, not at creation time.",
+        ],
+        example_use_case: "Substack newsletter: subscriber pays $5/month. Author publishes content → 'Deliver' forward advances Ordered→ContentPublished. " +
+            "This guard verifies (1) order is at 'Ordered' node (not already delivered), AND (2) Signer holds permission index 1000 on author's Permission object. " +
+            "Prevents a malicious party from publishing fake content. Subscriber cannot trigger 'Deliver' (lacks permission).",
+        verifier_constraint_level: "level2_identity_set",
+    },
+    {
+        id: "tpl_forward_content_subscription_cancel",
+        scene_id: "machine_forward_guard",
+        name: "Content subscription cancel verification (Substack-style)",
+        description: "Forward guard for content subscription cancel flow. Verifies that (1) the order is at the expected pre-cancel node " +
+            "(e.g. 'Ordered'), AND (2) the Signer is the order owner (subscriber). Allows subscriber to cancel within grace period " +
+            "for full refund. Designed for Substack-style: Paid → Cancelled (terminal-cancel), with refund via Allocation template.",
+        recommended_patterns: ["P06", "P09"],
+        parameters: [
+            {
+                name: "expected_pre_cancel_node",
+                type: "string",
+                description: "Expected current node name BEFORE cancel (e.g. 'Ordered')",
+                required: true,
+                default: "Ordered",
+                constraint: "Must exactly match the name defined in Machine nodes (case-sensitive).",
+            },
+        ],
+        example_table: [
+            {
+                identifier: 0,
+                b_submission: true,
+                value_type: "Address",
+                object_type: "Order",
+                name: "Order object address (submitted by verifier at runtime)",
+            },
+            {
+                identifier: 1,
+                b_submission: false,
+                value_type: "String",
+                value: "${expected_pre_cancel_node}",
+                name: "Expected pre-cancel node name (e.g. 'Ordered')",
+            },
+        ],
+        example_root: {
+            type: "logic_and",
+            nodes: [
+                {
+                    type: "logic_string_nocase_equal",
+                    nodes: [
+                        { type: "query", query: "progress.current", object: { identifier: 0, convert_witness: "OrderProgress" }, parameters: [] },
+                        { type: "identifier", identifier: 1 },
+                    ],
+                },
+                {
+                    type: "logic_equal",
+                    nodes: [
+                        { type: "context", context: "Signer" },
+                        { type: "query", query: "order.owner", object: { identifier: 0 }, parameters: [] },
+                    ],
+                },
+            ],
+        },
+        applicable_industries: ["subscription", "content", "newsletter", "media"],
+        relevant_risks: ["R-C2-01", "R-C2-03"],
+        creation_notes: [
+            "VERIFIED QUERY NAMES: progress.current (id 1253, String); order.owner (id 1202, Address) — order holder (subscriber).",
+            "SUBSCRIBER-ONLY: only the order owner can cancel — prevents third-party griefing. Author cannot cancel on behalf of subscriber.",
+            "GRACE PERIOD: this guard does NOT enforce a time window. If a grace period is needed (e.g. cancel within 24h of payment), add a third condition: context(Clock) <= order.time + grace_period.",
+            "REFUND ALLOCATION: pair this guard with an Allocation template that refunds 100% to the subscriber (order.owner). Trigger node = 'Cancelled'.",
+            "GUARD-FIRST-WINS: when 'Ordered' has competing forwards (Deliver|Cancel|Dispute), each with its own guard, the first guard to verify wins.",
+        ],
+        example_use_case: "Substack newsletter: subscriber pays $5, then changes mind before content is published. 'Cancel' forward advances Ordered→Cancelled. " +
+            "This guard verifies (1) order is at 'Ordered' (not yet delivered), AND (2) Signer is the order owner. " +
+            "Author cannot cancel on behalf of subscriber. Refund triggers automatically via Allocation on 'Cancelled' node.",
+        verifier_constraint_level: "level2_identity_set",
+    },
+    {
+        id: "tpl_forward_content_subscription_refund",
+        scene_id: "machine_forward_guard",
+        name: "Content subscription refund verification (Substack-style, arbitration-triggered)",
+        description: "Forward guard for content subscription dispute/refund flow. Verifies that (1) the order is at the expected pre-dispute node " +
+            "(e.g. 'Disputed'), AND (2) the Signer holds the arbitrator's permission index on the bound Permission object. " +
+            "Only the arbitrator can advance Disputed→Refunded, ensuring dispute resolution is impartial. " +
+            "Designed for Substack-style: Paid → Disputed → Refunded (terminal-dispute).",
+        recommended_patterns: ["P06", "P09"],
+        parameters: [
+            {
+                name: "expected_pre_refund_node",
+                type: "string",
+                description: "Expected current node name BEFORE refund (e.g. 'Disputed')",
+                required: true,
+                default: "Disputed",
+                constraint: "Must exactly match the name defined in Machine nodes (case-sensitive).",
+            },
+            {
+                name: "permission_object",
+                type: "address",
+                description: "Permission object address bound to the Machine (arbitrator role lives here)",
+                required: true,
+                constraint: "Must be the same Permission object bound to the Machine. Use name (not address) if Permission is not yet created.",
+            },
+            {
+                name: "arbitrator_permission_index",
+                type: "number",
+                description: "Permission index reserved for the arbitrator role (who can resolve disputes)",
+                required: true,
+                default: "1500",
+                constraint: "Must match the index configured in the Permission object. Substack convention: 1000=author, 1500=arbitrator.",
+            },
+        ],
+        example_table: [
+            {
+                identifier: 0,
+                b_submission: true,
+                value_type: "Address",
+                object_type: "Order",
+                name: "Order object address (submitted by verifier at runtime)",
+            },
+            {
+                identifier: 1,
+                b_submission: false,
+                value_type: "String",
+                value: "${expected_pre_refund_node}",
+                name: "Expected pre-refund node name (e.g. 'Disputed')",
+            },
+            {
+                identifier: 2,
+                b_submission: false,
+                value_type: "Address",
+                value: "${permission_object}",
+                name: "Permission object address (bound to Machine, holds arbitrator role)",
+            },
+            {
+                identifier: 3,
+                b_submission: false,
+                value_type: "U64",
+                value: "${arbitrator_permission_index}",
+                name: "Arbitrator permission index (e.g. 1500)",
+            },
+        ],
+        example_root: {
+            type: "logic_and",
+            nodes: [
+                {
+                    type: "logic_string_nocase_equal",
+                    nodes: [
+                        { type: "query", query: "progress.current", object: { identifier: 0, convert_witness: "OrderProgress" }, parameters: [] },
+                        { type: "identifier", identifier: 1 },
+                    ],
+                },
+                {
+                    type: "logic_equal",
+                    nodes: [
+                        { type: "context", context: "Signer" },
+                        {
+                            type: "query",
+                            query: "permission.permitted",
+                            object: { identifier: 2 },
+                            parameters: [{ type: "context", context: "Signer" }, { type: "identifier", identifier: 3 }],
+                        },
+                    ],
+                },
+            ],
+        },
+        applicable_industries: ["subscription", "content", "newsletter", "media"],
+        relevant_risks: ["R-C2-01", "R-C2-03", "R-X1-08"],
+        creation_notes: [
+            "VERIFIED QUERY NAMES: progress.current (id 1253, String); permission.permitted (Permission object query, returns Address of permitted operator for the given index).",
+            "ARBITRATOR-ONLY: only the arbitrator (permission index 1500) can advance Disputed→Refunded. Neither author nor subscriber can self-resolve.",
+            "ARBITRATIONS BINDING: Service MUST have arbitrations bound BEFORE publish (F-S-21 — post-publish immutable). ConfirmGate C-S-19 + QS11 will warn if publish is attempted without arbitrations.",
+            "DISPUTE ENTRY: 'Dispute' forward (Ordered→Disputed) is triggered by subscriber (order.owner). After Disputed, only arbitrator can resolve.",
+            "REFUND ALLOCATION: pair this guard with an Allocation template that refunds 100% to the subscriber (order.owner). Trigger node = 'Refunded'.",
+            "GUARD-FIRST-WINS: when 'Disputed' has competing forwards (Resolve-Refund|Resolve-Reject), each with its own guard. First guard to verify wins.",
+        ],
+        example_use_case: "Substack newsletter: subscriber disputes content quality. Subscriber triggers 'Dispute' forward (Ordered→Disputed). " +
+            "Arbitrator reviews evidence and triggers 'Resolve-Refund' forward (Disputed→Refunded). " +
+            "This guard verifies (1) order is at 'Disputed' (dispute properly opened), AND (2) Signer holds arbitrator permission index 1500. " +
+            "Author cannot self-resolve. Subscriber cannot self-refund.",
+        verifier_constraint_level: "level2_identity_set",
+    },
 ];
 export function getTemplatesByScene(sceneId) {
     return GUARD_TEMPLATES.filter((t) => t.scene_id === sceneId);

package/dist/knowledge/machine-ledger.js

@@ -284,7 +284,7 @@ export function inferSceneFromFlow(description) {
     if (lower.includes("wonder") || lower.includes("praise") || lower.includes("complain")
         || lower.includes("thumbs_up") || lower.includes("thumbs_down")
         || lower.includes("rating") || lower.includes("feedback")
-        || lower.includes("好评") || lower.includes("差评")) {
+        || lower.includes("praise") || lower.includes("complaint")) {
         return findScene("wonder_feedback");
     }
     if (lower.includes("reward") || lower.includes("incentive")) {

package/dist/knowledge/machine-render.d.ts

@@ -0,0 +1,41 @@
+export interface MachineNodeForRender {
+    name: string;
+    description?: string | null;
+}
+export interface MachineForwardForRender {
+    name: string;
+    weight: number;
+    named_operator?: string | null;
+    permission_index?: number | null;
+    guard?: string | null;
+    retained_submission?: number[] | string | null;
+}
+export interface MachineEdgeForRender {
+    from: string;
+    to: string;
+    threshold: number;
+    forwards: MachineForwardForRender[];
+}
+export interface MachineRenderInput {
+    nodes: MachineNodeForRender[];
+    edges: MachineEdgeForRender[];
+    machineName?: string | null;
+    machineAddress?: string | null;
+    published?: boolean | null;
+    paused?: boolean | null;
+}
+export declare function sanitizeMermaidNodeId(name: string): string;
+export declare function renderMachineMermaid(nodes: MachineNodeForRender[], edges: MachineEdgeForRender[], options?: {
+    colored?: boolean;
+}): string;
+export declare function renderMachineTreeIndented(input: MachineRenderInput): string;
+export declare function parseMachineTreeIndented(text: string): {
+    success: boolean;
+    data?: {
+        nodes: MachineNodeForRender[];
+        edges: MachineEdgeForRender[];
+    };
+    errors: string[];
+};
+export declare function renderMachineAscii(input: MachineRenderInput): string;
+export declare function renderMachineMarkmap(input: MachineRenderInput): string;