@neuroverseos/governance 0.1.0 → 0.1.2

package/dist/chunk-BUWWN2NX.js

@@ -0,0 +1,192 @@
+// src/engine/explain-engine.ts
+function detectTensions(rules) {
+  const increases = /* @__PURE__ */ new Map();
+  const decreases = /* @__PURE__ */ new Map();
+  for (const rule of rules) {
+    const allEffects = collectAllEffects(rule);
+    for (const effect of allEffects) {
+      const target = effect.target;
+      const isIncrease = effect.operation === "add" || effect.operation === "multiply" && typeof effect.value === "number" && effect.value > 1;
+      const isDecrease = effect.operation === "subtract" || effect.operation === "multiply" && typeof effect.value === "number" && effect.value < 1;
+      if (isIncrease) {
+        if (!increases.has(target)) increases.set(target, []);
+        increases.get(target).push(rule.label);
+      }
+      if (isDecrease) {
+        if (!decreases.has(target)) decreases.set(target, []);
+        decreases.get(target).push(rule.label);
+      }
+    }
+  }
+  const tensions = [];
+  for (const [variable, incRules] of increases) {
+    const decRules = decreases.get(variable);
+    if (decRules && decRules.length > 0) {
+      tensions.push({
+        variable,
+        increasedBy: incRules,
+        decreasedBy: decRules
+      });
+    }
+  }
+  return tensions;
+}
+function collectAllEffects(rule) {
+  const effects = [...rule.effects ?? []];
+  for (const ce of rule.effects_conditional ?? []) {
+    effects.push(...ce.effects);
+  }
+  return effects;
+}
+function explainWorld(world) {
+  const dynamics = [...world.rules].sort((a, b) => a.order - b.order).map((rule) => {
+    const allEffects = collectAllEffects(rule);
+    return {
+      ruleId: rule.id,
+      label: rule.label,
+      severity: rule.severity,
+      triggerDescription: rule.causal_translation?.trigger_text ?? describeTriggers(rule),
+      effectDescription: rule.causal_translation?.effect_text ?? describeEffects(allEffects),
+      targets: [...new Set(allEffects.map((e) => e.target))]
+    };
+  });
+  const stateVariables = Object.entries(world.stateSchema.variables ?? {}).map(
+    ([name, v]) => ({
+      name,
+      label: v.label || name,
+      type: v.type,
+      defaultValue: v.default,
+      range: v.type === "number" && v.min !== void 0 && v.max !== void 0 ? `${v.min}\u2013${v.max}` : v.type === "enum" && v.options ? v.options.join(", ") : void 0
+    })
+  );
+  const invariants = world.invariants.map((inv) => ({
+    id: inv.id,
+    label: inv.label,
+    enforcement: inv.enforcement
+  }));
+  const gates = (world.gates.viability_classification ?? []).map((g) => ({
+    status: g.status,
+    field: g.field,
+    threshold: `${g.operator} ${g.value}`
+  }));
+  const tensions = detectTensions(world.rules);
+  const outcomes = (world.outcomes.computed_outcomes ?? []).map((o) => ({
+    id: o.id,
+    label: o.label,
+    type: o.type,
+    primary: o.primary ?? false
+  }));
+  const stats = {
+    invariants: world.invariants.length,
+    stateVariables: Object.keys(world.stateSchema.variables ?? {}).length,
+    rules: world.rules.length,
+    gates: (world.gates.viability_classification ?? []).length,
+    outcomes: (world.outcomes.computed_outcomes ?? []).length,
+    assumptions: Object.keys(world.assumptions.profiles ?? {}).length
+  };
+  return {
+    worldName: world.world.name,
+    worldId: world.world.world_id,
+    thesis: world.world.thesis,
+    dynamics,
+    stateVariables,
+    invariants,
+    gates,
+    tensions,
+    outcomes,
+    stats
+  };
+}
+function describeTriggers(rule) {
+  if (!rule.triggers || rule.triggers.length === 0) return "Always active";
+  return rule.triggers.map((t) => `${t.field} ${t.operator} ${t.value}`).join(" AND ");
+}
+function describeEffects(effects) {
+  if (effects.length === 0) return "No direct effects";
+  return effects.map((e) => {
+    switch (e.operation) {
+      case "multiply":
+        return `${e.target} scaled by ${e.value}`;
+      case "add":
+        return `${e.target} increased by ${e.value}`;
+      case "subtract":
+        return `${e.target} decreased by ${e.value}`;
+      case "set":
+        return `${e.target} set to ${e.value}`;
+      case "set_boolean":
+        return `${e.target} set to ${e.value}`;
+      default:
+        return `${e.target} ${e.operation} ${e.value}`;
+    }
+  }).join("; ");
+}
+function renderExplainText(output) {
+  const lines = [];
+  lines.push(`WORLD: ${output.worldName}`);
+  lines.push(`ID: ${output.worldId}`);
+  lines.push("");
+  if (output.thesis) {
+    lines.push("THESIS");
+    lines.push(`  ${output.thesis}`);
+    lines.push("");
+  }
+  lines.push("STRUCTURE");
+  lines.push(`  ${output.stats.invariants} invariants, ${output.stats.stateVariables} state variables, ${output.stats.rules} rules`);
+  lines.push(`  ${output.stats.gates} viability gates, ${output.stats.outcomes} outcomes, ${output.stats.assumptions} assumption profiles`);
+  lines.push("");
+  if (output.dynamics.length > 0) {
+    lines.push("KEY DYNAMICS");
+    for (const d of output.dynamics) {
+      const severity = d.severity === "structural" ? "[structural]" : d.severity === "advantage" ? "[advantage]" : "[degradation]";
+      lines.push(`  ${d.label} ${severity}`);
+      lines.push(`    When: ${d.triggerDescription}`);
+      lines.push(`    Then: ${d.effectDescription}`);
+    }
+    lines.push("");
+  }
+  if (output.tensions.length > 0) {
+    lines.push("DRAMATIC TENSIONS");
+    for (const t of output.tensions) {
+      lines.push(`  ${t.variable}:`);
+      lines.push(`    Increased by: ${t.increasedBy.join(", ")}`);
+      lines.push(`    Decreased by: ${t.decreasedBy.join(", ")}`);
+    }
+    lines.push("");
+  }
+  if (output.stateVariables.length > 0) {
+    lines.push("STATE VARIABLES");
+    for (const v of output.stateVariables) {
+      const range = v.range ? ` (${v.range})` : "";
+      lines.push(`  ${v.label}: ${v.type}, default ${v.defaultValue}${range}`);
+    }
+    lines.push("");
+  }
+  if (output.invariants.length > 0) {
+    lines.push("INVARIANTS (cannot change)");
+    for (const inv of output.invariants) {
+      lines.push(`  ${inv.label} [${inv.enforcement}]`);
+    }
+    lines.push("");
+  }
+  if (output.gates.length > 0) {
+    lines.push("VIABILITY GATES");
+    for (const g of output.gates) {
+      lines.push(`  ${g.status}: ${g.field} ${g.threshold}`);
+    }
+    lines.push("");
+  }
+  if (output.outcomes.length > 0) {
+    lines.push("OUTCOMES");
+    for (const o of output.outcomes) {
+      const primary = o.primary ? " [primary]" : "";
+      lines.push(`  ${o.label} (${o.type})${primary}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+export {
+  explainWorld,
+  renderExplainText
+};

package/dist/chunk-CROPZ75A.js

@@ -0,0 +1,107 @@
+import {
+  evaluateGuard
+} from "./chunk-B4NF3OLW.js";
+import {
+  loadWorld
+} from "./chunk-M3TZFGHO.js";
+
+// src/adapters/openclaw.ts
+var GovernanceBlockedError = class extends Error {
+  verdict;
+  action;
+  constructor(verdict, action) {
+    super(`[NeuroVerse] BLOCKED: ${verdict.reason ?? verdict.ruleId ?? "governance rule"}`);
+    this.name = "GovernanceBlockedError";
+    this.verdict = verdict;
+    this.action = action;
+  }
+};
+function defaultMapAction(action, direction) {
+  return {
+    intent: action.type,
+    tool: action.tool ?? action.type,
+    args: action.input,
+    direction,
+    scope: typeof action.input?.path === "string" ? action.input.path : typeof action.input?.url === "string" ? action.input.url : void 0
+  };
+}
+var NeuroVersePlugin = class {
+  name = "neuroverse-governance";
+  world;
+  options;
+  engineOptions;
+  mapAction;
+  constructor(world, options = {}) {
+    this.world = world;
+    this.options = options;
+    this.engineOptions = {
+      trace: options.trace ?? false,
+      level: options.level
+    };
+    this.mapAction = options.mapAction ?? defaultMapAction;
+  }
+  /**
+   * Evaluate an action before execution.
+   *
+   * @throws GovernanceBlockedError if BLOCKED
+   * @returns HookResult with verdict details
+   */
+  beforeAction(action) {
+    const event = this.mapAction(action, "input");
+    const verdict = evaluateGuard(event, this.world, this.engineOptions);
+    const result = {
+      allowed: verdict.status === "ALLOW",
+      verdict,
+      action
+    };
+    this.options.onEvaluate?.(result);
+    if (verdict.status === "BLOCK") {
+      throw new GovernanceBlockedError(verdict, action);
+    }
+    return result;
+  }
+  /**
+   * Evaluate an action's output (post-execution governance).
+   * Only runs if evaluateOutputs is enabled.
+   *
+   * @returns HookResult or null if output evaluation is disabled
+   */
+  afterAction(action, _output) {
+    if (!this.options.evaluateOutputs) return null;
+    const event = this.mapAction(action, "output");
+    const verdict = evaluateGuard(event, this.world, this.engineOptions);
+    const result = {
+      allowed: verdict.status === "ALLOW",
+      verdict,
+      action
+    };
+    this.options.onEvaluate?.(result);
+    if (verdict.status === "BLOCK") {
+      throw new GovernanceBlockedError(verdict, action);
+    }
+    return result;
+  }
+  /**
+   * Get the plugin hooks object for agent.use().
+   */
+  hooks() {
+    return {
+      beforeAction: (action) => this.beforeAction(action),
+      afterAction: (action, output) => this.afterAction(action, output)
+    };
+  }
+};
+async function createNeuroVersePlugin(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return new NeuroVersePlugin(world, options);
+}
+function createNeuroVersePluginFromWorld(world, options) {
+  return new NeuroVersePlugin(world, options);
+}
+
+export {
+  GovernanceBlockedError,
+  NeuroVersePlugin,
+  createNeuroVersePlugin,
+  createNeuroVersePluginFromWorld
+};