@wowok/agent-mcp 2.5.1 → 2.5.3

package/dist/project/rollback-policy.js

@@ -0,0 +1,290 @@
+import { existsSync, rmSync } from "fs";
+import { join } from "path";
+import { loadStageState, projectDir, rollbackStage as rollbackStageState, } from "./project-store.js";
+export const REVERSIBILITY_MATRIX = [
+    {
+        object_type: "permission",
+        lifecycle_state: "created",
+        struct_reversible: "reversible",
+        behavior_reversible: true,
+        gas_impact: "low",
+        explanation: "Permission (unpublished): can add tables/admins freely",
+    },
+    {
+        object_type: "permission",
+        lifecycle_state: "referenced",
+        struct_reversible: "limited",
+        behavior_reversible: true,
+        gas_impact: "medium",
+        explanation: "Permission (referenced by published service): modifications limited — affects dependents",
+    },
+    {
+        object_type: "machine",
+        lifecycle_state: "created",
+        struct_reversible: "reversible",
+        behavior_reversible: true,
+        gas_impact: "low",
+        explanation: "Machine (unpublished): can modify nodes/edges/forwards freely",
+    },
+    {
+        object_type: "machine",
+        lifecycle_state: "published",
+        struct_reversible: "immutable",
+        behavior_reversible: true,
+        gas_impact: "none",
+        explanation: "Machine (published): structure is immutable — can only advance progress",
+    },
+    {
+        object_type: "service",
+        lifecycle_state: "created",
+        struct_reversible: "reversible",
+        behavior_reversible: true,
+        gas_impact: "low",
+        explanation: "Service (unpublished): can modify fields freely",
+    },
+    {
+        object_type: "service",
+        lifecycle_state: "published",
+        struct_reversible: "immutable",
+        behavior_reversible: true,
+        gas_impact: "none",
+        explanation: "Service (published): machine/order_allocators frozen — can still transact normally",
+    },
+    {
+        object_type: "guard",
+        lifecycle_state: "created",
+        struct_reversible: "immutable",
+        behavior_reversible: false,
+        gas_impact: "none",
+        explanation: "Guard: create-only semantics — immutable from creation",
+    },
+    {
+        object_type: "allocation",
+        lifecycle_state: "created",
+        struct_reversible: "reversible",
+        behavior_reversible: true,
+        gas_impact: "low",
+        explanation: "Allocator (unbound): can modify strategy freely",
+    },
+    {
+        object_type: "allocation",
+        lifecycle_state: "bound",
+        struct_reversible: "limited",
+        behavior_reversible: true,
+        gas_impact: "medium",
+        explanation: "Allocator (bound to published service): strategy modifications limited",
+    },
+    {
+        object_type: "treasury",
+        lifecycle_state: "created",
+        struct_reversible: "reversible",
+        behavior_reversible: true,
+        gas_impact: "low",
+        explanation: "Treasury: can modify rules freely",
+    },
+    {
+        object_type: "arb",
+        lifecycle_state: "created",
+        struct_reversible: "reversible",
+        behavior_reversible: true,
+        gas_impact: "low",
+        explanation: "Arbitration: can modify rules freely",
+    },
+    {
+        object_type: "reward",
+        lifecycle_state: "created",
+        struct_reversible: "reversible",
+        behavior_reversible: true,
+        gas_impact: "low",
+        explanation: "Reward: can modify rules freely",
+    },
+    {
+        object_type: "progress",
+        lifecycle_state: "bound",
+        struct_reversible: "immutable",
+        behavior_reversible: true,
+        gas_impact: "none",
+        explanation: "Progress (bound to machine): cannot swap machine — can only forward",
+    },
+    {
+        object_type: "order",
+        lifecycle_state: "created",
+        struct_reversible: "immutable",
+        behavior_reversible: true,
+        gas_impact: "none",
+        explanation: "Order: structure immutable after creation — can only advance state",
+    },
+];
+export function queryReversibility(objectType, lifecycleState) {
+    return REVERSIBILITY_MATRIX.find((e) => e.object_type === objectType && e.lifecycle_state === lifecycleState);
+}
+export function getReversibilityForType(objectType) {
+    return REVERSIBILITY_MATRIX.filter((e) => e.object_type === objectType);
+}
+export function recommendIterationStrategy(prefix, version, currentStage) {
+    const state = loadStageState(prefix, version);
+    if (!state) {
+        return {
+            strategy: "in_place",
+            reason: "Project not initialized — no stage state found. Use in-place for new projects.",
+        };
+    }
+    if (state.has_published_object) {
+        const versionMatch = version.match(/^v(\d+)$/);
+        const nextVersionNum = versionMatch ? parseInt(versionMatch[1]) + 1 : 2;
+        const forkTo = `v${nextVersionNum}`;
+        return {
+            strategy: "fork",
+            reason: `Project has published on-chain objects — in-place modification would break running business. ` +
+                `Fork to ${forkTo} to preserve the original version as a read-only historical snapshot.`,
+            fork_to_version: forkTo,
+            published_objects: state.stage_meta[5]?.committed
+                ? ["see deployment/05-substeps/ for published object list"]
+                : [],
+        };
+    }
+    const stage = currentStage ?? state.stage;
+    return {
+        strategy: "in_place",
+        reason: `Project has no published objects (current stage: ${stage}). ` +
+            `Safe to modify the current version directly — all changes are local and reversible.`,
+    };
+}
+const STAGE_DIR_SUFFIXES = {
+    1: "01-namespace",
+    2: "02-puzzle",
+    3: "03-risk",
+    4: "04-steps",
+    5: "05-substeps",
+};
+export function evaluateRollbackPolicy(prefix, version, targetStage) {
+    const state = loadStageState(prefix, version);
+    if (!state) {
+        return {
+            allowed: false,
+            target_stage: targetStage,
+            current_stage: 1,
+            block_reason: `Project not initialized: ${prefix}_${version}`,
+            files_to_clean: [],
+            warnings: [],
+            iteration_strategy: {
+                strategy: "in_place",
+                reason: "Project not initialized.",
+            },
+        };
+    }
+    const currentStage = state.stage;
+    const iterationStrategy = recommendIterationStrategy(prefix, version, currentStage);
+    if (state.has_published_object) {
+        return {
+            allowed: false,
+            target_stage: targetStage,
+            current_stage: currentStage,
+            block_reason: `Project has published on-chain objects — rollback is forbidden (§3.3). ` +
+                `Use fork_project to create a new version for modifications.`,
+            files_to_clean: [],
+            warnings: [],
+            iteration_strategy: iterationStrategy,
+        };
+    }
+    if (targetStage >= currentStage) {
+        return {
+            allowed: false,
+            target_stage: targetStage,
+            current_stage: currentStage,
+            block_reason: `Target stage ${targetStage} must be less than current stage ${currentStage}.`,
+            files_to_clean: [],
+            warnings: [],
+            iteration_strategy: iterationStrategy,
+        };
+    }
+    if (targetStage < 1) {
+        return {
+            allowed: false,
+            target_stage: targetStage,
+            current_stage: currentStage,
+            block_reason: "Cannot rollback below stage 1.",
+            files_to_clean: [],
+            warnings: [],
+            iteration_strategy: iterationStrategy,
+        };
+    }
+    const filesToClean = [];
+    const warnings = [];
+    const depDir = join(projectDir(prefix, version), "deployment");
+    for (let s = targetStage + 1; s <= 5; s++) {
+        const stageDir = join(depDir, STAGE_DIR_SUFFIXES[s]);
+        if (existsSync(stageDir)) {
+            filesToClean.push(`deployment/${STAGE_DIR_SUFFIXES[s]}/`);
+        }
+    }
+    if (targetStage <= 2 && existsSync(depDir)) {
+        filesToClean.length = 0;
+        filesToClean.push("deployment/");
+    }
+    if (filesToClean.length > 0) {
+        warnings.push(`Rollback will delete ${filesToClean.length} file(s)/directory(ies): ${filesToClean.join(", ")}. ` +
+            `This data will be lost — regenerate by re-running the stage action.`);
+    }
+    return {
+        allowed: true,
+        target_stage: targetStage,
+        current_stage: currentStage,
+        files_to_clean: filesToClean,
+        warnings,
+        iteration_strategy: iterationStrategy,
+    };
+}
+export function rollbackStageWithPolicy(prefix, version, targetStage, reason) {
+    const policy = evaluateRollbackPolicy(prefix, version, targetStage);
+    if (!policy.allowed) {
+        return {
+            success: false,
+            target_stage: targetStage,
+            previous_stage: policy.current_stage,
+            files_to_clean: [],
+            files_cleaned: [],
+            stage_state: loadStageState(prefix, version),
+            warnings: [],
+            iteration_strategy: policy.iteration_strategy,
+            message: `Rollback blocked: ${policy.block_reason}`,
+        };
+    }
+    const filesCleaned = [];
+    const depDir = join(projectDir(prefix, version), "deployment");
+    if (policy.files_to_clean.includes("deployment/")) {
+        if (existsSync(depDir)) {
+            rmSync(depDir, { recursive: true, force: true });
+            filesCleaned.push("deployment/");
+        }
+    }
+    else {
+        for (const relPath of policy.files_to_clean) {
+            const absPath = join(projectDir(prefix, version), relPath);
+            if (existsSync(absPath)) {
+                rmSync(absPath, { recursive: true, force: true });
+                filesCleaned.push(relPath);
+            }
+        }
+    }
+    const newState = rollbackStageState(prefix, version, targetStage, {
+        reason: reason ?? `rollback to stage ${targetStage} (policy-evaluated)`,
+        affectedFiles: filesCleaned.length > 0 ? filesCleaned : ["stage.json"],
+    });
+    return {
+        success: true,
+        target_stage: targetStage,
+        previous_stage: policy.current_stage,
+        files_to_clean: policy.files_to_clean,
+        files_cleaned: filesCleaned,
+        stage_state: newState,
+        warnings: policy.warnings,
+        iteration_strategy: policy.iteration_strategy,
+        message: `Rolled back from stage ${policy.current_stage} to ${targetStage}. ` +
+            `${filesCleaned.length} file(s)/directory(ies) cleaned. ` +
+            `Stage state updated. ` +
+            (policy.iteration_strategy.strategy === "fork"
+                ? `Note: this project has published objects — future modifications require fork.`
+                : `Project has no published objects — in-place modification is safe.`),
+    };
+}

package/dist/project/stage-gate.d.ts

@@ -0,0 +1,49 @@
+import type { ProjectStage } from "./project-store.js";
+export type GateDimension = "semantic" | "tools" | "reversibility" | "risk" | "isolation" | "gas_budget";
+export interface GasBudgetCheck {
+    network: "testnet" | "mainnet";
+    already_spent_gas: number;
+    estimated_rerun_gas: number;
+    warning?: string;
+}
+export interface StageGateCheck {
+    dimension: GateDimension;
+    status: "PASS" | "FAIL" | "WARN";
+    message: string;
+}
+export interface StageGateInput {
+    stage: ProjectStage;
+    prefix: string;
+    version: string;
+    naming?: {
+        prefix_valid: boolean;
+        version_valid: boolean;
+    };
+    puzzles?: Record<string, unknown>;
+    puzzles_completeness?: "complete" | "partial" | "empty";
+    risk_status?: string;
+    risk_can_proceed?: boolean;
+    doc_error_count?: number;
+    objects?: Array<{
+        entry_id: string;
+        object_type?: string;
+        reused_from?: string;
+    }>;
+    edges?: Array<{
+        from: string;
+        to: string;
+    }>;
+    trace_coherent?: boolean;
+    has_published_object?: boolean;
+    gas_budget?: GasBudgetCheck;
+}
+export interface StageGateResult {
+    stage: ProjectStage;
+    passed: boolean;
+    checks: StageGateCheck[];
+    blocking_issues: string[];
+    warnings: string[];
+    can_proceed: boolean;
+}
+export declare function validateStageGate(input: StageGateInput): StageGateResult;
+export declare function validateStageGateFromDisk(prefix: string, version: string, stage?: ProjectStage, extra?: Partial<StageGateInput>): StageGateResult;

package/dist/project/stage-gate.js

@@ -0,0 +1,310 @@
+import { loadStageState, projectExists } from "./project-store.js";
+function buildGasBudgetCheck(input) {
+    const gb = input.gas_budget;
+    if (!gb) {
+        return {
+            dimension: "gas_budget",
+            status: "PASS",
+            message: "Gas budget not provided (N/A for this stage or caller omitted)",
+        };
+    }
+    if (gb.network === "testnet") {
+        return {
+            dimension: "gas_budget",
+            status: "PASS",
+            message: "testnet: no gas limit (faucet is free); rollback is costless",
+        };
+    }
+    const total = gb.already_spent_gas + gb.estimated_rerun_gas;
+    const warning = gb.warning ??
+        `mainnet: estimated total gas ${total} MIST (already_spent=${gb.already_spent_gas} + rerun=${gb.estimated_rerun_gas}). Rollback will incur real cost.`;
+    return {
+        dimension: "gas_budget",
+        status: "WARN",
+        message: warning,
+    };
+}
+function validateStage1Gate(input) {
+    const checks = [];
+    const namingValid = input.naming?.prefix_valid && input.naming?.version_valid;
+    checks.push({
+        dimension: "semantic",
+        status: namingValid ? "PASS" : "FAIL",
+        message: namingValid
+            ? "Project namespace is valid (prefix + version)"
+            : "Project naming is invalid — prefix must match ^[a-z][a-z0-9_]{2,63}$ and version must match ^v\\d+$",
+    });
+    checks.push({
+        dimension: "tools",
+        status: "PASS",
+        message: "Stage 1 requires no on-chain tools (namespace is local-only)",
+    });
+    checks.push({
+        dimension: "reversibility",
+        status: "PASS",
+        message: "Stage 1 is fully reversible (no on-chain state changes)",
+    });
+    checks.push({
+        dimension: "risk",
+        status: "PASS",
+        message: "No risks at namespace stage",
+    });
+    checks.push({
+        dimension: "isolation",
+        status: "PASS",
+        message: "Stage 1 has no objects (isolation N/A)",
+    });
+    checks.push(buildGasBudgetCheck(input));
+    return checks;
+}
+function validateStage2Gate(input) {
+    const checks = [];
+    const hasPuzzles = input.puzzles && Object.keys(input.puzzles).length > 0;
+    const completeness = input.puzzles_completeness ?? "empty";
+    checks.push({
+        dimension: "semantic",
+        status: hasPuzzles
+            ? completeness === "complete"
+                ? "PASS"
+                : completeness === "partial"
+                    ? "WARN"
+                    : "FAIL"
+            : "FAIL",
+        message: hasPuzzles
+            ? `Puzzles present with completeness: ${completeness}`
+            : "No puzzles found — call analyze_intent first",
+    });
+    if (hasPuzzles) {
+        const objectTypes = Object.keys(input.puzzles);
+        checks.push({
+            dimension: "tools",
+            status: "PASS",
+            message: `${objectTypes.length} object type(s) defined: ${objectTypes.join(", ")}`,
+        });
+    }
+    else {
+        checks.push({
+            dimension: "tools",
+            status: "FAIL",
+            message: "Cannot verify tools — no puzzles available",
+        });
+    }
+    checks.push({
+        dimension: "reversibility",
+        status: "PASS",
+        message: "Stage 2 is in-memory only (no on-chain state changes)",
+    });
+    checks.push({
+        dimension: "risk",
+        status: "PASS",
+        message: "Risk assessment happens in stage 3 (aggregate_risks)",
+    });
+    if (input.objects && input.objects.length > 0) {
+        const crossProject = input.objects.filter((o) => o.reused_from && o.reused_from.includes(":") && !o.reused_from.startsWith("0x"));
+        checks.push({
+            dimension: "isolation",
+            status: crossProject.length === 0 ? "PASS" : "FAIL",
+            message: crossProject.length === 0
+                ? "No cross-project object references detected"
+                : `${crossProject.length} object(s) reference external projects (§3.0 violation): ${crossProject.map((o) => o.entry_id).join(", ")}`,
+        });
+    }
+    else {
+        checks.push({
+            dimension: "isolation",
+            status: "PASS",
+            message: "No objects to check for isolation (stage 2)",
+        });
+    }
+    checks.push(buildGasBudgetCheck(input));
+    return checks;
+}
+function validateStage3Gate(input) {
+    const checks = [];
+    const hasRiskStatus = input.risk_status !== undefined && input.risk_status !== "";
+    checks.push({
+        dimension: "semantic",
+        status: hasRiskStatus ? "PASS" : "FAIL",
+        message: hasRiskStatus
+            ? `Risk status: ${input.risk_status}`
+            : "No risk assessment found — call aggregate_risks first",
+    });
+    checks.push({
+        dimension: "tools",
+        status: "PASS",
+        message: "Risk assessment uses puzzles from stage 2 (no additional tools)",
+    });
+    checks.push({
+        dimension: "reversibility",
+        status: "PASS",
+        message: "Stage 3 is reversible (re-run aggregate_risks to update)",
+    });
+    const canProceed = input.risk_can_proceed === true;
+    checks.push({
+        dimension: "risk",
+        status: canProceed ? "PASS" : "FAIL",
+        message: canProceed
+            ? "All CRITICAL risks resolved — may proceed"
+            : "CRITICAL risks remain — fix before proceeding (non-blocking principle: only CRITICAL blocks)",
+    });
+    checks.push({
+        dimension: "isolation",
+        status: "PASS",
+        message: "Isolation verified in stage 2",
+    });
+    checks.push(buildGasBudgetCheck(input));
+    return checks;
+}
+function validateStage4Gate(input) {
+    const checks = [];
+    const errorCount = input.doc_error_count ?? -1;
+    checks.push({
+        dimension: "semantic",
+        status: errorCount === 0 ? "PASS" : errorCount > 0 ? "FAIL" : "WARN",
+        message: errorCount === 0
+            ? "Deployment doc generated with 0 D-errors"
+            : errorCount > 0
+                ? `${errorCount} D-error(s) remain — fix before proceeding`
+                : "Doc error count unknown — call generate_deployment_doc first",
+    });
+    if (input.objects && input.edges) {
+        const objectIds = new Set(input.objects.map((o) => o.entry_id));
+        const danglingEdges = input.edges.filter((e) => !objectIds.has(e.from) || !objectIds.has(e.to));
+        checks.push({
+            dimension: "tools",
+            status: danglingEdges.length === 0 ? "PASS" : "FAIL",
+            message: danglingEdges.length === 0
+                ? `All ${input.edges.length} edge(s) reference defined objects`
+                : `${danglingEdges.length} edge(s) reference undefined objects`,
+        });
+    }
+    else {
+        checks.push({
+            dimension: "tools",
+            status: "WARN",
+            message: "Objects/edges not provided — cannot verify tool availability",
+        });
+    }
+    checks.push({
+        dimension: "reversibility",
+        status: "PASS",
+        message: "Stage 4 is reversible (regenerate deployment doc)",
+    });
+    const riskPassed = input.risk_status === "RISK_PASSED";
+    checks.push({
+        dimension: "risk",
+        status: riskPassed ? "PASS" : "WARN",
+        message: riskPassed
+            ? "Risk status is RISK_PASSED"
+            : `Risk status is ${input.risk_status ?? "unknown"} — recommend resolving before deployment`,
+    });
+    if (input.objects && input.objects.length > 0) {
+        const crossProject = input.objects.filter((o) => o.reused_from && !o.reused_from.startsWith("0x") && o.reused_from.includes(":"));
+        checks.push({
+            dimension: "isolation",
+            status: crossProject.length === 0 ? "PASS" : "FAIL",
+            message: crossProject.length === 0
+                ? "No cross-project references in deployment objects"
+                : `${crossProject.length} object(s) have cross-project reused_from (§3.0 violation)`,
+        });
+    }
+    else {
+        checks.push({
+            dimension: "isolation",
+            status: "PASS",
+            message: "No objects to check for isolation (stage 4)",
+        });
+    }
+    checks.push(buildGasBudgetCheck(input));
+    return checks;
+}
+function validateStage5Gate(input) {
+    const checks = [];
+    const coherent = input.trace_coherent === true;
+    checks.push({
+        dimension: "semantic",
+        status: coherent ? "PASS" : "FAIL",
+        message: coherent
+            ? "Substeps are coherent (no dangling/circular/missing)"
+            : "Substeps are not coherent — call trace_substeps and fix issues",
+    });
+    checks.push({
+        dimension: "tools",
+        status: coherent ? "PASS" : "FAIL",
+        message: coherent
+            ? "All substep dependencies resolve"
+            : "Substep dependencies have issues (see trace_substeps output)",
+    });
+    const hasPublished = input.has_published_object === true;
+    checks.push({
+        dimension: "reversibility",
+        status: hasPublished ? "WARN" : "PASS",
+        message: hasPublished
+            ? "Objects have been published on-chain — rollback requires fork (§3.3). " +
+                "Ensure all substeps are correct before executing on mainnet."
+            : "No objects published yet — stage 5 is still reversible",
+    });
+    checks.push({
+        dimension: "risk",
+        status: "PASS",
+        message: "Risks verified in stage 3",
+    });
+    checks.push({
+        dimension: "isolation",
+        status: "PASS",
+        message: "Isolation verified in stages 2 and 4",
+    });
+    checks.push(buildGasBudgetCheck(input));
+    return checks;
+}
+const STAGE_VALIDATORS = {
+    1: validateStage1Gate,
+    2: validateStage2Gate,
+    3: validateStage3Gate,
+    4: validateStage4Gate,
+    5: validateStage5Gate,
+};
+export function validateStageGate(input) {
+    const validator = STAGE_VALIDATORS[input.stage];
+    const checks = validator(input);
+    const blockingIssues = checks
+        .filter((c) => c.status === "FAIL")
+        .map((c) => `[${c.dimension}] ${c.message}`);
+    const warnings = checks
+        .filter((c) => c.status === "WARN")
+        .map((c) => `[${c.dimension}] ${c.message}`);
+    return {
+        stage: input.stage,
+        passed: blockingIssues.length === 0,
+        checks,
+        blocking_issues: blockingIssues,
+        warnings,
+        can_proceed: blockingIssues.length === 0,
+    };
+}
+export function validateStageGateFromDisk(prefix, version, stage, extra) {
+    if (!projectExists(prefix, version)) {
+        return {
+            stage: stage ?? 1,
+            passed: false,
+            checks: [{
+                    dimension: "semantic",
+                    status: "FAIL",
+                    message: `Project not found locally: ${prefix}_${version}`,
+                }],
+            blocking_issues: [`Project not found locally: ${prefix}_${version}`],
+            warnings: [],
+            can_proceed: false,
+        };
+    }
+    const state = loadStageState(prefix, version);
+    const effectiveStage = stage ?? state?.stage ?? 1;
+    const hasPublished = state?.has_published_object ?? false;
+    return validateStageGate({
+        stage: effectiveStage,
+        prefix,
+        version,
+        has_published_object: hasPublished,
+        ...extra,
+    });
+}

package/dist/schema/call/allocation.d.ts

@@ -1056,6 +1056,7 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         project: z.ZodOptional<z.ZodString>;
         client_schema_version: z.ZodOptional<z.ZodString>;
         schema_strict_mode: z.ZodOptional<z.ZodBoolean>;
+        dry_run: z.ZodOptional<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         account: string;
         no_cache?: boolean | undefined;
@@ -1067,6 +1068,7 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         project?: string | undefined;
         client_schema_version?: string | undefined;
         schema_strict_mode?: boolean | undefined;
+        dry_run?: boolean | undefined;
     }, {
         no_cache?: boolean | undefined;
         network?: import("@wowok/wowok").ENTRYPOINT | undefined;
@@ -1078,6 +1080,7 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         project?: string | undefined;
         client_schema_version?: string | undefined;
         schema_strict_mode?: boolean | undefined;
+        dry_run?: boolean | undefined;
     }>>;
     submission: z.ZodOptional<z.ZodObject<{
         type: z.ZodLiteral<"submission">;
@@ -1353,6 +1356,7 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         project?: string | undefined;
         client_schema_version?: string | undefined;
         schema_strict_mode?: boolean | undefined;
+        dry_run?: boolean | undefined;
     } | undefined;
 }, {
     data: {
@@ -1448,6 +1452,7 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         project?: string | undefined;
         client_schema_version?: string | undefined;
         schema_strict_mode?: boolean | undefined;
+        dry_run?: boolean | undefined;
     } | undefined;
 }>;
 export type CallAllocation_Create = z.infer<typeof CallAllocation_CreateSchema>;