@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/repository-risk.js

@@ -0,0 +1,312 @@
+import { MAX_POLICY_COUNT, MAX_POLICY_GUARD_COUNT, MAX_DATA_SIZE, MAX_ID_COUNT_ONCE, MAX_REWARD_COUNT, } from "@wowok/wowok";
+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;
+}
+const R_REP_1_01 = {
+    rule: {
+        id: "R-REP-01",
+        level: "MEDIUM",
+        category: "structural",
+        title: `Policy count exceeds MAX_POLICY_COUNT (${MAX_POLICY_COUNT})`,
+        description: `A single Repository may hold up to MAX_POLICY_COUNT=${MAX_POLICY_COUNT} policies (Move source: repository.move:22). ` +
+            `Exceeding this limit aborts with E_POLICY_COUNT_EXCEEDED (3) in policy_add_imp(). Each policy defines a named ` +
+            `data slot with its own write_guard list and id_from routing — having too many policies makes the Repository ` +
+            `hard to audit and increases gas cost for policy lookups (O(n) scan in policy_by_name).`,
+        affected_stakeholders: ["creator"],
+        scenario: "Caller adds 51 policies to a single Repository",
+        mitigation: "Consolidate related data under fewer policies. If truly needed, split data across multiple Repository " +
+            "objects and reference them via Service.repository or Progress.context_repositories.",
+        related_move_error: "E_POLICY_COUNT_EXCEEDED (3)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.policies || ctx.existing_policy_count === undefined)
+            return null;
+        const total = ctx.existing_policy_count + ctx.policies.length;
+        if (total <= MAX_POLICY_COUNT)
+            return null;
+        return { ...R_REP_1_01.rule, evidence: `existing=${ctx.existing_policy_count}, adding=${ctx.policies.length}, total=${total}, limit=${MAX_POLICY_COUNT}` };
+    },
+};
+const R_REP_2_01 = {
+    rule: {
+        id: "R-REP-02",
+        level: "HIGH",
+        category: "policy",
+        title: `write_guard empty when id_from=None — unauthorized writes (R-D-1 Move assert)`,
+        description: "When id_from is None, the data ID must be provided by the caller (via id_data_with_passport or " +
+            "id_data_mixed_with_passport). Without a write_guard, ANY address can write data with any ID — this " +
+            "is almost certainly a misconfiguration. The Move contract now enforces this via " +
+            "E_POLICY_WRITE_GUARD_REQUIRED (22) in policy_add_imp() [R-D-1=A].",
+        affected_stakeholders: ["creator", "writer"],
+        scenario: "Caller creates a policy with id_from=None and empty write_guard list",
+        mitigation: "When id_from=None, provide at least one PolicyGuard entry in write_guard. If you want unrestricted " +
+            "writes, use id_from=Clock or id_from=Signer instead (which auto-generates the ID and requires empty write_guard).",
+        related_move_error: "E_POLICY_WRITE_GUARD_REQUIRED (22)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.policies)
+            return null;
+        const offenders = ctx.policies.filter(p => normalizeIdFrom(p.id_from) === 0 && p.write_guard_count === 0);
+        if (offenders.length === 0)
+            return null;
+        return {
+            ...R_REP_2_01.rule,
+            evidence: `policies with id_from=None + empty write_guard: ${offenders.map(p => p.name).join(", ")}`,
+        };
+    },
+};
+const R_REP_2_02 = {
+    rule: {
+        id: "R-REP-03",
+        level: "HIGH",
+        category: "policy",
+        title: `id_from_submission set when id_from=Clock/Signer — id routing conflict (R-D-1 Move assert)`,
+        description: "When id_from is Clock or Signer, the data ID is auto-generated (timestamp or signer address). " +
+            "A PolicyGuard with id_from_submission set would try to route the id from a Passport submission, " +
+            "conflicting with the auto-generated id_from path. The Move contract enforces that id_from_submission " +
+            "MUST be None for every PolicyGuard when id_from is Clock/Signer (data_from_submission is still " +
+            "allowed — it is used by data_when_id_from_set_with_passport to extract data from the submission). " +
+            "Violations abort with E_POLICY_ID_FROM_SUBMISSION_FORBIDDEN (23) in policy_add_imp() [R-D-1=A, refined].",
+        affected_stakeholders: ["creator", "writer"],
+        scenario: "Caller creates a policy with id_from=Clock and a write_guard entry whose id_from_submission is set",
+        mitigation: "When id_from=Clock or Signer, ensure every PolicyGuard has id_from_submission=null. " +
+            "data_from_submission may still be set if you want the guard to supply the data payload " +
+            "(routed via data_when_id_from_set_with_passport). If you need submission-derived ids, " +
+            "switch to id_from=None and set id_from_submission on the guard.",
+        related_move_error: "E_POLICY_ID_FROM_SUBMISSION_FORBIDDEN (23)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.policies)
+            return null;
+        const offenders = ctx.policies.filter(p => {
+            const idFrom = normalizeIdFrom(p.id_from);
+            return (idFrom === 1 || idFrom === 2) && p.has_id_from_submission;
+        });
+        if (offenders.length === 0)
+            return null;
+        return {
+            ...R_REP_2_02.rule,
+            evidence: `policies with id_from=Clock/Signer + id_from_submission set: ${offenders.map(p => `${p.name}(id_from=${p.id_from})`).join(", ")}`,
+        };
+    },
+};
+const R_REP_1_02 = {
+    rule: {
+        id: "R-REP-04",
+        level: "MEDIUM",
+        category: "structural",
+        title: `Policy write_guard count exceeds MAX_POLICY_GUARD_COUNT (${MAX_POLICY_GUARD_COUNT})`,
+        description: `Each policy may define up to MAX_POLICY_GUARD_COUNT=${MAX_POLICY_GUARD_COUNT} guard entries in its write_guard list ` +
+            `(Move source: repository.move:23). Exceeding this limit aborts with E_POLICY_GUARD_COUNT_EXCEEDED (2). ` +
+            `Each entry maps to a Guard object that must be verified via Passport submission, so more guards = ` +
+            `more complex write authorization semantics.`,
+        affected_stakeholders: ["creator"],
+        scenario: "Caller creates a policy with 11 guard entries in write_guard",
+        mitigation: "Consolidate guard logic. If multiple guards must verify the same data, consider composing them into a " +
+            "single Guard with relies/rep fields, or split the data across multiple policies with fewer guards each.",
+        related_move_error: "E_POLICY_GUARD_COUNT_EXCEEDED (2)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.policies)
+            return null;
+        const offenders = ctx.policies.filter(p => p.write_guard_count > MAX_POLICY_GUARD_COUNT);
+        if (offenders.length === 0)
+            return null;
+        return {
+            ...R_REP_1_02.rule,
+            evidence: `policies exceeding guard count: ${offenders.map(p => `${p.name}(${p.write_guard_count})`).join(", ")}`,
+        };
+    },
+};
+const R_REP_1_03 = {
+    rule: {
+        id: "R-REP-05",
+        level: "MEDIUM",
+        category: "structural",
+        title: `Data value exceeds MAX_DATA_SIZE (${MAX_DATA_SIZE} bytes)`,
+        description: `A single Repository data value must be ≤ MAX_DATA_SIZE=${MAX_DATA_SIZE} bytes (Move source: repository.move:24). ` +
+            `Exceeding this limit aborts with E_DATA_EXCEEDED (4). The value is stored as a BCS-serialized vector<u8> ` +
+            `with a type-tag prefix byte. Large data should be stored off-chain (e.g. IPFS, Walrus) and referenced ` +
+            `by hash/address, NOT inlined into the Repository data value.`,
+        affected_stakeholders: ["writer"],
+        scenario: "Caller writes a 50KB JSON blob as a Repository data value",
+        mitigation: "Store large payloads off-chain and write only the content hash (32-64 bytes) to the Repository. " +
+            "Use about_address on a Proof object to bind the off-chain data to an on-chain attestation.",
+        related_move_error: "E_DATA_EXCEEDED (4)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.data_size === undefined)
+            return null;
+        if (ctx.data_size <= MAX_DATA_SIZE)
+            return null;
+        return { ...R_REP_1_03.rule, evidence: `data_size=${ctx.data_size}, limit=${MAX_DATA_SIZE}` };
+    },
+};
+const R_REP_3_01 = {
+    rule: {
+        id: "R-REP-06",
+        level: "LOW",
+        category: "routing",
+        title: `Policy has data_from_submission but no id_from_submission — verify Mode 5 routing intent`,
+        description: "When a PolicyGuard has data_from_submission set (data comes from Passport submission) but no " +
+            "id_from_submission (id comes from caller), the SDK routes to id_data_mixed_with_passport (Mode 5). " +
+            "This is a valid but advanced pattern — ensure the caller provides matching id vectors. The SDK " +
+            "hasSubmissionSettings helper now correctly detects this case [P1-1 fix, R-D-3=A].",
+        affected_stakeholders: ["creator", "writer"],
+        scenario: "Policy has a guard with data_from_submission=2, id_from_submission=undefined",
+        mitigation: "Document the expected caller input shape. Ensure the caller provides both the id vector (positional) " +
+            "and the Passport submission (for data). Verify routing via the SDK hasSubmissionSettings helper.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.policies)
+            return null;
+        const offenders = ctx.policies.filter(p => p.has_data_from_submission && !p.has_id_from_submission);
+        if (offenders.length === 0)
+            return null;
+        return {
+            ...R_REP_3_01.rule,
+            evidence: `policies with data_from_submission but no id_from_submission: ${offenders.map(p => p.name).join(", ")}`,
+        };
+    },
+};
+const R_REP_4_01 = {
+    rule: {
+        id: "R-REP-07",
+        level: "HIGH",
+        category: "submission",
+        title: `data_from_submission set on a policy used in id_data_remove_with_passport — Move will abort (R-D-2)`,
+        description: "id_data_remove_with_passport only removes data identified by the caller-provided id vector; it " +
+            "cannot consume Passport submissions for either id or data. The Move contract now enforces that BOTH " +
+            "id_from_submission AND data_from_submission MUST be None for this entry point [R-D-2=A], aborting " +
+            "with E_GUARD_SPECIFIED_ID_FROM_SUBMISSION (11). Previously, only id_from_submission was checked, " +
+            "allowing data_from_submission to be silently ignored — masking a routing bug.",
+        affected_stakeholders: ["writer", "verifier"],
+        scenario: "Caller uses id_data_remove_with_passport on a policy whose guard has data_from_submission=2",
+        mitigation: "For data removal via Passport, use id_data_mixed_remove_with_passport instead (which requires " +
+            "id_from_submission and derives the id from the submission). Do not set data_from_submission on " +
+            "policies intended for id_data_remove_with_passport.",
+        related_move_error: "E_GUARD_SPECIFIED_ID_FROM_SUBMISSION (11)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.is_data_remove_with_passport || !ctx.policies)
+            return null;
+        const offenders = ctx.policies.filter(p => p.has_data_from_submission);
+        if (offenders.length === 0)
+            return null;
+        return {
+            ...R_REP_4_01.rule,
+            evidence: `policies with data_from_submission used in id_data_remove_with_passport: ${offenders.map(p => p.name).join(", ")}`,
+        };
+    },
+};
+const R_REP_1_04 = {
+    rule: {
+        id: "R-REP-08",
+        level: "LOW",
+        category: "structural",
+        title: `ID count per single op exceeds MAX_ID_COUNT_ONCE (${MAX_ID_COUNT_ONCE})`,
+        description: `A single Repository call (data_add, data_remove, id_data_*) may operate on at most ` +
+            `MAX_ID_COUNT_ONCE=${MAX_ID_COUNT_ONCE} IDs (Move source: repository.move:25). Exceeding this limit ` +
+            `aborts with E_ID_COUNT_EXCEEDED (5). Batch large operations across multiple transactions.`,
+        affected_stakeholders: ["writer"],
+        scenario: "Caller passes 150 IDs in a single data_remove call",
+        mitigation: `Split into batches of ≤ ${MAX_ID_COUNT_ONCE} IDs per transaction.`,
+        related_move_error: "E_ID_COUNT_EXCEEDED (5)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.id_count_once === undefined)
+            return null;
+        if (ctx.id_count_once <= MAX_ID_COUNT_ONCE)
+            return null;
+        return { ...R_REP_1_04.rule, evidence: `id_count=${ctx.id_count_once}, limit=${MAX_ID_COUNT_ONCE}` };
+    },
+};
+const R_REP_1_05 = {
+    rule: {
+        id: "R-REP-09",
+        level: "INFO",
+        category: "structural",
+        title: `Reward count approaches MAX_REWARD_COUNT (${MAX_REWARD_COUNT})`,
+        description: `A Repository may reference up to MAX_REWARD_COUNT=${MAX_REWARD_COUNT} Reward objects (Move source: repository.move:26). ` +
+            `Exceeding this limit aborts with E_MAX_REWARD_COUNT_EXCEEDED (19). Rewards incentivize data contribution; ` +
+            `having many rewards is fine but increases accounting complexity.`,
+        affected_stakeholders: ["creator"],
+        scenario: "Caller adds 20 rewards to a Repository (at the limit)",
+        mitigation: "Monitor reward count. If more incentives are needed, consolidate rewards or use a separate Repository.",
+        related_move_error: "E_MAX_REWARD_COUNT_EXCEEDED (19)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.reward_count === undefined)
+            return null;
+        if (ctx.reward_count < MAX_REWARD_COUNT)
+            return null;
+        return { ...R_REP_1_05.rule, evidence: `reward_count=${ctx.reward_count}, limit=${MAX_REWARD_COUNT}` };
+    },
+};
+const R_REP_5_01 = {
+    rule: {
+        id: "R-REP-10",
+        level: "INFO",
+        category: "knowledge",
+        title: "Knowledge layer & constant sync — RESOLVED",
+        description: "All 6 Repository constants (MAX_POLICY_COUNT, MAX_POLICY_DESCRIPTION_LEN, MAX_POLICY_GUARD_COUNT, " +
+            "MAX_DATA_SIZE, MAX_ID_COUNT_ONCE, MAX_REWARD_COUNT) are now synced to onchain-constants.ts. " +
+            "The MCP Knowledge layer now includes repository-risk.ts, repository-confirm.ts, " +
+            "repository-translation.ts (R-D-4=A). The SDK hasSubmissionSettings helper now correctly checks both " +
+            "id_from_submission AND data_from_submission (P1-1). parseIdFrom is used in data/data_remove (P1-2). " +
+            "This risk rule is retained for historical audit and to detect future regressions.",
+        affected_stakeholders: ["system"],
+        scenario: "Future regression: someone removes a Repository constant from onchain-constants.ts",
+        mitigation: "Run the onchain-constants sync test to detect drift.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.constants_synced)
+            return null;
+        return { ...R_REP_5_01.rule, evidence: "constants_synced=false" };
+    },
+};
+export const REPOSITORY_RISK_RULES = [
+    R_REP_1_01,
+    R_REP_2_01,
+    R_REP_2_02,
+    R_REP_1_02,
+    R_REP_1_03,
+    R_REP_3_01,
+    R_REP_4_01,
+    R_REP_1_04,
+    R_REP_1_05,
+    R_REP_5_01,
+];
+export function checkRepositoryRisks(ctx) {
+    const risks = [];
+    for (const rule of REPOSITORY_RISK_RULES) {
+        const r = rule.check(ctx);
+        if (r)
+            risks.push(r);
+    }
+    return risks;
+}
+export function getRepositoryRiskById(id) {
+    return REPOSITORY_RISK_RULES.find(r => r.rule.id === id)?.rule;
+}
+export { normalizeIdFrom as parseIdFromForRiskCheck };

package/dist/knowledge/repository-translation.d.ts

@@ -0,0 +1,58 @@
+export interface SemanticToRepositorySchemaRule {
+    id: string;
+    pattern_name: string;
+    routing_mode: "clock" | "signer" | "guard_caller" | "guard_submission";
+    semantic_intent: string;
+    match_keywords: string[];
+    schema_elements: {
+        id_from_value: number | string;
+        required_policy_fields: string[];
+        write_guard_requirement: "empty" | "non_empty" | "either";
+        move_entry_point: string;
+        caller_input_shape: string;
+    };
+    constraints: string[];
+    example: Record<string, unknown>;
+}
+export declare const SEMANTIC_TO_REPOSITORY_SCHEMA_RULES: SemanticToRepositorySchemaRule[];
+export interface RepositoryFieldTranslation {
+    field_name: string;
+    move_field?: string;
+    value_type: string;
+    semantic: string;
+    format_example: string;
+    validation_rules: string[];
+}
+export declare const REPOSITORY_FIELD_TRANSLATIONS: RepositoryFieldTranslation[];
+export interface RepositoryConstraintRule {
+    id: string;
+    name: string;
+    description: string;
+    validation_logic: string;
+    failure_message: string;
+    related_field: string;
+}
+export declare const REPOSITORY_CONSTRAINT_RULES: RepositoryConstraintRule[];
+export interface RepositoryExplainInput {
+    policies?: RepositoryPolicyInput[];
+    op?: string;
+    is_data_remove_with_passport?: boolean;
+}
+export interface RepositoryPolicyInput {
+    name: string;
+    id_from: number | string;
+    write_guard_count: number;
+    has_id_from_submission: boolean;
+    has_data_from_submission: boolean;
+}
+export interface RepositoryExplanation {
+    summary: string;
+    routing_modes: string[];
+    r_d_1_status: string;
+    r_d_2_status: string;
+    p1_1_status: string;
+    p1_2_status: string;
+    warnings: string[];
+    recommendations: string[];
+}
+export declare function explainRepository(input: RepositoryExplainInput): RepositoryExplanation;