@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/examples-scanner.js

@@ -0,0 +1,825 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { analyzeTopology, } from "./machine-topology.js";
+import { assessMachineRisks, } from "./machine-risk.js";
+import { runStaticChecklist, } from "./machine-confirm.js";
+import { explainNode, } from "./machine-translation.js";
+import { identifyCrossMachineDependency, detectCrossMachineCycle, } from "./machine-context.js";
+export function getMachineName(op) {
+    if (typeof op.data.object === 'string')
+        return op.data.object;
+    return op.data.object.name;
+}
+const EXAMPLES_DIR = path.resolve('d:/wowok/docs/examples');
+export function nodeDefsToMachine(nodeDefs) {
+    const nodes = [];
+    const pairs = [];
+    const seenNodeNames = new Set();
+    for (const nodeDef of nodeDefs) {
+        if (!seenNodeNames.has(nodeDef.name)) {
+            nodes.push({ name: nodeDef.name });
+            seenNodeNames.add(nodeDef.name);
+        }
+        for (const p of nodeDef.pairs) {
+            pairs.push({
+                prev_node: p.prev_node,
+                next_node: nodeDef.name,
+                threshold: p.threshold,
+                forwards: p.forwards.map((f) => normalizeForward(f)),
+            });
+        }
+    }
+    return { nodes, pairs };
+}
+function normalizeForward(f) {
+    const namedOp = f.named_operator ?? f.namedOperator;
+    const permIdx = f.permission_index ?? f.permissionIndex;
+    let guard;
+    if (typeof f.guard === 'string') {
+        guard = f.guard;
+    }
+    else if (f.guard && typeof f.guard === 'object') {
+        const g = f.guard;
+        if (typeof g.guard === 'string')
+            guard = g.guard;
+    }
+    let retained;
+    if (f.retained_submission !== undefined && f.retained_submission !== null) {
+        if (typeof f.retained_submission === 'string') {
+            retained = f.retained_submission;
+        }
+        else if (Array.isArray(f.retained_submission)) {
+            retained = f.retained_submission;
+        }
+        else if (typeof f.retained_submission === 'object') {
+            const r = f.retained_submission;
+            if (r.retained_submission !== undefined) {
+                retained = r.retained_submission;
+            }
+        }
+    }
+    else if (f.guard && typeof f.guard === 'object') {
+        const g = f.guard;
+        if (g.retained_submission !== undefined && g.retained_submission !== null) {
+            if (Array.isArray(g.retained_submission)) {
+                retained = g.retained_submission;
+            }
+            else if (typeof g.retained_submission === 'string') {
+                retained = g.retained_submission;
+            }
+        }
+    }
+    return {
+        name: f.name,
+        weight: f.weight,
+        named_operator: namedOp,
+        permission_index: permIdx,
+        guard,
+        retained_submission: retained,
+    };
+}
+function extractJsonBlocks(mdPath) {
+    const content = fs.readFileSync(mdPath, 'utf-8');
+    const lines = content.split('\n');
+    const blocks = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim().startsWith('```json')) {
+            const blockLines = [];
+            let j = i + 1;
+            while (j < lines.length && !lines[j].trim().startsWith('```')) {
+                blockLines.push(lines[j]);
+                j++;
+            }
+            const raw = blockLines.join('\n');
+            try {
+                const json = JSON.parse(raw);
+                if (json && typeof json === 'object' && 'operation_type' in json) {
+                    blocks.push({ lineStart: i + 1, raw, json: json });
+                }
+            }
+            catch {
+            }
+            i = j + 1;
+        }
+        else {
+            i++;
+        }
+    }
+    return blocks;
+}
+function extractDefinedGuardNames(mdPath) {
+    const blocks = extractJsonBlocks(mdPath);
+    const names = new Set();
+    for (const b of blocks) {
+        if (b.json.operation_type !== 'guard')
+            continue;
+        const data = b.json.data;
+        if (!data)
+            continue;
+        const namedNew = data.namedNew;
+        const name = namedNew?.name;
+        if (name)
+            names.add(name);
+    }
+    return names;
+}
+export function loadAllExamples(examplesDir = EXAMPLES_DIR) {
+    const result = [];
+    if (!fs.existsSync(examplesDir))
+        return result;
+    const entries = fs.readdirSync(examplesDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const subdir = path.join(examplesDir, entry.name);
+        const subEntries = fs.readdirSync(subdir, { withFileTypes: true });
+        for (const sub of subEntries) {
+            if (!sub.isFile())
+                continue;
+            const fullPath = path.join(subdir, sub.name);
+            const relativePath = `${entry.name}/${sub.name}`;
+            if (sub.name.endsWith('.md')) {
+                const machineOps = extractMachineOpsFromMarkdown(fullPath);
+                const progressOps = extractProgressOpsFromMarkdown(fullPath);
+                const definedGuards = extractDefinedGuardNames(fullPath);
+                if (machineOps.length === 0 && progressOps.length === 0 && definedGuards.size === 0)
+                    continue;
+                const businessDescription = machineOps[0]?.op.data.description;
+                result.push({
+                    example_name: entry.name,
+                    relative_path: relativePath,
+                    absolute_path: fullPath,
+                    machine_ops: machineOps,
+                    progress_ops: progressOps,
+                    defined_guard_names: definedGuards,
+                    business_description: businessDescription,
+                });
+            }
+            else if (sub.name.endsWith('.json') && sub.name.includes('machine')) {
+                const raw = fs.readFileSync(fullPath, 'utf-8');
+                try {
+                    const arr = JSON.parse(raw);
+                    if (!Array.isArray(arr) || arr.length === 0)
+                        continue;
+                    const machineName = path.basename(sub.name, '.json');
+                    result.push({
+                        example_name: entry.name,
+                        relative_path: relativePath,
+                        absolute_path: fullPath,
+                        machine_ops: [{
+                                op: {
+                                    operation_type: "machine",
+                                    data: {
+                                        object: { name: machineName, replaceExistName: false },
+                                        node: { op: "add", nodes: arr },
+                                        publish: false,
+                                    },
+                                    env: { network: "testnet" },
+                                },
+                                line_start: 0,
+                            }],
+                        progress_ops: [],
+                        defined_guard_names: new Set(),
+                        business_description: `(standalone JSON: ${machineName})`,
+                    });
+                }
+                catch {
+                }
+            }
+        }
+    }
+    return result;
+}
+function extractMachineOpsFromMarkdown(mdPath) {
+    const blocks = extractJsonBlocks(mdPath);
+    const result = [];
+    for (const b of blocks) {
+        if (b.json.operation_type !== 'machine')
+            continue;
+        try {
+            const op = b.json;
+            if (!op.data)
+                continue;
+            const hasNodes = op.data.node?.nodes && Array.isArray(op.data.node.nodes);
+            const hasPublish = op.data.publish === true;
+            if (!hasNodes && !hasPublish)
+                continue;
+            result.push({ op, line_start: b.lineStart });
+        }
+        catch {
+        }
+    }
+    return result;
+}
+function extractProgressOpsFromMarkdown(mdPath) {
+    const blocks = extractJsonBlocks(mdPath);
+    const result = [];
+    for (const b of blocks) {
+        const json = b.json;
+        const data = json.data;
+        if (!data)
+            continue;
+        const progress = data.progress;
+        if (!progress)
+            continue;
+        const operation = progress.operation;
+        if (!operation || !operation.next_node_name || !operation.forward)
+            continue;
+        try {
+            result.push({
+                operation_type: json.operation_type,
+                data: {
+                    object: data.object,
+                    progress: { operation: { next_node_name: operation.next_node_name, forward: operation.forward } },
+                    submission: data.submission,
+                },
+                env: { account: json.env?.account, network: json.env?.network },
+                _source_line: b.lineStart,
+            });
+        }
+        catch {
+        }
+    }
+    return result;
+}
+export function analyzeSchemaConsistency(_example) {
+    return [];
+}
+export function analyzeThresholdIssues(example) {
+    const findings = [];
+    for (const { op, line_start } of example.machine_ops) {
+        if (!op.data.node?.nodes)
+            continue;
+        const { nodes, pairs } = nodeDefsToMachine(op.data.node.nodes);
+        const machineName = getMachineName(op);
+        const entryPairs = pairs.filter((p) => p.prev_node === "");
+        const hasCompetingEntries = entryPairs.length > 1;
+        for (const pair of pairs) {
+            if (pair.prev_node === "" && pair.threshold === 0) {
+                const forwardCount = pair.forwards.length;
+                const isLegitimate = forwardCount === 1 ||
+                    hasCompetingEntries;
+                if (isLegitimate)
+                    continue;
+                findings.push({
+                    example: example.example_name,
+                    source_file: example.relative_path,
+                    line: line_start,
+                    machine_name: machineName,
+                    category: "design",
+                    severity: "medium",
+                    title: "Entry pair with threshold=0 and multiple Forwards (potential permission bypass)",
+                    detail: `Pair (prev="", next="${pair.next_node}") has threshold=0 with ${forwardCount} Forwards. ` +
+                        `With threshold=0, ANY single Forward fires → migration, potentially bypassing other Forwards' ` +
+                        `permission checks. Set threshold ≥ 1 so ALL intended Forwards must agree. ` +
+                        `(Note: single-Forward Pairs and competing-OR Pairs with threshold=0 are NOT flagged — they are legitimate.)`,
+                    rule_id: "R-M3-09",
+                    fix: `Set threshold=1 (or higher) on entry pair targeting "${pair.next_node}" if Forwards represent AND semantics; keep threshold=0 if OR semantics is intended (then consider splitting into competing Pairs).`,
+                });
+            }
+        }
+        for (const pair of pairs) {
+            const totalWeight = pair.forwards.reduce((sum, f) => sum + f.weight, 0);
+            if (pair.threshold > totalWeight) {
+                findings.push({
+                    example: example.example_name,
+                    source_file: example.relative_path,
+                    line: line_start,
+                    machine_name: machineName,
+                    category: "design",
+                    severity: "critical",
+                    title: "Threshold exceeds total forward weight (unreachable)",
+                    detail: `Pair (prev="${pair.prev_node}", next="${pair.next_node}") has threshold=${pair.threshold} but total forward weight=${totalWeight}. This pair can NEVER be satisfied — workflow dead-ends here.`,
+                    rule_id: "R-M2-06",
+                    fix: `Reduce threshold to ≤ ${totalWeight} or add more forwards with weight.`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+export function analyzeNetworkSafety(example) {
+    const findings = [];
+    for (const { op, line_start } of example.machine_ops) {
+        const machineName = getMachineName(op);
+        const isPublish = op.data.publish === true;
+        const network = op.env.network;
+        if (isPublish && network === "mainnet") {
+            findings.push({
+                example: example.example_name,
+                source_file: example.relative_path,
+                line: line_start,
+                machine_name: machineName,
+                category: "runtime",
+                severity: "critical",
+                title: "Direct mainnet publish without testnet test",
+                detail: `Machine "${machineName}" is published directly to mainnet. Per R-M4-02, must test on testnet first.`,
+                rule_id: "R-M4-02",
+                fix: `Set env.network to "testnet" for first publish, run end-to-end test, then re-publish on mainnet.`,
+            });
+        }
+    }
+    return findings;
+}
+export function analyzeConfirmationBypass(example) {
+    const findings = [];
+    for (const { op, line_start } of example.machine_ops) {
+        const machineName = getMachineName(op);
+        const isPublish = op.data.publish === true;
+        const confirmed = op.env.confirmed === true;
+        if (isPublish && confirmed) {
+            findings.push({
+                example: example.example_name,
+                source_file: example.relative_path,
+                line: line_start,
+                machine_name: machineName,
+                category: "runtime",
+                severity: "medium",
+                title: "confirmed=true bypasses user confirmation prompt",
+                detail: `Machine "${machineName}" is published with env.confirmed=true. This bypasses the ConfirmGate user-confirmation step. Examples should demonstrate the two-step confirmation flow (Phase 1 prompt → Phase 2 confirmed=true).`,
+                rule_id: "R-M4-04",
+                fix: `Show Phase 1 (without confirmed=true) and Phase 2 (with confirmed=true) as separate steps in the example.`,
+            });
+        }
+    }
+    return findings;
+}
+export function analyzeGuardReferences(example) {
+    const findings = [];
+    const defined = example.defined_guard_names;
+    for (const { op, line_start } of example.machine_ops) {
+        if (!op.data.node?.nodes)
+            continue;
+        const machineName = getMachineName(op);
+        const isPublish = op.data.publish === true;
+        for (const nodeDef of op.data.node.nodes) {
+            for (const pair of nodeDef.pairs) {
+                for (const fwd of pair.forwards) {
+                    let guardName;
+                    if (typeof fwd.guard === 'string') {
+                        guardName = fwd.guard;
+                    }
+                    else if (fwd.guard && typeof fwd.guard === 'object') {
+                        const g = fwd.guard;
+                        if (typeof g.guard === 'string')
+                            guardName = g.guard;
+                    }
+                    if (!guardName)
+                        continue;
+                    if (!defined.has(guardName)) {
+                        findings.push({
+                            example: example.example_name,
+                            source_file: example.relative_path,
+                            line: line_start,
+                            machine_name: machineName,
+                            category: "runtime",
+                            severity: isPublish ? "critical" : "high",
+                            title: `Guard "${guardName}" referenced but not defined in example`,
+                            detail: `Forward "${fwd.name}" references Guard "${guardName}" but no operation_type="guard" with name="${guardName}" appears earlier in ${example.relative_path}. ${isPublish ? "Publishing will fail at runtime." : "Will fail at machine creation."}`,
+                            rule_id: isPublish ? "R-M4-03" : "R-M2-01",
+                            fix: `Add a guard creation step (operation_type="guard") with name="${guardName}" BEFORE the machine creation step.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return findings;
+}
+export function analyzeCrossMachineDeps(example, guardResolutions = new Map()) {
+    const findings = [];
+    const allDeps = [];
+    for (const { op, line_start } of example.machine_ops) {
+        if (!op.data.node?.nodes)
+            continue;
+        const { nodes, pairs } = nodeDefsToMachine(op.data.node.nodes);
+        const machineId = getMachineName(op);
+        const deps = identifyCrossMachineDependency(machineId, { nodes, pairs }, guardResolutions);
+        allDeps.push(...deps);
+        if (deps.length > 0) {
+            findings.push({
+                example: example.example_name,
+                source_file: example.relative_path,
+                line: line_start,
+                machine_name: machineId,
+                category: "cross_machine",
+                severity: "info",
+                title: `Machine declares ${deps.length} cross-Machine dependencies`,
+                detail: deps.map((d) => `Forward "${d.dependency.machine_a_forward}" depends on Machine "${d.machine_b_id}" reaching node "${d.dependency.machine_b_node}"`).join('; '),
+                rule_id: "P-M3",
+            });
+        }
+    }
+    const cycles = detectCrossMachineCycle(allDeps);
+    for (const cycle of cycles) {
+        findings.push({
+            example: example.example_name,
+            source_file: example.relative_path,
+            line: 0,
+            machine_name: "(project-level)",
+            category: "cross_machine",
+            severity: "critical",
+            title: "Cross-Machine dependency cycle detected",
+            detail: `Cycle: ${cycle.join(' → ')}`,
+            rule_id: "R-M2-07",
+            fix: `Break the cycle by removing one of the dependencies in the cycle.`,
+        });
+    }
+    return { deps: allDeps, cycles, findings };
+}
+export function analyzeRoundTrip(example) {
+    const findings = [];
+    for (const { op, line_start } of example.machine_ops) {
+        if (!op.data.node?.nodes)
+            continue;
+        const { nodes, pairs } = nodeDefsToMachine(op.data.node.nodes);
+        const machineName = getMachineName(op);
+        const topo = analyzeTopology(nodes, pairs);
+        if (topo.has_cycles) {
+            findings.push({
+                example: example.example_name,
+                source_file: example.relative_path,
+                line: line_start,
+                machine_name: machineName,
+                category: "round_trip",
+                severity: "critical",
+                title: "Topology analysis: cycle detected (DAG violation)",
+                detail: `Machine "${machineName}" has cycles: ${JSON.stringify(topo.cycle_nodes)}`,
+                rule_id: "R-M1-03",
+                fix: `Remove cycles — Machine must be a DAG.`,
+            });
+        }
+        const ctx = {
+            network: op.env.network === "mainnet" ? "mainnet" : "testnet",
+            testnet_test_passed: op.env.network !== "mainnet",
+            published_services: new Set(),
+            published_guards: new Set(),
+            published_permissions: new Set(),
+            published_machines: new Set(),
+            published_arbitrations: new Set(),
+            published_rewards: new Set(),
+            published_allocators: new Set(),
+            published_repositories: new Set(),
+        };
+        for (const pair of pairs) {
+            for (const fwd of pair.forwards) {
+                if (fwd.guard)
+                    ctx.published_guards.add(fwd.guard);
+            }
+        }
+        const machineJson = {
+            nodes,
+            pairs,
+            b_published: op.data.publish === true,
+        };
+        const assessment = assessMachineRisks(machineJson, ctx);
+        const criticalRisks = assessment.detected_risks.filter((r) => r.severity === "critical");
+        if (criticalRisks.length > 0) {
+            for (const r of criticalRisks) {
+                findings.push({
+                    example: example.example_name,
+                    source_file: example.relative_path,
+                    line: line_start,
+                    machine_name: machineName,
+                    category: "round_trip",
+                    severity: "critical",
+                    title: `Risk assessment: ${r.rule_id} (${r.severity})`,
+                    detail: r.detail,
+                    rule_id: r.rule_id,
+                });
+            }
+        }
+        const checklist = { nodes, pairs, name: machineName };
+        const checklistResult = runStaticChecklist(checklist);
+        const failedItems = checklistResult.failed_items.filter((i) => ["C-01", "C-03", "C-06", "C-10"].includes(i.id));
+        for (const item of failedItems) {
+            findings.push({
+                example: example.example_name,
+                source_file: example.relative_path,
+                line: line_start,
+                machine_name: machineName,
+                category: "round_trip",
+                severity: "high",
+                title: `Checklist ${item.id} failed: ${item.description}`,
+                detail: item.detail ?? `(no detail)`,
+                rule_id: item.id,
+            });
+        }
+        for (const node of nodes) {
+            const outgoing = pairs.filter((p) => p.prev_node === node.name);
+            const nodeForExpl = {
+                name: node.name,
+                pairs: outgoing,
+                all_pairs: pairs,
+            };
+            const explained = explainNode(nodeForExpl);
+            if (!explained.name || explained.pairs.length !== outgoing.length) {
+                findings.push({
+                    example: example.example_name,
+                    source_file: example.relative_path,
+                    line: line_start,
+                    machine_name: machineName,
+                    category: "round_trip",
+                    severity: "medium",
+                    title: `Round-trip mismatch for node "${node.name}"`,
+                    detail: `explainNode produced inconsistent output: name="${explained.name}", pairs_count=${explained.pairs.length} (expected ${outgoing.length})`,
+                    rule_id: "RT-001",
+                });
+            }
+        }
+    }
+    return findings;
+}
+export function analyzeProgressOps(example) {
+    const findings = [];
+    const validForwardPairs = new Set();
+    let machineName = "(none)";
+    for (const { op } of example.machine_ops) {
+        if (!op.data.node?.nodes)
+            continue;
+        machineName = getMachineName(op);
+        const { pairs } = nodeDefsToMachine(op.data.node.nodes);
+        for (const pair of pairs) {
+            validForwardPairs.add(`${pair.next_node}::${pair.forwards.map((f) => f.name).join("|")}`);
+            for (const fwd of pair.forwards) {
+                validForwardPairs.add(`${pair.next_node}::${fwd.name}`);
+            }
+        }
+    }
+    for (const progressOp of example.progress_ops) {
+        const op = progressOp.data.progress?.operation;
+        if (!op)
+            continue;
+        const key = `${op.next_node_name}::${op.forward}`;
+        const valid = validForwardPairs.has(key);
+        if (!valid) {
+            const forwardExists = [...validForwardPairs].some((k) => k.endsWith(`::${op.forward}`));
+            if (!forwardExists) {
+                findings.push({
+                    example: example.example_name,
+                    source_file: example.relative_path,
+                    line: progressOp._source_line ?? 0,
+                    machine_name: machineName,
+                    category: "progress",
+                    severity: "high",
+                    title: `Progress references unknown forward "${op.forward}"`,
+                    detail: `Progress op references forward "${op.forward}" but no such forward exists in machine "${machineName}".`,
+                    rule_id: "R-M3-04",
+                    fix: `Verify forward name matches one defined in the Machine.`,
+                });
+            }
+            else {
+                findings.push({
+                    example: example.example_name,
+                    source_file: example.relative_path,
+                    line: progressOp._source_line ?? 0,
+                    machine_name: machineName,
+                    category: "progress",
+                    severity: "medium",
+                    title: `Progress forward "${op.forward}" doesn't lead to "${op.next_node_name}"`,
+                    detail: `Forward "${op.forward}" exists but doesn't target node "${op.next_node_name}".`,
+                    rule_id: "R-M3-05",
+                    fix: `Correct next_node_name to match the forward's target.`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+export function analyzePublishStep(example) {
+    const findings = [];
+    const hasPublish = example.machine_ops.some(({ op }) => op.data.publish === true);
+    const hasProgress = example.progress_ops.length > 0;
+    if (hasProgress && !hasPublish) {
+        findings.push({
+            example: example.example_name,
+            source_file: example.relative_path,
+            line: 0,
+            machine_name: "(file-level)",
+            category: "runtime",
+            severity: "high",
+            title: "Progress operations present but no `publish: true` step",
+            detail: `Example has ${example.progress_ops.length} progress operations but no machine operation with publish=true. Progress::new will fail at runtime (machine not published).`,
+            rule_id: "R-M4-01",
+            fix: `Add a publish step (or set data.publish=true on the machine creation operation).`,
+        });
+    }
+    return findings;
+}
+export function analyzeRiskRuleCoverage(example) {
+    const ruleCounts = new Map();
+    let totalFindings = 0;
+    const allFindings = [
+        ...analyzeSchemaConsistency(example),
+        ...analyzeThresholdIssues(example),
+        ...analyzeNetworkSafety(example),
+        ...analyzeConfirmationBypass(example),
+        ...analyzeGuardReferences(example),
+        ...analyzeRoundTrip(example),
+        ...analyzeProgressOps(example),
+        ...analyzePublishStep(example),
+    ];
+    for (const f of allFindings) {
+        if (f.rule_id) {
+            ruleCounts.set(f.rule_id, (ruleCounts.get(f.rule_id) ?? 0) + 1);
+            totalFindings++;
+        }
+    }
+    return { ruleCounts, totalFindings };
+}
+export function scanAllExamples(examplesDir = EXAMPLES_DIR) {
+    const examples = loadAllExamples(examplesDir);
+    const findingsByExample = new Map();
+    const findingsByCategory = new Map();
+    const findingsBySeverity = new Map();
+    const riskRuleCoverage = new Map();
+    let totalFindings = 0;
+    for (const example of examples) {
+        const exampleFindings = [];
+        exampleFindings.push(...analyzeSchemaConsistency(example));
+        exampleFindings.push(...analyzeThresholdIssues(example));
+        exampleFindings.push(...analyzeNetworkSafety(example));
+        exampleFindings.push(...analyzeConfirmationBypass(example));
+        exampleFindings.push(...analyzeGuardReferences(example));
+        const crossMachine = analyzeCrossMachineDeps(example);
+        exampleFindings.push(...crossMachine.findings);
+        exampleFindings.push(...analyzeRoundTrip(example));
+        exampleFindings.push(...analyzeProgressOps(example));
+        exampleFindings.push(...analyzePublishStep(example));
+        findingsByExample.set(example.relative_path, exampleFindings);
+        for (const f of exampleFindings) {
+            const catList = findingsByCategory.get(f.category) ?? [];
+            catList.push(f);
+            findingsByCategory.set(f.category, catList);
+            const sevList = findingsBySeverity.get(f.severity) ?? [];
+            sevList.push(f);
+            findingsBySeverity.set(f.severity, sevList);
+            if (f.rule_id) {
+                riskRuleCoverage.set(f.rule_id, (riskRuleCoverage.get(f.rule_id) ?? 0) + 1);
+            }
+            totalFindings++;
+        }
+    }
+    return {
+        examples,
+        findings_by_example: findingsByExample,
+        findings_by_category: findingsByCategory,
+        findings_by_severity: findingsBySeverity,
+        total_findings: totalFindings,
+        risk_rule_coverage: riskRuleCoverage,
+    };
+}
+export function formatScanReport(result) {
+    const lines = [];
+    lines.push('# Examples Scan Report — d:\\wowok\\docs\\examples');
+    lines.push('');
+    lines.push('> Auto-generated by `examples-scanner.ts` — comprehensive scan of all');
+    lines.push('> machine/progress JSON in 5 example directories for design and runtime problems.');
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`- **Examples scanned**: ${result.examples.length}`);
+    lines.push(`- **Total findings**: ${result.total_findings}`);
+    lines.push('');
+    lines.push('### Findings by Severity');
+    lines.push('');
+    lines.push('| Severity | Count |');
+    lines.push('|----------|-------|');
+    const sevOrder = ["critical", "high", "medium", "low", "info"];
+    for (const sev of sevOrder) {
+        const count = result.findings_by_severity.get(sev)?.length ?? 0;
+        lines.push(`| ${sev} | ${count} |`);
+    }
+    lines.push('');
+    lines.push('### Findings by Category');
+    lines.push('');
+    lines.push('| Category | Count |');
+    lines.push('|----------|-------|');
+    const catOrder = [
+        "schema_consistency", "design", "runtime",
+        "cross_machine", "round_trip", "progress", "risk_rule",
+    ];
+    for (const cat of catOrder) {
+        const count = result.findings_by_category.get(cat)?.length ?? 0;
+        lines.push(`| ${cat} | ${count} |`);
+    }
+    lines.push('');
+    lines.push('### Risk Rule Coverage (which rules fired across examples)');
+    lines.push('');
+    lines.push('| Rule ID | Total Hits |');
+    lines.push('|---------|-----------|');
+    const sortedRules = [...result.risk_rule_coverage.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+    for (const [ruleId, count] of sortedRules) {
+        lines.push(`| ${ruleId} | ${count} |`);
+    }
+    lines.push('');
+    lines.push('## Per-Example Findings');
+    lines.push('');
+    for (const example of result.examples) {
+        const findings = result.findings_by_example.get(example.relative_path) ?? [];
+        lines.push(`### ${example.example_name} — \`${example.relative_path}\``);
+        lines.push('');
+        lines.push(`- **Source**: \`${example.relative_path}\``);
+        lines.push(`- **Machine operations**: ${example.machine_ops.length}`);
+        lines.push(`- **Progress operations**: ${example.progress_ops.length}`);
+        lines.push(`- **Defined guards**: ${example.defined_guard_names.size}`);
+        if (example.business_description) {
+            lines.push(`- **Business description**: ${example.business_description}`);
+        }
+        lines.push(`- **Findings**: ${findings.length}`);
+        lines.push('');
+        if (findings.length === 0) {
+            lines.push('✅ No issues detected.');
+            lines.push('');
+            continue;
+        }
+        const bySev = new Map();
+        for (const f of findings) {
+            const list = bySev.get(f.severity) ?? [];
+            list.push(f);
+            bySev.set(f.severity, list);
+        }
+        for (const sev of sevOrder) {
+            const sevFindings = bySev.get(sev) ?? [];
+            if (sevFindings.length === 0)
+                continue;
+            lines.push(`#### ${sev.toUpperCase()} (${sevFindings.length})`);
+            lines.push('');
+            for (const f of sevFindings) {
+                lines.push(`- **[${f.rule_id ?? "—"}] ${f.title}** (line ${f.line})`);
+                lines.push(`  - ${f.detail}`);
+                if (f.fix) {
+                    lines.push(`  - **Fix**: ${f.fix}`);
+                }
+                lines.push('');
+            }
+        }
+    }
+    lines.push('## Cross-Cutting Patterns');
+    lines.push('');
+    const schemaFindings = result.findings_by_category.get("schema_consistency") ?? [];
+    if (schemaFindings.length === 0) {
+        lines.push('### Schema Consistency — No Issues (camelCase is canonical)');
+        lines.push('');
+        lines.push('The previous SCHEMA-001/002/003/004 rules have been REMOVED (2026-07-19).');
+        lines.push('');
+        lines.push('**Reason**: Verification against MCP schema (`d:\\wowok\\agent\\mcp\\src`) confirmed that:');
+        lines.push('- `MachineForwardSchema` accepts `namedOperator`, `permissionIndex` (camelCase)');
+        lines.push('- `MachineForwardGuardSchema` is an OBJECT `{ guard: string, retained_submission?: number[] }` (NOT a flat string)');
+        lines.push('- `NamedObjectSchema` accepts `replaceExistName`, `onChain` (camelCase)');
+        lines.push('');
+        lines.push('Source examples using camelCase are therefore CORRECT per MCP schema — the previous rules were false positives.');
+        lines.push('');
+    }
+    const thresholdFindings = (result.findings_by_category.get("design") ?? []).filter((f) => f.rule_id === "R-M3-09");
+    if (thresholdFindings.length > 0) {
+        lines.push('### Threshold=0 on Multi-Forward Entry Pairs (R-M3-09)');
+        lines.push('');
+        lines.push(`Found ${thresholdFindings.length} multi-Forward entry pairs with threshold=0 across examples.`);
+        lines.push('');
+        lines.push('**Detection logic** (refined 2026-07-19):');
+        lines.push('- Single-Forward Pair with threshold=0 → **NOT flagged** (legitimate: single execution triggers migration regardless of threshold)');
+        lines.push('- Competing-OR Pairs (multiple Pairs share prev_node="") with threshold=0 → **NOT flagged** (legitimate OR semantics)');
+        lines.push('- Multi-Forward Pair with threshold=0 AND no competing siblings → **FLAGGED** (potential permission bypass: any single Forward fires → migration)');
+        lines.push('');
+        const affectedFiles = [...new Set(thresholdFindings.map((f) => f.source_file))];
+        lines.push(`**Affected source files**: ${affectedFiles.map((p) => `\`${p}\``).join(', ')}.`);
+        lines.push('');
+        lines.push('**Fix**: Set threshold=1 (or higher) if Forwards represent AND semantics; keep threshold=0 only if OR semantics is intended (then consider splitting into competing Pairs).');
+        lines.push('');
+    }
+    else {
+        lines.push('### Threshold=0 on Entry Pairs — No Issues');
+        lines.push('');
+        lines.push('All entry pairs with threshold=0 fall into legitimate categories (single-Forward or competing-OR).');
+        lines.push('');
+    }
+    const mainnetFindings = (result.findings_by_category.get("runtime") ?? []).filter((f) => f.rule_id === "R-M4-02");
+    if (mainnetFindings.length > 0) {
+        lines.push('### Direct Mainnet Publish (R-M4-02)');
+        lines.push('');
+        lines.push(`Found ${mainnetFindings.length} examples publishing directly to mainnet without testnet test.`);
+        lines.push('');
+        lines.push('**Affected examples**: MyShop, MyShop_Advanced.');
+        lines.push('');
+        lines.push('**Fix**: Add a testnet publish step before mainnet, or change the network to testnet for examples.');
+        lines.push('');
+    }
+    lines.push('## Recommendations for Linter & Cognition Closure');
+    lines.push('');
+    lines.push('Based on the findings, the following linter rules and cognition improvements are recommended:');
+    lines.push('');
+    lines.push('1. **REMOVED SCHEMA-001/002/003/004** (2026-07-19): These rules incorrectly assumed SDK snake_case as the standard. MCP schema actually accepts camelCase (`namedOperator`, `permissionIndex`, `replaceExistName`) and nested Guard object form. Examples are correct as-is.');
+    lines.push('2. **REFACTORED R-M3-02 → R-M3-09** (2026-07-19, then 2026-07-20): Original R-M3-02 (threshold=0) conflicted with machine-risk.ts\'s R-M3-02 (permissionIndex out of bounds). Initially renamed to R-M3-06, but that also collided with machine-risk.ts\'s R-M3-06 (Permission game imbalance). Final rename: R-M3-09. Logic also refined: single-Forward and competing-OR threshold=0 cases are now exempt.');
+    lines.push('3. **Reinforce R-M4-03**: Guard must be created before Machine publish. Examples should include guard creation step (operation_type="guard") with matching name before machine creation.');
+    lines.push('4. **Add lint rule** for `confirmed: true` + `publish: true` combination without showing the Phase 1 confirmation prompt first.');
+    lines.push('5. **IMPLEMENTED**: R-M3-08 (permissionIndex < 1000) rule added to machine-risk.ts, and C-11 checklist item added to machine-confirm.ts (2026-07-20). Both enforce the on-chain USER_DEFINED_PERM_INDEX_START = 1000 hard constraint (see doc 06 §4.4).');
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push('*End of report.*');
+    return lines.join('\n');
+}
+export const EXAMPLES_SCANNER_VERSION = "1.0.0";