@wowok/agent-mcp 2.6.3 → 2.6.6

package/dist/knowledge/guard-templates.js

@@ -1051,5 +1051,55 @@ export function validateTemplateParams(templateId, params) {
         .map((p) => p.name);
     return { valid: missing.length === 0, missing };
 }
+function deepSubstitute(obj, params) {
+    if (typeof obj === "string") {
+        const full = obj.match(/^\$\{(\w+)\}$/);
+        if (full && full[1] in params) {
+            return params[full[1]];
+        }
+        return obj.replace(/\$\{(\w+)\}/g, (_, key) => key in params ? String(params[key]) : `\${${key}}`);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => deepSubstitute(item, params));
+    }
+    if (obj && typeof obj === "object") {
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) {
+            result[k] = deepSubstitute(v, params);
+        }
+        return result;
+    }
+    return obj;
+}
+export function fillGuardTemplate(templateId, params) {
+    const template = getTemplateById(templateId);
+    if (!template) {
+        return { ok: false, error: `Template not found: ${templateId}` };
+    }
+    const { valid, missing } = validateTemplateParams(templateId, params);
+    if (!valid) {
+        return {
+            ok: false,
+            error: `Missing required parameters: ${missing.join(", ")}`,
+            missing,
+        };
+    }
+    const filled = { ...params };
+    for (const p of template.parameters) {
+        if (!(p.name in filled) && p.default !== undefined) {
+            filled[p.name] = p.default;
+        }
+    }
+    const table = deepSubstitute(template.example_table, filled);
+    const root = deepSubstitute(template.example_root, filled);
+    const leftover = JSON.stringify({ table, root }).match(/\$\{(\w+)\}/);
+    if (leftover) {
+        return {
+            ok: false,
+            error: `Unresolved placeholder \${${leftover[1]}} — not declared in template parameters`,
+        };
+    }
+    return { ok: true, table, root };
+}
 export const GUARD_TEMPLATES_VERSION = "1.0.0";
 export const GUARD_TEMPLATES_COUNT = GUARD_TEMPLATES.length;

package/dist/knowledge/index.d.ts

@@ -1,5 +1,5 @@
 import { CONCEPT_GLOSSARY, CONCEPT_GLOSSARY_VERSION, resolveTerm, lookupEntry, validateText, auditSchemaFields, type GlossaryEntry, type GlossaryCategory, type GlossaryDrift } from "./glossary.js";
-import { CONFIRMATION_RULES, SAFETY_RULES_VERSION, type ConfirmationRule, type OperationPreview, type ConfirmLevel } from "./safety-rules.js";
+import { CONFIRMATION_RULES, SAFETY_RULES_VERSION, OBJECT_REUSE_RULES, CREATE_VS_MODIFY_PATTERN, IMMUTABILITY_RULES, OPERATION_TYPE_CLASSIFICATION, OPERATION_CLASS_META, classifyTool, NAMING_CONVENTIONS, checkObjectReuseRules, checkImmutabilityRules, type ConfirmationRule, type OperationPreview, type ConfirmLevel, type ReuseRecommendation, type ObjectReuseRule, type ImmutabilityRule, type OperationClass, type OperationClassMeta, type SafetyRiskItem } from "./safety-rules.js";
 import { TOOL_CONSTRAINTS, TOOL_CONSTRAINTS_VERSION, validateOperation, hasBlockingViolations, getWarningViolations, type ConstraintSeverity, type FieldConstraint, type OperationConstraint, type ConstraintViolation } from "./tool-constraints.js";
 import { PERMISSION_TYPES, GAME_ELEMENTS, getPermissionType, getGameElement, getGameElementsByType, PROCESS_MODEL_VERSION, type PermissionScope, type PermissionTypeDef, type GameElementType, type GameElementDef } from "./process-model.js";
 import { computeTrustScore, quickRiskAssessment, ARBITRATION_TRUST_VERSION, type ArbMetrics, type TrustScore, type TrustComponent } from "./arbitration-trust.js";
@@ -105,7 +105,7 @@ import { TOOLS_REFERENCE, getToolReference, searchToolReference, getToolSequence
 import { SCENARIO_MODES, SCENARIO_MODES_VERSION, MODE_COMPOSITIONS, matchScenarioMode, inferScenarioTraits, getScenarioMode, listScenarioModes, getShippedModes, getModeCompositions, type IndustryModeName, type ScenarioTraits, type ModeAllocatorStrategy, type ModeGuardRef, type ModeMachineNode, type ScenarioMode, type ModeComposition } from "./scenario-modes.js";
 import { GUARD_DESIGN_PATTERNS, GUARD_DESIGN_PATTERNS_VERSION, VERIFIER_LEVEL_GUIDANCE, getGuardDesignPattern, searchGuardDesignPatterns, getPatternsByHost, getPatternsByIndustry, getPatternsByDataSourceClass, getVerifierLevelGuidance, suggestPatternForRequirement, type GuardDataSourceClass, type VerifierConstraintLevel, type GuardHostObject, type GuardDesignPattern, type VerifierLevelGuidance } from "./guard-design-patterns.js";
 export { CONCEPT_GLOSSARY, CONCEPT_GLOSSARY_VERSION, resolveTerm, lookupEntry, validateText, auditSchemaFields, type GlossaryEntry, type GlossaryCategory, type GlossaryDrift, };
-export { CONFIRMATION_RULES, SAFETY_RULES_VERSION, type ConfirmationRule, type OperationPreview, type ConfirmLevel, };
+export { CONFIRMATION_RULES, SAFETY_RULES_VERSION, OBJECT_REUSE_RULES, CREATE_VS_MODIFY_PATTERN, IMMUTABILITY_RULES, OPERATION_TYPE_CLASSIFICATION, OPERATION_CLASS_META, classifyTool, NAMING_CONVENTIONS, checkObjectReuseRules, checkImmutabilityRules, type ConfirmationRule, type OperationPreview, type ConfirmLevel, type ReuseRecommendation, type ObjectReuseRule, type ImmutabilityRule, type OperationClass, type OperationClassMeta, type SafetyRiskItem, };
 export { TOOL_CONSTRAINTS, TOOL_CONSTRAINTS_VERSION, validateOperation, hasBlockingViolations, getWarningViolations, type ConstraintSeverity, type FieldConstraint, type OperationConstraint, type ConstraintViolation, };
 export { PERMISSION_TYPES, GAME_ELEMENTS, getPermissionType, getGameElement, getGameElementsByType, PROCESS_MODEL_VERSION, type PermissionScope, type PermissionTypeDef, type GameElementType, type GameElementDef, };
 export { computeTrustScore, quickRiskAssessment, ARBITRATION_TRUST_VERSION, type ArbMetrics, type TrustScore, type TrustComponent, };

package/dist/knowledge/index.js

@@ -1,5 +1,5 @@
 import { CONCEPT_GLOSSARY, CONCEPT_GLOSSARY_VERSION, resolveTerm, lookupEntry, validateText, auditSchemaFields } from "./glossary.js";
-import { CONFIRMATION_RULES, SAFETY_RULES_VERSION } from "./safety-rules.js";
+import { CONFIRMATION_RULES, SAFETY_RULES_VERSION, OBJECT_REUSE_RULES, CREATE_VS_MODIFY_PATTERN, IMMUTABILITY_RULES, OPERATION_TYPE_CLASSIFICATION, OPERATION_CLASS_META, classifyTool, NAMING_CONVENTIONS, checkObjectReuseRules, checkImmutabilityRules } from "./safety-rules.js";
 import { TOOL_CONSTRAINTS, TOOL_CONSTRAINTS_VERSION, validateOperation, hasBlockingViolations, getWarningViolations, } from "./tool-constraints.js";
 import { PERMISSION_TYPES, GAME_ELEMENTS, getPermissionType, getGameElement, getGameElementsByType, PROCESS_MODEL_VERSION, } from "./process-model.js";
 import { computeTrustScore, quickRiskAssessment, ARBITRATION_TRUST_VERSION, } from "./arbitration-trust.js";
@@ -105,7 +105,7 @@ import { TOOLS_REFERENCE, getToolReference, searchToolReference, getToolSequence
 import { SCENARIO_MODES, SCENARIO_MODES_VERSION, MODE_COMPOSITIONS, matchScenarioMode, inferScenarioTraits, getScenarioMode, listScenarioModes, getShippedModes, getModeCompositions, } from "./scenario-modes.js";
 import { GUARD_DESIGN_PATTERNS, GUARD_DESIGN_PATTERNS_VERSION, VERIFIER_LEVEL_GUIDANCE, getGuardDesignPattern, searchGuardDesignPatterns, getPatternsByHost, getPatternsByIndustry, getPatternsByDataSourceClass, getVerifierLevelGuidance, suggestPatternForRequirement, } from "./guard-design-patterns.js";
 export { CONCEPT_GLOSSARY, CONCEPT_GLOSSARY_VERSION, resolveTerm, lookupEntry, validateText, auditSchemaFields, };
-export { CONFIRMATION_RULES, SAFETY_RULES_VERSION, };
+export { CONFIRMATION_RULES, SAFETY_RULES_VERSION, OBJECT_REUSE_RULES, CREATE_VS_MODIFY_PATTERN, IMMUTABILITY_RULES, OPERATION_TYPE_CLASSIFICATION, OPERATION_CLASS_META, classifyTool, NAMING_CONVENTIONS, checkObjectReuseRules, checkImmutabilityRules, };
 export { TOOL_CONSTRAINTS, TOOL_CONSTRAINTS_VERSION, validateOperation, hasBlockingViolations, getWarningViolations, };
 export { PERMISSION_TYPES, GAME_ELEMENTS, getPermissionType, getGameElement, getGameElementsByType, PROCESS_MODEL_VERSION, };
 export { computeTrustScore, quickRiskAssessment, ARBITRATION_TRUST_VERSION, };

package/dist/knowledge/machine-risk.js

@@ -123,7 +123,10 @@ export const MACHINE_RISK_RULES = [
             "dispute in the machine (e.g., 'disputed → refunded' forward guarded " +
             "by Permission index 1500) create dead-end paths because no one has " +
             "Permission 1500 — arbitrators are NOT Permission holders.",
-        detection: "Match node names against regex /^(disputed|refunded|arb|arbitration|dispute|refund)$/i",
+        detection: "Match node names against regex /(^|_)(disputed?|refund(?:ed)?|arbitration|arb)(_|$)/i " +
+            "(catches both exact names like 'refunded' and compound fund-flow terminals like " +
+            "'deposit_refunded'/'deposit_deducted'; business states like 'return_approved'/" +
+            "'damage_confirmed'/'cancelled'/'returned' do NOT match)",
         recommendation: "Remove all dispute/refund nodes from the machine. Instead: (1) bind an " +
             "Arbitration object to the Service via Service.arbitrations, (2) configure " +
             "arbitrators via Arbitration.voting_guard_add, (3) deposit compensation_fund " +

package/dist/knowledge/progress-context.js

@@ -336,7 +336,7 @@ export function buildPromptFromProgressContext(bundle) {
     }
     if (h.include_terminal_node_note) {
         lines.push("─ Terminal Node Note ──────────────");
-        lines.push("At terminal nodes (completed/enforced/deposit_refunded/paid), use progress::owner_receive");
+        lines.push("At terminal nodes (completed/enforced/return_approved/paid), use progress::owner_receive");
         lines.push("to unwrap Receiving<K> / CoinWrapper<T> via Payment.unwrap_with_check.");
         lines.push("Permission 225 (PROGRESS_OWNER_RECEIVE) required; recipient = Machine.permission owner.");
         lines.push("");

package/dist/knowledge/progress-ledger.js

@@ -177,7 +177,7 @@ export const PROGRESS_SCENES = [
         industry: ["finance", "treasury", "rental", "freelance"],
         scenario: "Owner receives Receiving<K> objects or CoinWrapper<T> coins sent to the Progress object. " +
             "unwrap → permission::owner_receive_inner forwards to Permission owner. " +
-            "Used at terminal nodes (deposit_refunded, completed, enforced) to disburse funds.",
+            "Used at terminal nodes (return_approved, completed, enforced) to disburse funds.",
         phases: ["owner_receive"],
         requires_published_machine: true,
         requires_order_bound: true,
@@ -189,7 +189,7 @@ export const PROGRESS_SCENES = [
         common_patterns: [
             "owner_receive unwraps CoinWrapper<T> via Payment.unwrap_with_check (amount validation)",
             "owner_receive_object receives a generic K:key+store object and forwards to Permission owner",
-            "Triggered at terminal nodes (e.g. 'deposit_refunded' in rental, 'enforced' in arbitration)",
+            "Triggered at terminal nodes (e.g. 'return_approved' in rental, 'enforced' in arbitration)",
             "Permission owner ≠ Progress creator: receives flow to whoever owns the bound Machine's Permission",
         ],
         recommended_templates: ["T-PR-06"],
@@ -326,5 +326,5 @@ export const PROGRESS_CROSS_OBJECT_REFS = [
     { object: "Passport", phase: "forward_advance", relationship: "Forward.guard (Some) requires Passport + passport::result_for_guard" },
     { object: "Passport", phase: "unhold_state", relationship: "unhold_with_passport: 224 check via passport (fallback when sender_has_permission_idcheck fails)" },
     { object: "Payment", phase: "owner_receive", relationship: "owner_receive unwraps CoinWrapper<T> via Payment.unwrap_with_check" },
-    { object: "Allocation", phase: "completed", relationship: "Terminal node triggers Allocation alloc (e.g. 'completed', 'enforced', 'deposit_refunded')" },
+    { object: "Allocation", phase: "completed", relationship: "Terminal node triggers Allocation alloc (e.g. 'completed', 'enforced', 'return_approved')" },
 ];

package/dist/knowledge/progress-templates.js

@@ -184,7 +184,7 @@ export const PROGRESS_TEMPLATES = [
         notes: [
             "Permission 225 (PROGRESS_OWNER_RECEIVE) is required; SDK CallProgress_Data does NOT expose this op",
             "Recipient is Permission owner (Machine.permission's owner), NOT Progress creator",
-            "Triggered at terminal nodes: 'deposit_refunded', 'completed', 'enforced', 'paid'",
+            "Triggered at terminal nodes: 'return_approved', 'completed', 'enforced', 'paid'",
             "For coins: Payment.unwrap_with_check validates amount before forwarding to owner",
             "For objects: generic K:key+store — forwarded directly via permission::owner_receive_inner",
         ],

package/dist/knowledge/progress-translation.js

@@ -128,7 +128,7 @@ export const PROGRESS_SEMANTIC_TO_SCHEMA_RULES = [
             arguments: ["progress", "machine", "permission", "received", "payment"],
         },
         reverse_explanation: "Calls progress::owner_receive (225 permission). Unwraps CoinWrapper<T> via Payment.unwrap_with_check, " +
-            "forwards coin/object to Permission owner. Typically triggered at terminal nodes (deposit_refunded, completed, enforced).",
+            "forwards coin/object to Permission owner. Typically triggered at terminal nodes (return_approved, completed, enforced).",
     },
 ];
 export const PROGRESS_SCHEMA_TO_SEMANTIC_RULES = [

package/dist/knowledge/safety-rules.d.ts

@@ -33,4 +33,86 @@ export declare function getAmountThreshold(): bigint;
 export declare function formatAmount(value: string | bigint, precision?: bigint): string;
 export declare function collectDefaultWarnings(env: any, data: any): string[];
 export declare const CONFIRMATION_RULES: ConfirmationRule[];
-export declare const SAFETY_RULES_VERSION = 1;
+export declare function extractAmount(data: any): string | null;
+export type ReuseRecommendation = "always_reuse" | "strongly_recommended" | "recommended" | "optional";
+export interface ObjectReuseRule {
+    rule_id: string;
+    object_type: string;
+    recommendation: ReuseRecommendation;
+    reason: string;
+    ask_user: string;
+}
+export declare const OBJECT_REUSE_RULES: readonly ObjectReuseRule[];
+export declare const CREATE_VS_MODIFY_PATTERN: {
+    readonly reuse_form: "string";
+    readonly create_form: "object";
+    readonly resolution_api: "GetObjectExisted";
+    readonly note: "String reference = REUSE (name resolution failure is a hard error); object shape = CREATE (always).";
+};
+export interface ImmutabilityRule {
+    rule_id: string;
+    object_type: string;
+    trigger: "create" | "publish";
+    immutable_fields: string[];
+    mutable_after?: string[];
+    message: string;
+}
+export declare const IMMUTABILITY_RULES: readonly ImmutabilityRule[];
+export type OperationClass = "LOCAL_ONLY" | "ONCHAIN" | "QUERY" | "ENCRYPTED";
+export declare const OPERATION_TYPE_CLASSIFICATION: Record<OperationClass, readonly string[]>;
+export interface OperationClassMeta {
+    gas: boolean;
+    confirmation_required: boolean;
+    note: string;
+}
+export declare const OPERATION_CLASS_META: Record<OperationClass, OperationClassMeta>;
+export declare function classifyTool(toolName: string): OperationClass | undefined;
+export declare const NAMING_CONVENTIONS: {
+    readonly scheme: "<projectPrefix>_<type>_<purpose>_<version>";
+    readonly parts: {
+        readonly project_prefix: {
+            readonly example: "shopFunny_";
+            readonly purpose: "Prevents cross-project collisions";
+        };
+        readonly type_prefix: {
+            readonly example: "machine_ / guard_ / service_";
+            readonly purpose: "Clarifies object type";
+        };
+        readonly purpose_suffix: {
+            readonly example: "serviceWithdraw";
+            readonly purpose: "Describes function";
+        };
+        readonly version_suffix: {
+            readonly example: "_v2";
+            readonly purpose: "Enables iteration without replaceExistName";
+        };
+    };
+    readonly entry_id: {
+        readonly pattern: "^<object_type>:<name>$";
+        readonly example: "service:myshop_service";
+    };
+    readonly replace_exist_name: {
+        readonly default: false;
+        readonly false_effect: "Throws error if name is in use — safe default";
+        readonly true_effect: "Existing object/account with the same name is suspended/unbound to free the name";
+        readonly account_default_forbidden: "replaceExistName:true on the default account (name='') is FORBIDDEN — use suspend() explicitly";
+        readonly recommendation: "DISCOURAGED — prefer versioned names (_v1, _v2) for production";
+    };
+    readonly recommendations: readonly ["Always provide tags on object creation for filtering and management", "Use names as primary identifiers; use short address form (0x1234...def) only for display", "All cross-object references (Guard tables, Service bindings, Machine forwards) use NAMES — resolved per-network at build time"];
+};
+export interface SafetyRiskItem {
+    rule_id: string;
+    severity: "info" | "warn";
+    message: string;
+}
+export declare function checkObjectReuseRules(planned: readonly {
+    object_type: string;
+    is_new: boolean;
+    name?: string;
+}[]): SafetyRiskItem[];
+export declare function checkImmutabilityRules(ops: readonly {
+    object_type: string;
+    trigger: "create" | "publish";
+    name?: string;
+}[]): SafetyRiskItem[];
+export declare const SAFETY_RULES_VERSION = 2;

package/dist/knowledge/safety-rules.js

@@ -217,7 +217,7 @@ export const CONFIRMATION_RULES = [
         bypass_on_explicit_intent: ["test guard", "testing guard", "gen passport", "generate passport"],
     },
 ];
-function extractAmount(data) {
+export function extractAmount(data) {
     if (!data)
         return null;
     const candidates = [
@@ -237,4 +237,168 @@ function extractAmount(data) {
     }
     return null;
 }
-export const SAFETY_RULES_VERSION = 1;
+export const OBJECT_REUSE_RULES = [
+    {
+        rule_id: "REUSE-001",
+        object_type: "permission",
+        recommendation: "strongly_recommended",
+        reason: "Centralized permission control across all services",
+        ask_user: "Do you have an existing Permission to reuse? Provide the name or ID.",
+    },
+    {
+        rule_id: "REUSE-002",
+        object_type: "machine",
+        recommendation: "recommended",
+        reason: "Save design time for similar processes",
+        ask_user: "Do you have an existing Machine whose workflow fits? Provide the name or ID.",
+    },
+    {
+        rule_id: "REUSE-003",
+        object_type: "guard",
+        recommendation: "recommended",
+        reason: "Avoid redundant validation rules",
+        ask_user: "Do you have an existing Guard with matching validation logic? Provide the name or ID.",
+    },
+    {
+        rule_id: "REUSE-004",
+        object_type: "contact",
+        recommendation: "recommended",
+        reason: "Single point of customer-service management",
+        ask_user: "Do you have an existing Contact for customer service? Provide the name or ID.",
+    },
+    {
+        rule_id: "REUSE-005",
+        object_type: "arbitration",
+        recommendation: "always_reuse",
+        reason: "Customers choose from established arbiters; creating a new Arbitration is an operator-level decision",
+        ask_user: "Which existing Arbitration service should disputes route to? Provide the name or ID.",
+    },
+];
+export const CREATE_VS_MODIFY_PATTERN = {
+    reuse_form: "string",
+    create_form: "object",
+    resolution_api: "GetObjectExisted",
+    note: "String reference = REUSE (name resolution failure is a hard error); object shape = CREATE (always).",
+};
+export const IMMUTABILITY_RULES = [
+    {
+        rule_id: "IMMUT-001",
+        object_type: "machine",
+        trigger: "publish",
+        immutable_fields: ["nodes", "pairs", "forwards"],
+        message: "Machine topology is immutable after publish — verify all nodes/forwards via machineNode2file BEFORE publishing",
+    },
+    {
+        rule_id: "IMMUT-002",
+        object_type: "service",
+        trigger: "publish",
+        immutable_fields: ["machine", "order_allocators", "arbitrations"],
+        mutable_after: ["sales"],
+        message: "Service.machine, order_allocators and arbitrations are frozen after publish; sales remains fully modifiable (L3) without pause",
+    },
+    {
+        rule_id: "IMMUT-003",
+        object_type: "guard",
+        trigger: "create",
+        immutable_fields: ["table", "root", "rely"],
+        message: "Guard is CREATE-only and immutable — cannot be edited or deleted after creation. To change: export via guard2file → edit → CREATE new → rebind",
+    },
+];
+export const OPERATION_TYPE_CLASSIFICATION = {
+    LOCAL_ONLY: [
+        "account_operation",
+        "local_mark_operation",
+        "local_info_operation",
+        "project_operation",
+        "config_operation",
+    ],
+    ONCHAIN: [
+        "onchain_operations",
+        "wip_file",
+        "bridge_operation",
+        "messenger_operation",
+    ],
+    QUERY: [
+        "query_toolkit",
+        "onchain_table_data",
+        "onchain_events",
+        "guard2file",
+        "machineNode2file",
+        "schema_query",
+        "wowok_buildin_info",
+        "trust_score",
+    ],
+    ENCRYPTED: [
+        "messenger_operation",
+    ],
+};
+export const OPERATION_CLASS_META = {
+    LOCAL_ONLY: { gas: false, confirmation_required: false, note: "Local state only — no gas, no confirmation needed" },
+    ONCHAIN: { gas: true, confirmation_required: true, note: "On-chain write — gas consumed, explicit user confirmation REQUIRED before execution" },
+    QUERY: { gas: false, confirmation_required: false, note: "Read-only — no gas, no confirmation needed" },
+    ENCRYPTED: { gas: false, confirmation_required: false, note: "Local encryption — no gas, no confirmation needed" },
+};
+export function classifyTool(toolName) {
+    if (OPERATION_TYPE_CLASSIFICATION.ENCRYPTED.includes(toolName))
+        return "ENCRYPTED";
+    for (const cls of ["LOCAL_ONLY", "ONCHAIN", "QUERY"]) {
+        if (OPERATION_TYPE_CLASSIFICATION[cls].includes(toolName))
+            return cls;
+    }
+    return undefined;
+}
+export const NAMING_CONVENTIONS = {
+    scheme: "<projectPrefix>_<type>_<purpose>_<version>",
+    parts: {
+        project_prefix: { example: "shopFunny_", purpose: "Prevents cross-project collisions" },
+        type_prefix: { example: "machine_ / guard_ / service_", purpose: "Clarifies object type" },
+        purpose_suffix: { example: "serviceWithdraw", purpose: "Describes function" },
+        version_suffix: { example: "_v2", purpose: "Enables iteration without replaceExistName" },
+    },
+    entry_id: { pattern: "^<object_type>:<name>$", example: "service:myshop_service" },
+    replace_exist_name: {
+        default: false,
+        false_effect: "Throws error if name is in use — safe default",
+        true_effect: "Existing object/account with the same name is suspended/unbound to free the name",
+        account_default_forbidden: "replaceExistName:true on the default account (name='') is FORBIDDEN — use suspend() explicitly",
+        recommendation: "DISCOURAGED — prefer versioned names (_v1, _v2) for production",
+    },
+    recommendations: [
+        "Always provide tags on object creation for filtering and management",
+        "Use names as primary identifiers; use short address form (0x1234...def) only for display",
+        "All cross-object references (Guard tables, Service bindings, Machine forwards) use NAMES — resolved per-network at build time",
+    ],
+};
+export function checkObjectReuseRules(planned) {
+    const risks = [];
+    for (const p of planned) {
+        if (!p.is_new)
+            continue;
+        const rule = OBJECT_REUSE_RULES.find((r) => r.object_type === p.object_type);
+        if (!rule)
+            continue;
+        if (rule.recommendation === "always_reuse" || rule.recommendation === "strongly_recommended") {
+            risks.push({
+                rule_id: rule.rule_id,
+                severity: rule.recommendation === "always_reuse" ? "warn" : "info",
+                message: `Creating NEW ${p.object_type}${p.name ? ` "${p.name}"` : ""} — reuse is ${rule.recommendation}: ${rule.reason}. ${rule.ask_user}`,
+            });
+        }
+    }
+    return risks;
+}
+export function checkImmutabilityRules(ops) {
+    const risks = [];
+    for (const op of ops) {
+        const rule = IMMUTABILITY_RULES.find((r) => r.object_type === op.object_type && r.trigger === op.trigger);
+        if (!rule)
+            continue;
+        risks.push({
+            rule_id: rule.rule_id,
+            severity: "warn",
+            message: `${op.object_type}${op.name ? ` "${op.name}"` : ""} ${op.trigger}: ${rule.message}. Immutable: [${rule.immutable_fields.join(", ")}]${rule.mutable_after ? `. Still mutable: [${rule.mutable_after.join(", ")}]` : ""}`,
+        });
+    }
+    return risks;
+}
+export const SAFETY_RULES_VERSION = 2;

package/dist/knowledge/scenario-modes.d.ts

@@ -50,4 +50,4 @@ export declare function getScenarioMode(name: IndustryModeName): ScenarioMode |
 export declare function listScenarioModes(): ScenarioMode[];
 export declare function getShippedModes(): ScenarioMode[];
 export declare function getModeCompositions(name: IndustryModeName): ModeComposition[];
-export declare const SCENARIO_MODES_VERSION = 1;
+export declare const SCENARIO_MODES_VERSION = 2;

package/dist/knowledge/scenario-modes.js

@@ -18,8 +18,7 @@ export const SCENARIO_MODES = [
             { name: "delivered", role: "Deliverable available for review" },
             { name: "accepted", role: "Customer signs acceptance" },
             { name: "completed", role: "Funds released to provider" },
-            { name: "refunded", role: "Customer-initiated refund path" },
-            { name: "cancelled", role: "Pre-delivery cancellation" },
+            { name: "cancelled", role: "Pre-delivery cancellation — triggers refund Allocator" },
         ],
         guards: [
             { template_id: "buy_guard_identity", host: "service", purpose: "Customer identity check on purchase" },
@@ -33,13 +32,14 @@ export const SCENARIO_MODES = [
             recipient: "signer",
             count: 2,
             mode: "amount",
-            description: "100% to provider on accepted; 100% refund to customer on refunded",
+            description: "100% to provider on completed; 100% refund to customer on cancelled (refund Allocator, off-Machine fund routing per R-M1-11)",
         },
         key_risk: "Customer never accepts delivery — provider cannot get paid",
         build_notes: [
             "Use Service `setting_locked_time` to lock rules for the engagement duration",
             "WIP hash on deliverable is mandatory — protects provider in disputes",
             "Acceptance gate is the trust pivot — both parties must agree on criteria",
+            "R-M1-11: no 'refunded'/'disputed'/'arb' nodes — refunds route via Allocator (100% to OrderHolder) triggered by 'cancelled', disputes via Arbitration",
             "NEW: Payment exception compensation for delivery delays — provider Treasury auto-compensates customer (§2.13)",
         ],
     },
@@ -62,8 +62,9 @@ export const SCENARIO_MODES = [
             { name: "in_use", role: "Rental period active" },
             { name: "returned", role: "Customer returns item" },
             { name: "inspected", role: "Owner inspects returned item" },
-            { name: "deposit_refunded", role: "No damage — full deposit returned" },
-            { name: "deposit_deducted", role: "Damage found — deposit partially deducted" },
+            { name: "return_approved", role: "No damage — triggers deposit refund Allocator (100% to customer)" },
+            { name: "damage_confirmed", role: "Damage confirmed via pre+post WIP diff — triggers deposit deduction Allocator" },
+            { name: "completed", role: "Rental finalized — triggers rent Allocator (rent to owner)" },
         ],
         guards: [
             { template_id: "deposit_guard_amount", host: "service", purpose: "Verify deposit amount matches listing" },
@@ -78,13 +79,14 @@ export const SCENARIO_MODES = [
             recipient: "entity",
             count: 3,
             mode: "amount",
-            description: "Rent to owner; refund to customer; deduction to owner (damage case)",
+            description: "Rent to owner on completed; deposit refund to customer on return_approved; deposit deduction to owner on damage_confirmed (fund routing via Allocator per R-M1-11)",
         },
         key_risk: "Owner claims damage without pre-rental WIP — customer loses deposit unfairly",
         build_notes: [
             "Pre-rental WIP is non-negotiable — without it, damage claims fail",
             "Deposit must be escrowed, not direct-transferred — enables fair deduction",
             "Inspection gate prevents customer from denying damage",
+            "R-M1-11: no 'deposit_refunded'/'deposit_deducted'/'refunded' nodes — deposit refund/deduction flows through Allocator triggered by return_approved/damage_confirmed business states",
             "NEW: Payment exception compensation for return delays — Treasury withdraws scene-bound Payment (§2.13)",
             "NEW: Repository quote_guard for weather/usage data subscription revenue (§2.11)",
         ],
@@ -106,7 +108,7 @@ export const SCENARIO_MODES = [
             { name: "paid", role: "Entry: enrollment and tuition paid via Service.buy(); Machine starts here" },
             { name: "session_N", role: "Per-session attendance (1..N)" },
             { name: "completed", role: "All sessions delivered" },
-            { name: "refunded", role: "Institution-approved refund" },
+            { name: "withdrawn", role: "Enrollment cancelled mid-course — triggers unearned-tuition refund Allocator" },
         ],
         guards: [
             { template_id: "attendance_guard_signer", host: "machine", purpose: "Per-session student attendance signature" },
@@ -117,7 +119,7 @@ export const SCENARIO_MODES = [
             recipient: "entity",
             count: 1,
             mode: "amount",
-            description: "1/N of tuition released per session attendance; unearned portion refundable",
+            description: "1/N of tuition released per session attendance; unearned portion refunded to student via Allocator on withdrawn (per R-M1-11)",
         },
         key_risk: "Tutoring institutions run away with prepaid tuition",
         build_notes: [
@@ -147,7 +149,7 @@ export const SCENARIO_MODES = [
             { name: "segment_D2", role: "Segment 2 (e.g., guided tour)" },
             { name: "returned", role: "Trip completed, customer returns" },
             { name: "completed", role: "All segments delivered, funds released" },
-            { name: "refunded", role: "Trip interruption refund" },
+            { name: "interrupted", role: "Trip interrupted — triggers refund Allocator (undelivered segments) or Arbitration" },
         ],
         guards: [
             { template_id: "segment_guard_wip", host: "machine", purpose: "Per-segment arrival WIP (hotel check-in, etc.)" },
@@ -160,7 +162,7 @@ export const SCENARIO_MODES = [
             recipient: "entity",
             count: 3,
             mode: "amount",
-            description: "Deposit 20% to agency, final 80% to agency, then agency-side Allocation splits to hotel/guide/driver per segment",
+            description: "Deposit 20% to agency, final 80% to agency, then agency-side Allocation splits to hotel/guide/driver per segment; undelivered segments refunded to customer via Allocator on interrupted (per R-M1-11)",
         },
         key_risk: "Paid in full then service shrinks — multi-tier transparency prevents this",
         build_notes: [
@@ -316,4 +318,4 @@ export function getShippedModes() {
 export function getModeCompositions(name) {
     return MODE_COMPOSITIONS.filter((c) => c.modes.includes(name));
 }
-export const SCENARIO_MODES_VERSION = 1;
+export const SCENARIO_MODES_VERSION = 2;

package/dist/knowledge/template-registry.d.ts

@@ -0,0 +1,48 @@
+export declare const TEMPLATE_REGISTRY_VERSION = 1;
+export type TemplateObjectType = "guard" | "machine" | "service" | "order" | "progress" | "arbitration" | "treasury" | "permission" | "passport" | "allocation" | "reward";
+export declare const TEMPLATE_OBJECT_TYPES: readonly TemplateObjectType[];
+export type UnifiedTemplateParamDefault = string | number | boolean | object | string[];
+export interface UnifiedTemplateParam {
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+    default?: UnifiedTemplateParamDefault;
+    constraint?: string;
+}
+export interface UnifiedTemplateMeta {
+    id: string;
+    object_type: TemplateObjectType;
+    name: string;
+    description: string;
+    scenes: string[];
+    industries: string[];
+    instantiable: boolean;
+    parameters: UnifiedTemplateParam[];
+}
+export type InstantiateTemplateResult = {
+    ok: true;
+    object_type: TemplateObjectType;
+    template_id: string;
+    body: unknown;
+    notes?: string[];
+} | {
+    ok: false;
+    object_type: TemplateObjectType | null;
+    template_id: string;
+    error: string;
+    missing_params?: string[];
+    guidance?: unknown;
+};
+type AnyParams = Record<string, unknown>;
+export declare function getTemplateIdCollisions(): string[];
+export declare function getTemplateCounts(): Record<TemplateObjectType, number>;
+export declare function listTemplates(objectType?: TemplateObjectType): UnifiedTemplateMeta[];
+export declare function getTemplateDetail(templateId: string): (UnifiedTemplateMeta & {
+    raw: unknown;
+    notes?: string[];
+    guidance?: unknown;
+}) | null;
+export declare function findTemplateObjectType(templateId: string): TemplateObjectType | null;
+export declare function instantiateTemplate(templateId: string, params: AnyParams): InstantiateTemplateResult;
+export {};