@neuroverseos/governance 0.9.0 → 0.11.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-CRJOB4CP.js

@@ -0,0 +1,93 @@
+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);
+    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) {