@wowok/agent-mcp 2.3.16 → 2.3.18

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

@@ -0,0 +1,60 @@
+import type { GuardScene } from "./guard-ledger.js";
+export type GuardStakeholder = "customer" | "provider" | "arbitrator" | "claimant" | "system";
+export type RiskLevel = "critical" | "high" | "medium" | "low" | "info";
+export type RiskCategory = "data_source_trust" | "submission_forgery" | "game_theory" | "logic_gap" | "binding_risk" | "dependency_risk";
+export interface GuardRisk {
+    id: string;
+    level: RiskLevel;
+    category: RiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: GuardStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+}
+export interface GuardRiskAssessment {
+    guard_summary: string;
+    scene?: GuardScene;
+    risks: GuardRisk[];
+    overall_risk: RiskLevel;
+    stakeholder_advice: Partial<Record<GuardStakeholder, string[]>>;
+    needs_human_review: boolean;
+}
+export interface RiskRule {
+    id: string;
+    trigger: string;
+    check: (ctx: RiskCheckContext) => GuardRisk | null;
+}
+export interface RiskCheckContext {
+    table: Array<{
+        identifier: number;
+        b_submission: boolean;
+        value_type: string;
+        value?: unknown;
+        name?: string;
+        object_type?: string;
+    }>;
+    root: any;
+    rely?: {
+        guards: string[];
+        logic_or?: boolean;
+    };
+    scene?: GuardScene;
+    operation_type?: string;
+}
+export declare function assessGuardRisks(params: {
+    table: RiskCheckContext["table"];
+    root: any;
+    rely?: RiskCheckContext["rely"];
+    scene?: GuardScene;
+    operation_type?: string;
+}): GuardRiskAssessment;
+export declare function assessGuardRisksForOperation(operation_type: string, data: any): GuardRiskAssessment | null;
+export declare function getRiskSummary(assessment: GuardRiskAssessment): {
+    risk_count: number;
+    critical_count: number;
+    high_count: number;
+    needs_human_review: boolean;
+    top_risks: string[];
+};

package/dist/knowledge/guard-risk.js

@@ -0,0 +1,474 @@
+const RISK_RULES = [
+    {
+        id: "R-DST-01",
+        trigger: "Guard 查询 Repository 数据但未验证写入者权限",
+        check: (ctx) => {
+            const rootStr = JSON.stringify(ctx.root).toLowerCase();
+            if (rootStr.includes('"query"') && rootStr.includes('repository')) {
+                const hasSignerCheck = rootStr.includes('"signer"') || rootStr.includes('"context"');
+                if (!hasSignerCheck) {
+                    return {
+                        id: "R-DST-01",
+                        level: "high",
+                        category: "data_source_trust",
+                        title: "Repository 数据源未验证写入者权限",
+                        description: "Guard 查询 Repository 数据，但未验证谁有权写入该 Repository。" +
+                            "恶意写入者可以操纵 Repository 数据来欺骗 Guard。",
+                        affected_stakeholders: ["customer", "provider"],
+                        scenario: "数据源操纵：攻击者写入虚假数据使 Guard 通过",
+                        mitigation: "1) 在 Repository write_guard 中限制写入者权限；" +
+                            "2) 在当前 Guard 中添加 context(Signer) 验证写入者身份；" +
+                            "3) 使用多点数据源交叉验证",
+                    };
+                }
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-DST-02",
+        trigger: "Guard 查询 Progress 状态但未验证 Machine 发布状态",
+        check: (ctx) => {
+            const rootStr = JSON.stringify(ctx.root).toLowerCase();
+            if (rootStr.includes('progress') && ctx.scene?.host_object === "Machine") {
+                return {
+                    id: "R-DST-02",
+                    level: "medium",
+                    category: "data_source_trust",
+                    title: "Progress 数据依赖 Machine 不可变性",
+                    description: "Guard 查询 Progress 状态。如果 Machine 未发布，Provider 可以修改 Machine 节点结构，" +
+                        "导致 Guard 验证的节点名失效或被重命名。",
+                    affected_stakeholders: ["customer"],
+                    scenario: "Provider 修改 Machine 节点名使 Guard 验证失效",
+                    mitigation: "1) 确保 Machine 已发布（bPublished=true）再绑定 Guard；" +
+                        "2) 在 Guard 中查询 Machine.bPublished 字段验证；" +
+                        "3) 使用节点 ID 而非节点名进行比较",
+                };
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-SF-01",
+        trigger: "Guard 依赖提交数据但未验证签名者身份（无 Signer 检查=high；有 Signer 检查=info 降级）",
+        check: (ctx) => {
+            const hasSubmission = ctx.table.some((e) => e.b_submission);
+            if (!hasSubmission)
+                return null;
+            if (ctx.scene?.binding_field === "voting_guard")
+                return null;
+            const rootStr = JSON.stringify(ctx.root);
+            const hasSignerCheck = rootStr.includes('"Signer"');
+            if (!hasSignerCheck) {
+                return {
+                    id: "R-SF-01",
+                    level: "high",
+                    category: "submission_forgery",
+                    title: "提交数据未与签名者身份绑定",
+                    description: "Guard 接受运行时提交数据，但未验证提交者是否为当前交易签名者。" +
+                        "攻击者可以提交他人的数据（如他人的地址、他人的凭证）来通过 Guard。",
+                    affected_stakeholders: ["customer", "provider"],
+                    scenario: "身份伪造：攻击者提交他人的地址冒充授权用户",
+                    mitigation: "1) 添加 context(Signer) 与提交数据绑定验证；" +
+                        "2) 使用 vec_contains_address 验证签名者在白名单中；" +
+                        "3) 使用 Passport 凭证替代裸地址提交",
+                };
+            }
+            return {
+                id: "R-SF-01",
+                level: "info",
+                category: "submission_forgery",
+                title: "提交数据已通过 context(Signer) 间接绑定（请确认绑定方向正确）",
+                description: "Guard 接受运行时提交数据，且 root 子树中包含 context(Signer) 检查，" +
+                    "提交数据与签名者形成间接绑定，伪造风险已降低。" +
+                    "但需人工确认：context(Signer) 比较的常量是正确角色（如 Provider 地址而非 Customer 地址），" +
+                    "且提交数据确实应由该签名者提供。",
+                affected_stakeholders: ["customer", "provider"],
+                scenario: "间接绑定待确认：Signer 检查方向与提交数据归属是否匹配",
+                mitigation: "1) 确认 context(Signer) 与正确的 table 常量比较（Provider 地址而非 Customer 地址）；" +
+                    "2) 确认提交数据的来源角色与 Signer 检查一致；" +
+                    "3) 如需更严格绑定，使用 query 验证提交者链上身份",
+            };
+        },
+    },
+    {
+        id: "R-SF-02",
+        trigger: "voting_guard 权重来自提交数据但未验证来源",
+        check: (ctx) => {
+            if (ctx.scene?.binding_field === "voting_guard") {
+                const numericEntries = ctx.table.filter((e) => e.b_submission && ["U8", "U16", "U32", "U64", "U128", "U256"].includes(e.value_type));
+                if (numericEntries.length > 0) {
+                    return {
+                        id: "R-SF-02",
+                        level: "critical",
+                        category: "submission_forgery",
+                        title: "投票权重来自用户提交，可能被伪造",
+                        description: "voting_guard 的权重数据来自 b_submission=true 的 table 条目。" +
+                            "如果未通过 EntityRegistrar 或其他可信来源验证权重，" +
+                            "投票者可以提交任意高权重操纵投票结果。",
+                        affected_stakeholders: ["arbitrator"],
+                        scenario: "权重伪造：投票者提交虚假高分操纵仲裁结果",
+                        mitigation: "1) 权重应从 EntityRegistrar 查询而非用户提交；" +
+                            "2) 使用 query(entity.records) 获取链上注册的声誉分；" +
+                            "3) 在 Guard 中验证提交权重与链上记录一致",
+                    };
+                }
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-GT-01",
+        trigger: "分账 Guard 可能导致某些参与者被跳过",
+        check: (ctx) => {
+            if (ctx.scene?.binding_field === "order_allocators") {
+                return {
+                    id: "R-GT-01",
+                    level: "medium",
+                    category: "game_theory",
+                    title: "order_allocators first-match-wins 可能导致分账不公",
+                    description: "order_allocators 采用 first-match-wins 策略：第一个 Guard 通过的 Allocator 执行分账。" +
+                        "如果顺序设计不当，某些参与者可能永远无法获得分账。" +
+                        "例如：如果第一个 Allocator 的 Guard 条件过宽，后续更精确的 Allocator 永远不会执行。",
+                    affected_stakeholders: ["provider"],
+                    scenario: "分账跳过：Provider 的分账 Allocator 被前面的宽泛条件跳过",
+                    mitigation: "1) 确保 order_allocators 顺序从严格到宽松；" +
+                        "2) 每个 Allocator 的 Guard 条件应互斥；" +
+                        "3) 考虑使用逻辑_or 依赖而非顺序排列",
+                };
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-GT-02",
+        trigger: "流程 Guard 时间锁可能锁定弱势方",
+        check: (ctx) => {
+            const rootStr = JSON.stringify(ctx.root);
+            if (rootStr.includes("Clock") && rootStr.includes("calc_number_add")) {
+                return {
+                    id: "R-GT-02",
+                    level: "medium",
+                    category: "game_theory",
+                    title: "时间锁可能锁定处于弱势的一方",
+                    description: "Guard 使用时间锁（context(Clock) + calc_number_add）。时间锁本身是中性的，" +
+                        "但需检查锁定方向：如果锁定 Customer 先付款但不能及时验收，Provider 获得优势；" +
+                        "如果锁定 Provider 先交付但不能及时收款，Customer 获得优势。",
+                    affected_stakeholders: ["customer", "provider"],
+                    scenario: "时间不对等：一方被时间锁定，另一方有行动自由",
+                    mitigation: "1) 确保时间锁对称（双方都有时间约束）；" +
+                        "2) 时间锁到期后提供退出机制（如自动退款/自动完成）；" +
+                        "3) 在 Machine 中设计对应的超时 Forward 节点",
+                };
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-GT-03",
+        trigger: "Arbitration usage_guard 可能阻止合法争议",
+        check: (ctx) => {
+            if (ctx.scene?.binding_field === "usage_guard") {
+                const rootStr = JSON.stringify(ctx.root);
+                const andCount = (rootStr.match(/"logic_and"/g) || []).length;
+                if (andCount >= 3) {
+                    return {
+                        id: "R-GT-03",
+                        level: "high",
+                        category: "game_theory",
+                        title: "usage_guard 条件过多可能阻止合法争议",
+                        description: `检测到 ${andCount} 个 logic_and 组合。过多 AND 条件使争议门槛过高，` +
+                            "Customer 可能无法发起合法争议，Provider 获得不正当优势。",
+                        affected_stakeholders: ["customer"],
+                        scenario: "争议门槛过高：Customer 无法发起合法争议",
+                        mitigation: "1) 重新评估每个 AND 条件的必要性；" +
+                            "2) 考虑使用 logic_or 降低门槛；" +
+                            "3) 将非必要条件移到 voting_guard 而非 usage_guard",
+                    };
+                }
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-LG-01",
+        trigger: "Guard root 为 identifier 直接返回 Bool",
+        check: (ctx) => {
+            if (ctx.root?.type === "identifier") {
+                return {
+                    id: "R-LG-01",
+                    level: "medium",
+                    category: "logic_gap",
+                    title: "Root 直接返回提交的 Bool 值，可被操纵",
+                    description: "Guard root 是 identifier 节点，直接返回 table 中的 Bool 值。" +
+                        "如果该条目 b_submission=true，调用者可以直接提交 true 绕过所有验证。",
+                    affected_stakeholders: ["customer", "provider"],
+                    scenario: "绕过验证：调用者提交 true 直接通过 Guard",
+                    mitigation: "1) 确保 identifier 引用的条目 b_submission=false（常量）；" +
+                        "2) 或添加额外的 logic_and 条件进行交叉验证",
+                };
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-LG-02",
+        trigger: "Guard 使用 logic_as_u256_greater 但未处理空值",
+        check: (ctx) => {
+            const rootStr = JSON.stringify(ctx.root);
+            if (rootStr.includes("logic_as_u256_greater") && rootStr.includes("query")) {
+                return {
+                    id: "R-LG-02",
+                    level: "medium",
+                    category: "logic_gap",
+                    title: "数值比较未处理查询返回空值的情况",
+                    description: "Guard 使用 logic_as_u256_greater 进行数值比较，且操作数来自 query。" +
+                        "如果 query 返回空值（如对象不存在、字段未设置），比较结果可能不确定。" +
+                        "WoWok 协议中空值通常被视为 0，可能导致非预期通过。",
+                    affected_stakeholders: ["customer", "provider"],
+                    scenario: "空值误判：query 返回 0 导致 > 0 条件意外通过或失败",
+                    mitigation: "1) 在比较前添加 query 结果存在性检查；" +
+                        "2) 使用 query_reward_record_exists 或 query_progress_history_find 先验证；" +
+                        "3) 考虑添加 logic_and(对象存在, 数值比较) 组合",
+                };
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-LG-03",
+        trigger: "Guard 使用 logic_string_contains 可能被子串匹配绕过",
+        check: (ctx) => {
+            const rootStr = JSON.stringify(ctx.root);
+            if (rootStr.includes("logic_string_contains") && !rootStr.includes("logic_string_nocase")) {
+                return {
+                    id: "R-LG-03",
+                    level: "low",
+                    category: "logic_gap",
+                    title: "logic_string_contains 子串匹配可能被绕过",
+                    description: "Guard 使用 logic_string_contains 进行字符串匹配。" +
+                        "子串匹配可能被绕过：例如检查 'Completed' 时，'NotCompleted' 也包含 'Completed'。" +
+                        "此外，大小写敏感可能导致非预期失败。",
+                    affected_stakeholders: ["customer", "provider"],
+                    scenario: "子串误匹配：'NotCompleted' 包含 'Completed' 导致误通过",
+                    mitigation: "1) 优先使用 logic_equal 进行精确匹配；" +
+                        "2) 如需子串匹配，添加边界条件（如前缀+后缀）；" +
+                        "3) 确认是否需要大小写不敏感（使用 nocase 变体）",
+                };
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-LG-04",
+        trigger: "时间锁 query 返回 0 导致 logic_as_u256_greater_or_equal 比较永远为 true",
+        check: (ctx) => {
+            const rootStr = JSON.stringify(ctx.root);
+            const hasGreaterOrEqual = rootStr.includes("logic_as_u256_greater_or_equal");
+            const hasClock = rootStr.includes('"Clock"');
+            const hasCalcAdd = rootStr.includes("calc_number_add");
+            const hasQuery = rootStr.includes('"query"');
+            if (hasGreaterOrEqual && hasClock && hasCalcAdd && hasQuery) {
+                return {
+                    id: "R-LG-04",
+                    level: "medium",
+                    category: "logic_gap",
+                    title: "时间锁查询可能返回 0 导致 >= 比较永远为 true",
+                    description: "Guard 使用 logic_as_u256_greater_or_equal 进行时间锁比较，且被比较的基准值来自 query。" +
+                        "如果 query 返回 0（如查询尚未发生的操作时间戳、未设置的节点进入时间），" +
+                        "则 Clock >= 0 + timeout 永远为 true，时间锁形同虚设，弱势方可以立即绕过时间约束。",
+                    affected_stakeholders: ["customer", "provider"],
+                    scenario: "时间锁失效：query 返回 0 使 >= 条件永远通过",
+                    mitigation: "1) 使用返回当前节点进入时间的 query（如 progress.current_time, id=1272）" +
+                        "而非操作时间戳（如 progress.session.forward.time, id=1271）；" +
+                        "2) 在时间锁前添加 query > 0 的前置检查；" +
+                        "3) 确认 query 在 Guard 执行时必然有值（查询当前节点属性而非历史操作）",
+                };
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-BR-01",
+        trigger: "Guard 绑定到已发布的 Machine/Service（不可变）",
+        check: (ctx) => {
+            if (ctx.scene && !ctx.scene.mutable_after_publish) {
+                return {
+                    id: "R-BR-01",
+                    level: "info",
+                    category: "binding_risk",
+                    title: `Guard 绑定到不可变的 ${ctx.scene.host_object}（发布后不可修改）`,
+                    description: `${ctx.scene.host_object} 发布后 ${ctx.scene.binding_field} 不可修改。` +
+                        "如果 Guard 设计有误，需要新建 Machine/Service 并迁移所有引用。" +
+                        "这是设计约束而非风险，但需要确保 Guard 设计正确后再发布。",
+                    affected_stakeholders: ["provider"],
+                    scenario: "不可逆绑定：发布后发现 Guard 设计有误无法修改",
+                    mitigation: "1) 发布前使用 gen_passport 进行充分测试；" +
+                        "2) 测试 expected-pass 和 expected-fail 两种场景；" +
+                        "3) 发布前导出 Guard 备份（guard2file）",
+                };
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-BR-02",
+        trigger: "Repository write_guard 未验证 id_from_submission 类型",
+        check: (ctx) => {
+            if (ctx.scene?.binding_field === "write_guard") {
+                return {
+                    id: "R-BR-02",
+                    level: "high",
+                    category: "binding_risk",
+                    title: "Repository write_guard 需验证 id_from_submission 类型",
+                    description: "Repository write_guard 的 id_from_submission 引用的 table 条目必须 Address 类型。" +
+                        "data_from_submission 引用的条目必须匹配 Repository value_type。" +
+                        "类型不匹配会导致写入失败或数据损坏。",
+                    affected_stakeholders: ["provider"],
+                    scenario: "类型不匹配：写入失败或数据损坏",
+                    mitigation: "1) 确认 id_from_submission 引用的条目 value_type=Address；" +
+                        "2) 确认 data_from_submission 引用的条目 value_type 匹配 Repository；" +
+                        "3) 在 gen_passport 测试中覆盖写入场景",
+                };
+            }
+            return null;
+        },
+    },
+    {
+        id: "R-DR-01",
+        trigger: "Guard 使用 rely 但依赖的 Guard 可能失效",
+        check: (ctx) => {
+            if (ctx.rely && ctx.rely.guards.length > 0) {
+                const logic = ctx.rely.logic_or ? "OR" : "AND";
+                return {
+                    id: "R-DR-01",
+                    level: ctx.rely.logic_or ? "low" : "medium",
+                    category: "dependency_risk",
+                    title: `rely ${logic} 依赖 ${ctx.rely.guards.length} 个外部 Guard`,
+                    description: `Guard 使用 rely ${logic} 依赖 ${ctx.rely.guards.length} 个外部 Guard。` +
+                        (ctx.rely.logic_or
+                            ? "OR 逻辑：任一依赖通过即可。如果某个依赖 Guard 设计宽松，可能成为绕过入口。"
+                            : "AND 逻辑：所有依赖必须通过。如果某个依赖 Guard 失效或被删除，当前 Guard 将永远失败。"),
+                    affected_stakeholders: ["customer", "provider"],
+                    scenario: ctx.rely.logic_or
+                        ? "依赖绕过：宽松的依赖 Guard 成为攻击入口"
+                        : "依赖失效：依赖 Guard 被删除导致当前 Guard 永远失败",
+                    mitigation: ctx.rely.logic_or
+                        ? "1) 审查每个依赖 Guard 的严格程度；2) 确保所有依赖 Guard 至少与当前 Guard 同等严格"
+                        : "1) 确认所有依赖 Guard 的 rep=true 且不可删除；2) 考虑是否真的需要 AND 依赖",
+                };
+            }
+            return null;
+        },
+    },
+];
+export function assessGuardRisks(params) {
+    const ctx = {
+        table: params.table,
+        root: params.root,
+        rely: params.rely,
+        scene: params.scene,
+        operation_type: params.operation_type,
+    };
+    const risks = [];
+    for (const rule of RISK_RULES) {
+        try {
+            const risk = rule.check(ctx);
+            if (risk)
+                risks.push(risk);
+        }
+        catch {
+        }
+    }
+    const overall_risk = getOverallRiskLevel(risks);
+    const stakeholder_advice = generateStakeholderAdvice(risks, params.scene);
+    const needs_human_review = risks.some((r) => r.level === "critical") ||
+        risks.filter((r) => r.level === "high").length >= 2;
+    const guard_summary = generateGuardSummary(params);
+    return {
+        guard_summary,
+        scene: params.scene,
+        risks,
+        overall_risk,
+        stakeholder_advice,
+        needs_human_review,
+    };
+}
+function getOverallRiskLevel(risks) {
+    if (risks.some((r) => r.level === "critical"))
+        return "critical";
+    if (risks.some((r) => r.level === "high"))
+        return "high";
+    if (risks.some((r) => r.level === "medium"))
+        return "medium";
+    if (risks.some((r) => r.level === "low"))
+        return "low";
+    return "info";
+}
+function generateStakeholderAdvice(risks, scene) {
+    const advice = {};
+    for (const risk of risks) {
+        for (const stakeholder of risk.affected_stakeholders) {
+            if (!advice[stakeholder])
+                advice[stakeholder] = [];
+            advice[stakeholder].push(`[${risk.level.toUpperCase()}] ${risk.title}: ${risk.mitigation}`);
+        }
+    }
+    if (scene) {
+        switch (scene.binding_field) {
+            case "buy_guard":
+                if (!advice.customer)
+                    advice.customer = [];
+                advice.customer.push("购买前确认 buy_guard 的验证逻辑，确保你的身份/凭证能通过验证");
+                break;
+            case "order_allocators":
+                if (!advice.provider)
+                    advice.provider = [];
+                advice.provider.push("确认 order_allocators 顺序，确保你的分账 Allocator 不会被前面的条件跳过");
+                break;
+            case "voting_guard":
+                if (!advice.arbitrator)
+                    advice.arbitrator = [];
+                advice.arbitrator.push("确认投票权重来源可信，建议从 EntityRegistrar 查询而非用户提交");
+                break;
+            case "Forward.guard":
+                if (!advice.customer)
+                    advice.customer = [];
+                advice.customer.push("确认 Forward.guard 的条件，确保你能满足推进条件，避免资金被锁定");
+                break;
+        }
+    }
+    return advice;
+}
+function generateGuardSummary(params) {
+    const parts = [];
+    parts.push(`table 条目数: ${params.table.length}`);
+    const submissions = params.table.filter((e) => e.b_submission).length;
+    parts.push(`提交数据: ${submissions} 条`);
+    parts.push(`root 类型: ${params.root?.type ?? "unknown"}`);
+    if (params.rely) {
+        parts.push(`rely: ${params.rely.guards.length} 个依赖 (${params.rely.logic_or ? "OR" : "AND"})`);
+    }
+    return parts.join(", ");
+}
+export function assessGuardRisksForOperation(operation_type, data) {
+    if (operation_type !== "guard")
+        return null;
+    const table = data?.table ?? [];
+    const root = data?.root;
+    const rely = data?.rely;
+    let scene;
+    return assessGuardRisks({ table, root, rely, scene, operation_type });
+}
+export function getRiskSummary(assessment) {
+    return {
+        risk_count: assessment.risks.length,
+        critical_count: assessment.risks.filter((r) => r.level === "critical").length,
+        high_count: assessment.risks.filter((r) => r.level === "high").length,
+        needs_human_review: assessment.needs_human_review,
+        top_risks: assessment.risks
+            .filter((r) => r.level === "critical" || r.level === "high")
+            .slice(0, 3)
+            .map((r) => r.title),
+    };
+}

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

@@ -0,0 +1,46 @@
+export interface SemanticToSchemaRule {
+    id: string;
+    pattern_name: string;
+    semantic_intent: string;
+    match_keywords: string[];
+    schema_elements: {
+        root_type: string;
+        table_entries: Array<{
+            value_type: string;
+            b_submission: boolean;
+            purpose: string;
+        }>;
+        query_nodes?: Array<{
+            query_name: string;
+            object_type: string;
+            convert_witness?: number;
+        }>;
+        tree_structure: string;
+    };
+    constraints: string[];
+    example: Record<string, unknown>;
+}
+export declare const SEMANTIC_TO_SCHEMA_RULES: SemanticToSchemaRule[];
+export interface SchemaToSemanticRule {
+    element_type: "node" | "table_entry" | "query" | "witness" | "rely";
+    type_name: string;
+    semantic: string;
+    return_type?: string;
+    child_constraints?: string;
+    discovery_tool?: string;
+}
+export declare const SCHEMA_TO_SEMANTIC_RULES: SchemaToSemanticRule[];
+export interface GuardConstraintRule {
+    id: string;
+    name: string;
+    description: string;
+    category: "root" | "table" | "query" | "witness" | "rely" | "binding";
+    validation_logic: string;
+    failure_message: string;
+    pitfall_number?: number;
+}
+export declare const GUARD_CONSTRAINT_RULES: GuardConstraintRule[];
+export declare function matchSemanticPattern(userIntent: string): SemanticToSchemaRule[];
+export declare function explainNode(nodeType: string): SchemaToSemanticRule | undefined;
+export declare function explainWitness(witnessType: number): SchemaToSemanticRule | undefined;
+export declare function getConstraintsByCategory(category: GuardConstraintRule["category"]): GuardConstraintRule[];