@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/passport-puzzle.d.ts

@@ -0,0 +1,108 @@
+import { type PassportConsumerObject, type PassportLifecycleStage, type ImpackRole, type ReliesLogic } from "./passport-ledger.js";
+export interface PassportIntentPuzzle {
+    protected_operation: string;
+    consumer_object: PassportConsumerObject;
+    verification_rules: string[];
+    failure_conditions: string[];
+}
+export interface PassportBindingPuzzle {
+    guard_objects: string[];
+    impack_flags: boolean[];
+    relies_dependencies: string[][];
+    relies_logic: ReliesLogic[];
+    topological_order: string[];
+}
+export interface SubmissionEntry {
+    guard: string;
+    identifier: number;
+    value: string;
+    value_type: string;
+    estimated_size: number;
+}
+export interface PassportSubmissionPuzzle {
+    submissions: SubmissionEntry[];
+    max_entry_size: number;
+    size_ok: boolean;
+}
+export interface PassportVerifyPuzzle {
+    tx_hash_binding: true;
+    has_verified: boolean;
+    verify_flow: {
+        step: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+        action: "pre_check" | "iterate_guards" | "calc_relies_result" | "verify_guard_native" | "check_submission_size" | "impack_decision" | "finalize";
+        description: string;
+    }[];
+}
+export interface PassportResultPuzzle {
+    decision_rule: "impack_mechanism";
+    impack_guards: string[];
+    per_guard_logic: {
+        guard: string;
+        impack: ImpackRole;
+        relies_logic: ReliesLogic;
+        relies_guards: string[];
+        computation: string;
+    }[];
+    overall_formula: string;
+}
+export interface PassportLifecyclePuzzle {
+    stages: {
+        stage: PassportLifecycleStage;
+        description: string;
+        completed: boolean;
+    }[];
+    terminal_state: "freeze" | "destroy" | "undecided";
+    destroy_before_freeze: true;
+}
+export type PassportPuzzleDimension = "A" | "B" | "C" | "D" | "E" | "F";
+export interface PassportPuzzle {
+    intent?: PassportIntentPuzzle;
+    binding?: PassportBindingPuzzle;
+    submission?: PassportSubmissionPuzzle;
+    verify?: PassportVerifyPuzzle;
+    result?: PassportResultPuzzle;
+    lifecycle?: PassportLifecyclePuzzle;
+}
+export interface PassportPuzzleCompleteness {
+    dimensions: PassportPuzzleDimension[];
+    missing: PassportPuzzleDimension[];
+    missing_details: {
+        dimension: PassportPuzzleDimension;
+        reason: string;
+    }[];
+    complete: boolean;
+    next_step: string;
+}
+export interface InitPuzzleInput {
+    protected_operation?: string;
+    consumer_object?: PassportConsumerObject;
+    verification_rules?: string[];
+    failure_conditions?: string[];
+}
+export declare function initPuzzleFromIntent(intent: InitPuzzleInput): PassportPuzzle;
+export declare function checkPuzzleCompleteness(puzzle: PassportPuzzle): PassportPuzzleCompleteness;
+export interface PassportConstraintViolation {
+    constraint_id: string;
+    severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+    message: string;
+    current_value?: string | number;
+    limit?: string | number;
+    related_move_error?: string;
+}
+export declare function validateConstraints(puzzle: PassportPuzzle): PassportConstraintViolation[];
+export declare function buildResultPuzzle(binding: PassportBindingPuzzle): PassportResultPuzzle;
+export declare function buildDefaultVerifyFlow(): PassportVerifyPuzzle["verify_flow"];
+export declare function buildDefaultLifecycleStages(): PassportLifecyclePuzzle["stages"];
+export declare function generateConfirmationText(puzzle: PassportPuzzle): string;
+export declare function buildPassportPuzzle(input: {
+    intent: InitPuzzleInput;
+    binding: {
+        guard_objects: string[];
+        impack_flags: boolean[];
+        relies_dependencies?: string[][];
+        relies_logic?: ReliesLogic[];
+    };
+    submission: SubmissionEntry[];
+    terminal_state?: "freeze" | "destroy" | "undecided";
+}): PassportPuzzle;
+export declare const PASSPORT_PUZZLE_VERSION = "1.0.0";

package/dist/knowledge/passport-puzzle.js

@@ -0,0 +1,333 @@
+import { MAX_GUARD_COUNT_PASSPORT, MAX_SUBMISSION_SIZE_PASSPORT, } from "./passport-ledger.js";
+export function initPuzzleFromIntent(intent) {
+    const puzzle = {};
+    if (intent.protected_operation || intent.verification_rules || intent.consumer_object) {
+        puzzle.intent = {
+            protected_operation: intent.protected_operation ?? "",
+            consumer_object: intent.consumer_object ?? "Service",
+            verification_rules: intent.verification_rules ?? [],
+            failure_conditions: intent.failure_conditions ?? [],
+        };
+    }
+    puzzle.verify = {
+        tx_hash_binding: true,
+        has_verified: false,
+        verify_flow: buildDefaultVerifyFlow(),
+    };
+    puzzle.lifecycle = {
+        stages: buildDefaultLifecycleStages(),
+        terminal_state: "undecided",
+        destroy_before_freeze: true,
+    };
+    return puzzle;
+}
+export function checkPuzzleCompleteness(puzzle) {
+    const missing = [];
+    const missing_details = [];
+    if (!puzzle.intent) {
+        missing.push("A");
+        missing_details.push({ dimension: "A", reason: "Intent not specified (protected_operation + verification_rules)" });
+    }
+    else if (!puzzle.intent.protected_operation) {
+        missing.push("A");
+        missing_details.push({ dimension: "A", reason: "protected_operation is empty" });
+    }
+    else if (puzzle.intent.verification_rules.length === 0) {
+        missing.push("A");
+        missing_details.push({ dimension: "A", reason: "verification_rules is empty — what should each Guard check?" });
+    }
+    if (!puzzle.binding) {
+        missing.push("B");
+        missing_details.push({ dimension: "B", reason: "Binding not specified (guard_objects + impack_flags + relies)" });
+    }
+    else if (puzzle.binding.guard_objects.length === 0) {
+        missing.push("B");
+        missing_details.push({ dimension: "B", reason: "guard_objects is empty — at least 1 Guard required" });
+    }
+    else if (!puzzle.binding.impack_flags.some(f => f)) {
+        missing.push("B");
+        missing_details.push({ dimension: "B", reason: "No impack=true Guard — at least 1 required (E_IMPACK_GUARD_NOT_FOUND)" });
+    }
+    else if (puzzle.binding.guard_objects.length > MAX_GUARD_COUNT_PASSPORT) {
+        missing.push("B");
+        missing_details.push({ dimension: "B", reason: `guard_objects count ${puzzle.binding.guard_objects.length} > MAX_GUARD_COUNT_PASSPORT=${MAX_GUARD_COUNT_PASSPORT}` });
+    }
+    if (!puzzle.submission) {
+        missing.push("C");
+        missing_details.push({ dimension: "C", reason: "Submission not specified (per-Guard identifier + value + value_type)" });
+    }
+    else if (!puzzle.submission.size_ok) {
+        missing.push("C");
+        missing_details.push({
+            dimension: "C",
+            reason: `max_entry_size ${puzzle.submission.max_entry_size} > MAX_SUBMISSION_SIZE_PASSPORT=${MAX_SUBMISSION_SIZE_PASSPORT}`,
+        });
+    }
+    if (!puzzle.verify) {
+        missing.push("D");
+        missing_details.push({ dimension: "D", reason: "Verify dimension not initialized (should be auto-filled)" });
+    }
+    if (!puzzle.result) {
+        missing.push("E");
+        missing_details.push({ dimension: "E", reason: "Result computation not derived (call buildResultPuzzle from binding)" });
+    }
+    if (!puzzle.lifecycle) {
+        missing.push("F");
+        missing_details.push({ dimension: "F", reason: "Lifecycle not initialized (should be auto-filled)" });
+    }
+    return {
+        dimensions: ["A", "B", "C", "D", "E", "F"],
+        missing,
+        missing_details,
+        complete: missing.length === 0,
+        next_step: missing.length === 0
+            ? "Puzzle complete — ready for confirmation text generation"
+            : `Next: complete dimension ${missing[0]} — ${missing_details[0].reason}`,
+    };
+}
+export function validateConstraints(puzzle) {
+    const violations = [];
+    if (puzzle.binding && puzzle.binding.guard_objects.length > MAX_GUARD_COUNT_PASSPORT) {
+        violations.push({
+            constraint_id: "F-PASS-04",
+            severity: "CRITICAL",
+            message: `Guard count ${puzzle.binding.guard_objects.length} exceeds MAX_GUARD_COUNT_PASSPORT=${MAX_GUARD_COUNT_PASSPORT}`,
+            current_value: puzzle.binding.guard_objects.length,
+            limit: MAX_GUARD_COUNT_PASSPORT,
+            related_move_error: "E_GUARD_COUNT_EXCEEDED (1)",
+        });
+    }
+    if (puzzle.binding && !puzzle.binding.impack_flags.some(f => f)) {
+        violations.push({
+            constraint_id: "F-PASS-07",
+            severity: "CRITICAL",
+            message: "No impack=true Guard — verify() will abort E_IMPACK_GUARD_NOT_FOUND",
+            related_move_error: "E_IMPACK_GUARD_NOT_FOUND (9)",
+        });
+    }
+    if (puzzle.binding) {
+        const added = new Set();
+        for (let i = 0; i < puzzle.binding.guard_objects.length; i++) {
+            const guard = puzzle.binding.guard_objects[i];
+            const relies = puzzle.binding.relies_dependencies[i] ?? [];
+            for (const rely of relies) {
+                if (!added.has(rely)) {
+                    violations.push({
+                        constraint_id: "F-PASS-06",
+                        severity: "HIGH",
+                        message: `Guard ${guard} (index ${i}) relies on ${rely}, but ${rely} is not added before it (topological order violated)`,
+                        related_move_error: "E_RELIES_GUARD_NOT_ADDED (2)",
+                    });
+                }
+            }
+            added.add(guard);
+        }
+    }
+    if (puzzle.submission && !puzzle.submission.size_ok) {
+        violations.push({
+            constraint_id: "F-PASS-05",
+            severity: "HIGH",
+            message: `Submission max entry size ${puzzle.submission.max_entry_size} > MAX_SUBMISSION_SIZE_PASSPORT=${MAX_SUBMISSION_SIZE_PASSPORT}`,
+            current_value: puzzle.submission.max_entry_size,
+            limit: MAX_SUBMISSION_SIZE_PASSPORT,
+            related_move_error: "E_SUBMISSION_SIZE_EXCEEDED (3)",
+        });
+    }
+    if (puzzle.binding) {
+        const guardToRelies = new Map();
+        for (let i = 0; i < puzzle.binding.guard_objects.length; i++) {
+            guardToRelies.set(puzzle.binding.guard_objects[i], puzzle.binding.relies_dependencies[i] ?? []);
+        }
+        for (let i = 0; i < puzzle.binding.guard_objects.length; i++) {
+            const guard = puzzle.binding.guard_objects[i];
+            const relies = puzzle.binding.relies_dependencies[i] ?? [];
+            for (const rely of relies) {
+                const relyOfRely = guardToRelies.get(rely) ?? [];
+                if (relyOfRely.length > 0) {
+                    violations.push({
+                        constraint_id: "F-PASS-12",
+                        severity: "LOW",
+                        message: `Guard ${guard} relies on ${rely}, but ${rely} itself has relies ${JSON.stringify(relyOfRely)} — transitive dependencies are not allowed`,
+                    });
+                }
+            }
+        }
+    }
+    return violations;
+}
+export function buildResultPuzzle(binding) {
+    const impackGuards = binding.guard_objects.filter((_, i) => binding.impack_flags[i]);
+    const perGuardLogic = binding.guard_objects.map((guard, i) => {
+        const impack = binding.impack_flags[i] ? "impack" : "non_impack";
+        const logic = binding.relies_logic[i] ?? "AND";
+        const relies = binding.relies_dependencies[i] ?? [];
+        const relyPart = relies.length === 0
+            ? "(no relies)"
+            : relies.map(r => `${r}.result`).join(` ${logic} `);
+        const computation = relies.length === 0
+            ? `${guard}.result (standalone)`
+            : `${relyPart} ${logic} ${guard}.result`;
+        return { guard, impack, relies_logic: logic, relies_guards: relies, computation };
+    });
+    const overallFormula = impackGuards.length === 0
+        ? "result = false (no impack Guard — E_IMPACK_GUARD_NOT_FOUND)"
+        : `result = AND(${impackGuards.map(g => `${g}.result`).join(", ")})`;
+    return {
+        decision_rule: "impack_mechanism",
+        impack_guards: impackGuards,
+        per_guard_logic: perGuardLogic,
+        overall_formula: overallFormula,
+    };
+}
+export function buildDefaultVerifyFlow() {
+    return [
+        { step: 1, action: "pre_check", description: "assert !has_verified (E_HAS_VERIFIED), tx_hash matches (E_DIGEST_NOT_MATCH)" },
+        { step: 2, action: "iterate_guards", description: "for each GuardInfo in self.guard (in addition order)" },
+        { step: 3, action: "calc_relies_result", description: "calculate relies result via AND/OR logic; short-circuit on AND-false or OR-true" },
+        { step: 4, action: "verify_guard_native", description: "guard::verify_guard(guard, submission, impack) — native function, opaque" },
+        { step: 5, action: "check_submission_size", description: "assert BCS submission size ≤ MAX_SUBMISSION_SIZE_PASSPORT=256 (E_SUBMISSION_SIZE_EXCEEDED)" },
+        { step: 6, action: "impack_decision", description: "if impack=true and result=false → set self.result=false, return immediately" },
+        { step: 7, action: "finalize", description: "assert at least 1 impack Guard (E_IMPACK_GUARD_NOT_FOUND); set has_verified=true, self.result=true" },
+    ];
+}
+export function buildDefaultLifecycleStages() {
+    return [
+        { stage: "new", description: "passport::new(clock, ctx) — create Passport, bind tx_hash", completed: false },
+        { stage: "guard_add", description: "passport::guard_add(self, guard, identifiers, values, impack, ctx) — add Guards (repeatable, pre-verify)", completed: false },
+        { stage: "verify", description: "passport::verify(self, ctx) — one-time verification, sets has_verified=true", completed: false },
+        { stage: "use", description: "passport::result / result_for_guard / result_for_permission / submission_get — query results", completed: false },
+        { stage: "freeze_or_destroy", description: "passport::freezen(self) [permanent] OR passport::destroy(self) [release]", completed: false },
+    ];
+}
+export function generateConfirmationText(puzzle) {
+    const lines = [];
+    lines.push("═══ Passport Confirmation ═══");
+    lines.push("");
+    if (puzzle.intent) {
+        lines.push("─ A. Intent ──────────────");
+        lines.push(`Protected operation: ${puzzle.intent.protected_operation}`);
+        lines.push(`Consumer object: ${puzzle.intent.consumer_object}`);
+        if (puzzle.intent.verification_rules.length > 0) {
+            lines.push("Verification rules:");
+            for (const r of puzzle.intent.verification_rules)
+                lines.push(`  - ${r}`);
+        }
+        if (puzzle.intent.failure_conditions.length > 0) {
+            lines.push("Failure conditions:");
+            for (const fc of puzzle.intent.failure_conditions)
+                lines.push(`  - ${fc}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.binding) {
+        const b = puzzle.binding;
+        lines.push("─ B. Binding ──────────────");
+        lines.push(`Guards (${b.guard_objects.length}/${MAX_GUARD_COUNT_PASSPORT}):`);
+        b.guard_objects.forEach((g, i) => {
+            const impack = b.impack_flags[i] ? "IMPACK" : "non-impack";
+            const relies = b.relies_dependencies[i] ?? [];
+            const logic = b.relies_logic[i] ?? "AND";
+            const relyStr = relies.length === 0 ? "" : ` relies=${JSON.stringify(relies)} (${logic})`;
+            lines.push(`  [${i}] ${g} — ${impack}${relyStr}`);
+        });
+        if (b.topological_order.length > 0) {
+            lines.push(`Topological order: ${b.topological_order.join(" → ")}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.submission) {
+        const s = puzzle.submission;
+        lines.push("─ C. Submission ──────────────");
+        lines.push(`Entries: ${s.submissions.length}, max entry size: ${s.max_entry_size}/${MAX_SUBMISSION_SIZE_PASSPORT} bytes (${s.size_ok ? "OK" : "EXCEEDS"})`);
+        for (const sub of s.submissions) {
+            lines.push(`  - guard=${sub.guard}, identifier=${sub.identifier}, value_type=${sub.value_type}, size=${sub.estimated_size}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.verify) {
+        const v = puzzle.verify;
+        lines.push("─ D. Verify ──────────────");
+        lines.push(`tx_hash binding: ${v.tx_hash_binding ? "YES (Move-level hard-coded)" : "NO"}`);
+        lines.push(`has_verified: ${v.has_verified}`);
+        lines.push(`Verify flow (${v.verify_flow.length} steps):`);
+        for (const step of v.verify_flow) {
+            lines.push(`  ${step.step}. ${step.action}: ${step.description}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.result) {
+        const r = puzzle.result;
+        lines.push("─ E. Result ──────────────");
+        lines.push(`Decision rule: ${r.decision_rule}`);
+        lines.push(`impack Guards: ${r.impack_guards.length === 0 ? "(none — will fail verify)" : r.impack_guards.join(", ")}`);
+        lines.push(`Overall formula: ${r.overall_formula}`);
+        if (r.per_guard_logic.length > 0) {
+            lines.push("Per-Guard logic:");
+            for (const pgl of r.per_guard_logic) {
+                lines.push(`  - ${pgl.guard} (${pgl.impack}, ${pgl.relies_logic}): ${pgl.computation}`);
+            }
+        }
+        lines.push("");
+    }
+    if (puzzle.lifecycle) {
+        const l = puzzle.lifecycle;
+        lines.push("─ F. Lifecycle ──────────────");
+        lines.push(`Terminal state: ${l.terminal_state}`);
+        for (const stage of l.stages) {
+            const mark = stage.completed ? "✓" : "○";
+            lines.push(`  ${mark} ${stage.stage}: ${stage.description}`);
+        }
+        lines.push("");
+    }
+    const violations = validateConstraints(puzzle);
+    if (violations.length > 0) {
+        lines.push("─ Constraint Violations ──────────────");
+        for (const v of violations) {
+            lines.push(`  [${v.severity}] ${v.constraint_id}: ${v.message}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export function buildPassportPuzzle(input) {
+    const puzzle = initPuzzleFromIntent(input.intent);
+    const topological_order = computeTopologicalOrder(input.binding.guard_objects, input.binding.relies_dependencies ?? input.binding.guard_objects.map(() => []));
+    puzzle.binding = {
+        guard_objects: input.binding.guard_objects,
+        impack_flags: input.binding.impack_flags,
+        relies_dependencies: input.binding.relies_dependencies ?? input.binding.guard_objects.map(() => []),
+        relies_logic: input.binding.relies_logic ?? input.binding.guard_objects.map(() => "AND"),
+        topological_order,
+    };
+    const maxEntrySize = input.submission.reduce((max, s) => Math.max(max, s.estimated_size), 0);
+    puzzle.submission = {
+        submissions: input.submission,
+        max_entry_size: maxEntrySize,
+        size_ok: maxEntrySize <= MAX_SUBMISSION_SIZE_PASSPORT,
+    };
+    puzzle.result = buildResultPuzzle(puzzle.binding);
+    if (input.terminal_state) {
+        puzzle.lifecycle.terminal_state = input.terminal_state;
+    }
+    return puzzle;
+}
+function computeTopologicalOrder(guard_objects, relies_dependencies) {
+    const order = [];
+    const added = new Set();
+    for (let i = 0; i < guard_objects.length; i++) {
+        const guard = guard_objects[i];
+        const relies = relies_dependencies[i] ?? [];
+        for (const rely of relies) {
+            if (!added.has(rely) && guard_objects.includes(rely)) {
+                order.push(rely);
+                added.add(rely);
+            }
+        }
+        if (!added.has(guard)) {
+            order.push(guard);
+            added.add(guard);
+        }
+    }
+    return order;
+}
+export const PASSPORT_PUZZLE_VERSION = "1.0.0";

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

@@ -0,0 +1,70 @@
+import { PASSPORT_ERROR_CODES, type PassportScenario } from "./passport-ledger.js";
+export type PassportRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export type PassportRiskCategory = "structural" | "lifecycle" | "logic" | "operational" | "knowledge";
+export type PassportStakeholder = "creator" | "consumer" | "guard_owner" | "system";
+export interface PassportRisk {
+    id: string;
+    level: PassportRiskLevel;
+    category: PassportRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: PassportStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+    related_move_error?: string;
+    related_risk?: string;
+    resolved?: boolean;
+    auto_fixable: boolean;
+}
+export interface PassportRiskRule {
+    id: string;
+    category: PassportRiskCategory;
+    trigger: string;
+    check: (ctx: PassportRiskCheckContext) => PassportRisk | null;
+}
+export interface PassportRiskCheckContext {
+    object?: string | null;
+    guard_config?: {
+        guard: {
+            object: string;
+            impack: boolean;
+        }[];
+        submission?: {
+            guard: string;
+            submission: {
+                identifier: number;
+                value: unknown;
+                value_type: string;
+            }[];
+        }[];
+    };
+    has_verified?: boolean;
+    guard_count?: number;
+    has_impack_guard?: boolean;
+    max_submission_size?: number;
+    relies_map?: Record<string, string[]>;
+    has_transitive_relies?: boolean;
+    operation_type?: "create" | "guard_add" | "guard_clear" | "verify" | "use" | "freezen" | "destroy" | "query";
+    is_frozen?: boolean;
+    matched_scenario?: PassportScenario;
+    constants_synced?: boolean;
+    knowledge_files_present?: boolean;
+}
+export declare const PASSPORT_RISK_VERSION = "1.0.0";
+export declare function getAllRiskRules(): PassportRiskRule[];
+export declare function getRiskRulesCount(): number;
+export declare function getRiskRulesByCategory(category: PassportRiskCategory): PassportRiskRule[];
+export interface PassportRiskAssessment {
+    summary: string;
+    scenario?: PassportScenario;
+    risks: PassportRisk[];
+    overall_risk: PassportRiskLevel;
+    risks_by_category: Partial<Record<PassportRiskCategory, number>>;
+    risks_by_level: Partial<Record<PassportRiskLevel, number>>;
+    stakeholder_advice: Partial<Record<PassportStakeholder, string[]>>;
+    needs_human_review: boolean;
+    blocks_publish: boolean;
+}
+export declare function assessPassportRisks(ctx: PassportRiskCheckContext): PassportRiskAssessment;
+export { PASSPORT_ERROR_CODES };