@neuroverseos/governance 0.10.0 → 0.12.0

package/dist/admin/index.cjs

@@ -322,8 +322,26 @@ function isExternalScope(scope) {
   ];
   return !internalPatterns.some((p) => p.test(scope));
 }
-var MAX_INPUT_LENGTH = 1e5;
 function evaluateGuard(event, world, options = {}) {
+  const verdict = evaluateGuardCore(event, world, options);
+  return options.mode === "observe" ? toShadowVerdict(verdict) : verdict;
+}
+function toShadowVerdict(verdict) {
+  if (verdict.status === "ALLOW") return verdict;
+  return {
+    ...verdict,
+    status: "ALLOW",
+    shadowStatus: verdict.status,
+    shadowReason: verdict.reason,
+    // Preserve the original reason as shadowReason and wipe the
+    // top-level reason so callers that display `reason` for BLOCK/PAUSE
+    // don't accidentally surface an enforcement message.
+    reason: void 0,
+    warning: verdict.reason ? `Observe mode: would have ${verdict.status.toLowerCase()} \u2014 ${verdict.reason}` : `Observe mode: would have ${verdict.status.toLowerCase()}`
+  };
+}
+var MAX_INPUT_LENGTH = 1e5;
+function evaluateGuardCore(event, world, options = {}) {
   const startTime = performance.now();
   const level = options.level ?? "standard";
   const includeTrace = options.trace ?? false;

package/dist/admin/index.js

@@ -3,7 +3,7 @@ import {
 } from "../chunk-GJ6LM4JZ.js";
 import {
   evaluateGuard
-} from "../chunk-ZAF6JH23.js";
+} from "../chunk-MBOW6YXN.js";
 import "../chunk-QLPTHTVB.js";
 import "../chunk-QWGCMQQD.js";
 

package/dist/audit-JYNN3MOQ.js

@@ -0,0 +1,98 @@
+import {
+  readStdin
+} from "./chunk-BQZMOEML.js";
+import {
+  resolveWorldPath
+} from "./chunk-AKW5YVCE.js";
+import {
+  loadWorld
+} from "./chunk-I4RTIMLX.js";
+import {
+  evaluateGuard
+} from "./chunk-MBOW6YXN.js";
+import "./chunk-QLPTHTVB.js";
+import "./chunk-QWGCMQQD.js";
+
+// src/cli/audit.ts
+function parseArgs(argv) {
+  let worldPath = "";
+  let trace = false;
+  let level;
+  let multi = false;
+  let crossingsOnly = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--world") worldPath = argv[++i] ?? "";
+    else if (a === "--trace") trace = true;
+    else if (a === "--level") {
+      const v = argv[++i];
+      if (v === "basic" || v === "standard" || v === "strict") level = v;
+    } else if (a === "--multi") multi = true;
+    else if (a === "--crossings-only") crossingsOnly = true;
+  }
+  return { worldPath, trace, level, multi, crossingsOnly };
+}
+function usage() {
+  process.stderr.write(
+    "Usage: neuroverse audit --world <path> [--trace] [--level basic|standard|strict] [--multi] [--crossings-only]\n\nReads GuardEvent JSON from stdin. With --multi, reads a JSON array.\nEvaluates in observe mode \u2014 no enforcement. Verdicts carry\nshadowStatus/shadowReason for any event that would have crossed.\n"
+  );
+}
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (!args.worldPath) {
+    usage();
+    process.exit(1);
+  }
+  let world;
+  try {
+    const resolved = resolveWorldPath(args.worldPath);
+    if (!resolved) {
+      process.stderr.write(`Failed to resolve world path: ${args.worldPath}
+`);
+      process.exit(1);
+    }
+    world = await loadWorld(resolved);
+  } catch (err) {
+    process.stderr.write(`Failed to load world: ${err instanceof Error ? err.message : err}
+`);
+    process.exit(1);
+  }
+  let raw = "";
+  try {
+    raw = await readStdin();
+  } catch (err) {
+    process.stderr.write(`Failed to read stdin: ${err instanceof Error ? err.message : err}
+`);
+    process.exit(1);
+  }
+  if (!raw.trim()) {
+    process.stderr.write("No input on stdin. Pipe a GuardEvent or a JSON array with --multi.\n");
+    process.exit(1);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    process.stderr.write(`Invalid JSON on stdin: ${err instanceof Error ? err.message : err}
+`);
+    process.exit(1);
+  }
+  const options = { trace: args.trace, level: args.level, mode: "observe" };
+  if (args.multi) {
+    if (!Array.isArray(parsed)) {
+      process.stderr.write("--multi expects a JSON array on stdin.\n");
+      process.exit(1);
+    }
+    const verdicts = parsed.map(
+      (e) => evaluateGuard(e, world, options)
+    );
+    const out = args.crossingsOnly ? verdicts.filter((v) => v.shadowStatus && v.shadowStatus !== "ALLOW") : verdicts;
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    return;
+  }
+  const verdict = evaluateGuard(parsed, world, options);
+  process.stdout.write(JSON.stringify(verdict, null, 2) + "\n");
+}
+export {
+  main
+};

package/dist/audit-behavior-C62FdRAC.d.cts

@@ -0,0 +1,100 @@
+import { d as GuardStatus, G as GuardVerdict } from './guard-contract-Oznf-Kgq.cjs';
+import { WorldDefinition } from './types.cjs';
+
+/**
+ * @neuroverseos/governance — auditBehavior
+ *
+ * Takes an observed event (from the Radiant pipeline: a commit, a PR, a
+ * Slack message, a Notion edit) and evaluates it against a worldmodel in
+ * observe mode — without any enforcement side effects. Returns the shadow
+ * verdict so callers can record crossings of declared invariants.
+ *
+ * This is the primitive that lets Bevia / Radiant / Mirror-Mode tooling
+ * show leaders where their worldmodel is being bumped against, without
+ * imposing any stop/pause/modify semantics on the team's work.
+ *
+ * Relationship to evaluateGuard:
+ *
+ *   evaluateGuard({ intent, ... }, world, { mode: 'enforce' })
+ *     → what an AI agent receives when governance says "BLOCK this action"
+ *
+ *   evaluateGuard({ intent, ... }, world, { mode: 'observe' })
+ *     → what tooling like Bevia receives when governance says "this would
+ *        have been blocked if enforced, but pass through and record"
+ *
+ *   auditBehavior(event, world)
+ *     → convenience on top of the observe path that (a) maps a
+ *        behavioral event into a synthetic GuardEvent, (b) calls
+ *        evaluateGuard in observe mode, and (c) returns a Crossing
+ *        record shaped for behavioral logs.
+ *
+ * The mapping from behavioral events to GuardEvents is intentionally
+ * conservative: we use the event's `kind` as the tool, its `content` as
+ * the intent, and pass through timestamp + actor as metadata. Callers
+ * that want richer mappings (classifying event semantics into tool
+ * namespaces, etc.) can construct a GuardEvent directly and call
+ * evaluateGuard themselves.
+ */
+
+/**
+ * Minimal shape an observed event needs to be auditable. Matches the
+ * Radiant `Event` type's relevant fields but doesn't require importing
+ * the full radiant domain module — keeps auditBehavior consumable by any
+ * adapter that emits events.
+ */
+interface AuditableEvent {
+    /** Source-system-unique id (e.g. "github-push-abc123", "slack-msg-789"). */
+    id: string;
+    /** ISO 8601. */
+    timestamp: string;
+    /** Free-form kind tag from the adapter — 'commit', 'pr_opened', 'chat_message', etc. */
+    kind?: string;
+    /** Textual content of the event — commit message, PR body, chat text, etc. */
+    content?: string;
+    /** Actor id that produced the event. */
+    actorId?: string;
+    /** Actor kind — 'human' | 'ai' | 'bot' | 'unknown'. */
+    actorKind?: string;
+    /** Optional repo / channel / page reference, passed through as GuardEvent.scope. */
+    scope?: string;
+}
+/**
+ * A single crossing record — an observed event that would have triggered
+ * a non-ALLOW verdict if the world were running in enforce mode.
+ *
+ * When `wouldHaveBlocked` is `false`, the event passed all layers cleanly
+ * and no crossing occurred. Crossing records are most useful when
+ * `wouldHaveBlocked` is `true` — that's a moment the leader said they
+ * cared about, and here's evidence their team bumped into it.
+ */
+interface Crossing {
+    eventId: string;
+    timestamp: string;
+    kind?: string;
+    actorId?: string;
+    /** The status the engine would have returned in enforce mode. */
+    shadowStatus: GuardStatus;
+    /** Human-readable reason the shadow verdict fired. */
+    shadowReason?: string;
+    /** Rule or guard id that produced the shadow verdict. */
+    ruleId?: string;
+    /** Shortened quote of the event content — useful for a crossings panel. */
+    excerpt?: string;
+    /** True when the engine would have blocked/paused/etc. in enforce mode. */
+    wouldHaveBlocked: boolean;
+    /** Full verdict in case callers want the complete object. */
+    verdict: GuardVerdict;
+}
+/**
+ * Evaluate a single behavioral event against a world in observe mode.
+ */
+declare function auditBehavior(event: AuditableEvent, world: WorldDefinition): Crossing;
+/**
+ * Convenience: audit a whole stream of events. Returns one Crossing per
+ * event; the caller can filter `wouldHaveBlocked` to get only the
+ * interesting ones. Deterministic — same events + same world = same
+ * crossings, every time.
+ */
+declare function auditBehaviors(events: AuditableEvent[], world: WorldDefinition): Crossing[];
+
+export { type AuditableEvent as A, type Crossing as C, auditBehavior as a, auditBehaviors as b };

package/dist/audit-behavior-DFy7LeYv.d.ts

@@ -0,0 +1,100 @@
+import { d as GuardStatus, G as GuardVerdict } from './guard-contract-w_i_6gh-.js';
+import { WorldDefinition } from './types.js';
+
+/**
+ * @neuroverseos/governance — auditBehavior
+ *
+ * Takes an observed event (from the Radiant pipeline: a commit, a PR, a
+ * Slack message, a Notion edit) and evaluates it against a worldmodel in
+ * observe mode — without any enforcement side effects. Returns the shadow
+ * verdict so callers can record crossings of declared invariants.
+ *
+ * This is the primitive that lets Bevia / Radiant / Mirror-Mode tooling
+ * show leaders where their worldmodel is being bumped against, without
+ * imposing any stop/pause/modify semantics on the team's work.
+ *
+ * Relationship to evaluateGuard:
+ *
+ *   evaluateGuard({ intent, ... }, world, { mode: 'enforce' })
+ *     → what an AI agent receives when governance says "BLOCK this action"
+ *
+ *   evaluateGuard({ intent, ... }, world, { mode: 'observe' })
+ *     → what tooling like Bevia receives when governance says "this would
+ *        have been blocked if enforced, but pass through and record"
+ *
+ *   auditBehavior(event, world)
+ *     → convenience on top of the observe path that (a) maps a
+ *        behavioral event into a synthetic GuardEvent, (b) calls
+ *        evaluateGuard in observe mode, and (c) returns a Crossing
+ *        record shaped for behavioral logs.
+ *
+ * The mapping from behavioral events to GuardEvents is intentionally
+ * conservative: we use the event's `kind` as the tool, its `content` as
+ * the intent, and pass through timestamp + actor as metadata. Callers
+ * that want richer mappings (classifying event semantics into tool
+ * namespaces, etc.) can construct a GuardEvent directly and call
+ * evaluateGuard themselves.
+ */
+
+/**
+ * Minimal shape an observed event needs to be auditable. Matches the
+ * Radiant `Event` type's relevant fields but doesn't require importing
+ * the full radiant domain module — keeps auditBehavior consumable by any
+ * adapter that emits events.
+ */
+interface AuditableEvent {
+    /** Source-system-unique id (e.g. "github-push-abc123", "slack-msg-789"). */
+    id: string;
+    /** ISO 8601. */
+    timestamp: string;
+    /** Free-form kind tag from the adapter — 'commit', 'pr_opened', 'chat_message', etc. */
+    kind?: string;
+    /** Textual content of the event — commit message, PR body, chat text, etc. */
+    content?: string;
+    /** Actor id that produced the event. */
+    actorId?: string;
+    /** Actor kind — 'human' | 'ai' | 'bot' | 'unknown'. */
+    actorKind?: string;
+    /** Optional repo / channel / page reference, passed through as GuardEvent.scope. */
+    scope?: string;
+}
+/**
+ * A single crossing record — an observed event that would have triggered
+ * a non-ALLOW verdict if the world were running in enforce mode.
+ *
+ * When `wouldHaveBlocked` is `false`, the event passed all layers cleanly
+ * and no crossing occurred. Crossing records are most useful when
+ * `wouldHaveBlocked` is `true` — that's a moment the leader said they
+ * cared about, and here's evidence their team bumped into it.
+ */
+interface Crossing {
+    eventId: string;
+    timestamp: string;
+    kind?: string;
+    actorId?: string;
+    /** The status the engine would have returned in enforce mode. */
+    shadowStatus: GuardStatus;
+    /** Human-readable reason the shadow verdict fired. */
+    shadowReason?: string;
+    /** Rule or guard id that produced the shadow verdict. */
+    ruleId?: string;
+    /** Shortened quote of the event content — useful for a crossings panel. */
+    excerpt?: string;
+    /** True when the engine would have blocked/paused/etc. in enforce mode. */
+    wouldHaveBlocked: boolean;
+    /** Full verdict in case callers want the complete object. */
+    verdict: GuardVerdict;
+}
+/**
+ * Evaluate a single behavioral event against a world in observe mode.
+ */
+declare function auditBehavior(event: AuditableEvent, world: WorldDefinition): Crossing;
+/**
+ * Convenience: audit a whole stream of events. Returns one Crossing per
+ * event; the caller can filter `wouldHaveBlocked` to get only the
+ * interesting ones. Deterministic — same events + same world = same
+ * crossings, every time.
+ */
+declare function auditBehaviors(events: AuditableEvent[], world: WorldDefinition): Crossing[];
+
+export { type AuditableEvent as A, type Crossing as C, auditBehavior as a, auditBehaviors as b };

package/dist/{behavioral-SPWPGYXL.js → behavioral-4TKMHZQZ.js}

@@ -5,8 +5,8 @@ import {
 } from "./chunk-CNSO6XW5.js";
 import {
   readAuditLog
-} from "./chunk-2VAWP6FI.js";
-import "./chunk-ZAF6JH23.js";
+} from "./chunk-RAS62JXV.js";
+import "./chunk-MBOW6YXN.js";
 import "./chunk-QLPTHTVB.js";
 import "./chunk-QWGCMQQD.js";
 

package/dist/{chunk-OQU65525.js → chunk-24YW7BHC.js}

@@ -1,6 +1,6 @@
 import {
   readAuditLog
-} from "./chunk-2VAWP6FI.js";
+} from "./chunk-RAS62JXV.js";
 
 // src/engine/impact-report.ts
 function generateImpactReport(events) {

package/dist/{chunk-BZYQHJDM.js → chunk-2KTPIE57.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/radiant/core/compress.ts
 function compressWorldmodel(content) {
@@ -1830,6 +1830,7 @@ async function auditGovernance(events, worldPath) {
     return emptyAudit(events.length, "Could not load compiled worldmodel for governance audit.");
   }
   const verdicts = [];
+  const crossings = [];
   for (const ce of events) {
     const intent = ce.event.content?.slice(0, 500) || ce.event.kind || "activity";
     const scope = ce.event.metadata?.scope || void 0;
@@ -1840,16 +1841,32 @@ async function auditGovernance(events, worldPath) {
           scope,
           actionCategory: mapKindToCategory(ce.event.kind)
         },
-        world
+        world,
+        { mode: "observe" }
       );
+      const shadow = result.shadowStatus ?? "ALLOW";
       verdicts.push({
         eventId: ce.event.id,
         domain: ce.domain,
-        status: result.status,
-        reason: result.reason,
+        status: shadow,
+        reason: result.shadowReason,
         ruleId: result.ruleId,
         warning: result.warning
       });
+      if (shadow !== "ALLOW") {
+        crossings.push({
+          eventId: ce.event.id,
+          timestamp: ce.event.timestamp,
+          kind: ce.event.kind,
+          actorId: ce.event.actor.id,
+          shadowStatus: shadow,
+          shadowReason: result.shadowReason,
+          ruleId: result.ruleId,
+          excerpt: intent.length > 280 ? intent.slice(0, 279) + "\u2026" : intent,
+          wouldHaveBlocked: true,
+          verdict: result
+        });
+      }
     } catch {
       verdicts.push({
         eventId: ce.event.id,
@@ -1868,6 +1885,7 @@ async function auditGovernance(events, worldPath) {
     human,
     cyber,
     joint,
+    crossings,
     summary
   };
 }
@@ -1923,6 +1941,7 @@ function emptyAudit(total, reason) {
     human: { allow: 0, modify: 0, block: 0, details: [] },
     cyber: { allow: 0, modify: 0, block: 0, details: [] },
     joint: { allow: 0, modify: 0, block: 0, details: [] },
+    crossings: [],
     summary: reason
   };
 }
@@ -2899,7 +2918,8 @@ Compare stated intent against actual GitHub activity. Gaps = drift.`;
     scores,
     eventCount: events.length,
     activeAdapters,
-    worldStack
+    worldStack,
+    governance
   };
 }
 function filterEventsByUser(events, username) {

package/dist/{chunk-TJ5L2UTE.js → chunk-5K3LATTM.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/adapters/autoresearch.ts
 var AutoresearchGovernor = class {

package/dist/{chunk-HDNDL6D5.js → chunk-5LDBYOSJ.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/adapters/express.ts
 function methodToCategory(method) {

package/dist/{chunk-FDPPZLSQ.js → chunk-5ZWKM7MO.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 import {
   advancePlan,
   evaluatePlan,

package/dist/{chunk-B3IIPTY3.js → chunk-6MB6TMAG.js}

@@ -10,7 +10,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/adapters/openai.ts
 var GovernanceBlockedError2 = class extends GovernanceBlockedError {

package/dist/{chunk-IOVXB6QN.js → chunk-GXTAHCND.js}

@@ -12,7 +12,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/adapters/mentraos.ts
 var DEFAULT_USER_RULES = {

package/dist/{chunk-FKQCPRKI.js → chunk-MAOIHKFO.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/adapters/langchain.ts
 var GovernanceBlockedError2 = class extends GovernanceBlockedError {

package/dist/{chunk-ZAF6JH23.js → chunk-MBOW6YXN.js}

@@ -89,8 +89,26 @@ function isExternalScope(scope) {
   ];
   return !internalPatterns.some((p) => p.test(scope));
 }
-var MAX_INPUT_LENGTH = 1e5;
 function evaluateGuard(event, world, options = {}) {
+  const verdict = evaluateGuardCore(event, world, options);
+  return options.mode === "observe" ? toShadowVerdict(verdict) : verdict;
+}
+function toShadowVerdict(verdict) {
+  if (verdict.status === "ALLOW") return verdict;
+  return {
+    ...verdict,
+    status: "ALLOW",
+    shadowStatus: verdict.status,
+    shadowReason: verdict.reason,
+    // Preserve the original reason as shadowReason and wipe the
+    // top-level reason so callers that display `reason` for BLOCK/PAUSE
+    // don't accidentally surface an enforcement message.
+    reason: void 0,
+    warning: verdict.reason ? `Observe mode: would have ${verdict.status.toLowerCase()} \u2014 ${verdict.reason}` : `Observe mode: would have ${verdict.status.toLowerCase()}`
+  };
+}
+var MAX_INPUT_LENGTH = 1e5;
+function evaluateGuardCore(event, world, options = {}) {
   const startTime = performance.now();
   const level = options.level ?? "standard";
   const includeTrace = options.trace ?? false;

package/dist/{chunk-A2UZTLRV.js → chunk-MLXKSX3L.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/adapters/github.ts
 var GitHubGovernanceBlockedError = class extends GovernanceBlockedError {

package/dist/{chunk-7FL3U7Z5.js → chunk-MWGEXHOD.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/runtime/govern.ts
 function actionToGuardEvent(action) {

package/dist/{chunk-6CV4XG3J.js → chunk-QFDFAWZ6.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-INWQHLPS.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/engine/intent-classifier.ts
 function buildSystemPrompt(knownIntents) {

package/dist/{chunk-2VAWP6FI.js → chunk-RAS62JXV.js}

@@ -1,6 +1,6 @@
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/engine/audit-logger.ts
 var FileAuditLogger = class {

package/dist/{chunk-OTZU76DH.js → chunk-XAF3CYCW.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 import {
   advancePlan,
   evaluatePlan,

package/dist/{chunk-T6GMRZWC.js → chunk-XTYQCTDD.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/engine/tool-classifier.ts
 var TOOL_CATEGORY_MAP = {

package/dist/{chunk-TIXVEPS2.js → chunk-YN7OI5ZV.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-I4RTIMLX.js";
 import {
   evaluateGuard
-} from "./chunk-ZAF6JH23.js";
+} from "./chunk-MBOW6YXN.js";
 
 // src/adapters/openclaw.ts
 var GovernanceBlockedError2 = class extends GovernanceBlockedError {