@wowok/agent-mcp 2.4.3 → 2.5.0

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

@@ -0,0 +1,127 @@
+import { type RewardScene, type RewardBuiltinPermissionEntry, type RewardGuardConstructor, type RewardGuardConstructorSpec, type RewardPhase, type RewardRecipientType, type RewardAmountType } from "./reward-ledger.js";
+import { type RewardPuzzle, type RewardPuzzleCompleteness } from "./reward-puzzle.js";
+import { type RewardRiskAssessment, type RewardRiskRule, type RewardStakeholder } from "./reward-risk.js";
+import { type RewardSemanticToSchemaRule } from "./reward-translation.js";
+import { type RewardTemplate } from "./reward-templates.js";
+import { REWARD_OPERATION_CHECKLIST, REWARD_CONFIRMATION_QUESTIONS, type RewardJsonForConfirm } from "./reward-confirm.js";
+export declare const REWARD_CONTEXT_VERSION = "1.0.0";
+export type RewardInjectionMode = "initial_design" | "pre_claim" | "post_claim" | "guard_review" | "balance_review" | "stakeholder_review";
+export type RewardStakeholderPerspective = RewardStakeholder | "system";
+export interface RewardContextBundle {
+    version: string;
+    mode: RewardInjectionMode;
+    stakeholder_perspective?: RewardStakeholderPerspective;
+    matched_scene?: RewardScene;
+    matched_template?: RewardTemplate;
+    matched_pattern?: RewardSemanticToSchemaRule;
+    puzzle_state?: RewardPuzzle;
+    puzzle_completeness?: RewardPuzzleCompleteness;
+    relevant_risks: RewardRiskRule[];
+    risk_assessment?: RewardRiskAssessment;
+    relevant_checklist: typeof REWARD_OPERATION_CHECKLIST;
+    relevant_questions: typeof REWARD_CONFIRMATION_QUESTIONS;
+    relevant_builtin_permissions: RewardBuiltinPermissionEntry[];
+    relevant_guard_constructors: RewardGuardConstructorSpec[];
+    cross_object_refs: RewardCrossObjectRef[];
+    onchain_constraints: RewardOnchainConstraint[];
+    rendering_hints: RewardRenderingHints;
+}
+export interface RewardCrossObjectRef {
+    object: "Guard" | "Permission" | "Passport" | "Payment" | "Repository" | "Service" | "Demand" | "Allocation" | "Contact" | "Coin";
+    phase: RewardPhase | "universal";
+    relationship: string;
+    description: string;
+}
+export interface RewardOnchainConstraint {
+    name: string;
+    value: string | number;
+    description: string;
+    error_code?: string;
+}
+export interface RewardRenderingHints {
+    include_puzzle_template: boolean;
+    include_risk_details: boolean;
+    include_questions: boolean;
+    include_claim_warning: boolean;
+    include_owner_receive_warning: boolean;
+    include_cross_object_refs: boolean;
+    include_guard_constructor_matrix: boolean;
+    max_length: number;
+}
+export interface BuildRewardContextInput {
+    mode: RewardInjectionMode;
+    intent?: string;
+    reward_json?: RewardJsonForConfirm;
+    stakeholder?: RewardStakeholderPerspective;
+    target_phase?: RewardPhase;
+    target_industry?: string;
+    max_length?: number;
+    reward_type?: string;
+    current_balance?: string;
+    current_guard_count?: number;
+    current_record_count_for_recipient?: number;
+    current_guard_not_added_expiration_time?: number | null;
+    current_clock_ms?: number;
+    permission_address?: string;
+    signer?: string;
+    target_guard_addresses?: string[];
+    passport_submission_value_types?: Record<number, string>;
+    passport_identifier_is_address?: Record<number, boolean>;
+    guard_store_from_id_compatible?: Record<string, boolean>;
+}
+export declare function buildRewardContext(input: BuildRewardContextInput): RewardContextBundle;
+export declare function buildPromptFromRewardContext(bundle: RewardContextBundle): string;
+export declare function getRewardContextSummary(bundle: RewardContextBundle): string;
+export declare function buildStakeholderContext(stakeholder: RewardStakeholderPerspective, intent?: string, reward_json?: RewardJsonForConfirm): RewardContextBundle;
+export declare function quickValidateRewardJson(reward_json: RewardJsonForConfirm, current_state?: {
+    reward_type?: string;
+    current_balance?: string;
+    current_guard_count?: number;
+    current_record_count_for_recipient?: number;
+    current_guard_not_added_expiration_time?: number | null;
+    current_clock_ms?: number;
+    target_guard_addresses?: string[];
+}): {
+    ok: boolean;
+    violations: string[];
+};
+export declare function getRewardKnowledgeSnapshot(): {
+    version: {
+        ledger: string;
+        puzzle: string;
+        risk: string;
+        translation: string;
+        templates: number;
+        confirm: string;
+        context: string;
+    };
+    scenes_count: number;
+    builtin_permissions_count: number;
+    builtin_permissions: {
+        index: 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157;
+        name: string;
+        sdk_exposed: boolean;
+    }[];
+    guard_constructors_count: number;
+    guard_constructors: {
+        constructor: RewardGuardConstructor;
+        recipient_type: RewardRecipientType;
+        amount_type: RewardAmountType;
+    }[];
+    error_codes_count: number;
+    templates_count: number;
+    templates: RewardTemplate[];
+    semantic_patterns_count: number;
+    schema_rules_count: number;
+    constraint_rules_count: number;
+    risk_rules_count: number;
+    checklist_count: number;
+    confirmation_questions_count: number;
+    cross_object_refs_count: number;
+    onchain_limits: {
+        max_guard_count_reward: 200;
+        max_record_count_reward: 5200;
+    };
+    injection_modes: RewardInjectionMode[];
+    stakeholders: RewardStakeholderPerspective[];
+};

package/dist/knowledge/reward-context.js

@@ -0,0 +1,504 @@
+import { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD, } from "./onchain-constants.js";
+import { REWARD_PERMISSIONS, REWARD_GUARD_CONSTRUCTORS, REWARD_ERROR_CODES, REWARD_CROSS_OBJECT_REFS, REWARD_LEDGER_VERSION, inferSceneFromIntent, getScenesByIndustry, getScenesByPhase, getAllBuiltinPermissions, getRewardScenesCount, validateGuardCount, validateRecordCount, } from "./reward-ledger.js";
+import { initPuzzleFromIntent, checkPuzzleCompleteness, } from "./reward-puzzle.js";
+import { REWARD_RISK_VERSION, assessRewardRisks, getAllRewardRiskRules, getRewardRiskRulesCount, getRewardRiskRulesByStakeholder, REWARD_STAKEHOLDERS, } from "./reward-risk.js";
+import { REWARD_TRANSLATION_VERSION, REWARD_SEMANTIC_TO_SCHEMA_RULES, REWARD_SCHEMA_TO_SEMANTIC_RULES, REWARD_CONSTRAINT_RULES, matchSemanticPattern, } from "./reward-translation.js";
+import { REWARD_TEMPLATES, REWARD_TEMPLATES_VERSION, getRewardTemplate, listRewardTemplates, suggestRewardTemplate, } from "./reward-templates.js";
+import { REWARD_CONFIRM_VERSION, REWARD_OPERATION_CHECKLIST, REWARD_CONFIRMATION_QUESTIONS, } from "./reward-confirm.js";
+export const REWARD_CONTEXT_VERSION = "1.0.0";
+export function buildRewardContext(input) {
+    const max_length = input.max_length ?? 4000;
+    let matched_scene;
+    if (input.intent) {
+        matched_scene = inferSceneFromIntent(input.intent);
+    }
+    if (!matched_scene && input.target_phase) {
+        const phaseScenes = getScenesByPhase(input.target_phase);
+        if (phaseScenes.length > 0)
+            matched_scene = phaseScenes[0];
+    }
+    if (!matched_scene && input.target_industry) {
+        const industryScenes = getScenesByIndustry(input.target_industry);
+        if (industryScenes.length > 0)
+            matched_scene = industryScenes[0];
+    }
+    let matched_template;
+    if (input.intent) {
+        matched_template = suggestRewardTemplate(input.intent);
+    }
+    if (!matched_template && matched_scene && matched_scene.recommended_templates.length > 0) {
+        const tplType = matched_scene.recommended_templates[0];
+        matched_template = getRewardTemplate(tplType);
+    }
+    let matched_pattern;
+    if (input.intent) {
+        const patterns = matchSemanticPattern(input.intent);
+        if (patterns.length > 0)
+            matched_pattern = patterns[0];
+    }
+    let puzzle_state;
+    let puzzle_completeness;
+    if (input.mode === "initial_design" && input.intent) {
+        puzzle_state = initPuzzleFromIntent({ rule_sentence: input.intent });
+        puzzle_completeness = checkPuzzleCompleteness(puzzle_state);
+    }
+    const relevant_risks = filterRiskRules(input.mode, input.stakeholder, matched_scene);
+    let risk_assessment;
+    if (input.mode === "pre_claim" && input.reward_json) {
+        const ctx = {
+            object: input.reward_json.object,
+            claim: input.reward_json.claim,
+            description: input.reward_json.description,
+            coin_add: input.reward_json.coin_add,
+            receive: input.reward_json.receive,
+            guard_add: input.reward_json.guard_add,
+            guard_remove_expired: input.reward_json.guard_remove_expired,
+            guard_expiration_time: input.reward_json.guard_expiration_time,
+            owner_receive: input.reward_json.owner_receive,
+            um: input.reward_json.um,
+            reward_type: input.reward_type,
+            current_balance: input.current_balance,
+            current_guard_count: input.current_guard_count,
+            current_record_count_for_recipient: input.current_record_count_for_recipient,
+            current_guard_not_added_expiration_time: input.current_guard_not_added_expiration_time,
+            current_clock_ms: input.current_clock_ms,
+            permission_address: input.permission_address,
+            signer: input.signer,
+            target_guard_addresses: input.target_guard_addresses,
+            passport_submission_value_types: input.passport_submission_value_types,
+            passport_identifier_is_address: input.passport_identifier_is_address,
+            guard_store_from_id_compatible: input.guard_store_from_id_compatible,
+        };
+        risk_assessment = assessRewardRisks(ctx);
+    }
+    const relevant_checklist = filterChecklist(input.mode);
+    const relevant_questions = filterQuestions(input.mode);
+    const relevant_builtin_permissions = matched_scene
+        ? matched_scene.builtin_indexes_consumed
+        : getAllBuiltinPermissions();
+    const relevant_guard_constructors = filterGuardConstructors(matched_scene);
+    const cross_object_refs = buildCrossObjectRefs(input.target_phase, matched_scene);
+    const onchain_constraints = buildOnchainConstraints();
+    const rendering_hints = buildRenderingHints(input.mode, max_length, !!input.reward_json?.claim, input.reward_json?.owner_receive != null, input.mode === "initial_design");
+    return {
+        version: REWARD_CONTEXT_VERSION,
+        mode: input.mode,
+        stakeholder_perspective: input.stakeholder,
+        matched_scene,
+        matched_template,
+        matched_pattern,
+        puzzle_state,
+        puzzle_completeness,
+        relevant_risks,
+        risk_assessment,
+        relevant_checklist,
+        relevant_questions,
+        relevant_builtin_permissions,
+        relevant_guard_constructors,
+        cross_object_refs,
+        onchain_constraints,
+        rendering_hints,
+    };
+}
+function filterRiskRules(mode, stakeholder, scene) {
+    const allRules = getAllRewardRiskRules();
+    if (mode === "initial_design") {
+        return allRules.filter(r => r.category === "structural" || r.category === "semantic");
+    }
+    if (mode === "pre_claim") {
+        return allRules;
+    }
+    if (mode === "post_claim") {
+        return allRules.filter(r => r.id === "R-R-1-02" || r.id === "R-R-4-02" || r.id === "R-R-4-01");
+    }
+    if (mode === "guard_review") {
+        return allRules.filter(r => r.category === "structural" || r.category === "lifecycle" || r.category === "semantic");
+    }
+    if (mode === "balance_review") {
+        return allRules.filter(r => r.category === "cross_object" || r.id === "R-R-4-02" || r.id === "R-R-3-02");
+    }
+    if (mode === "stakeholder_review" && stakeholder) {
+        const stakeholderNorm = stakeholder === "system" ? "system" : stakeholder;
+        return getRewardRiskRulesByStakeholder(stakeholderNorm);
+    }
+    return allRules;
+}
+function filterChecklist(mode) {
+    if (mode === "initial_design") {
+        return REWARD_OPERATION_CHECKLIST.filter(i => ["C-R-01", "C-R-06"].includes(i.id));
+    }
+    if (mode === "pre_claim") {
+        return REWARD_OPERATION_CHECKLIST.filter(i => ["C-R-02", "C-R-03", "C-R-05", "C-R-08"].includes(i.id));
+    }
+    if (mode === "guard_review") {
+        return REWARD_OPERATION_CHECKLIST.filter(i => ["C-R-01", "C-R-04", "C-R-05", "C-R-06", "C-R-10"].includes(i.id));
+    }
+    if (mode === "balance_review") {
+        return REWARD_OPERATION_CHECKLIST.filter(i => ["C-R-03", "C-R-07", "C-R-09"].includes(i.id));
+    }
+    if (mode === "stakeholder_review") {
+        return REWARD_OPERATION_CHECKLIST;
+    }
+    return REWARD_OPERATION_CHECKLIST;
+}
+function filterQuestions(mode) {
+    if (mode === "pre_claim") {
+        return REWARD_CONFIRMATION_QUESTIONS.filter(q => ["QRW1", "QRW2", "QRW5"].includes(q.id));
+    }
+    if (mode === "guard_review") {
+        return REWARD_CONFIRMATION_QUESTIONS.filter(q => ["QRW2", "QRW4"].includes(q.id));
+    }
+    if (mode === "balance_review") {
+        return REWARD_CONFIRMATION_QUESTIONS.filter(q => ["QRW3", "QRW6"].includes(q.id));
+    }
+    if (mode === "initial_design") {
+        return [];
+    }
+    return [];
+}
+function filterGuardConstructors(scene) {
+    if (!scene)
+        return [...REWARD_GUARD_CONSTRUCTORS];
+    const recipientTypes = new Set(scene.recipient_types_used);
+    const amountTypes = new Set(scene.amount_types_used);
+    return REWARD_GUARD_CONSTRUCTORS.filter(c => recipientTypes.has(c.recipient_type) && amountTypes.has(c.amount_type));
+}
+function buildCrossObjectRefs(targetPhase, scene) {
+    const refs = REWARD_CROSS_OBJECT_REFS.map(r => ({
+        object: r.object,
+        phase: r.phase,
+        relationship: r.relationship,
+        description: r.relationship,
+    }));
+    if (targetPhase) {
+        return refs.filter(r => r.phase === targetPhase || r.phase === "universal");
+    }
+    if (scene) {
+        const scenePhases = scene.phases;
+        return refs.filter(r => r.phase === "universal" || scenePhases.includes(r.phase));
+    }
+    return refs;
+}
+function buildOnchainConstraints() {
+    return [
+        {
+            name: "MAX_GUARD_COUNT_REWARD",
+            value: MAX_GUARD_COUNT_REWARD,
+            description: "Maximum guards per Reward",
+            error_code: "E_GUARD_COUNT_EXCEEDED",
+        },
+        {
+            name: "MAX_RECORD_COUNT_REWARD",
+            value: MAX_RECORD_COUNT_REWARD,
+            description: "Maximum records per recipient (per-recipient claim history cap)",
+            error_code: "E_RECORD_COUNT_EXCEEDED",
+        },
+        {
+            name: "REWARD_NEW (150)",
+            value: 150,
+            description: "Builtin: create new Reward (new / new_with_passport)",
+        },
+        {
+            name: "REWARD_DESCRIPTION (151)",
+            value: 151,
+            description: "Builtin: update description (description_set)",
+        },
+        {
+            name: "REWARD_GUARD (152)",
+            value: 152,
+            description: "Builtin: add / remove expired guards (guard_add, guard_remove_expired)",
+        },
+        {
+            name: "REWARD_COIN_ADD (153)",
+            value: 153,
+            description: "Builtin: deposit Coin<T> into balance (coin_add)",
+        },
+        {
+            name: "REWARD_RECEIVE (154)",
+            value: 154,
+            description: "Builtin: receive CoinWrapper<T> via Payment (receive)",
+        },
+        {
+            name: "REWARD_GUARD_EXPIRATION_TIME_ADD (155)",
+            value: 155,
+            description: "Builtin: set/cancel guard_not_added_expiration_time (time-lock on guard additions)",
+            error_code: "E_GUARD_LOCKED_TIME",
+        },
+        {
+            name: "REWARD_OWNER_RECEIVE (156)",
+            value: 156,
+            description: "Builtin: owner unwrap Receiving<K>/CoinWrapper<K> (owner_receive, owner_receive_object)",
+        },
+        {
+            name: "REWARD_UM (157)",
+            value: 157,
+            description: "Builtin: bind/unbind Contact (UM) (um_set, um_none)",
+        },
+        {
+            name: "E_INSUFFICIENT_BALANCE",
+            value: 6,
+            description: "Move error: claim with balance < amount (balance::split aborts)",
+        },
+        {
+            name: "E_GUARD_NOT_FOUND",
+            value: 7,
+            description: "Move error: claim with guard not in self.guards",
+        },
+        {
+            name: "E_GUARD_EXPIRED",
+            value: 2,
+            description: "Move error: guard_add / claim with expiration_time < now",
+        },
+        {
+            name: "E_GUARD_LOCKED_TIME",
+            value: 10,
+            description: "Move error: guard_add while guard_not_added_expiration_time is Some and clock ≤ expiration",
+        },
+        {
+            name: "E_AMOUNT_NOT_U64",
+            value: 5,
+            description: "Move error: RewardGuard constructor with GuardU64Identifier amount where identifier type ≠ u64",
+        },
+        {
+            name: "E_RECIPIENT_IDENTIFIER_NOT_ADDRESS",
+            value: 4,
+            description: "Move error: RewardGuard constructor with GuardIdentifier recipient where identifier type ≠ address",
+        },
+        {
+            name: "E_STORE_FROM_ID_NOT_COMPATIBLE",
+            value: 12,
+            description: "Move error: RewardGuard constructor with store_from_id where identifier is not number/address compatible",
+        },
+    ];
+}
+function buildRenderingHints(mode, max_length, hasClaim, hasOwnerReceive, isInitialDesign) {
+    return {
+        include_puzzle_template: isInitialDesign,
+        include_risk_details: mode === "pre_claim" || mode === "stakeholder_review",
+        include_questions: mode === "pre_claim" || mode === "guard_review" || mode === "balance_review",
+        include_claim_warning: hasClaim,
+        include_owner_receive_warning: hasOwnerReceive,
+        include_cross_object_refs: mode === "initial_design" || mode === "stakeholder_review",
+        include_guard_constructor_matrix: isInitialDesign || mode === "guard_review",
+        max_length,
+    };
+}
+export function buildPromptFromRewardContext(bundle) {
+    const lines = [];
+    const h = bundle.rendering_hints;
+    lines.push(`═══ Reward Context (mode: ${bundle.mode}) ═══`);
+    lines.push("");
+    if (bundle.stakeholder_perspective) {
+        lines.push(`Stakeholder perspective: ${bundle.stakeholder_perspective}`);
+        lines.push("");
+    }
+    if (bundle.matched_scene) {
+        lines.push(`Scene: ${bundle.matched_scene.name}`);
+        lines.push(`Phases: ${bundle.matched_scene.phases.join(", ")}`);
+        lines.push(`Typical guard count: ${bundle.matched_scene.typical_guard_count}/${MAX_GUARD_COUNT_REWARD}`);
+        lines.push(`Recipient types: ${bundle.matched_scene.recipient_types_used.join(", ")}`);
+        lines.push(`Amount types: ${bundle.matched_scene.amount_types_used.join(", ")}`);
+        lines.push(`Uses expiration_time: ${bundle.matched_scene.uses_expiration_time ? "YES" : "NO"}`);
+        lines.push("");
+    }
+    if (bundle.matched_template) {
+        lines.push(`Suggested template: ${bundle.matched_template.type} — ${bundle.matched_template.name}`);
+        lines.push("");
+    }
+    if (bundle.matched_pattern) {
+        lines.push(`Matched pattern: ${bundle.matched_pattern.id} — ${bundle.matched_pattern.pattern_name}`);
+        lines.push(`Intent: ${bundle.matched_pattern.semantic_intent}`);
+        lines.push("");
+    }
+    if (h.include_puzzle_template && bundle.puzzle_completeness) {
+        const c = bundle.puzzle_completeness;
+        lines.push("─ Puzzle Completeness ──────────────");
+        lines.push(`Complete: ${c.complete ? "YES" : "NO"}`);
+        if (c.missing.length > 0) {
+            lines.push(`Missing dimensions: ${c.missing.join(", ")}`);
+            for (const md of c.missing_details) {
+                lines.push(`  - ${md.dimension}: ${md.reason}`);
+            }
+        }
+        lines.push(`Next: ${c.next_step}`);
+        lines.push("");
+    }
+    if (h.include_guard_constructor_matrix && bundle.relevant_guard_constructors.length > 0) {
+        lines.push(`─ Guard Constructors (${bundle.relevant_guard_constructors.length}) ──────────────`);
+        for (const c of bundle.relevant_guard_constructors) {
+            lines.push(`  ${c.constructor}: ${c.recipient_type} × ${c.amount_type}`);
+            lines.push(`    use: ${c.typical_use}`);
+        }
+        lines.push("");
+    }
+    if (h.include_risk_details && bundle.relevant_risks.length > 0) {
+        lines.push(`─ Relevant Risk Rules (${bundle.relevant_risks.length}) ──────────────`);
+        for (const r of bundle.relevant_risks.slice(0, 6)) {
+            lines.push(`  ${r.id} [${r.category}] — ${r.trigger}`);
+        }
+        if (bundle.relevant_risks.length > 6) {
+            lines.push(`  ... and ${bundle.relevant_risks.length - 6} more`);
+        }
+        lines.push("");
+    }
+    if (bundle.risk_assessment) {
+        lines.push("─ Risk Assessment ──────────────");
+        lines.push(`Overall: ${bundle.risk_assessment.overall_risk}`);
+        lines.push(`Detected: ${bundle.risk_assessment.risks.length} risk(s)`);
+        if (bundle.risk_assessment.needs_human_review) {
+            lines.push("⚠️ Needs human review (HIGH/CRITICAL risks present)");
+        }
+        lines.push("");
+    }
+    if (bundle.relevant_builtin_permissions.length > 0) {
+        lines.push(`─ Builtin Permissions (${bundle.relevant_builtin_permissions.length}) ──────────────`);
+        for (const p of bundle.relevant_builtin_permissions) {
+            lines.push(`  [${p.index}] ${p.name}: ${p.description}`);
+        }
+        lines.push("");
+    }
+    if (h.include_claim_warning) {
+        lines.push("⚠️ CLAIM IS PERMISSION-FREE: anyone with a valid Passport + Guard can claim.");
+        lines.push("   Ensure the Guard binds to specific Service/Order context to prevent unauthorized claims.");
+        lines.push("");
+    }
+    if (h.include_owner_receive_warning) {
+        lines.push("⚠️ OWNER_RECEIVE (156): unwrap forwards to Permission owner (NOT Reward creator).");
+        lines.push("   Grant 156 only to dedicated addresses; log every invocation for audit.");
+        lines.push("");
+    }
+    if (h.include_cross_object_refs && bundle.cross_object_refs.length > 0) {
+        lines.push(`─ Cross-Object References (${bundle.cross_object_refs.length}) ──────────────`);
+        for (const ref of bundle.cross_object_refs.slice(0, 8)) {
+            lines.push(`  ${ref.object} [${ref.phase}]: ${ref.relationship}`);
+        }
+        if (bundle.cross_object_refs.length > 8) {
+            lines.push(`  ... and ${bundle.cross_object_refs.length - 8} more`);
+        }
+        lines.push("");
+    }
+    if (bundle.onchain_constraints.length > 0) {
+        lines.push("─ On-chain Constraints ──────────────");
+        for (const c of bundle.onchain_constraints) {
+            const errPart = c.error_code ? ` (abort: ${c.error_code})` : "";
+            lines.push(`  ${c.name} = ${c.value} — ${c.description}${errPart}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export function getRewardContextSummary(bundle) {
+    const parts = [
+        `mode=${bundle.mode}`,
+        `scene=${bundle.matched_scene?.id ?? "none"}`,
+        `risks=${bundle.relevant_risks.length}`,
+        `permissions=${bundle.relevant_builtin_permissions.length}`,
+        `constructors=${bundle.relevant_guard_constructors.length}`,
+        `cross_refs=${bundle.cross_object_refs.length}`,
+    ];
+    if (bundle.stakeholder_perspective)
+        parts.push(`stakeholder=${bundle.stakeholder_perspective}`);
+    if (bundle.risk_assessment)
+        parts.push(`overall_risk=${bundle.risk_assessment.overall_risk}`);
+    if (bundle.matched_template)
+        parts.push(`template=${bundle.matched_template.type}`);
+    if (bundle.matched_pattern)
+        parts.push(`pattern=${bundle.matched_pattern.id}`);
+    return parts.join(", ");
+}
+export function buildStakeholderContext(stakeholder, intent, reward_json) {
+    return buildRewardContext({
+        mode: "stakeholder_review",
+        intent,
+        reward_json,
+        stakeholder,
+    });
+}
+export function quickValidateRewardJson(reward_json, current_state = {}) {
+    const violations = [];
+    if (reward_json.guard_add && reward_json.guard_add.length > 0) {
+        const current = current_state.current_guard_count ?? 0;
+        const check = validateGuardCount(current);
+        if (!check.ok)
+            violations.push(check.violation);
+    }
+    if (reward_json.claim) {
+        const records = current_state.current_record_count_for_recipient ?? 0;
+        const check = validateRecordCount(records);
+        if (!check.ok)
+            violations.push(check.violation);
+    }
+    if (reward_json.coin_add && current_state.reward_type) {
+        if (reward_json.coin_add.coin_type !== current_state.reward_type) {
+            violations.push(`coin_add type ${reward_json.coin_add.coin_type} ≠ Reward<${current_state.reward_type}>`);
+        }
+    }
+    if (reward_json.claim && current_state.target_guard_addresses) {
+        if (!current_state.target_guard_addresses.includes(reward_json.claim)) {
+            violations.push(`claim guard ${reward_json.claim} not in Reward.guards — E_GUARD_NOT_FOUND`);
+        }
+    }
+    if (reward_json.claim && current_state.current_balance !== undefined) {
+        const balance = BigInt(current_state.current_balance);
+        if (balance === 0n) {
+            violations.push("balance=0 — E_INSUFFICIENT_BALANCE will abort claim");
+        }
+    }
+    if (reward_json.guard_expiration_time !== undefined &&
+        reward_json.guard_expiration_time !== null &&
+        current_state.current_clock_ms !== undefined) {
+        if (reward_json.guard_expiration_time <= current_state.current_clock_ms) {
+            violations.push(`guard_expiration_time ${reward_json.guard_expiration_time} ≤ clock ${current_state.current_clock_ms} — E_GUARD_LOCKED_TIME_INVALID`);
+        }
+    }
+    return { ok: violations.length === 0, violations };
+}
+export function getRewardKnowledgeSnapshot() {
+    return {
+        version: {
+            ledger: REWARD_LEDGER_VERSION,
+            puzzle: "1.0.0",
+            risk: REWARD_RISK_VERSION,
+            translation: REWARD_TRANSLATION_VERSION,
+            templates: REWARD_TEMPLATES_VERSION,
+            confirm: REWARD_CONFIRM_VERSION,
+            context: REWARD_CONTEXT_VERSION,
+        },
+        scenes_count: getRewardScenesCount(),
+        builtin_permissions_count: REWARD_PERMISSIONS.length,
+        builtin_permissions: REWARD_PERMISSIONS.map(p => ({
+            index: p.index,
+            name: p.name,
+            sdk_exposed: p.sdk_exposed,
+        })),
+        guard_constructors_count: REWARD_GUARD_CONSTRUCTORS.length,
+        guard_constructors: REWARD_GUARD_CONSTRUCTORS.map(c => ({
+            constructor: c.constructor,
+            recipient_type: c.recipient_type,
+            amount_type: c.amount_type,
+        })),
+        error_codes_count: REWARD_ERROR_CODES.length,
+        templates_count: REWARD_TEMPLATES.length,
+        templates: listRewardTemplates(),
+        semantic_patterns_count: REWARD_SEMANTIC_TO_SCHEMA_RULES.length,
+        schema_rules_count: REWARD_SCHEMA_TO_SEMANTIC_RULES.length,
+        constraint_rules_count: REWARD_CONSTRAINT_RULES.length,
+        risk_rules_count: getRewardRiskRulesCount(),
+        checklist_count: REWARD_OPERATION_CHECKLIST.length,
+        confirmation_questions_count: REWARD_CONFIRMATION_QUESTIONS.length,
+        cross_object_refs_count: REWARD_CROSS_OBJECT_REFS.length,
+        onchain_limits: {
+            max_guard_count_reward: MAX_GUARD_COUNT_REWARD,
+            max_record_count_reward: MAX_RECORD_COUNT_REWARD,
+        },
+        injection_modes: [
+            "initial_design",
+            "pre_claim",
+            "post_claim",
+            "guard_review",
+            "balance_review",
+            "stakeholder_review",
+        ],
+        stakeholders: REWARD_STAKEHOLDERS,
+    };
+}