@neuroverseos/governance 0.3.1 → 0.3.3

package/dist/build-QKOBBC23.js

@@ -0,0 +1,341 @@
+import {
+  DeriveInputError,
+  DeriveProviderError,
+  deriveWorld
+} from "./chunk-6S5CFQXY.js";
+import {
+  DERIVE_EXIT_CODES
+} from "./chunk-Q6O7ZLO2.js";
+import "./chunk-OT6PXH54.js";
+import "./chunk-7P3S7MAY.js";
+import {
+  parseWorldMarkdown
+} from "./chunk-EMQDLDAF.js";
+import {
+  emitWorldDefinition
+} from "./chunk-PVTQQS3Y.js";
+import "./chunk-QWGCMQQD.js";
+
+// src/cli/build.ts
+var FINDING_LABELS = {
+  "guard-coverage": "STORY INSIGHT",
+  "semantic-tension": "DRAMATIC TENSION",
+  "orphan": "MISSING CAUSALITY",
+  "contradiction": "CONFLICT DETECTED",
+  "referential-integrity": "BROKEN REFERENCE",
+  "completeness": "INCOMPLETE STRUCTURE",
+  "schema-violation": "VALUE OUT OF RANGE"
+};
+function humanLabel(section) {
+  const category = section.replace(/^Validate:/, "");
+  return FINDING_LABELS[category] ?? section.toUpperCase();
+}
+function traceCausalChains(rules) {
+  const effectToTrigger = /* @__PURE__ */ new Map();
+  for (const rule of rules) {
+    for (const trigger of rule.triggers) {
+      if (!effectToTrigger.has(trigger.field)) effectToTrigger.set(trigger.field, /* @__PURE__ */ new Set());
+      effectToTrigger.get(trigger.field).add(rule.id);
+    }
+  }
+  const chains = [];
+  const ruleById = new Map(rules.map((r) => [r.id, r]));
+  for (const startRule of rules) {
+    const chain = [startRule.effects[0]?.target].filter(Boolean);
+    if (chain.length === 0) continue;
+    const visited = /* @__PURE__ */ new Set([startRule.id]);
+    let current = startRule;
+    for (let depth = 0; depth < 5; depth++) {
+      const lastTarget = current.effects[0]?.target;
+      if (!lastTarget) break;
+      const triggeredRuleIds = effectToTrigger.get(lastTarget);
+      if (!triggeredRuleIds) break;
+      let nextRule;
+      for (const id of triggeredRuleIds) {
+        if (!visited.has(id)) {
+          nextRule = ruleById.get(id);
+          break;
+        }
+      }
+      if (!nextRule) break;
+      visited.add(nextRule.id);
+      const nextTarget = nextRule.effects[0]?.target;
+      if (nextTarget && !chain.includes(nextTarget)) {
+        chain.push(nextTarget);
+      }
+      current = nextRule;
+    }
+    if (chain.length >= 2) {
+      chains.push(chain);
+    }
+  }
+  const sorted = chains.sort((a, b) => b.length - a.length);
+  const unique = [];
+  for (const chain of sorted) {
+    const key = chain.join(" -> ");
+    const isSubset = unique.some((existing) => existing.join(" -> ").includes(key));
+    if (!isSubset) unique.push(chain);
+  }
+  return unique.slice(0, 3);
+}
+function renderGovernanceHealth(health) {
+  const lines = [];
+  lines.push("GOVERNANCE HEALTH");
+  lines.push(`  Coverage: ${health.surfacesCovered} / ${health.surfacesTotal} action surfaces governed`);
+  lines.push(`  Invariants enforced: ${health.invariantsEnforced} / ${health.invariantsTotal}`);
+  if (health.shadowedGuards > 0) {
+    lines.push(`  Shadowed guards: ${health.shadowedGuards}`);
+  }
+  if (health.unenforcedInvariants > 0) {
+    lines.push(`  Unenforced invariants: ${health.unenforcedInvariants}`);
+  }
+  if (health.unreachableRules > 0) {
+    lines.push(`  Unreachable rules: ${health.unreachableRules}`);
+  }
+  if (health.incompleteStateCoverage > 0) {
+    lines.push(`  Incomplete state coverage: ${health.incompleteStateCoverage}`);
+  }
+  if (health.surfaces.length > 0) {
+    lines.push("");
+    lines.push("  Surfaces:");
+    for (const s of health.surfaces) {
+      lines.push(`    ${s.name}: ${s.governed ? "governed" : "unguarded"}`);
+    }
+  }
+  lines.push("");
+  lines.push(`  Risk level: ${health.riskLevel.charAt(0).toUpperCase() + health.riskLevel.slice(1)}`);
+  return lines.join("\n");
+}
+function parseArgs(argv) {
+  let inputPath = "";
+  let outputDir;
+  let validate = true;
+  let dryRun = false;
+  let provider;
+  let model;
+  let endpoint;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--output" && i + 1 < argv.length) {
+      outputDir = argv[++i];
+    } else if (arg === "--no-validate") {
+      validate = false;
+    } else if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg === "--provider" && i + 1 < argv.length) {
+      provider = argv[++i];
+    } else if (arg === "--model" && i + 1 < argv.length) {
+      model = argv[++i];
+    } else if (arg === "--endpoint" && i + 1 < argv.length) {
+      endpoint = argv[++i];
+    } else if (!arg.startsWith("--") && !inputPath) {
+      inputPath = arg;
+    }
+  }
+  if (!inputPath) throw new DeriveInputError("Usage: neuroverse build <input.md> [--output <dir>]");
+  return { inputPath, outputDir, validate, dryRun, provider, model, endpoint };
+}
+async function writeWorldFiles(outputDir, world) {
+  const { writeFile, mkdir } = await import("fs/promises");
+  const { join } = await import("path");
+  await mkdir(outputDir, { recursive: true });
+  await writeFile(join(outputDir, "world.json"), JSON.stringify(world.world, null, 2));
+  await writeFile(join(outputDir, "invariants.json"), JSON.stringify({ invariants: world.invariants }, null, 2));
+  await writeFile(join(outputDir, "assumptions.json"), JSON.stringify(world.assumptions, null, 2));
+  await writeFile(join(outputDir, "state-schema.json"), JSON.stringify(world.stateSchema, null, 2));
+  await writeFile(join(outputDir, "gates.json"), JSON.stringify(world.gates, null, 2));
+  await writeFile(join(outputDir, "outcomes.json"), JSON.stringify(world.outcomes, null, 2));
+  await writeFile(join(outputDir, "metadata.json"), JSON.stringify(world.metadata, null, 2));
+  const rulesDir = join(outputDir, "rules");
+  await mkdir(rulesDir, { recursive: true });
+  const sortedRules = [...world.rules].sort((a, b) => a.order - b.order);
+  for (let i = 0; i < sortedRules.length; i++) {
+    const ruleNum = String(i + 1).padStart(3, "0");
+    await writeFile(join(rulesDir, `rule-${ruleNum}.json`), JSON.stringify(sortedRules[i], null, 2));
+  }
+}
+function write(msg) {
+  process.stderr.write(msg);
+}
+function printInsight(finding) {
+  const label = humanLabel(finding.section);
+  const icon = finding.severity === "error" ? "x" : "!";
+  write(`  ${icon} ${label}: ${finding.message}
+`);
+}
+async function main(argv = process.argv.slice(2)) {
+  try {
+    const args = parseArgs(argv);
+    const { basename } = await import("path");
+    write(`
+NeuroVerse World Builder
+`);
+    write(`
+Analyzing: ${basename(args.inputPath)}
+`);
+    const derivedPath = args.outputDir ? `${args.outputDir}/source.nv-world.md` : ".neuroverse/build-output.nv-world.md";
+    const { mkdir } = await import("fs/promises");
+    const { dirname } = await import("path");
+    await mkdir(dirname(derivedPath), { recursive: true });
+    const { result, exitCode, dryRunOutput } = await deriveWorld({
+      inputPath: args.inputPath,
+      outputPath: derivedPath,
+      validate: args.validate,
+      dryRun: args.dryRun,
+      providerOverride: args.provider || args.model || args.endpoint ? { provider: args.provider, model: args.model, endpoint: args.endpoint } : void 0
+    });
+    if (dryRunOutput) {
+      process.stdout.write(JSON.stringify({
+        dryRun: true,
+        systemPrompt: dryRunOutput.systemPrompt,
+        userPrompt: dryRunOutput.userPrompt,
+        durationMs: result.durationMs
+      }, null, 2) + "\n");
+      process.exit(DERIVE_EXIT_CODES.SUCCESS);
+      return;
+    }
+    const { readFile } = await import("fs/promises");
+    const derivedContent = await readFile(derivedPath, "utf-8");
+    const parseResult = parseWorldMarkdown(derivedContent);
+    const worldName = parseResult.world?.frontmatter?.name ?? "Derived World";
+    const worldId = parseResult.world?.frontmatter?.world_id ?? "derived_world";
+    const thesis = parseResult.world?.thesis ?? "";
+    write(`
+World: ${worldName}
+`);
+    if (thesis) {
+      const firstLine = thesis.split(/[.\n]/)[0].trim();
+      if (firstLine) write(`Theme: ${firstLine}
+`);
+    }
+    const parsedRules = parseResult.world?.rules ?? [];
+    if (parsedRules.length > 0) {
+      const chains = traceCausalChains(parsedRules);
+      if (chains.length > 0) {
+        write(`
+Core dynamics:
+`);
+        for (const chain of chains) {
+          write(`  ${chain.join(" -> ")}
+`);
+        }
+      }
+    }
+    write(`
+Structure:
+`);
+    const sectionLabels = {
+      frontmatter: "Metadata",
+      thesis: "Thesis",
+      invariants: "Invariants",
+      state: "State variables",
+      assumptions: "Assumptions",
+      rules: "Rules",
+      gates: "Gates",
+      outcomes: "Outcomes"
+    };
+    for (const [key, label] of Object.entries(sectionLabels)) {
+      if (result.sectionsDetected.includes(key)) {
+        const val = parseResult.world?.[key];
+        const count = Array.isArray(val) ? ` (${val.length})` : "";
+        write(`  + ${label}${count}
+`);
+      }
+    }
+    if (result.normalization) {
+      const n = result.normalization;
+      write(`
+Auto-corrections: ${n.fixCount}
+`);
+      if (n.invariantIds > 0) write(`  - ${n.invariantIds} invariant ID(s) formatted
+`);
+      if (n.gateThresholds > 0) write(`  - ${n.gateThresholds} gate threshold(s) converted
+`);
+      if (n.triggerTags > 0) write(`  - ${n.triggerTags} trigger(s) tagged
+`);
+    }
+    const errors = result.findings.filter((f) => f.severity === "error");
+    const warnings = result.findings.filter((f) => f.severity === "warning");
+    if (warnings.length > 0) {
+      write(`
+Insights:
+`);
+      for (const w of warnings) printInsight(w);
+    }
+    if (errors.length > 0) {
+      write(`
+Issues:
+`);
+      for (const e of errors) printInsight(e);
+    }
+    if (exitCode !== 0 || !parseResult.world) {
+      write(`
+World source written to: ${derivedPath}
+`);
+      write(`Fix the issues above, then run: neuroverse build ${derivedPath}
+
+`);
+      process.exit(exitCode);
+      return;
+    }
+    const outputDir = args.outputDir ?? `.neuroverse/worlds/${worldId}`;
+    try {
+      const emitResult = emitWorldDefinition(parseResult.world);
+      await writeWorldFiles(outputDir, emitResult.world);
+      const { join } = await import("path");
+      const { copyFile } = await import("fs/promises");
+      const sourceDest = join(outputDir, "source.nv-world.md");
+      if (derivedPath !== sourceDest) {
+        await copyFile(derivedPath, sourceDest);
+      }
+      write(`
+World ready: ${worldId}
+`);
+      write(`  ${outputDir}/
+`);
+    } catch (bootstrapError) {
+      write(`
+World source written to: ${derivedPath}
+`);
+      write(`Bootstrap failed: ${bootstrapError instanceof Error ? bootstrapError.message : String(bootstrapError)}
+`);
+      write(`Run: neuroverse bootstrap --input ${derivedPath} --output <dir>
+
+`);
+      process.exit(1);
+      return;
+    }
+    write(`
+Next steps:
+`);
+    write(`  Explore    neuroverse explain ${worldId}
+`);
+    write(`  Simulate   neuroverse simulate ${worldId}
+`);
+    write(`  Improve    neuroverse improve ${worldId}
+`);
+    write(`
+`);
+    process.exit(0);
+  } catch (e) {
+    if (e instanceof DeriveInputError) {
+      process.stderr.write(`Input error: ${e.message}
+`);
+      process.exit(DERIVE_EXIT_CODES.INPUT_ERROR);
+    } else if (e instanceof DeriveProviderError) {
+      process.stderr.write(`Provider error: ${e.message}
+`);
+      process.exit(DERIVE_EXIT_CODES.PROVIDER_ERROR);
+    } else {
+      process.stderr.write(`Build failed: ${e instanceof Error ? e.message : String(e)}
+`);
+      process.exit(DERIVE_EXIT_CODES.PROVIDER_ERROR);
+    }
+  }
+}
+export {
+  humanLabel,
+  main,
+  renderGovernanceHealth,
+  traceCausalChains
+};

package/dist/chunk-3WQLXYTP.js

@@ -0,0 +1,91 @@
+import {
+  GovernanceBlockedError,
+  buildEngineOptions,
+  extractScope,
+  trackPlanProgress
+} from "./chunk-5U2MQO5P.js";
+import {
+  evaluateGuard
+} from "./chunk-W7LLXRGY.js";
+import {
+  loadWorld
+} from "./chunk-CTZHONLA.js";
+
+// src/adapters/langchain.ts
+var GovernanceBlockedError2 = class extends GovernanceBlockedError {
+  event;
+  constructor(verdict, event) {
+    super(verdict);
+    this.event = event;
+  }
+};
+function defaultMapToolCall(toolName, toolInput) {
+  return {
+    intent: toolName,
+    tool: toolName,
+    scope: extractScope(toolInput),
+    args: toolInput,
+    direction: "input"
+  };
+}
+var NeuroVerseCallbackHandler = class {
+  name = "NeuroVerseGovernance";
+  world;
+  options;
+  engineOptions;
+  mapToolCall;
+  activePlan;
+  constructor(world, options = {}) {
+    this.world = world;
+    this.options = options;
+    this.activePlan = options.plan;
+    this.engineOptions = buildEngineOptions(options, this.activePlan);
+    this.mapToolCall = options.mapToolCall ?? defaultMapToolCall;
+  }
+  /**
+   * Called before a tool is executed.
+   * Evaluates the tool call against the governance world.
+   *
+   * @throws GovernanceBlockedError if the action is BLOCKED
+   * @throws GovernanceBlockedError if the action is PAUSED and onPause returns false
+   */
+  async handleToolStart(tool, input) {
+    let parsedInput;
+    try {
+      parsedInput = typeof input === "string" ? JSON.parse(input) : input;
+    } catch {
+      parsedInput = { raw: input };
+    }
+    const event = this.mapToolCall(tool.name, parsedInput);
+    this.engineOptions.plan = this.activePlan;
+    const verdict = evaluateGuard(event, this.world, this.engineOptions);
+    this.options.onEvaluate?.(verdict, event);
+    if (verdict.status === "BLOCK") {
+      this.options.onBlock?.(verdict, event);
+      throw new GovernanceBlockedError2(verdict, event);
+    }
+    if (verdict.status === "PAUSE") {
+      const approved = await this.options.onPause?.(verdict, event);
+      if (!approved) {
+        throw new GovernanceBlockedError2(verdict, event);
+      }
+    }
+    if (verdict.status === "ALLOW") {
+      trackPlanProgress(event, this, this.options);
+    }
+  }
+};
+async function createNeuroVerseCallbackHandler(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return new NeuroVerseCallbackHandler(world, options);
+}
+function createNeuroVerseCallbackHandlerFromWorld(world, options) {
+  return new NeuroVerseCallbackHandler(world, options);
+}
+
+export {
+  GovernanceBlockedError2 as GovernanceBlockedError,
+  NeuroVerseCallbackHandler,
+  createNeuroVerseCallbackHandler,
+  createNeuroVerseCallbackHandlerFromWorld
+};

package/dist/chunk-4FLICVVA.js

@@ -0,0 +1,119 @@
+import {
+  GovernanceBlockedError,
+  buildEngineOptions,
+  defaultBlockMessage,
+  extractScope,
+  trackPlanProgress
+} from "./chunk-5U2MQO5P.js";
+import {
+  evaluateGuard
+} from "./chunk-W7LLXRGY.js";
+import {
+  loadWorld
+} from "./chunk-CTZHONLA.js";
+
+// src/adapters/openai.ts
+var GovernanceBlockedError2 = class extends GovernanceBlockedError {
+  toolCallId;
+  constructor(verdict, toolCallId) {
+    super(verdict);
+    this.toolCallId = toolCallId;
+  }
+};
+function defaultMapFunctionCall(name, args) {
+  return {
+    intent: name,
+    tool: name,
+    scope: extractScope(args),
+    args,
+    direction: "input"
+  };
+}
+var GovernedToolExecutor = class {
+  world;
+  options;
+  engineOptions;
+  mapFn;
+  blockMsg;
+  activePlan;
+  constructor(world, options = {}) {
+    this.world = world;
+    this.options = options;
+    this.activePlan = options.plan;
+    this.engineOptions = buildEngineOptions(options, this.activePlan);
+    this.mapFn = options.mapFunctionCall ?? defaultMapFunctionCall;
+    this.blockMsg = options.blockMessage ?? defaultBlockMessage;
+  }
+  /**
+   * Evaluate a single tool call against governance rules.
+   * Returns the verdict without executing the tool.
+   */
+  evaluate(toolCall) {
+    let args;
+    try {
+      args = JSON.parse(toolCall.function.arguments);
+    } catch {
+      args = { raw: toolCall.function.arguments };
+    }
+    const event = this.mapFn(toolCall.function.name, args);
+    this.engineOptions.plan = this.activePlan;
+    const verdict = evaluateGuard(event, this.world, this.engineOptions);
+    this.options.onEvaluate?.(verdict, event);
+    if (verdict.status === "ALLOW") {
+      trackPlanProgress(event, this, this.options);
+    }
+    return verdict;
+  }
+  /**
+   * Execute a tool call with governance enforcement.
+   *
+   * If ALLOW: runs the tool and returns the result.
+   * If BLOCK: returns a blocked message (no execution).
+   * If PAUSE: throws — caller must handle approval flow.
+   *
+   * @param toolCall - The OpenAI tool call to evaluate
+   * @param runner - The actual tool execution function
+   * @returns A tool result message ready for the OpenAI API
+   */
+  async execute(toolCall, runner) {
+    const verdict = this.evaluate(toolCall);
+    if (verdict.status === "BLOCK") {
+      return {
+        tool_call_id: toolCall.id,
+        role: "tool",
+        content: this.blockMsg(verdict),
+        _verdict: verdict
+      };
+    }
+    if (verdict.status === "PAUSE") {
+      throw new GovernanceBlockedError2(verdict, toolCall.id);
+    }
+    let args;
+    try {
+      args = JSON.parse(toolCall.function.arguments);
+    } catch {
+      args = { raw: toolCall.function.arguments };
+    }
+    const content = await runner(toolCall.function.name, args);
+    return {
+      tool_call_id: toolCall.id,
+      role: "tool",
+      content,
+      _verdict: verdict
+    };
+  }
+};
+async function createGovernedToolExecutor(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return new GovernedToolExecutor(world, options);
+}
+function createGovernedToolExecutorFromWorld(world, options) {
+  return new GovernedToolExecutor(world, options);
+}
+
+export {
+  GovernanceBlockedError2 as GovernanceBlockedError,
+  GovernedToolExecutor,
+  createGovernedToolExecutor,
+  createGovernedToolExecutorFromWorld
+};

package/dist/chunk-4NGDRRQH.js

@@ -0,0 +1,10 @@
+// src/contracts/bootstrap-contract.ts
+var BOOTSTRAP_EXIT_CODES = {
+  SUCCESS: 0,
+  FAIL: 1,
+  ERROR: 3
+};
+
+export {
+  BOOTSTRAP_EXIT_CODES
+};