@neuroverseos/governance 0.4.0 → 0.4.1

package/dist/engine/simulate-engine.d.ts

@@ -0,0 +1,105 @@
+import { GovernanceEvent, ViabilityStatus, WorldDefinition } from '../types.js';
+
+/**
+ * Simulate Engine — Deterministic State Evolution (Reference Simulator)
+ *
+ * Pure function: (world, options) → SimulationResult
+ *
+ * This is NeuroVerse's REFERENCE SIMULATOR — one way to model how a world
+ * evolves over time. It is NOT the governance engine.
+ *
+ * simulateWorld() ≠ evaluateGuard()
+ *
+ *   evaluateGuard()  — Runtime enforcement. Decides if an action is allowed.
+ *                      Includes safety layer, role checks, plan enforcement,
+ *                      kernel rules, level constraints. Use for governance.
+ *
+ *   simulateWorld()  — State evolution modeling. Evaluates rule triggers,
+ *                      applies effects, tracks viability over N steps.
+ *                      Use for scenario planning and what-if analysis.
+ *
+ * World files (.nv-world.md) are portable — they define rules, roles, and
+ * constraints that can be consumed by any simulator or governance engine.
+ * This simulator is a reference implementation, not the only interpreter.
+ *
+ * Supports:
+ *   - Single-step evaluation (default)
+ *   - Multi-step iteration (--steps N)
+ *   - State overrides (start from non-default values)
+ *   - Assumption profile selection
+ *   - Collapse detection (early termination)
+ *
+ * INVARIANTS:
+ *   - Deterministic: same world + same options → same result.
+ *   - Zero network calls. Zero LLM calls. Zero async.
+ *   - Every rule evaluation is recorded in the trace.
+ *   - World definition is REQUIRED — no world, no simulation.
+ */
+
+interface SimulateOptions {
+    /** Number of simulation steps (default: 1) */
+    steps?: number;
+    /** State variable overrides (start values) */
+    stateOverrides?: Record<string, string | number | boolean>;
+    /** Assumption profile to use (default: world default) */
+    profile?: string;
+    /**
+     * Governance events to inject into the simulation.
+     * Events are applied before state-driven rules each step.
+     * This is the bridge: Guard → Events → Simulate → State Evolution.
+     *
+     * Events are distributed across steps (round-robin) or all applied to step 1
+     * if there are fewer steps than events.
+     */
+    events?: GovernanceEvent[];
+}
+interface SimulationResult {
+    worldId: string;
+    worldName: string;
+    profile: string;
+    initialState: Record<string, string | number | boolean>;
+    steps: SimulationStep[];
+    finalState: Record<string, string | number | boolean>;
+    finalViability: ViabilityStatus;
+    collapsed: boolean;
+    collapseStep?: number;
+    collapseRule?: string;
+    /** Total events consumed during simulation */
+    eventsConsumed: number;
+}
+interface SimulationStep {
+    step: number;
+    /** Events applied during this step (before rules) */
+    eventsApplied: EventApplication[];
+    rulesEvaluated: RuleEvaluation[];
+    rulesFired: number;
+    stateAfter: Record<string, string | number | boolean>;
+    viability: ViabilityStatus;
+    collapsed: boolean;
+}
+/** Record of an event applied during simulation */
+interface EventApplication {
+    eventType: string;
+    rulesTriggered: string[];
+    effects: AppliedEffect[];
+}
+interface RuleEvaluation {
+    ruleId: string;
+    label: string;
+    triggered: boolean;
+    excluded: boolean;
+    effects: AppliedEffect[];
+    collapsed: boolean;
+    collapseField?: string;
+}
+interface AppliedEffect {
+    target: string;
+    operation: string;
+    value: number | boolean | string;
+    before: string | number | boolean;
+    after: string | number | boolean;
+}
+declare function simulateWorld(world: WorldDefinition, options?: SimulateOptions): SimulationResult;
+declare function renderSimulateText(result: SimulationResult): string;
+
+export { type AppliedEffect, type EventApplication, type RuleEvaluation, type SimulateOptions, type SimulationResult, type SimulationStep, renderSimulateText, simulateWorld };

package/dist/engine/simulate-engine.js

@@ -0,0 +1,9 @@
+import {
+  renderSimulateText,
+  simulateWorld
+} from "../chunk-CYDMUJVZ.js";
+import "../chunk-QWGCMQQD.js";
+export {
+  renderSimulateText,
+  simulateWorld
+};

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

@@ -12,10 +12,10 @@ import {
 import {
   evaluateGuard
 } from "./chunk-ZAF6JH23.js";
-import "./chunk-QLPTHTVB.js";
 import {
   loadWorld
-} from "./chunk-BXLTEUS4.js";
+} from "./chunk-I4RTIMLX.js";
+import "./chunk-QLPTHTVB.js";
 import "./chunk-QWGCMQQD.js";
 
 // src/cli/equity-penalties.ts

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

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

package/dist/github-TIKTWOGU.js

@@ -0,0 +1,27 @@
+import {
+  GitHubGovernanceBlockedError,
+  GitHubGovernor,
+  GitHubWebhookHandler,
+  createGitHubGovernor,
+  createGitHubGovernorFromWorld,
+  createGitHubWebhookHandler,
+  createGitHubWebhookHandlerFromWorld,
+  formatForActions,
+  formatPRComment
+} from "./chunk-3S5AD4AB.js";
+import "./chunk-5U2MQO5P.js";
+import "./chunk-ZAF6JH23.js";
+import "./chunk-I4RTIMLX.js";
+import "./chunk-QLPTHTVB.js";
+import "./chunk-QWGCMQQD.js";
+export {
+  GitHubGovernanceBlockedError,
+  GitHubGovernor,
+  GitHubWebhookHandler,
+  createGitHubGovernor,
+  createGitHubGovernorFromWorld,
+  createGitHubWebhookHandler,
+  createGitHubWebhookHandlerFromWorld,
+  formatForActions,
+  formatPRComment
+};

package/dist/{guard-W3BMQPBJ.js → guard-6KSCWT2W.js}

@@ -13,10 +13,10 @@ import {
 import {
   evaluateGuard
 } from "./chunk-ZAF6JH23.js";
-import "./chunk-QLPTHTVB.js";
 import {
   loadWorld
-} from "./chunk-BXLTEUS4.js";
+} from "./chunk-I4RTIMLX.js";
+import "./chunk-QLPTHTVB.js";
 import "./chunk-QWGCMQQD.js";
 
 // src/cli/guard.ts

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

@@ -1,371 +1,4 @@
-/**
- * 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;
-}
+import { GovernanceEvent } from './types.cjs';
 
 /**
  * Plan Contract — Plan Enforcement Types
@@ -924,4 +557,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 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 };
+export { type AdvanceResult as A, type Consequence as C, type EvaluationTrace as E, type GuardEvent as G, type IntentRecord as I, type KernelRuleCheck as K, type LevelCheck as L, type PlanDefinition as P, type Reward as R, type StepEvidence as S, type VerdictEvidence as V, type GuardVerdict as a, type GuardEngineOptions as b, type PlanProgress as c, type GuardStatus as d, type PlanVerdict as e, type PlanCheck as f, type AgentBehaviorState as g, GUARD_EXIT_CODES as h, type GuardCheck as i, type GuardExitCode as j, type InvariantCheck as k, PLAN_EXIT_CODES as l, type PlanCompletionMode as m, type PlanConstraint as n, type PlanExitCode as o, type PlanStatus as p, type PlanStep as q, type PrecedenceResolution as r, type RoleCheck as s, type SafetyCheck as t };