@neuroverseos/governance 0.4.0 → 0.4.2

package/dist/spatial/index.d.cts

@@ -0,0 +1,517 @@
+/**
+ * Spatial Governance — Type Definitions
+ *
+ * This module defines the future of AI governance on smart glasses:
+ * location-aware, multi-user, consent-based, and temporary.
+ *
+ * The core insight: when AI lives on your face, governance can't be
+ * static. The rules that apply at home are different from the rules
+ * at a hospital. The rules that apply when you're alone are different
+ * from when you're in a shared AR space with three other people.
+ *
+ * Key concepts:
+ *
+ *   Zone        — A physical or spatial location that publishes governance rules.
+ *                 A coffee shop, a hospital, a concert venue, an office.
+ *                 Zones are discovered via Auki spatial anchors, BLE beacons,
+ *                 geofence, or manual opt-in.
+ *
+ *   ZoneRules   — The governance rules a zone publishes. "In this space,
+ *                 no recording. In this space, no AI recommendations.
+ *                 In this space, PHI stays in-network."
+ *
+ *   OptIn       — The user's decision to accept a zone's rules. Always
+ *                 explicit. Never forced. You can refuse — but the zone
+ *                 may refuse you entry (e.g., hospital requiring no recording).
+ *
+ *   Handshake   — When multiple AR-enabled people are in the same space,
+ *                 their governance layers negotiate. The result is a
+ *                 shared governance context where "most restrictive wins."
+ *
+ *   Session     — A spatial governance session. Begins when you enter a zone
+ *                 or join a handshake. Ends when you leave. Rules are
+ *                 temporary — they dissolve when the session ends.
+ *
+ * Architecture:
+ *
+ *   ┌─────────────────────────────────────────────────────────────┐
+ *   │ Governance Stack (top wins)                                 │
+ *   ├─────────────────────────────────────────────────────────────┤
+ *   │ 1. User Rules        — Personal, permanent, cross-app      │
+ *   │ 2. Spatial Handshake  — Multi-user, most-restrictive-wins   │
+ *   │ 3. Zone Rules         — Location-specific, temporary        │
+ *   │ 4. Platform World     — MentraOS hardware + safety          │
+ *   │ 5. App World          — App-specific rules                  │
+ *   └─────────────────────────────────────────────────────────────┘
+ *
+ *   User rules ALWAYS win. A zone cannot relax your personal rules.
+ *   A zone CAN tighten them. A handshake applies the union of all
+ *   participants' restrictions.
+ *
+ * This module exists for the future. It works today but doesn't
+ * require spatial hardware. When Auki + MentraOS go spatial,
+ * this is ready.
+ */
+/**
+ * A spatial zone — a physical or virtual location that publishes governance rules.
+ *
+ * Zones are discovered, not hardcoded. The discovery mechanism depends on
+ * the available technology:
+ *   - Auki spatial anchors (AR-native, precise)
+ *   - BLE beacons (indoor, range-limited)
+ *   - Geofence (GPS, coarse)
+ *   - QR code / NFC tap (manual opt-in)
+ *   - Manual selection (user picks from nearby zones)
+ */
+interface Zone {
+    /** Unique zone identifier */
+    zoneId: string;
+    /** Human-readable name ("Blue Bottle Coffee — Hayes Valley") */
+    name: string;
+    /** Who publishes this zone's rules */
+    publisher: ZonePublisher;
+    /** The governance rules this zone enforces */
+    rules: ZoneRules;
+    /** How this zone was discovered */
+    discovery: ZoneDiscovery;
+    /** Zone type — affects default rule templates */
+    type: ZoneType;
+    /** Whether this zone requires opt-in to enter (e.g., hospital) */
+    requiresOptIn: boolean;
+    /** Human-readable explanation of why these rules exist */
+    rationale: string;
+    /** Zone boundary definition (optional — for geofence/spatial) */
+    boundary?: ZoneBoundary;
+    /** When this zone's rules were last updated */
+    rulesUpdatedAt: number;
+    /** Zone version — incremented when rules change */
+    version: string;
+}
+interface ZonePublisher {
+    /** Publisher name ("Blue Bottle Coffee", "UCSF Medical Center") */
+    name: string;
+    /** Publisher type */
+    type: 'business' | 'institution' | 'government' | 'community' | 'individual';
+    /** Verified by MentraOS / NeuroverseOS (signed zone) */
+    verified: boolean;
+}
+type ZoneType = 'public_space' | 'retail' | 'hospitality' | 'healthcare' | 'workplace' | 'education' | 'entertainment' | 'transit' | 'residential' | 'religious' | 'government' | 'custom';
+type ZoneDiscovery = {
+    method: 'auki_anchor';
+    anchorId: string;
+    confidence: number;
+} | {
+    method: 'ble_beacon';
+    beaconId: string;
+    rssi: number;
+} | {
+    method: 'geofence';
+    lat: number;
+    lng: number;
+    radiusMeters: number;
+} | {
+    method: 'qr_code';
+    payload: string;
+} | {
+    method: 'nfc_tap';
+    tagId: string;
+} | {
+    method: 'manual';
+    selectedAt: number;
+};
+interface ZoneBoundary {
+    /** Boundary type */
+    type: 'radius' | 'polygon' | 'spatial_volume';
+    /** For radius: center point + radius in meters */
+    center?: {
+        lat: number;
+        lng: number;
+        altitude?: number;
+    };
+    radiusMeters?: number;
+    /** For polygon: ordered list of points */
+    polygon?: Array<{
+        lat: number;
+        lng: number;
+    }>;
+    /** For spatial_volume: Auki spatial anchor + dimensions */
+    spatialAnchor?: {
+        anchorId: string;
+        widthM: number;
+        heightM: number;
+        depthM: number;
+    };
+}
+/**
+ * The governance rules a zone publishes.
+ *
+ * These are not suggestions — they're constraints that apply when you
+ * opt into the zone. But they can ONLY tighten, never relax. If your
+ * personal rules already block recording, a zone that allows recording
+ * doesn't change anything for you.
+ */
+interface ZoneRules {
+    /** Camera policy in this zone */
+    camera: 'allowed' | 'confirm_each' | 'blocked';
+    /** Microphone / recording policy */
+    microphone: 'allowed' | 'confirm_each' | 'blocked';
+    /** AI data send policy (sending captured data to AI providers) */
+    aiDataSend: 'allowed' | 'declared_only' | 'confirm_each' | 'blocked';
+    /** AI action policy (AI taking actions on user's behalf) */
+    aiActions: 'allowed' | 'confirm_all' | 'blocked';
+    /** AI recommendations / suggestions policy */
+    aiRecommendations: 'allowed' | 'non_commercial' | 'blocked';
+    /** Location sharing policy */
+    locationSharing: 'allowed' | 'confirm_each' | 'blocked';
+    /** Display behavior — can AI overlay content in this space? */
+    aiOverlay: 'allowed' | 'non_obstructive' | 'blocked';
+    /** Data retention — can apps retain data captured in this zone? */
+    dataRetention: 'allowed' | 'session_only' | 'blocked';
+    /** Commercial behavior — can AI suggest purchases, compare prices? */
+    commercialAI: 'allowed' | 'blocked';
+    /** Bystander protection — are there non-consenting people present? */
+    bystanderProtection: 'standard' | 'elevated' | 'strict';
+    /** Custom constraints (zone-specific) */
+    custom?: ZoneCustomRule[];
+}
+interface ZoneCustomRule {
+    /** Rule identifier */
+    id: string;
+    /** Human-readable description */
+    description: string;
+    /** What intent this blocks/modifies */
+    targetIntent: string;
+    /** What happens */
+    effect: 'block' | 'confirm' | 'modify';
+    /** Why this rule exists */
+    rationale: string;
+}
+/**
+ * A user's opt-in decision for a zone.
+ *
+ * Opt-in is ALWAYS explicit. The glasses show the zone's rules,
+ * the user taps to accept or decline. If they decline, they can
+ * still be in the physical space — but the zone's rules don't apply
+ * (and the zone may display "AI recording not permitted" signs).
+ */
+interface ZoneOptIn {
+    /** The zone being opted into */
+    zoneId: string;
+    /** When the user opted in */
+    optedInAt: number;
+    /** How the user opted in */
+    method: 'tap_confirm' | 'voice_confirm' | 'auto_recognized';
+    /** Which rules the user accepted */
+    acceptedRules: ZoneRules;
+    /** Whether the user made any personal overrides to zone rules */
+    userOverrides: Partial<ZoneRules>;
+    /** The effective rules (zone rules + user overrides, most restrictive wins) */
+    effectiveRules: ZoneRules;
+    /** Session identifier — links to the spatial session */
+    sessionId: string;
+}
+/**
+ * A spatial handshake — multi-user governance negotiation.
+ *
+ * When multiple people wearing AR glasses are in the same space,
+ * their governance layers need to compose. The handshake protocol:
+ *
+ *   1. Discovery — glasses detect nearby participants (Auki, BLE, etc.)
+ *   2. Announce — each participant shares their governance requirements
+ *      (NOT their personal data — just their constraints)
+ *   3. Negotiate — the system computes the most restrictive union
+ *   4. Apply — all participants operate under the shared constraints
+ *   5. Dissolve — when someone leaves, the handshake recomputes
+ *
+ * The "most restrictive wins" invariant is absolute:
+ *   - If ONE person blocks recording, NO ONE can record
+ *   - If ONE person requires AI confirmation, EVERYONE confirms
+ *   - If ONE person blocks AI recommendations, NO ONE gets them
+ *
+ * This protects the most privacy-conscious person in any shared space.
+ */
+interface SpatialHandshake {
+    /** Unique handshake identifier */
+    handshakeId: string;
+    /** Participants in the handshake */
+    participants: HandshakeParticipant[];
+    /** The negotiated governance rules (most restrictive union) */
+    negotiatedRules: ZoneRules;
+    /** The zone this handshake is happening in (if any) */
+    zoneId?: string;
+    /** When the handshake was created */
+    createdAt: number;
+    /** When the handshake was last re-negotiated */
+    lastNegotiatedAt: number;
+    /** Handshake state */
+    state: 'negotiating' | 'active' | 'dissolved';
+}
+interface HandshakeParticipant {
+    /** Participant identifier (anonymous — not their real identity) */
+    participantId: string;
+    /** What this participant shares (their governance requirements) */
+    publishedConstraints: ParticipantConstraints;
+    /** When they joined the handshake */
+    joinedAt: number;
+    /** Whether they've acknowledged the negotiated rules */
+    acknowledged: boolean;
+}
+/**
+ * What a participant shares during handshake negotiation.
+ *
+ * This is NOT personal data. It's governance metadata.
+ * "I require no recording" is a constraint, not an identity.
+ */
+interface ParticipantConstraints {
+    /** This participant's camera policy (their minimum requirement) */
+    cameraMinimum: 'allowed' | 'confirm_each' | 'blocked';
+    /** This participant's microphone policy */
+    microphoneMinimum: 'allowed' | 'confirm_each' | 'blocked';
+    /** This participant's AI data send policy */
+    aiDataSendMinimum: 'allowed' | 'declared_only' | 'confirm_each' | 'blocked';
+    /** This participant's AI recommendation policy */
+    aiRecommendationsMinimum: 'allowed' | 'non_commercial' | 'blocked';
+    /** This participant's data retention policy */
+    dataRetentionMinimum: 'allowed' | 'session_only' | 'blocked';
+    /** This participant's bystander protection level */
+    bystanderProtectionMinimum: 'standard' | 'elevated' | 'strict';
+}
+/**
+ * A spatial governance session.
+ *
+ * Begins when you enter a zone or join a handshake.
+ * Ends when you leave. Rules are temporary.
+ *
+ * This is the runtime state. It holds the effective governance
+ * context that the guard engine evaluates against.
+ */
+interface SpatialSession {
+    /** Session identifier */
+    sessionId: string;
+    /** Active zone (if in one) */
+    zone?: Zone;
+    /** Active opt-in (if opted into a zone) */
+    optIn?: ZoneOptIn;
+    /** Active handshake (if in a multi-user context) */
+    handshake?: SpatialHandshake;
+    /** The effective spatial rules (zone + handshake + user, most restrictive wins) */
+    effectiveRules: ZoneRules;
+    /** Session state */
+    state: 'discovering' | 'opted_in' | 'handshake_active' | 'active' | 'ended';
+    /** When this session started */
+    startedAt: number;
+    /** When this session ended (null if active) */
+    endedAt: number | null;
+    /** Audit trail of governance events during this session */
+    events: SpatialEvent[];
+}
+type SpatialEvent = {
+    type: 'zone_discovered';
+    zone: Zone;
+    timestamp: number;
+} | {
+    type: 'zone_opted_in';
+    zoneId: string;
+    timestamp: number;
+} | {
+    type: 'zone_declined';
+    zoneId: string;
+    reason: string;
+    timestamp: number;
+} | {
+    type: 'zone_exited';
+    zoneId: string;
+    timestamp: number;
+} | {
+    type: 'handshake_started';
+    handshakeId: string;
+    participantCount: number;
+    timestamp: number;
+} | {
+    type: 'handshake_participant_joined';
+    handshakeId: string;
+    participantId: string;
+    timestamp: number;
+} | {
+    type: 'handshake_participant_left';
+    handshakeId: string;
+    participantId: string;
+    timestamp: number;
+} | {
+    type: 'handshake_negotiated';
+    handshakeId: string;
+    timestamp: number;
+} | {
+    type: 'handshake_dissolved';
+    handshakeId: string;
+    timestamp: number;
+} | {
+    type: 'rule_tightened';
+    rule: string;
+    from: string;
+    to: string;
+    source: string;
+    timestamp: number;
+} | {
+    type: 'intent_blocked_by_zone';
+    intent: string;
+    zoneId: string;
+    timestamp: number;
+} | {
+    type: 'intent_blocked_by_handshake';
+    intent: string;
+    handshakeId: string;
+    timestamp: number;
+};
+/** Default zone rules — permissive baseline (zones tighten, never relax) */
+declare const DEFAULT_ZONE_RULES: ZoneRules;
+/** Default participant constraints — fully permissive (participant tightens) */
+declare const DEFAULT_PARTICIPANT_CONSTRAINTS: ParticipantConstraints;
+
+/**
+ * Spatial Governance Engine
+ *
+ * The runtime engine for location-aware, multi-user governance.
+ *
+ * Core operations:
+ *
+ *   discoverZone()     — A zone is detected nearby (Auki anchor, BLE, etc.)
+ *   optInToZone()      — User accepts the zone's rules
+ *   exitZone()         — User leaves the zone, rules dissolve
+ *
+ *   startHandshake()   — Begin multi-user governance negotiation
+ *   joinHandshake()    — Another participant enters the shared space
+ *   leaveHandshake()   — Participant exits, handshake recomputes
+ *
+ *   evaluateSpatial()  — Check an intent against the current spatial context
+ *   resolveEffective() — Compute the most restrictive rules from all layers
+ *
+ * The "most restrictive wins" invariant:
+ *   When multiple governance layers overlap (user rules, zone rules,
+ *   handshake rules), the MOST restrictive value for each field wins.
+ *   This means:
+ *     - 'blocked' beats 'confirm_each' beats 'declared_only' beats 'allowed'
+ *     - 'strict' beats 'elevated' beats 'standard'
+ *     - A zone can tighten your rules, never relax them
+ *     - A handshake participant can tighten the group, never relax it
+ */
+
+/**
+ * Merge two ZoneRules, taking the most restrictive value for each field.
+ * This is the core of "most restrictive wins."
+ */
+declare function mergeRules(a: ZoneRules, b: ZoneRules): ZoneRules;
+/**
+ * Convert participant constraints to ZoneRules format for merging.
+ */
+declare function constraintsToRules(c: ParticipantConstraints): ZoneRules;
+/**
+ * Create an opt-in for a zone.
+ *
+ * The effective rules are computed by merging the zone's rules
+ * with any user overrides (most restrictive wins).
+ */
+declare function createOptIn(zone: Zone, userOverrides?: Partial<ZoneRules>, method?: ZoneOptIn['method']): ZoneOptIn;
+/**
+ * Start a new spatial handshake with an initial participant.
+ */
+declare function startHandshake(initiator: ParticipantConstraints, initiatorId: string, zoneId?: string): SpatialHandshake;
+/**
+ * Add a participant to an existing handshake. Returns a new handshake
+ * with recomputed negotiated rules.
+ */
+declare function joinHandshake(handshake: SpatialHandshake, constraints: ParticipantConstraints, participantId: string): SpatialHandshake;
+/**
+ * Remove a participant from a handshake. Returns a new handshake
+ * with recomputed rules, or null if the handshake is dissolved
+ * (< 2 participants remaining).
+ */
+declare function leaveHandshake(handshake: SpatialHandshake, participantId: string): SpatialHandshake | null;
+/**
+ * Create a new spatial session.
+ */
+declare function createSession(): SpatialSession;
+/**
+ * Apply a zone opt-in to a session. Returns a new session with
+ * the zone's rules merged in.
+ */
+declare function applyZoneToSession(session: SpatialSession, zone: Zone, optIn: ZoneOptIn): SpatialSession;
+/**
+ * Apply a handshake to a session. Returns a new session with
+ * the handshake's negotiated rules merged in.
+ */
+declare function applyHandshakeToSession(session: SpatialSession, handshake: SpatialHandshake): SpatialSession;
+/**
+ * Exit a zone. Zone rules dissolve, but handshake rules may remain.
+ */
+declare function exitZone(session: SpatialSession): SpatialSession;
+/**
+ * End a session. All spatial rules dissolve.
+ */
+declare function endSession(session: SpatialSession): SpatialSession;
+type SpatialVerdict = {
+    allowed: boolean;
+    requiresConfirmation: boolean;
+    blockedBy: 'none' | 'zone' | 'handshake' | 'zone+handshake';
+    reason: string;
+    rule: string;
+};
+/**
+ * Evaluate an intent against the current spatial governance context.
+ *
+ * This is the spatial layer — it sits between user rules and the
+ * platform world in the governance stack.
+ */
+declare function evaluateSpatial(intent: string, session: SpatialSession): SpatialVerdict;
+/**
+ * Emergency override for spatial governance.
+ *
+ * When activated, ALL spatial rules (zone + handshake) are bypassed.
+ * Only MentraOS platform constraints remain (hardware capability, physics).
+ *
+ * Use case: You're in a store that blocks recording. Someone gets violent.
+ * You need to film, call for help, stream to emergency contacts.
+ * Emergency override smashes through every zone and handshake rule.
+ *
+ * The user is king. Always.
+ *
+ * In the MentraOS adapter, this is wired to the executor's
+ * activateEmergencyOverride() method, which also skips user rules
+ * and platform governance — leaving only hardware constraints.
+ *
+ * Returns a new session in emergency mode with all rules dissolved.
+ */
+declare function activateEmergencyOverride(session: SpatialSession): SpatialSession;
+/**
+ * Evaluate an intent during emergency override — always allow.
+ * The only thing that can still block is hardware (physics).
+ */
+declare function evaluateSpatialEmergency(_intent: string): SpatialVerdict;
+/**
+ * Pre-built zone rule templates for common location types.
+ * Zones can start from a template and customize.
+ */
+declare const ZONE_TEMPLATES: Record<string, ZoneRules>;
+
+/**
+ * Example Zones — Real-world spatial governance scenarios
+ *
+ * These demonstrate what zone governance looks like in practice.
+ * Each zone is a real-world location type with rules that make sense
+ * for that context.
+ *
+ * When Mentra + Auki go spatial, these become discoverable.
+ * Your glasses walk into a space, detect the Auki anchor or BLE beacon,
+ * and present the zone's rules for opt-in.
+ */
+
+declare const BLUE_BOTTLE_HAYES: Zone;
+declare const UCSF_MEDICAL: Zone;
+declare const APPLE_UNION_SQUARE: Zone;
+declare const CHASE_CENTER: Zone;
+declare const WEWORK_SOMA: Zone;
+declare const SFMOMA: Zone;
+declare const MY_HOME: Zone;
+declare const EXAMPLE_ZONES: Zone[];
+
+export { APPLE_UNION_SQUARE, BLUE_BOTTLE_HAYES, CHASE_CENTER, DEFAULT_PARTICIPANT_CONSTRAINTS, DEFAULT_ZONE_RULES, EXAMPLE_ZONES, type HandshakeParticipant, MY_HOME, type ParticipantConstraints, SFMOMA, type SpatialEvent, type SpatialHandshake, type SpatialSession, type SpatialVerdict, UCSF_MEDICAL, WEWORK_SOMA, ZONE_TEMPLATES, type Zone, type ZoneBoundary, type ZoneCustomRule, type ZoneDiscovery, type ZoneOptIn, type ZonePublisher, type ZoneRules, type ZoneType, activateEmergencyOverride, applyHandshakeToSession, applyZoneToSession, constraintsToRules, createOptIn, createSession, endSession, evaluateSpatial, evaluateSpatialEmergency, exitZone, joinHandshake, leaveHandshake, mergeRules, startHandshake };