@neuroverseos/governance 0.1.0

package/dist/drift-monitor.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * Drift Monitor — Background service tracking governance health
+ *
+ * Tracks:
+ *   - Block frequency (are we blocking too much? too little?)
+ *   - Manual overrides (humans overriding PAUSE decisions)
+ *   - Tool friction (which tools cause the most governance friction?)
+ *   - Rule friction (which rules fire most often?)
+ *
+ * Can also read from audit.jsonl for historical analysis.
+ * Stored in .neuroverseos/state.json — separate from MEMORY.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriftMonitor = void 0;
+const fs_1 = require("fs");
+// ────────────────────────────────────────────────────────────────────────
+// Monitor
+// ────────────────────────────────────────────────────────────────────────
+class DriftMonitor {
+    constructor(config) {
+        this.saveInterval = null;
+        this.config = config;
+        this.state = this.loadState();
+    }
+    start() {
+        this.saveInterval = setInterval(() => this.saveState(), 30000);
+    }
+    stop() {
+        if (this.saveInterval) {
+            clearInterval(this.saveInterval);
+            this.saveInterval = null;
+        }
+        this.saveState();
+    }
+    /**
+     * Record an action and its governance verdict.
+     */
+    recordAction(tool, verdict, ruleId) {
+        this.state.totalActions++;
+        switch (verdict) {
+            case 'ALLOW':
+                this.state.allowCount++;
+                break;
+            case 'PAUSE':
+                this.state.pauseCount++;
+                break;
+            case 'BLOCK':
+                this.state.blockCount++;
+                break;
+        }
+        // Tool friction
+        if (!this.state.toolFriction[tool]) {
+            this.state.toolFriction[tool] = { blocks: 0, pauses: 0, allows: 0 };
+        }
+        const tf = this.state.toolFriction[tool];
+        if (verdict === 'BLOCK')
+            tf.blocks++;
+        else if (verdict === 'PAUSE')
+            tf.pauses++;
+        else
+            tf.allows++;
+        // Rule friction
+        if (ruleId) {
+            this.state.ruleFriction[ruleId] = (this.state.ruleFriction[ruleId] ?? 0) + 1;
+        }
+        this.state.lastUpdated = Date.now();
+    }
+    /**
+     * Record when a human overrides a PAUSE decision.
+     */
+    recordOverride() {
+        this.state.overrideCount++;
+    }
+    /**
+     * Get current drift statistics.
+     */
+    getStats() {
+        const total = this.state.totalActions || 1;
+        const blockRate = this.state.blockCount / total;
+        const pauseRate = this.state.pauseCount / total;
+        const overrideRate = this.state.pauseCount > 0
+            ? this.state.overrideCount / this.state.pauseCount
+            : 0;
+        const driftSignals = [];
+        if (blockRate > 0.3) {
+            driftSignals.push(`High block rate (${(blockRate * 100).toFixed(1)}%) — governance may be too strict`);
+        }
+        if (overrideRate > 0.5 && this.state.pauseCount >= 5) {
+            driftSignals.push(`High override rate (${(overrideRate * 100).toFixed(1)}%) — world rules may need amendment`);
+        }
+        for (const [tool, friction] of Object.entries(this.state.toolFriction)) {
+            const toolTotal = friction.blocks + friction.pauses + friction.allows;
+            const toolBlockRate = friction.blocks / Math.max(toolTotal, 1);
+            if (toolBlockRate > 0.5 && toolTotal >= 3) {
+                driftSignals.push(`Tool "${tool}" blocked ${(toolBlockRate * 100).toFixed(0)}% of the time`);
+            }
+        }
+        if (total > 20 && blockRate === 0 && pauseRate === 0) {
+            driftSignals.push('Zero blocks or pauses — governance may be too permissive');
+        }
+        return {
+            totalActions: this.state.totalActions,
+            allowCount: this.state.allowCount,
+            pauseCount: this.state.pauseCount,
+            blockCount: this.state.blockCount,
+            blockRate,
+            pauseRate,
+            overrideRate,
+            driftSignals,
+        };
+    }
+    /**
+     * Generate amendment proposals based on drift patterns.
+     */
+    generateProposals() {
+        const proposals = [];
+        const stats = this.getStats();
+        // High override rate → suggest loosening specific guards
+        if (stats.overrideRate > 0.5 && this.state.pauseCount >= 5) {
+            const topRule = Object.entries(this.state.ruleFriction)
+                .sort(([, a], [, b]) => b - a)[0];
+            if (topRule) {
+                proposals.push({
+                    type: 'modify_threshold',
+                    reason: `Rule "${topRule[0]}" triggered ${topRule[1]} times with ${(stats.overrideRate * 100).toFixed(0)}% override rate`,
+                    suggestion: topRule[0],
+                    evidence: `${(stats.overrideRate * 100).toFixed(0)}% of pauses were manually overridden`,
+                });
+            }
+        }
+        // Tool constantly blocked → suggest more nuanced guard
+        for (const [tool, friction] of Object.entries(this.state.toolFriction)) {
+            const total = friction.blocks + friction.pauses + friction.allows;
+            if (friction.blocks > 5 && friction.blocks / total > 0.7) {
+                proposals.push({
+                    type: 'add_guard',
+                    reason: `Tool "${tool}" is blocked ${friction.blocks} out of ${total} times`,
+                    suggestion: `Add granular guard for "${tool}" that allows safe patterns and blocks dangerous ones`,
+                    evidence: `${tool}: ${friction.blocks} blocks, ${friction.pauses} pauses, ${friction.allows} allows`,
+                });
+            }
+        }
+        // Zero governance firing → suggest adding guards
+        if (this.state.totalActions > 20 && stats.blockRate === 0 && stats.pauseRate === 0) {
+            proposals.push({
+                type: 'add_guard',
+                reason: 'No governance constraints have fired in over 20 actions',
+                suggestion: 'Consider adding guards for destructive operations, external communication, or production access',
+                evidence: `${this.state.totalActions} actions with 0 blocks and 0 pauses`,
+            });
+        }
+        return proposals;
+    }
+    /**
+     * Rebuild stats from the audit log (for historical analysis).
+     */
+    rebuildFromAudit() {
+        if (!(0, fs_1.existsSync)(this.config.auditPath))
+            return;
+        try {
+            const raw = (0, fs_1.readFileSync)(this.config.auditPath, 'utf-8');
+            const lines = raw.split('\n').filter(l => l.trim());
+            // Reset state
+            this.state = this.freshState();
+            let decisionCount = 0;
+            for (const line of lines) {
+                try {
+                    const entry = JSON.parse(line);
+                    // Decision entries
+                    if (entry.type === 'decision') {
+                        const dec = entry;
+                        if (dec.decision === 'allow-once' || dec.decision === 'allow-always') {
+                            decisionCount++;
+                        }
+                        continue;
+                    }
+                    // Verdict entries
+                    const verdict = entry;
+                    this.recordAction(verdict.tool, verdict.status, verdict.ruleId ?? undefined);
+                }
+                catch {
+                    continue;
+                }
+            }
+            this.state.overrideCount = decisionCount;
+            this.saveState();
+        }
+        catch {
+            // Silent failure
+        }
+    }
+    // ── Persistence ────────────────────────────────────────────────
+    loadState() {
+        if ((0, fs_1.existsSync)(this.config.statePath)) {
+            try {
+                return JSON.parse((0, fs_1.readFileSync)(this.config.statePath, 'utf-8'));
+            }
+            catch {
+                // Corrupted state — start fresh
+            }
+        }
+        return this.freshState();
+    }
+    freshState() {
+        return {
+            totalActions: 0,
+            allowCount: 0,
+            pauseCount: 0,
+            blockCount: 0,
+            overrideCount: 0,
+            toolFriction: {},
+            ruleFriction: {},
+            lastUpdated: Date.now(),
+            sessionStart: Date.now(),
+        };
+    }
+    saveState() {
+        try {
+            (0, fs_1.writeFileSync)(this.config.statePath, JSON.stringify(this.state, null, 2));
+        }
+        catch {
+            // Silent failure — don't crash on state save
+        }
+    }
+}
+exports.DriftMonitor = DriftMonitor;
+//# sourceMappingURL=drift-monitor.js.map

package/dist/drift-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-monitor.js","sourceRoot":"","sources":["../drift-monitor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAEH,2BAA6D;AA4C7D,2EAA2E;AAC3E,UAAU;AACV,2EAA2E;AAE3E,MAAa,YAAY;IAKvB,YAAY,MAA0B;QAF9B,iBAAY,GAA0C,IAAI,CAAC;QAGjE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,KAAM,CAAC,CAAC;IAClE,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACjC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,SAAS,EAAE,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,IAAY,EAAE,OAAoC,EAAE,MAAe;QAC9E,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;QAE1B,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,OAAO;gBACV,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;gBACxB,MAAM;YACR,KAAK,OAAO;gBACV,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;gBACxB,MAAM;YACR,KAAK,OAAO;gBACV,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;gBACxB,MAAM;QACV,CAAC;QAED,gBAAgB;QAChB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QACtE,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,OAAO,KAAK,OAAO;YAAE,EAAE,CAAC,MAAM,EAAE,CAAC;aAChC,IAAI,OAAO,KAAK,OAAO;YAAE,EAAE,CAAC,MAAM,EAAE,CAAC;;YACrC,EAAE,CAAC,MAAM,EAAE,CAAC;QAEjB,gBAAgB;QAChB,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC/E,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC;QAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC;QAChD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC;QAChD,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC;YAC5C,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU;YAClD,CAAC,CAAC,CAAC,CAAC;QAEN,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,IAAI,SAAS,GAAG,GAAG,EAAE,CAAC;YACpB,YAAY,CAAC,IAAI,CAAC,oBAAoB,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,mCAAmC,CAAC,CAAC;QACzG,CAAC;QAED,IAAI,YAAY,GAAG,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;YACrD,YAAY,CAAC,IAAI,CAAC,uBAAuB,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,qCAAqC,CAAC,CAAC;QACjH,CAAC;QAED,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;YACvE,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;YACtE,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;YAC/D,IAAI,aAAa,GAAG,GAAG,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;gBAC1C,YAAY,CAAC,IAAI,CAAC,SAAS,IAAI,aAAa,CAAC,aAAa,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;YAC/F,CAAC;QACH,CAAC;QAED,IAAI,KAAK,GAAG,EAAE,IAAI,SAAS,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;YACrD,YAAY,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;QAChF,CAAC;QAED,OAAO;YACL,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY;YACrC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU;YACjC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU;YACjC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU;YACjC,SAAS;YACT,SAAS;YACT,YAAY;YACZ,YAAY;SACb,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,iBAAiB;QACf,MAAM,SAAS,GAAoB,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QAE9B,yDAAyD;QACzD,IAAI,KAAK,CAAC,YAAY,GAAG,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;YAC3D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC;iBACpD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAEpC,IAAI,OAAO,EAAE,CAAC;gBACZ,SAAS,CAAC,IAAI,CAAC;oBACb,IAAI,EAAE,kBAAkB;oBACxB,MAAM,EAAE,SAAS,OAAO,CAAC,CAAC,CAAC,eAAe,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB;oBACzH,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;oBACtB,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,sCAAsC;iBACzF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,uDAAuD;QACvD,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;YACvE,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;YAClE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,KAAK,GAAG,GAAG,EAAE,CAAC;gBACzD,SAAS,CAAC,IAAI,CAAC;oBACb,IAAI,EAAE,WAAW;oBACjB,MAAM,EAAE,SAAS,IAAI,gBAAgB,QAAQ,CAAC,MAAM,WAAW,KAAK,QAAQ;oBAC5E,UAAU,EAAE,2BAA2B,IAAI,uDAAuD;oBAClG,QAAQ,EAAE,GAAG,IAAI,KAAK,QAAQ,CAAC,MAAM,YAAY,QAAQ,CAAC,MAAM,YAAY,QAAQ,CAAC,MAAM,SAAS;iBACrG,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,iDAAiD;QACjD,IAAI,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,EAAE,IAAI,KAAK,CAAC,SAAS,KAAK,CAAC,IAAI,KAAK,CAAC,SAAS,KAAK,CAAC,EAAE,CAAC;YACnF,SAAS,CAAC,IAAI,CAAC;gBACb,IAAI,EAAE,WAAW;gBACjB,MAAM,EAAE,yDAAyD;gBACjE,UAAU,EAAE,iGAAiG;gBAC7G,QAAQ,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,qCAAqC;aAC1E,CAAC,CAAC;QACL,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,gBAAgB;QACd,IAAI,CAAC,IAAA,eAAU,EAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;YAAE,OAAO;QAE/C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAA,iBAAY,EAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACzD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAEpD,cAAc;YACd,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAE/B,IAAI,aAAa,GAAG,CAAC,CAAC;YAEtB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBAE/B,mBAAmB;oBACnB,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;wBAC9B,MAAM,GAAG,GAAG,KAA2B,CAAC;wBACxC,IAAI,GAAG,CAAC,QAAQ,KAAK,YAAY,IAAI,GAAG,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;4BACrE,aAAa,EAAE,CAAC;wBAClB,CAAC;wBACD,SAAS;oBACX,CAAC;oBAED,kBAAkB;oBAClB,MAAM,OAAO,GAAG,KAAmB,CAAC;oBACpC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC;gBAC/E,CAAC;gBAAC,MAAM,CAAC;oBACP,SAAS;gBACX,CAAC;YACH,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,aAAa,CAAC;YACzC,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,iBAAiB;QACnB,CAAC;IACH,CAAC;IAED,kEAAkE;IAE1D,SAAS;QACf,IAAI,IAAA,eAAU,EAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAA,iBAAY,EAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;YAClE,CAAC;YAAC,MAAM,CAAC;gBACP,gCAAgC;YAClC,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC3B,CAAC;IAEO,UAAU;QAChB,OAAO;YACL,YAAY,EAAE,CAAC;YACf,UAAU,EAAE,CAAC;YACb,UAAU,EAAE,CAAC;YACb,UAAU,EAAE,CAAC;YACb,aAAa,EAAE,CAAC;YAChB,YAAY,EAAE,EAAE;YAChB,YAAY,EAAE,EAAE;YAChB,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;YACvB,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE;SACzB,CAAC;IACJ,CAAC;IAEO,SAAS;QACf,IAAI,CAAC;YACH,IAAA,kBAAa,EAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,6CAA6C;QAC/C,CAAC;IACH,CAAC;CACF;AA1OD,oCA0OC"}

package/dist/governance-engine.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+import type { GovernanceWorld, GovernanceVerdict, ActiveWorldRecord, RoleBinding, BindingChangeSeverity, ToolCallEvent, EngineConfig, EngineStatus } from './types';
+export declare class GovernanceEngine {
+    private config;
+    private world;
+    private worldMtimeMs;
+    private cachedWorldHash;
+    private metaRecord;
+    private surfacedAlerts;
+    private workspaceDir;
+    constructor(config: EngineConfig);
+    /** Set the workspace directory for md drift detection */
+    setWorkspaceDir(dir: string): void;
+    /** Clear surfaced alerts (e.g. on session reset) */
+    clearAlertHistory(): void;
+    loadWorld(): void;
+    getWorld(): GovernanceWorld | null;
+    setWorld(world: GovernanceWorld): void;
+    saveWorld(): void;
+    getStatus(): EngineStatus;
+    /** Load or create world.meta.json for integrity tracking */
+    loadMeta(): void;
+    saveMeta(): void;
+    getMetaRecord(): ActiveWorldRecord | null;
+    setMetaRecord(record: ActiveWorldRecord): void;
+    /**
+     * Get all role bindings from the meta record.
+     * Returns empty array if no bindings exist.
+     */
+    getRoleBindings(): RoleBinding[];
+    /**
+     * Hydrate a Map<agentId, roleId> from stored bindings.
+     * Called at startup and after any binding change.
+     */
+    hydrateRoleMap(roleMap: Map<string, string>): void;
+    /**
+     * Add or update a role binding. Returns the severity of the change.
+     * Does NOT auto-save — caller must call saveMeta().
+     */
+    setRoleBinding(agentId: string, roleId: string, boundBy?: RoleBinding['boundBy']): BindingChangeSeverity;
+    /**
+     * Remove a role binding. Returns 'removal' severity.
+     * Does NOT auto-save — caller must call saveMeta().
+     */
+    removeRoleBinding(agentId: string): boolean;
+    /**
+     * Classify the severity of changing from one role to another.
+     * Uses the role's requiresApproval and cannotDo as proxy for privilege level.
+     */
+    private classifyBindingChange;
+    /**
+     * Estimate privilege level of a role (higher = more permissive).
+     * Simple heuristic: canDo breadth - cannotDo restrictions - approval overhead.
+     */
+    private estimatePrivilege;
+    private getMetaPath;
+    /** Canonical SHA-256 hash of a world object (sorted keys, no whitespace) */
+    computeWorldHash(world: GovernanceWorld): string;
+    /**
+     * 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.
+     */
+    private checkGovernanceSourceProtection;
+    /**
+     * Run all integrity checks before the governance pipeline.
+     * Returns accumulated alerts. Critical alerts override the verdict.
+     */
+    private checkIntegrity;
+    /**
+     * Verify world.json hash against stored hash.
+     * Uses mtime cache to avoid re-reading on every call.
+     */
+    private verifyWorldHash;
+    /**
+     * 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: ToolCallEvent): GovernanceVerdict;
+    /**
+     * The actual ordered pipeline. This is the core of governance.
+     */
+    private runPipeline;
+    /**
+     * Step 2: Invariants. Non-toggleable. Non-overridable. Hard BLOCK.
+     */
+    private checkInvariants;
+    /**
+     * Step 3: Guards. Scoped + tool-filtered. Can PAUSE or BLOCK.
+     */
+    private checkGuards;
+    /**
+     * Step 4: Rules. Contextual triggers with verdict effects.
+     */
+    private checkRules;
+    /**
+     * Step 5: Role constraints. cannotDo = BLOCK, requiresApproval = PAUSE.
+     */
+    private checkRoles;
+    /**
+     * Apply an approved amendment to the world.
+     */
+    applyAmendment(proposal: {
+        type: 'add_guard' | 'modify_threshold' | 'add_role' | 'add_invariant';
+        suggestion: string;
+        reason: string;
+    }): void;
+}
+//# sourceMappingURL=governance-engine.d.ts.map

package/dist/governance-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance-engine.d.ts","sourceRoot":"","sources":["../governance-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAEjB,iBAAiB,EACjB,WAAW,EACX,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,YAAY,EACb,MAAM,SAAS,CAAC;AA0BjB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,KAAK,CAAgC;IAG7C,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,cAAc,CAA0B;IAChD,OAAO,CAAC,YAAY,CAAuB;gBAE/B,MAAM,EAAE,YAAY;IAIhC,yDAAyD;IACzD,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIlC,oDAAoD;IACpD,iBAAiB,IAAI,IAAI;IAMzB,SAAS,IAAI,IAAI;IAajB,QAAQ,IAAI,eAAe,GAAG,IAAI;IAIlC,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAItC,SAAS,IAAI,IAAI;IAMjB,SAAS,IAAI,YAAY;IAczB,4DAA4D;IAC5D,QAAQ,IAAI,IAAI;IAuBhB,QAAQ,IAAI,IAAI;IAMhB,aAAa,IAAI,iBAAiB,GAAG,IAAI;IAIzC,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAM9C;;;OAGG;IACH,eAAe,IAAI,WAAW,EAAE;IAIhC;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAQlD;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,WAAW,CAAC,SAAS,CAAW,GAAG,qBAAqB;IA6BjH;;;OAGG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQ3C;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,WAAW;IAKnB,4EAA4E;IAC5E,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM;IAOhD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,+BAA+B;IAuDvC;;;OAGG;IACH,OAAO,CAAC,cAAc;IA6EtB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAiCvB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,iBAAiB;IAyCjD;;OAEG;IACH,OAAO,CAAC,WAAW;IA6CnB;;OAEG;IACH,OAAO,CAAC,eAAe;IAyBvB;;OAEG;IACH,OAAO,CAAC,WAAW;IA+BnB;;OAEG;IACH,OAAO,CAAC,UAAU;IAyBlB;;OAEG;IACH,OAAO,CAAC,UAAU;IAqClB;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE;QACvB,IAAI,EAAE,WAAW,GAAG,kBAAkB,GAAG,UAAU,GAAG,eAAe,CAAC;QACtE,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KAChB,GAAG,IAAI;CAuDT"}