@neuroverseos/governance 0.4.0 → 0.4.1

package/dist/adapters/autoresearch.d.cts

@@ -1,4 +1,5 @@
-import { W as WorldDefinition, G as GuardEvent, a as GuardVerdict } from '../guard-contract-CLBbTGK_.cjs';
+import { G as GuardEvent, a as GuardVerdict } from '../guard-contract-C991HDZp.cjs';
+import { WorldDefinition } from '../types.cjs';
 
 /**
  * Autoresearch Adapter — Bridge between NeuroVerse governance and autoresearch loops

package/dist/adapters/autoresearch.d.ts

@@ -1,4 +1,5 @@
-import { W as WorldDefinition, G as GuardEvent, a as GuardVerdict } from '../guard-contract-CLBbTGK_.js';
+import { G as GuardEvent, a as GuardVerdict } from '../guard-contract-hHjTTjtR.js';
+import { WorldDefinition } from '../types.js';
 
 /**
  * Autoresearch Adapter — Bridge between NeuroVerse governance and autoresearch loops

package/dist/adapters/autoresearch.js

@@ -1,10 +1,10 @@
 import {
   AutoresearchGovernor,
   createAutoresearchGovernor
-} from "../chunk-YNYCQECH.js";
+} from "../chunk-QMVQ6KPL.js";
 import "../chunk-ZAF6JH23.js";
+import "../chunk-I4RTIMLX.js";
 import "../chunk-QLPTHTVB.js";
-import "../chunk-BXLTEUS4.js";
 import "../chunk-QWGCMQQD.js";
 export {
   AutoresearchGovernor,

package/dist/adapters/deep-agents.d.cts

@@ -1,5 +1,6 @@
-import { b as GuardEngineOptions, P as PlanDefinition, W as WorldDefinition, a as GuardVerdict, G as GuardEvent, c as PlanProgress } from '../guard-contract-CLBbTGK_.cjs';
-import { G as GovernanceBlockedError$1 } from '../shared-BGzmYP5g.cjs';
+import { b as GuardEngineOptions, P as PlanDefinition, a as GuardVerdict, G as GuardEvent, c as PlanProgress } from '../guard-contract-C991HDZp.cjs';
+import { WorldDefinition } from '../types.cjs';
+import { G as GovernanceBlockedError$1 } from '../shared-DGnn1jiS.cjs';
 
 /**
  * Centralized Tool Classification & Risk Pattern Detection

package/dist/adapters/deep-agents.d.ts

@@ -1,5 +1,6 @@
-import { b as GuardEngineOptions, P as PlanDefinition, W as WorldDefinition, a as GuardVerdict, G as GuardEvent, c as PlanProgress } from '../guard-contract-CLBbTGK_.js';
-import { G as GovernanceBlockedError$1 } from '../shared-CwGpPheR.js';
+import { b as GuardEngineOptions, P as PlanDefinition, a as GuardVerdict, G as GuardEvent, c as PlanProgress } from '../guard-contract-hHjTTjtR.js';
+import { WorldDefinition } from '../types.js';
+import { G as GovernanceBlockedError$1 } from '../shared-U405h52W.js';
 
 /**
  * Centralized Tool Classification & Risk Pattern Detection

package/dist/adapters/deep-agents.js

@@ -3,11 +3,11 @@ import {
   GovernanceBlockedError,
   createDeepAgentsGuard,
   createDeepAgentsGuardFromWorld
-} from "../chunk-DWHUZUEY.js";
+} from "../chunk-YJ34R5NB.js";
 import "../chunk-5U2MQO5P.js";
 import "../chunk-ZAF6JH23.js";
+import "../chunk-I4RTIMLX.js";
 import "../chunk-QLPTHTVB.js";
-import "../chunk-BXLTEUS4.js";
 import "../chunk-QWGCMQQD.js";
 export {
   DeepAgentsGuard,

package/dist/adapters/express.d.cts

@@ -1,4 +1,5 @@
-import { a as GuardVerdict, G as GuardEvent, W as WorldDefinition } from '../guard-contract-CLBbTGK_.cjs';
+import { a as GuardVerdict, G as GuardEvent } from '../guard-contract-C991HDZp.cjs';
+import { WorldDefinition } from '../types.cjs';
 
 /**
  * NeuroVerse Adapter — Express / Fastify

package/dist/adapters/express.d.ts

@@ -1,4 +1,5 @@
-import { a as GuardVerdict, G as GuardEvent, W as WorldDefinition } from '../guard-contract-CLBbTGK_.js';
+import { a as GuardVerdict, G as GuardEvent } from '../guard-contract-hHjTTjtR.js';
+import { WorldDefinition } from '../types.js';
 
 /**
  * NeuroVerse Adapter — Express / Fastify

package/dist/adapters/express.js

@@ -1,10 +1,10 @@
 import {
   createGovernanceMiddleware,
   createGovernanceMiddlewareFromWorld
-} from "../chunk-25XHSTPT.js";
+} from "../chunk-RDA7ISWC.js";
 import "../chunk-ZAF6JH23.js";
+import "../chunk-I4RTIMLX.js";
 import "../chunk-QLPTHTVB.js";
-import "../chunk-BXLTEUS4.js";
 import "../chunk-QWGCMQQD.js";
 export {
   createGovernanceMiddleware,

package/dist/adapters/index.cjs

@@ -2779,6 +2779,7 @@ var MentraGovernedExecutor = class {
   _userRules;
   _emergencyOverride = false;
   _emergencyActivatedAt = null;
+  _spatialSession = null;
   constructor(world, options = {}, userRules = DEFAULT_USER_RULES) {
     this.world = world;
     this.options = options;
@@ -2835,13 +2836,36 @@ var MentraGovernedExecutor = class {
   get emergencyActivatedAt() {
     return this._emergencyActivatedAt;
   }
+  // ── Spatial Governance (optional) ────────────────────────────────────────
+  /**
+   * Attach a spatial session to this executor.
+   *
+   * When attached, intents are evaluated against the spatial context
+   * (zone rules + handshake rules) AFTER user rules but BEFORE
+   * hardware and platform checks. This is Layer 1.5.
+   *
+   * Pass null to detach (e.g., when leaving a zone).
+   */
+  setSpatialSession(session) {
+    this._spatialSession = session;
+  }
+  /** Whether a spatial session is currently active */
+  get hasSpatialSession() {
+    return this._spatialSession !== null;
+  }
+  /** Get the current spatial session description */
+  get spatialDescription() {
+    return this._spatialSession?.description ?? null;
+  }
   /**
    * Evaluate an intent against user rules + platform world.
    *
    * Three-layer evaluation:
-   *   0. Emergency override — if active, skip governance (layers 1 + 3),
+   *   0. Emergency override — if active, skip governance (layers 1 + 1.5 + 3),
    *      but STILL enforce platform constraints (layer 2)
    *   1. User rules check — personal governance override, can BLOCK or PAUSE
+   *   1.5. Spatial governance — zone + handshake rules (optional, temporary)
+   *      ↑ ONLY ACTIVE when a spatial session is attached
    *   2. Hardware capability check — validates glasses support
    *      ↑ THIS IS A PLATFORM CONSTRAINT — never overridden
    *   3. Platform guard engine — full world rule evaluation
@@ -2872,6 +2896,47 @@ var MentraGovernedExecutor = class {
         return result2;
       }
     }
+    if (!this._emergencyOverride && this._spatialSession) {
+      const spatialResult = this._spatialSession.evaluate(intent);
+      if (!spatialResult.allowed && !spatialResult.requiresConfirmation) {
+        const verdict2 = {
+          status: "BLOCK",
+          ruleId: "spatial-zone-rule",
+          reason: spatialResult.reason,
+          evidence: makeEvidence("spatial-zone-rule")
+        };
+        const result2 = {
+          allowed: false,
+          requiresConfirmation: false,
+          verdict: verdict2,
+          intentDef,
+          appContext,
+          decidingLayer: "spatial"
+        };
+        this.options.onBlock?.(result2);
+        this.options.onEvaluate?.(result2);
+        return result2;
+      }
+      if (spatialResult.requiresConfirmation) {
+        const verdict2 = {
+          status: "PAUSE",
+          ruleId: "spatial-zone-rule",
+          reason: spatialResult.reason,
+          evidence: makeEvidence("spatial-zone-rule")
+        };
+        const result2 = {
+          allowed: false,
+          requiresConfirmation: true,
+          verdict: verdict2,
+          intentDef,
+          appContext,
+          decidingLayer: "spatial"
+        };
+        this.options.onPause?.(result2);
+        this.options.onEvaluate?.(result2);
+        return result2;
+      }
+    }
     if (intentDef && glassesModel && !intentDef.supported_glasses.includes(glassesModel)) {
       const verdict2 = {
         status: "BLOCK",

package/dist/adapters/index.d.cts

@@ -1,284 +1,10 @@
-export { B as BaseAdapterOptions, G as GovernanceBlockedError, G as MentraGovernanceBlockedError, P as PlanTrackingCallbacks, a as PlanTrackingState, b as buildEngineOptions, d as defaultBlockMessage, e as extractScope, t as trackPlanProgress } from '../shared-BGzmYP5g.cjs';
+export { B as BaseAdapterOptions, G as GovernanceBlockedError, G as MentraGovernanceBlockedError, P as PlanTrackingCallbacks, a as PlanTrackingState, b as buildEngineOptions, d as defaultBlockMessage, e as extractScope, t as trackPlanProgress } from '../shared-DGnn1jiS.cjs';
 export { GovernanceBlockedError as LangChainGovernanceBlockedError, NeuroVerseCallbackHandler, NeuroVerseHandlerOptions, createNeuroVerseCallbackHandler, createNeuroVerseCallbackHandlerFromWorld } from './langchain.cjs';
 export { GovernedExecutorOptions, GovernedToolExecutor, GovernedToolResult, GovernanceBlockedError as OpenAIGovernanceBlockedError, OpenAIToolCall, createGovernedToolExecutor, createGovernedToolExecutorFromWorld } from './openai.cjs';
 export { AgentAction, HookResult, NeuroVersePlugin, NeuroVersePluginOptions, GovernanceBlockedError as OpenClawGovernanceBlockedError, createNeuroVersePlugin, createNeuroVersePluginFromWorld } from './openclaw.cjs';
 export { GovernanceMiddlewareOptions, GovernanceRequest, GovernanceResponse, createGovernanceMiddleware, createGovernanceMiddlewareFromWorld } from './express.cjs';
 export { AutoresearchGovernor, AutoresearchGovernorConfig, ExperimentProposal, ExperimentResult, ResearchState } from './autoresearch.cjs';
 export { GovernanceBlockedError as DeepAgentsGovernanceBlockedError, DeepAgentsGuard, DeepAgentsGuardOptions, DeepAgentsGuardResult, DeepAgentsToolCall, DeepAgentsToolCategory, createDeepAgentsGuard, createDeepAgentsGuardFromWorld } from './deep-agents.cjs';
-import { a as GuardVerdict, P as PlanDefinition, c as PlanProgress, W as WorldDefinition } from '../guard-contract-CLBbTGK_.cjs';
-
-/**
- * MentraOS Intent Taxonomy — Canonical Intent-to-SDK Mapping
- *
- * This is the contract between NeuroVerse governance and the MentraOS platform.
- * Every user action that touches hardware, data, AI processing, or session
- * state must map to exactly one intent in this taxonomy. The guard engine
- * evaluates intents, not natural language.
- *
- * Two categories of intents:
- *   1. Hardware intents — SDK methods that access glasses hardware
- *   2. AI interaction intents — data flows to AI APIs, AI actions on
- *      behalf of the user, AI data retention decisions
- *
- * Flow:
- *   User speech → classifyIntentWithAI(knownIntents) → MentraIntent
- *   → evaluateGuard(event, world) → verdict → MentraOS SDK call (or block)
- *
- * Design rules:
- *   - One intent per SDK method or AI action type. No ambiguity.
- *   - Intent names are snake_case, prefixed by domain.
- *   - Every intent declares which MentraOS permission it requires.
- *   - Every intent declares which glasses support it.
- *   - AI intents use 'NONE' permission (they operate at the app server layer).
- *   - The taxonomy is the single source of truth for governance coverage.
- */
-interface MentraIntentDefinition {
-    /** Canonical intent identifier (e.g., "camera_photo_capture") */
-    intent: string;
-    /** Human-readable description of what this intent does */
-    description: string;
-    /** MentraOS SDK method(s) this maps to */
-    sdk_method: string;
-    /** MentraOS permission required (from app_config.json) */
-    permission: MentraPermission;
-    /** Hardware domain this intent belongs to */
-    domain: MentraDomain;
-    /** Which glasses models support this capability */
-    supported_glasses: GlassesModel[];
-    /** Governance tool category for guard engine classification */
-    action_category: 'read' | 'write' | 'delete' | 'network' | 'shell' | 'browser' | 'other';
-    /** Risk level baseline (can be elevated by spatial context) */
-    base_risk: 'low' | 'medium' | 'high' | 'critical';
-    /** Whether the action produces data that leaves the device boundary */
-    exfiltration_risk: boolean;
-    /** Whether the action is reversible */
-    reversible: boolean;
-}
-type MentraPermission = 'CAMERA' | 'MICROPHONE' | 'LOCATION' | 'CALENDAR' | 'READ_NOTIFICATIONS' | 'NONE';
-type MentraDomain = 'camera' | 'microphone' | 'display' | 'location' | 'calendar' | 'notifications' | 'session' | 'dashboard' | 'audio' | 'tool_call' | 'ai_data' | 'ai_action';
-type GlassesModel = 'even_realities_g1' | 'mentra_live' | 'mentra_mach1' | 'vuzix_z100';
-declare const MENTRA_INTENT_TAXONOMY: MentraIntentDefinition[];
-/** All canonical intent strings for use with classifyIntentWithAI() */
-declare const MENTRA_KNOWN_INTENTS: string[];
-/** Get the definition for an intent, or undefined if unknown */
-declare function getMentraIntent(intent: string): MentraIntentDefinition | undefined;
-/** Get all intents that require a specific permission */
-declare function getIntentsByPermission(permission: MentraPermission): MentraIntentDefinition[];
-/** Get all intents supported by a specific glasses model */
-declare function getIntentsByGlasses(model: GlassesModel): MentraIntentDefinition[];
-/** Check if an intent is supported on a given glasses model */
-declare function isIntentSupported(intent: string, model: GlassesModel): boolean;
-/** Get all high-risk or critical intents */
-declare function getHighRiskIntents(): MentraIntentDefinition[];
-/** Get all intents with exfiltration risk */
-declare function getExfiltrationIntents(): MentraIntentDefinition[];
-/** Get all AI data flow intents (data sent to AI APIs) */
-declare function getAIDataIntents(): MentraIntentDefinition[];
-/** Get all AI action intents (actions AI takes on user's behalf) */
-declare function getAIActionIntents(): MentraIntentDefinition[];
-/** Get all AI-related intents (data + actions) */
-declare function getAIIntents(): MentraIntentDefinition[];
-/** Check if an intent is an AI interaction intent */
-declare function isAIIntent(intent: string): boolean;
-
-/**
- * NeuroVerse Adapter — MentraOS Smart Glasses
- *
- * The boundary layer between NeuroVerse governance and MentraOS SDK.
- *
- * This adapter provides two governance layers:
- *   1. Platform Governance — enforces hardware permissions, session isolation,
- *      AI data flow declarations, and AI action confirmation requirements
- *   2. User Rules Override — enforces the user's personal governance preferences
- *      across ALL apps. User rules always win.
- *
- * Architecture:
- *   App receives user data (transcription, camera, location)
- *   → App wants to send data to AI API or take action
- *   → MentraGovernedExecutor.evaluate(intent, appContext)
- *   → Layer 1: User rules check (overrides everything)
- *   → Layer 2: Hardware capability check (physics — never overridden)
- *   → Layer 3: Platform guard engine (world rules)
- *   → verdict: ALLOW / BLOCK / PAUSE
- *
- * The adapter sits at:
- *   App Server → NeuroVerse Guard → MentraOS SDK → Hardware
- *              → NeuroVerse Guard → AI API call (or block)
- *
- * Usage:
- *   import { createMentraGovernedExecutor } from '@neuroverseos/governance/adapters/mentraos';
- *
- *   const executor = await createMentraGovernedExecutor('./world/');
- *   const result = executor.evaluate('ai_send_transcription', appContext);
- */
-
-/**
- * Context for the current app session.
- * This replaces the old SpatialContext — grounded in real app data,
- * not hypothetical spatial tech.
- */
-interface AppContext {
-    /** The app's unique identifier from console.mentra.glass */
-    appId: string;
-    /** Whether the app declared its AI provider(s) at registration */
-    aiProviderDeclared: boolean;
-    /** List of AI API providers the app declared (e.g., ['openai', 'anthropic']) */
-    declaredAIProviders: string[];
-    /** Whether the user has opted in to data retention for this app */
-    dataRetentionOptedIn: boolean;
-    /** Number of distinct data types the app has sent to AI this session */
-    aiDataTypesSent: number;
-    /** Connected glasses model */
-    glassesModel?: GlassesModel;
-}
-/**
- * User's personal governance preferences.
- * These override EVERY app's behavior. The user is king.
- *
- * In production, these are loaded from the user's profile on the MentraOS phone app.
- * The user sets them once, and they apply across all apps.
- */
-interface UserRules {
-    /**
-     * AI data send policy.
-     * - 'declared_only': AI data sends allowed only to declared providers (default)
-     * - 'confirm_each': Every AI data send requires user confirmation
-     * - 'block_all': No AI data sends allowed (offline-only mode)
-     */
-    aiDataPolicy: 'declared_only' | 'confirm_each' | 'block_all';
-    /**
-     * AI auto-action policy.
-     * - 'confirm_all': Every AI action must be confirmed on display (default)
-     * - 'allow_low_risk': Low-risk actions (display, read) auto-allowed; high-risk confirmed
-     * - 'block_all': No AI actions allowed
-     */
-    aiActionPolicy: 'confirm_all' | 'allow_low_risk' | 'block_all';
-    /**
-     * AI purchase policy.
-     * - 'confirm_each': Per-transaction confirmation required (default)
-     * - 'block_all': No AI purchases allowed
-     */
-    aiPurchasePolicy: 'confirm_each' | 'block_all';
-    /**
-     * AI messaging policy.
-     * - 'confirm_each': Per-message confirmation required (default)
-     * - 'block_all': No AI messaging allowed
-     */
-    aiMessagingPolicy: 'confirm_each' | 'block_all';
-    /**
-     * Data retention policy.
-     * - 'app_declared': Allow retention if app declared it and user opted in (default)
-     * - 'never': No data retention, ever
-     */
-    dataRetentionPolicy: 'app_declared' | 'never';
-    /**
-     * Maximum number of AI providers receiving data simultaneously.
-     * Default: 5. Set to 1 for single-provider mode.
-     */
-    maxAIProviders: number;
-}
-/** Default user rules — reasonable defaults, not paranoid, not permissive */
-declare const DEFAULT_USER_RULES: UserRules;
-/**
- * Evaluate an intent against the user's personal rules.
- * Returns null if the user rules don't apply to this intent.
- * Returns a block verdict if the user rules block it.
- * Returns a pause verdict if the user rules require confirmation.
- */
-declare function evaluateUserRules(intent: string, rules: UserRules, appContext: AppContext): {
-    verdict: GuardVerdict;
-    reason: string;
-} | null;
-interface MentraGuardResult {
-    /** Whether the action is allowed */
-    allowed: boolean;
-    /** Whether the action requires user confirmation (PAUSE) */
-    requiresConfirmation: boolean;
-    /** The governance verdict */
-    verdict: GuardVerdict;
-    /** The resolved intent definition (if found in taxonomy) */
-    intentDef?: MentraIntentDefinition;
-    /** User rules check result (if applicable) */
-    userRulesResult?: {
-        reason: string;
-    };
-    /** The app context used for evaluation */
-    appContext: AppContext;
-    /** Which governance layer produced this verdict */
-    decidingLayer: 'user_rules' | 'hardware' | 'platform' | 'emergency_override';
-}
-interface MentraExecutorOptions {
-    /** Include full evaluation trace in verdicts. Default: false. */
-    trace?: boolean;
-    /** Enforcement level override. */
-    level?: 'basic' | 'standard' | 'strict';
-    /** Called when an action is blocked. */
-    onBlock?: (result: MentraGuardResult) => void;
-    /** Called when an action requires confirmation. */
-    onPause?: (result: MentraGuardResult) => void;
-    /** Called for every evaluation. */
-    onEvaluate?: (result: MentraGuardResult) => void;
-    /** Plan to enforce. */
-    plan?: PlanDefinition;
-    /** Plan progress callbacks. */
-    onPlanProgress?: (progress: PlanProgress) => void;
-    onPlanComplete?: () => void;
-}
-declare class MentraGovernedExecutor {
-    private world;
-    private engineOptions;
-    private options;
-    private planState;
-    private planCallbacks;
-    private _userRules;
-    private _emergencyOverride;
-    private _emergencyActivatedAt;
-    constructor(world: WorldDefinition, options?: MentraExecutorOptions, userRules?: UserRules);
-    /** Get the current user rules */
-    get userRules(): UserRules;
-    /** Update user rules at runtime (e.g., user changes preferences in phone app) */
-    updateUserRules(rules: Partial<UserRules>): void;
-    /**
-     * Activate emergency override — user is king.
-     *
-     * Bypasses all NeuroVerse governance rules (user rules, platform rules).
-     * Does NOT bypass MentraOS platform constraints (hardware capability,
-     * declared permissions, session isolation). You can't override physics.
-     *
-     * Returns the timestamp of activation for audit trail.
-     */
-    activateEmergencyOverride(): number;
-    /**
-     * Deactivate emergency override — governance resumes.
-     * Returns the duration the override was active (ms).
-     */
-    deactivateEmergencyOverride(): number;
-    /** Whether emergency override is currently active */
-    get isEmergencyOverrideActive(): boolean;
-    /** Timestamp when emergency override was activated, or null */
-    get emergencyActivatedAt(): number | null;
-    /**
-     * Evaluate an intent against user rules + platform world.
-     *
-     * Three-layer evaluation:
-     *   0. Emergency override — if active, skip governance (layers 1 + 3),
-     *      but STILL enforce platform constraints (layer 2)
-     *   1. User rules check — personal governance override, can BLOCK or PAUSE
-     *   2. Hardware capability check — validates glasses support
-     *      ↑ THIS IS A PLATFORM CONSTRAINT — never overridden
-     *   3. Platform guard engine — full world rule evaluation
-     */
-    evaluate(intent: string, appContext: AppContext): MentraGuardResult;
-    /** Get all known intents for this adapter */
-    get knownIntents(): string[];
-}
-/**
- * Create a MentraOS governed executor from a world directory path.
- */
-declare function createMentraGovernedExecutor(worldPath: string, options?: MentraExecutorOptions, userRules?: UserRules): Promise<MentraGovernedExecutor>;
-/**
- * Create a MentraOS governed executor from an already-loaded WorldDefinition.
- */
-declare function createMentraGovernedExecutorFromWorld(world: WorldDefinition, options?: MentraExecutorOptions, userRules?: UserRules): MentraGovernedExecutor;
-
-export { type AppContext, DEFAULT_USER_RULES, type GlassesModel, MENTRA_INTENT_TAXONOMY, MENTRA_KNOWN_INTENTS, type MentraDomain, type MentraExecutorOptions, MentraGovernedExecutor, type MentraGuardResult, type MentraIntentDefinition, type MentraPermission, type UserRules, createMentraGovernedExecutor, createMentraGovernedExecutorFromWorld, evaluateUserRules, getAIActionIntents, getAIDataIntents, getAIIntents, getExfiltrationIntents, getHighRiskIntents, getIntentsByGlasses, getIntentsByPermission, getMentraIntent, isAIIntent, isIntentSupported };
+export { AppContext, DEFAULT_USER_RULES, GlassesModel, MENTRA_INTENT_TAXONOMY, MENTRA_KNOWN_INTENTS, MentraDomain, MentraExecutorOptions, MentraGovernedExecutor, MentraGuardResult, MentraIntentDefinition, MentraPermission, UserRules, createMentraGovernedExecutor, createMentraGovernedExecutorFromWorld, evaluateUserRules, getAIActionIntents, getAIDataIntents, getAIIntents, getExfiltrationIntents, getHighRiskIntents, getIntentsByGlasses, getIntentsByPermission, getMentraIntent, isAIIntent, isIntentSupported } from './mentraos.cjs';
+import '../guard-contract-C991HDZp.cjs';
+import '../types.cjs';