@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/repository-translation.js

@@ -0,0 +1,422 @@
+import { MAX_POLICY_COUNT, MAX_POLICY_DESCRIPTION_LEN, MAX_POLICY_GUARD_COUNT, MAX_DATA_SIZE, MAX_ID_COUNT_ONCE, MAX_REWARD_COUNT, } from "@wowok/wowok";
+export const SEMANTIC_TO_REPOSITORY_SCHEMA_RULES = [
+    {
+        id: "P-REP-01",
+        pattern_name: "Clock-routed data (id=timestamp)",
+        routing_mode: "clock",
+        semantic_intent: "Data is keyed by current timestamp (id_from=Clock). Each write produces a unique timestamp-keyed entry. " +
+            "Suitable for append-only logs, time-series records, and audit trails. write_guard may be empty (id is " +
+            "auto-generated and predictable) or non-empty with data_from_submission set (guard supplies the data " +
+            "payload while id comes from the clock — e.g. oracle-fed time-series).",
+        match_keywords: ["timestamp", "log", "audit trail", "time-series", "append-only", "clock"],
+        schema_elements: {
+            id_from_value: 1,
+            required_policy_fields: ["name", "description", "id_from", "value_type", "write_guard"],
+            write_guard_requirement: "either",
+            move_entry_point: "data_when_id_from_set",
+            caller_input_shape: "{ name, data } — no id, no write_guard, no Passport",
+        },
+        constraints: [
+            "id_from MUST be Clock (1)",
+            "write_guard MAY be empty OR non-empty (R-D-1 refined)",
+            "If write_guard is non-empty, every PolicyGuard.id_from_submission MUST be None (E_POLICY_ID_FROM_SUBMISSION_FORBIDDEN=23)",
+            "data_from_submission MAY be set (used by data_when_id_from_set_with_passport)",
+            "Caller uses data_when_id_from_set (no guard) or data_when_id_from_set_with_passport (with guard)",
+            "ID is auto-generated from clock::timestamp_ms",
+        ],
+        example: {
+            name: "audit_log",
+            description: "Append-only audit log keyed by timestamp",
+            id_from: "Clock",
+            value_type: 0,
+            write_guard: [],
+        },
+    },
+    {
+        id: "P-REP-02",
+        pattern_name: "Signer-routed data (id=signer address)",
+        routing_mode: "signer",
+        semantic_intent: "Data is keyed by signer address (id_from=Signer). Each user has at most one data entry per policy. " +
+            "Suitable for user profiles, KYC attestations, per-user settings. write_guard may be empty (signer " +
+            "writes their own data) or non-empty with data_from_submission set (guard supplies the data payload " +
+            "while id comes from the signer — e.g. verified credential insertion).",
+        match_keywords: ["profile", "user data", "kyc", "per-user", "signer", "identity"],
+        schema_elements: {
+            id_from_value: 2,
+            required_policy_fields: ["name", "description", "id_from", "value_type", "write_guard"],
+            write_guard_requirement: "either",
+            move_entry_point: "data_when_id_from_set",
+            caller_input_shape: "{ name, data } — no id, no write_guard, no Passport",
+        },
+        constraints: [
+            "id_from MUST be Signer (2)",
+            "write_guard MAY be empty OR non-empty (R-D-1 refined)",
+            "If write_guard is non-empty, every PolicyGuard.id_from_submission MUST be None (E_POLICY_ID_FROM_SUBMISSION_FORBIDDEN=23)",
+            "data_from_submission MAY be set (used by data_when_id_from_set_with_passport)",
+            "Caller uses data_when_id_from_set (no guard) or data_when_id_from_set_with_passport (with guard)",
+            "ID is auto-generated from ctx.sender()",
+        ],
+        example: {
+            name: "user_profile",
+            description: "Per-user profile data keyed by signer address",
+            id_from: "Signer",
+            value_type: 0,
+            write_guard: [],
+        },
+    },
+    {
+        id: "P-REP-03",
+        pattern_name: "Guard-protected with caller-provided id (Mode 4)",
+        routing_mode: "guard_caller",
+        semantic_intent: "Data is keyed by caller-provided id (id_from=None). Write authorization requires a Passport submission " +
+            "verifying the guard. Suitable for application-specific keys (order IDs, content hashes, custom identifiers). " +
+            "The guard enforces WHO can write; the caller decides WHAT id to use.",
+        match_keywords: ["custom id", "order id", "content hash", "application key", "guard protected", "passport"],
+        schema_elements: {
+            id_from_value: 0,
+            required_policy_fields: ["name", "description", "id_from", "value_type", "write_guard"],
+            write_guard_requirement: "non_empty",
+            move_entry_point: "id_data_with_passport",
+            caller_input_shape: "{ name, items: [{ id, data, write_guard }] } — id and data provided by caller, Passport verifies guard",
+        },
+        constraints: [
+            "id_from MUST be None (0)",
+            "write_guard MUST be non-empty (R-D-1: E_POLICY_WRITE_GUARD_REQUIRED=22)",
+            "Each PolicyGuard MUST have id_from_submission=None AND data_from_submission=None",
+            "Caller uses id_data_with_passport entry point",
+            "Passport must verify one of the policy's write_guards",
+        ],
+        example: {
+            name: "order_metadata",
+            description: "Order-specific metadata keyed by order id, guard-protected",
+            id_from: "None",
+            value_type: 0,
+            write_guard: [
+                { guard: "0xguard_addr...", id_from_submission: null, data_from_submission: null },
+            ],
+        },
+    },
+    {
+        id: "P-REP-04",
+        pattern_name: "Guard-protected with submission-derived id/data (Mode 5)",
+        routing_mode: "guard_submission",
+        semantic_intent: "Data id and/or data payload are derived from Guard submission values in the Passport. This is the most " +
+            "flexible mode: the guard can compute both the key and the value from its internal table. Suitable for " +
+            "bridges (where the guard verifies an external event and outputs the bridged amount), oracle-fed data, " +
+            "and complex authorization patterns.",
+        match_keywords: ["oracle", "bridge", "submission", "guard derived", "computed id", "computed data"],
+        schema_elements: {
+            id_from_value: 0,
+            required_policy_fields: ["name", "description", "id_from", "value_type", "write_guard"],
+            write_guard_requirement: "non_empty",
+            move_entry_point: "id_data_mixed_with_passport",
+            caller_input_shape: "{ name, items: [{ write_guard, id?, data? }] } — id/data omitted where submission provides them",
+        },
+        constraints: [
+            "id_from MUST be None (0)",
+            "write_guard MUST be non-empty (R-D-1: E_POLICY_WRITE_GUARD_REQUIRED=22)",
+            "Each PolicyGuard may have id_from_submission and/or data_from_submission set",
+            "Caller uses id_data_mixed_with_passport entry point",
+            "SDK hasSubmissionSettings must check BOTH id_from_submission AND data_from_submission (P1-1 fix)",
+            "Passport must verify the specified write_guards",
+        ],
+        example: {
+            name: "oracle_price",
+            description: "Oracle-fed price data, id and data both from guard submission",
+            id_from: "None",
+            value_type: 0,
+            write_guard: [
+                {
+                    guard: "0xoracle_guard_addr...",
+                    id_from_submission: 0,
+                    data_from_submission: 1,
+                },
+            ],
+        },
+    },
+];
+export const REPOSITORY_FIELD_TRANSLATIONS = [
+    {
+        field_name: "policies",
+        value_type: "PolicyRule[]",
+        semantic: "List of policy rules defining data write permissions and routing. Each policy is a named data slot " +
+            "with its own write_guard list and id_from routing mode. Operations (data_add/data_remove) reference " +
+            "policies by name.",
+        format_example: "[{ name: 'audit_log', id_from: 'Clock', ... }]",
+        validation_rules: [
+            `Array length ≤ MAX_POLICY_COUNT (${MAX_POLICY_COUNT})`,
+            "Each policy name must be unique within the Repository",
+            "Move aborts with E_POLICY_COUNT_EXCEEDED (3) on overflow",
+            "Move aborts with E_POLICY_NOT_FOUND (7) when name not found",
+        ],
+    },
+    {
+        field_name: "policies[].name",
+        move_field: "PolicyRule.name",
+        value_type: "string",
+        semantic: "Policy name. Acts as the key for data_add/data_remove operations. Must be unique within the Repository. " +
+            "Cannot be empty if NAME_ALLOW_EMPTY is not set.",
+        format_example: "audit_log",
+        validation_rules: [
+            "Non-empty string (unless NAME_ALLOW_EMPTY)",
+            "Must match an existing policy name in data_add/data_remove operations",
+        ],
+    },
+    {
+        field_name: "policies[].description",
+        move_field: "PolicyRule.description",
+        value_type: "string",
+        semantic: "Human-readable description of what the policy is for. Helps with auditing and tooling.",
+        format_example: "Append-only audit log keyed by timestamp",
+        validation_rules: [
+            `Length ≤ MAX_POLICY_DESCRIPTION_LEN (${MAX_POLICY_DESCRIPTION_LEN})`,
+            "Move aborts with E_POLICY_DESCRIPTION_EXCEEDED (1)",
+        ],
+    },
+    {
+        field_name: "policies[].id_from",
+        move_field: "PolicyRule.id_from",
+        value_type: "u8 (number | 'None' | 'Clock' | 'Signer')",
+        semantic: "Source of data ID when writing data. None (0): caller provides id; Clock (1): id=timestamp; " +
+            "Signer (2): id=signer address. Determines which entry point to use for data operations. " +
+            "SDK parseIdFrom normalizes string forms before comparison [P1-2 fix].",
+        format_example: "0, 1, 2, 'None', 'Clock', 'Signer'",
+        validation_rules: [
+            "Must be one of: 0, 1, 2, 'None', 'Clock', 'Signer' (case-insensitive)",
+            "Move aborts with E_INVALID_ID_FROM (18) for invalid u8 values",
+            "R-D-1 (refined): None requires non-empty write_guard; Clock/Signer allows non-empty write_guard but every PolicyGuard.id_from_submission MUST be None (data_from_submission still allowed)",
+        ],
+    },
+    {
+        field_name: "policies[].write_guard",
+        move_field: "PolicyRule.write_guard",
+        value_type: "PolicyGuard[]",
+        semantic: "List of Guard objects that must be verified (via Passport) to write data. Each PolicyGuard maps to a " +
+            "Guard object and optionally specifies id_from_submission / data_from_submission for Mode 4/5 routing. " +
+            "R-D-1 (refined): must be non-empty when id_from=None; when id_from=Clock/Signer, MAY be non-empty but " +
+            "every PolicyGuard.id_from_submission MUST be None (data_from_submission is still allowed, enabling Mode 2b " +
+            "where id is auto-generated from clock/signer while data comes from the guard submission).",
+        format_example: "[{ guard: '0xaddr...', id_from_submission: 0, data_from_submission: 1 }]",
+        validation_rules: [
+            `Array length ≤ MAX_POLICY_GUARD_COUNT (${MAX_POLICY_GUARD_COUNT}) per policy`,
+            "Move aborts with E_POLICY_GUARD_COUNT_EXCEEDED (2)",
+            "R-D-1: E_POLICY_WRITE_GUARD_REQUIRED (22) if empty when id_from=None",
+            "R-D-1: E_POLICY_ID_FROM_SUBMISSION_FORBIDDEN (23) if any PolicyGuard.id_from_submission is non-null when id_from=Clock/Signer (data_from_submission still allowed)",
+        ],
+    },
+    {
+        field_name: "policies[].write_guard[].id_from_submission",
+        move_field: "PolicyGuard.id_from_submission",
+        value_type: "Option<u8> (number | null)",
+        semantic: "Guard table data index whose value is the ID of the data to be written. When set, the ID comes from " +
+            "the Passport submission (Mode 5). When null, the caller must provide the ID (Mode 4). " +
+            "R-D-1 (refined): MUST be null when policy id_from=Clock/Signer (id is auto-generated; setting this " +
+            "would conflict with id_from routing). data_from_submission is still allowed in that case (Mode 2b).",
+        format_example: "0, 1, 2, or null",
+        validation_rules: [
+            "Optional (null → caller provides id)",
+            "Guard must have is_identifier_address_compatible(identifier)",
+            "Move aborts with E_INVALID_ID_IN_GUARD_TABLE (16) if incompatible",
+            "R-D-1: MUST be null when policy id_from=Clock/Signer (E_POLICY_ID_FROM_SUBMISSION_FORBIDDEN=23)",
+        ],
+    },
+    {
+        field_name: "policies[].write_guard[].data_from_submission",
+        move_field: "PolicyGuard.data_from_submission",
+        value_type: "Option<u8> (number | null)",
+        semantic: "Guard table data index whose value is the data to be written. When set, the data comes from the " +
+            "Passport submission (Mode 5). When null, the caller provides the data (Mode 4). " +
+            "R-D-2: must be null for id_data_remove_with_passport (removal cannot consume submission data).",
+        format_example: "0, 1, 2, or null",
+        validation_rules: [
+            "Optional (null → caller provides data)",
+            "Guard must have has_identifier(identifier)",
+            "Move aborts with E_INVALID_DATA_IN_GUARD_TABLE (17) if missing",
+            "R-D-2: E_GUARD_SPECIFIED_ID_FROM_SUBMISSION (11) if set in id_data_remove_with_passport",
+        ],
+    },
+    {
+        field_name: "data_add / data_remove",
+        value_type: "SignerOrClock | { name, items }",
+        semantic: "Data operations. For Clock/Signer policies, use SignerOrClock form ({name, data} or {name}). " +
+            "For None policies, use items form with id + write_guard per item. SDK hasSubmissionSettings helper " +
+            "routes to the correct Move entry point based on PolicyGuard settings [P1-1 fix].",
+        format_example: "{ name: 'audit_log', data: ... } or { name: 'order_meta', items: [{ id, data, write_guard }] }",
+        validation_rules: [
+            "Policy name must exist in Repository (E_POLICY_NOT_FOUND=7)",
+            "write_guard must be in policy (E_GUARD_SPECIFIED_NOT_IN_POLICY=13)",
+            "ID count ≤ MAX_ID_COUNT_ONCE per call",
+            "Data size ≤ MAX_DATA_SIZE per value",
+        ],
+    },
+    {
+        field_name: "rewards",
+        value_type: "{ op: 'add'|'set'|'remove'|'clear', objects: string[] }",
+        semantic: "Reward objects referenced by this Repository. Rewards incentivize data contribution. When a writer " +
+            "adds data, they may claim a reward (if the guard verifies eligibility).",
+        format_example: "{ op: 'add', objects: ['0xreward1...', '0xreward2...'] }",
+        validation_rules: [
+            `Total reward count ≤ MAX_REWARD_COUNT (${MAX_REWARD_COUNT})`,
+            "Move aborts with E_MAX_REWARD_COUNT_EXCEEDED (19)",
+            "Reward objects must be properly configured (guard, amounts, recipients)",
+        ],
+    },
+];
+export const REPOSITORY_CONSTRAINT_RULES = [
+    {
+        id: "REP_C_01",
+        name: "policy count within limit",
+        description: `Total policies in a Repository must be ≤ MAX_POLICY_COUNT (${MAX_POLICY_COUNT}).`,
+        validation_logic: "existing_policies + new_policies <= MAX_POLICY_COUNT",
+        failure_message: `Policy count exceeds MAX_POLICY_COUNT (${MAX_POLICY_COUNT}) — E_POLICY_COUNT_EXCEEDED (3)`,
+        related_field: "policies",
+    },
+    {
+        id: "REP_C_02",
+        name: "write_guard required when id_from=None (R-D-1)",
+        description: "When id_from is None, write_guard MUST be non-empty to prevent unauthorized writes.",
+        validation_logic: "id_from == None => write_guard.length > 0",
+        failure_message: "id_from=None requires non-empty write_guard — E_POLICY_WRITE_GUARD_REQUIRED (22)",
+        related_field: "policies[].write_guard",
+    },
+    {
+        id: "REP_C_03",
+        name: "id_from_submission forbidden when id_from=Clock/Signer (R-D-1 refined)",
+        description: "When id_from is Clock or Signer, every PolicyGuard.id_from_submission MUST be None (id is auto-generated; data_from_submission is still allowed).",
+        validation_logic: "(id_from == Clock || id_from == Signer) => all write_guard[].id_from_submission == null",
+        failure_message: "id_from=Clock/Signer requires id_from_submission=null on all guards — E_POLICY_ID_FROM_SUBMISSION_FORBIDDEN (23)",
+        related_field: "policies[].write_guard[].id_from_submission",
+    },
+    {
+        id: "REP_C_04",
+        name: "policy guard count within limit",
+        description: `Each policy write_guard list must be ≤ MAX_POLICY_GUARD_COUNT (${MAX_POLICY_GUARD_COUNT}).`,
+        validation_logic: "policy.write_guard.length <= MAX_POLICY_GUARD_COUNT",
+        failure_message: `Policy guard count exceeds MAX_POLICY_GUARD_COUNT (${MAX_POLICY_GUARD_COUNT}) — E_POLICY_GUARD_COUNT_EXCEEDED (2)`,
+        related_field: "policies[].write_guard",
+    },
+    {
+        id: "REP_C_05",
+        name: "data size within limit",
+        description: `Each data value must be ≤ MAX_DATA_SIZE (${MAX_DATA_SIZE}) bytes.`,
+        validation_logic: "data.length <= MAX_DATA_SIZE",
+        failure_message: `Data value exceeds MAX_DATA_SIZE (${MAX_DATA_SIZE} bytes) — E_DATA_EXCEEDED (4)`,
+        related_field: "data_add.data",
+    },
+    {
+        id: "REP_C_06",
+        name: "id count per op within limit",
+        description: `A single Repository call may operate on at most MAX_ID_COUNT_ONCE (${MAX_ID_COUNT_ONCE}) IDs.`,
+        validation_logic: "id_count <= MAX_ID_COUNT_ONCE",
+        failure_message: `ID count exceeds MAX_ID_COUNT_ONCE (${MAX_ID_COUNT_ONCE}) — E_ID_COUNT_EXCEEDED (5)`,
+        related_field: "data_add.items[].id / data_remove.items[].id",
+    },
+    {
+        id: "REP_C_07",
+        name: "data_from_submission null in id_data_remove_with_passport (R-D-2)",
+        description: "id_data_remove_with_passport only removes data by caller id; it cannot consume Passport submissions. " +
+            "Both id_from_submission AND data_from_submission must be None.",
+        validation_logic: "is_data_remove_with_passport => !has_id_from_submission && !has_data_from_submission",
+        failure_message: "id_data_remove_with_passport cannot have id_from_submission or data_from_submission — E_GUARD_SPECIFIED_ID_FROM_SUBMISSION (11)",
+        related_field: "policies[].write_guard[].data_from_submission",
+    },
+    {
+        id: "REP_C_08",
+        name: "hasSubmissionSettings checks both submission fields (P1-1)",
+        description: "SDK hasSubmissionSettings helper must check BOTH id_from_submission AND data_from_submission to " +
+            "correctly route Mode 5 (id_data_mixed_with_passport).",
+        validation_logic: "hasSubmissionSettings = (id_from_submission != null) || (data_from_submission != null)",
+        failure_message: "Mode 5 routing missed if only id_from_submission is checked (P1-1 fix)",
+        related_field: "policies[].write_guard",
+    },
+];
+function normalizeIdFrom(v) {
+    if (typeof v === "number")
+        return v;
+    const lower = String(v).toLowerCase();
+    if (lower === "none")
+        return 0;
+    if (lower === "clock")
+        return 1;
+    if (lower === "signer")
+        return 2;
+    const parsed = Number(v);
+    return Number.isNaN(parsed) ? -1 : parsed;
+}
+export function explainRepository(input) {
+    const warnings = [];
+    const recommendations = [];
+    const routingModes = [];
+    let rD1Violations = 0;
+    let rD2Violations = 0;
+    let p11Correct = true;
+    let p12Recognized = true;
+    if (input.policies) {
+        for (const p of input.policies) {
+            const idFrom = normalizeIdFrom(p.id_from);
+            if (idFrom < 0 || idFrom > 2) {
+                p12Recognized = false;
+                warnings.push(`Policy "${p.name}": id_from="${p.id_from}" not recognized (P1-2 parseIdFrom)`);
+            }
+            if (idFrom === 0 && p.write_guard_count === 0) {
+                rD1Violations++;
+                warnings.push(`Policy "${p.name}": id_from=None + empty write_guard violates R-D-1 (E_POLICY_WRITE_GUARD_REQUIRED=22)`);
+            }
+            if ((idFrom === 1 || idFrom === 2) && p.has_id_from_submission) {
+                rD1Violations++;
+                warnings.push(`Policy "${p.name}": id_from=Clock/Signer + id_from_submission set violates R-D-1 (E_POLICY_ID_FROM_SUBMISSION_FORBIDDEN=23)`);
+            }
+            if (input.is_data_remove_with_passport && p.has_data_from_submission) {
+                rD2Violations++;
+                warnings.push(`Policy "${p.name}": data_from_submission set but used in id_data_remove_with_passport violates R-D-2`);
+            }
+            if (idFrom === 0 && (p.has_id_from_submission || p.has_data_from_submission)) {
+                if (p.has_data_from_submission && !p.has_id_from_submission) {
+                    routingModes.push(`${p.name}: Mode 5 (data_from_submission only) — SDK hasSubmissionSettings correctly detects [P1-1]`);
+                }
+                else {
+                    routingModes.push(`${p.name}: Mode 5 (id_data_mixed_with_passport)`);
+                }
+            }
+            else if (idFrom === 0 && p.write_guard_count > 0) {
+                routingModes.push(`${p.name}: Mode 4 (Guard + caller id, id_data_with_passport)`);
+            }
+            else if ((idFrom === 1 || idFrom === 2) && p.write_guard_count > 0) {
+                routingModes.push(`${p.name}: Mode 2b (auto-id + guard, data_when_id_from_set_with_passport)`);
+            }
+            else if (idFrom === 1) {
+                routingModes.push(`${p.name}: Mode 1 (Clock-routed, data_when_id_from_set)`);
+            }
+            else if (idFrom === 2) {
+                routingModes.push(`${p.name}: Mode 2 (Signer-routed, data_when_id_from_set)`);
+            }
+            else {
+                routingModes.push(`${p.name}: unknown/invalid routing`);
+            }
+        }
+    }
+    if (rD1Violations > 0)
+        recommendations.push("Fix R-D-1 violations: align write_guard presence with id_from");
+    if (rD2Violations > 0)
+        recommendations.push("Fix R-D-2 violations: remove data_from_submission for id_data_remove_with_passport");
+    if (!p12Recognized)
+        recommendations.push("Use recognized id_from values: 0/1/2 or 'None'/'Clock'/'Signer'");
+    if (routingModes.length === 0)
+        recommendations.push("Define at least one policy to enable data operations");
+    const rD1Status = rD1Violations === 0 ? "PASS (all policies satisfy R-D-1)" : `FAIL (${rD1Violations} violation(s))`;
+    const rD2Status = rD2Violations === 0 ? "PASS (no R-D-2 violations)" : `FAIL (${rD2Violations} violation(s))`;
+    const p11Status = p11Correct ? "PASS (hasSubmissionSettings checks both fields)" : "FAIL";
+    const p12Status = p12Recognized ? "PASS (all id_from values recognized)" : "FAIL (unrecognized id_from values)";
+    const summary = `Repository has ${input.policies?.length ?? 0} policy(ies). ` +
+        `R-D-1: ${rD1Status}. R-D-2: ${rD2Status}. P1-1: ${p11Status}. P1-2: ${p12Status}.`;
+    return {
+        summary,
+        routing_modes: routingModes,
+        r_d_1_status: rD1Status,
+        r_d_2_status: rD2Status,
+        p1_1_status: p11Status,
+        p1_2_status: p12Status,
+        warnings,
+        recommendations,
+    };
+}

package/dist/knowledge/resource-risk.d.ts

@@ -0,0 +1,32 @@
+export type ResourceRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export type ResourceRiskCategory = "structural" | "semantic" | "lifecycle" | "permission" | "knowledge";
+export type ResourceStakeholder = "owner" | "caller" | "system";
+export interface ResourceRisk {
+    id: string;
+    level: ResourceRiskLevel;
+    category: ResourceRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: ResourceStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+    related_move_error?: string;
+    auto_fixable: boolean;
+}
+export interface ResourceRiskCheckContext {
+    tags_count?: number;
+    expects_resource_permission?: boolean;
+    tag_set_return_ignored?: boolean;
+    is_destroy?: boolean;
+    expects_tag_events?: boolean;
+    references_dead_switch?: boolean;
+    constants_synced?: boolean;
+}
+export declare const RESOURCE_RISK_RULES: {
+    rule: ResourceRisk;
+    check: (ctx: ResourceRiskCheckContext) => ResourceRisk | null;
+}[];
+export declare const RESOURCE_RISK_VERSION = "1.0.0";
+export declare function checkResourceRisks(ctx: ResourceRiskCheckContext): ResourceRisk[];
+export declare function getResourceRiskById(id: string): ResourceRisk | undefined;

package/dist/knowledge/resource-risk.js

@@ -0,0 +1,157 @@
+import { MAX_TAGS_COUNT } from "@wowok/wowok";
+const R_R_01 = {
+    rule: {
+        id: "R-RESOURCE-01",
+        level: "LOW",
+        category: "permission",
+        title: "Resource has no Permission — relies entirely on caller-side gating",
+        description: "Resource does not associate with a Permission object. All functions are " +
+            "public(package) (new/destroy/transfer/tag_set/tag_unset) or public " +
+            "(add_object_tags/remove_object_tags/remove_object) — there is no on-chain permission " +
+            "check. Access control is delegated to the calling module (Personal, Entity). A " +
+            "caller that forgets to enforce its own permission check would let any address mutate " +
+            "tags.",
+        affected_stakeholders: ["owner", "caller"],
+        scenario: "Personal/Entity forgets to gate add_object_tags behind its own permission check",
+        mitigation: "Callers (Personal, Entity) MUST enforce their own permission checks before invoking " +
+            "Resource functions. Audit the call sites in Personal/Entity to confirm gating.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.expects_resource_permission)
+            return null;
+        return { ...R_R_01.rule, evidence: "expects_resource_permission=true (Resource has none)" };
+    },
+};
+const R_R_02 = {
+    rule: {
+        id: "R-RESOURCE-02",
+        level: "MEDIUM",
+        category: "semantic",
+        title: "Tag mutations emit no events — external indexers must poll",
+        description: "add_object_tags / remove_object_tags / remove_object do not emit events " +
+            "(resource.move:89-145). External indexers cannot rely on an event stream to track " +
+            "tag changes; they must poll the ParentTable field. This complicates real-time " +
+            "notification and consistency.",
+        affected_stakeholders: ["owner", "caller"],
+        scenario: "Indexer expects a TagAddedEvent but none is emitted; UI fails to refresh",
+        mitigation: "External indexers should poll Resource.table on a cadence. Do not build critical UX " +
+            "on tag event streams until events are added in a future version.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.expects_tag_events)
+            return null;
+        return { ...R_R_02.rule, evidence: "expects_tag_events=true (no events emitted)" };
+    },
+};
+const R_R_03 = {
+    rule: {
+        id: "R-RESOURCE-03",
+        level: "LOW",
+        category: "structural",
+        title: `MAX_TAGS_COUNT=${MAX_TAGS_COUNT} permissive — storage cost`,
+        description: `A single object's AddressTag.tags vector may hold up to MAX_TAGS_COUNT=${MAX_TAGS_COUNT} ` +
+            `entries (resource.move:9). The limit aborts with E_TAGS_COUNT_EXCEEDED (1) only at the ` +
+            `boundary. 100 tags per object is generous; loading all tags on every read increases ` +
+            `gas and storage cost.`,
+        affected_stakeholders: ["owner"],
+        scenario: "Caller adds 100 tags to a single object",
+        mitigation: "Business layer should self-limit tag count well below 100. For heavy tagging, " +
+            "shard across multiple Resource objects or store bulk tags off-chain.",
+        related_move_error: "E_TAGS_COUNT_EXCEEDED (1)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.tags_count === undefined)
+            return null;
+        if (ctx.tags_count < MAX_TAGS_COUNT)
+            return null;
+        return { ...R_R_03.rule, evidence: `tags_count=${ctx.tags_count}, limit=${MAX_TAGS_COUNT}` };
+    },
+};
+const R_R_04 = {
+    rule: {
+        id: "R-RESOURCE-04",
+        level: "LOW",
+        category: "lifecycle",
+        title: "destroy is irreversible — no recovery mechanism",
+        description: "Resource.destroy(resource) (resource.move:38) deletes the object and its ParentTable " +
+            "in place. There is no archive, no event, and no rollback. Once destroyed, the object " +
+            "ID is permanently invalid and all tags are lost.",
+        affected_stakeholders: ["owner"],
+        scenario: "Caller destroys a Resource that is still referenced by Personal/Entity",
+        mitigation: "Confirm no live references exist before calling destroy. SDK should refuse to destroy " +
+            "a Resource whose owner address is still referenced by Personal.mark or Entity.resource.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.is_destroy)
+            return null;
+        return { ...R_R_04.rule, evidence: "is_destroy=true (irreversible)" };
+    },
+};
+const R_R_05 = {
+    rule: {
+        id: "R-RESOURCE-05",
+        level: "MEDIUM",
+        category: "semantic",
+        title: "tag_set returns bool — SDK may ignore the 'already exists' signal",
+        description: "tag_set(resource, object, name) returns bool: true if a new tag was added, false if " +
+            "the tag already existed (resource.move:47-58). If the SDK ignores the return value, " +
+            "callers cannot distinguish 'newly added' from 'duplicate silently skipped'. This " +
+            "masks intent and complicates idempotency reasoning.",
+        affected_stakeholders: ["caller"],
+        scenario: "SDK treats tag_set as void; caller assumes tag was added when it was a duplicate",
+        mitigation: "SDK should expose tag_set's bool return value to the caller. UI should show 'tag " +
+            "already existed' when false is returned.",
+        auto_fixable: true,
+    },
+    check: (ctx) => {
+        if (!ctx.tag_set_return_ignored)
+            return null;
+        return { ...R_R_05.rule, evidence: "tag_set_return_ignored=true (duplicate not surfaced)" };
+    },
+};
+const R_R_06 = {
+    rule: {
+        id: "R-RESOURCE-06",
+        level: "LOW",
+        category: "semantic",
+        title: "Commented-out switch function (resource.move:71-86) — feature may be intended",
+        description: "resource.move:71-86 contains a switch function that is fully commented out. The " +
+            "intended behavior is unclear — it may be a planned feature (e.g. bulk tag operations) " +
+            "that was disabled. Referencing it as if it were live would silently fail.",
+        affected_stakeholders: ["system"],
+        scenario: "Developer reads the commented switch and assumes it is callable",
+        mitigation: "Confirm with the package maintainers whether the switch should be enabled or removed. " +
+            "Do not reference it in SDK or MCP code.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.references_dead_switch)
+            return null;
+        return { ...R_R_06.rule, evidence: "references_dead_switch=true (commented out in Move)" };
+    },
+};
+export const RESOURCE_RISK_RULES = [
+    R_R_01,
+    R_R_02,
+    R_R_03,
+    R_R_04,
+    R_R_05,
+    R_R_06,
+];
+export const RESOURCE_RISK_VERSION = "1.0.0";
+export function checkResourceRisks(ctx) {
+    const risks = [];
+    for (const rule of RESOURCE_RISK_RULES) {
+        const r = rule.check(ctx);
+        if (r)
+            risks.push(r);
+    }
+    return risks;
+}
+export function getResourceRiskById(id) {
+    return RESOURCE_RISK_RULES.find(r => r.rule.id === id)?.rule;
+}