@neuroverseos/governance 0.5.0 → 0.6.0

package/dist/engine/guard-engine.d.cts

@@ -0,0 +1,60 @@
+import { WorldDefinition, GovernanceEvent } from '../types.cjs';
+import { a as GuardEvent, b as GuardEngineOptions, G as GuardVerdict, d as GuardStatus } from '../guard-contract-ddiIPlOg.cjs';
+
+/**
+ * Guard Engine — Deterministic Governance Evaluator
+ *
+ * Pure function: (event, world, options) → verdict
+ *
+ * Evaluates a GuardEvent against a loaded WorldDefinition and produces
+ * a GuardVerdict with evidence and optional evaluation trace.
+ *
+ * Evaluation chain (first-match-wins on BLOCK/PAUSE):
+ *   1.   Safety checks (prompt injection, scope escape)    → PAUSE
+ *   1.5  Plan enforcement (task scope)                     → BLOCK/PAUSE
+ *   2.   Role-specific rules (cannotDo, requiresApproval)  → BLOCK/PAUSE
+ *   3.   Declarative guards (guards.json)                  → BLOCK/PAUSE/WARN
+ *   4.   Kernel rules (kernel.json forbidden patterns)     → BLOCK
+ *   5.   Level constraints (basic/standard/strict)         → PAUSE
+ *   6.   Default                                           → ALLOW
+ *
+ * Invariant checks run unconditionally and are recorded in evidence
+ * but do not produce verdicts — they measure world health.
+ *
+ * INVARIANTS:
+ *   - Deterministic: same event + same world → same verdict.
+ *   - Zero network calls. Zero LLM calls. Zero async.
+ *   - Every check is recorded in the trace, not just the decider.
+ *   - No hidden logic. Everything is in the world file or declared here.
+ */
+
+declare function evaluateGuard(event: GuardEvent, world: WorldDefinition, options?: GuardEngineOptions): GuardVerdict;
+/**
+ * Build a normalized allowlist key from a GuardEvent.
+ *
+ * Format: `tool::intent` (both lowercased, intent trimmed).
+ * Tool defaults to '*' when absent.
+ *
+ * Callers use this to:
+ *   1. Add keys to the allowlist set (on user "allow-always" decision)
+ *   2. The engine uses it to check membership before evaluation
+ *
+ * The key is opaque — callers should always use this function
+ * rather than constructing keys manually.
+ */
+declare function eventToAllowlistKey(event: GuardEvent): string;
+/**
+ * Convert a guard verdict into a GovernanceEvent.
+ *
+ * The guard evaluation log IS the event stream.
+ * No Kafka, no queues — just data flowing from Guard → Simulate.
+ *
+ * Mapping:
+ *   ALLOW  → "action_allowed"
+ *   BLOCK  → "action_blocked"
+ *   PAUSE  → "action_paused"
+ *   + semantic type from intent when available
+ */
+declare function verdictToEvent(status: GuardStatus, intent?: string): GovernanceEvent;
+
+export { evaluateGuard, eventToAllowlistKey, verdictToEvent };

package/dist/engine/guard-engine.d.ts

@@ -0,0 +1,60 @@
+import { WorldDefinition, GovernanceEvent } from '../types.js';
+import { a as GuardEvent, b as GuardEngineOptions, G as GuardVerdict, d as GuardStatus } from '../guard-contract-q6HJAq3Q.js';
+
+/**
+ * Guard Engine — Deterministic Governance Evaluator
+ *
+ * Pure function: (event, world, options) → verdict
+ *
+ * Evaluates a GuardEvent against a loaded WorldDefinition and produces
+ * a GuardVerdict with evidence and optional evaluation trace.
+ *
+ * Evaluation chain (first-match-wins on BLOCK/PAUSE):
+ *   1.   Safety checks (prompt injection, scope escape)    → PAUSE
+ *   1.5  Plan enforcement (task scope)                     → BLOCK/PAUSE
+ *   2.   Role-specific rules (cannotDo, requiresApproval)  → BLOCK/PAUSE
+ *   3.   Declarative guards (guards.json)                  → BLOCK/PAUSE/WARN
+ *   4.   Kernel rules (kernel.json forbidden patterns)     → BLOCK
+ *   5.   Level constraints (basic/standard/strict)         → PAUSE
+ *   6.   Default                                           → ALLOW
+ *
+ * Invariant checks run unconditionally and are recorded in evidence
+ * but do not produce verdicts — they measure world health.
+ *
+ * INVARIANTS:
+ *   - Deterministic: same event + same world → same verdict.
+ *   - Zero network calls. Zero LLM calls. Zero async.
+ *   - Every check is recorded in the trace, not just the decider.
+ *   - No hidden logic. Everything is in the world file or declared here.
+ */
+
+declare function evaluateGuard(event: GuardEvent, world: WorldDefinition, options?: GuardEngineOptions): GuardVerdict;
+/**
+ * Build a normalized allowlist key from a GuardEvent.
+ *
+ * Format: `tool::intent` (both lowercased, intent trimmed).
+ * Tool defaults to '*' when absent.
+ *
+ * Callers use this to:
+ *   1. Add keys to the allowlist set (on user "allow-always" decision)
+ *   2. The engine uses it to check membership before evaluation
+ *
+ * The key is opaque — callers should always use this function
+ * rather than constructing keys manually.
+ */
+declare function eventToAllowlistKey(event: GuardEvent): string;
+/**
+ * Convert a guard verdict into a GovernanceEvent.
+ *
+ * The guard evaluation log IS the event stream.
+ * No Kafka, no queues — just data flowing from Guard → Simulate.
+ *
+ * Mapping:
+ *   ALLOW  → "action_allowed"
+ *   BLOCK  → "action_blocked"
+ *   PAUSE  → "action_paused"
+ *   + semantic type from intent when available
+ */
+declare function verdictToEvent(status: GuardStatus, intent?: string): GovernanceEvent;
+
+export { evaluateGuard, eventToAllowlistKey, verdictToEvent };

package/dist/{guard-engine-N7TUIUU7.js → engine/guard-engine.js}

@@ -2,9 +2,9 @@ import {
   evaluateGuard,
   eventToAllowlistKey,
   verdictToEvent
-} from "./chunk-ZAF6JH23.js";
-import "./chunk-QLPTHTVB.js";
-import "./chunk-QWGCMQQD.js";
+} from "../chunk-ZAF6JH23.js";
+import "../chunk-QLPTHTVB.js";
+import "../chunk-QWGCMQQD.js";
 export {
   evaluateGuard,
   eventToAllowlistKey,

package/dist/engine/simulate-engine.cjs

@@ -0,0 +1,390 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/engine/simulate-engine.ts
+var simulate_engine_exports = {};
+__export(simulate_engine_exports, {
+  renderSimulateText: () => renderSimulateText,
+  simulateWorld: () => simulateWorld
+});
+module.exports = __toCommonJS(simulate_engine_exports);
+function simulateWorld(world, options = {}) {
+  if (!world || !world.world) {
+    throw new Error(
+      'World definition required. simulateWorld() cannot run without a world.\nLoad one with: loadWorld("./world/") or parseWorldMarkdown(markdown)'
+    );
+  }
+  const steps = Math.max(1, Math.min(options.steps ?? 1, 50));
+  const profileName = options.profile ?? world.world.default_assumption_profile;
+  const state = buildInitialState(world.stateSchema, options.stateOverrides);
+  for (const outcome of world.outcomes?.computed_outcomes ?? []) {
+    if (!(outcome.id in state)) {
+      state[outcome.id] = outcome.primary ? 100 : 0;
+    }
+  }
+  const assumptions = resolveAssumptions(world.assumptions, profileName);
+  const initialState = { ...state };
+  const simulationSteps = [];
+  let collapsed = false;
+  let collapseStep;
+  let collapseRule;
+  const sortedRules = [...world.rules].sort((a, b) => a.order - b.order);
+  const allEvents = options.events ?? [];
+  const eventsByStep = Array.from({ length: steps }, () => []);
+  for (let i = 0; i < allEvents.length; i++) {
+    const stepIdx = Math.min(i, steps - 1);
+    eventsByStep[stepIdx].push(allEvents[i]);
+  }
+  let totalEventsConsumed = 0;
+  for (let stepNum = 1; stepNum <= steps; stepNum++) {
+    if (collapsed) break;
+    const stepEvents = eventsByStep[stepNum - 1];
+    const stepResult = evaluateStep(
+      stepNum,
+      sortedRules,
+      state,
+      assumptions,
+      world,
+      stepEvents
+    );
+    totalEventsConsumed += stepResult.eventsApplied.length;
+    simulationSteps.push(stepResult);
+    if (stepResult.collapsed) {
+      collapsed = true;
+      collapseStep = stepNum;
+      collapseRule = stepResult.rulesEvaluated.find((r) => r.collapsed)?.ruleId;
+    }
+  }
+  const finalViability = classifyViability(state, world);
+  return {
+    worldId: world.world.world_id,
+    worldName: world.world.name,
+    profile: profileName,
+    initialState,
+    steps: simulationSteps,
+    finalState: { ...state },
+    finalViability,
+    collapsed,
+    collapseStep,
+    collapseRule,
+    eventsConsumed: totalEventsConsumed
+  };
+}
+function evaluateStep(stepNum, rules, state, assumptions, world, events = []) {
+  const evaluations = [];
+  const eventApplications = [];
+  let rulesFired = 0;
+  let collapsed = false;
+  const firedRuleIds = /* @__PURE__ */ new Set();
+  for (const evt of events) {
+    const application = {
+      eventType: evt.type,
+      rulesTriggered: [],
+      effects: []
+    };
+    for (const rule of rules) {
+      const eventTrigger = rule.triggers.find(
+        (t) => t.field === "event" && t.source === "state"
+      );
+      if (!eventTrigger) continue;
+      const matches = evaluateOperator(evt.type, eventTrigger.operator, eventTrigger.value);
+      if (!matches) continue;
+      application.rulesTriggered.push(rule.id);
+      firedRuleIds.add(rule.id);
+      for (const effect of rule.effects ?? []) {
+        const applied = applyEffect(effect, state);
+        if (applied) application.effects.push(applied);
+      }
+    }
+    eventApplications.push(application);
+  }
+  for (const rule of rules) {
+    if (collapsed) {
+      evaluations.push({
+        ruleId: rule.id,
+        label: rule.label,
+        triggered: false,
+        excluded: true,
+        effects: [],
+        collapsed: false
+      });
+      continue;
+    }
+    const excluded = rule.exclusive_with ? firedRuleIds.has(rule.exclusive_with) : false;
+    if (excluded) {
+      evaluations.push({
+        ruleId: rule.id,
+        label: rule.label,
+        triggered: false,
+        excluded: true,
+        effects: [],
+        collapsed: false
+      });
+      continue;
+    }
+    const triggered = evaluateTriggers(rule.triggers, state, assumptions);
+    if (!triggered) {
+      evaluations.push({
+        ruleId: rule.id,
+        label: rule.label,
+        triggered: false,
+        excluded: false,
+        effects: [],
+        collapsed: false
+      });
+      continue;
+    }
+    firedRuleIds.add(rule.id);
+    rulesFired++;
+    const appliedEffects = [];
+    for (const effect of rule.effects ?? []) {
+      const applied = applyEffect(effect, state);
+      if (applied) appliedEffects.push(applied);
+    }
+    for (const ce of rule.effects_conditional ?? []) {
+      const conditionMet = evaluateSingleTrigger(ce.condition, state, assumptions);
+      const andMet = ce.and ? evaluateSingleTrigger(ce.and, state, assumptions) : true;
+      const orMet = ce.or ? evaluateSingleTrigger(ce.or, state, assumptions) : false;
+      const anyMet = ce.condition_any ? ce.condition_any.some((c) => evaluateSingleTrigger(c, state, assumptions)) : false;
+      const shouldApply = conditionMet && andMet || ce.or && orMet || ce.condition_any && anyMet;
+      if (shouldApply) {
+        for (const effect of ce.effects) {
+          const applied = applyEffect(effect, state);
+          if (applied) appliedEffects.push(applied);
+        }
+      }
+    }
+    let ruleCollapsed = false;
+    if (rule.collapse_check) {
+      const fieldVal = typeof state[rule.collapse_check.field] === "number" ? state[rule.collapse_check.field] : 0;
+      if (evaluateOperator(fieldVal, rule.collapse_check.operator, rule.collapse_check.value)) {
+        ruleCollapsed = true;
+        collapsed = true;
+      }
+    }
+    if (!ruleCollapsed && rule.secondary_check) {
+      const fieldVal = typeof state[rule.secondary_check.field] === "number" ? state[rule.secondary_check.field] : 0;
+      if (evaluateOperator(fieldVal, rule.secondary_check.operator, rule.secondary_check.value)) {
+        ruleCollapsed = true;
+        collapsed = true;
+      }
+    }
+    evaluations.push({
+      ruleId: rule.id,
+      label: rule.label,
+      triggered: true,
+      excluded: false,
+      effects: appliedEffects,
+      collapsed: ruleCollapsed,
+      collapseField: ruleCollapsed ? rule.collapse_check?.field ?? rule.secondary_check?.field : void 0
+    });
+  }
+  const viability = classifyViability(state, world);
+  return {
+    step: stepNum,
+    eventsApplied: eventApplications,
+    rulesEvaluated: evaluations,
+    rulesFired,
+    stateAfter: { ...state },
+    viability,
+    collapsed
+  };
+}
+function evaluateTriggers(triggers, state, assumptions) {
+  if (!triggers || triggers.length === 0) return true;
+  return triggers.every((t) => evaluateSingleTrigger(t, state, assumptions));
+}
+function evaluateSingleTrigger(trigger, state, assumptions) {
+  const source = trigger.source === "assumption" ? assumptions : state;
+  const fieldValue = source[trigger.field];
+  if (fieldValue === void 0) return false;
+  return evaluateOperator(fieldValue, trigger.operator, trigger.value);
+}
+function evaluateOperator(fieldValue, operator, conditionValue) {
+  switch (operator) {
+    case "==":
+      return fieldValue === conditionValue;
+    case "!=":
+      return fieldValue !== conditionValue;
+    case ">":
+      return typeof fieldValue === "number" && typeof conditionValue === "number" && fieldValue > conditionValue;
+    case "<":
+      return typeof fieldValue === "number" && typeof conditionValue === "number" && fieldValue < conditionValue;
+    case ">=":
+      return typeof fieldValue === "number" && typeof conditionValue === "number" && fieldValue >= conditionValue;
+    case "<=":
+      return typeof fieldValue === "number" && typeof conditionValue === "number" && fieldValue <= conditionValue;
+    case "in":
+      return Array.isArray(conditionValue) && conditionValue.includes(String(fieldValue));
+    default:
+      return false;
+  }
+}
+function applyEffect(effect, state) {
+  const before = state[effect.target];
+  let after;
+  switch (effect.operation) {
+    case "multiply":
+    case "multiply_dynamic": {
+      const current = typeof before === "number" ? before : 0;
+      const factor = typeof effect.value === "number" ? effect.value : 1;
+      after = current * factor;
+      break;
+    }
+    case "add":
+    case "add_dynamic": {
+      const current = typeof before === "number" ? before : 0;
+      const addend = typeof effect.value === "number" ? effect.value : 0;
+      after = current + addend;
+      break;
+    }
+    case "subtract":
+    case "subtract_dynamic": {
+      const current = typeof before === "number" ? before : 0;
+      const subtrahend = typeof effect.value === "number" ? effect.value : 0;
+      after = current - subtrahend;
+      break;
+    }
+    case "set":
+    case "set_dynamic":
+      after = effect.value;
+      break;
+    case "set_boolean":
+      after = !!effect.value;
+      break;
+    default:
+      return null;
+  }
+  state[effect.target] = after;
+  return {
+    target: effect.target,
+    operation: effect.operation,
+    value: effect.value,
+    before: before ?? 0,
+    after
+  };
+}
+function buildInitialState(schema, overrides) {
+  const state = {};
+  for (const [name, variable] of Object.entries(schema.variables ?? {})) {
+    state[name] = variable.default;
+  }
+  if (overrides) {
+    for (const [key, value] of Object.entries(overrides)) {
+      state[key] = value;
+    }
+  }
+  return state;
+}
+function resolveAssumptions(config, profileName) {
+  const profile = config.profiles?.[profileName];
+  return profile?.parameters ?? {};
+}
+function classifyViability(state, world) {
+  const gates = world.gates?.viability_classification ?? [];
+  for (const gate of gates) {
+    const fieldValue = state[gate.field];
+    if (typeof fieldValue !== "number") continue;
+    if (evaluateOperator(fieldValue, gate.operator, gate.value)) {
+      return gate.status;
+    }
+  }
+  return "MODEL_COLLAPSES";
+}
+function renderSimulateText(result) {
+  const lines = [];
+  lines.push(`SIMULATION: ${result.worldName}`);
+  lines.push(`Profile: ${result.profile}`);
+  lines.push(`Steps: ${result.steps.length}`);
+  lines.push("");
+  lines.push("INITIAL STATE");
+  for (const [key, value] of Object.entries(result.initialState)) {
+    lines.push(`  ${key}: ${value}`);
+  }
+  lines.push("");
+  for (const step of result.steps) {
+    lines.push(`STEP ${step.step}`);
+    if (step.eventsApplied && step.eventsApplied.length > 0) {
+      for (const evt of step.eventsApplied) {
+        lines.push(`  EVENT: ${evt.eventType}`);
+        if (evt.rulesTriggered.length > 0) {
+          lines.push(`    Rules triggered: ${evt.rulesTriggered.join(", ")}`);
+        }
+        for (const effect of evt.effects) {
+          const beforeStr = formatValue(effect.before);
+          const afterStr = formatValue(effect.after);
+          lines.push(`    ${effect.target}: ${beforeStr} -> ${afterStr}`);
+        }
+      }
+    }
+    const fired = step.rulesEvaluated.filter((r) => r.triggered);
+    const skipped = step.rulesEvaluated.filter((r) => !r.triggered && !r.excluded);
+    const excluded = step.rulesEvaluated.filter((r) => r.excluded);
+    if (fired.length === 0) {
+      lines.push("  No rules fired (state unchanged)");
+    } else {
+      for (const rule of fired) {
+        lines.push(`  FIRED: ${rule.label}`);
+        for (const effect of rule.effects) {
+          const beforeStr = formatValue(effect.before);
+          const afterStr = formatValue(effect.after);
+          lines.push(`    ${effect.target}: ${beforeStr} -> ${afterStr}`);
+        }
+        if (rule.collapsed) {
+          lines.push(`    COLLAPSE on ${rule.collapseField}`);
+        }
+      }
+    }
+    if (excluded.length > 0) {
+      lines.push(`  Excluded: ${excluded.map((r) => r.label).join(", ")}`);
+    }
+    lines.push(`  Viability: ${step.viability}`);
+    if (step.collapsed) {
+      lines.push("  ** MODEL COLLAPSED **");
+    }
+    lines.push("");
+  }
+  lines.push("FINAL STATE");
+  for (const [key, value] of Object.entries(result.finalState)) {
+    const initial = result.initialState[key];
+    const changed = initial !== value;
+    const marker = changed ? " (changed)" : "";
+    lines.push(`  ${key}: ${formatValue(value)}${marker}`);
+  }
+  lines.push("");
+  if (result.eventsConsumed > 0) {
+    lines.push(`EVENTS CONSUMED: ${result.eventsConsumed}`);
+  }
+  lines.push(`VIABILITY: ${result.finalViability}`);
+  if (result.collapsed) {
+    lines.push(`COLLAPSED at step ${result.collapseStep} (rule: ${result.collapseRule})`);
+  }
+  return lines.join("\n");
+}
+function formatValue(v) {
+  if (typeof v === "number") {
+    return Number.isInteger(v) ? String(v) : v.toFixed(2);
+  }
+  return String(v);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  renderSimulateText,
+  simulateWorld
+});

package/dist/engine/simulate-engine.d.cts

@@ -0,0 +1,105 @@
+import { GovernanceEvent, ViabilityStatus, WorldDefinition } from '../types.cjs';
+
+/**
+ * Simulate Engine — Deterministic State Evolution (Reference Simulator)
+ *
+ * Pure function: (world, options) → SimulationResult
+ *
+ * This is NeuroVerse's REFERENCE SIMULATOR — one way to model how a world
+ * evolves over time. It is NOT the governance engine.
+ *
+ * simulateWorld() ≠ evaluateGuard()
+ *
+ *   evaluateGuard()  — Runtime enforcement. Decides if an action is allowed.
+ *                      Includes safety layer, role checks, plan enforcement,
+ *                      kernel rules, level constraints. Use for governance.
+ *
+ *   simulateWorld()  — State evolution modeling. Evaluates rule triggers,
+ *                      applies effects, tracks viability over N steps.
+ *                      Use for scenario planning and what-if analysis.
+ *
+ * World files (.nv-world.md) are portable — they define rules, roles, and
+ * constraints that can be consumed by any simulator or governance engine.
+ * This simulator is a reference implementation, not the only interpreter.
+ *
+ * Supports:
+ *   - Single-step evaluation (default)
+ *   - Multi-step iteration (--steps N)
+ *   - State overrides (start from non-default values)
+ *   - Assumption profile selection
+ *   - Collapse detection (early termination)
+ *
+ * INVARIANTS:
+ *   - Deterministic: same world + same options → same result.
+ *   - Zero network calls. Zero LLM calls. Zero async.
+ *   - Every rule evaluation is recorded in the trace.
+ *   - World definition is REQUIRED — no world, no simulation.
+ */
+
+interface SimulateOptions {
+    /** Number of simulation steps (default: 1) */
+    steps?: number;
+    /** State variable overrides (start values) */
+    stateOverrides?: Record<string, string | number | boolean>;
+    /** Assumption profile to use (default: world default) */
+    profile?: string;
+    /**
+     * Governance events to inject into the simulation.
+     * Events are applied before state-driven rules each step.
+     * This is the bridge: Guard → Events → Simulate → State Evolution.
+     *
+     * Events are distributed across steps (round-robin) or all applied to step 1
+     * if there are fewer steps than events.
+     */
+    events?: GovernanceEvent[];
+}
+interface SimulationResult {
+    worldId: string;
+    worldName: string;
+    profile: string;
+    initialState: Record<string, string | number | boolean>;
+    steps: SimulationStep[];
+    finalState: Record<string, string | number | boolean>;
+    finalViability: ViabilityStatus;
+    collapsed: boolean;
+    collapseStep?: number;
+    collapseRule?: string;
+    /** Total events consumed during simulation */
+    eventsConsumed: number;
+}
+interface SimulationStep {
+    step: number;
+    /** Events applied during this step (before rules) */
+    eventsApplied: EventApplication[];
+    rulesEvaluated: RuleEvaluation[];
+    rulesFired: number;
+    stateAfter: Record<string, string | number | boolean>;
+    viability: ViabilityStatus;
+    collapsed: boolean;
+}
+/** Record of an event applied during simulation */
+interface EventApplication {
+    eventType: string;
+    rulesTriggered: string[];
+    effects: AppliedEffect[];
+}
+interface RuleEvaluation {
+    ruleId: string;
+    label: string;
+    triggered: boolean;
+    excluded: boolean;
+    effects: AppliedEffect[];
+    collapsed: boolean;
+    collapseField?: string;
+}
+interface AppliedEffect {
+    target: string;
+    operation: string;
+    value: number | boolean | string;
+    before: string | number | boolean;
+    after: string | number | boolean;
+}
+declare function simulateWorld(world: WorldDefinition, options?: SimulateOptions): SimulationResult;
+declare function renderSimulateText(result: SimulationResult): string;
+
+export { type AppliedEffect, type EventApplication, type RuleEvaluation, type SimulateOptions, type SimulationResult, type SimulationStep, renderSimulateText, simulateWorld };