@neuroverseos/governance 0.2.2 → 0.3.0

package/dist/init-world-VWMQZQC7.js

@@ -0,0 +1,223 @@
+import "./chunk-YZFATT7X.js";
+
+// src/cli/init-world.ts
+import { readFileSync, existsSync } from "fs";
+import { writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+function parseArgs(argv) {
+  const template = argv[0] || "";
+  let outputPath = "";
+  const config = {};
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--context" && i + 1 < argv.length) {
+      config.context = argv[++i];
+    } else if (arg === "--dataset" && i + 1 < argv.length) {
+      config.dataset = argv[++i];
+    } else if (arg === "--goal" && i + 1 < argv.length) {
+      config.goal = argv[++i];
+    } else if (arg === "--metric" && i + 1 < argv.length) {
+      config.metric = argv[++i];
+    } else if (arg === "--optimize" && i + 1 < argv.length) {
+      const dir = argv[++i];
+      if (dir === "minimize" || dir === "maximize") {
+        config.optimize = dir;
+      }
+    } else if (arg === "--compute" && i + 1 < argv.length) {
+      config.computeBudgetMinutes = parseInt(argv[++i], 10);
+    } else if (arg === "--output" && i + 1 < argv.length) {
+      outputPath = argv[++i];
+    }
+  }
+  return { template, config, outputPath };
+}
+var AVAILABLE_TEMPLATES = ["autoresearch"];
+function loadBaseTemplate(template) {
+  let currentDir;
+  try {
+    currentDir = dirname(fileURLToPath(import.meta.url));
+  } catch {
+    currentDir = __dirname;
+  }
+  const candidates = [
+    join(currentDir, "..", "worlds", `${template}.nv-world.md`),
+    join(currentDir, "worlds", `${template}.nv-world.md`),
+    // Fallback: resolve from process.cwd()
+    join(process.cwd(), "src", "worlds", `${template}.nv-world.md`)
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return readFileSync(candidate, "utf-8");
+    }
+  }
+  throw new Error(`Template "${template}" not found. Available: ${AVAILABLE_TEMPLATES.join(", ")}`);
+}
+function customizeAutoresearchWorld(baseTemplate, config) {
+  let output = baseTemplate;
+  if (config.context) {
+    const worldId = config.context.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "").slice(0, 40);
+    output = output.replace(/^world_id: autoresearch$/m, `world_id: ${worldId}_research`);
+    output = output.replace(/^name: Autoresearch Governance$/m, `name: ${config.context} Research`);
+  }
+  if (config.context) {
+    const customThesis = `Autonomous AI research loops investigating ${config.context} must operate within structured governance: experiments are reproducible, metrics are tracked, compute budgets are enforced, and agents cannot drift beyond their declared research context. A research world without constraints produces noise, not knowledge.`;
+    output = output.replace(
+      /^Autonomous AI research loops must operate.*$/m,
+      customThesis
+    );
+  }
+  if (config.dataset) {
+    output = output.replace(
+      /- `dataset_must_be_declared`[^\n]+/,
+      `- \`dataset_must_be_declared\` \u2014 The dataset "${config.dataset}" must be used for training and evaluation and never changed without governance approval (structural, immutable)`
+    );
+  }
+  if (config.context && config.constraints && config.constraints.length > 0) {
+    const constraintInvariants = config.constraints.map(
+      (c, i) => `- \`custom_constraint_${i + 1}\` \u2014 ${c} (prompt, immutable)`
+    ).join("\n");
+    output = output.replace(
+      /- `architecture_constraints_honored`[^\n]+/,
+      `- \`architecture_constraints_honored\` \u2014 If the research context declares architectural constraints, experiments must satisfy them (prompt, immutable)
+${constraintInvariants}`
+    );
+  }
+  if (config.metric) {
+    output = output.replace(
+      /Best value achieved for the primary evaluation metric/g,
+      `Best value achieved for ${config.metric}`
+    );
+  }
+  if (config.computeBudgetMinutes) {
+    output = output.replace(
+      /- default: 1440\n- label: Compute Budget/,
+      `- default: ${config.computeBudgetMinutes}
+- label: Compute Budget`
+    );
+  }
+  if (config.optimize === "maximize") {
+    output = output.replace(
+      /- default: 100\n- label: Best Metric Value/,
+      "- default: -1000\n- label: Best Metric Value"
+    );
+  }
+  return output;
+}
+function generateResearchContext(config) {
+  const context = {
+    research: {
+      context: config.context || "Define your research context",
+      dataset: config.dataset || "Define your dataset",
+      goal: config.goal || "Define your optimization goal",
+      metric: {
+        name: config.metric || "val_bpb",
+        optimization: config.optimize || "minimize"
+      }
+    },
+    roles: config.roles || [
+      "hypothesis_generator",
+      "experiment_runner",
+      "result_evaluator",
+      "critic"
+    ],
+    experiment_loop: {
+      generate_architecture: true,
+      train_model: true,
+      evaluate_results: true,
+      iterate: true
+    },
+    state: {
+      experiments_run: 0,
+      best_result: null,
+      architectures_tested: []
+    }
+  };
+  return JSON.stringify(context, null, 2);
+}
+async function main(argv = process.argv.slice(2)) {
+  try {
+    const args = parseArgs(argv);
+    if (!args.template) {
+      process.stderr.write("Usage: neuroverse init-world <template> [options]\n\n");
+      process.stderr.write("Available templates:\n");
+      for (const t of AVAILABLE_TEMPLATES) {
+        process.stderr.write(`  ${t}    Generate a governed research world for autonomous AI experiments
+`);
+      }
+      process.stderr.write("\nExample:\n");
+      process.stderr.write('  neuroverse init-world autoresearch --context "attention-free LLM architectures" --dataset "TinyStories"\n');
+      process.exit(1);
+      return;
+    }
+    if (!AVAILABLE_TEMPLATES.includes(args.template)) {
+      process.stderr.write(`Unknown template: "${args.template}"
+`);
+      process.stderr.write(`Available: ${AVAILABLE_TEMPLATES.join(", ")}
+`);
+      process.exit(1);
+      return;
+    }
+    const worldFileName = args.config.context ? args.config.context.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) + ".nv-world.md" : "research.nv-world.md";
+    const outputPath = args.outputPath || `./${worldFileName}`;
+    if (existsSync(outputPath)) {
+      process.stderr.write(`File already exists: ${outputPath}
+`);
+      process.stderr.write("Use --output to specify a different path.\n");
+      process.exit(2);
+      return;
+    }
+    const baseTemplate = loadBaseTemplate(args.template);
+    const customized = customizeAutoresearchWorld(baseTemplate, args.config);
+    await writeFile(outputPath, customized, "utf-8");
+    const contextPath = outputPath.replace(/\.nv-world\.md$/, ".research.json");
+    await writeFile(contextPath, generateResearchContext(args.config), "utf-8");
+    const result = {
+      created: {
+        world: outputPath,
+        context: contextPath
+      },
+      template: args.template,
+      config: {
+        context: args.config.context || null,
+        dataset: args.config.dataset || null,
+        goal: args.config.goal || null,
+        metric: args.config.metric || "val_bpb",
+        optimize: args.config.optimize || "minimize",
+        computeBudgetMinutes: args.config.computeBudgetMinutes || 1440
+      },
+      nextSteps: [
+        `Edit ${outputPath} to refine governance rules for your research`,
+        `neuroverse bootstrap --input ${outputPath} --output ./world/ --validate`,
+        `neuroverse simulate ${outputPath} --steps 5`,
+        `neuroverse guard --world ./world/ < experiment.json`,
+        `npx autoresearch run --world ${contextPath}`
+      ]
+    };
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    process.stderr.write("\n");
+    process.stderr.write(`\u2713 World created: ${outputPath}
+`);
+    process.stderr.write(`\u2713 Research context: ${contextPath}
+`);
+    process.stderr.write("\n");
+    process.stderr.write("Next steps:\n");
+    process.stderr.write(`  Compile world      neuroverse bootstrap --input ${outputPath} --output ./world/ --validate
+`);
+    process.stderr.write(`  Simulate           neuroverse simulate ${outputPath} --steps 5
+`);
+    process.stderr.write(`  Run autoresearch   npx autoresearch run --world ${contextPath}
+`);
+    process.stderr.write(`  Launch dashboard   make dashboard
+`);
+    process.stderr.write("\n");
+    process.exit(0);
+  } catch (e) {
+    process.stderr.write(`init-world failed: ${e instanceof Error ? e.message : e}
+`);
+    process.exit(3);
+  }
+}
+export {
+  main
+};

package/dist/{mcp-server-LZVJHBT5.js → mcp-server-FPVSU32Z.js}

@@ -1,11 +1,11 @@
 import {
   McpGovernanceServer,
   startMcpServer
-} from "./chunk-DPVS43ZT.js";
+} from "./chunk-OGL7QXZS.js";
 import "./chunk-AKW5YVCE.js";
 import "./chunk-4JRYGIO7.js";
-import "./chunk-JZPQGIKR.js";
 import "./chunk-4QXB6PEO.js";
+import "./chunk-JZPQGIKR.js";
 import "./chunk-YZFATT7X.js";
 export {
   McpGovernanceServer,

package/dist/{session-VISISNWJ.js → session-EKTRSR7C.js}

@@ -2,10 +2,10 @@ import {
   SessionManager,
   runInteractiveMode,
   runPipeMode
-} from "./chunk-KEST3MWO.js";
+} from "./chunk-4A7LISES.js";
 import "./chunk-4JRYGIO7.js";
-import "./chunk-JZPQGIKR.js";
 import "./chunk-4QXB6PEO.js";
+import "./chunk-JZPQGIKR.js";
 import "./chunk-YZFATT7X.js";
 export {
   SessionManager,

package/dist/worlds/autoresearch.nv-world.md

@@ -0,0 +1,230 @@
+---
+world_id: autoresearch
+name: Autoresearch Governance
+version: 1.0.0
+runtime_mode: SIMULATION
+default_profile: conservative
+alternative_profile: exploratory
+---
+
+# Thesis
+
+Autonomous AI research loops must operate within structured governance: experiments are reproducible, metrics are tracked, compute budgets are enforced, and agents cannot drift beyond their declared research context. A research world without constraints produces noise, not knowledge.
+
+# Invariants
+
+- `experiments_must_be_reproducible` — Every experiment must log architecture, hyperparameters, dataset, and training config sufficient to reproduce results (structural, immutable)
+- `metrics_must_be_recorded` — Every training run must produce at least one evaluation metric; runs without metrics are invalid (structural, immutable)
+- `dataset_must_be_declared` — The dataset used for training and evaluation must be explicitly declared and never changed without governance approval (structural, immutable)
+- `goal_must_be_defined` — The optimization goal (metric + direction) must be defined before any experiment runs (structural, immutable)
+- `no_data_leakage` — Training data must never contaminate evaluation data; train/val/test splits must be fixed (structural, immutable)
+- `compute_budget_enforced` — Experiments must respect declared compute limits; exceeding budget halts the loop (structural, immutable)
+- `architecture_constraints_honored` — If the research context declares architectural constraints, experiments must satisfy them (prompt, immutable)
+
+# State
+
+## experiments_run
+- type: number
+- min: 0
+- max: 10000
+- step: 1
+- default: 0
+- label: Experiments Run
+- description: Total number of experiments completed in this research loop
+
+## best_metric_value
+- type: number
+- min: -1000
+- max: 1000
+- step: 0.01
+- default: 100
+- label: Best Metric Value
+- description: Best value achieved for the primary evaluation metric
+
+## keep_rate
+- type: number
+- min: 0
+- max: 100
+- step: 1
+- default: 0
+- label: Keep Rate
+- description: Percentage of experiments that improved upon the previous best result
+
+## compute_used_minutes
+- type: number
+- min: 0
+- max: 100000
+- step: 1
+- default: 0
+- label: Compute Used (minutes)
+- description: Total wall-clock training time consumed across all experiments
+
+## compute_budget_minutes
+- type: number
+- min: 0
+- max: 100000
+- step: 60
+- default: 1440
+- label: Compute Budget (minutes)
+- description: Maximum allowed wall-clock training time for the research loop
+
+## research_context_drift
+- type: number
+- min: 0
+- max: 100
+- step: 1
+- default: 0
+- label: Context Drift
+- description: Degree to which recent experiments have diverged from the declared research context. 0 = on-topic. 100 = unrelated.
+
+## metric_improvement_rate
+- type: number
+- min: 0
+- max: 100
+- step: 1
+- default: 0
+- label: Improvement Rate
+- description: Rate of metric improvement over the last 10 experiments. 0 = stagnant. 100 = rapid improvement.
+
+## failed_experiments
+- type: number
+- min: 0
+- max: 10000
+- step: 1
+- default: 0
+- label: Failed Experiments
+- description: Number of experiments that crashed, timed out, or produced no valid metrics
+
+# Assumptions
+
+## conservative
+- name: Conservative Research
+- description: Prioritize reproducibility and careful iteration. Small architectural changes per experiment. Strict compute limits. Reject experiments that drift from the research context.
+- iteration_style: incremental
+- drift_tolerance: low
+- compute_strictness: high
+- failure_tolerance: low
+
+## exploratory
+- name: Exploratory Research
+- description: Allow broader architectural exploration. Larger jumps between experiments. More lenient compute budget. Accept higher context drift if metrics improve.
+- iteration_style: explorative
+- drift_tolerance: moderate
+- compute_strictness: moderate
+- failure_tolerance: moderate
+
+# Rules
+
+## rule-001: Compute Budget Exhausted (structural)
+When compute budget is exceeded, the research loop must halt. No further experiments are allowed.
+
+When compute_used_minutes > compute_budget_minutes [state]
+Then research_viability *= 0.00
+Collapse: research_viability < 0.05
+
+> trigger: Compute usage exceeds declared budget — no training time remains.
+> rule: Unbounded compute makes research ungovernable. The budget is a hard constraint, not a suggestion.
+> shift: Research loop halts. Final results are reported. No new experiments start.
+> effect: Research viability set to zero. Loop terminated.
+
+## rule-002: High Failure Rate (degradation)
+Too many failed experiments indicate a systemic problem — bad code, misconfigured environment, or impossible architecture.
+
+When failed_experiments > 5 [state] AND experiments_run > 0 [state]
+Then research_viability *= 0.50
+
+> trigger: More than 5 experiments have failed — possible systemic issue.
+> rule: Failures consume compute without producing knowledge. High failure rates signal infrastructure problems, not research progress.
+> shift: Research viability degrades. Agent should investigate root cause before continuing.
+> effect: Research viability reduced to 50%.
+
+## rule-003: Context Drift Warning (degradation)
+Experiments diverging from the declared research context waste compute and produce irrelevant results.
+
+When research_context_drift > 40 [state]
+Then research_viability *= 0.60
+
+> trigger: Context drift above 40% — experiments are straying from the research topic.
+> rule: Governance exists to keep research focused. Agents exploring unrelated architectures are not contributing to the declared goal.
+> shift: Research viability degrades. Agent must return to the declared research context.
+> effect: Research viability reduced to 60%.
+
+## rule-004: Metric Stagnation (degradation)
+When experiments stop improving the primary metric, the research approach may need fundamental revision.
+
+When metric_improvement_rate < 5 [state] AND experiments_run > 10 [state]
+Then research_viability *= 0.70
+
+> trigger: Improvement rate below 5% after 10+ experiments — research may have plateaued.
+> rule: Stagnant metrics indicate diminishing returns from the current approach. The agent should consider a strategy change.
+> shift: Research viability degrades. Agent should try a substantially different approach or conclude the loop.
+> effect: Research viability reduced to 70%.
+
+## rule-005: Strong Progress (advantage)
+Consistent metric improvement validates the research approach and warrants continued investment.
+
+When metric_improvement_rate > 30 [state] AND keep_rate > 20 [state]
+Then research_viability *= 1.20
+
+> trigger: Improvement rate above 30% with keep rate above 20% — research is productive.
+> rule: Productive research should be encouraged. Strong metric trends indicate a promising research direction.
+> shift: Research viability improves. Continued experimentation is well-justified.
+> effect: Research viability boosted by 20%.
+
+## rule-006: No Metrics Recorded (structural)
+An experiment that produces no evaluation metrics is invalid and must not count as progress.
+
+When experiments_run > 0 [state] AND best_metric_value == 100 [state]
+Then research_viability *= 0.30
+Collapse: research_viability < 0.05
+
+> trigger: Experiments have run but no metric improvement from default — metrics may not be recording.
+> rule: Research without measurement is not research. Every experiment must produce at least one evaluation metric.
+> shift: Research viability drops sharply. Agent must fix metric recording before continuing.
+> effect: Research viability reduced to 30%.
+
+## rule-007: Efficient Compute Usage (advantage)
+High keep rate with low compute usage indicates efficient research methodology.
+
+When keep_rate > 30 [state] AND compute_used_minutes < compute_budget_minutes [state]
+Then research_viability *= 1.15
+
+> trigger: Keep rate above 30% with compute budget remaining — efficient experimentation.
+> rule: Efficient use of compute demonstrates disciplined research. Not every experiment needs to be expensive.
+> shift: Research viability improves. The research methodology is sustainable.
+> effect: Research viability boosted by 15%.
+
+# Gates
+
+- BREAKTHROUGH: research_viability >= 90
+- PRODUCTIVE: research_viability >= 60
+- ONGOING: research_viability >= 35
+- STRUGGLING: research_viability > 10
+- HALTED: research_viability <= 10
+
+# Outcomes
+
+## research_viability
+- type: number
+- range: 0-100
+- display: percentage
+- label: Research Viability
+- primary: true
+
+## best_metric_value
+- type: number
+- range: -1000-1000
+- display: decimal
+- label: Best Metric Value
+
+## keep_rate
+- type: number
+- range: 0-100
+- display: percentage
+- label: Keep Rate
+
+## experiments_run
+- type: number
+- range: 0-10000
+- display: integer
+- label: Experiments Run

package/llms.txt

@@ -0,0 +1,79 @@
+# NeuroVerse Governance
+
+> Deterministic runtime governance for AI agents. No LLM in the evaluation loop.
+
+## What it does
+
+NeuroVerse enforces behavioral boundaries on AI agents. Every agent action passes
+through a 6-phase evaluation pipeline and receives an ALLOW, BLOCK, or PAUSE verdict.
+Same event + same rules = same verdict, every time.
+
+## Core concepts
+
+- **World**: Permanent governance rules (guards, invariants, kernel rules, roles)
+- **Plan**: Temporary task-scoped constraints layered on top of a world
+- **Guard event**: An action an agent wants to take (intent, tool, scope)
+- **Verdict**: ALLOW, BLOCK, or PAUSE — returned synchronously, no network calls
+
+## Install
+
+```bash
+npm install @neuroverseos/governance
+```
+
+## Quick test (no install required)
+
+```bash
+npx @neuroverseos/governance init
+npx @neuroverseos/governance build
+npx @neuroverseos/governance guard
+```
+
+## Programmatic usage
+
+```javascript
+import { evaluateGuard, loadWorld } from '@neuroverseos/governance';
+
+const world = await loadWorld('./world/');
+const verdict = evaluateGuard({ intent: 'delete user data', tool: 'database' }, world);
+// → { status: 'BLOCK', reason: 'Destructive database operation on protected resource' }
+```
+
+## Plan enforcement
+
+```javascript
+import { parsePlanMarkdown, evaluatePlan, advancePlan } from '@neuroverseos/governance';
+
+const { plan } = parsePlanMarkdown(markdown);
+const verdict = evaluatePlan({ intent: 'write blog post' }, plan);
+// → { status: 'ON_PLAN', matchedStep: 'write_announcement_blog_post' }
+
+const result = advancePlan(plan, 'write_announcement_blog_post');
+// → { success: true, plan: <updated> }
+```
+
+Plans support two completion modes:
+- `completion: trust` (default) — caller says "done", step advances
+- `completion: verified` — steps with `[verify: ...]` require evidence to advance
+
+## Adapters
+
+- OpenAI function calling: `@neuroverseos/governance/adapters/openai`
+- LangChain callback handler: `@neuroverseos/governance/adapters/langchain`
+- OpenClaw plugin: `@neuroverseos/governance/adapters/openclaw`
+- Express/Fastify middleware: `@neuroverseos/governance/adapters/express`
+- MCP server: `neuroverse mcp --world ./world`
+
+## Evaluation pipeline
+
+```
+Safety → Plan → Roles → Guards → Kernel → Level → Verdict
+```
+
+First BLOCK wins. No async. Pure function.
+
+## Links
+
+- npm: https://www.npmjs.com/package/@neuroverseos/governance
+- GitHub: https://github.com/NeuroverseOS/Neuroverseos-governance
+- Website: https://neuroverseos.com