@neuroverseos/governance 0.3.1 → 0.3.3

package/dist/chunk-ZJTDUCC2.js

@@ -0,0 +1,194 @@
+// src/engine/rule-utils.ts
+function collectAllEffects(rule) {
+  const effects = [...rule.effects ?? []];
+  for (const ce of rule.effects_conditional ?? []) {
+    effects.push(...ce.effects);
+  }
+  return effects;
+}
+
+// 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 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-ZWI3NIXK.js

@@ -0,0 +1,314 @@
+// src/engine/simulate-engine.ts
+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);
+  for (let stepNum = 1; stepNum <= steps; stepNum++) {
+    if (collapsed) break;
+    const stepResult = evaluateStep(
+      stepNum,
+      sortedRules,
+      state,
+      assumptions,
+      world
+    );
+    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
+  };
+}
+function evaluateStep(stepNum, rules, state, assumptions, world) {
+  const evaluations = [];
+  let rulesFired = 0;
+  let collapsed = false;
+  const firedRuleIds = /* @__PURE__ */ new Set();
+  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,
+    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}`);
+    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("");
+  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);
+}
+
+export {
+  simulateWorld,
+  renderSimulateText
+};