@neuroverseos/governance 0.3.4 → 0.4.1

package/dist/types.d.cts

@@ -0,0 +1,370 @@
+/**
+ * World Engine Types — Subset for Governance Engine
+ *
+ * These types map to the .nv-world.zip file format.
+ * This file contains only the types referenced by the governance
+ * engine (guard, validate, bootstrap). The full type system lives
+ * in the main NeuroVerse OS repo.
+ */
+interface ModelIdentity {
+    modelName: string;
+    acronymExpansion?: string;
+    nameType: 'acronym' | 'metaphor';
+    purpose: string;
+    domain?: string;
+}
+interface WorldIdentity {
+    world_id: string;
+    name: string;
+    thesis: string;
+    version: string;
+    runtime_mode: 'SIMULATION' | 'NARRATIVE' | 'COMPLIANCE' | 'CUSTOM';
+    default_assumption_profile: string;
+    default_alternative_profile: string;
+    modules: string[];
+    players: {
+        thinking_space: boolean;
+        experience_space: boolean;
+        action_space: boolean;
+    };
+    modelIdentity?: ModelIdentity;
+}
+interface Invariant {
+    id: string;
+    label: string;
+    enforcement: 'structural' | 'prompt';
+    mutable: false;
+}
+interface AssumptionProfile {
+    name: string;
+    description: string;
+    is_default_baseline?: boolean;
+    is_default_alternative?: boolean;
+    parameters: Record<string, string>;
+}
+interface ParameterDefinition {
+    type: 'enum' | 'number' | 'boolean';
+    options?: string[];
+    min?: number;
+    max?: number;
+    label: string;
+    description: string;
+}
+interface AssumptionConfig {
+    profiles: Record<string, AssumptionProfile>;
+    parameter_definitions: Record<string, ParameterDefinition>;
+}
+interface StateVariable {
+    type: 'enum' | 'number' | 'boolean';
+    options?: string[];
+    min?: number;
+    max?: number;
+    step?: number;
+    default: string | number | boolean;
+    mutable: boolean;
+    label: string;
+    description: string;
+    display_as?: 'percentage' | 'integer' | 'decimal';
+}
+interface StatePreset {
+    description: string;
+    values: Record<string, string | number | boolean>;
+}
+interface StateSchema {
+    variables: Record<string, StateVariable>;
+    presets: Record<string, StatePreset>;
+}
+type TriggerOperator = '==' | '!=' | '>' | '<' | '>=' | '<=' | 'in';
+type EffectOperation = 'multiply' | 'add' | 'subtract' | 'set' | 'set_boolean' | 'multiply_dynamic' | 'add_dynamic' | 'subtract_dynamic' | 'set_dynamic';
+type RuleSeverity = 'structural' | 'degradation' | 'advantage';
+interface Trigger {
+    field: string;
+    operator: TriggerOperator;
+    value: string | number | boolean | string[];
+    source: 'state' | 'assumption';
+}
+interface Effect {
+    target: string;
+    operation: EffectOperation;
+    value: number | boolean | string;
+    value_formula?: string;
+}
+interface CollapseCheck {
+    field: string;
+    operator: TriggerOperator;
+    value: number;
+    result: 'MODEL_COLLAPSES';
+}
+interface ConditionalEffect {
+    condition: Trigger;
+    and?: Trigger;
+    or?: Trigger;
+    condition_any?: Trigger[];
+    effects: Effect[];
+}
+interface CausalTranslation {
+    trigger_text: string;
+    rule_text: string;
+    shift_text: string;
+    effect_text: string;
+}
+interface RuleRedirect {
+    suggested_action: string;
+    reason: string;
+    fallback_state_changes?: Record<string, string | number | boolean>;
+}
+interface Rule {
+    id: string;
+    severity: RuleSeverity;
+    label: string;
+    description: string;
+    order: number;
+    triggers: Trigger[];
+    effects?: Effect[];
+    effects_conditional?: ConditionalEffect[];
+    collapse_check?: CollapseCheck;
+    secondary_check?: CollapseCheck;
+    exclusive_with?: string;
+    causal_translation: CausalTranslation;
+    redirect?: RuleRedirect;
+}
+type ViabilityStatus = 'THRIVING' | 'STABLE' | 'COMPRESSED' | 'CRITICAL' | 'MODEL_COLLAPSES';
+interface ViabilityGate {
+    status: ViabilityStatus;
+    field: string;
+    operator: TriggerOperator;
+    value: number;
+    color: string;
+    icon: string;
+}
+interface CollapseVisual {
+    background: string;
+    text: string;
+    border: string;
+    label: string;
+}
+interface GatesConfig {
+    viability_classification: ViabilityGate[];
+    structural_override: {
+        description: string;
+        enforcement: 'mandatory';
+    };
+    sustainability_threshold: number;
+    collapse_visual: CollapseVisual;
+}
+interface ComputedOutcome {
+    id: string;
+    type: 'number' | 'boolean' | 'enum';
+    range?: [number, number];
+    options?: string[];
+    default?: number | boolean | string;
+    display_as?: 'percentage' | 'integer' | 'decimal';
+    label: string;
+    primary?: boolean;
+    initial_value?: string;
+    derived_from?: string;
+    assignment?: 'rule' | 'external';
+    show_in_comparison: boolean;
+    structural_indicator?: boolean;
+}
+interface ComparisonLayout {
+    primary_card: string;
+    status_badge: string;
+    structural_indicators: string[];
+}
+interface OutcomesConfig {
+    computed_outcomes: ComputedOutcome[];
+    comparison_layout: ComparisonLayout;
+}
+interface WorldMetadata {
+    format_version: string;
+    created_at: string;
+    last_modified: string;
+    authoring_method: 'manual-authoring' | 'configurator-ai' | 'migration';
+    integrity_hash?: string;
+}
+interface KernelConfig {
+    artifact_type: string;
+    kernel_id: string;
+    version: string;
+    domain: string;
+    enforcement_level: 'standard' | 'strict' | 'permissive';
+    input_boundaries: {
+        forbidden_patterns: Array<{
+            id: string;
+            pattern: string;
+            reason: string;
+            action: 'BLOCK' | 'WARN';
+        }>;
+    };
+    output_boundaries: {
+        forbidden_patterns: Array<{
+            id: string;
+            pattern: string;
+            reason: string;
+            action: 'BLOCK' | 'WARN';
+        }>;
+    };
+    response_vocabulary: Record<string, string>;
+    metadata: {
+        compiled_by: string;
+        compiled_at: string;
+        source_hash: string;
+        compiler_version: string;
+    };
+}
+type RoleArchetype = 'observer' | 'operator' | 'strategist' | 'guardian' | 'steward' | 'executor';
+type RoleAuthority = 'none' | 'execute_within_limits' | 'reprioritize_within_bounds' | 'block_violations' | 'escalate_audit_freeze' | 'execute_declared_actions';
+type RolePosture = 'analyze' | 'task_oriented' | 'long_term_coherence' | 'constraint_aware' | 'system_integrity' | 'efficient';
+interface WorldRoleDefinition {
+    id: string;
+    archetype: RoleArchetype;
+    authority: RoleAuthority;
+    posture: RolePosture;
+    name: string;
+    description: string;
+    icon?: string;
+    roleMandate: string;
+    voiceStyle?: string;
+    canDo: string[];
+    cannotDo: string[];
+    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 {
+    from: string;
+    to: string;
+    initiator: 'self' | 'steward' | 'any';
+    condition?: string;
+}
+interface RolesConfig {
+    assignment: RoleAssignment;
+    roles: WorldRoleDefinition[];
+    transitions?: RoleTransition[];
+}
+interface Guard {
+    id: string;
+    label: string;
+    description: string;
+    category: 'structural' | 'operational' | 'advisory';
+    enforcement: 'block' | 'pause' | 'warn' | 'modify' | 'penalize' | 'reward' | 'neutral';
+    immutable: boolean;
+    invariant_ref?: string;
+    intent_patterns: string[];
+    required_roles?: string[];
+    redirect?: string;
+    default_enabled?: boolean;
+    /** Tool names this guard applies to (case-insensitive). Empty/absent = all tools. */
+    appliesTo?: string[];
+    player_modes?: {
+        thinking?: 'annotate' | 'block' | 'ignore';
+        experience?: 'simulate' | 'score' | 'ignore';
+        action?: 'block' | 'pause' | 'warn' | 'modify' | 'penalize' | 'reward' | 'neutral';
+    };
+    /** Consequence to apply when enforcement is 'penalize' */
+    consequence?: {
+        type: 'freeze' | 'reduce_influence' | 'increase_risk' | 'cooldown' | 'custom';
+        rounds?: number;
+        magnitude?: number;
+        description: string;
+    };
+    /** Reward to apply when enforcement is 'reward' */
+    reward?: {
+        type: 'boost_influence' | 'priority' | 'faster_execution' | 'weight_increase' | 'custom';
+        rounds?: number;
+        magnitude?: number;
+        description: string;
+    };
+    /** For 'modify' enforcement: what the action should be changed to */
+    modify_to?: string;
+}
+interface IntentPattern {
+    label: string;
+    pattern: string;
+}
+interface GuardsConfig {
+    guards: Guard[];
+    intent_vocabulary: Record<string, IntentPattern>;
+    /** All known action surfaces (e.g. "shell", "http", "db", "email", "deploy").
+     *  When declared, the validator checks that every surface has at least one
+     *  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[];
+    assumptions: AssumptionConfig;
+    stateSchema: StateSchema;
+    rules: Rule[];
+    gates: GatesConfig;
+    outcomes: OutcomesConfig;
+    guards?: GuardsConfig;
+    roles?: RolesConfig;
+    kernel?: KernelConfig;
+    lenses?: LensesConfig;
+    enforcement?: string;
+    metadata: WorldMetadata;
+}
+
+export type { AssumptionConfig, AssumptionProfile, CausalTranslation, CollapseCheck, CollapseVisual, ComparisonLayout, ComputedOutcome, ConditionalEffect, Effect, EffectOperation, GatesConfig, GovernanceEvent, Guard, GuardsConfig, IntentPattern, Invariant, KernelConfig, LensConfig, LensDirectiveConfig, LensesConfig, ModelIdentity, OutcomesConfig, ParameterDefinition, RoleArchetype, RoleAssignment, RoleAuthority, RolePosture, RoleTransition, RolesConfig, Rule, RuleRedirect, RuleSeverity, StatePreset, StateSchema, StateVariable, Trigger, TriggerOperator, ViabilityGate, ViabilityStatus, WorldDefinition, WorldIdentity, WorldMetadata, WorldRoleDefinition };