@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/reward-ledger.d.ts

@@ -0,0 +1,96 @@
+import { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD } from "./onchain-constants.js";
+export { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD, };
+export type RewardPhase = "creation" | "guard_addition" | "guard_lock_mgmt" | "funds_replenish" | "claim" | "um_mgmt" | "owner_receive" | "description_update" | "permission_update";
+export interface RewardBuiltinPermissionEntry {
+    index: 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157;
+    name: string;
+    description: string;
+    governed_operations: string[];
+    sdk_exposed: boolean;
+}
+export type RewardRecipientType = "GuardIdentifier" | "Entity" | "Signer";
+export type RewardAmountType = "GuardU64Identifier" | "Fixed";
+export type RewardGuardConstructor = "guard_u8_u8" | "guard_u8_u64" | "guard_entity_u8" | "guard_entity_u64" | "guard_signer_u8" | "guard_signer_u64";
+export interface RewardGuardConstructorSpec {
+    constructor: RewardGuardConstructor;
+    recipient_type: RewardRecipientType;
+    amount_type: RewardAmountType;
+    params: {
+        recipient_param?: "u8" | "address";
+        amount_param: "u8" | "u64";
+        expiration_time: "Option<u64>";
+        store_from_id: "Option<u8>";
+    };
+    construction_checks: string[];
+    typical_use: string;
+}
+export interface RewardScene {
+    id: string;
+    name: string;
+    industry: string[];
+    scenario: string;
+    phases: RewardPhase[];
+    coin_type_note: string;
+    typical_guard_count: number;
+    recipient_types_used: RewardRecipientType[];
+    amount_types_used: RewardAmountType[];
+    uses_expiration_time: boolean;
+    uses_store_from_id: boolean;
+    builtin_indexes_consumed: RewardBuiltinPermissionEntry[];
+    common_patterns: string[];
+    recommended_templates: string[];
+}
+export declare const REWARD_NEW: RewardBuiltinPermissionEntry;
+export declare const REWARD_DESCRIPTION: RewardBuiltinPermissionEntry;
+export declare const REWARD_GUARD: RewardBuiltinPermissionEntry;
+export declare const REWARD_COIN_ADD: RewardBuiltinPermissionEntry;
+export declare const REWARD_RECEIVE: RewardBuiltinPermissionEntry;
+export declare const REWARD_GUARD_EXPIRATION_TIME_ADD: RewardBuiltinPermissionEntry;
+export declare const REWARD_OWNER_RECEIVE: RewardBuiltinPermissionEntry;
+export declare const REWARD_UM: RewardBuiltinPermissionEntry;
+export declare const REWARD_PERMISSIONS: RewardBuiltinPermissionEntry[];
+export interface RewardFieldEntry {
+    name: string;
+    move_type: string;
+    mutability: "immutable" | "admin_mutable" | "runtime";
+    set_at_creation: boolean;
+    constraint: string;
+    permission_index?: number;
+    related_errors?: string[];
+}
+export declare const REWARD_FIELDS: RewardFieldEntry[];
+export declare const REWARD_GUARD_CONSTRUCTORS: RewardGuardConstructorSpec[];
+export interface RewardErrorCodeEntry {
+    code: number;
+    name: string;
+    description: string;
+    trigger_operation: string;
+}
+export declare const REWARD_ERROR_CODES: RewardErrorCodeEntry[];
+export declare const REWARD_SCENES: RewardScene[];
+export declare const REWARD_LEDGER_VERSION = "1.0.0";
+export declare function getScenesByPhase(phase: RewardPhase): RewardScene[];
+export declare function findSceneById(id: string): RewardScene | undefined;
+export declare function getScenesByIndustry(industry: string): RewardScene[];
+export declare function getBuiltinPermissionByIndex(index: number): RewardBuiltinPermissionEntry | undefined;
+export declare function isRewardBuiltinPermission(index: number): boolean;
+export declare function getAllBuiltinPermissions(): RewardBuiltinPermissionEntry[];
+export declare function getRewardScenesCount(): number;
+export declare function getGuardConstructorSpec(constructor: RewardGuardConstructor): RewardGuardConstructorSpec | undefined;
+export declare function resolveGuardConstructor(recipient_type: RewardRecipientType, amount_type: RewardAmountType): RewardGuardConstructor | undefined;
+export declare function getRewardErrorByCode(code: number): RewardErrorCodeEntry | undefined;
+export declare function getRewardErrorByName(name: string): RewardErrorCodeEntry | undefined;
+export declare function validateGuardCount(currentGuardCount: number): {
+    ok: boolean;
+    violation?: string;
+};
+export declare function validateRecordCount(currentRecordCount: number): {
+    ok: boolean;
+    violation?: string;
+};
+export declare function inferSceneFromIntent(intent: string): RewardScene | undefined;
+export declare const REWARD_CROSS_OBJECT_REFS: Array<{
+    object: "Guard" | "Permission" | "Passport" | "Payment" | "Repository" | "Service" | "Demand" | "Allocation" | "Contact" | "Coin";
+    phase: RewardPhase | "universal";
+    relationship: string;
+}>;

package/dist/knowledge/reward-ledger.js

@@ -0,0 +1,502 @@
+import { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD, } from "./onchain-constants.js";
+export { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD, };
+export const REWARD_NEW = {
+    index: 150,
+    name: "REWARD_NEW",
+    description: "Create new Reward<T> (asserted by reward::new / new_with_passport)",
+    governed_operations: ["reward::new", "reward::new_with_passport"],
+    sdk_exposed: true,
+};
+export const REWARD_DESCRIPTION = {
+    index: 151,
+    name: "REWARD_DESCRIPTION",
+    description: "Update description (asserted by reward::description_set / _with_passport)",
+    governed_operations: ["reward::description_set", "reward::description_set_with_passport"],
+    sdk_exposed: true,
+};
+export const REWARD_GUARD = {
+    index: 152,
+    name: "REWARD_GUARD",
+    description: "Add / remove expired guards (≤ MAX_GUARD_COUNT_REWARD=200)",
+    governed_operations: [
+        "reward::guard_add",
+        "reward::guard_add_with_passport",
+        "reward::guard_remove_expired",
+        "reward::guard_remove_expired_with_passport",
+    ],
+    sdk_exposed: true,
+};
+export const REWARD_COIN_ADD = {
+    index: 153,
+    name: "REWARD_COIN_ADD",
+    description: "Deposit Coin<T> directly into Reward balance (joins Balance<T>)",
+    governed_operations: ["reward::coin_add", "reward::coin_add_with_passport"],
+    sdk_exposed: true,
+};
+export const REWARD_RECEIVE = {
+    index: 154,
+    name: "REWARD_RECEIVE",
+    description: "Receive CoinWrapper<T> via Payment.unwrap_with_check (joins Balance<T>)",
+    governed_operations: ["reward::receive", "reward::receive_with_passport"],
+    sdk_exposed: true,
+};
+export const REWARD_GUARD_EXPIRATION_TIME_ADD = {
+    index: 155,
+    name: "REWARD_GUARD_EXPIRATION_TIME_ADD",
+    description: "Set / cancel guard_not_added_expiration_time (time-lock on new guard additions)",
+    governed_operations: [
+        "reward::guard_expiration_time_add",
+        "reward::guard_expiration_time_add_with_passport",
+    ],
+    sdk_exposed: true,
+};
+export const REWARD_OWNER_RECEIVE = {
+    index: 156,
+    name: "REWARD_OWNER_RECEIVE",
+    description: "Owner receives Receiving<K> / CoinWrapper<K> at terminal state (unwrap → owner)",
+    governed_operations: [
+        "reward::owner_receive",
+        "reward::owner_receive_with_passport",
+        "reward::owner_receive_object",
+        "reward::owner_receive_object_with_passport",
+    ],
+    sdk_exposed: true,
+};
+export const REWARD_UM = {
+    index: 157,
+    name: "REWARD_UM",
+    description: "Bind / unbind Contact (UM) for off-chain coordination",
+    governed_operations: [
+        "reward::um_set",
+        "reward::um_set_with_passport",
+        "reward::um_none",
+        "reward::um_none_with_passport",
+    ],
+    sdk_exposed: true,
+};
+export const REWARD_PERMISSIONS = [
+    REWARD_NEW,
+    REWARD_DESCRIPTION,
+    REWARD_GUARD,
+    REWARD_COIN_ADD,
+    REWARD_RECEIVE,
+    REWARD_GUARD_EXPIRATION_TIME_ADD,
+    REWARD_OWNER_RECEIVE,
+    REWARD_UM,
+];
+export const REWARD_FIELDS = [
+    {
+        name: "id",
+        move_type: "UID",
+        mutability: "immutable",
+        set_at_creation: true,
+        constraint: "Object UID; assigned in new_imp via object::new(ctx). Never changes.",
+    },
+    {
+        name: "description",
+        move_type: "String",
+        mutability: "admin_mutable",
+        set_at_creation: true,
+        permission_index: 151,
+        constraint: "Must satisfy common::DESCRIPTION. Updated via description_set (151).",
+    },
+    {
+        name: "guards",
+        move_type: "vector<RewardGuard>",
+        mutability: "admin_mutable",
+        set_at_creation: true,
+        permission_index: 152,
+        constraint: "vector::length < MAX_GUARD_COUNT (200); E_GUARD_COUNT_EXCEEDED on overflow.",
+        related_errors: ["E_GUARD_COUNT_EXCEEDED"],
+    },
+    {
+        name: "balance",
+        move_type: "Balance<T>",
+        mutability: "runtime",
+        set_at_creation: true,
+        constraint: "Zero at creation (balance::zero()); grows via coin_add/receive; shrinks via claim (split) and never via direct withdraw.",
+        related_errors: ["E_INSUFFICIENT_BALANCE"],
+    },
+    {
+        name: "guard_not_added_expiration_time",
+        move_type: "Option<u64>",
+        mutability: "admin_mutable",
+        set_at_creation: true,
+        permission_index: 155,
+        constraint: "Option<timestamp_ms>. When Some(t): guard_add requires clock > t (E_GUARD_LOCKED_TIME). When None or t < now: guards can be added.",
+        related_errors: ["E_GUARD_LOCKED_TIME", "E_GUARD_LOCKED_TIME_NOT_INCREASING", "E_GUARD_LOCKED_TIME_INVALID"],
+    },
+    {
+        name: "record",
+        move_type: "ParentTable<address, RecipientRecord>",
+        mutability: "runtime",
+        set_at_creation: true,
+        constraint: "Per-recipient claim history. Each RecipientRecord.amount vector has length < MAX_RECORD_COUNT (5200); E_RECORD_COUNT_EXCEEDED on overflow.",
+        related_errors: ["E_RECORD_COUNT_EXCEEDED"],
+    },
+    {
+        name: "um",
+        move_type: "Option<address>",
+        mutability: "admin_mutable",
+        set_at_creation: true,
+        permission_index: 157,
+        constraint: "Option<Contact address>. um_set creates Registrar affiliation; um_none disaffiliates.",
+    },
+    {
+        name: "permission",
+        move_type: "address",
+        mutability: "admin_mutable",
+        set_at_creation: true,
+        constraint: "Permission object address. Updated via permission_set (asserts old.owner == sender). Creates Registrar affiliation_change.",
+    },
+];
+export const REWARD_GUARD_CONSTRUCTORS = [
+    {
+        constructor: "guard_u8_u8",
+        recipient_type: "GuardIdentifier",
+        amount_type: "GuardU64Identifier",
+        params: {
+            recipient_param: "u8",
+            amount_param: "u8",
+            expiration_time: "Option<u64>",
+            store_from_id: "Option<u8>",
+        },
+        construction_checks: [
+            "is_identifier_address(guard, recipient) — E_RECIPIENT_IDENTIFIER_NOT_ADDRESS (4)",
+            "get_submission_value_type(guard, amount) must be Some(TYPE_U64) — E_AMOUNT_NOT_U64 (5)",
+            "if store_from_id is Some: is_identifier_address_compatible — E_STORE_FROM_ID_NOT_COMPATIBLE (12)",
+        ],
+        typical_use: "Dynamic recipient + dynamic amount — both extracted from Passport at claim time (e.g. referral rewards where referrer and amount vary per claim).",
+    },
+    {
+        constructor: "guard_u8_u64",
+        recipient_type: "GuardIdentifier",
+        amount_type: "Fixed",
+        params: {
+            recipient_param: "u8",
+            amount_param: "u64",
+            expiration_time: "Option<u64>",
+            store_from_id: "Option<u8>",
+        },
+        construction_checks: [
+            "is_identifier_address(guard, recipient) — E_RECIPIENT_IDENTIFIER_NOT_ADDRESS (4)",
+            "if store_from_id is Some: is_identifier_address_compatible — E_STORE_FROM_ID_NOT_COMPATIBLE (12)",
+        ],
+        typical_use: "Dynamic recipient + fixed amount — e.g. first-order reward where any new customer claims a fixed 1 WOW.",
+    },
+    {
+        constructor: "guard_entity_u8",
+        recipient_type: "Entity",
+        amount_type: "GuardU64Identifier",
+        params: {
+            recipient_param: "address",
+            amount_param: "u8",
+            expiration_time: "Option<u64>",
+            store_from_id: "Option<u8>",
+        },
+        construction_checks: [
+            "get_submission_value_type(guard, amount) must be Some(TYPE_U64) — E_AMOUNT_NOT_U64 (5)",
+            "if store_from_id is Some: is_identifier_address_compatible — E_STORE_FROM_ID_NOT_COMPATIBLE (12)",
+        ],
+        typical_use: "Fixed recipient + dynamic amount — e.g. tiered loyalty reward where amount depends on Passport submission (tier level).",
+    },
+    {
+        constructor: "guard_entity_u64",
+        recipient_type: "Entity",
+        amount_type: "Fixed",
+        params: {
+            recipient_param: "address",
+            amount_param: "u64",
+            expiration_time: "Option<u64>",
+            store_from_id: "Option<u8>",
+        },
+        construction_checks: [
+            "if store_from_id is Some: is_identifier_address_compatible — E_STORE_FROM_ID_NOT_COMPATIBLE (12)",
+        ],
+        typical_use: "Fully fixed recipient + amount — simplest configuration (e.g. specific partner bounty).",
+    },
+    {
+        constructor: "guard_signer_u8",
+        recipient_type: "Signer",
+        amount_type: "GuardU64Identifier",
+        params: {
+            amount_param: "u8",
+            expiration_time: "Option<u64>",
+            store_from_id: "Option<u8>",
+        },
+        construction_checks: [
+            "get_submission_value_type(guard, amount) must be Some(TYPE_U64) — E_AMOUNT_NOT_U64 (5)",
+            "if store_from_id is Some: is_identifier_address_compatible — E_STORE_FROM_ID_NOT_COMPATIBLE (12)",
+        ],
+        typical_use: "Caller is recipient + dynamic amount — e.g. self-service claim where amount depends on Passport submission (e.g. cashback rate).",
+    },
+    {
+        constructor: "guard_signer_u64",
+        recipient_type: "Signer",
+        amount_type: "Fixed",
+        params: {
+            amount_param: "u64",
+            expiration_time: "Option<u64>",
+            store_from_id: "Option<u8>",
+        },
+        construction_checks: [
+            "if store_from_id is Some: is_identifier_address_compatible — E_STORE_FROM_ID_NOT_COMPATIBLE (12)",
+        ],
+        typical_use: "Caller is recipient + fixed amount — e.g. flash sale where any eligible caller claims a fixed reward.",
+    },
+];
+export const REWARD_ERROR_CODES = [
+    { code: 1, name: "E_GUARD_LOCKED_TIME_NOT_INCREASING", description: "guard_expiration_time_add: new time < current clock (must be ≥ now)", trigger_operation: "guard_expiration_time_add" },
+    { code: 2, name: "E_GUARD_EXPIRED", description: "guard_add on guard with expiration_time < now, OR claim on guard with expiration_time < now", trigger_operation: "guard_add / claim" },
+    { code: 3, name: "E_GUARD_COUNT_EXCEEDED", description: "guard_add would exceed MAX_GUARD_COUNT=200 (only on NEW guard, not on update of existing)", trigger_operation: "guard_add" },
+    { code: 4, name: "E_RECIPIENT_IDENTIFIER_NOT_ADDRESS", description: "RewardGuard constructor: recipient identifier type is not address (GuardIdentifier variant only)", trigger_operation: "reward_guard (constructor)" },
+    { code: 5, name: "E_AMOUNT_NOT_U64", description: "RewardGuard constructor: amount identifier type is not u64 (GuardU64Identifier variant only)", trigger_operation: "reward_guard (constructor)" },
+    { code: 6, name: "E_INSUFFICIENT_BALANCE", description: "claim: balance < amount (cannot split more than held)", trigger_operation: "claim" },
+    { code: 7, name: "E_GUARD_NOT_FOUND", description: "claim: no guard in self.guards matches the supplied guard address", trigger_operation: "claim" },
+    { code: 8, name: "E_RECORD_COUNT_EXCEEDED", description: "claim: recipient already has MAX_RECORD_COUNT=5200 entries (E_RECORD_COUNT_EXCEEDED)", trigger_operation: "claim" },
+    { code: 10, name: "E_GUARD_LOCKED_TIME", description: "guard_add while guard_not_added_expiration_time is Some and clock ≤ expiration_time", trigger_operation: "guard_add" },
+    { code: 11, name: "E_GUARD_LOCKED_TIME_INVALID", description: "guard_expiration_time_add: new Some(t) where t ≤ now (must be future)", trigger_operation: "guard_expiration_time_add" },
+    { code: 12, name: "E_STORE_FROM_ID_NOT_COMPATIBLE", description: "RewardGuard constructor: store_from_id identifier type is not number or address", trigger_operation: "reward_guard (constructor)" },
+];
+export const REWARD_SCENES = [
+    {
+        id: "reward_first_order",
+        name: "First-order reward",
+        industry: ["universal", "ecommerce", "service", "freelance"],
+        scenario: "New customers receive a fixed reward after their first order. Guard verifies order ownership + first-time status; " +
+            "Recipient=Signer (caller is the new customer); Amount=Fixed (e.g. 1 WOW).",
+        phases: ["creation", "guard_addition", "funds_replenish", "claim"],
+        coin_type_note: "T = project reward coin (e.g. 0x2::wow::WOW or a custom token)",
+        typical_guard_count: 1,
+        recipient_types_used: ["Signer"],
+        amount_types_used: ["Fixed"],
+        uses_expiration_time: true,
+        uses_store_from_id: false,
+        builtin_indexes_consumed: [REWARD_NEW, REWARD_GUARD, REWARD_COIN_ADD],
+        common_patterns: [
+            "guard_signer_u64 — caller claims a fixed amount (e.g. 1 WOW)",
+            "Guard verifies: order_address.holder == signer AND order is the first order (Repository query)",
+            "expiration_time bounds the campaign window (e.g. 30 days)",
+            "coin_add deposits the campaign budget upfront (e.g. 100 WOW for 100 claims)",
+        ],
+        recommended_templates: ["first_order"],
+    },
+    {
+        id: "reward_referral",
+        name: "Referral viral reward",
+        industry: ["universal", "ecommerce", "service", "content"],
+        scenario: "Both referrer and referee receive a reward when the referee completes a first order. Two guards: one for referrer (Entity), one for referee (Signer).",
+        phases: ["creation", "guard_addition", "funds_replenish", "claim"],
+        coin_type_note: "T = project reward coin",
+        typical_guard_count: 2,
+        recipient_types_used: ["Entity", "Signer"],
+        amount_types_used: ["Fixed"],
+        uses_expiration_time: true,
+        uses_store_from_id: true,
+        builtin_indexes_consumed: [REWARD_NEW, REWARD_GUARD, REWARD_COIN_ADD],
+        common_patterns: [
+            "guard_entity_u64 for referrer (recipient = referrer address, fixed amount)",
+            "guard_signer_u64 for referee (caller is recipient, fixed amount)",
+            "Guard verifies: referrer marked in Repository AND referee's order completed",
+            "store_from_id may record the order address for audit trail",
+        ],
+        recommended_templates: ["referral"],
+    },
+    {
+        id: "reward_loyalty",
+        name: "Loyalty tiered reward",
+        industry: ["universal", "ecommerce", "subscription", "content"],
+        scenario: "Customers unlock higher rewards after reaching cumulative spending tiers. Recipient=Signer; Amount=GuardU64Identifier (tier-dependent amount extracted from Passport).",
+        phases: ["creation", "guard_addition", "funds_replenish", "claim"],
+        coin_type_note: "T = project reward coin",
+        typical_guard_count: 1,
+        recipient_types_used: ["Signer"],
+        amount_types_used: ["GuardU64Identifier"],
+        uses_expiration_time: false,
+        uses_store_from_id: false,
+        builtin_indexes_consumed: [REWARD_NEW, REWARD_GUARD, REWARD_COIN_ADD],
+        common_patterns: [
+            "guard_signer_u8 — amount is dynamic, extracted from Passport submission (tier level → reward amount)",
+            "Guard verifies: cumulative spend ≥ tier threshold (Repository query)",
+            "No expiration_time — loyalty is perpetual (until deactivated via guard_remove_expired)",
+            "Guard submission value type MUST be u64 (E_AMOUNT_NOT_U64 otherwise)",
+        ],
+        recommended_templates: ["loyalty"],
+    },
+    {
+        id: "reward_flash_sale",
+        name: "Limited-time flash sale reward",
+        industry: ["universal", "ecommerce", "retail"],
+        scenario: "Time-bounded reward for the first N callers. Recipient=Signer; Amount=Fixed. Guard verifies time window + claim count.",
+        phases: ["creation", "guard_addition", "funds_replenish", "claim", "guard_lock_mgmt"],
+        coin_type_note: "T = project reward coin",
+        typical_guard_count: 1,
+        recipient_types_used: ["Signer"],
+        amount_types_used: ["Fixed"],
+        uses_expiration_time: true,
+        uses_store_from_id: false,
+        builtin_indexes_consumed: [REWARD_NEW, REWARD_GUARD, REWARD_COIN_ADD, REWARD_GUARD_EXPIRATION_TIME_ADD],
+        common_patterns: [
+            "guard_signer_u64 — fixed amount per claim (e.g. 2 WOW)",
+            "expiration_time bounds the flash sale window (e.g. 48 hours)",
+            "guard_expiration_time_add (155) may lock further guard additions during the sale",
+            "Budget = max_claims × amount; coin_add deposits this upfront",
+        ],
+        recommended_templates: ["flash_sale"],
+    },
+    {
+        id: "reward_bulk_discount",
+        name: "Bulk discount / cashback reward",
+        industry: ["universal", "ecommerce", "wholesale", "service"],
+        scenario: "Customer receives cashback proportional to order size. Recipient=Signer or Entity (order holder); Amount=GuardU64Identifier (cashback rate from Passport).",
+        phases: ["creation", "guard_addition", "funds_replenish", "claim"],
+        coin_type_note: "T = payment coin type (must match order payment for clean cashback)",
+        typical_guard_count: 1,
+        recipient_types_used: ["Signer", "Entity"],
+        amount_types_used: ["GuardU64Identifier"],
+        uses_expiration_time: false,
+        uses_store_from_id: true,
+        builtin_indexes_consumed: [REWARD_NEW, REWARD_GUARD, REWARD_COIN_ADD, REWARD_RECEIVE],
+        common_patterns: [
+            "guard_signer_u8 — caller claims dynamic amount (cashback = order_amount × rate)",
+            "store_from_id records the order address for cross-reference (audit trail)",
+            "receive (154) may be used to accept CoinWrapper<T> refunds that replenish the balance",
+            "Guard verifies: order.completed AND order.service == this Service",
+        ],
+        recommended_templates: ["cashback"],
+    },
+    {
+        id: "reward_milestone",
+        name: "Service milestone reward",
+        industry: ["universal", "ecommerce", "content", "subscription"],
+        scenario: "When a Service reaches a milestone (e.g. 100 orders), early supporters receive extra rewards. Recipient=Entity (early customer); Amount=Fixed.",
+        phases: ["creation", "guard_addition", "funds_replenish", "claim", "guard_lock_mgmt"],
+        coin_type_note: "T = project reward coin",
+        typical_guard_count: 50,
+        recipient_types_used: ["Entity"],
+        amount_types_used: ["Fixed"],
+        uses_expiration_time: true,
+        uses_store_from_id: false,
+        builtin_indexes_consumed: [REWARD_NEW, REWARD_GUARD, REWARD_COIN_ADD, REWARD_GUARD_EXPIRATION_TIME_ADD],
+        common_patterns: [
+            "guard_entity_u64 for each early customer (recipient = customer address, fixed amount)",
+            "Multiple guards (up to 50 for 50 early supporters) — well within MAX_GUARD_COUNT=200",
+            "Guard verifies: Service order_count >= milestone AND claimer is in early-customer list",
+            "guard_expiration_time_add (155) may lock the guard list after milestone setup",
+        ],
+        recommended_templates: ["milestone"],
+    },
+];
+export const REWARD_LEDGER_VERSION = "1.0.0";
+export function getScenesByPhase(phase) {
+    return REWARD_SCENES.filter(s => s.phases.includes(phase));
+}
+export function findSceneById(id) {
+    return REWARD_SCENES.find(s => s.id === id);
+}
+export function getScenesByIndustry(industry) {
+    return REWARD_SCENES.filter(s => s.industry.includes(industry) || s.industry.includes("universal"));
+}
+export function getBuiltinPermissionByIndex(index) {
+    return REWARD_PERMISSIONS.find(p => p.index === index);
+}
+export function isRewardBuiltinPermission(index) {
+    return getBuiltinPermissionByIndex(index) !== undefined;
+}
+export function getAllBuiltinPermissions() {
+    return [...REWARD_PERMISSIONS];
+}
+export function getRewardScenesCount() {
+    return REWARD_SCENES.length;
+}
+export function getGuardConstructorSpec(constructor) {
+    return REWARD_GUARD_CONSTRUCTORS.find(c => c.constructor === constructor);
+}
+export function resolveGuardConstructor(recipient_type, amount_type) {
+    const map = {
+        "GuardIdentifier|GuardU64Identifier": "guard_u8_u8",
+        "GuardIdentifier|Fixed": "guard_u8_u64",
+        "Entity|GuardU64Identifier": "guard_entity_u8",
+        "Entity|Fixed": "guard_entity_u64",
+        "Signer|GuardU64Identifier": "guard_signer_u8",
+        "Signer|Fixed": "guard_signer_u64",
+    };
+    return map[`${recipient_type}|${amount_type}`];
+}
+export function getRewardErrorByCode(code) {
+    return REWARD_ERROR_CODES.find(e => e.code === code);
+}
+export function getRewardErrorByName(name) {
+    return REWARD_ERROR_CODES.find(e => e.name === name);
+}
+export function validateGuardCount(currentGuardCount) {
+    if (currentGuardCount >= MAX_GUARD_COUNT_REWARD) {
+        return {
+            ok: false,
+            violation: `Guard count ${currentGuardCount} would exceed MAX_GUARD_COUNT_REWARD ${MAX_GUARD_COUNT_REWARD}`,
+        };
+    }
+    return { ok: true };
+}
+export function validateRecordCount(currentRecordCount) {
+    if (currentRecordCount >= MAX_RECORD_COUNT_REWARD) {
+        return {
+            ok: false,
+            violation: `Record count ${currentRecordCount} would exceed MAX_RECORD_COUNT_REWARD ${MAX_RECORD_COUNT_REWARD} — recipient can no longer claim`,
+        };
+    }
+    return { ok: true };
+}
+export function inferSceneFromIntent(intent) {
+    const lower = intent.toLowerCase();
+    const keywordMap = [
+        ["flash sale", "reward_flash_sale"],
+        ["flash_sale", "reward_flash_sale"],
+        ["limited-time", "reward_flash_sale"],
+        ["limited time", "reward_flash_sale"],
+        ["referral", "reward_referral"],
+        ["viral", "reward_referral"],
+        ["refer a friend", "reward_referral"],
+        ["invite", "reward_referral"],
+        ["loyalty", "reward_loyalty"],
+        ["tiered", "reward_loyalty"],
+        ["tier", "reward_loyalty"],
+        ["repeat", "reward_loyalty"],
+        ["cashback", "reward_bulk_discount"],
+        ["bulk discount", "reward_bulk_discount"],
+        ["bulk_discount", "reward_bulk_discount"],
+        ["wholesale", "reward_bulk_discount"],
+        ["milestone", "reward_milestone"],
+        ["early supporter", "reward_milestone"],
+        ["early customer", "reward_milestone"],
+        ["first order", "reward_first_order"],
+        ["first_order", "reward_first_order"],
+        ["new customer", "reward_first_order"],
+        ["first-time", "reward_first_order"],
+    ];
+    for (const [kw, sceneId] of keywordMap) {
+        if (lower.includes(kw)) {
+            const scene = findSceneById(sceneId);
+            if (scene)
+                return scene;
+        }
+    }
+    return undefined;
+}
+export const REWARD_CROSS_OBJECT_REFS = [
+    { object: "Permission", phase: "universal", relationship: "Reward.permission (address; borrowed for all 150-157 assertions)" },
+    { object: "Permission", phase: "permission_update", relationship: "permission_set: asserts old.owner == sender; creates Registrar affiliation_change" },
+    { object: "Guard", phase: "guard_addition", relationship: "RewardGuard.guard = guard.id_address (each guard registered via Registrar affiliation)" },
+    { object: "Guard", phase: "claim", relationship: "claim: iterates self.guards looking for guard.id_address match; E_GUARD_NOT_FOUND if no match" },
+    { object: "Guard", phase: "claim", relationship: "claim: passport::result_for_guard(passport, guard_id) verifies submission data" },
+    { object: "Passport", phase: "claim", relationship: "claim: passport::submission_get extracts recipient (address) and/or amount (u64) per RewardGuard variant" },
+    { object: "Passport", phase: "claim", relationship: "claim: if store_from_id is Some, extracts store-from address from Passport submission" },
+    { object: "Payment", phase: "funds_replenish", relationship: "receive (154): Payment.unwrap_with_check extracts Coin<T> from CoinWrapper<T> and joins balance" },
+    { object: "Payment", phase: "owner_receive", relationship: "owner_receive (156): Payment.unwrap_with_check forwards CoinWrapper<K> to Permission owner" },
+    { object: "Repository", phase: "claim", relationship: "Guard may query Repository (e.g. order history for first-order / loyalty verification)" },
+    { object: "Service", phase: "claim", relationship: "Guard may verify order.service == this Service (cashback / first-order scenarios)" },
+    { object: "Demand", phase: "guard_addition", relationship: "Guard may be shared with Demand (recommendation filtering); same Guard object address space" },
+    { object: "Allocation", phase: "owner_receive", relationship: "Terminal Allocation alloc may route funds back to Reward (replenishment loop)" },
+    { object: "Contact", phase: "um_mgmt", relationship: "um_set (157): binds Contact (UM) for off-chain coordination; creates Registrar affiliation" },
+    { object: "Coin", phase: "universal", relationship: "Reward<phantom T>: T is the coin type; balance: Balance<T>; coin_add expects Coin<T>" },
+];