@wowok/agent-mcp 2.4.3 → 2.5.0

package/dist/knowledge/service-ledger.js

@@ -0,0 +1,609 @@
+export const SERVICE_PERMISSIONS = [
+    { index: 300, name: "SERVICE_NEW", description: "Create new Service", governed_operation: "service::new", post_publish_mutability: "na" },
+    { index: 301, name: "SERVICE_DESCRIPTION", description: "Modify Service description", governed_operation: "service::description_set", post_publish_mutability: "mutable" },
+    { index: 303, name: "SERVICE_LOCATION", description: "Set Service location/URL", governed_operation: "service::location_set", post_publish_mutability: "mutable" },
+    { index: 304, name: "SERVICE_REPOSITORY", description: "Add/remove Repository references", governed_operation: "service::repository_add/remove/clear", post_publish_mutability: "mutable" },
+    { index: 305, name: "SERVICE_SALES", description: "Add/set/remove/clear sales items", governed_operation: "service::sales_add/set/remove/clear", post_publish_mutability: "mutable" },
+    { index: 306, name: "SERVICE_MACHINE", description: "Bind/unbind Machine workflow template", governed_operation: "service::machine_set/machine_none", post_publish_mutability: "immutable" },
+    { index: 307, name: "SERVICE_BUY_GUARD", description: "Set/clear buy Guard (post-publish mutable)", governed_operation: "service::buy_guard_set/buy_guard_none", post_publish_mutability: "mutable" },
+    { index: 308, name: "SERVICE_ARBITRATION", description: "Add/remove Arbitration references", governed_operation: "service::arbitration_add/remove/clear", post_publish_mutability: "immutable" },
+    { index: 309, name: "SERVICE_CUSTOMER_INFO_REQUIRED", description: "Set customer required info fields", governed_operation: "service::customer_required_set", post_publish_mutability: "mutable" },
+    { index: 310, name: "SERVICE_PAUSE", description: "Pause/resume Service (block new orders)", governed_operation: "service::pause", post_publish_mutability: "mutable" },
+    { index: 311, name: "SERVICE_PUBLISH", description: "Publish Service (IRREVERSIBLE)", governed_operation: "service::publish", post_publish_mutability: "one_shot" },
+    { index: 312, name: "SERVICE_DISCOUNT", description: "Issue/discount_destroy discount coupons", governed_operation: "service::discount", post_publish_mutability: "mutable" },
+    { index: 313, name: "SERVICE_ORDER_ALLOCATOR", description: "Set order allocator strategy", governed_operation: "service::order_allocators_set", post_publish_mutability: "immutable" },
+    { index: 314, name: "SERVICE_COMPENSATION_FUND_WITHDRAW", description: "Withdraw compensation fund (lock_duration)", governed_operation: "service::compensation_fund_withdraw", post_publish_mutability: "locked_by_duration" },
+    { index: 315, name: "SERVICE_COMPENSATION_FUND_DEPOSIT", description: "Deposit to compensation fund", governed_operation: "service::compensation_fund_add", post_publish_mutability: "mutable" },
+    { index: 316, name: "SERVICE_COMPENSATION_FUND_RECEIVE", description: "Receive compensation fund (lock_duration)", governed_operation: "service::compensation_fund_receive", post_publish_mutability: "locked_by_duration" },
+    { index: 317, name: "SERVICE_COMPENSATION_LOCKED_TIME_ADD", description: "Extend setting_lock_duration (only-increase)", governed_operation: "service::setting_lock_duration_add", post_publish_mutability: "mutable" },
+    { index: 318, name: "SERVICE_REWARD", description: "Add/remove Reward references (locked)", governed_operation: "service::reward_add/remove/clear", post_publish_mutability: "locked_by_duration" },
+    { index: 319, name: "SERVICE_OWNER_RECEIVE", description: "Receive Payment/objects to owner", governed_operation: "service::owner_receive", post_publish_mutability: "mutable" },
+    { index: 320, name: "SERVICE_UM", description: "Bind/unbind Contact as UM", governed_operation: "service::um_set/um_none", post_publish_mutability: "mutable" },
+];
+export const SERVICE_ORDER_FLOW_STAGES = [
+    {
+        stage: 1,
+        name: "pre_check",
+        preconditions: [
+            "Service.bPublished == true (else E_SERVICE_NOT_PUBLISHED)",
+            "Service.bPaused == false (else E_SERVICE_PAUSED)",
+            "buy_guard (if set) added to guards[] list for verification",
+        ],
+        side_effects: [],
+        always_executed: true,
+    },
+    {
+        stage: 2,
+        name: "wip_verify",
+        preconditions: [
+            "buy.items non-empty",
+            "Each item.name matches a sale in Service.sales (else E_SALE_NOT_FOUND)",
+            "sale.suspension == false (else E_SALE_SUSPENDED)",
+        ],
+        side_effects: [
+            "If buyer passes empty wip_hash, SDK auto-fills with sale.wip_hash",
+            "verifiedWipUrls Set avoids re-verifying same WIP URL across items",
+            "verify_wip() fetches WIP file and compares hash (else E_WIP_HASH_NOT_MATCH)",
+        ],
+        always_executed: true,
+    },
+    {
+        stage: 3,
+        name: "quote",
+        preconditions: [
+            "All items have valid sale + wip_hash match",
+            "stock >= purchase quantity (else E_STOCK_INSUFFICIENT)",
+            "discount object (if used) is valid and unexpired",
+        ],
+        side_effects: [
+            "quote_imp() computes total price (with discount if applicable)",
+            "⚠️ Stock is deducted (split) — side effect is NOT auto-rolled-back on later failure",
+            "service::quote or service::quote_with_discount MoveCall",
+        ],
+        always_executed: true,
+    },
+    {
+        stage: 4,
+        name: "create_order",
+        preconditions: ["Quote object from stage 3", "Registrar + Clock objects available"],
+        side_effects: [
+            "service::buy or service::buy_with_passport MoveCall",
+            "Order object created (builder=customer, service=Service.id)",
+            "Order.id recorded for stages 5-7",
+        ],
+        always_executed: true,
+    },
+    {
+        stage: 5,
+        name: "create_allocation",
+        preconditions: [
+            "Service.order_allocators is Some (configured)",
+            "Order from stage 4",
+            "CoinParam for total_pay matches Service<T> type",
+        ],
+        side_effects: [
+            "service::order_allocation MoveCall",
+            "Allocation object created (first-match-wins fund distribution)",
+            "Order.allocation = Allocation address",
+        ],
+        always_executed: true,
+    },
+    {
+        stage: 6,
+        name: "create_progress",
+        preconditions: ["Service.machine is Some (machine bound)", "Order from stage 4", "Machine from Service.machine"],
+        side_effects: [
+            "service::order_progress MoveCall",
+            "Progress object created (Progress.machine = Service.machine, Progress.task = Order.id)",
+        ],
+        always_executed: false,
+    },
+    {
+        stage: 7,
+        name: "post_actions",
+        preconditions: ["Order/Allocation/Progress objects from stages 4-6"],
+        side_effects: [
+            "agent_set (if order_new.agents provided)",
+            "order_required_info_update (if order_required_info provided)",
+            "owner_change (if transfer provided — sets new Order owner)",
+            "namedNewOrder / namedNewAllocation / namedNewProgress (local naming)",
+        ],
+        always_executed: false,
+    },
+    {
+        stage: 8,
+        name: "return_result",
+        preconditions: ["All preceding stages succeeded"],
+        side_effects: [
+            "Returns BuyResult { order, allocation?, progress? }",
+            "Caller proceeds to sign + submit transaction",
+        ],
+        always_executed: true,
+    },
+];
+export const SERVICE_CROSS_OBJECT_BINDINGS = [
+    { object: "Machine", field: "machine", required: false, locked_after_publish: true, notes: "Workflow template; post-publish immutable (F-S-20). Progress.machine inherits this value." },
+    { object: "Guard", field: "buy_guard", required: false, locked_after_publish: false, notes: "Buyer eligibility guard; post-publish STILL MUTABLE (unusual — see F-S-26)" },
+    { object: "Allocation", field: "order_allocators", required: true, locked_after_publish: true, notes: "Order fund distribution strategy; publish prerequisite (F-S-18). Post-publish immutable (F-S-22)." },
+    { object: "Arbitration", field: "arbitrations", required: false, locked_after_publish: true, notes: "Dispute handlers; required if compensation_fund > 0 (F-S-19). Post-publish immutable (F-S-21)." },
+    { object: "Repository", field: "repositories", required: false, locked_after_publish: false, notes: "Shared data stores; mutable post-publish" },
+    { object: "Reward", field: "rewards", required: false, locked_after_publish: false, notes: "Marketing incentives; mutable but locked by setting_lock_duration (F-S-24)" },
+    { object: "Contact", field: "um", required: false, locked_after_publish: false, notes: "User Manager (Contact object); mutable post-publish" },
+    { object: "Treasury", field: "(indirect via order_allocators.sharing.who=Entity)", required: false, locked_after_publish: false, notes: "Treasury is referenced by Allocation.sharing.who, not by Service directly" },
+];
+export const SERVICE_SCENES = [
+    {
+        id: "service_retail",
+        name: "Retail e-commerce Service",
+        category: "retail",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set", "location_set", "customer_required_set"],
+        permission_index_operations: [
+            "service::publish (311)",
+            "service::pause (310)",
+            "service::sales_add/set/remove/clear (305)",
+            "service::order_allocators_set (313)",
+            "service::buy_guard_set (307)",
+            "service::discount (312)",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: [
+            "order_allocators must be set (F-S-18, E_NO_ALLOCATOR)",
+            "If compensation_fund > 0, arbitrations must be non-empty (F-S-19)",
+        ],
+        common_patterns: [
+            "Multi-tier pricing via sales[] (Standard/Premium/Enterprise)",
+            "WIP hash per sale item for tamper-proof product info",
+            "buy_guard for KYC whitelist during pre-sale, then null for public sale",
+            "compensation_fund deposited before publish + arbitrations configured",
+        ],
+        recommended_templates: ["T-S-01", "T-S-06"],
+    },
+    {
+        id: "service_rental",
+        name: "Rental Service (short/long-term)",
+        category: "rental",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set", "location_set"],
+        permission_index_operations: [
+            "service::publish (311)",
+            "service::sales_add/set (305)",
+            "service::machine_set (306) — for rental workflow",
+            "service::arbitration_add (308) — for deposit disputes",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: [
+            "order_allocators must be set",
+            "machine recommended (rental workflow with deposit/return stages)",
+            "arbitrations recommended (deposit refund disputes)",
+        ],
+        common_patterns: [
+            "Machine workflow with 'Deposit → Use → Return → Refund' nodes",
+            "compensation_fund holds deposit guarantees",
+            "buy_guard verifies renter identity/KYC",
+            "stock=1 per rental item (unique items)",
+        ],
+        recommended_templates: ["T-S-02", "T-S-04"],
+    },
+    {
+        id: "service_subscription",
+        name: "Subscription Service (recurring)",
+        category: "subscription",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set", "location_set"],
+        permission_index_operations: [
+            "service::publish (311)",
+            "service::sales_add/set (305)",
+            "service::discount (312) — promotional rates",
+            "service::reward_add (318) — loyalty rewards",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: ["order_allocators must be set"],
+        common_patterns: [
+            "Tiered plans (Free/Pro/Enterprise) as sales[]",
+            "Discount coupons for trial periods",
+            "Rewards for long-term subscribers",
+            "Renewal handled by repeat orders (no native recurring billing)",
+        ],
+        recommended_templates: ["T-S-03"],
+    },
+    {
+        id: "service_workflow",
+        name: "Workflow-bound Service (machine-bound)",
+        category: "workflow",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set", "location_set"],
+        permission_index_operations: [
+            "service::machine_set (306) — bind workflow",
+            "service::publish (311)",
+            "service::order_allocators_set (313)",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: [
+            "order_allocators must be set",
+            "machine must be published before binding",
+            "machine recommended for any multi-stage service delivery",
+        ],
+        common_patterns: [
+            "Machine defines Pay → Confirm → Deliver → Sign-off nodes",
+            "Progress created per order (stage 6 of buy flow)",
+            "Named operators assigned per Forward in Machine",
+            "Service.paused does NOT affect already-created Progress (existing orders continue)",
+        ],
+        recommended_templates: ["T-S-04"],
+    },
+    {
+        id: "service_arbitration",
+        name: "Arbitration-bound Service (dispute-ready)",
+        category: "arbitration",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set"],
+        permission_index_operations: [
+            "service::arbitration_add (308)",
+            "service::compensation_fund_add (315)",
+            "service::setting_lock_duration_add (317)",
+            "service::publish (311)",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: [
+            "If compensation_fund > 0, arbitrations must be non-empty (F-S-19)",
+            "Arbitration objects must be created before binding",
+            "compensation_fund_add before publish recommended (else post-publish deposit still possible)",
+        ],
+        common_patterns: [
+            "2-3 Arbitration objects (different arb committees for different dispute types)",
+            "compensation_fund deposited as % of expected order volume",
+            "setting_lock_duration extended by owner to build customer trust",
+            "compensation_claim triggered by arbitration result (not by Service directly)",
+        ],
+        recommended_templates: ["T-S-05", "T-S-06"],
+    },
+    {
+        id: "service_compensation_fund",
+        name: "Compensation Fund Service (embedded balance)",
+        category: "compensation_fund",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set"],
+        permission_index_operations: [
+            "service::compensation_fund_add (315) — deposit",
+            "service::compensation_fund_withdraw (314) — withdraw (locked)",
+            "service::compensation_fund_receive (316) — receive (locked)",
+            "service::setting_lock_duration_add (317) — extend lock",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: [
+            "compensation_fund > 0 → arbitrations non-empty (F-S-19)",
+            "compensation_fund coin type must match Service<T> type parameter",
+        ],
+        common_patterns: [
+            "Fund inflow: compensation_fund_add (315) — always mutable",
+            "Fund outflow: compensation_fund_withdraw (314) — requires bPaused + lock_duration expired",
+            "Fund receive: compensation_fund_receive (316) — locked by duration",
+            "Fund consumer: arbitration::compensation_claim (driven by arb result)",
+            "Distinct from Treasury: Service-internal, arbitration-bound, lock-protected",
+        ],
+        recommended_templates: ["T-S-06"],
+    },
+    {
+        id: "service_reward",
+        name: "Reward-attached Service (marketing)",
+        category: "reward",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set"],
+        permission_index_operations: [
+            "service::reward_add/remove/clear (318) — locked by duration",
+            "service::discount (312)",
+            "service::publish (311)",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: ["order_allocators must be set"],
+        common_patterns: [
+            "Rewards added post-publish (still allowed, but locked by duration)",
+            "Reward objects must exist before binding (queryObjectsWithType validation)",
+            "MAX_REWARD_COUNT = 20 per Service",
+            "Reward removal also locked by duration (protects customer expectations)",
+        ],
+        recommended_templates: ["T-S-08"],
+    },
+    {
+        id: "service_arbitration_binding",
+        name: "Arbitration Binding Service (post-publish immutable)",
+        category: "arbitration",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set"],
+        permission_index_operations: [
+            "service::arbitration_add (308) — pre-publish only",
+            "service::arbitration_remove (308) — pre-publish only",
+            "service::arbitration_clear (308) — pre-publish only",
+            "service::publish (311)",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: [
+            "MAX_ARBITRATION_COUNT = 20 per Service (F-S-04)",
+            "Each Arbitration object must be valid (queryObjectsWithType validation)",
+            "Arbitration bound = locked post-publish (F-S-21). To change: create new Service.",
+        ],
+        common_patterns: [
+            "Pre-publish: set 1-3 Arbitration objects for different dispute scopes",
+            "Post-publish: immutable — clone Service if change needed",
+            "⚠️ Data inconsistency: dynamic-pricing.ts marks arbitrations as mutable, but SDK blocks it (F-S-21)",
+        ],
+        recommended_templates: ["T-S-05"],
+    },
+    {
+        id: "service_buy_guard",
+        name: "Buy Guard Service (post-publish mutable guard)",
+        category: "buy_guard",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set"],
+        permission_index_operations: [
+            "service::buy_guard_set (307) — bind guard",
+            "service::buy_guard_none (307) — clear guard",
+            "service::publish (311)",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: ["order_allocators must be set"],
+        common_patterns: [
+            "Pre-sale phase: buy_guard = whitelist Guard (KYC verified buyers only)",
+            "Public sale: buy_guard = null (anyone can buy)",
+            "Restricted phase: buy_guard = KYC Guard (compliance)",
+            "⚠️ buy_guard is the ONLY publish-locked-field exception — still mutable post-publish",
+            "buy_guard verification happens at Stage 1 of buy flow (pre_check)",
+        ],
+        recommended_templates: ["T-S-01"],
+    },
+    {
+        id: "service_order_allocator",
+        name: "Order Allocator Service (fund distribution config)",
+        category: "order_allocator",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set"],
+        permission_index_operations: [
+            "service::order_allocators_set (313) — pre-publish only",
+            "service::publish (311) — requires order_allocators (F-S-18)",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: [
+            "order_allocators MUST be set (F-S-18, E_NO_ALLOCATOR)",
+            "Allocators.sharing.who can reference Treasury addresses (indirect Treasury binding)",
+            "MAX_SHARING_COUNT = 100 per allocator",
+        ],
+        common_patterns: [
+            "Multi-party split: merchant 80% / platform 10% / logistics 10%",
+            "Threshold-based: different allocators for different order sizes",
+            "Guard-bound allocator: allocation execution requires Guard verification",
+            "Post-publish immutable — clone Service to change allocation strategy",
+        ],
+        recommended_templates: ["T-S-08"],
+    },
+    {
+        id: "service_dynamic_pricing",
+        name: "Dynamic Pricing Service (discount-driven)",
+        category: "dynamic_pricing",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set"],
+        permission_index_operations: [
+            "service::discount (312) — issue coupons",
+            "service::sales_add/set (305) — adjust base prices",
+            "service::sales_remove (305) — remove deprecated SKUs",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: ["order_allocators must be set"],
+        common_patterns: [
+            "Discount types: 0=rates (basis points, per 10000), 1=minus (direct deduction)",
+            "MAX_DISCOUNT_COUNT_ONCE = 1000 per issue call",
+            "MAX_DISCOUNT_RECEIVER_ONCE = 1000 receivers per call",
+            "MAX_DISCOUNT_TOTAL_COUNT = 20000 total coupons",
+            "discount_destroy: holder-only (no SERVICE_DISCOUNT permission needed)",
+        ],
+        recommended_templates: ["T-S-07"],
+    },
+    {
+        id: "service_multi_allocator",
+        name: "Multi-Allocator Service (tiered fund distribution)",
+        category: "multi_allocator",
+        permission_index_range: "300-320",
+        builtin_indexes: SERVICE_PERMISSIONS,
+        cross_object_bindings: SERVICE_CROSS_OBJECT_BINDINGS,
+        order_flow_stages: SERVICE_ORDER_FLOW_STAGES,
+        owner_operations: ["um_set", "builder (transfer)"],
+        admin_operations: ["description_set"],
+        permission_index_operations: [
+            "service::order_allocators_set (313) — pre-publish only",
+            "service::publish (311)",
+        ],
+        mutable_after_publish: {
+            machine: false, arbitrations: false, order_allocators: false,
+            buy_guard: true, rewards: "locked_by_duration",
+            compensation_fund_withdraw: "locked_by_duration", compensation_fund_receive: "locked_by_duration",
+            sales: true, description: true, location: true, repositories: true,
+            customer_required: true, discount: true, um: true, pause: true,
+        },
+        publish_prerequisites: [
+            "order_allocators MUST be set",
+            "Each allocator has its own Guard + sharing + threshold",
+            "First-match-wins: first allocator whose threshold is met handles the order",
+        ],
+        common_patterns: [
+            "Tier 1 (small orders): single-recipient allocator (low fee)",
+            "Tier 2 (medium orders): two-recipient split (merchant + platform)",
+            "Tier 3 (large orders): three-recipient split (merchant + platform + logistics)",
+            "Each tier can have its own Guard for execution authorization",
+        ],
+        recommended_templates: ["T-S-08"],
+    },
+];
+export const SERVICE_LEDGER_VERSION = "1.0.0";
+export function getScenesByCategory(category) {
+    return SERVICE_SCENES.filter(s => s.category === category);
+}
+export function findSceneById(id) {
+    return SERVICE_SCENES.find(s => s.id === id);
+}
+export function getServicePermissionByIndex(index) {
+    return SERVICE_PERMISSIONS.find(p => p.index === index);
+}
+export function isServicePermission(index) {
+    return getServicePermissionByIndex(index) !== undefined;
+}
+export function getPermissionsByMutability(mutability) {
+    return SERVICE_PERMISSIONS.filter(p => p.post_publish_mutability === mutability);
+}
+export function getImmutablePostPublishPermissions() {
+    return SERVICE_PERMISSIONS.filter(p => p.post_publish_mutability === "immutable" || p.post_publish_mutability === "one_shot");
+}
+export function getLockedByDurationPermissions() {
+    return SERVICE_PERMISSIONS.filter(p => p.post_publish_mutability === "locked_by_duration");
+}
+export function inferSceneFromIntent(intent) {
+    const lower = intent.toLowerCase();
+    const categoryKeywords = [
+        ["retail", "retail"], ["ecommerce", "retail"],
+        ["rental", "rental"], ["rent", "rental"], ["short-term rental", "rental"], ["long-term rental", "rental"],
+        ["subscription", "subscription"], ["subscribe", "subscription"],
+        ["workflow", "workflow"], ["machine-bound", "workflow"],
+        ["arbitration", "arbitration"], ["dispute", "arbitration"],
+        ["compensation", "compensation_fund"], ["compensation_fund", "compensation_fund"],
+        ["reward", "reward"], ["marketing", "reward"],
+        ["buy_guard", "buy_guard"], ["kyc", "buy_guard"], ["whitelist", "buy_guard"],
+        ["allocator", "order_allocator"],
+        ["discount", "dynamic_pricing"], ["coupon", "dynamic_pricing"],
+        ["multi-allocator", "multi_allocator"], ["tiered", "multi_allocator"],
+    ];
+    for (const [kw, cat] of categoryKeywords) {
+        if (lower.includes(kw)) {
+            const scenes = getScenesByCategory(cat);
+            if (scenes.length > 0)
+                return scenes[0];
+        }
+    }
+    if (lower.includes("service")) {
+        return findSceneById("service_retail");
+    }
+    return undefined;
+}
+export function getAllServiceScenes() {
+    return [...SERVICE_SCENES];
+}
+export function getServiceScenesCount() {
+    return SERVICE_SCENES.length;
+}
+export function getServicePermissionsCount() {
+    return SERVICE_PERMISSIONS.length;
+}
+export function getOrderFlowStage(stage) {
+    return SERVICE_ORDER_FLOW_STAGES.find(s => s.stage === stage);
+}
+export function getCrossObjectBindings() {
+    return [...SERVICE_CROSS_OBJECT_BINDINGS];
+}