@wowok/agent-mcp 2.5.5 → 2.6.1

package/dist/extensions/types.d.ts

@@ -0,0 +1,218 @@
+import type { ProjectObjectType } from "../project/namespace.js";
+import type { IndustryTraits, IndustrySource } from "../knowledge/industry-registry.js";
+import type { AcquisitionFlywheel } from "../knowledge/acquisition-flywheel.js";
+import type { IndustryRiskCheck, IndustryNeed } from "../customer/industry-risks.js";
+import type { ModeMachineNode, ModeGuardRef, ModeAllocatorStrategy } from "../knowledge/scenario-modes.js";
+export type { ProjectObjectType, IndustryTraits, IndustrySource, AcquisitionFlywheel, IndustryRiskCheck, IndustryNeed, ModeMachineNode, ModeGuardRef, ModeAllocatorStrategy, };
+export interface ProjectContext {
+    project_id?: string;
+    prefix: string;
+    network: "testnet" | "mainnet" | "both";
+    business_intent?: string;
+    version?: string;
+    testnet_test_passed?: boolean;
+    industry?: string;
+}
+export interface Blueprint {
+    context: ProjectContext;
+    objects: BlueprintObject[];
+    edges: BlueprintEdge[];
+    steps: BlueprintStep[];
+    scenarios?: BlueprintScenario[];
+    industry_source: string;
+    applied_template: string;
+    validation?: {
+        errors: string[];
+        warnings: string[];
+    };
+}
+export interface BlueprintObject {
+    entry_id: string;
+    object_type: ProjectObjectType;
+    name: string;
+    config: Record<string, unknown>;
+    publish_required: boolean;
+    status: "draft" | "deployed";
+    description?: string;
+}
+export interface BlueprintEdge {
+    from: string;
+    to: string;
+    edge_kind: string;
+    field_path: string;
+    required_at_publish: boolean;
+}
+export interface BlueprintStep {
+    step: number;
+    object_type: ProjectObjectType;
+    operation: "create" | "publish";
+    substep_count: number;
+    depends_on: number[];
+    entry_id: string;
+    network_phase: "testnet" | "mainnet" | "both";
+}
+export interface BlueprintScenario {
+    scenario_id: string;
+    description: string;
+    primary_object: string;
+    supporting_objects: string[];
+}
+export type RiskAppetite = "conservative" | "balanced" | "aggressive";
+export interface ExpectedBenefit {
+    metric: string;
+    expected_value: string;
+    evidence: string;
+}
+export interface ModeRiskConstraints {
+    require_arbitration: boolean;
+    require_compensation_fund: boolean;
+    require_wip_evidence: boolean;
+    max_single_transaction?: number;
+    other_constraints?: string[];
+}
+export interface ModeApplicableConditions {
+    business_scale: "small" | "medium" | "large";
+    min_daily_orders?: number;
+    other_conditions?: string[];
+}
+export interface ConfigOverrideRule {
+    object_type: string;
+    field_path: string;
+    value?: unknown;
+    condition?: {
+        intent_contains?: string;
+        context_field?: string;
+        matches?: unknown;
+        then_value: unknown;
+        else_value?: unknown;
+    };
+}
+export interface IndustryMode {
+    name: string;
+    display_name: string;
+    version: string;
+    source: IndustrySource;
+    traits: IndustryTraits;
+    machine_shape: ModeMachineNode[];
+    guards: ModeGuardRef[];
+    allocator: ModeAllocatorStrategy;
+    risk_checks: IndustryRiskCheck[];
+    needs: IndustryNeed[];
+    flywheel: AcquisitionFlywheel;
+    key_risk: string;
+    build_notes?: string[];
+    capabilities_used: string[];
+    config_overrides?: Record<string, Record<string, unknown>>;
+    config_override_rules?: ConfigOverrideRule[];
+    expected_benefits: ExpectedBenefit[];
+    risk_appetite: RiskAppetite;
+    risk_constraints: ModeRiskConstraints;
+    applicable_conditions: ModeApplicableConditions;
+    similar_industries?: string[];
+    novel_capabilities?: string[];
+}
+export interface UserDefinedMode extends IndustryMode {
+    owner: string;
+    source: IndustrySource;
+    derived_from?: string;
+    custom_metrics?: BaseMetric[];
+    custom_constraints?: ModeConstraint[];
+    evolution_history?: Array<{
+        version: string;
+        changed_at: number;
+        changes: string[];
+    }>;
+}
+export interface IndustryModeRegistration {
+    mode: IndustryMode;
+    aliases?: string[];
+    enabled: boolean;
+    registered_at: number;
+}
+export type DeriveModeOptions = Partial<UserDefinedMode>;
+export type EvolveModeOptions = Partial<UserDefinedMode>;
+export type MetricType = "risk" | "benefit";
+export type MetricScale = "level" | "numeric" | "percentage";
+export type MetricValue = string | number;
+export type CapabilityMetricValue = Record<string, Record<string, MetricValue>>;
+export interface BaseMetric {
+    metric_id: string;
+    display_name: string;
+    description: string;
+    type: MetricType;
+    scale: MetricScale;
+    weight?: number;
+    scope: "builtin" | "custom";
+    owner?: string;
+}
+export interface MetricEvaluationDetail {
+    metric_id: string;
+    display_name: string;
+    value: MetricValue;
+    normalized_score: number;
+    weight: number;
+}
+export interface MetricEvaluation {
+    risk_score: number;
+    benefit_score: number;
+    metric_details: MetricEvaluationDetail[];
+}
+export type ConstraintSeverity = "hard" | "soft";
+export type ConstraintViolationAction = "block" | "warn" | "log";
+export type ConstraintRule = {
+    type: "capability_required";
+    capability_id: string;
+} | {
+    type: "capability_forbidden";
+    capability_id: string;
+} | {
+    type: "numeric_limit";
+    field: string;
+    max?: number;
+    min?: number;
+} | {
+    type: "condition_required";
+    condition: string;
+    ai_evaluated: true;
+};
+export interface ModeConstraint {
+    constraint_id: string;
+    display_name: string;
+    description: string;
+    rule: ConstraintRule;
+    severity: ConstraintSeverity;
+    on_violation: ConstraintViolationAction;
+    scope: "builtin" | "custom";
+    owner?: string;
+}
+export interface ConstraintViolation {
+    constraint_id: string;
+    display_name: string;
+    violation: string;
+    severity: ConstraintSeverity;
+    action: ConstraintViolationAction;
+    recommendation: string;
+}
+export interface ModeEvaluation {
+    applicable: boolean;
+    risk_score: number;
+    benefit_score: number;
+    risk_benefit_ratio: number;
+    capability_conflicts: string[];
+    violated_constraints: string[];
+    unmet_conditions: string[];
+    recommendations: string[];
+}
+export interface ModeMigrationEvaluation {
+    feasibility_score: number;
+    source_risk_score: number;
+    target_risk_score: number;
+    source_benefit_score: number;
+    target_benefit_score: number;
+    risk_delta: number;
+    benefit_delta: number;
+    added_capabilities: string[];
+    removed_capabilities: string[];
+    conflicting_capabilities: string[];
+    recommendations: string[];
+}

package/dist/extensions/types.js

@@ -0,0 +1 @@
+export {};

package/dist/harness/checkpoint.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, openSync, closeSync } from "fs";
 import { join } from "path";
-import { homedir } from "os";
-const CHECKPOINT_ROOT = join(homedir(), ".wowok", "checkpoints");
+import { getWowMcpDir } from "@wowok/wowok";
+const CHECKPOINT_ROOT = join(getWowMcpDir(), "checkpoints");
 function getTaskDir(taskId) {
     return join(CHECKPOINT_ROOT, taskId);
 }

package/dist/knowledge/deployment-scanner.d.ts

@@ -44,6 +44,8 @@ export interface DeploymentScanResult {
         D16_no_critical_risk: "pass" | "fail";
         D17_no_high_risk: "pass" | "fail";
         D18_completeness_checklist: "pass" | "fail";
+        D19_machine_entry_forward: "pass" | "fail";
+        D20_service_compensation_fund: "pass" | "fail";
     };
     scanned_at: number;
     scanner_version: string;
@@ -56,6 +58,7 @@ export declare function analyzePermissionIndexRange(input: DeploymentScanInput):
 export declare function analyzeScenarioCoverage(input: DeploymentScanInput): Finding[];
 export declare function analyzeVerificationChecklist(input: DeploymentScanInput): Finding[];
 export declare function analyzeDeployableReadiness(input: DeploymentScanInput): Finding[];
+export declare function analyzeMachineAndServiceReadiness(input: DeploymentScanInput): Finding[];
 export declare function scanDeployment(input: DeploymentScanInput): DeploymentScanResult;
 export declare function isReady(scan: DeploymentScanResult): boolean;
 export declare function isBlocked(scan: DeploymentScanResult): boolean;

package/dist/knowledge/deployment-scanner.js

@@ -25,7 +25,7 @@ function fromDeploymentDocInput(input) {
     for (let i = 1; i <= 5; i++)
         mainnet_verification.set(`V-M-${String(i).padStart(2, "0")}`, false);
     const completeness_checklist = new Map();
-    for (let i = 1; i <= 18; i++)
+    for (let i = 1; i <= 20; i++)
         completeness_checklist.set(`D-${String(i).padStart(2, "0")}`, false);
     return {
         project_name: input.project_prefix, version, namespace_tag,
@@ -529,7 +529,7 @@ export function analyzeScenarioCoverage(input) {
 }
 const TESTNET_VERIFICATION_ITEMS = ["V-T-01", "V-T-02", "V-T-03", "V-T-04", "V-T-05", "V-T-06", "V-T-07", "V-T-08", "V-T-09", "V-T-10", "V-T-11"];
 const MAINNET_VERIFICATION_ITEMS = ["V-M-01", "V-M-02", "V-M-03", "V-M-04", "V-M-05"];
-const COMPLETENESS_CHECK_IDS = Array.from({ length: 18 }, (_, i) => `D-${String(i + 1).padStart(2, "0")}`);
+const COMPLETENESS_CHECK_IDS = Array.from({ length: 20 }, (_, i) => `D-${String(i + 1).padStart(2, "0")}`);
 export function analyzeVerificationChecklist(input) {
     const findings = [];
     try {
@@ -623,6 +623,64 @@ function resolveRiskResult(input) {
     }
     return undefined;
 }
+function extractMachinePairs(block) {
+    const data = block.data;
+    if (!data)
+        return [];
+    const node = data.node;
+    if (!node || typeof node !== "object")
+        return [];
+    const nodes = node.nodes;
+    if (!Array.isArray(nodes))
+        return [];
+    return nodes.filter((n) => {
+        if (!n || typeof n !== "object")
+            return false;
+        const pairs = n.pairs;
+        return Array.isArray(pairs);
+    }).flatMap((n) => n.pairs ?? []);
+}
+export function analyzeMachineAndServiceReadiness(input) {
+    const findings = [];
+    try {
+        const doc = normalizeInput(input);
+        if (!doc)
+            return [];
+        const allBlocks = [...doc.testnet_blocks, ...doc.mainnet_blocks];
+        for (const block of allBlocks) {
+            if (block.operation_type !== "machine")
+                continue;
+            const pairs = extractMachinePairs(block);
+            if (pairs.length === 0)
+                continue;
+            const entryPairs = pairs.filter((p) => p.prev_node === "");
+            for (const pair of entryPairs) {
+                const forwardsLen = Array.isArray(pair.forwards) ? pair.forwards.length : 0;
+                if (forwardsLen === 0) {
+                    add(findings, "D-19", "critical", `Machine in step ${block.step} (${block.env.network ?? "?"}) has an entry node (prev_node="") with no forwards. ` +
+                        `Progress created from this Machine will be permanently stuck at current="" (P0-2 root cause).`, `${block.env.network ?? "?"} step ${block.step}`, `Add at least one forward to the entry node's pairs. Example: pairs: [{prev_node: "", forwards: [{next_node: "Ordered", ...}]}]`);
+                }
+            }
+        }
+        const serviceBlocks = allBlocks.filter((b) => b.operation_type === "service");
+        if (serviceBlocks.length > 0) {
+            const blocksWithFundAdd = serviceBlocks.filter((b) => {
+                const data = b.data;
+                return data?.compensation_fund_add != null;
+            });
+            if (blocksWithFundAdd.length === 0) {
+                add(findings, "D-20", "warning", `No Service block in the deployment doc includes a compensation_fund_add step. ` +
+                    `Without deposit, arbitration rulings that award refunds to buyers cannot be paid out from the Service. ` +
+                    `Industries like freelance may not require this (info), but rental/travel/education typically do.`, "§3.2 / §4.2 Service blocks", `Add a compensation_fund_add step for the Service (e.g., data.compensation_fund_add = {balance: <amount>}). ` +
+                    `Recommended: 5× the max single-order amount (P1-1 evaluation rule).`);
+            }
+        }
+    }
+    catch (err) {
+        add(findings, "D-19", "warning", `analyzeMachineAndServiceReadiness failed: ${err.message}`);
+    }
+    return findings;
+}
 export function scanDeployment(input) {
     const allFindings = [
         ...analyzeObjectDependencyCompleteness(input),
@@ -633,6 +691,7 @@ export function scanDeployment(input) {
         ...analyzeScenarioCoverage(input),
         ...analyzeVerificationChecklist(input),
         ...analyzeDeployableReadiness(input),
+        ...analyzeMachineAndServiceReadiness(input),
     ];
     return {
         project_name: input.project_name,
@@ -666,6 +725,8 @@ function computeChecks(findings) {
         D16_no_critical_risk: has("D-16") ? "fail" : "pass",
         D17_no_high_risk: has("D-17") ? "fail" : "pass",
         D18_completeness_checklist: has("D-18") ? "fail" : "pass",
+        D19_machine_entry_forward: has("D-19") ? "fail" : "pass",
+        D20_service_compensation_fund: has("D-20") ? "fail" : "pass",
     };
 }
 function computeCoverage(input) {
@@ -726,7 +787,7 @@ export function summarizeScan(scan) {
     L.push(`| testnet steps | ${scan.coverage.testnet_steps} |`);
     L.push(`| mainnet steps | ${scan.coverage.mainnet_steps} |`);
     L.push(`| verification items | ${scan.coverage.verification_items} |`, "");
-    L.push("## Checks (D-01 ~ D-18)", "", "| Check ID | Status |", "|----------|--------|");
+    L.push("## Checks (D-01 ~ D-20)", "", "| Check ID | Status |", "|----------|--------|");
     const entries = Object.entries(scan.checks);
     for (const [id, status] of entries)
         L.push(`| ${id} | ${status === "pass" ? "✅ pass" : "❌ fail"} |`);

package/dist/knowledge/flywheel-loop.js

@@ -3,7 +3,7 @@ import { getIndustryProfile, resolveIndustryName } from "./industry-registry.js"
 import { evaluateIndustryHealthByIntent, suggestIndustryUpdateByIntent, getRoleAdvice, filterSuggestionsByRole, getIntentProfile, } from "./intent-metrics.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
-import { homedir } from "os";
+import { getWowMcpDir } from "@wowok/wowok";
 export const FLYWHEEL_LOOP_VERSION = 2;
 const MIN_SIGNALS_FOR_EVOLUTION = 10;
 const DEFAULT_SCHEDULE = {
@@ -287,10 +287,7 @@ export function getIndustryEvolutionStatus(industry) {
 }
 export const EVOLUTION_STATE_VERSION = 1;
 function evolutionStateFilePath() {
-    const dir = process.env.WOWOK_CONFIG_DIR
-        ? process.env.WOWOK_CONFIG_DIR
-        : join(homedir(), ".wowok");
-    return join(dir, "evolution-state.json");
+    return join(getWowMcpDir(), "evolution-state.json");
 }
 export function saveEvolutionState() {
     const path = evolutionStateFilePath();

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

@@ -1,4 +1,17 @@
 import type { GuardScene } from "./guard-ledger.js";
+export declare const GUARD_COGNITIVE_PRINCIPLES: readonly [{
+    readonly id: "P1";
+    readonly title: "Guard validation always precedes the operation";
+    readonly statement: string;
+    readonly code_evidence: string;
+    readonly legitimate_exception: string;
+    readonly scope: "Applies when a Guard queries state of the SAME object the operation mutates.";
+}, {
+    readonly id: "P2";
+    readonly title: "Guard is CREATE-only and immutable";
+    readonly statement: string;
+    readonly scope: "Applies to all Guard lifecycle decisions.";
+}];
 export type GuardStakeholder = "customer" | "provider" | "arbitrator" | "claimant" | "system";
 export type RiskLevel = "critical" | "high" | "medium" | "low";
 export type DataSourceClass = "type1_onchain_constant" | "type2_witness_derived" | "type3_submitted_object" | "type4_system_context" | "cross_type";

package/dist/knowledge/guard-risk.js

@@ -1,4 +1,24 @@
 import { GUARDQUERY } from "@wowok/wowok";
+export const GUARD_COGNITIVE_PRINCIPLES = [
+    {
+        id: "P1",
+        title: "Guard validation always precedes the operation",
+        statement: "Guard validation ALWAYS occurs BEFORE the operation it guards. " +
+            "A Guard must NOT depend on data that the current operation will modify.",
+        code_evidence: "progress.move next_with_passport_imp: result_for_guard (line 471) " +
+            "runs before session_accomplish (line 481) which sets self.current (line 443).",
+        legitimate_exception: "Querying progress.current of a DIFFERENT Progress object (cross-machine) " +
+            "is safe and reasonable — that progress is not modified by the current operation.",
+        scope: "Applies when a Guard queries state of the SAME object the operation mutates.",
+    },
+    {
+        id: "P2",
+        title: "Guard is CREATE-only and immutable",
+        statement: "After creation, Guard table/root/rely cannot be modified. " +
+            "To change logic, create a new Guard and rebind references.",
+        scope: "Applies to all Guard lifecycle decisions.",
+    },
+];
 function rootStr(ctx) {
     return JSON.stringify(ctx.root).toLowerCase();
 }
@@ -1681,6 +1701,43 @@ const RISK_RULES = [
             };
         },
     },
+    {
+        id: "R-X1-15",
+        data_source_class: "cross_type",
+        trigger: "Guard root contains a progress.current query (id=1253 or name='progress.current'); " +
+            "if bound to a forward of the SAME Progress object, the guard evaluates before state transition",
+        check: (ctx) => {
+            const queryIds = extractQueryIds(ctx.root);
+            if (!queryIds.includes(1253))
+                return null;
+            return {
+                id: "R-X1-15",
+                data_source_class: "cross_type",
+                level: "medium",
+                category: "logic_gap",
+                title: "Guard queries progress.current — verify it is NOT the same Progress object the hosting operation mutates",
+                description: "Cognitive Principle P1: Guard validation ALWAYS occurs BEFORE the operation. " +
+                    "This Guard contains a progress.current query. If this Guard is bound to a forward " +
+                    "of the SAME Progress object it queries, the Guard will see the PRE-transition value " +
+                    "(source node, not target node) and may always fail. " +
+                    "Querying a DIFFERENT Progress object (e.g. another Machine's progress) is a valid " +
+                    "and reasonable design pattern — the principle does not apply in that case. " +
+                    "Allocator-bound guards are also unaffected because allocation.alloc() runs AFTER " +
+                    "the state transition completes.",
+                affected_stakeholders: ["provider"],
+                scenario: "Forward guard checks progress.current == target_node of the same Progress — " +
+                    "always fails because guard runs before session_accomplish sets the new current node",
+                mitigation: "1) If this Guard queries the SAME Progress object the forward operates on: " +
+                    "remove the guard from the forward, bind it ONLY to the Allocator (which runs after transition); " +
+                    "OR change the check to verify the SOURCE node instead of the target node. " +
+                    "2) If this Guard queries a DIFFERENT Progress object (cross-machine): no action needed — " +
+                    "this is a legitimate pattern. " +
+                    "3) Refer to GUARD_COGNITIVE_PRINCIPLES P1 for the full principle and code evidence.",
+                evidence: `Root contains progress.current query (id=1253). ` +
+                    `Query IDs detected: [${queryIds.join(", ")}].`,
+            };
+        },
+    },
 ];
 function deriveStakeholders(sceneId) {
     switch (sceneId) {