@neuroverseos/governance 0.1.0 → 0.1.2

package/dist/governance-engine.js

@@ -1,660 +0,0 @@
-"use strict";
-/**
- * Governance Engine — Deterministic decision pipeline
- *
- * Evaluates tool calls against world rules in strict order:
- *   1. Session allowlist → ALLOW silently if guard already approved
- *   2. Invariants → any hit = BLOCK (immediate, no override)
- *   3. Guards → condition engine + tool filter → PAUSE or BLOCK
- *   4. Rules → trigger evaluation → verdict override
- *   5. Role constraints → cannotDo = BLOCK, requiresApproval = PAUSE
- *   6. Default → ALLOW
- *
- * Same world + same event = same verdict. Always.
- * No AI. No network calls. Sub-millisecond per evaluation.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.GovernanceEngine = void 0;
-const fs_1 = require("fs");
-const crypto_1 = require("crypto");
-const path_1 = require("path");
-const condition_engine_1 = require("./condition-engine");
-const world_bootstrap_1 = require("./world-bootstrap");
-// ────────────────────────────────────────────────────────────────────────
-// Default verdict (spec §4)
-// ────────────────────────────────────────────────────────────────────────
-const DEFAULT_ALLOW = {
-    status: 'ALLOW',
-    reason: 'No rules matched — default allow',
-    ruleId: null,
-    guard: null,
-    evidence: null,
-};
-const NO_WORLD = {
-    status: 'ALLOW',
-    reason: 'No world file loaded',
-    ruleId: null,
-    guard: null,
-    evidence: null,
-};
-// ────────────────────────────────────────────────────────────────────────
-// Engine
-// ────────────────────────────────────────────────────────────────────────
-class GovernanceEngine {
-    constructor(config) {
-        this.world = null;
-        // Runtime integrity state (spec §8)
-        this.worldMtimeMs = 0;
-        this.cachedWorldHash = null;
-        this.metaRecord = null;
-        this.surfacedAlerts = new Set();
-        this.workspaceDir = null;
-        this.config = config;
-    }
-    /** Set the workspace directory for md drift detection */
-    setWorkspaceDir(dir) {
-        this.workspaceDir = dir;
-    }
-    /** Clear surfaced alerts (e.g. on session reset) */
-    clearAlertHistory() {
-        this.surfacedAlerts.clear();
-    }
-    // ── World Loading ──────────────────────────────────────────────
-    loadWorld() {
-        if (!(0, fs_1.existsSync)(this.config.worldPath)) {
-            this.world = null;
-            return;
-        }
-        try {
-            const raw = (0, fs_1.readFileSync)(this.config.worldPath, 'utf-8');
-            this.world = JSON.parse(raw);
-        }
-        catch {
-            this.world = null;
-        }
-    }
-    getWorld() {
-        return this.world;
-    }
-    setWorld(world) {
-        this.world = world;
-    }
-    saveWorld() {
-        if (this.world) {
-            (0, fs_1.writeFileSync)(this.config.worldPath, JSON.stringify(this.world, null, 2));
-        }
-    }
-    getStatus() {
-        return {
-            worldLoaded: this.world !== null,
-            invariantCount: this.world?.invariants?.length ?? 0,
-            guardCount: this.world?.guards?.length ?? 0,
-            ruleCount: this.world?.rules?.length ?? 0,
-            roleCount: this.world?.roles?.length ?? 0,
-            enforcement: this.config.enforcement,
-            observeOnly: this.config.observeOnly,
-        };
-    }
-    // ── World Meta / Integrity ───────────────────────────────────
-    /** Load or create world.meta.json for integrity tracking */
-    loadMeta() {
-        const metaPath = this.getMetaPath();
-        if (!metaPath)
-            return;
-        if ((0, fs_1.existsSync)(metaPath)) {
-            try {
-                this.metaRecord = JSON.parse((0, fs_1.readFileSync)(metaPath, 'utf-8'));
-            }
-            catch {
-                this.metaRecord = null;
-            }
-        }
-        else if (this.world) {
-            // Migration: world.json exists but no meta yet (spec §16)
-            this.metaRecord = {
-                world: this.world,
-                hash: this.computeWorldHash(this.world),
-                activatedAt: Date.now(),
-                activatedBy: 'migration',
-                version: 1,
-            };
-            this.saveMeta();
-        }
-    }
-    saveMeta() {
-        const metaPath = this.getMetaPath();
-        if (!metaPath || !this.metaRecord)
-            return;
-        (0, fs_1.writeFileSync)(metaPath, JSON.stringify(this.metaRecord, null, 2));
-    }
-    getMetaRecord() {
-        return this.metaRecord;
-    }
-    setMetaRecord(record) {
-        this.metaRecord = record;
-    }
-    // ── Role Bindings (agentId → roleId) ─────────────────────────
-    /**
-     * Get all role bindings from the meta record.
-     * Returns empty array if no bindings exist.
-     */
-    getRoleBindings() {
-        return this.metaRecord?.roleBindings ?? [];
-    }
-    /**
-     * Hydrate a Map<agentId, roleId> from stored bindings.
-     * Called at startup and after any binding change.
-     */
-    hydrateRoleMap(roleMap) {
-        roleMap.clear();
-        const bindings = this.getRoleBindings();
-        for (const binding of bindings) {
-            roleMap.set(binding.agentId, binding.roleId);
-        }
-    }
-    /**
-     * Add or update a role binding. Returns the severity of the change.
-     * Does NOT auto-save — caller must call saveMeta().
-     */
-    setRoleBinding(agentId, roleId, boundBy = 'human') {
-        if (!this.metaRecord)
-            return 'new_binding';
-        if (!this.metaRecord.roleBindings) {
-            this.metaRecord.roleBindings = [];
-        }
-        const existing = this.metaRecord.roleBindings.find(b => b.agentId === agentId);
-        let severity;
-        if (!existing) {
-            severity = 'new_binding';
-            this.metaRecord.roleBindings.push({
-                agentId,
-                roleId,
-                boundAt: Date.now(),
-                boundBy,
-            });
-        }
-        else {
-            const oldRoleId = existing.roleId;
-            severity = this.classifyBindingChange(oldRoleId, roleId);
-            existing.roleId = roleId;
-            existing.boundAt = Date.now();
-            existing.boundBy = boundBy;
-        }
-        return severity;
-    }
-    /**
-     * Remove a role binding. Returns 'removal' severity.
-     * Does NOT auto-save — caller must call saveMeta().
-     */
-    removeRoleBinding(agentId) {
-        if (!this.metaRecord?.roleBindings)
-            return false;
-        const idx = this.metaRecord.roleBindings.findIndex(b => b.agentId === agentId);
-        if (idx === -1)
-            return false;
-        this.metaRecord.roleBindings.splice(idx, 1);
-        return true;
-    }
-    /**
-     * Classify the severity of changing from one role to another.
-     * Uses the role's requiresApproval and cannotDo as proxy for privilege level.
-     */
-    classifyBindingChange(oldRoleId, newRoleId) {
-        if (oldRoleId === newRoleId)
-            return 'reassignment';
-        if (!this.world)
-            return 'reassignment';
-        const oldRole = this.world.roles.find(r => r.id === oldRoleId);
-        const newRole = this.world.roles.find(r => r.id === newRoleId);
-        if (!oldRole || !newRole)
-            return 'reassignment';
-        // Privilege proxy: more cannotDo restrictions = lower privilege
-        // requiresApproval = lower privilege
-        const oldPrivilege = this.estimatePrivilege(oldRole);
-        const newPrivilege = this.estimatePrivilege(newRole);
-        if (newPrivilege > oldPrivilege)
-            return 'escalation';
-        if (newPrivilege < oldPrivilege)
-            return 'de_escalation';
-        return 'reassignment';
-    }
-    /**
-     * Estimate privilege level of a role (higher = more permissive).
-     * Simple heuristic: canDo breadth - cannotDo restrictions - approval overhead.
-     */
-    estimatePrivilege(role) {
-        let score = role.canDo.length;
-        score -= role.cannotDo.length * 2;
-        if (role.requiresApproval)
-            score -= 3;
-        return score;
-    }
-    getMetaPath() {
-        if (!this.config.worldPath)
-            return null;
-        return (0, path_1.join)((0, path_1.dirname)(this.config.worldPath), 'world.meta.json');
-    }
-    /** Canonical SHA-256 hash of a world object (sorted keys, no whitespace) */
-    computeWorldHash(world) {
-        const canonical = JSON.stringify(world, Object.keys(world).sort());
-        return (0, crypto_1.createHash)('sha256').update(canonical).digest('hex');
-    }
-    // ── Runtime Integrity Checks (spec §8) ─────────────────────
-    /**
-     * System-level protection: intercept modifications to governance source files.
-     *
-     * This runs BEFORE all user-defined rules and cannot be removed by
-     * modifying world.json. It is the engine's self-protection layer.
-     *
-     * - write_file / edit_file targeting .neuroverseos/ → BLOCK
-     * - write_file / edit_file targeting .md files → PAUSE
-     * - shell commands referencing .neuroverseos/ → BLOCK
-     *
-     * The PAUSE verdict flows through the existing interactive prompt in the
-     * before_tool_call hook. Session overrides ("always") are handled there.
-     */
-    checkGovernanceSourceProtection(event) {
-        const toolLower = event.tool.toLowerCase();
-        const targetPath = event.scope || event.args?.file_path || '';
-        const pathLower = targetPath.toLowerCase();
-        // ── File-writing tools ──────────────────────────────────
-        const isFileWrite = toolLower.includes('write') || toolLower.includes('edit');
-        if (isFileWrite && pathLower) {
-            // BLOCK: Direct modification of governance state directory
-            if (pathLower.includes('.neuroverseos')) {
-                return {
-                    status: 'BLOCK',
-                    reason: 'Direct modification of governance state is not permitted. Use /world commands to manage governance.',
-                    ruleId: 'system:governance-source-protection',
-                    guard: null,
-                    evidence: `target: ${targetPath}`,
-                    severity: 'governance',
-                };
-            }
-            // PAUSE: Modification of governance source files (.md)
-            if (pathLower.endsWith('.md')) {
-                return {
-                    status: 'PAUSE',
-                    reason: 'Governance source modification detected. Changes to .md files alter your World File on next bootstrap. If you did not request this edit, DENY it.',
-                    ruleId: 'system:governance-source-protection',
-                    guard: 'governance-source-write',
-                    evidence: `target: ${targetPath}`,
-                    severity: 'governance',
-                };
-            }
-        }
-        // ── Shell commands ──────────────────────────────────────
-        const isShell = toolLower === 'shell' || toolLower === 'bash';
-        if (isShell) {
-            const command = (event.scope || event.args?.command || '').toLowerCase();
-            // BLOCK: shell commands that target governance state directory
-            if (command.includes('.neuroverseos')) {
-                return {
-                    status: 'BLOCK',
-                    reason: 'Shell command targets governance state directory. Use /world commands to manage governance.',
-                    ruleId: 'system:governance-source-protection',
-                    guard: null,
-                    evidence: `command references .neuroverseos/`,
-                    severity: 'governance',
-                };
-            }
-        }
-        return null;
-    }
-    /**
-     * Run all integrity checks before the governance pipeline.
-     * Returns accumulated alerts. Critical alerts override the verdict.
-     */
-    checkIntegrity() {
-        const alerts = [];
-        let blocked = null;
-        // 1. Hash verification — was world.json tampered?
-        if (this.metaRecord && this.world) {
-            const hashResult = this.verifyWorldHash();
-            if (hashResult) {
-                alerts.push(hashResult);
-                blocked = {
-                    status: 'BLOCK',
-                    reason: 'World file integrity check failed. File was modified outside approval pipeline.',
-                    ruleId: 'system:integrity',
-                    guard: null,
-                    evidence: 'hash mismatch',
-                };
-            }
-        }
-        // 2. World missing — meta exists but world.json was deleted
-        if (this.metaRecord && !this.world) {
-            const alert = {
-                level: 'critical',
-                code: 'WORLD_MISSING',
-                message: 'World file was deleted outside the approval pipeline.',
-                action: 'Run /world restore to reload the last approved version.',
-            };
-            alerts.push(alert);
-            blocked = {
-                status: 'BLOCK',
-                reason: 'World file missing. Was deleted outside approval pipeline.',
-                ruleId: 'system:integrity',
-                guard: null,
-                evidence: 'world.json missing, world.meta.json present',
-            };
-        }
-        // 3. Pending world detection — non-blocking
-        if (!blocked) {
-            const pendingPath = (0, path_1.join)((0, path_1.dirname)(this.config.worldPath), 'world.pending.json');
-            if ((0, fs_1.existsSync)(pendingPath) && !this.surfacedAlerts.has('PENDING_UNAPPROVED')) {
-                alerts.push({
-                    level: 'info',
-                    code: 'PENDING_UNAPPROVED',
-                    message: 'Pending governance changes await approval.',
-                    action: 'Run /world diff to review.',
-                });
-                this.surfacedAlerts.add('PENDING_UNAPPROVED');
-            }
-        }
-        // 4. Source drift detection — non-blocking
-        if (!blocked && this.workspaceDir && this.world?.metadata?.mdHashes) {
-            const driftKey = 'SOURCE_DRIFT';
-            if (!this.surfacedAlerts.has(driftKey)) {
-                const drift = (0, world_bootstrap_1.checkMdDrift)(this.workspaceDir, this.world.metadata.mdHashes);
-                const hasDrift = drift.changed.length > 0 || drift.added.length > 0 || drift.removed.length > 0;
-                if (hasDrift) {
-                    const parts = [];
-                    if (drift.changed.length > 0)
-                        parts.push(`modified: ${drift.changed.join(', ')}`);
-                    if (drift.added.length > 0)
-                        parts.push(`new: ${drift.added.join(', ')}`);
-                    if (drift.removed.length > 0)
-                        parts.push(`removed: ${drift.removed.join(', ')}`);
-                    alerts.push({
-                        level: 'warning',
-                        code: 'SOURCE_DRIFT',
-                        message: 'Governance source files have changed since last bootstrap.',
-                        action: 'Run /world bootstrap to review.',
-                        details: parts.join('; '),
-                    });
-                    this.surfacedAlerts.add(driftKey);
-                }
-            }
-        }
-        return { alerts, blocked };
-    }
-    /**
-     * Verify world.json hash against stored hash.
-     * Uses mtime cache to avoid re-reading on every call.
-     */
-    verifyWorldHash() {
-        if (!this.metaRecord || !(0, fs_1.existsSync)(this.config.worldPath))
-            return null;
-        try {
-            const stat = (0, fs_1.statSync)(this.config.worldPath);
-            const currentMtime = stat.mtimeMs;
-            // Only re-hash if file was modified since last check
-            if (currentMtime !== this.worldMtimeMs) {
-                const raw = (0, fs_1.readFileSync)(this.config.worldPath, 'utf-8');
-                const currentWorld = JSON.parse(raw);
-                this.cachedWorldHash = this.computeWorldHash(currentWorld);
-                this.worldMtimeMs = currentMtime;
-            }
-            if (this.cachedWorldHash && this.cachedWorldHash !== this.metaRecord.hash) {
-                return {
-                    level: 'critical',
-                    code: 'TAMPERED',
-                    message: 'World file integrity check failed. Modified outside approval pipeline.',
-                    action: 'Run /world restore to reload the last approved version.',
-                    details: `expected: ${this.metaRecord.hash.slice(0, 12)}..., found: ${this.cachedWorldHash.slice(0, 12)}...`,
-                };
-            }
-        }
-        catch {
-            // File unreadable — will be caught by other checks
-        }
-        return null;
-    }
-    // ── Decision Pipeline (spec §3) ───────────────────────────────
-    /**
-     * Evaluate a tool call event against the loaded world.
-     * Returns a deterministic verdict: ALLOW, PAUSE, or BLOCK.
-     * Now includes runtime integrity checks (spec §8).
-     */
-    evaluate(event) {
-        // Step 0: System-level governance source protection (hardcoded, cannot be removed)
-        const sourceProtection = this.checkGovernanceSourceProtection(event);
-        if (sourceProtection) {
-            // Still surface any integrity alerts alongside the protection verdict
-            const { alerts } = this.checkIntegrity();
-            return alerts.length > 0 ? { ...sourceProtection, alerts } : sourceProtection;
-        }
-        // Runtime integrity checks run before governance pipeline
-        const { alerts, blocked } = this.checkIntegrity();
-        if (blocked) {
-            return { ...blocked, alerts: alerts.length > 0 ? alerts : undefined };
-        }
-        if (!this.world)
-            return NO_WORLD;
-        // Observe-only: run pipeline but always return ALLOW
-        if (this.config.observeOnly) {
-            const wouldBe = this.runPipeline(event);
-            if (wouldBe.status !== 'ALLOW') {
-                return {
-                    status: 'ALLOW',
-                    reason: `[OBSERVE] Would have been ${wouldBe.status}: ${wouldBe.reason}`,
-                    ruleId: wouldBe.ruleId,
-                    guard: wouldBe.guard,
-                    evidence: wouldBe.evidence,
-                    alerts: alerts.length > 0 ? alerts : undefined,
-                };
-            }
-            return { ...DEFAULT_ALLOW, alerts: alerts.length > 0 ? alerts : undefined };
-        }
-        const verdict = this.runPipeline(event);
-        if (alerts.length > 0) {
-            return { ...verdict, alerts };
-        }
-        return verdict;
-    }
-    /**
-     * The actual ordered pipeline. This is the core of governance.
-     */
-    runPipeline(event) {
-        const world = this.world;
-        // 1. Session allowlist — checked in index.ts before calling evaluate
-        //    (sessionOverrides on the event). We check here too for defense in depth.
-        if (event.sessionOverrides.length > 0) {
-            // Will be used by guards step — don't short-circuit entirely
-            // because invariants can never be overridden
-        }
-        // 2. Invariants — always evaluated, never overridable
-        const invariantVerdict = this.checkInvariants(event, world.invariants);
-        if (invariantVerdict)
-            return invariantVerdict;
-        // 3. Guards — scoped, condition-based
-        const guardVerdict = this.checkGuards(event, world.guards);
-        if (guardVerdict) {
-            // Check if this guard was session-overridden
-            if (world.kernel.sessionOverridesAllowed &&
-                guardVerdict.ruleId &&
-                event.sessionOverrides.includes(guardVerdict.ruleId)) {
-                return {
-                    ...DEFAULT_ALLOW,
-                    reason: `Session override for ${guardVerdict.ruleId}`,
-                };
-            }
-            return guardVerdict;
-        }
-        // 4. Rules — contextual triggers with effects
-        const ruleVerdict = this.checkRules(event, world.rules);
-        if (ruleVerdict)
-            return ruleVerdict;
-        // 5. Role constraints
-        const roleVerdict = this.checkRoles(event, world.roles);
-        if (roleVerdict)
-            return roleVerdict;
-        // 6. Default → ALLOW
-        return DEFAULT_ALLOW;
-    }
-    // ── Pipeline Steps ─────────────────────────────────────────────
-    /**
-     * Step 2: Invariants. Non-toggleable. Non-overridable. Hard BLOCK.
-     */
-    checkInvariants(event, invariants) {
-        if (!invariants?.length)
-            return null;
-        for (const inv of invariants) {
-            // Scope check
-            if (inv.scope.length > 0 && !inv.scope.includes(event.type))
-                continue;
-            const result = (0, condition_engine_1.evaluateCondition)(inv.condition, event);
-            if (result.matched) {
-                return {
-                    status: 'BLOCK',
-                    reason: inv.description,
-                    ruleId: `invariant:${inv.id}`,
-                    guard: null,
-                    evidence: result.evidence,
-                };
-            }
-        }
-        return null;
-    }
-    /**
-     * Step 3: Guards. Scoped + tool-filtered. Can PAUSE or BLOCK.
-     */
-    checkGuards(event, guards) {
-        if (!guards?.length)
-            return null;
-        for (const guard of guards) {
-            // Scope check
-            if (guard.scope.length > 0 && !guard.scope.includes(event.type))
-                continue;
-            // Tool filter — if appliesTo is set, only match those tools
-            if (guard.appliesTo.length > 0) {
-                const toolLower = event.tool.toLowerCase();
-                if (!guard.appliesTo.some(t => t.toLowerCase() === toolLower))
-                    continue;
-            }
-            const result = (0, condition_engine_1.evaluateCondition)(guard.condition, event);
-            if (result.matched) {
-                return {
-                    status: guard.enforcement === 'block' ? 'BLOCK' : 'PAUSE',
-                    reason: guard.description ?? guard.id,
-                    ruleId: `guard:${guard.id}`,
-                    guard: guard.id,
-                    evidence: result.evidence,
-                };
-            }
-        }
-        return null;
-    }
-    /**
-     * Step 4: Rules. Contextual triggers with verdict effects.
-     */
-    checkRules(event, rules) {
-        if (!rules?.length)
-            return null;
-        for (const rule of rules) {
-            const result = (0, condition_engine_1.evaluateCondition)(rule.trigger, event);
-            if (result.matched) {
-                const status = rule.effect.verdict.toUpperCase();
-                if (status !== 'ALLOW') {
-                    return {
-                        status,
-                        reason: rule.description ?? rule.id,
-                        ruleId: `rule:${rule.id}`,
-                        guard: null,
-                        evidence: result.evidence,
-                    };
-                }
-            }
-        }
-        return null;
-    }
-    /**
-     * Step 5: Role constraints. cannotDo = BLOCK, requiresApproval = PAUSE.
-     */
-    checkRoles(event, roles) {
-        if (!roles?.length || !event.role)
-            return null;
-        const role = roles.find(r => r.id === event.role || r.name.toLowerCase() === event.role?.toLowerCase());
-        if (!role)
-            return null;
-        // Check cannotDo — hard BLOCK
-        const toolLower = event.tool.toLowerCase();
-        if (role.cannotDo.some(action => toolLower.includes(action.toLowerCase()))) {
-            return {
-                status: 'BLOCK',
-                reason: `Role "${role.name}" cannot perform "${event.tool}"`,
-                ruleId: `role:${role.id}`,
-                guard: null,
-                evidence: `tool "${event.tool}" in cannotDo list`,
-            };
-        }
-        // Check requiresApproval — PAUSE
-        if (role.requiresApproval) {
-            return {
-                status: 'PAUSE',
-                reason: `Role "${role.name}" requires approval for all actions`,
-                ruleId: `role:${role.id}`,
-                guard: null,
-                evidence: `role requires approval`,
-            };
-        }
-        return null;
-    }
-    // ── Amendment Application ──────────────────────────────────────
-    /**
-     * Apply an approved amendment to the world.
-     */
-    applyAmendment(proposal) {
-        if (!this.world)
-            return;
-        switch (proposal.type) {
-            case 'add_invariant':
-                this.world.invariants.push({
-                    id: `inv-${Date.now().toString(36)}`,
-                    description: proposal.reason,
-                    scope: ['tool_call'],
-                    condition: {
-                        field: 'intent',
-                        operator: 'contains',
-                        value: proposal.suggestion.toLowerCase(),
-                    },
-                    enforcement: 'block',
-                });
-                break;
-            case 'add_guard':
-                this.world.guards.push({
-                    id: `guard-${Date.now().toString(36)}`,
-                    description: proposal.reason,
-                    scope: ['tool_call'],
-                    appliesTo: [],
-                    condition: {
-                        field: 'intent',
-                        operator: 'contains',
-                        value: proposal.suggestion.toLowerCase(),
-                    },
-                    enforcement: 'pause',
-                    requiresApproval: true,
-                });
-                break;
-            case 'add_role':
-                this.world.roles.push({
-                    id: `role-${Date.now().toString(36)}`,
-                    name: proposal.suggestion,
-                    canDo: [],
-                    cannotDo: [],
-                    requiresApproval: false,
-                });
-                break;
-            case 'modify_threshold':
-                // Convert guard enforcement from pause→block or block→pause
-                const targetGuard = this.world.guards.find(g => g.id === proposal.suggestion || g.description === proposal.suggestion);
-                if (targetGuard) {
-                    targetGuard.enforcement = targetGuard.enforcement === 'pause' ? 'block' : 'pause';
-                }
-                break;
-        }
-    }
-}
-exports.GovernanceEngine = GovernanceEngine;
-//# sourceMappingURL=governance-engine.js.map