@neuroverseos/governance 0.2.2 → 0.3.0

package/dist/adapters/autoresearch.d.cts

@@ -0,0 +1,103 @@
+import { W as WorldDefinition, G as GuardEvent } from '../guard-contract-WZx__PmU.cjs';
+
+/**
+ * Autoresearch Adapter — Bridge between NeuroVerse governance and autoresearch loops
+ *
+ * This adapter translates autoresearch experiment events into GuardEvents
+ * that can be evaluated by the NeuroVerse governance engine.
+ *
+ * Usage:
+ *   import { AutoresearchGovernor } from '@neuroverseos/governance/adapters';
+ *
+ *   const governor = new AutoresearchGovernor({ worldPath: './world/' });
+ *   const verdict = await governor.evaluateExperiment(experiment);
+ *   const state = governor.updateState(experimentResult);
+ */
+
+interface ExperimentProposal {
+    experiment_id: number;
+    architecture: string;
+    description: string;
+    estimated_minutes?: number;
+    hyperparameters?: Record<string, unknown>;
+}
+interface ExperimentResult {
+    experiment_id: number;
+    architecture: string;
+    dataset: string;
+    metric_name: string;
+    metric_value: number;
+    training_config: Record<string, unknown>;
+    wall_clock_minutes: number;
+    timestamp: string;
+    success: boolean;
+    error?: string;
+}
+interface ResearchState {
+    experiments_run: number;
+    best_result: ExperimentResult | null;
+    architectures_tested: string[];
+    experiment_log: ExperimentResult[];
+    total_compute_minutes: number;
+    keep_count: number;
+}
+interface AutoresearchGovernorConfig {
+    world?: WorldDefinition;
+    worldPath?: string;
+    metric: string;
+    optimize: 'minimize' | 'maximize';
+    computeBudgetMinutes: number;
+    dataset: string;
+    context: string;
+    constraints?: string[];
+}
+declare class AutoresearchGovernor {
+    private config;
+    private state;
+    constructor(config: AutoresearchGovernorConfig);
+    /**
+     * Convert an experiment proposal into a GuardEvent for governance evaluation.
+     */
+    proposalToGuardEvent(proposal: ExperimentProposal): GuardEvent;
+    /**
+     * Evaluate an experiment proposal against governance rules.
+     * Returns a simplified verdict without requiring the full guard engine.
+     */
+    evaluateProposal(proposal: ExperimentProposal): {
+        allowed: boolean;
+        reason: string;
+        warnings: string[];
+    };
+    /**
+     * Record an experiment result and update research state.
+     */
+    recordResult(result: ExperimentResult): {
+        kept: boolean;
+        improvement: number | null;
+        state: ResearchState;
+    };
+    /**
+     * Export current state as a state snapshot compatible with the world file.
+     */
+    toWorldState(): Record<string, number>;
+    /**
+     * Get a summary of the current research state.
+     */
+    getSummary(): {
+        experiments_run: number;
+        best_result: ExperimentResult | null;
+        keep_rate: number;
+        compute_remaining_minutes: number;
+        architectures_tested: string[];
+    };
+    /**
+     * Load state from a persisted research context file.
+     */
+    loadState(state: ResearchState): void;
+    /**
+     * Export state for persistence.
+     */
+    exportState(): ResearchState;
+}
+
+export { AutoresearchGovernor, type AutoresearchGovernorConfig, type ExperimentProposal, type ExperimentResult, type ResearchState };

package/dist/adapters/autoresearch.d.ts

@@ -0,0 +1,103 @@
+import { W as WorldDefinition, G as GuardEvent } from '../guard-contract-WZx__PmU.js';
+
+/**
+ * Autoresearch Adapter — Bridge between NeuroVerse governance and autoresearch loops
+ *
+ * This adapter translates autoresearch experiment events into GuardEvents
+ * that can be evaluated by the NeuroVerse governance engine.
+ *
+ * Usage:
+ *   import { AutoresearchGovernor } from '@neuroverseos/governance/adapters';
+ *
+ *   const governor = new AutoresearchGovernor({ worldPath: './world/' });
+ *   const verdict = await governor.evaluateExperiment(experiment);
+ *   const state = governor.updateState(experimentResult);
+ */
+
+interface ExperimentProposal {
+    experiment_id: number;
+    architecture: string;
+    description: string;
+    estimated_minutes?: number;
+    hyperparameters?: Record<string, unknown>;
+}
+interface ExperimentResult {
+    experiment_id: number;
+    architecture: string;
+    dataset: string;
+    metric_name: string;
+    metric_value: number;
+    training_config: Record<string, unknown>;
+    wall_clock_minutes: number;
+    timestamp: string;
+    success: boolean;
+    error?: string;
+}
+interface ResearchState {
+    experiments_run: number;
+    best_result: ExperimentResult | null;
+    architectures_tested: string[];
+    experiment_log: ExperimentResult[];
+    total_compute_minutes: number;
+    keep_count: number;
+}
+interface AutoresearchGovernorConfig {
+    world?: WorldDefinition;
+    worldPath?: string;
+    metric: string;
+    optimize: 'minimize' | 'maximize';
+    computeBudgetMinutes: number;
+    dataset: string;
+    context: string;
+    constraints?: string[];
+}
+declare class AutoresearchGovernor {
+    private config;
+    private state;
+    constructor(config: AutoresearchGovernorConfig);
+    /**
+     * Convert an experiment proposal into a GuardEvent for governance evaluation.
+     */
+    proposalToGuardEvent(proposal: ExperimentProposal): GuardEvent;
+    /**
+     * Evaluate an experiment proposal against governance rules.
+     * Returns a simplified verdict without requiring the full guard engine.
+     */
+    evaluateProposal(proposal: ExperimentProposal): {
+        allowed: boolean;
+        reason: string;
+        warnings: string[];
+    };
+    /**
+     * Record an experiment result and update research state.
+     */
+    recordResult(result: ExperimentResult): {
+        kept: boolean;
+        improvement: number | null;
+        state: ResearchState;
+    };
+    /**
+     * Export current state as a state snapshot compatible with the world file.
+     */
+    toWorldState(): Record<string, number>;
+    /**
+     * Get a summary of the current research state.
+     */
+    getSummary(): {
+        experiments_run: number;
+        best_result: ExperimentResult | null;
+        keep_rate: number;
+        compute_remaining_minutes: number;
+        architectures_tested: string[];
+    };
+    /**
+     * Load state from a persisted research context file.
+     */
+    loadState(state: ResearchState): void;
+    /**
+     * Export state for persistence.
+     */
+    exportState(): ResearchState;
+}
+
+export { AutoresearchGovernor, type AutoresearchGovernorConfig, type ExperimentProposal, type ExperimentResult, type ResearchState };

package/dist/adapters/autoresearch.js

@@ -0,0 +1,7 @@
+import {
+  AutoresearchGovernor
+} from "../chunk-T5EUJQE5.js";
+import "../chunk-YZFATT7X.js";
+export {
+  AutoresearchGovernor
+};

package/dist/adapters/express.d.cts

@@ -1,4 +1,4 @@
-import { G as GuardVerdict, a as GuardEvent, W as WorldDefinition } from '../guard-contract-Cm91Kp4j.cjs';
+import { a as GuardVerdict, G as GuardEvent, W as WorldDefinition } from '../guard-contract-WZx__PmU.cjs';
 
 /**
  * NeuroVerse Adapter — Express / Fastify

package/dist/adapters/express.d.ts

@@ -1,4 +1,4 @@
-import { G as GuardVerdict, a as GuardEvent, W as WorldDefinition } from '../guard-contract-Cm91Kp4j.js';
+import { a as GuardVerdict, G as GuardEvent, W as WorldDefinition } from '../guard-contract-WZx__PmU.js';
 
 /**
  * NeuroVerse Adapter — Express / Fastify

package/dist/adapters/express.js

@@ -3,8 +3,8 @@ import {
   createGovernanceMiddlewareFromWorld
 } from "../chunk-2NICNKOM.js";
 import "../chunk-4JRYGIO7.js";
-import "../chunk-JZPQGIKR.js";
 import "../chunk-4QXB6PEO.js";
+import "../chunk-JZPQGIKR.js";
 import "../chunk-YZFATT7X.js";
 export {
   createGovernanceMiddleware,

package/dist/adapters/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/adapters/index.ts
 var adapters_exports = {};
 __export(adapters_exports, {
+  AutoresearchGovernor: () => AutoresearchGovernor,
   GovernedToolExecutor: () => GovernedToolExecutor,
   LangChainGovernanceBlockedError: () => GovernanceBlockedError,
   NeuroVerseCallbackHandler: () => NeuroVerseCallbackHandler,
@@ -1479,8 +1480,178 @@ function createGovernanceMiddlewareFromWorld(world, options = {}) {
     }
   };
 }
+
+// src/adapters/autoresearch.ts
+var AutoresearchGovernor = class {
+  config;
+  state;
+  constructor(config) {
+    this.config = config;
+    this.state = {
+      experiments_run: 0,
+      best_result: null,
+      architectures_tested: [],
+      experiment_log: [],
+      total_compute_minutes: 0,
+      keep_count: 0
+    };
+  }
+  /**
+   * Convert an experiment proposal into a GuardEvent for governance evaluation.
+   */
+  proposalToGuardEvent(proposal) {
+    return {
+      intent: `run experiment: ${proposal.description}`,
+      tool: "experiment_runner",
+      scope: "experiment",
+      roleId: "experiment_runner",
+      direction: "output",
+      actionCategory: "shell",
+      args: {
+        experiment_id: String(proposal.experiment_id),
+        architecture: proposal.architecture,
+        estimated_minutes: String(proposal.estimated_minutes || 5)
+      }
+    };
+  }
+  /**
+   * Evaluate an experiment proposal against governance rules.
+   * Returns a simplified verdict without requiring the full guard engine.
+   */
+  evaluateProposal(proposal) {
+    const warnings = [];
+    const estimatedMinutes = proposal.estimated_minutes || 5;
+    if (this.state.total_compute_minutes + estimatedMinutes > this.config.computeBudgetMinutes) {
+      return {
+        allowed: false,
+        reason: `Compute budget exhausted: ${this.state.total_compute_minutes}/${this.config.computeBudgetMinutes} minutes used`,
+        warnings
+      };
+    }
+    if (this.config.constraints) {
+      for (const constraint of this.config.constraints) {
+        const lower = constraint.toLowerCase();
+        const archLower = proposal.architecture.toLowerCase();
+        const descLower = proposal.description.toLowerCase();
+        if (lower.startsWith("no ")) {
+          const forbidden = lower.slice(3).trim();
+          if (archLower.includes(forbidden) || descLower.includes(forbidden)) {
+            return {
+              allowed: false,
+              reason: `Architecture constraint violated: ${constraint}`,
+              warnings
+            };
+          }
+        }
+      }
+    }
+    const failureCount = this.state.experiment_log.filter((e) => !e.success).length;
+    if (failureCount > 5) {
+      warnings.push(`High failure rate: ${failureCount} failed experiments. Consider investigating root cause.`);
+    }
+    const recentArchitectures = this.state.experiment_log.slice(-5).map((e) => e.architecture);
+    const uniqueRecent = new Set(recentArchitectures).size;
+    if (recentArchitectures.length >= 5 && uniqueRecent === 1) {
+      warnings.push("Research may be stuck: last 5 experiments used the same architecture.");
+    }
+    return { allowed: true, reason: "Experiment approved", warnings };
+  }
+  /**
+   * Record an experiment result and update research state.
+   */
+  recordResult(result) {
+    this.state.experiments_run++;
+    this.state.total_compute_minutes += result.wall_clock_minutes;
+    this.state.experiment_log.push(result);
+    if (!this.state.architectures_tested.includes(result.architecture)) {
+      this.state.architectures_tested.push(result.architecture);
+    }
+    if (!result.success) {
+      return { kept: false, improvement: null, state: { ...this.state } };
+    }
+    let kept = false;
+    let improvement = null;
+    if (this.state.best_result === null) {
+      kept = true;
+      this.state.best_result = result;
+      this.state.keep_count++;
+    } else {
+      const prev = this.state.best_result.metric_value;
+      const curr = result.metric_value;
+      if (this.config.optimize === "minimize") {
+        kept = curr < prev;
+        improvement = kept ? prev - curr : null;
+      } else {
+        kept = curr > prev;
+        improvement = kept ? curr - prev : null;
+      }
+      if (kept) {
+        this.state.best_result = result;
+        this.state.keep_count++;
+      }
+    }
+    return { kept, improvement, state: { ...this.state } };
+  }
+  /**
+   * Export current state as a state snapshot compatible with the world file.
+   */
+  toWorldState() {
+    const successfulExperiments = this.state.experiment_log.filter((e) => e.success);
+    const failedCount = this.state.experiment_log.filter((e) => !e.success).length;
+    const keepRate = this.state.experiments_run > 0 ? Math.round(this.state.keep_count / this.state.experiments_run * 100) : 0;
+    let improvementRate = 0;
+    if (successfulExperiments.length >= 2) {
+      const recent = successfulExperiments.slice(-10);
+      let improvements = 0;
+      for (let i = 1; i < recent.length; i++) {
+        const prev = recent[i - 1].metric_value;
+        const curr = recent[i].metric_value;
+        if (this.config.optimize === "minimize" ? curr < prev : curr > prev) {
+          improvements++;
+        }
+      }
+      improvementRate = Math.round(improvements / (recent.length - 1) * 100);
+    }
+    return {
+      experiments_run: this.state.experiments_run,
+      best_metric_value: this.state.best_result?.metric_value ?? (this.config.optimize === "minimize" ? 100 : -1e3),
+      keep_rate: keepRate,
+      compute_used_minutes: Math.round(this.state.total_compute_minutes),
+      compute_budget_minutes: this.config.computeBudgetMinutes,
+      failed_experiments: failedCount,
+      metric_improvement_rate: improvementRate,
+      research_context_drift: 0
+      // would need NLP to compute properly
+    };
+  }
+  /**
+   * Get a summary of the current research state.
+   */
+  getSummary() {
+    return {
+      experiments_run: this.state.experiments_run,
+      best_result: this.state.best_result,
+      keep_rate: this.state.experiments_run > 0 ? Math.round(this.state.keep_count / this.state.experiments_run * 100) : 0,
+      compute_remaining_minutes: this.config.computeBudgetMinutes - this.state.total_compute_minutes,
+      architectures_tested: [...this.state.architectures_tested]
+    };
+  }
+  /**
+   * Load state from a persisted research context file.
+   */
+  loadState(state) {
+    this.state = { ...state };
+  }
+  /**
+   * Export state for persistence.
+   */
+  exportState() {
+    return { ...this.state };
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AutoresearchGovernor,
   GovernedToolExecutor,
   LangChainGovernanceBlockedError,
   NeuroVerseCallbackHandler,

package/dist/adapters/index.d.cts

@@ -2,4 +2,5 @@ export { GovernanceBlockedError as LangChainGovernanceBlockedError, NeuroVerseCa
 export { GovernedExecutorOptions, GovernedToolExecutor, GovernedToolResult, GovernanceBlockedError as OpenAIGovernanceBlockedError, OpenAIToolCall, createGovernedToolExecutor, createGovernedToolExecutorFromWorld } from './openai.cjs';
 export { AgentAction, HookResult, NeuroVersePlugin, NeuroVersePluginOptions, GovernanceBlockedError as OpenClawGovernanceBlockedError, createNeuroVersePlugin, createNeuroVersePluginFromWorld } from './openclaw.cjs';
 export { GovernanceMiddlewareOptions, GovernanceRequest, GovernanceResponse, createGovernanceMiddleware, createGovernanceMiddlewareFromWorld } from './express.cjs';
-import '../guard-contract-Cm91Kp4j.cjs';
+export { AutoresearchGovernor, AutoresearchGovernorConfig, ExperimentProposal, ExperimentResult, ResearchState } from './autoresearch.cjs';
+import '../guard-contract-WZx__PmU.cjs';

package/dist/adapters/index.d.ts

@@ -2,4 +2,5 @@ export { GovernanceBlockedError as LangChainGovernanceBlockedError, NeuroVerseCa
 export { GovernedExecutorOptions, GovernedToolExecutor, GovernedToolResult, GovernanceBlockedError as OpenAIGovernanceBlockedError, OpenAIToolCall, createGovernedToolExecutor, createGovernedToolExecutorFromWorld } from './openai.js';
 export { AgentAction, HookResult, NeuroVersePlugin, NeuroVersePluginOptions, GovernanceBlockedError as OpenClawGovernanceBlockedError, createNeuroVersePlugin, createNeuroVersePluginFromWorld } from './openclaw.js';
 export { GovernanceMiddlewareOptions, GovernanceRequest, GovernanceResponse, createGovernanceMiddleware, createGovernanceMiddlewareFromWorld } from './express.js';
-import '../guard-contract-Cm91Kp4j.js';
+export { AutoresearchGovernor, AutoresearchGovernorConfig, ExperimentProposal, ExperimentResult, ResearchState } from './autoresearch.js';
+import '../guard-contract-WZx__PmU.js';

package/dist/adapters/index.js

@@ -1,3 +1,6 @@
+import {
+  AutoresearchGovernor
+} from "../chunk-T5EUJQE5.js";
 import {
   createGovernanceMiddleware,
   createGovernanceMiddlewareFromWorld
@@ -7,24 +10,25 @@ import {
   NeuroVerseCallbackHandler,
   createNeuroVerseCallbackHandler,
   createNeuroVerseCallbackHandlerFromWorld
-} from "../chunk-RWXVAH6P.js";
+} from "../chunk-COT5XS4V.js";
 import {
   GovernanceBlockedError as GovernanceBlockedError2,
   GovernedToolExecutor,
   createGovernedToolExecutor,
   createGovernedToolExecutorFromWorld
-} from "../chunk-OHAC6HJE.js";
+} from "../chunk-ER62HNGF.js";
 import {
   GovernanceBlockedError as GovernanceBlockedError3,
   NeuroVersePlugin,
   createNeuroVersePlugin,
   createNeuroVersePluginFromWorld
-} from "../chunk-SKU3GAPD.js";
+} from "../chunk-2PQU3VAN.js";
 import "../chunk-4JRYGIO7.js";
-import "../chunk-JZPQGIKR.js";
 import "../chunk-4QXB6PEO.js";
+import "../chunk-JZPQGIKR.js";
 import "../chunk-YZFATT7X.js";
 export {
+  AutoresearchGovernor,
   GovernedToolExecutor,
   GovernanceBlockedError as LangChainGovernanceBlockedError,
   NeuroVerseCallbackHandler,

package/dist/adapters/langchain.d.cts

@@ -1,4 +1,4 @@
-import { G as GuardVerdict, a as GuardEvent, W as WorldDefinition, P as PlanDefinition, b as PlanProgress } from '../guard-contract-Cm91Kp4j.cjs';
+import { a as GuardVerdict, G as GuardEvent, W as WorldDefinition, P as PlanDefinition, b as PlanProgress } from '../guard-contract-WZx__PmU.cjs';
 
 /**
  * NeuroVerse Adapter — LangChain

package/dist/adapters/langchain.d.ts

@@ -1,4 +1,4 @@
-import { G as GuardVerdict, a as GuardEvent, W as WorldDefinition, P as PlanDefinition, b as PlanProgress } from '../guard-contract-Cm91Kp4j.js';
+import { a as GuardVerdict, G as GuardEvent, W as WorldDefinition, P as PlanDefinition, b as PlanProgress } from '../guard-contract-WZx__PmU.js';
 
 /**
  * NeuroVerse Adapter — LangChain

package/dist/adapters/langchain.js

@@ -3,10 +3,10 @@ import {
   NeuroVerseCallbackHandler,
   createNeuroVerseCallbackHandler,
   createNeuroVerseCallbackHandlerFromWorld
-} from "../chunk-RWXVAH6P.js";
+} from "../chunk-COT5XS4V.js";
 import "../chunk-4JRYGIO7.js";
-import "../chunk-JZPQGIKR.js";
 import "../chunk-4QXB6PEO.js";
+import "../chunk-JZPQGIKR.js";
 import "../chunk-YZFATT7X.js";
 export {
   GovernanceBlockedError,

package/dist/adapters/openai.d.cts

@@ -1,4 +1,4 @@
-import { G as GuardVerdict, a as GuardEvent, P as PlanDefinition, b as PlanProgress, W as WorldDefinition } from '../guard-contract-Cm91Kp4j.cjs';
+import { a as GuardVerdict, G as GuardEvent, P as PlanDefinition, b as PlanProgress, W as WorldDefinition } from '../guard-contract-WZx__PmU.cjs';
 
 /**
  * NeuroVerse Adapter — OpenAI

package/dist/adapters/openai.d.ts

@@ -1,4 +1,4 @@
-import { G as GuardVerdict, a as GuardEvent, P as PlanDefinition, b as PlanProgress, W as WorldDefinition } from '../guard-contract-Cm91Kp4j.js';
+import { a as GuardVerdict, G as GuardEvent, P as PlanDefinition, b as PlanProgress, W as WorldDefinition } from '../guard-contract-WZx__PmU.js';
 
 /**
  * NeuroVerse Adapter — OpenAI

package/dist/adapters/openai.js

@@ -3,10 +3,10 @@ import {
   GovernedToolExecutor,
   createGovernedToolExecutor,
   createGovernedToolExecutorFromWorld
-} from "../chunk-OHAC6HJE.js";
+} from "../chunk-ER62HNGF.js";
 import "../chunk-4JRYGIO7.js";
-import "../chunk-JZPQGIKR.js";
 import "../chunk-4QXB6PEO.js";
+import "../chunk-JZPQGIKR.js";
 import "../chunk-YZFATT7X.js";
 export {
   GovernanceBlockedError,

package/dist/adapters/openclaw.d.cts

@@ -1,4 +1,4 @@
-import { G as GuardVerdict, W as WorldDefinition, a as GuardEvent, P as PlanDefinition, b as PlanProgress } from '../guard-contract-Cm91Kp4j.cjs';
+import { a as GuardVerdict, W as WorldDefinition, G as GuardEvent, P as PlanDefinition, b as PlanProgress } from '../guard-contract-WZx__PmU.cjs';
 
 /**
  * NeuroVerse Adapter — OpenClaw

package/dist/adapters/openclaw.d.ts

@@ -1,4 +1,4 @@
-import { G as GuardVerdict, W as WorldDefinition, a as GuardEvent, P as PlanDefinition, b as PlanProgress } from '../guard-contract-Cm91Kp4j.js';
+import { a as GuardVerdict, W as WorldDefinition, G as GuardEvent, P as PlanDefinition, b as PlanProgress } from '../guard-contract-WZx__PmU.js';
 
 /**
  * NeuroVerse Adapter — OpenClaw

package/dist/adapters/openclaw.js

@@ -3,10 +3,10 @@ import {
   NeuroVersePlugin,
   createNeuroVersePlugin,
   createNeuroVersePluginFromWorld
-} from "../chunk-SKU3GAPD.js";
+} from "../chunk-2PQU3VAN.js";
 import "../chunk-4JRYGIO7.js";
-import "../chunk-JZPQGIKR.js";
 import "../chunk-4QXB6PEO.js";
+import "../chunk-JZPQGIKR.js";
 import "../chunk-YZFATT7X.js";
 export {
   GovernanceBlockedError,