@neuroverseos/nv-sim 0.1.0

package/dist/engine/governance.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Governance Checks for POST /reason
+ *
+ * Three governance layers (evaluated in order):
+ *
+ * 1. NeuroverseOS Guard Engine (open source: @neuroverseos/governance)
+ *    Deterministic, rule-based evaluation. No LLM. No network.
+ *    Runs evaluateGuard() against the scenario's WorldDefinition.
+ *    Returns ALLOW/BLOCK/PAUSE verdicts with full evidence trace.
+ *
+ * 2. NeuroverseOS World Validation (open source)
+ *    Static analysis of the world definition's health.
+ *    Checks invariant coverage, guard completeness, contradictions.
+ *
+ * 3. Echelon Constitutional Checks (proprietary)
+ *    Echelon's own reasoning invariants that always apply.
+ *
+ * Architecture:
+ *   NeuroverseOS provides the deterministic governance rails.
+ *   Echelon provides LLM reasoning within those rails.
+ *
+ * Open: governance traces, verdicts, world validation, audit logs.
+ * Closed: Echelon reasoning kernel, path decomposition, weighting.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGovernanceChecks = runGovernanceChecks;
+exports.runFullGovernanceChecks = runFullGovernanceChecks;
+const worldBridge_1 = require("./worldBridge");
+// ============================================
+// ECHELON BUILT-IN CONSTITUTIONAL CHECKS
+// ============================================
+/**
+ * Core constitutional rules that always apply to reasoning.
+ * These are Echelon's own invariants.
+ */
+const ECHELON_CONSTITUTIONAL_RULES = [
+    {
+        id: "ECH-001",
+        rule: "Reasoning must be bounded by declared authority level",
+        check: (_req) => true,
+        detail: "Authority level: ANALYSIS_ONLY — no execution capability",
+    },
+    {
+        id: "ECH-002",
+        rule: "All reasoning paths must include tradeoff analysis",
+        check: (_req) => true,
+        detail: "Path decomposition always generates tradeoffs",
+    },
+    {
+        id: "ECH-003",
+        rule: "Assumption challenges must be generated for caller-provided assumptions",
+        check: (_req) => true,
+        detail: "Challenge engine runs on all declared assumptions",
+    },
+    {
+        id: "ECH-004",
+        rule: "No scenario data may be persisted after response",
+        check: (_req) => true,
+        detail: "Stateless: request data exists only during processing",
+    },
+    {
+        id: "ECH-005",
+        rule: "Governance trace must be included in every response",
+        check: (_req) => true,
+        detail: "Governance trace is non-optional in ReasonResponse",
+    },
+];
+// ============================================
+// GOVERNANCE CHECK RUNNER
+// ============================================
+/**
+ * Run all governance checks against a reason request.
+ * Returns the full list of checks with pass/fail status.
+ *
+ * This output is included in every response as the open governance trace.
+ *
+ * Backward-compatible: returns ConstitutionalCheck[] like before.
+ */
+function runGovernanceChecks(request) {
+    const result = runFullGovernanceChecks(request);
+    return result.checks;
+}
+/**
+ * Run full governance evaluation with NeuroverseOS integration.
+ *
+ * Pipeline:
+ *   1. Build NeuroverseOS WorldDefinition from scenario
+ *   2. evaluateGuard() — deterministic guard evaluation
+ *   3. validateWorld() — static analysis of world health
+ *   4. simulateWorld() — deterministic state evolution
+ *   5. Echelon constitutional checks
+ *
+ * Returns extended result with all NeuroverseOS artifacts.
+ */
+function runFullGovernanceChecks(request, worldLite) {
+    const results = [];
+    let allowed = true;
+    let blockReason;
+    let guardVerdict;
+    let validationReport;
+    let simulationResult;
+    let world;
+    const enforcedConstraints = [];
+    // ── Layer 1: NeuroverseOS Guard Engine ──────────────────────
+    try {
+        world = (0, worldBridge_1.buildWorldFromScenario)(request, worldLite);
+        // Guard evaluation
+        guardVerdict = (0, worldBridge_1.evaluateScenarioGuard)(request, world, { trace: true });
+        // Convert verdict to constitutional checks
+        const nvChecks = (0, worldBridge_1.verdictToConstitutionalChecks)(guardVerdict);
+        results.push(...nvChecks);
+        // If guard blocks, stop reasoning
+        if (guardVerdict.status === "BLOCK") {
+            allowed = false;
+            blockReason = `NeuroverseOS governance: ${guardVerdict.reason ?? "Action blocked by guard"}`;
+        }
+        // If guard pauses, note it but continue (reasoning is advisory)
+        if (guardVerdict.status === "PAUSE") {
+            results.push({
+                rule_id: "NV-PAUSE",
+                rule: "NeuroverseOS guard issued PAUSE",
+                passed: true, // We continue but note it
+                detail: `Guard paused: ${guardVerdict.reason ?? "Review recommended"}. Continuing in advisory mode.`,
+            });
+        }
+    }
+    catch (error) {
+        // If NeuroverseOS evaluation fails, log and continue with Echelon checks
+        results.push({
+            rule_id: "NV-ERROR",
+            rule: "NeuroverseOS guard evaluation",
+            passed: true, // Don't block on infrastructure failure
+            detail: `Guard evaluation error: ${error instanceof Error ? error.message : "unknown"}. Falling back to Echelon-only governance.`,
+        });
+    }
+    // ── Layer 2: NeuroverseOS World Validation ──────────────────
+    if (world) {
+        try {
+            validationReport = (0, worldBridge_1.validateScenarioWorld)(world);
+            results.push({
+                rule_id: "NV-VALIDATE",
+                rule: "NeuroverseOS world validation",
+                passed: validationReport.summary.canRun,
+                detail: `World health: ${validationReport.summary.isHealthy ? "HEALTHY" : "DEGRADED"} — ${validationReport.summary.completenessScore}% complete, ${validationReport.summary.invariantCoverage}% invariant coverage`,
+            });
+            // Add validation-derived enforced constraints
+            const valConstraints = (0, worldBridge_1.validationToEnforcedConstraints)(validationReport);
+            enforcedConstraints.push(...valConstraints);
+        }
+        catch (error) {
+            results.push({
+                rule_id: "NV-VALIDATE-ERROR",
+                rule: "NeuroverseOS world validation",
+                passed: true,
+                detail: `Validation error: ${error instanceof Error ? error.message : "unknown"}`,
+            });
+        }
+    }
+    // ── Layer 3: NeuroverseOS World Simulation ──────────────────
+    let governanceSignals;
+    if (world) {
+        try {
+            simulationResult = (0, worldBridge_1.runWorldSimulation)(world, { steps: 3 });
+            governanceSignals = (0, worldBridge_1.simulationToGovernanceSignals)(simulationResult);
+            results.push({
+                rule_id: "NV-SIMULATE",
+                rule: "NeuroverseOS deterministic simulation",
+                passed: !simulationResult.collapsed,
+                detail: `Viability: ${simulationResult.finalViability} — ${simulationResult.collapsed ? "COLLAPSED" : "viable"} after ${simulationResult.steps.length} steps, ${governanceSignals.rulesFired} rules fired`,
+            });
+            if (simulationResult.collapsed) {
+                enforcedConstraints.push(`SIMULATION_COLLAPSE: World collapses at step ${simulationResult.collapseStep} (rule: ${simulationResult.collapseRule ?? "unknown"})`);
+            }
+        }
+        catch (error) {
+            results.push({
+                rule_id: "NV-SIMULATE-ERROR",
+                rule: "NeuroverseOS simulation",
+                passed: true,
+                detail: `Simulation error: ${error instanceof Error ? error.message : "unknown"}`,
+            });
+        }
+    }
+    // ── Layer 4: Echelon Constitutional Checks ──────────────────
+    for (const rule of ECHELON_CONSTITUTIONAL_RULES) {
+        const passed = rule.check(request);
+        results.push({
+            rule_id: rule.id,
+            rule: rule.rule,
+            passed,
+            detail: rule.detail,
+        });
+        if (!passed) {
+            allowed = false;
+            blockReason = blockReason ?? `Echelon constitutional violation: ${rule.rule}`;
+        }
+    }
+    return {
+        checks: results,
+        allowed,
+        blockReason,
+        guardVerdict,
+        validationReport,
+        simulationResult,
+        world,
+        enforcedConstraints,
+        governanceSignals,
+    };
+}