@neuroverseos/governance 0.3.4 → 0.5.0

package/dist/{decision-flow-M63D47LO.js → decision-flow-3K4D72G4.js}

@@ -1,11 +1,11 @@
 import {
   readAuditLog
-} from "./chunk-A7GKPPU7.js";
+} from "./chunk-2VAWP6FI.js";
 import {
   generateDecisionFlow,
   renderDecisionFlow
 } from "./chunk-D2UCV5AK.js";
-import "./chunk-W7LLXRGY.js";
+import "./chunk-ZAF6JH23.js";
 import "./chunk-QLPTHTVB.js";
 import "./chunk-QWGCMQQD.js";
 

package/dist/{demo-G43RLCPK.js → demo-66MMJTEH.js}

@@ -6,7 +6,7 @@ import {
   handleListPresets,
   handleReasonRequest,
   writeTempWorld
-} from "./chunk-U6U7EJZL.js";
+} from "./chunk-JKGPSFGH.js";
 import {
   adaptationFromVerdict,
   detectBehavioralPatterns,
@@ -15,13 +15,13 @@ import {
 import {
   resolveWorldPath
 } from "./chunk-AKW5YVCE.js";
-import "./chunk-W7LLXRGY.js";
+import "./chunk-ZAF6JH23.js";
 import "./chunk-QLPTHTVB.js";
 import {
   DEFAULT_BUNDLED_WORLD,
   loadBundledWorld,
   loadWorld
-} from "./chunk-CTZHONLA.js";
+} from "./chunk-BXLTEUS4.js";
 import {
   __require
 } from "./chunk-QWGCMQQD.js";

package/dist/{derive-LMDUTXDD.js → derive-AUQE3L3P.js}

@@ -2,15 +2,15 @@ import {
   DeriveInputError,
   DeriveProviderError,
   deriveWorld
-} from "./chunk-YEKMVDWK.js";
+} from "./chunk-4G6WHPLI.js";
 import {
   DERIVE_EXIT_CODES
 } from "./chunk-FMSTRBBS.js";
-import "./chunk-OT6PXH54.js";
 import "./chunk-INWQHLPS.js";
+import "./chunk-OT6PXH54.js";
 import "./chunk-7P3S7MAY.js";
-import "./chunk-EMQDLDAF.js";
-import "./chunk-PVTQQS3Y.js";
+import "./chunk-3NZMMSOW.js";
+import "./chunk-YPCVY4GS.js";
 import "./chunk-QWGCMQQD.js";
 
 // src/cli/derive.ts
@@ -121,7 +121,7 @@ Normalization: ${n.fixCount} fix(es) applied
       process.stderr.write(`
 Bootstrapping to ${args.bootstrapDir}...
 `);
-      const { main: bootstrapMain } = await import("./bootstrap-CQRZVOXK.js");
+      const { main: bootstrapMain } = await import("./bootstrap-IP5QMC3Q.js");
       await bootstrapMain([
         "--input",
         result.outputPath,

package/dist/{doctor-6BC6X2VO.js → doctor-EY7LKSYY.js}

@@ -12,6 +12,7 @@ var globImport_adapters = __glob({
   "../adapters/express.ts": () => import("./adapters/express.js"),
   "../adapters/index.ts": () => import("./adapters/index.js"),
   "../adapters/langchain.ts": () => import("./adapters/langchain.js"),
+  "../adapters/mentraos.ts": () => import("./mentraos-LLH7KEV4.js"),
   "../adapters/openai.ts": () => import("./adapters/openai.js"),
   "../adapters/openclaw.ts": () => import("./adapters/openclaw.js"),
   "../adapters/shared.ts": () => import("./shared-7RLUHNMU.js")
@@ -103,7 +104,7 @@ async function main(argv) {
     });
   }
   try {
-    const { evaluateGuard } = await import("./guard-engine-PNR6MHCM.js");
+    const { evaluateGuard } = await import("./guard-engine-N7TUIUU7.js");
     checks.push({
       label: "Guard engine",
       status: typeof evaluateGuard === "function" ? "pass" : "fail",

package/dist/{equity-penalties-SG5IZQ7I.js → equity-penalties-WWC7UDQD.js}

@@ -1,6 +1,6 @@
 import {
   verdictToAuditEvent
-} from "./chunk-A7GKPPU7.js";
+} from "./chunk-2VAWP6FI.js";
 import {
   applyConsequence,
   applyReward,
@@ -11,11 +11,11 @@ import {
 } from "./chunk-D2UCV5AK.js";
 import {
   evaluateGuard
-} from "./chunk-W7LLXRGY.js";
+} from "./chunk-ZAF6JH23.js";
 import "./chunk-QLPTHTVB.js";
 import {
   loadWorld
-} from "./chunk-CTZHONLA.js";
+} from "./chunk-BXLTEUS4.js";
 import "./chunk-QWGCMQQD.js";
 
 // src/cli/equity-penalties.ts

package/dist/{explain-RHBU2GBR.js → explain-MUSGDT67.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-ZJTDUCC2.js";
 import {
   loadWorld
-} from "./chunk-CTZHONLA.js";
+} from "./chunk-BXLTEUS4.js";
 import "./chunk-QWGCMQQD.js";
 
 // src/cli/explain.ts

package/dist/{guard-AEEJNWLD.js → guard-W3BMQPBJ.js}

@@ -4,7 +4,7 @@ import {
 import {
   GUARD_EXIT_CODES,
   evaluateGuardWithAI
-} from "./chunk-VXHSMA3I.js";
+} from "./chunk-6CV4XG3J.js";
 import "./chunk-INWQHLPS.js";
 import {
   describeActiveWorld,
@@ -12,11 +12,11 @@ import {
 } from "./chunk-AKW5YVCE.js";
 import {
   evaluateGuard
-} from "./chunk-W7LLXRGY.js";
+} from "./chunk-ZAF6JH23.js";
 import "./chunk-QLPTHTVB.js";
 import {
   loadWorld
-} from "./chunk-CTZHONLA.js";
+} from "./chunk-BXLTEUS4.js";
 import "./chunk-QWGCMQQD.js";
 
 // src/cli/guard.ts

package/dist/{guard-contract-B7lplwm9.d.ts → guard-contract-CLBbTGK_.d.cts}

@@ -231,6 +231,8 @@ interface WorldRoleDefinition {
     requiresApproval?: boolean;
     trackedOutcomes?: string[];
     ownedRules?: string[];
+    /** Default lens for this role (references a lens id from the world's lenses config) */
+    defaultLens?: string;
 }
 type RoleAssignment = 'dynamic' | 'per_session' | 'permanent';
 interface RoleTransition {
@@ -292,6 +294,63 @@ interface GuardsConfig {
      *  governing guard — surfaces without guards are reported as fail-open. */
     tool_surfaces?: string[];
 }
+/**
+ * A governance event — the bridge between Guard and Simulate.
+ *
+ * Guard produces events (what happened).
+ * Simulate consumes events (what changes because of it).
+ *
+ * Events are NOT stored — they flow through the system.
+ * Guard evaluation log IS the event stream.
+ */
+interface GovernanceEvent {
+    /** Semantic event type: "complaint", "refund", "action_blocked", etc. */
+    type: string;
+    /** Who caused this event */
+    actor?: 'customer' | 'agent' | 'system';
+    /** Where the event originated */
+    source: 'guard' | 'manual' | 'system';
+    /** Unix timestamp (ms) */
+    timestamp: number;
+    /** Guard status that produced this event (when source=guard) */
+    guardStatus?: 'ALLOW' | 'BLOCK' | 'PAUSE' | 'MODIFY' | 'PENALIZE' | 'REWARD' | 'NEUTRAL';
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+interface LensDirectiveConfig {
+    id: string;
+    scope: 'response_framing' | 'language_style' | 'content_filtering' | 'value_emphasis' | 'behavior_shaping';
+    instruction: string;
+}
+interface LensConfig {
+    id: string;
+    name: string;
+    tagline: string;
+    description: string;
+    tags: string[];
+    tone: {
+        formality: 'casual' | 'neutral' | 'formal' | 'professional';
+        verbosity: 'terse' | 'concise' | 'balanced' | 'detailed';
+        emotion: 'warm' | 'neutral' | 'reserved' | 'clinical';
+        confidence: 'humble' | 'balanced' | 'authoritative' | 'assertive';
+    };
+    directives: LensDirectiveConfig[];
+    defaultForRoles: string[];
+    priority: number;
+    stackable: boolean;
+}
+interface LensesConfig {
+    lenses: LensConfig[];
+    /**
+     * Lens policy:
+     * - 'locked': lenses are assigned by role, user cannot change without pin
+     * - 'role_default': lenses start as role default, user can override
+     * - 'user_choice': no default, user picks freely
+     */
+    policy?: 'locked' | 'role_default' | 'user_choice';
+    /** Pin required to change lenses when policy is 'locked' */
+    lockPin?: string;
+}
 interface WorldDefinition {
     world: WorldIdentity;
     invariants: Invariant[];
@@ -303,6 +362,7 @@ interface WorldDefinition {
     guards?: GuardsConfig;
     roles?: RolesConfig;
     kernel?: KernelConfig;
+    lenses?: LensesConfig;
     enforcement?: string;
     metadata: WorldMetadata;
 }
@@ -681,6 +741,9 @@ interface GuardVerdict {
     intentRecord?: IntentRecord;
     /** Audit evidence — always present */
     evidence: VerdictEvidence;
+    /** Governance event emitted by this evaluation — always present.
+     *  This is the bridge to Simulate: Guard → Event → State Evolution. */
+    event?: GovernanceEvent;
     /** Evaluation trace — present when trace mode is enabled */
     trace?: EvaluationTrace;
 }
@@ -821,6 +884,33 @@ interface GuardEngineOptions {
      * The caller owns mutation (applying consequences/rewards after verdict).
      */
     agentStates?: Map<string, AgentBehaviorState>;
+    /**
+     * Emergency override — the user is king.
+     *
+     * When active, the governance engine returns ALLOW for every action.
+     * All rules are bypassed. The user gets access to every tool the
+     * platform permits.
+     *
+     * What this overrides:
+     *   - Spatial governance (public space camera blocks, bystander rules)
+     *   - Multi-wearer handshake composition
+     *   - Role restrictions, level constraints, plan enforcement
+     *   - Behavioral penalties (cooldowns, freezes)
+     *
+     * What this CANNOT override:
+     *   - Platform-enforced constraints (MentraOS SDK permission declarations,
+     *     hardware capability matrix, session isolation, credential scope)
+     *   - Physical impossibility (no camera on glasses without camera hardware)
+     *
+     * The override removes the governance layer, not the platform layer.
+     * Every action taken during override is still logged to the audit trail
+     * with emergency_override: true for accountability.
+     *
+     * Design: the user is king. In a life-threatening situation, governance
+     * steps aside. The audit trail is the accountability mechanism, not
+     * the block.
+     */
+    emergencyOverride?: boolean;
 }
 declare const GUARD_EXIT_CODES: {
     readonly ALLOW: 0;
@@ -834,4 +924,4 @@ declare const GUARD_EXIT_CODES: {
 };
 type GuardExitCode = (typeof GUARD_EXIT_CODES)[keyof typeof GUARD_EXIT_CODES];
 
-export { type AdvanceResult as A, type Consequence as C, type EvaluationTrace as E, type GuardEvent as G, type Invariant as I, type KernelRuleCheck as K, type LevelCheck as L, type PlanDefinition as P, type Reward as R, type StepEvidence as S, type ViabilityStatus as V, type WorldDefinition as W, type GuardVerdict as a, type GuardEngineOptions as b, type PlanProgress as c, type PlanVerdict as d, type PlanCheck as e, type AgentBehaviorState as f, type GuardStatus as g, type Guard as h, type Rule as i, GUARD_EXIT_CODES as j, type GuardCheck as k, type GuardExitCode as l, type IntentRecord as m, type InvariantCheck as n, PLAN_EXIT_CODES as o, type PlanCompletionMode as p, type PlanConstraint as q, type PlanExitCode as r, type PlanStatus as s, type PlanStep as t, type PrecedenceResolution as u, type RoleCheck as v, type SafetyCheck as w, type VerdictEvidence as x };
+export { type AdvanceResult as A, type Consequence as C, type EvaluationTrace as E, type GuardEvent as G, type Invariant as I, type KernelRuleCheck as K, type LevelCheck as L, type PlanDefinition as P, type Reward as R, type StepEvidence as S, type ViabilityStatus as V, type WorldDefinition as W, type GuardVerdict as a, type GuardEngineOptions as b, type PlanProgress as c, type GuardStatus as d, type GovernanceEvent as e, type PlanVerdict as f, type PlanCheck as g, type AgentBehaviorState as h, type Guard as i, type Rule as j, GUARD_EXIT_CODES as k, type GuardCheck as l, type GuardExitCode as m, type IntentRecord as n, type InvariantCheck as o, PLAN_EXIT_CODES as p, type PlanCompletionMode as q, type PlanConstraint as r, type PlanExitCode as s, type PlanStatus as t, type PlanStep as u, type PrecedenceResolution as v, type RoleCheck as w, type SafetyCheck as x, type VerdictEvidence as y };

package/dist/{guard-contract-B7lplwm9.d.cts → guard-contract-CLBbTGK_.d.ts}

@@ -231,6 +231,8 @@ interface WorldRoleDefinition {
     requiresApproval?: boolean;
     trackedOutcomes?: string[];
     ownedRules?: string[];
+    /** Default lens for this role (references a lens id from the world's lenses config) */
+    defaultLens?: string;
 }
 type RoleAssignment = 'dynamic' | 'per_session' | 'permanent';
 interface RoleTransition {
@@ -292,6 +294,63 @@ interface GuardsConfig {
      *  governing guard — surfaces without guards are reported as fail-open. */
     tool_surfaces?: string[];
 }
+/**
+ * A governance event — the bridge between Guard and Simulate.
+ *
+ * Guard produces events (what happened).
+ * Simulate consumes events (what changes because of it).
+ *
+ * Events are NOT stored — they flow through the system.
+ * Guard evaluation log IS the event stream.
+ */
+interface GovernanceEvent {
+    /** Semantic event type: "complaint", "refund", "action_blocked", etc. */
+    type: string;
+    /** Who caused this event */
+    actor?: 'customer' | 'agent' | 'system';
+    /** Where the event originated */
+    source: 'guard' | 'manual' | 'system';
+    /** Unix timestamp (ms) */
+    timestamp: number;
+    /** Guard status that produced this event (when source=guard) */
+    guardStatus?: 'ALLOW' | 'BLOCK' | 'PAUSE' | 'MODIFY' | 'PENALIZE' | 'REWARD' | 'NEUTRAL';
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+interface LensDirectiveConfig {
+    id: string;
+    scope: 'response_framing' | 'language_style' | 'content_filtering' | 'value_emphasis' | 'behavior_shaping';
+    instruction: string;
+}
+interface LensConfig {
+    id: string;
+    name: string;
+    tagline: string;
+    description: string;
+    tags: string[];
+    tone: {
+        formality: 'casual' | 'neutral' | 'formal' | 'professional';
+        verbosity: 'terse' | 'concise' | 'balanced' | 'detailed';
+        emotion: 'warm' | 'neutral' | 'reserved' | 'clinical';
+        confidence: 'humble' | 'balanced' | 'authoritative' | 'assertive';
+    };
+    directives: LensDirectiveConfig[];
+    defaultForRoles: string[];
+    priority: number;
+    stackable: boolean;
+}
+interface LensesConfig {
+    lenses: LensConfig[];
+    /**
+     * Lens policy:
+     * - 'locked': lenses are assigned by role, user cannot change without pin
+     * - 'role_default': lenses start as role default, user can override
+     * - 'user_choice': no default, user picks freely
+     */
+    policy?: 'locked' | 'role_default' | 'user_choice';
+    /** Pin required to change lenses when policy is 'locked' */
+    lockPin?: string;
+}
 interface WorldDefinition {
     world: WorldIdentity;
     invariants: Invariant[];
@@ -303,6 +362,7 @@ interface WorldDefinition {
     guards?: GuardsConfig;
     roles?: RolesConfig;
     kernel?: KernelConfig;
+    lenses?: LensesConfig;
     enforcement?: string;
     metadata: WorldMetadata;
 }
@@ -681,6 +741,9 @@ interface GuardVerdict {
     intentRecord?: IntentRecord;
     /** Audit evidence — always present */
     evidence: VerdictEvidence;
+    /** Governance event emitted by this evaluation — always present.
+     *  This is the bridge to Simulate: Guard → Event → State Evolution. */
+    event?: GovernanceEvent;
     /** Evaluation trace — present when trace mode is enabled */
     trace?: EvaluationTrace;
 }
@@ -821,6 +884,33 @@ interface GuardEngineOptions {
      * The caller owns mutation (applying consequences/rewards after verdict).
      */
     agentStates?: Map<string, AgentBehaviorState>;
+    /**
+     * Emergency override — the user is king.
+     *
+     * When active, the governance engine returns ALLOW for every action.
+     * All rules are bypassed. The user gets access to every tool the
+     * platform permits.
+     *
+     * What this overrides:
+     *   - Spatial governance (public space camera blocks, bystander rules)
+     *   - Multi-wearer handshake composition
+     *   - Role restrictions, level constraints, plan enforcement
+     *   - Behavioral penalties (cooldowns, freezes)
+     *
+     * What this CANNOT override:
+     *   - Platform-enforced constraints (MentraOS SDK permission declarations,
+     *     hardware capability matrix, session isolation, credential scope)
+     *   - Physical impossibility (no camera on glasses without camera hardware)
+     *
+     * The override removes the governance layer, not the platform layer.
+     * Every action taken during override is still logged to the audit trail
+     * with emergency_override: true for accountability.
+     *
+     * Design: the user is king. In a life-threatening situation, governance
+     * steps aside. The audit trail is the accountability mechanism, not
+     * the block.
+     */
+    emergencyOverride?: boolean;
 }
 declare const GUARD_EXIT_CODES: {
     readonly ALLOW: 0;
@@ -834,4 +924,4 @@ declare const GUARD_EXIT_CODES: {
 };
 type GuardExitCode = (typeof GUARD_EXIT_CODES)[keyof typeof GUARD_EXIT_CODES];
 
-export { type AdvanceResult as A, type Consequence as C, type EvaluationTrace as E, type GuardEvent as G, type Invariant as I, type KernelRuleCheck as K, type LevelCheck as L, type PlanDefinition as P, type Reward as R, type StepEvidence as S, type ViabilityStatus as V, type WorldDefinition as W, type GuardVerdict as a, type GuardEngineOptions as b, type PlanProgress as c, type PlanVerdict as d, type PlanCheck as e, type AgentBehaviorState as f, type GuardStatus as g, type Guard as h, type Rule as i, GUARD_EXIT_CODES as j, type GuardCheck as k, type GuardExitCode as l, type IntentRecord as m, type InvariantCheck as n, PLAN_EXIT_CODES as o, type PlanCompletionMode as p, type PlanConstraint as q, type PlanExitCode as r, type PlanStatus as s, type PlanStep as t, type PrecedenceResolution as u, type RoleCheck as v, type SafetyCheck as w, type VerdictEvidence as x };
+export { type AdvanceResult as A, type Consequence as C, type EvaluationTrace as E, type GuardEvent as G, type Invariant as I, type KernelRuleCheck as K, type LevelCheck as L, type PlanDefinition as P, type Reward as R, type StepEvidence as S, type ViabilityStatus as V, type WorldDefinition as W, type GuardVerdict as a, type GuardEngineOptions as b, type PlanProgress as c, type GuardStatus as d, type GovernanceEvent as e, type PlanVerdict as f, type PlanCheck as g, type AgentBehaviorState as h, type Guard as i, type Rule as j, GUARD_EXIT_CODES as k, type GuardCheck as l, type GuardExitCode as m, type IntentRecord as n, type InvariantCheck as o, PLAN_EXIT_CODES as p, type PlanCompletionMode as q, type PlanConstraint as r, type PlanExitCode as s, type PlanStatus as t, type PlanStep as u, type PrecedenceResolution as v, type RoleCheck as w, type SafetyCheck as x, type VerdictEvidence as y };

package/dist/{guard-engine-PNR6MHCM.js → guard-engine-N7TUIUU7.js}

@@ -1,10 +1,12 @@
 import {
   evaluateGuard,
-  eventToAllowlistKey
-} from "./chunk-W7LLXRGY.js";
+  eventToAllowlistKey,
+  verdictToEvent
+} from "./chunk-ZAF6JH23.js";
 import "./chunk-QLPTHTVB.js";
 import "./chunk-QWGCMQQD.js";
 export {
   evaluateGuard,
-  eventToAllowlistKey
+  eventToAllowlistKey,
+  verdictToEvent
 };

package/dist/{impact-3XVDSCBU.js → impact-WIAM66IH.js}

@@ -1,11 +1,11 @@
 import {
   generateImpactReport,
   renderImpactReport
-} from "./chunk-TG6SEF24.js";
+} from "./chunk-OQU65525.js";
 import {
   readAuditLog
-} from "./chunk-A7GKPPU7.js";
-import "./chunk-W7LLXRGY.js";
+} from "./chunk-2VAWP6FI.js";
+import "./chunk-ZAF6JH23.js";
 import "./chunk-QLPTHTVB.js";
 import "./chunk-QWGCMQQD.js";
 

package/dist/{improve-TQP4ECSY.js → improve-PJDAWW4Q.js}

@@ -4,12 +4,12 @@ import {
 import {
   improveWorld,
   renderImproveText
-} from "./chunk-F66BVUYB.js";
+} from "./chunk-Y6WXAPKY.js";
+import "./chunk-7QIAF377.js";
 import "./chunk-7P3S7MAY.js";
-import "./chunk-ZWI3NIXK.js";
 import {
   loadWorld
-} from "./chunk-CTZHONLA.js";
+} from "./chunk-BXLTEUS4.js";
 import "./chunk-QWGCMQQD.js";
 
 // src/cli/improve.ts