@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/order-translation.js

@@ -0,0 +1,550 @@
+import { MAX_AGENT_COUNT, MAX_DISPUTE_COUNT, } from "@wowok/wowok";
+import { ORDER_SCENES, inferSceneFromIntent, } from "./order-ledger.js";
+export const SEMANTIC_TO_SCHEMA_RULES = [
+    {
+        id: "P-O-01",
+        pattern_name: "Create Order via service::buy (compound creation)",
+        semantic_intent: "Buy items from a Service — atomically creates Order + Allocation + Progress, snapshots service.machine, emits NewOrderEvent",
+        match_keywords: ["buy", "purchase", "order"],
+        schema_fields: ["(via service::buy, not direct order::create)"],
+        example_json: {
+            _note: "Order is NOT created via CallOrder_Data. It is created via service::buy() which internally calls order::new + order::create.",
+            _call_target: "service",
+            object: "0xSERVICE_ADDRESS",
+            buy: {
+                items: [{ name: "Product A", price: "1000000000", quantity: 1, wip_hash: "0xABC..." }],
+                discount: null,
+                named_order: "my_order_alias",
+                machine_forward: null,
+            },
+        },
+        reverse_explanation: "Order creation is composite — service::buy atomically builds Order + Allocation + Progress + emits NewOrderEvent. order::create is package-only.",
+        operation_field: "object",
+        permission_layer: "L3_package_only",
+    },
+    {
+        id: "P-O-02",
+        pattern_name: "Advance Progress (forward/hold)",
+        semantic_intent: "Advance Order's Progress to next node via forward or hold",
+        match_keywords: ["advance", "forward", "progress", "next"],
+        schema_fields: ["object", "progress"],
+        example_json: {
+            object: "0xORDER_ADDRESS",
+            progress: {
+                next_node_name: "shipped",
+                forward: { name: "deliver", operator: null, guard: null },
+                op: "next",
+                message: "Order dispatched",
+            },
+        },
+        reverse_explanation: "progress.forward triggers Progress::operate → order.progress node transition. Both owner and agent can advance (L2).",
+        operation_field: "progress",
+        permission_layer: "L2_owner_or_agent",
+    },
+    {
+        id: "P-O-03",
+        pattern_name: "Set agent list (owner-only, pre-progress)",
+        semantic_intent: "Replace the entire agent list. Frozen after Progress binding.",
+        match_keywords: ["set agent", "agent", "delegate"],
+        schema_fields: ["object", "agent"],
+        example_json: {
+            object: "0xORDER_ADDRESS",
+            agent: ["0xAGENT1", "0xAGENT2"],
+        },
+        reverse_explanation: "agent field overwrites entire agent list. Owner-only (L1). Aborts E_PROGRESS_NOT_SPECIFIED if Progress already bound. ⚠️ Boundary bug: actual max 11 (not 10).",
+        operation_field: "agent",
+        permission_layer: "L1_owner_only",
+    },
+    {
+        id: "P-O-04",
+        pattern_name: "Set required_info (Contact or WTS Proof)",
+        semantic_intent: "Update recipient contact or delivery proof. Both owner and agent can update.",
+        match_keywords: ["required_info", "recipient", "contact", "wts proof"],
+        schema_fields: ["object", "required_info"],
+        example_json: {
+            object: "0xORDER_ADDRESS",
+            required_info: "0xCONTACT_ADDRESS",
+        },
+        reverse_explanation: "required_info accepts Contact object (recipient) or WTS Proof object (delivery proof). null clears. L2 (owner or agent).",
+        operation_field: "required_info",
+        permission_layer: "L2_owner_or_agent",
+    },
+    {
+        id: "P-O-05",
+        pattern_name: "Apply for arbitration (arb_confirm)",
+        semantic_intent: "File arbitration with confirm/deny + description + proposition. Triggers dispute() appending Arb to order.dispute.",
+        match_keywords: ["arb_confirm", "apply arbitration", "file dispute", "compensation"],
+        schema_fields: ["object", "arb_confirm"],
+        example_json: {
+            object: "0xORDER_ADDRESS",
+            arb_confirm: {
+                arb: "0xARB_ADDRESS",
+                confirm: true,
+                description: "Item never arrived",
+                proposition: ["Refund full amount", "Compensation for delay"],
+            },
+        },
+        reverse_explanation: "arb_confirm triggers arb::principal_confirm + arb::description_change + arb::proposition_change, and Arb module calls order::dispute(arb) to append. L2.",
+        operation_field: "arb_confirm",
+        permission_layer: "L2_owner_or_agent",
+    },
+    {
+        id: "P-O-06",
+        pattern_name: "Object to arbitration (arb_objection)",
+        semantic_intent: "Object to Arb ruling and request re-arbitration",
+        match_keywords: ["arb_objection", "object", "appeal"],
+        schema_fields: ["object", "arb_objection"],
+        example_json: {
+            object: "0xORDER_ADDRESS",
+            arb_objection: {
+                arb: "0xARB_ADDRESS",
+                objection: "Evidence was not properly reviewed",
+            },
+        },
+        reverse_explanation: "arb_objection triggers arb::objection. Requires Arb status = Arbitrated. L2 (owner or agent). Irreversible.",
+        operation_field: "arb_objection",
+        permission_layer: "L2_owner_or_agent",
+    },
+    {
+        id: "P-O-07",
+        pattern_name: "Claim compensation (arb_claim_compensation)",
+        semantic_intent: "Claim compensation from a ruled Arb. Sets claimed_by — ONE-TIME, IRREVERSIBLE, blocks future disputes.",
+        match_keywords: ["arb_claim_compensation", "claim", "compensation"],
+        schema_fields: ["object", "arb_claim_compensation"],
+        example_json: {
+            object: "0xORDER_ADDRESS",
+            arb_claim_compensation: {
+                arb: "0xRULED_ARB_ADDRESS",
+            },
+        },
+        reverse_explanation: "arb_claim_compensation triggers service::compensation_claim → order::compensate(arb) → sets claimed_by=arb. IRREVERSIBLE. L2.",
+        operation_field: "arb_claim_compensation",
+        permission_layer: "L2_owner_or_agent",
+    },
+    {
+        id: "P-O-08",
+        pattern_name: "Receive payment/objects (owner-only)",
+        semantic_intent: "Receive CoinWrapper or arbitrary Receiving<K> from Progress. Funds forwarded to owner.",
+        match_keywords: ["receive", "collect", "extract"],
+        schema_fields: ["object", "receive"],
+        example_json: {
+            object: "0xORDER_ADDRESS",
+            receive: {
+                received: "0xRECEIVING_OBJECT_ID",
+            },
+        },
+        reverse_explanation: "receive calls order::owner_receive or owner_receive_object. Owner-only (L1) — agent CANNOT receive. Aborts E_ORDER_DELIVERING if Progress not at terminal.",
+        operation_field: "receive",
+        permission_layer: "L1_owner_only",
+    },
+    {
+        id: "P-O-09",
+        pattern_name: "Transfer ownership (transfer_to)",
+        semantic_intent: "Transfer Order ownership to new address. IRREVERSIBLE. New owner takes over ALL permissions.",
+        match_keywords: ["transfer", "transfer_to", "handover"],
+        schema_fields: ["object", "transfer_to"],
+        example_json: {
+            object: "0xORDER_ADDRESS",
+            transfer_to: "0xNEW_OWNER_ADDRESS",
+        },
+        reverse_explanation: "transfer_to calls order::owner_change(new_owner). Owner-only (L1). IRREVERSIBLE. Unlike agent_set, can be called after Progress binding.",
+        operation_field: "transfer_to",
+        permission_layer: "L1_owner_only",
+    },
+    {
+        id: "P-O-10",
+        pattern_name: "Query Order state (read-only)",
+        semantic_intent: "Read Order fields: items, amount, owner/builder, agent, dispute, claimed_by, progress, machine, time",
+        match_keywords: ["query", "read", "check", "status"],
+        schema_fields: ["(read-only via query layer, not CallOrder_Data)"],
+        example_json: {
+            _note: "Query uses the query/object endpoint, not CallOrder_Data",
+            _call_target: "query",
+            object: "0xORDER_ADDRESS",
+            fields: ["items", "amount", "owner", "agent", "dispute", "claimed_by", "progress", "machine"],
+        },
+        reverse_explanation: "Query is read-only — does not modify state. Use to verify state before any L1/L2 operation. SDK ObjectOrder returns all 14 fields.",
+        operation_field: "object",
+    },
+    {
+        id: "P-O-11",
+        pattern_name: "Query Order history (event log)",
+        semantic_intent: "Query Order lifecycle events. ⚠️ Only NewOrderEvent is actually emitted — other events must be INFERRED from field changes.",
+        match_keywords: ["history", "events", "lifecycle", "audit"],
+        schema_fields: ["(read-only via query layer, event filter)"],
+        example_json: {
+            _note: "Only NewOrderEvent is emitted on-chain. Other lifecycle events must be inferred by querying Order field diffs over time.",
+            _call_target: "query",
+            object: "0xORDER_ADDRESS",
+            event_filter: { type: "order::NewOrderEvent" },
+        },
+        reverse_explanation: "Audit weakness: only 1 of 11 lifecycle events is actually emitted. Use status_inference formula from ORDER_AUDIT_FORMULAS to derive state.",
+        operation_field: "object",
+    },
+    {
+        id: "P-O-12",
+        pattern_name: "Monitor Order status changes (polling)",
+        semantic_intent: "Poll Order status to detect: Progress advance, dispute append, claimed_by set, ownership transfer",
+        match_keywords: ["monitor", "poll", "watch", "track"],
+        schema_fields: ["(read-only via query layer, polling)"],
+        example_json: {
+            _note: "Monitor by querying Order at intervals and diffing fields",
+            _call_target: "query",
+            object: "0xORDER_ADDRESS",
+            poll_interval_ms: 5000,
+            watch_fields: ["progress", "dispute", "claimed_by", "owner"],
+        },
+        reverse_explanation: "No push notifications — must poll. Track 4 critical fields: progress (advance), dispute (new arb), claimed_by (terminal), owner (transfer).",
+        operation_field: "object",
+    },
+];
+export const SCHEMA_TO_SEMANTIC_RULES = [
+    {
+        element_type: "field",
+        type_name: "object",
+        semantic_explanation: "Order object address. STRING=operate existing Order. null/omitted is invalid (Order creation goes through service::buy).",
+        constraints: ["Must be valid Order object ID", "Order must exist on-chain"],
+    },
+    {
+        element_type: "field",
+        type_name: "agent",
+        semantic_explanation: "Agent address list (overwrites entire list). Owner-only (L1). Frozen after Progress binding. ⚠️ Boundary bug: actual max 11 (not 10).",
+        constraints: [`<= ${MAX_AGENT_COUNT} agents (doc) / 11 (actual bug)`, "Owner-only", "Frozen after Progress binding"],
+    },
+    {
+        element_type: "field",
+        type_name: "required_info",
+        semantic_explanation: "Contact object (recipient info) or WTS Proof object (delivery proof). null clears. L2 (owner or agent).",
+        constraints: ["Must be Contact or WTS Proof object", "null clears the field"],
+    },
+    {
+        element_type: "field",
+        type_name: "progress",
+        semantic_explanation: "Progress operation object — advance via forward/hold. Both owner and agent can advance. Node transition is irreversible.",
+        constraints: ["Requires Progress binding (order.progress.is_some())", "L2 (owner or agent)", "Node transition irreversible"],
+    },
+    {
+        element_type: "field",
+        type_name: "arb_confirm",
+        semantic_explanation: "Apply for arbitration compensation. Triggers dispute() appending Arb to order.dispute. L2. Irreversible.",
+        constraints: ["Arb must exist", "L2 (owner or agent)", "claimed_by must be None"],
+    },
+    {
+        element_type: "field",
+        type_name: "arb_objection",
+        semantic_explanation: "Object to Arb ruling and request re-arbitration. Requires Arb status = Arbitrated. L2. Irreversible.",
+        constraints: ["Arb must be in Arbitrated state", "L2 (owner or agent)"],
+    },
+    {
+        element_type: "field",
+        type_name: "arb_claim_compensation",
+        semantic_explanation: "Claim compensation from ruled Arb. Sets claimed_by. ONE-TIME, IRREVERSIBLE, blocks future disputes. L2.",
+        constraints: ["Arb must be Arbitrated", "claimed_by must be None", "L2 (owner or agent)", "IRREVERSIBLE"],
+    },
+    {
+        element_type: "field",
+        type_name: "receive",
+        semantic_explanation: "Receive CoinWrapper or arbitrary Receiving<K> from Progress. Funds forwarded to owner. Owner-only (L1) — agent CANNOT.",
+        constraints: ["Owner-only (L1)", "Progress must be at terminal node (not delivering)", "Can be called multiple times"],
+    },
+    {
+        element_type: "field",
+        type_name: "transfer_to",
+        semantic_explanation: "New owner address for ownership transfer. IRREVERSIBLE. New owner takes over ALL permissions. Owner-only (L1).",
+        constraints: ["Owner-only (L1)", "IRREVERSIBLE", "Valid Wow address"],
+    },
+    {
+        element_type: "op",
+        type_name: "forward",
+        semantic_explanation: "Advance Progress to next node via named forward. Triggers Progress::operate.",
+        constraints: ["Forward name must exist on current node", "Guard (if any) must pass"],
+    },
+    {
+        element_type: "op",
+        type_name: "hold",
+        semantic_explanation: "Hold at current Progress node (optional pause).",
+        constraints: ["Node must support hold"],
+    },
+    {
+        element_type: "op",
+        type_name: "confirm",
+        semantic_explanation: "In arb_confirm: true=confirm materials valid, false=deny materials.",
+        constraints: ["Boolean — no other values"],
+    },
+    {
+        element_type: "index",
+        type_name: "dispute_index",
+        semantic_explanation: "Position in order.dispute vector. 0-based. Max 10 disputes total.",
+        constraints: [`<= ${MAX_DISPUTE_COUNT} disputes`, "Frozen when claimed_by.is_some()"],
+    },
+    {
+        element_type: "error",
+        type_name: "E_OWNER (code 1)",
+        semantic_explanation: "Sender != order.owner. L1 operation attempted by non-owner (agent or third party).",
+        constraints: ["Aborts assert_owner"],
+    },
+    {
+        element_type: "error",
+        type_name: "E_PERMISSION (code 5)",
+        semantic_explanation: "Sender is neither owner nor in agent[]. L2 operation attempted by unauthorized caller.",
+        constraints: ["Aborts assert_op_permission (via has_op_permission returning false)"],
+    },
+    {
+        element_type: "error",
+        type_name: "E_PROGRESS_NOT_SPECIFIED (code 3)",
+        semantic_explanation: "⚠️ DUAL SEMANTICS: (a) order::create — machine is Some but progress is None; (b) agent_set/owner_change — progress is already bound (frozen).",
+        constraints: ["Check context to disambiguate", "Same code, opposite meanings"],
+    },
+    {
+        element_type: "error",
+        type_name: "E_ORDER_ALREADY_CLAIMED (code 7)",
+        semantic_explanation: "claimed_by is already Some. Cannot file new disputes, claim again, or call compensate.",
+        constraints: ["IRREVERSIBLE — no way to reset claimed_by"],
+    },
+    {
+        element_type: "error",
+        type_name: "E_MAX_AGENT_COUNT (code 2)",
+        semantic_explanation: "agent list exceeds MAX_AGENT_COUNT (10). ⚠️ Actual boundary uses <= so allows 11 (bug).",
+        constraints: [`Doc limit: ${MAX_AGENT_COUNT}`, "Actual limit: 11 (boundary bug)"],
+    },
+    {
+        element_type: "error",
+        type_name: "E_MAX_DISPUTE_COUNT (code 6)",
+        semantic_explanation: "dispute vector at MAX_DISPUTE_COUNT (10). Next dispute() call aborts.",
+        constraints: [`Max: ${MAX_DISPUTE_COUNT}`],
+    },
+    {
+        element_type: "error",
+        type_name: "E_ALLOCATION_NOT_SPECIFIED (code 8)",
+        semantic_explanation: "order::create with amount > 0 but allocation is None.",
+        constraints: ["If amount > 0, allocation must be set"],
+    },
+    {
+        element_type: "error",
+        type_name: "E_ALLOCATION_ALREADY_SPECIFIED (code 9)",
+        semantic_explanation: "on_allocation called twice. Allocation is one-time set.",
+        constraints: ["One-time only"],
+    },
+    {
+        element_type: "error",
+        type_name: "E_PROGRESS_ALREADY_SPECIFIED (code 10)",
+        semantic_explanation: "on_progress called twice. Progress is one-time set.",
+        constraints: ["One-time only"],
+    },
+];
+export const ORDER_CONSTRAINT_RULES = [
+    {
+        id: "MC-O-01",
+        category: "structural",
+        rule: "Order has 14 fields; SDK uses 'builder' for Move's 'owner' (only naming deviation in 22 objects)",
+        applies_to: ["object.owner", "object.builder"],
+    },
+    {
+        id: "MC-O-02",
+        category: "structural",
+        rule: `agent count <= MAX_AGENT_COUNT (${MAX_AGENT_COUNT}) per docs; ⚠️ actual allows 11 due to <= bug`,
+        applies_to: ["agent"],
+    },
+    {
+        id: "MC-O-03",
+        category: "structural",
+        rule: `dispute count <= MAX_DISPUTE_COUNT (${MAX_DISPUTE_COUNT}); frozen when claimed_by.is_some()`,
+        applies_to: ["dispute"],
+    },
+    {
+        id: "MC-O-04",
+        category: "structural",
+        rule: "Order creation is COMPOSITE via service::buy — order::create is package-only",
+        applies_to: ["(creation flow)"],
+    },
+    {
+        id: "MC-O-05",
+        category: "semantic",
+        rule: "order.machine is a SNAPSHOT copied from service.machine at buy time (not a reference)",
+        applies_to: ["machine"],
+    },
+    {
+        id: "MC-O-06",
+        category: "semantic",
+        rule: "E_PROGRESS_NOT_SPECIFIED has DUAL semantics: (a) create: machine Some + progress None; (b) agent_set/owner_change: progress already bound",
+        applies_to: ["error code 3"],
+    },
+    {
+        id: "MC-O-07",
+        category: "semantic",
+        rule: "Only NewOrderEvent is actually emitted; 10 other lifecycle events must be inferred from field changes",
+        applies_to: ["events"],
+    },
+    {
+        id: "MC-O-08",
+        category: "semantic",
+        rule: "SaleItem.item ↔ PurchasedItem.name (different field names for same concept)",
+        applies_to: ["items.item", "purchased_items.name"],
+    },
+    {
+        id: "MC-O-09",
+        category: "authority",
+        rule: "L1 owner-only operations: receive, transfer_to, owner_change, agent_set (assert_owner)",
+        applies_to: ["receive", "transfer_to", "agent"],
+    },
+    {
+        id: "MC-O-10",
+        category: "authority",
+        rule: "L2 owner-or-agent operations: required_info, progress, arb_confirm, arb_objection, arb_claim_compensation (has_op_permission)",
+        applies_to: ["required_info", "progress", "arb_confirm", "arb_objection", "arb_claim_compensation"],
+    },
+    {
+        id: "MC-O-11",
+        category: "authority",
+        rule: "L3 package-only operations: on_progress, on_allocation, dispute, compensate (no external access)",
+        applies_to: ["(package-only functions)"],
+    },
+    {
+        id: "MC-O-12",
+        category: "authority",
+        rule: "Agent CANNOT receive payments — only owner can call owner_receive / owner_receive_object",
+        applies_to: ["receive"],
+    },
+    {
+        id: "MC-O-13",
+        category: "lifecycle",
+        rule: "Progress binding FREEZES owner and agent — agent_set/owner_change abort E_PROGRESS_NOT_SPECIFIED after binding",
+        applies_to: ["agent", "transfer_to (pre-progress)", "owner_change"],
+    },
+    {
+        id: "MC-O-14",
+        category: "lifecycle",
+        rule: "claimed_by is ONE-TIME, IRREVERSIBLE — blocks future dispute(), compensate(), and arb_claim_compensation",
+        applies_to: ["claimed_by", "arb_claim_compensation", "dispute"],
+    },
+    {
+        id: "MC-O-15",
+        category: "cross_object",
+        rule: "Order + Allocation + Progress are 1:1:1 bound at creation; cannot rebind or detach",
+        applies_to: ["progress", "allocation"],
+    },
+];
+export const ORDER_TRANSLATION_VERSION = "1.0.0";
+export function matchSemanticPattern(userIntent) {
+    const lower = userIntent.toLowerCase();
+    return SEMANTIC_TO_SCHEMA_RULES.filter(rule => rule.match_keywords.some(kw => lower.includes(kw.toLowerCase())));
+}
+export function explainOrderCallData(data) {
+    const lines = [];
+    if (!data.object) {
+        lines.push("Operation: ⚠️ INVALID — Order object address required (Order creation goes through service::buy, not CallOrder_Data)");
+        return lines.join("\n");
+    }
+    lines.push(`Operation: MODIFY existing Order at ${data.object}`);
+    if (data.agent) {
+        lines.push(`- ⚠️ Set agent list (${data.agent.length} agent(s)): [${data.agent.join(", ")}]`);
+        lines.push(`  Owner-only (L1). Frozen after Progress binding. Boundary bug allows max 11 (not 10).`);
+    }
+    if (data.required_info !== undefined) {
+        if (data.required_info === null) {
+            lines.push(`- Clear required_info (L2 — owner or agent)`);
+        }
+        else {
+            lines.push(`- Set required_info: ${data.required_info} (Contact or WTS Proof; L2 — owner or agent)`);
+        }
+    }
+    if (data.progress) {
+        const p = data.progress;
+        lines.push(`- Advance Progress (L2 — owner or agent)`);
+        if (p.next_node_name)
+            lines.push(`  Next node: ${p.next_node_name}`);
+        if (p.forward)
+            lines.push(`  Forward: ${p.forward.name}${p.forward.operator ? ` (operator: ${p.forward.operator})` : ""}`);
+        if (p.op)
+            lines.push(`  Op: ${p.op}`);
+        if (p.message)
+            lines.push(`  Message: "${p.message}"`);
+    }
+    if (data.arb_confirm) {
+        const a = data.arb_confirm;
+        lines.push(`- ⚠️ Apply for arbitration (L2 — owner or agent, IRREVERSIBLE)`);
+        lines.push(`  Arb: ${a.arb}`);
+        lines.push(`  Confirm: ${a.confirm ? "valid materials" : "deny materials"}`);
+        if (a.description)
+            lines.push(`  Description: "${a.description}"`);
+        if (a.proposition && a.proposition.length > 0) {
+            lines.push(`  Propositions: ${a.proposition.length} claim(s)`);
+        }
+    }
+    if (data.arb_objection) {
+        const a = data.arb_objection;
+        lines.push(`- ⚠️ Object to Arb ruling (L2 — owner or agent, IRREVERSIBLE)`);
+        lines.push(`  Arb: ${a.arb}`);
+        lines.push(`  Objection: "${a.objection}"`);
+    }
+    if (data.arb_claim_compensation) {
+        const a = data.arb_claim_compensation;
+        lines.push(`- ⚠️⚠️ CLAIM COMPENSATION (L2 — owner or agent, ONE-TIME, IRREVERSIBLE)`);
+        lines.push(`  Arb: ${a.arb}`);
+        lines.push(`  After claim: NO new disputes can be filed (E_ORDER_ALREADY_CLAIMED)`);
+    }
+    if (data.receive) {
+        lines.push(`- Receive (L1 — OWNER-ONLY, agent CANNOT)`);
+        lines.push(`  Received object: ${data.receive.received}`);
+        lines.push(`  Funds/objects forwarded to owner address`);
+    }
+    if (data.transfer_to) {
+        lines.push(`- ⚠️⚠️ TRANSFER OWNERSHIP to ${data.transfer_to} (L1 — OWNER-ONLY, IRREVERSIBLE)`);
+        lines.push(`  New owner takes over ALL permissions`);
+        lines.push(`  Can be called even after Progress binding (unlike agent_set)`);
+    }
+    return lines.join("\n");
+}
+export function explainField(fieldName) {
+    return SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "field" && r.type_name === fieldName);
+}
+export function explainOp(opName) {
+    return SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "op" && r.type_name === opName);
+}
+export function explainOrderError(errorNameOrCode) {
+    const str = String(errorNameOrCode);
+    return SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "error" && (r.type_name === str ||
+        r.type_name.startsWith(str + " ") ||
+        r.type_name.includes(str)));
+}
+export function getConstraintsByCategory(category) {
+    return ORDER_CONSTRAINT_RULES.filter(r => r.category === category);
+}
+export function explainPermissionLayer(layer) {
+    const descriptions = {
+        L1_owner_only: "L1 — Owner-only (assert_owner). Aborts E_OWNER (code 1) if sender != owner. Agent CANNOT perform L1 ops.",
+        L2_owner_or_agent: "L2 — Owner or agent (has_op_permission). Aborts E_PERMISSION (code 5) if sender is neither owner nor in agent[].",
+        L3_package_only: "L3 — Package-only (no external access). Called by other wow-framework modules (progress, allocation, arbitration).",
+    };
+    return descriptions[layer];
+}
+export function resolveFieldName(sdkOrMoveName) {
+    if (sdkOrMoveName === "builder" || sdkOrMoveName === "owner") {
+        return { sdk_name: "builder", move_name: "owner", is_deviation: true };
+    }
+    return { sdk_name: sdkOrMoveName, move_name: sdkOrMoveName, is_deviation: false };
+}
+export function matchSceneFromOperation(operationField) {
+    const scenes = ORDER_SCENES.filter(s => s.operation_field === operationField);
+    return scenes.length > 0 ? scenes[0] : undefined;
+}
+export function explainOrderIntent(intent) {
+    const matchedScene = inferSceneFromIntent(intent);
+    const matchedPatterns = matchSemanticPattern(intent);
+    const relevantConstraints = matchedScene
+        ? ORDER_CONSTRAINT_RULES.filter(c => {
+            if (matchedScene.permission_layer === "L1_owner_only") {
+                return c.category === "authority" || c.category === "lifecycle";
+            }
+            if (matchedScene.permission_layer === "L2_owner_or_agent") {
+                return c.category === "authority" || c.category === "semantic";
+            }
+            return c.category === "structural" || c.category === "cross_object";
+        })
+        : ORDER_CONSTRAINT_RULES;
+    return {
+        matched_scene: matchedScene,
+        matched_patterns: matchedPatterns,
+        relevant_constraints: relevantConstraints,
+    };
+}

package/dist/knowledge/passport-confirm.d.ts

@@ -0,0 +1,130 @@
+import { type PassportScenario } from "./passport-ledger.js";
+import { type PassportRiskAssessment } from "./passport-risk.js";
+export type ConfirmAction = "block" | "warn" | "confirm_twice" | "info";
+export type ConfirmSeverity = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export type ConfirmGateStatus = "approved" | "blocked_creation" | "blocked_operation" | "blocked_consistency" | "pending_confirmation";
+export interface PassportConfirmationRule {
+    id: string;
+    check: string;
+    severity: ConfirmSeverity;
+    action: ConfirmAction;
+    related_error?: string;
+    layer: "creation" | "operation" | "consistency";
+}
+export interface CheckResult {
+    errors: string[];
+    warnings: string[];
+    requiresConfirmation: string[];
+    canProceed: boolean;
+}
+export interface ConfirmGateResult {
+    status: ConfirmGateStatus;
+    creation_result?: CheckResult;
+    operation_result?: CheckResult;
+    consistency_result?: CheckResult;
+    risk_assessment?: PassportRiskAssessment;
+    confirmation_text: string;
+    block_reason?: string;
+    decision_record: DecisionRecord;
+}
+export interface DecisionRecord {
+    timestamp: string;
+    gate_version: string;
+    final_status: ConfirmGateStatus;
+    layers_passed: string[];
+    layers_failed: string[];
+}
+export interface PassportGuardInfo {
+    guard: string;
+    result: boolean;
+    impack: boolean;
+}
+export interface ObjectPassport {
+    object: string;
+    info: PassportGuardInfo[];
+    result: boolean;
+    tx_hash: string;
+    impack_guard: string[];
+    time: number;
+    signer: string;
+    has_verified: boolean;
+}
+export interface ObjectGuard {
+    object: string;
+    relies?: string[];
+    relies_logic_and?: boolean;
+    table?: {
+        identifier: number;
+        value_type: string;
+        b_submission: boolean;
+    }[];
+}
+export type PassportOperation = {
+    type: "guard_add";
+    guard: string;
+    impack: boolean;
+    submission?: {
+        identifier: number;
+        value: unknown;
+        value_type: string;
+    }[];
+} | {
+    type: "verify";
+} | {
+    type: "guard_clear";
+} | {
+    type: "freezen";
+} | {
+    type: "destroy";
+} | {
+    type: "result_query";
+} | {
+    type: "result_for_guard";
+    guard: string;
+} | {
+    type: "result_for_permission";
+} | {
+    type: "submission_get";
+    guard: string;
+    identifier: number;
+};
+export declare const PASSPORT_CONFIRMATION_RULES: {
+    creation: PassportConfirmationRule[];
+    operation: PassportConfirmationRule[];
+    consistency: PassportConfirmationRule[];
+};
+export interface CreationCheckInput {
+    clock: string | null;
+    txDigest: string | null;
+}
+export declare function preCheckPassportCreation(input: CreationCheckInput): CheckResult;
+export interface OperationCheckInput {
+    passport: ObjectPassport;
+    operation: PassportOperation;
+    guardObjects: Map<string, ObjectGuard>;
+}
+export declare function preCheckPassportOperation(input: OperationCheckInput): CheckResult;
+export interface ConsistencyCheckInput {
+    passport: ObjectPassport;
+    guardObjects: Map<string, ObjectGuard>;
+    isFrozen: boolean;
+}
+export declare function checkPassportStateConsistency(input: ConsistencyCheckInput): CheckResult;
+export declare const PASSPORT_CONFIRM_VERSION = "1.0.0";
+export interface ConfirmGateInput {
+    creation_input?: CreationCheckInput;
+    operation_input?: OperationCheckInput;
+    consistency_input?: ConsistencyCheckInput;
+    skip_risk_assessment?: boolean;
+    skip_user_confirmation?: boolean;
+    scenario?: PassportScenario;
+}
+export declare function runPassportConfirmGate(input: ConfirmGateInput): ConfirmGateResult;
+export declare function estimateSubmissionSize(submission: {
+    identifier: number;
+    value: unknown;
+    value_type: string;
+}[]): number;
+export declare function getAllConfirmationRules(): PassportConfirmationRule[];
+export declare function getConfirmationRulesByLayer(layer: "creation" | "operation" | "consistency"): PassportConfirmationRule[];
+export declare function getConfirmationRuleById(id: string): PassportConfirmationRule | undefined;