@neuroverseos/governance 0.3.1 → 0.3.3

package/dist/world-BIP4GZBZ.js

@@ -0,0 +1,376 @@
+import {
+  validateWorld
+} from "./chunk-7P3S7MAY.js";
+import {
+  describeActiveWorld,
+  getActiveWorldName,
+  listWorlds,
+  resolveWorldPath,
+  setActiveWorld
+} from "./chunk-AKW5YVCE.js";
+import {
+  loadWorld
+} from "./chunk-CTZHONLA.js";
+import "./chunk-QWGCMQQD.js";
+
+// src/cli/world.ts
+var USAGE = `
+neuroverse world \u2014 World management
+
+Usage:
+  neuroverse world list                    List available worlds
+  neuroverse world use <name>              Set the active world
+  neuroverse world current                 Show which world is active and why
+  neuroverse world status [path|name]      Show world identity and health
+  neuroverse world diff <path1> <path2>    Compare two world versions
+  neuroverse world snapshot <path>         Save a timestamped snapshot
+  neuroverse world rollback <path>         Restore the previous snapshot
+
+Environment:
+  NEUROVERSE_WORLD=<name>    Override active world (for CI/agents)
+
+Options:
+  --json    Output as JSON
+`.trim();
+function parseArgs(argv) {
+  const subcommand = argv[0];
+  const paths = [];
+  const flags = {};
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") flags.json = true;
+    else if (arg === "--help" || arg === "-h") flags.help = true;
+    else paths.push(arg);
+  }
+  return { subcommand, paths, flags };
+}
+async function worldStatus(worldPath, json) {
+  const world = await loadWorld(worldPath);
+  const report = validateWorld(world);
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      world: world.world,
+      metadata: world.metadata,
+      guards: world.guards?.guards.length ?? 0,
+      invariants: world.invariants.length,
+      rules: world.rules.length,
+      roles: world.roles?.roles.length ?? 0,
+      kernel: world.kernel ? {
+        forbiddenInputs: world.kernel.input_boundaries?.forbidden_patterns?.length ?? 0,
+        forbiddenOutputs: world.kernel.output_boundaries?.forbidden_patterns?.length ?? 0
+      } : null,
+      validation: report.summary
+    }, null, 2) + "\n");
+    return;
+  }
+  const lines = [];
+  lines.push("WORLD STATUS");
+  lines.push("\u2500".repeat(40));
+  lines.push(`  Name:       ${world.world.name}`);
+  lines.push(`  ID:         ${world.world.world_id}`);
+  lines.push(`  Version:    ${world.world.version}`);
+  lines.push(`  Created:    ${world.metadata.created_at || "\u2014"}`);
+  lines.push(`  Modified:   ${world.metadata.last_modified || "\u2014"}`);
+  lines.push(`  Authoring:  ${world.metadata.authoring_method}`);
+  lines.push("");
+  lines.push("COMPONENTS");
+  lines.push("\u2500".repeat(40));
+  lines.push(`  Invariants:  ${world.invariants.length}`);
+  lines.push(`  Guards:      ${world.guards?.guards.length ?? 0}`);
+  lines.push(`  Rules:       ${world.rules.length}`);
+  lines.push(`  Roles:       ${world.roles?.roles.length ?? 0}`);
+  if (world.kernel) {
+    const k = world.kernel;
+    const totalRules = (k.input_boundaries?.forbidden_patterns?.length ?? 0) + (k.output_boundaries?.forbidden_patterns?.length ?? 0);
+    lines.push(`  Kernel:      ${totalRules} rules`);
+  }
+  lines.push("");
+  lines.push("HEALTH");
+  lines.push("\u2500".repeat(40));
+  const sev = report.summary;
+  const healthIcon = sev.errors === 0 && sev.warnings === 0 ? "HEALTHY" : sev.errors > 0 ? "ISSUES FOUND" : "WARNINGS";
+  lines.push(`  Status:    ${healthIcon}`);
+  lines.push(`  Errors:    ${sev.errors}`);
+  lines.push(`  Warnings:  ${sev.warnings}`);
+  lines.push(`  Info:      ${sev.info}`);
+  if (report.findings.length > 0) {
+    lines.push("");
+    lines.push("  Top findings:");
+    for (const f of report.findings.slice(0, 5)) {
+      const icon = f.severity === "error" ? "!" : f.severity === "warning" ? "?" : "-";
+      lines.push(`    [${icon}] ${f.message}`);
+    }
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+}
+async function worldDiff(path1, path2, json) {
+  const world1 = await loadWorld(path1);
+  const world2 = await loadWorld(path2);
+  const diff = computeWorldDiff(world1, world2);
+  if (json) {
+    process.stdout.write(JSON.stringify(diff, null, 2) + "\n");
+    return;
+  }
+  const lines = [];
+  lines.push("WORLD DIFF");
+  lines.push("\u2550".repeat(50));
+  lines.push(`  A: ${world1.world.name} v${world1.world.version}`);
+  lines.push(`  B: ${world2.world.name} v${world2.world.version}`);
+  lines.push("");
+  for (const change of diff.changes) {
+    const icon = change.type === "added" ? "+" : change.type === "removed" ? "-" : "~";
+    lines.push(`  [${icon}] ${change.component}: ${change.description}`);
+  }
+  if (diff.changes.length === 0) {
+    lines.push("  No differences found.");
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+}
+function computeWorldDiff(a, b) {
+  const changes = [];
+  if (a.world.version !== b.world.version) {
+    changes.push({ type: "changed", component: "version", description: `${a.world.version} \u2192 ${b.world.version}` });
+  }
+  const aInvIds = new Set(a.invariants.map((i) => i.id));
+  const bInvIds = new Set(b.invariants.map((i) => i.id));
+  for (const id of bInvIds) {
+    if (!aInvIds.has(id)) changes.push({ type: "added", component: "invariant", description: id });
+  }
+  for (const id of aInvIds) {
+    if (!bInvIds.has(id)) changes.push({ type: "removed", component: "invariant", description: id });
+  }
+  const aGuardIds = new Set((a.guards?.guards ?? []).map((g) => g.id));
+  const bGuardIds = new Set((b.guards?.guards ?? []).map((g) => g.id));
+  for (const id of bGuardIds) {
+    if (!aGuardIds.has(id)) changes.push({ type: "added", component: "guard", description: id });
+  }
+  for (const id of aGuardIds) {
+    if (!bGuardIds.has(id)) changes.push({ type: "removed", component: "guard", description: id });
+  }
+  const aRuleIds = new Set(a.rules.map((r) => r.id));
+  const bRuleIds = new Set(b.rules.map((r) => r.id));
+  for (const id of bRuleIds) {
+    if (!aRuleIds.has(id)) changes.push({ type: "added", component: "rule", description: id });
+  }
+  for (const id of aRuleIds) {
+    if (!bRuleIds.has(id)) changes.push({ type: "removed", component: "rule", description: id });
+  }
+  const aRoleIds = new Set((a.roles?.roles ?? []).map((r) => r.id));
+  const bRoleIds = new Set((b.roles?.roles ?? []).map((r) => r.id));
+  for (const id of bRoleIds) {
+    if (!aRoleIds.has(id)) changes.push({ type: "added", component: "role", description: id });
+  }
+  for (const id of aRoleIds) {
+    if (!bRoleIds.has(id)) changes.push({ type: "removed", component: "role", description: id });
+  }
+  const aGuardCount = a.guards?.guards.length ?? 0;
+  const bGuardCount = b.guards?.guards.length ?? 0;
+  if (aGuardCount !== bGuardCount && changes.filter((c) => c.component === "guard").length === 0) {
+    changes.push({ type: "changed", component: "guards", description: `${aGuardCount} \u2192 ${bGuardCount}` });
+  }
+  return { changes };
+}
+async function worldSnapshot(worldPath) {
+  const { readdir, readFile, mkdir, writeFile } = await import("fs/promises");
+  const { join } = await import("path");
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const snapshotDir = join(worldPath, ".snapshots", timestamp);
+  await mkdir(snapshotDir, { recursive: true });
+  const files = await readdir(worldPath);
+  let copied = 0;
+  for (const file of files) {
+    if (file.endsWith(".json")) {
+      const content = await readFile(join(worldPath, file), "utf-8");
+      await writeFile(join(snapshotDir, file), content, "utf-8");
+      copied++;
+    }
+  }
+  try {
+    const rulesDir = join(worldPath, "rules");
+    const ruleFiles = await readdir(rulesDir);
+    await mkdir(join(snapshotDir, "rules"), { recursive: true });
+    for (const file of ruleFiles) {
+      if (file.endsWith(".json")) {
+        const content = await readFile(join(rulesDir, file), "utf-8");
+        await writeFile(join(snapshotDir, "rules", file), content, "utf-8");
+        copied++;
+      }
+    }
+  } catch {
+  }
+  process.stdout.write(`Snapshot saved: ${snapshotDir}
+`);
+  process.stdout.write(`Files: ${copied}
+`);
+}
+async function worldRollback(worldPath) {
+  const { readdir, readFile, writeFile, mkdir } = await import("fs/promises");
+  const { join } = await import("path");
+  const snapshotsDir = join(worldPath, ".snapshots");
+  let snapshots;
+  try {
+    snapshots = (await readdir(snapshotsDir)).sort();
+  } catch {
+    process.stderr.write("No snapshots found. Run `neuroverse world snapshot` first.\n");
+    process.exit(1);
+    return;
+  }
+  if (snapshots.length === 0) {
+    process.stderr.write("No snapshots found. Run `neuroverse world snapshot` first.\n");
+    process.exit(1);
+    return;
+  }
+  const latest = snapshots[snapshots.length - 1];
+  const snapshotDir = join(snapshotsDir, latest);
+  const backupTimestamp = "pre-rollback-" + (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const backupDir = join(snapshotsDir, backupTimestamp);
+  await mkdir(backupDir, { recursive: true });
+  const currentFiles = await readdir(worldPath);
+  for (const file of currentFiles) {
+    if (file.endsWith(".json")) {
+      const content = await readFile(join(worldPath, file), "utf-8");
+      await writeFile(join(backupDir, file), content, "utf-8");
+    }
+  }
+  const snapshotFiles = await readdir(snapshotDir);
+  let restored = 0;
+  for (const file of snapshotFiles) {
+    if (file.endsWith(".json")) {
+      const content = await readFile(join(snapshotDir, file), "utf-8");
+      await writeFile(join(worldPath, file), content, "utf-8");
+      restored++;
+    }
+  }
+  try {
+    const rulesDir = join(snapshotDir, "rules");
+    const ruleFiles = await readdir(rulesDir);
+    await mkdir(join(worldPath, "rules"), { recursive: true });
+    for (const file of ruleFiles) {
+      if (file.endsWith(".json")) {
+        const content = await readFile(join(rulesDir, file), "utf-8");
+        await writeFile(join(worldPath, "rules", file), content, "utf-8");
+        restored++;
+      }
+    }
+  } catch {
+  }
+  process.stdout.write(`Rolled back to: ${latest}
+`);
+  process.stdout.write(`Restored: ${restored} files
+`);
+  process.stdout.write(`Backup saved: ${backupDir}
+`);
+}
+function worldList(json) {
+  const worlds = listWorlds();
+  if (json) {
+    process.stdout.write(JSON.stringify({ worlds, activeWorld: getActiveWorldName() }, null, 2) + "\n");
+    return;
+  }
+  if (worlds.length === 0) {
+    process.stdout.write("No worlds found.\n");
+    process.stdout.write("Run `neuroverse build <input.md>` to create one.\n");
+    return;
+  }
+  const lines = [];
+  lines.push("AVAILABLE WORLDS");
+  lines.push("\u2500".repeat(40));
+  for (const w of worlds) {
+    const marker = w.active ? "\u2192" : " ";
+    const activeLabel = w.active ? " (active)" : "";
+    lines.push(`  ${marker} ${w.name}${activeLabel}`);
+  }
+  const envWorld = process.env.NEUROVERSE_WORLD;
+  if (envWorld) {
+    lines.push("");
+    lines.push(`  env: NEUROVERSE_WORLD=${envWorld}`);
+  }
+  lines.push("");
+  lines.push("Switch: neuroverse world use <name>");
+  process.stdout.write(lines.join("\n") + "\n");
+}
+function worldUse(name) {
+  setActiveWorld(name);
+  process.stdout.write(`Active world: ${name}
+`);
+}
+function worldCurrent(json) {
+  const info = describeActiveWorld();
+  if (json) {
+    process.stdout.write(JSON.stringify(info ?? { name: null, source: null }, null, 2) + "\n");
+    return;
+  }
+  if (!info) {
+    process.stdout.write("No active world.\n");
+    process.stdout.write("Set one with: neuroverse world use <name>\n");
+    return;
+  }
+  process.stdout.write(`Active world: ${info.name}
+`);
+  process.stdout.write(`Source: ${info.source}
+`);
+}
+async function main(argv = process.argv.slice(2)) {
+  const { subcommand, paths, flags } = parseArgs(argv);
+  if (flags.help || !subcommand) {
+    process.stdout.write(USAGE + "\n");
+    process.exit(0);
+  }
+  switch (subcommand) {
+    case "list":
+    case "ls": {
+      return worldList(!!flags.json);
+    }
+    case "use": {
+      if (!paths[0]) {
+        process.stderr.write("Usage: neuroverse world use <name>\n");
+        process.exit(1);
+      }
+      return worldUse(paths[0]);
+    }
+    case "current": {
+      return worldCurrent(!!flags.json);
+    }
+    case "status": {
+      const ref = paths[0];
+      const resolved = ref ? resolveWorldPath(ref) : resolveWorldPath();
+      if (!resolved) {
+        process.stderr.write("Usage: neuroverse world status <path|name>\n");
+        process.stderr.write("Or set an active world: neuroverse world use <name>\n");
+        process.exit(1);
+      }
+      return worldStatus(resolved, !!flags.json);
+    }
+    case "diff": {
+      if (!paths[0] || !paths[1]) {
+        process.stderr.write("Usage: neuroverse world diff <path1> <path2>\n");
+        process.exit(1);
+      }
+      return worldDiff(paths[0], paths[1], !!flags.json);
+    }
+    case "snapshot": {
+      if (!paths[0]) {
+        process.stderr.write("Usage: neuroverse world snapshot <path>\n");
+        process.exit(1);
+      }
+      return worldSnapshot(paths[0]);
+    }
+    case "rollback": {
+      if (!paths[0]) {
+        process.stderr.write("Usage: neuroverse world rollback <path>\n");
+        process.exit(1);
+      }
+      return worldRollback(paths[0]);
+    }
+    default: {
+      process.stderr.write(`Unknown world subcommand: "${subcommand}"
+
+`);
+      process.stdout.write(USAGE + "\n");
+      process.exit(1);
+    }
+  }
+}
+export {
+  main
+};

package/dist/world-loader-Y6HMQH2D.js

@@ -0,0 +1,13 @@
+import {
+  DEFAULT_BUNDLED_WORLD,
+  loadBundledWorld,
+  loadWorld,
+  loadWorldFromDirectory
+} from "./chunk-CTZHONLA.js";
+import "./chunk-QWGCMQQD.js";
+export {
+  DEFAULT_BUNDLED_WORLD,
+  loadBundledWorld,
+  loadWorld,
+  loadWorldFromDirectory
+};

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