@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/guard-context.js

@@ -0,0 +1,287 @@
+import { GUARD_SCENES, findScene, } from "./guard-ledger.js";
+import { getTemplatesByScene, } from "./guard-templates.js";
+import { matchSemanticPattern, } from "./guard-translation.js";
+import { getAllRiskRules, assessGuardRisks, } from "./guard-risk.js";
+import { initPuzzleFromIntent, checkPuzzleCompleteness, } from "./guard-puzzle.js";
+import { GUARD_PUBLISH_CHECKLIST, GUARD_CONFIRMATION_QUESTIONS, } from "./guard-confirm.js";
+import { MAX_TABLE_SIZE, MAX_DESCRIPTION_LENGTH, } from "@wowok/wowok";
+import { MACHINE_SCENES, } from "./machine-ledger.js";
+export const GUARD_CONTEXT_VERSION = "1.0.0";
+export function buildGuardContext(input) {
+    const max_length = input.max_length ?? 4000;
+    let matched_scene;
+    if (input.intent) {
+        matched_scene = findSceneByIntentKeywords(input.intent);
+    }
+    else if (input.guard_json?.binding_scene_id) {
+        matched_scene = GUARD_SCENES.find(s => s.id === input.guard_json.binding_scene_id);
+    }
+    else if (input.target_host_object && input.target_binding_field) {
+        matched_scene = findScene(input.target_host_object, input.target_binding_field);
+    }
+    let matched_template;
+    if (matched_scene) {
+        const templates = getTemplatesByScene(matched_scene.id);
+        if (templates.length > 0)
+            matched_template = templates[0];
+    }
+    let matched_pattern;
+    if (input.intent) {
+        const patterns = matchSemanticPattern(input.intent);
+        if (patterns.length > 0)
+            matched_pattern = patterns[0];
+    }
+    let puzzle_state;
+    let puzzle_completeness;
+    if (input.mode === "initial_design" && input.intent) {
+        puzzle_state = initPuzzleFromIntent({ rule_sentence: input.intent });
+        puzzle_completeness = checkPuzzleCompleteness(puzzle_state);
+    }
+    else if (input.mode === "mid_design_review" && input.guard_json) {
+        puzzle_completeness = checkPuzzleCompleteness({});
+    }
+    const relevant_risks = filterRiskRules(input.mode, input.stakeholder, matched_scene);
+    let risk_assessment;
+    if (input.mode === "pre_publish" && input.guard_json) {
+        const guard_data = input.guard_json.root;
+        risk_assessment = assessGuardRisks({
+            table: guard_data?.table ?? [],
+            root: input.guard_json.root,
+            rely: guard_data?.rely,
+        });
+    }
+    const relevant_checklist = filterChecklist(input.mode);
+    const relevant_questions = filterQuestions(input.mode);
+    const cross_object_refs = buildCrossObjectRefs(matched_scene);
+    const onchain_constraints = buildOnchainConstraints();
+    const rendering_hints = buildRenderingHints(input.mode, max_length);
+    return {
+        version: GUARD_CONTEXT_VERSION,
+        mode: input.mode,
+        stakeholder_perspective: input.stakeholder,
+        matched_scene,
+        matched_template,
+        matched_pattern,
+        puzzle_state,
+        puzzle_completeness,
+        relevant_risks,
+        risk_assessment,
+        relevant_checklist,
+        relevant_questions,
+        cross_object_refs,
+        onchain_constraints,
+        rendering_hints,
+    };
+}
+function filterRiskRules(mode, stakeholder, scene) {
+    let rules = getAllRiskRules();
+    if (scene) {
+        rules = rules.filter(r => !r.id.startsWith("R-X") || true);
+    }
+    if (stakeholder && stakeholder !== "system") {
+    }
+    if (mode === "initial_design") {
+        return rules.filter(r => r.id.startsWith("R-C1") ||
+            r.id.startsWith("R-C4"));
+    }
+    if (mode === "pre_publish") {
+        return rules;
+    }
+    if (mode === "stakeholder_review" && stakeholder) {
+        return rules;
+    }
+    return rules;
+}
+function filterChecklist(mode) {
+    if (mode === "initial_design") {
+        return GUARD_PUBLISH_CHECKLIST.filter(item => ["GC-01", "GC-05", "GC-12"].includes(item.id));
+    }
+    if (mode === "pre_publish") {
+        return GUARD_PUBLISH_CHECKLIST;
+    }
+    return GUARD_PUBLISH_CHECKLIST.filter(item => !item.id.startsWith("GC-0"));
+}
+function filterQuestions(mode) {
+    if (mode === "pre_publish") {
+        return GUARD_CONFIRMATION_QUESTIONS;
+    }
+    if (mode === "mid_design_review") {
+        return GUARD_CONFIRMATION_QUESTIONS.filter(q => q.id === "QG1" || q.id === "QG2");
+    }
+    return [];
+}
+function buildCrossObjectRefs(scene) {
+    const refs = [];
+    for (const machine_scene of MACHINE_SCENES) {
+        refs.push({
+            object: "Machine",
+            field: "Forward.guard",
+            scene_id: machine_scene.id,
+            description: `Machine scene "${machine_scene.id}" can reference Guards via Forward.guard`,
+        });
+    }
+    if (scene && scene.host_object !== "Standalone") {
+        refs.push({
+            object: scene.host_object,
+            field: scene.binding_field,
+            scene_id: scene.id,
+            description: scene.validation_scene,
+        });
+    }
+    return refs;
+}
+function buildOnchainConstraints() {
+    return [
+        { name: "MAX_TABLE_SIZE", value: MAX_TABLE_SIZE, description: "Maximum entries in Guard table" },
+        { name: "MAX_DESCRIPTION_LENGTH", value: MAX_DESCRIPTION_LENGTH, description: "Maximum description length" },
+    ];
+}
+function buildRenderingHints(mode, max_length) {
+    switch (mode) {
+        case "initial_design":
+            return {
+                include_puzzle_template: true,
+                include_risk_details: false,
+                include_questions: false,
+                include_immutability_warning: true,
+                max_length,
+            };
+        case "mid_design_review":
+            return {
+                include_puzzle_template: false,
+                include_risk_details: true,
+                include_questions: false,
+                include_immutability_warning: true,
+                max_length,
+            };
+        case "pre_publish":
+            return {
+                include_puzzle_template: false,
+                include_risk_details: true,
+                include_questions: true,
+                include_immutability_warning: true,
+                max_length,
+            };
+        case "stakeholder_review":
+            return {
+                include_puzzle_template: false,
+                include_risk_details: true,
+                include_questions: false,
+                include_immutability_warning: false,
+                max_length,
+            };
+        default:
+            return {
+                include_puzzle_template: false,
+                include_risk_details: false,
+                include_questions: false,
+                include_immutability_warning: true,
+                max_length,
+            };
+    }
+}
+function findSceneByIntentKeywords(intent) {
+    const lower = intent.toLowerCase();
+    for (const scene of GUARD_SCENES) {
+        if (scene.id.split("_").some(keyword => lower.includes(keyword))) {
+            return scene;
+        }
+    }
+    return undefined;
+}
+export function buildPromptFromGuardContext(bundle) {
+    const lines = [];
+    const h = bundle.rendering_hints;
+    lines.push("═══════════════════════════════════════════════════════════");
+    lines.push(`  GUARD CONTEXT (mode: ${bundle.mode})`);
+    lines.push("═══════════════════════════════════════════════════════════");
+    if (bundle.matched_scene) {
+        lines.push("");
+        lines.push(`Matched Scene: ${bundle.matched_scene.name}`);
+        lines.push(`  Host Object: ${bundle.matched_scene.host_object}`);
+        lines.push(`  Binding Field: ${bundle.matched_scene.binding_field}`);
+        lines.push(`  Validation: ${bundle.matched_scene.validation_scene}`);
+    }
+    if (bundle.matched_template) {
+        lines.push("");
+        lines.push(`Recommended Template: ${bundle.matched_template.name}`);
+        lines.push(`  Patterns: ${bundle.matched_template.recommended_patterns.join(", ")}`);
+    }
+    if (bundle.matched_pattern) {
+        lines.push("");
+        lines.push(`Semantic Pattern: ${bundle.matched_pattern.id} — ${bundle.matched_pattern.pattern_name}`);
+        lines.push(`  Intent: ${bundle.matched_pattern.semantic_intent}`);
+    }
+    if (h.include_puzzle_template && bundle.puzzle_state) {
+        lines.push("");
+        lines.push("─ Puzzle State ──────────────────────────────────────────");
+        const completeness = bundle.puzzle_completeness;
+        if (completeness) {
+            lines.push(`Complete: ${completeness.complete ? "YES" : "NO"}`);
+            if (completeness.missing.length > 0) {
+                lines.push(`Missing: ${completeness.missing.join(", ")}`);
+            }
+        }
+    }
+    if (h.include_risk_details && bundle.relevant_risks.length > 0) {
+        lines.push("");
+        lines.push(`─ Relevant Risk Rules (${bundle.relevant_risks.length}) ──────────────────────`);
+        for (const r of bundle.relevant_risks.slice(0, 5)) {
+            lines.push(`  ${r.id} — ${r.trigger}`);
+        }
+        if (bundle.relevant_risks.length > 5) {
+            lines.push(`  ... and ${bundle.relevant_risks.length - 5} more`);
+        }
+    }
+    if (bundle.risk_assessment) {
+        lines.push("");
+        lines.push("─ Risk Assessment ───────────────────────────────────────");
+        lines.push(`Overall: ${bundle.risk_assessment.overall_risk.toUpperCase()}`);
+        lines.push(`Detected: ${bundle.risk_assessment.risks?.length ?? 0} risks`);
+    }
+    if (h.include_questions && bundle.relevant_questions.length > 0) {
+        lines.push("");
+        lines.push("─ Confirmation Questions ────────────────────────────────");
+        for (const q of bundle.relevant_questions) {
+            lines.push(`  ${q.id} (blocking=${q.blocking}): ${q.question}`);
+        }
+    }
+    if (bundle.cross_object_refs.length > 0) {
+        lines.push("");
+        lines.push("─ Cross-Object References ───────────────────────────────");
+        for (const ref of bundle.cross_object_refs.slice(0, 3)) {
+            lines.push(`  ${ref.object}.${ref.field} (${ref.scene_id})`);
+        }
+    }
+    if (bundle.onchain_constraints.length > 0) {
+        lines.push("");
+        lines.push("─ On-Chain Constraints ──────────────────────────────────");
+        for (const c of bundle.onchain_constraints) {
+            lines.push(`  ${c.name} = ${c.value} (${c.description})`);
+        }
+    }
+    if (h.include_immutability_warning) {
+        lines.push("");
+        lines.push("⚠️  Guard is IMMUTABLE after creation — no update path exists.");
+        lines.push("    Review the validation rule twice before publishing.");
+    }
+    lines.push("");
+    lines.push("═══════════════════════════════════════════════════════════");
+    return lines.join("\n");
+}
+export function getGuardContextSummary(bundle) {
+    const parts = [];
+    parts.push(`Guard Context v${bundle.version}`);
+    parts.push(`Mode: ${bundle.mode}`);
+    if (bundle.matched_scene)
+        parts.push(`Scene: ${bundle.matched_scene.id}`);
+    if (bundle.matched_template)
+        parts.push(`Template: ${bundle.matched_template.id}`);
+    if (bundle.matched_pattern)
+        parts.push(`Pattern: ${bundle.matched_pattern.id}`);
+    parts.push(`Risks: ${bundle.relevant_risks.length} relevant`);
+    parts.push(`Checklist: ${bundle.relevant_checklist.length} items`);
+    parts.push(`Questions: ${bundle.relevant_questions.length}`);
+    parts.push(`Cross-refs: ${bundle.cross_object_refs.length}`);
+    return parts.join(" | ");
+}

package/dist/knowledge/guard-design-patterns.d.ts

@@ -0,0 +1,37 @@
+import type { IndustryModeName } from "./scenario-modes.js";
+export type GuardDataSourceClass = "OnChainConstant" | "WitnessDerived" | "SubmittedObject" | "SystemContext";
+export type VerifierConstraintLevel = "level1_strict_single" | "level2_identity_set" | "level3_scene_combined" | "none";
+export type GuardHostObject = "service_buy_guard" | "service_allocator_guard" | "machine_forward" | "progress_submission" | "reward_claim" | "repository_write" | "arbitration_usage" | "arbitration_voting" | "gen_passport";
+export interface GuardDesignPattern {
+    id: string;
+    business_requirement: string;
+    data_source: GuardDataSourceClass;
+    host: GuardHostObject;
+    verifier_level: VerifierConstraintLevel;
+    logic_summary: string;
+    key_queries: string[];
+    witness_types?: string[];
+    mitigated_risks?: string[];
+    applicable_industries?: IndustryModeName[];
+    notes?: string[];
+}
+export declare const GUARD_DESIGN_PATTERNS: GuardDesignPattern[];
+export interface VerifierLevelGuidance {
+    level: VerifierConstraintLevel;
+    pattern: string;
+    when_to_use: string;
+    risk_rules: string[];
+    recommendation: "avoid" | "use_with_justification" | "recommended" | "default";
+}
+export declare const VERIFIER_LEVEL_GUIDANCE: VerifierLevelGuidance[];
+export declare function getGuardDesignPattern(id: string): GuardDesignPattern | undefined;
+export declare function searchGuardDesignPatterns(query: string): GuardDesignPattern[];
+export declare function getPatternsByHost(host: GuardHostObject): GuardDesignPattern[];
+export declare function getPatternsByIndustry(industry: IndustryModeName): GuardDesignPattern[];
+export declare function getPatternsByDataSourceClass(source: GuardDataSourceClass): GuardDesignPattern[];
+export declare function getVerifierLevelGuidance(level: VerifierConstraintLevel): VerifierLevelGuidance | undefined;
+export declare function suggestPatternForRequirement(requirement: string): {
+    best: GuardDesignPattern;
+    alternatives: GuardDesignPattern[];
+};
+export declare const GUARD_DESIGN_PATTERNS_VERSION = 1;

package/dist/knowledge/guard-design-patterns.js

@@ -0,0 +1,257 @@
+export const GUARD_DESIGN_PATTERNS = [
+    {
+        id: "pattern.identity_check_single",
+        business_requirement: "Only the author can purchase this service (strict single-identity)",
+        data_source: "SystemContext",
+        host: "service_buy_guard",
+        verifier_level: "level1_strict_single",
+        logic_summary: "logic_equal[context(Signer), identifier[N](fixed_address)]",
+        key_queries: [],
+        mitigated_risks: ["R-C4-04"],
+        notes: [
+            "Maximally secure but maximally inconvenient",
+            "If address is unavailable (key loss, rotation), Guard permanently blocks",
+            "Avoid unless role is permanently tied to one address",
+        ],
+    },
+    {
+        id: "pattern.identity_check_allowlist",
+        business_requirement: "Customer must be in an allowlist to purchase",
+        data_source: "SystemContext",
+        host: "service_buy_guard",
+        verifier_level: "level2_identity_set",
+        logic_summary: "vec_contains_address[identifier[N](allowlist_vec), context(Signer)]",
+        key_queries: [],
+        mitigated_risks: ["R-C4-04"],
+        notes: ["Allowlist stored as Address vector in table constant"],
+    },
+    {
+        id: "pattern.identity_check_order_holder",
+        business_requirement: "Only order owner or agent can perform operation",
+        data_source: "OnChainConstant",
+        host: "machine_forward",
+        verifier_level: "level2_identity_set",
+        logic_summary: "logic_or[logic_equal[query(1562 order.owner), context(Signer)], query(1567 order.agent has, Signer)]",
+        key_queries: ["order.owner", "order.agent has"],
+        mitigated_risks: ["R-C4-04", "R-C3-06"],
+        notes: [
+            "1562 returns Address → wrap in logic_equal",
+            "1567 returns Bool → use directly as logic_or child",
+            "Recommended Level 2 alternative to Level 1 strict binding",
+        ],
+    },
+    {
+        id: "pattern.identity_check_service_provider_dynamic",
+        business_requirement: "Verify caller is service's current permission owner (survives permission rotation)",
+        data_source: "SubmittedObject",
+        host: "machine_forward",
+        verifier_level: "level2_identity_set",
+        logic_summary: "logic_and[logic_equal[query(1488 service.permission), identifier[N](submitted_perm)], logic_or[logic_equal[query(1002 permission.owner), context(Signer)], query(1004 permission.admin has, Signer)]]",
+        key_queries: ["service.permission", "permission.owner", "permission.admin has"],
+        mitigated_risks: ["R-C4-04", "R-C3-05"],
+        notes: [
+            "Dynamic permission address (RECOMMENDED) — survives Service permission rotation",
+            "Caller submits permission address; Guard verifies match then checks identity",
+            "More complex than static but far more robust",
+        ],
+    },
+    {
+        id: "pattern.time_lock_progress",
+        business_requirement: "Customer must wait N hours before completing (time-lock)",
+        data_source: "WitnessDerived",
+        host: "machine_forward",
+        verifier_level: "none",
+        logic_summary: "logic_as_u256_ge[context(Clock), calc_number_add[query(1272 progress.current_time, witness=OrderProgress), identifier[N](duration_ms)]]",
+        key_queries: ["progress.current_time"],
+        witness_types: ["OrderProgress"],
+        mitigated_risks: [],
+        notes: [
+            "Use convert_witness=100 (OrderProgress) to derive Progress from submitted Order ID",
+            "Duration in milliseconds — test with small values first",
+        ],
+    },
+    {
+        id: "pattern.time_lock_absolute",
+        business_requirement: "Operation allowed only after a fixed timestamp",
+        data_source: "SystemContext",
+        host: "service_buy_guard",
+        verifier_level: "none",
+        logic_summary: "logic_as_u256_ge[context(Clock), identifier[N](release_timestamp)]",
+        key_queries: [],
+        mitigated_risks: [],
+        notes: ["Useful for pre-sale windows, embargo periods"],
+    },
+    {
+        id: "pattern.repository_data_check",
+        business_requirement: "External data must match expected value (e.g., weather, price feed)",
+        data_source: "OnChainConstant",
+        host: "machine_forward",
+        verifier_level: "none",
+        logic_summary: "logic_equal[query(1167 repository.data, policy, key), identifier[N](expected_value)]",
+        key_queries: ["repository.data"],
+        mitigated_risks: [],
+        notes: [
+            "Repository address declared as table constant",
+            "Timestamp keys may need convert_number_address",
+            "quote_guard = Some(addr) always fails in verify phase (impack_list empty) — use quote_guard = None",
+        ],
+    },
+    {
+        id: "pattern.progress_state_check",
+        business_requirement: "Specific forward has been accomplished (customer confirms delivery)",
+        data_source: "WitnessDerived",
+        host: "reward_claim",
+        verifier_level: "none",
+        logic_summary: "logic_equal[query_progress_history_find(...).accomplished, identifier[N](true)]",
+        key_queries: ["progress.current", "progress.current_time"],
+        witness_types: ["OrderProgress"],
+        mitigated_risks: [],
+        notes: ["Chain query_progress_history_find → query_progress_history_session_forward_find"],
+    },
+    {
+        id: "pattern.reward_one_time_claim",
+        business_requirement: "User can only claim reward once (no prior claims)",
+        data_source: "OnChainConstant",
+        host: "reward_claim",
+        verifier_level: "none",
+        logic_summary: "logic_equal[query_reward_record_count(recipient=Signer), identifier[N](0)]",
+        key_queries: ["reward.record_count"],
+        mitigated_risks: [],
+        notes: ["Record count check prevents double-claim"],
+    },
+    {
+        id: "pattern.reward_multi_condition",
+        business_requirement: "Order payment > threshold AND reached 'complete' to claim reward",
+        data_source: "WitnessDerived",
+        host: "reward_claim",
+        verifier_level: "none",
+        logic_summary: "logic_and[logic_as_u256_gt[query(order.amount), threshold], logic_equal[query(progress.current), 'complete'], logic_equal[query(order.service), identifier[N](expected_service)]]",
+        key_queries: ["order.amount", "progress.current", "order.service"],
+        witness_types: ["OrderProgress"],
+        mitigated_risks: ["R-C3-05"],
+        notes: ["Multi-condition: amount + progress state + service match"],
+    },
+    {
+        id: "pattern.arbitration_voting_weight",
+        business_requirement: "Vote weight equals reputation score (dynamic weight from Passport)",
+        data_source: "SubmittedObject",
+        host: "arbitration_voting",
+        verifier_level: "none",
+        logic_summary: "GuardIdentifier extracts numeric value from Passport submission",
+        key_queries: [],
+        mitigated_risks: ["R-C3-02"],
+        notes: [
+            "Table needs numeric submission entry at referenced index",
+            "Weight must come from on-chain EntityRegistrar, not submission",
+            "BINDING_01: voting_guard GuardIdentifier must be numeric (U8-U256)",
+        ],
+    },
+    {
+        id: "pattern.arbitration_membership_check",
+        business_requirement: "Only premium members can file disputes",
+        data_source: "OnChainConstant",
+        host: "arbitration_usage",
+        verifier_level: "none",
+        logic_summary: "logic_and[query(entity exists), logic_as_u256_ge[query(entity tier), identifier[N](premium_tier)]]",
+        key_queries: ["entity.registrar", "entity.linker"],
+        mitigated_risks: [],
+        notes: ["ENTITY_REGISTRAR_ADDRESS (0xaab) / ENTITY_LINKER_ADDRESS (0xaaa) must be in table"],
+    },
+    {
+        id: "pattern.scene_allocator_entity_recipient",
+        business_requirement: "Service allocator with sharing.who=Entity — no Signer binding needed",
+        data_source: "OnChainConstant",
+        host: "service_allocator_guard",
+        verifier_level: "level3_scene_combined",
+        logic_summary: "Scene verifies fund flow safety — Guard only validates allocation rules",
+        key_queries: ["service.permission", "order.amount"],
+        mitigated_risks: ["R-C3-06"],
+        notes: [
+            "Funds flow to fixed Treasury/address regardless of caller",
+            "sharing.who=Entity already guarantees recipient safety",
+            "No Signer binding required — R-C3-06 safe",
+        ],
+    },
+    {
+        id: "pattern.scene_machine_forward_operator",
+        business_requirement: "Machine forward with permissionIndex/namedOperator already verifies operator",
+        data_source: "OnChainConstant",
+        host: "machine_forward",
+        verifier_level: "level3_scene_combined",
+        logic_summary: "Forward's permissionIndex/namedOperator verifies operator — Guard only validates submitted data",
+        key_queries: [],
+        mitigated_risks: [],
+        notes: [
+            "Scene verifies operator permission via permissionIndex/namedOperator",
+            "Signer binding only needed if submitted data must belong to operator",
+            "Evaluate scene before adding Signer binding",
+        ],
+    },
+];
+export const VERIFIER_LEVEL_GUIDANCE = [
+    {
+        level: "level1_strict_single",
+        pattern: "logic_equal[context(Signer), identifier[N](fixed_address)]",
+        when_to_use: "Role permanently tied to one address AND designer accepts lock-in risk",
+        risk_rules: ["R-C4-04"],
+        recommendation: "avoid",
+    },
+    {
+        level: "level2_identity_set",
+        pattern: "logic_or of multiple identity checks",
+        when_to_use: "Role-based access — multiple authorized identities",
+        risk_rules: ["R-C4-04 (suppressed)"],
+        recommendation: "recommended",
+    },
+    {
+        level: "level3_scene_combined",
+        pattern: "Scene itself verifies identity — no Signer binding needed",
+        when_to_use: "Scene's host object already verifies operator (e.g., Machine forward, sharing.who=Entity)",
+        risk_rules: [],
+        recommendation: "default",
+    },
+    {
+        level: "none",
+        pattern: "No Signer binding required",
+        when_to_use: "Resource flow matters more than caller identity",
+        risk_rules: [],
+        recommendation: "default",
+    },
+];
+export function getGuardDesignPattern(id) {
+    return GUARD_DESIGN_PATTERNS.find((p) => p.id === id);
+}
+export function searchGuardDesignPatterns(query) {
+    const q = query.toLowerCase();
+    return GUARD_DESIGN_PATTERNS.filter((p) => {
+        if (p.business_requirement.toLowerCase().includes(q))
+            return true;
+        if (p.logic_summary.toLowerCase().includes(q))
+            return true;
+        if (p.key_queries.some((k) => k.toLowerCase().includes(q)))
+            return true;
+        return false;
+    });
+}
+export function getPatternsByHost(host) {
+    return GUARD_DESIGN_PATTERNS.filter((p) => p.host === host);
+}
+export function getPatternsByIndustry(industry) {
+    return GUARD_DESIGN_PATTERNS.filter((p) => p.applicable_industries?.includes(industry));
+}
+export function getPatternsByDataSourceClass(source) {
+    return GUARD_DESIGN_PATTERNS.filter((p) => p.data_source === source);
+}
+export function getVerifierLevelGuidance(level) {
+    return VERIFIER_LEVEL_GUIDANCE.find((g) => g.level === level);
+}
+export function suggestPatternForRequirement(requirement) {
+    const matches = searchGuardDesignPatterns(requirement);
+    if (matches.length === 0) {
+        const fallback = GUARD_DESIGN_PATTERNS[0];
+        return { best: fallback, alternatives: [] };
+    }
+    const [best, ...alternatives] = matches;
+    return { best, alternatives };
+}
+export const GUARD_DESIGN_PATTERNS_VERSION = 1;

package/dist/knowledge/guard-ledger.js

@@ -13,6 +13,7 @@ export const GUARD_SCENES = [
             "The name of b_submission=true entries must be a natural-language description (the contract the customer sees)",
             "If the Guard references the Service itself, use the circular reference pattern (CREATE Service → CREATE Guard → MODIFY Service)",
             "buy_guard can still be modified after Service is published (via MODIFY Service)",
+            "Reentrancy: LOW — Each purchase creates a fresh Order; no existing Order state is modified. Default: no reentrancy risk. IF business intent is 'limit one purchase per user' (limited-edition goods, whitelist single-buy), an anti-reentrancy check is REQUIRED but no direct GUARDQUERY primitive exists for per-user purchase history — use a Repository to record prior purchases and add `repository.data has` (query 1166) + `logic_not` to root, or revoke EntityRegistrar membership after first buy",
         ],
         common_patterns: [
             "Identity check: context(Signer) + logic_equal (single address) / vec_contains_address (whitelist)",
@@ -39,12 +40,18 @@ export const GUARD_SCENES = [
             "Guard usually queries Order/Progress state to determine allocation conditions",
             "Common queries: order.amount, progress.current_node, order.completed, etc.",
             "GuardIdentifier can be used for dynamic amounts (extract u64 value from table as allocation ratio)",
+            "Guard+sharing coupling: Guard determines IF allocation happens; sharing.who determines WHERE funds go. If sharing.who=Signer, the caller receives funds — the Guard MUST bind Signer (context(Signer)==authorized) to prevent theft. PREFERRED: use sharing.who=Entity (Treasury or fixed address) so funds always go to the legitimate recipient regardless of caller.",
+            "allocators require unique guard addresses: no two allocators may reference the same Guard object (create separate Guard objects with identical root/table but different descriptions if needed).",
+            "First-match-wins: only the first allocator whose Guard passes executes; subsequent allocators are skipped. Multiple allocators represent alternative strategies, not a simultaneous split.",
+            "If sharing.who=Entity references a Treasury object, verify the Treasury's permission is consistent with the Service's permission (different permissions = different permission organizations = minor risk).",
+            "Reentrancy: LOW — Protocol-level protection: order::on_allocation (order.move L116-119) asserts `allocation` field is None (E_ALLOCATION_ALREADY_SPECIFIED), enforcing ONE Allocation object per Order, ever. After alloc() executes, typical Rate-mode allocators (sum=10000, validated at allocation.move L162-163) and any Surplus-mode allocator drain balance to 0 via balance::withdraw_all (L254), making a second alloc() fail at `assert!(balance >= threshold)` (L193). EDGE CASE: Amount-mode-only allocators (no Surplus, total < full balance) leave remainder; a second alloc() could extract more — mitigated by preferring Rate/Surplus modes. External deposit via receive() (L291) is possible but irrational (attacker funds the Allocation they attack). Optional anti-reentrancy primitive: `order.allocation some` (query 1568) + logic_not",
         ],
         common_patterns: [
             "Node state check: query(Progress.current_node) + logic_equal('Completed')",
             "Amount threshold: query(Order.amount) + logic_as_u256_greater_or_equal(threshold)",
             "Multi-condition combination: logic_and (node state + amount + time)",
             "GuardIdentifier dynamic ratio: table[u64] extracts allocation ratio",
+            "Treasury+personal 2-allocator pattern: 2 Guard objects (identical root/table, different descriptions) + 2 allocators (sharing.who=Entity Treasury / Entity personal) — 2 alternative merchant collection approaches; first-match-wins means only the first executes.",
         ],
         mutable_after_publish: false,
         r_rounds_focus: ["R1", "R2", "R3", "R5", "R6", "R7"],
@@ -64,6 +71,7 @@ export const GUARD_SCENES = [
             "retained_submission indices must correspond to the Guard table",
             "Common queries: progress.current_node, progress.session_forward, order.service, etc.",
             "Time lock: context(Clock) + calc_number_add(progress.entry_time, duration) tested with 1000ms",
+            "Reentrancy: ALLOWED — By design, Forward moves progress.current_node to next_node (progress.move L443), naturally invalidating the Guard at the old node. Re-submission at the SAME node (before forward completes) is intentional: users may fix prior submission data or accumulate session weight toward threshold. No anti-reentrancy primitive needed. Optional observability queries: `progress.session_forward` (1262), `progress.history` (1273), `query_progress_history_find` (1274)",
         ],
         common_patterns: [
             "Identity check: context(Signer) + logic_equal (only specific parties can advance)",
@@ -88,6 +96,7 @@ export const GUARD_SCENES = [
             "Works in concert with Forward.guard: Forward.guard validates eligibility, submission guard validates data",
             "retained_submission stores submission data in Progress session for audit",
             "Common queries: progress.session_forward, progress.session_weight, etc.",
+            "Reentrancy: ALLOWED — Multiple submissions accumulate session weight toward threshold by design (progress.move session_accomplish_imp). Re-submission is the intended mechanism for reaching threshold; no anti-reentrancy primitive needed",
         ],
         common_patterns: [
             "Signature validation: identifier(signature_submission) + logic_equal(expected)",
@@ -110,6 +119,7 @@ export const GUARD_SCENES = [
             "Common query_reward_record_count prevents duplicate claims (one-time claim)",
             "Guard usually queries history records + time conditions + identity validation",
             "If the Reward references a Service, use the circular reference pattern",
+            "Reentrancy: CRITICAL — Guard pass distributes reward funds to the Claimant AND creates a reward_record, but the Guard conditions (identity, time, node state) do NOT naturally invalidate after a claim. Without an explicit anti-reentrancy primitive, the same Claimant can repeatedly pass the Guard and DRAIN THE ENTIRE POOL. This is the most severe reentrancy scene. REQUIRED anti-reentrancy primitive (any one): `reward.record has` (query 1613, Bool) + `logic_not`; OR `reward.record count` (query 1612, U64) + `logic_equal(0)`; OR `reward.record.find_first` (query 1626, U64) + `logic_not`/`logic_equal(0)`. Reference template: MyShop_Advanced Guard 7 condition 4 — `logic_not(query_reward_record_exists(where.storeFromId=order_id))`",
         ],
         common_patterns: [
             "One-time claim: query_reward_record_count(recipient) + logic_equal(0)",
@@ -134,6 +144,7 @@ export const GUARD_SCENES = [
             "The table entry referenced by data_from_submission must match the Repository's value_type",
             "Type mismatch leads to write failure or data corruption",
             "Commonly used for oracle data writes, third-party credential attestation, etc.",
+            "Reentrancy: LOW — Default writes are idempotent (same ID overwrites, different ID appends); no fund flow. IF business intent is 'one write per ID' (e.g. voting, immutable credential, single-attestation), an anti-reentrancy check is needed. Optional primitive: `repository.data has` (query 1166, Bool) + `logic_not`",
         ],
         common_patterns: [
             "Authorized writer: context(Signer) + vec_contains_address(authorized_writers)",
@@ -157,6 +168,7 @@ export const GUARD_SCENES = [
             "The customer must first generate a Passport (gen_passport passes usage_guard)",
             "Common queries: order.completed, order.service, entity.has, etc.",
             "Guard validates customer identity + order status + dispute eligibility",
+            "Reentrancy: HIGH — Guard pass creates a new Arb case. Without anti-reentrancy, a customer can create multiple Arb cases for the SAME Order (up to MAX_DISPUTE_COUNT=10 per order.move L96), harassing the counterparty and inflating arbitration system load. Not direct fund loss, but severe system abuse. Note: order::dispute (order.move L93-99) deduplicates by Arb address but does NOT prevent multiple distinct Arbs for the same Order. REQUIRED anti-reentrancy primitive (any one): `order.dispute has` (query 1565, Bool, per-Arb check) + `logic_not`; OR `order.dispute count` (query 1564, U64) + `logic_equal(0)` (strict: block any prior dispute) or `logic_as_u256_less_or_equal(N)` (lenient: allow up to N disputes)",
         ],
         common_patterns: [
             "Order status validation: query(Order.status) + logic_equal('completed')",
@@ -182,6 +194,7 @@ export const GUARD_SCENES = [
             "b_submission must be true (weight is submitted at runtime by the voter)",
             "Multiple voting_guards can be configured, each corresponding to a different voter group",
             "When Arbitration bPaused=true, voting is blocked",
+            "Reentrancy: CRITICAL — Guard pass counts the vote with the extracted weight. Without anti-reentrancy, the same voter can vote MULTIPLE times, multiplying their weight and skewing the arbitration result (which directly determines fund ownership via compensation). The voter's eligibility (identity, reputation) does NOT naturally invalidate after voting. REQUIRED anti-reentrancy primitive (any one): `arb.voted has` (query 1404, Bool, per-voter) + `logic_not`; OR `arb.voted.agree has` (query 1406, Bool, per-voter-per-proposition) + `logic_not`; OR `arb.voted.agree count` (query 1405, U64, per-voter) + `logic_equal(0)`. Note: `arb.voted_count` (1403) is total voter count (NOT per-voter) and does NOT serve as an anti-reentrancy primitive for individual voters",
         ],
         common_patterns: [
             "Reputation score weight: query(EntityRegistrar.records[reputation]) + GuardIdentifier(u64)",
@@ -208,6 +221,7 @@ export const GUARD_SCENES = [
             "Guard can be created standalone (not bound to a specific Host Object)",
             "Guard can be depended on by other Guards via rely (requires rep=true)",
             "The Passport generated by gen_passport can be used as submission data for subsequent operations",
+            "Reentrancy: LOW — Each gen_passport call generates an independent Passport (one Passport per operation). Multiple Passports for the same user are usually valid (each serves a different subsequent operation). IF business intent is 'one active Passport per user', an anti-reentrancy check is needed but no direct GUARDQUERY primitive exists — use off-chain tracking or a Repository to record issued Passport IDs",
         ],
         common_patterns: [
             "Identity validation: context(Signer) + logic_equal (single address/whitelist)",