@neuroverseos/governance 0.3.1 → 0.3.3

package/dist/chunk-F66BVUYB.js

@@ -0,0 +1,340 @@
+import {
+  validateWorld
+} from "./chunk-7P3S7MAY.js";
+import {
+  simulateWorld
+} from "./chunk-ZWI3NIXK.js";
+
+// src/engine/improve-engine.ts
+function improveWorld(world) {
+  const suggestions = [];
+  const report = validateWorld(world);
+  addValidationSuggestions(report.findings, suggestions);
+  analyzeRuleBalance(world, suggestions);
+  analyzeStateCoverage(world, suggestions);
+  analyzeGateCoverage(world, suggestions);
+  analyzeAssumptions(world, suggestions);
+  analyzeSimulationDynamics(world, suggestions);
+  analyzeCompleteness(world, suggestions);
+  const seen = /* @__PURE__ */ new Set();
+  const unique = suggestions.filter((s) => {
+    if (seen.has(s.id)) return false;
+    seen.add(s.id);
+    return true;
+  });
+  const priorityOrder = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3
+  };
+  unique.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+  const score = computeHealthScore(world, unique);
+  return {
+    worldId: world.world.world_id,
+    worldName: world.world.name,
+    score,
+    suggestions: unique,
+    stats: {
+      critical: unique.filter((s) => s.priority === "critical").length,
+      high: unique.filter((s) => s.priority === "high").length,
+      medium: unique.filter((s) => s.priority === "medium").length,
+      low: unique.filter((s) => s.priority === "low").length
+    }
+  };
+}
+function addValidationSuggestions(findings, suggestions) {
+  for (const f of findings) {
+    if (f.severity === "info") continue;
+    const priority = f.severity === "error" ? "critical" : "high";
+    const category = f.severity === "error" ? "fix" : "structure";
+    suggestions.push({
+      id: `validate-${f.id}`,
+      priority,
+      category,
+      title: f.message,
+      description: f.message,
+      action: f.suggestion ?? `Review ${f.affectedBlocks.join(", ")}`,
+      affectedFiles: f.affectedBlocks
+    });
+  }
+}
+function analyzeRuleBalance(world, suggestions) {
+  if (!world.rules || world.rules.length === 0) return;
+  const structural = world.rules.filter((r) => r.severity === "structural");
+  const degradation = world.rules.filter((r) => r.severity === "degradation");
+  const advantage = world.rules.filter((r) => r.severity === "advantage");
+  if (structural.length === 0) {
+    suggestions.push({
+      id: "no-structural-rules",
+      priority: "high",
+      category: "balance",
+      title: "No structural rules",
+      description: "All rules are degradation or advantage. Structural rules define the core mechanics that hold the world together.",
+      action: "Add at least one structural-severity rule that enforces a fundamental world constraint.",
+      affectedFiles: ["rules/"]
+    });
+  }
+  if (advantage.length === 0 && world.rules.length >= 3) {
+    suggestions.push({
+      id: "no-advantage-rules",
+      priority: "medium",
+      category: "balance",
+      title: "No advantage rules",
+      description: "All rules are negative (structural or degradation). Adding advantage rules creates positive feedback loops.",
+      action: 'Add a rule with severity "advantage" that rewards desirable state.',
+      affectedFiles: ["rules/"]
+    });
+  }
+  if (degradation.length === 0 && world.rules.length >= 3) {
+    suggestions.push({
+      id: "no-degradation-rules",
+      priority: "medium",
+      category: "balance",
+      title: "No degradation rules",
+      description: "No rules model gradual decline. Degradation rules create realistic tension.",
+      action: 'Add a rule with severity "degradation" that models gradual state decline.',
+      affectedFiles: ["rules/"]
+    });
+  }
+  const missingTranslation = world.rules.filter(
+    (r) => !r.causal_translation?.trigger_text && !r.causal_translation?.effect_text
+  );
+  if (missingTranslation.length > 0 && missingTranslation.length <= 5) {
+    suggestions.push({
+      id: "missing-causal-translations",
+      priority: "low",
+      category: "completeness",
+      title: `${missingTranslation.length} rule(s) missing causal translations`,
+      description: "Causal translations provide human-readable narratives for rules. They improve explain output.",
+      action: `Add causal_translation to: ${missingTranslation.map((r) => r.id).join(", ")}`,
+      affectedFiles: ["rules/"]
+    });
+  }
+}
+function analyzeStateCoverage(world, suggestions) {
+  if (!world.stateSchema?.variables || !world.rules) return;
+  const variables = Object.keys(world.stateSchema.variables);
+  const ruleTargets = /* @__PURE__ */ new Set();
+  const ruleTriggers = /* @__PURE__ */ new Set();
+  for (const rule of world.rules) {
+    for (const t of rule.triggers) {
+      if (t.source === "state") ruleTriggers.add(t.field);
+    }
+    for (const e of rule.effects ?? []) {
+      ruleTargets.add(e.target);
+    }
+    for (const ce of rule.effects_conditional ?? []) {
+      for (const e of ce.effects) {
+        ruleTargets.add(e.target);
+      }
+    }
+  }
+  const writeOnly = variables.filter((v) => ruleTargets.has(v) && !ruleTriggers.has(v));
+  if (writeOnly.length > 0) {
+    suggestions.push({
+      id: "write-only-variables",
+      priority: "medium",
+      category: "structure",
+      title: `${writeOnly.length} write-only variable(s)`,
+      description: `These variables are modified by rules but never trigger any rule: ${writeOnly.join(", ")}. They may be dead-end state.`,
+      action: "Add rules that trigger on these variables to create feedback loops.",
+      affectedFiles: ["rules/", "state-schema.json"]
+    });
+  }
+  const readOnly = variables.filter((v) => ruleTriggers.has(v) && !ruleTargets.has(v));
+  if (readOnly.length > 0 && readOnly.length <= 3) {
+    suggestions.push({
+      id: "read-only-variables",
+      priority: "low",
+      category: "structure",
+      title: `${readOnly.length} input-only variable(s)`,
+      description: `These variables trigger rules but are never modified: ${readOnly.join(", ")}. They act as fixed inputs.`,
+      action: "This is fine for configuration inputs. If they should evolve, add rules that target them.",
+      affectedFiles: ["state-schema.json"]
+    });
+  }
+}
+function analyzeGateCoverage(world, suggestions) {
+  const gates = world.gates?.viability_classification ?? [];
+  if (gates.length === 0) return;
+  const statuses = new Set(gates.map((g) => g.status));
+  const standard = ["THRIVING", "STABLE", "COMPRESSED", "CRITICAL", "MODEL_COLLAPSES"];
+  const missing = standard.filter((s) => !statuses.has(s));
+  if (missing.length > 0 && missing.length <= 2) {
+    suggestions.push({
+      id: "incomplete-viability-gates",
+      priority: "medium",
+      category: "structure",
+      title: `Missing viability level(s): ${missing.join(", ")}`,
+      description: "A complete viability ladder gives finer-grained status classification.",
+      action: `Add gates for: ${missing.join(", ")}`,
+      affectedFiles: ["gates.json"]
+    });
+  }
+}
+function analyzeAssumptions(world, suggestions) {
+  const profiles = Object.keys(world.assumptions?.profiles ?? {});
+  if (profiles.length === 1) {
+    suggestions.push({
+      id: "single-assumption-profile",
+      priority: "medium",
+      category: "completeness",
+      title: "Only one assumption profile",
+      description: "A single profile means no scenario comparison. Add an alternative profile to enable what-if analysis.",
+      action: "Add a second profile with different parameter values to assumptions.json.",
+      affectedFiles: ["assumptions.json"]
+    });
+  }
+}
+function analyzeSimulationDynamics(world, suggestions) {
+  if (!world.rules || world.rules.length === 0) return;
+  if (!world.stateSchema?.variables || Object.keys(world.stateSchema.variables).length === 0) return;
+  try {
+    const result = simulateWorld(world, { steps: 1 });
+    const step = result.steps[0];
+    if (step && step.rulesFired === 0) {
+      suggestions.push({
+        id: "no-rules-fire-default",
+        priority: "high",
+        category: "balance",
+        title: "No rules fire with default state",
+        description: "With all variables at their defaults, zero rules trigger. The world is inert until state changes.",
+        action: "Adjust rule thresholds or state defaults so at least some rules fire in the baseline scenario.",
+        affectedFiles: ["rules/", "state-schema.json"]
+      });
+    }
+    if (result.collapsed && result.collapseStep === 1) {
+      suggestions.push({
+        id: "immediate-collapse",
+        priority: "critical",
+        category: "balance",
+        title: "World collapses on first step",
+        description: `Rule "${result.collapseRule}" triggers collapse immediately with default state. The world cannot sustain itself.`,
+        action: "Adjust collapse thresholds or state defaults to prevent immediate collapse.",
+        affectedFiles: ["rules/", "state-schema.json"]
+      });
+    }
+    if (!result.collapsed) {
+      const multiStep = simulateWorld(world, { steps: 5 });
+      if (multiStep.collapsed) {
+        suggestions.push({
+          id: "eventual-collapse",
+          priority: "high",
+          category: "balance",
+          title: `World collapses by step ${multiStep.collapseStep}`,
+          description: `Starting from defaults, the world collapses after ${multiStep.collapseStep} steps. Consider adding stabilizing advantage rules.`,
+          action: "Add advantage rules or adjust degradation rates to allow sustainable states.",
+          affectedFiles: ["rules/"]
+        });
+      }
+    }
+  } catch {
+  }
+}
+function analyzeCompleteness(world, suggestions) {
+  if (!world.guards) {
+    suggestions.push({
+      id: "add-guards",
+      priority: "low",
+      category: "completeness",
+      title: "No guards defined",
+      description: "Guards enable runtime enforcement in Action Space. Without them, the world has no runtime protection.",
+      action: "Add guards.json with structural guards backing each invariant.",
+      affectedFiles: ["guards.json"]
+    });
+  }
+  if (!world.roles) {
+    suggestions.push({
+      id: "add-roles",
+      priority: "low",
+      category: "completeness",
+      title: "No roles defined",
+      description: "Roles enable multi-agent governance with different permission levels.",
+      action: "Add roles.json with at least an observer and steward role.",
+      affectedFiles: ["roles.json"]
+    });
+  }
+  if (!world.kernel) {
+    suggestions.push({
+      id: "add-kernel",
+      priority: "low",
+      category: "completeness",
+      title: "No kernel configuration",
+      description: "A kernel config provides Thinking Space governance with forbidden patterns and response vocabulary.",
+      action: "Add kernel.json with input/output boundaries.",
+      affectedFiles: ["kernel.json"]
+    });
+  }
+  const outcomes = world.outcomes?.computed_outcomes ?? [];
+  if (outcomes.length > 0 && !outcomes.some((o) => o.primary)) {
+    suggestions.push({
+      id: "no-primary-outcome",
+      priority: "medium",
+      category: "structure",
+      title: "No primary outcome defined",
+      description: "Marking one outcome as primary helps tools identify the main metric to display.",
+      action: "Set primary: true on the most important computed outcome.",
+      affectedFiles: ["outcomes.json"]
+    });
+  }
+}
+function computeHealthScore(world, suggestions) {
+  let score = 100;
+  for (const s of suggestions) {
+    switch (s.priority) {
+      case "critical":
+        score -= 15;
+        break;
+      case "high":
+        score -= 5;
+        break;
+      case "medium":
+        score -= 2;
+        break;
+      case "low":
+        score -= 1;
+        break;
+    }
+  }
+  return Math.max(0, Math.min(100, score));
+}
+function renderImproveText(report) {
+  const lines = [];
+  lines.push(`IMPROVE: ${report.worldName}`);
+  lines.push(`Health Score: ${report.score}/100`);
+  lines.push("");
+  if (report.suggestions.length === 0) {
+    lines.push("No suggestions \u2014 this world is in great shape.");
+    return lines.join("\n");
+  }
+  const groups = [
+    ["CRITICAL (must fix)", "critical", "x"],
+    ["HIGH PRIORITY", "high", "!"],
+    ["SUGGESTIONS", "medium", "-"],
+    ["NICE TO HAVE", "low", "."]
+  ];
+  for (const [header, priority, icon] of groups) {
+    const items = report.suggestions.filter((s) => s.priority === priority);
+    if (items.length === 0) continue;
+    lines.push(header);
+    for (const s of items) {
+      lines.push(`  ${icon} ${s.title}`);
+      lines.push(`    Action: ${s.action}`);
+    }
+    lines.push("");
+  }
+  const { stats } = report;
+  const parts = [];
+  if (stats.critical > 0) parts.push(`${stats.critical} critical`);
+  if (stats.high > 0) parts.push(`${stats.high} high`);
+  if (stats.medium > 0) parts.push(`${stats.medium} medium`);
+  if (stats.low > 0) parts.push(`${stats.low} low`);
+  lines.push(`Total: ${report.suggestions.length} suggestions (${parts.join(", ")})`);
+  return lines.join("\n");
+}
+
+export {
+  improveWorld,
+  renderImproveText
+};

package/dist/chunk-G7DJ6VOD.js

@@ -0,0 +1,101 @@
+import {
+  evaluateGuard
+} from "./chunk-W7LLXRGY.js";
+import {
+  loadWorld
+} from "./chunk-CTZHONLA.js";
+
+// src/adapters/express.ts
+function methodToCategory(method) {
+  switch (method.toUpperCase()) {
+    case "GET":
+    case "HEAD":
+    case "OPTIONS":
+      return "read";
+    case "POST":
+    case "PUT":
+    case "PATCH":
+      return "write";
+    case "DELETE":
+      return "delete";
+    default:
+      return "other";
+  }
+}
+function defaultMapRequest(req) {
+  const method = (req.method ?? "GET").toUpperCase();
+  const path = req.path ?? req.url ?? "/";
+  return {
+    intent: `${method} ${path}`,
+    tool: "http",
+    scope: path,
+    actionCategory: methodToCategory(method),
+    direction: "input",
+    args: {
+      method,
+      path,
+      ...req.params ?? {},
+      ...req.query ?? {}
+    }
+  };
+}
+function defaultOnBlock(verdict, _req, res, statusCode) {
+  const body = {
+    error: "Governance policy violation",
+    reason: verdict.reason ?? "Action not permitted",
+    ruleId: verdict.ruleId,
+    status: verdict.status
+  };
+  if (typeof res.status === "function" && typeof res.json === "function") {
+    const r = res.status(statusCode);
+    r.json(body);
+  } else if (res.send) {
+    res.statusCode = statusCode;
+    res.send(JSON.stringify(body));
+  } else if (res.end) {
+    res.statusCode = statusCode;
+    res.end();
+  }
+}
+async function createGovernanceMiddleware(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return createGovernanceMiddlewareFromWorld(world, options);
+}
+function createGovernanceMiddlewareFromWorld(world, options = {}) {
+  const engineOptions = {
+    trace: options.trace ?? false,
+    level: options.level
+  };
+  const mapRequest = options.mapRequest ?? defaultMapRequest;
+  const blockStatusCode = options.blockStatusCode ?? 403;
+  return async function neuroVerseGovernance(req, res, next) {
+    try {
+      const event = mapRequest(req);
+      const verdict = evaluateGuard(event, world, engineOptions);
+      options.onEvaluate?.(verdict, event, req);
+      if (verdict.status === "ALLOW") {
+        next();
+        return;
+      }
+      if (verdict.status === "PAUSE") {
+        const approved = await options.onPause?.(verdict, req);
+        if (approved) {
+          next();
+          return;
+        }
+      }
+      if (options.onBlock) {
+        options.onBlock(verdict, req, res);
+      } else {
+        defaultOnBlock(verdict, req, res, blockStatusCode);
+      }
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+export {
+  createGovernanceMiddleware,
+  createGovernanceMiddlewareFromWorld
+};

package/dist/chunk-I3RRAYK2.js

@@ -0,0 +1,11 @@
+// src/contracts/validate-contract.ts
+var VALIDATE_EXIT_CODES = {
+  PASS: 0,
+  FAIL: 1,
+  WARN: 2,
+  ERROR: 3
+};
+
+export {
+  VALIDATE_EXIT_CODES
+};