@neuroverseos/governance 0.4.3 → 0.5.1

package/dist/admin/index.d.cts

@@ -0,0 +1,362 @@
+import { WorldRoleDefinition, WorldDefinition } from '../types.cjs';
+
+/**
+ * Admin Layer — Type Definitions
+ *
+ * Types for enterprise governance management: roles, zones, authority,
+ * assignments, and policy simulation.
+ *
+ * These types sit on top of the core governance engine. The engine handles
+ * evaluation. This layer handles who has what role, where zones are,
+ * and who can change what.
+ */
+
+interface OrgRole {
+    /** Unique role identifier (e.g., 'floor-associate', 'shift-supervisor') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what this role is for */
+    description: string;
+    /** The governance role definition fed to the guard engine */
+    definition: WorldRoleDefinition;
+    /** Who created this role */
+    createdBy: string;
+    /** When this role was created */
+    createdAt: number;
+    /** Last modification */
+    updatedAt: number;
+    /** Whether this role is currently active */
+    active: boolean;
+}
+interface RoleAssignment {
+    /** Unique assignment ID */
+    id: string;
+    /** Device or employee identifier */
+    deviceId: string;
+    /** Optional human name for readability */
+    employeeName?: string;
+    /** The role assigned */
+    roleId: string;
+    /** Who made this assignment */
+    assignedBy: string;
+    /** When assigned */
+    assignedAt: number;
+    /** Optional expiration (e.g., vendor visit ends at 5pm) */
+    expiresAt?: number;
+    /** Why this assignment was made */
+    reason?: string;
+}
+type ZoneDiscoveryMethod = {
+    type: 'ble_beacon';
+    beaconId: string;
+} | {
+    type: 'geofence';
+    lat: number;
+    lng: number;
+    radiusMeters: number;
+} | {
+    type: 'auki_anchor';
+    anchorId: string;
+    confidence?: number;
+} | {
+    type: 'manual';
+    label: string;
+};
+type ZonePolicyLevel = 'allow' | 'confirm_each' | 'block';
+interface ZoneRuleSet {
+    camera: ZonePolicyLevel;
+    microphone: ZonePolicyLevel;
+    aiDataSend: ZonePolicyLevel;
+    aiActions: ZonePolicyLevel;
+    aiRecommendations: ZonePolicyLevel;
+    locationSharing: ZonePolicyLevel;
+    dataRetention: ZonePolicyLevel;
+    bystanderProtection: 'standard' | 'elevated' | 'maximum';
+    /** Custom rules targeting specific intents */
+    customRules: CustomZoneRule[];
+}
+interface CustomZoneRule {
+    /** Rule identifier */
+    id: string;
+    /** Human description */
+    description: string;
+    /** Intent pattern to match (e.g., 'ai_auto_purchase', 'camera_*') */
+    intentPattern: string;
+    /** What to do */
+    action: 'allow' | 'block' | 'confirm';
+    /** Why this rule exists */
+    rationale: string;
+}
+interface OrgZone {
+    /** Unique zone identifier */
+    id: string;
+    /** Human-readable name (e.g., 'Pharmacy', 'Loading Dock') */
+    name: string;
+    /** Description */
+    description: string;
+    /** Location/store this zone belongs to */
+    locationId: string;
+    /** How devices discover this zone */
+    discovery: ZoneDiscoveryMethod;
+    /** The governance rules for this zone */
+    rules: ZoneRuleSet;
+    /** Who created this zone */
+    createdBy: string;
+    /** When created */
+    createdAt: number;
+    /** Last modification */
+    updatedAt: number;
+    /** Whether this zone is currently active */
+    active: boolean;
+}
+type AuthorityLevel = 'viewer' | 'operator' | 'supervisor' | 'manager' | 'admin';
+interface AuthorityGrant {
+    /** The role this authority applies to */
+    roleId: string;
+    /** What level of admin authority this role carries */
+    authorityLevel: AuthorityLevel;
+    /** Optional: restrict authority to specific location(s) */
+    locationScope?: string[];
+}
+interface AuthorityChain {
+    /** Ordered list of authority grants (highest authority first) */
+    grants: AuthorityGrant[];
+    /** Can emergency override bypass authority chain? Always true for wearer safety. */
+    emergencyOverrideAlwaysAllowed: true;
+}
+type AuditAction = 'role_created' | 'role_updated' | 'role_deleted' | 'role_assigned' | 'role_unassigned' | 'zone_created' | 'zone_updated' | 'zone_deleted' | 'authority_updated' | 'simulation_run' | 'policy_deployed';
+interface AuditEntry {
+    /** Unique entry ID */
+    id: string;
+    /** What happened */
+    action: AuditAction;
+    /** Who did it */
+    actorId: string;
+    /** Actor's role at time of action */
+    actorRole: string;
+    /** When */
+    timestamp: number;
+    /** What was affected */
+    targetType: 'role' | 'zone' | 'assignment' | 'authority' | 'simulation';
+    /** Target identifier */
+    targetId: string;
+    /** What changed (before/after for updates) */
+    changes?: {
+        before?: Record<string, unknown>;
+        after?: Record<string, unknown>;
+    };
+    /** Human-readable description */
+    summary: string;
+}
+interface PolicySimulationRequest {
+    /** What are we simulating? */
+    type: 'role_change' | 'zone_change' | 'authority_change' | 'full_matrix';
+    /** The proposed change (new or modified role/zone) */
+    proposed?: {
+        role?: OrgRole;
+        zone?: OrgZone;
+        authority?: AuthorityGrant;
+    };
+    /** Which role to evaluate against (for zone changes) */
+    targetRoleId?: string;
+    /** Which zone to evaluate in (for role changes) */
+    targetZoneId?: string;
+    /** Specific intents to test (defaults to all 61) */
+    intents?: string[];
+}
+interface PolicySimulationResult {
+    /** Request that produced this result */
+    request: PolicySimulationRequest;
+    /** When the simulation ran */
+    timestamp: number;
+    /** Per-intent verdicts */
+    verdicts: IntentVerdict[];
+    /** Summary stats */
+    summary: {
+        total: number;
+        allowed: number;
+        blocked: number;
+        paused: number;
+        modified: number;
+    };
+    /** Conflicts detected (things that might break) */
+    conflicts: PolicyConflict[];
+    /** Comparison with current policy (if this is a change) */
+    diff?: PolicyDiff[];
+}
+interface IntentVerdict {
+    /** The intent evaluated */
+    intent: string;
+    /** Human description of the intent */
+    description: string;
+    /** Current verdict (before proposed change) */
+    currentVerdict?: 'allow' | 'block' | 'pause' | 'modify';
+    /** Proposed verdict (after change) */
+    proposedVerdict: 'allow' | 'block' | 'pause' | 'modify';
+    /** Whether this changed */
+    changed: boolean;
+    /** Why this verdict was reached */
+    reason: string;
+}
+interface PolicyConflict {
+    /** What's conflicting */
+    description: string;
+    /** Severity */
+    severity: 'warning' | 'error';
+    /** Which intent is affected */
+    intent: string;
+    /** What the admin should consider */
+    suggestion: string;
+}
+interface PolicyDiff {
+    /** The intent that changed */
+    intent: string;
+    /** Old verdict */
+    from: string;
+    /** New verdict */
+    to: string;
+    /** Human explanation */
+    explanation: string;
+}
+/**
+ * Pluggable storage backend. Mentra provides the database.
+ * We provide the interface.
+ */
+interface AdminStorage {
+    getRoles(): Promise<OrgRole[]>;
+    getRole(id: string): Promise<OrgRole | null>;
+    saveRole(role: OrgRole): Promise<void>;
+    deleteRole(id: string): Promise<void>;
+    getAssignments(): Promise<RoleAssignment[]>;
+    getAssignmentsByDevice(deviceId: string): Promise<RoleAssignment[]>;
+    getAssignmentsByRole(roleId: string): Promise<RoleAssignment[]>;
+    saveAssignment(assignment: RoleAssignment): Promise<void>;
+    deleteAssignment(id: string): Promise<void>;
+    getZones(): Promise<OrgZone[]>;
+    getZone(id: string): Promise<OrgZone | null>;
+    getZonesByLocation(locationId: string): Promise<OrgZone[]>;
+    saveZone(zone: OrgZone): Promise<void>;
+    deleteZone(id: string): Promise<void>;
+    getAuthorityChain(): Promise<AuthorityChain>;
+    saveAuthorityChain(chain: AuthorityChain): Promise<void>;
+    getAuditLog(options?: {
+        limit?: number;
+        offset?: number;
+        action?: AuditAction;
+    }): Promise<AuditEntry[]>;
+    appendAudit(entry: AuditEntry): Promise<void>;
+}
+
+/**
+ * Governance Admin Manager
+ *
+ * The management layer for enterprise governance. Handles CRUD for roles,
+ * zones, authority chains, and device assignments. Enforces authority
+ * levels — not everyone can change everything.
+ *
+ * Every mutation is audited. Every change can be simulated before deployment.
+ */
+
+declare class GovernanceAdmin {
+    private storage;
+    private platformWorld?;
+    constructor(storage: AdminStorage, platformWorld?: WorldDefinition);
+    private getActorAuthority;
+    private checkAuthority;
+    private audit;
+    createRole(role: OrgRole, actorId: string, actorRoleId: string): Promise<OrgRole>;
+    updateRole(roleId: string, updates: Partial<Pick<OrgRole, 'name' | 'description' | 'definition' | 'active'>>, actorId: string, actorRoleId: string): Promise<OrgRole>;
+    deleteRole(roleId: string, actorId: string, actorRoleId: string): Promise<void>;
+    listRoles(): Promise<OrgRole[]>;
+    getRole(roleId: string): Promise<OrgRole | null>;
+    assignRole(assignment: Omit<RoleAssignment, 'id' | 'assignedAt'>, actorId: string, actorRoleId: string): Promise<RoleAssignment>;
+    unassignRole(assignmentId: string, actorId: string, actorRoleId: string): Promise<void>;
+    getDeviceRole(deviceId: string): Promise<RoleAssignment | null>;
+    listAssignments(): Promise<RoleAssignment[]>;
+    createZone(zone: OrgZone, actorId: string, actorRoleId: string): Promise<OrgZone>;
+    updateZone(zoneId: string, updates: Partial<Pick<OrgZone, 'name' | 'description' | 'rules' | 'discovery' | 'active'>>, actorId: string, actorRoleId: string): Promise<OrgZone>;
+    deleteZone(zoneId: string, actorId: string, actorRoleId: string): Promise<void>;
+    listZones(locationId?: string): Promise<OrgZone[]>;
+    getZone(zoneId: string): Promise<OrgZone | null>;
+    updateAuthority(chain: AuthorityChain, actorId: string, actorRoleId: string): Promise<AuthorityChain>;
+    getAuthority(): Promise<AuthorityChain>;
+    simulate(request: PolicySimulationRequest, actorId: string, actorRoleId: string): Promise<PolicySimulationResult>;
+    simulateMatrix(actorId: string, actorRoleId: string): Promise<Map<string, Map<string, IntentVerdict[]>>>;
+    /**
+     * Simulate a proposed role change and return only what would break.
+     * The "measure twice" before deploying.
+     */
+    simulateRoleChange(roleId: string, proposedDefinitionUpdates: Partial<OrgRole['definition']>, actorId: string, actorRoleId: string): Promise<PolicySimulationResult>;
+    /**
+     * Simulate a proposed zone rule change and return impact.
+     */
+    simulateZoneChange(zoneId: string, proposedRuleUpdates: Partial<OrgZone['rules']>, targetRoleId: string, actorId: string, actorRoleId: string): Promise<PolicySimulationResult>;
+    getAuditLog(options?: {
+        limit?: number;
+        offset?: number;
+        action?: AuditAction;
+    }): Promise<AuditEntry[]>;
+}
+type AdminErrorCode = 'INSUFFICIENT_AUTHORITY' | 'LOCATION_SCOPE_DENIED' | 'ROLE_EXISTS' | 'ROLE_NOT_FOUND' | 'ROLE_IN_USE' | 'ZONE_EXISTS' | 'ZONE_NOT_FOUND';
+declare class GovernanceAdminError extends Error {
+    code: AdminErrorCode;
+    constructor(message: string, code: AdminErrorCode);
+}
+
+/**
+ * In-Memory Storage — Reference Implementation
+ *
+ * Ships with the package for development and testing.
+ * Mentra (or any integrator) replaces this with their own database adapter
+ * by implementing the AdminStorage interface.
+ */
+
+declare class InMemoryStorage implements AdminStorage {
+    private roles;
+    private assignments;
+    private zones;
+    private authority;
+    private audit;
+    getRoles(): Promise<OrgRole[]>;
+    getRole(id: string): Promise<OrgRole | null>;
+    saveRole(role: OrgRole): Promise<void>;
+    deleteRole(id: string): Promise<void>;
+    getAssignments(): Promise<RoleAssignment[]>;
+    getAssignmentsByDevice(deviceId: string): Promise<RoleAssignment[]>;
+    getAssignmentsByRole(roleId: string): Promise<RoleAssignment[]>;
+    saveAssignment(assignment: RoleAssignment): Promise<void>;
+    deleteAssignment(id: string): Promise<void>;
+    getZones(): Promise<OrgZone[]>;
+    getZone(id: string): Promise<OrgZone | null>;
+    getZonesByLocation(locationId: string): Promise<OrgZone[]>;
+    saveZone(zone: OrgZone): Promise<void>;
+    deleteZone(id: string): Promise<void>;
+    getAuthorityChain(): Promise<AuthorityChain>;
+    saveAuthorityChain(chain: AuthorityChain): Promise<void>;
+    getAuditLog(options?: {
+        limit?: number;
+        offset?: number;
+        action?: AuditAction;
+    }): Promise<AuditEntry[]>;
+    appendAudit(entry: AuditEntry): Promise<void>;
+}
+
+/**
+ * Policy Simulator — "What happens if I change this?"
+ *
+ * Runs the governance engine against proposed policy changes before they deploy.
+ * Uses the existing simulateWorld() engine and intent taxonomy to produce
+ * a full matrix of what would be allowed, blocked, paused, or modified.
+ *
+ * This is the enterprise "measure twice, cut once" tool.
+ */
+
+declare function simulatePolicy(request: PolicySimulationRequest, currentRoles: OrgRole[], currentZones: OrgZone[], platformWorld?: WorldDefinition): PolicySimulationResult;
+/**
+ * Generate a complete role × zone × intent matrix.
+ * Shows every combination: what each role can do in each zone.
+ */
+declare function simulateFullMatrix(roles: OrgRole[], zones: OrgZone[], platformWorld?: WorldDefinition): Map<string, Map<string, IntentVerdict[]>>;
+
+export { type AdminErrorCode, type AdminStorage, type AuditAction, type AuditEntry, type AuthorityChain, type AuthorityGrant, type AuthorityLevel, type CustomZoneRule, GovernanceAdmin, GovernanceAdminError, InMemoryStorage, type IntentVerdict, type OrgRole, type OrgZone, type PolicyConflict, type PolicyDiff, type PolicySimulationRequest, type PolicySimulationResult, type RoleAssignment, type ZoneDiscoveryMethod, type ZonePolicyLevel, type ZoneRuleSet, simulateFullMatrix, simulatePolicy };