@neuroverseos/governance 0.3.0 → 0.3.3

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { G as GuardEvent, W as WorldDefinition, c as GuardEngineOptions, a as GuardVerdict, P as PlanDefinition, S as StepEvidence, A as AdvanceResult, d as PlanVerdict, e as PlanCheck, b as PlanProgress, V as ViabilityStatus } from './guard-contract-WZx__PmU.js';
-export { E as EvaluationTrace, f as GUARD_EXIT_CODES, g as GuardCheck, h as GuardExitCode, i as GuardStatus, I as InvariantCheck, K as KernelRuleCheck, L as LevelCheck, j as PLAN_EXIT_CODES, k as PlanCompletionMode, l as PlanConstraint, m as PlanExitCode, n as PlanStatus, o as PlanStep, p as PrecedenceResolution, R as RoleCheck, q as SafetyCheck, r as VerdictEvidence } from './guard-contract-WZx__PmU.js';
+import { G as GuardEvent, W as WorldDefinition, b as GuardEngineOptions, a as GuardVerdict, P as PlanDefinition, S as StepEvidence, A as AdvanceResult, d as PlanVerdict, e as PlanCheck, c as PlanProgress, f as AgentBehaviorState, g as GuardStatus, C as Consequence, R as Reward, h as Guard, I as Invariant, i as Rule, V as ViabilityStatus } from './guard-contract-DqFcTScd.js';
+export { E as EvaluationTrace, j as GUARD_EXIT_CODES, k as GuardCheck, l as GuardExitCode, m as IntentRecord, n as InvariantCheck, K as KernelRuleCheck, L as LevelCheck, o as PLAN_EXIT_CODES, p as PlanCompletionMode, q as PlanConstraint, r as PlanExitCode, s as PlanStatus, t as PlanStep, u as PrecedenceResolution, v as RoleCheck, w as SafetyCheck, x as VerdictEvidence } from './guard-contract-DqFcTScd.js';
 
 /**
  * Guard Engine — Deterministic Governance Evaluator
@@ -28,12 +28,6 @@ export { E as EvaluationTrace, f as GUARD_EXIT_CODES, g as GuardCheck, h as Guar
  *   - No hidden logic. Everything is in the world file or declared here.
  */
 
-/**
- * Evaluate a guard event against a world definition.
- *
- * This is the entire guard engine. One function. Deterministic.
- * No class instantiation, no state, no side effects.
- */
 declare function evaluateGuard(event: GuardEvent, world: WorldDefinition, options?: GuardEngineOptions): GuardVerdict;
 /**
  * Build a normalized allowlist key from a GuardEvent.
@@ -291,6 +285,14 @@ interface SessionState {
     actionsBlocked: number;
     /** Total actions paused. */
     actionsPaused: number;
+    /** Total actions modified. */
+    actionsModified: number;
+    /** Total actions penalized. */
+    actionsPenalized: number;
+    /** Total actions rewarded. */
+    actionsRewarded: number;
+    /** Agent behavior states — tracks cooldowns, influence, rewards per agent. */
+    agentStates: Map<string, AgentBehaviorState>;
 }
 declare class SessionManager {
     private config;
@@ -307,6 +309,15 @@ declare class SessionManager {
      * Returns the verdict without executing anything.
      */
     evaluate(event: GuardEvent): GuardVerdict;
+    /**
+     * Advance all agent states by one round.
+     * Call this at the end of each simulation round to decrement cooldowns.
+     */
+    tickRound(): void;
+    /**
+     * Get the behavior state for a specific agent.
+     */
+    getAgentState(agentId: string): AgentBehaviorState | undefined;
     /**
      * Evaluate and execute a tool call.
      * Returns the execution result or block reason.
@@ -458,10 +469,27 @@ interface AuditEvent {
     actor?: string;
     direction?: 'input' | 'output';
     /** The governance decision */
-    decision: 'ALLOW' | 'BLOCK' | 'PAUSE';
+    decision: 'ALLOW' | 'BLOCK' | 'PAUSE' | 'MODIFY' | 'PENALIZE' | 'REWARD' | 'NEUTRAL';
     reason?: string;
     ruleId?: string;
     warning?: string;
+    /** Consequence applied (for PENALIZE decisions) */
+    consequence?: {
+        type: string;
+        rounds?: number;
+        magnitude?: number;
+        description: string;
+    };
+    /** Reward applied (for REWARD decisions) */
+    reward?: {
+        type: string;
+        rounds?: number;
+        magnitude?: number;
+        description: string;
+    };
+    /** Intent tracking — original vs final action */
+    originalIntent?: string;
+    finalAction?: string;
     /** Which rules/guards matched */
     guardsMatched: string[];
     rulesMatched: string[];
@@ -483,6 +511,10 @@ interface AuditSummary {
     allowed: number;
     blocked: number;
     paused: number;
+    modified: number;
+    penalized: number;
+    rewarded: number;
+    neutral: number;
     /** Unique actors seen */
     actors: string[];
     /** Actions grouped by intent */
@@ -491,6 +523,8 @@ interface AuditSummary {
         count: number;
         blocked: number;
         paused: number;
+        penalized: number;
+        rewarded: number;
     }[];
     /** Most frequently triggered rules */
     topRules: {
@@ -500,6 +534,13 @@ interface AuditSummary {
     /** Time range */
     firstEvent: string;
     lastEvent: string;
+    /** Behavioral economy summary */
+    behavioralEconomy: {
+        totalPenalties: number;
+        totalRewards: number;
+        netPressure: number;
+        redirectionRate: number;
+    };
 }
 /**
  * Pluggable audit logger interface.
@@ -667,8 +708,14 @@ interface ImpactReport {
     totalBlocked: number;
     totalPaused: number;
     totalAllowed: number;
-    /** Prevention rate: (blocked + paused) / total */
+    totalModified: number;
+    totalPenalized: number;
+    totalRewarded: number;
+    totalNeutral: number;
+    /** Prevention rate: (blocked + paused + modified + penalized) / total */
     preventionRate: number;
+    /** Redirection rate: everything not ALLOW/NEUTRAL */
+    redirectionRate: number;
     /** Blocked actions grouped by category */
     preventedByCategory: PreventionCategory[];
     /** Top prevented intents */
@@ -724,12 +771,170 @@ declare function renderImpactReport(report: ImpactReport): string;
  */
 declare function generateImpactReportFromFile(logPath: string): Promise<ImpactReport>;
 
+/**
+ * Decision Flow Engine — Intent → Rule → Outcome Visualization
+ *
+ * This is the core of the behavioral governance visualization.
+ * It transforms audit events into a flow structure that shows:
+ *
+ *   LEFT (Intent Pool)    →    CENTER (Rules)    →    RIGHT (Outcome Pool)
+ *   What agents wanted          What intercepted        What actually happened
+ *
+ * The gap between intent and outcome = governance value.
+ *
+ * Key metric: "X% of agent intent was redirected by governance"
+ *
+ * INVARIANTS:
+ *   - Pure function: audit events in, flow structure out.
+ *   - No speculation — only reports on actual evaluated actions.
+ *   - Every flow path is traceable to a specific audit event.
+ */
+
+/**
+ * A cluster of agents with the same intent.
+ */
+interface IntentCluster {
+    /** The original intent (e.g., "sell", "publish", "attack") */
+    intent: string;
+    /** Number of agents with this intent */
+    agentCount: number;
+    /** Intensity score (0-1) based on volume and risk */
+    intensity: number;
+    /** Individual agent IDs in this cluster */
+    agents: string[];
+}
+/**
+ * A rule that intercepted actions in the flow.
+ */
+interface RuleObstacle {
+    /** Rule/guard ID */
+    ruleId: string;
+    /** Human-readable label */
+    label: string;
+    /** How many actions this rule intercepted */
+    interceptCount: number;
+    /** Breakdown by enforcement type */
+    enforcements: {
+        blocked: number;
+        modified: number;
+        penalized: number;
+        paused: number;
+        rewarded: number;
+    };
+}
+/**
+ * An outcome cluster — what agents ended up doing.
+ */
+interface OutcomeCluster {
+    /** The enforcement type that produced this outcome */
+    enforcement: GuardStatus;
+    /** Number of agents with this outcome */
+    agentCount: number;
+    /** For MODIFY: what they were changed to */
+    modifiedTo?: string;
+    /** Agent IDs in this cluster */
+    agents: string[];
+    /** Visual style hint */
+    style: 'green' | 'yellow' | 'red' | 'gray' | 'blue' | 'white';
+}
+/**
+ * A single flow path from intent → rule → outcome.
+ */
+interface FlowPath {
+    /** Source intent */
+    intent: string;
+    /** Rule that intercepted (if any) */
+    ruleId?: string;
+    /** Resulting enforcement */
+    enforcement: GuardStatus;
+    /** Agent ID */
+    agentId: string;
+    /** Original action */
+    originalAction: string;
+    /** Final action */
+    finalAction: string;
+    /** Consequence applied (if PENALIZE) */
+    consequence?: Consequence;
+    /** Reward applied (if REWARD) */
+    reward?: Reward;
+}
+/**
+ * The complete Decision Flow — the visualization data structure.
+ *
+ * LEFT → CENTER → RIGHT
+ * Intents → Rules → Outcomes
+ */
+interface DecisionFlow {
+    /** Left column: intent clusters */
+    intents: IntentCluster[];
+    /** Center column: rule obstacles */
+    rules: RuleObstacle[];
+    /** Right column: outcome clusters */
+    outcomes: OutcomeCluster[];
+    /** Every individual flow path */
+    paths: FlowPath[];
+    /** Key metrics */
+    metrics: DecisionFlowMetrics;
+    /** Time window */
+    periodStart: string;
+    periodEnd: string;
+    worldName: string;
+}
+/**
+ * The headline metrics for the Decision Flow.
+ */
+interface DecisionFlowMetrics {
+    /** Total intents evaluated */
+    totalIntents: number;
+    /** How many were redirected (not ALLOW) */
+    totalRedirected: number;
+    /** Headline: "X% of agent intent was redirected by governance" */
+    redirectionRate: number;
+    /** Breakdown by enforcement type */
+    byEnforcement: Record<string, number>;
+    /** Total penalties applied */
+    totalPenalties: number;
+    /** Total rewards applied */
+    totalRewards: number;
+    /** Net behavioral pressure (rewards - penalties) */
+    netBehavioralPressure: number;
+}
+/**
+ * Generate a Decision Flow from audit events.
+ *
+ * This is the primary entry point — takes raw audit data and produces
+ * the complete visualization structure.
+ */
+declare function generateDecisionFlow(events: AuditEvent[]): DecisionFlow;
+/**
+ * Create a fresh agent behavior state.
+ */
+declare function createAgentState(agentId: string): AgentBehaviorState;
+/**
+ * Apply a consequence to an agent's behavior state.
+ * Returns the updated state (immutable — creates a new object).
+ */
+declare function applyConsequence(state: AgentBehaviorState, consequence: Consequence, ruleId: string): AgentBehaviorState;
+/**
+ * Apply a reward to an agent's behavior state.
+ * Returns the updated state (immutable).
+ */
+declare function applyReward(state: AgentBehaviorState, reward: Reward, ruleId: string): AgentBehaviorState;
+/**
+ * Advance all agent states by one round.
+ * Decrements cooldowns, applies time-based effects.
+ */
+declare function tickAgentStates(states: Map<string, AgentBehaviorState>): Map<string, AgentBehaviorState>;
+/**
+ * Render a Decision Flow as human-readable text.
+ * This is what `neuroverse decision-flow` prints.
+ */
+declare function renderDecisionFlow(flow: DecisionFlow): string;
+
 /**
  * World Loader — Shared world file loading for CLI commands
  *
- * Loads a WorldDefinition from either:
- *   - A directory containing individual JSON files
- *   - (Future) A .nv-world.zip archive
+ * Loads a WorldDefinition from a directory containing individual JSON files.
  *
  * Used by: neuroverse guard, neuroverse validate, neuroverse init
  * Not used by: neuroverse bootstrap (which produces world files, not consumes them)
@@ -744,7 +949,7 @@ declare function generateImpactReportFromFile(logPath: string): Promise<ImpactRe
  */
 declare function loadWorldFromDirectory(dirPath: string): Promise<WorldDefinition>;
 /**
- * Load a world from a path — auto-detects directory vs .nv-world.zip.
+ * Load a world from a directory path.
  */
 declare function loadWorld(worldPath: string): Promise<WorldDefinition>;
 
@@ -1285,6 +1490,103 @@ declare function emitWorldDefinition(parsed: ParsedWorld): {
     issues: ParseIssue[];
 };
 
+/**
+ * Add Engine — Incremental Governance Authoring
+ *
+ * Appends guards, rules, or invariants to a compiled world directory.
+ * Runs validation after every addition. Deterministic, no LLM calls.
+ *
+ * Three construct types map to user intent:
+ *   "Block X"                    → Guard   (action control)
+ *   "If X happens → Y changes"  → Rule    (world evolution)
+ *   "X must always be true"      → Invariant (hard constraint)
+ *
+ * Architecture:
+ *   addGuard()     → append to guards.json → validate → report
+ *   addRule()      → write rules/rule-NNN.json → validate → report
+ *   addInvariant() → append to invariants.json → validate → report
+ */
+
+interface AddResult {
+    /** What was added */
+    type: 'guard' | 'rule' | 'invariant';
+    /** The ID of the added construct */
+    id: string;
+    /** The file that was written */
+    file: string;
+    /** Whether validation passed after addition */
+    valid: boolean;
+    /** Validation findings (errors/warnings) introduced by this addition */
+    findings: ValidateReport['findings'];
+    /** The full object that was written */
+    construct: Guard | Rule | Invariant;
+}
+interface AddGuardInput {
+    /** Human-readable label (e.g., "Block dairy orders") */
+    label: string;
+    /** What enforcement to apply */
+    enforcement: Guard['enforcement'];
+    /** Intent patterns to match (e.g., ["order*dairy", "purchase*dairy"]) */
+    intentPatterns: string[];
+    /** Optional description */
+    description?: string;
+    /** Optional category override */
+    category?: Guard['category'];
+    /** Optional tool filter */
+    appliesTo?: string[];
+    /** Optional reason for block/pause */
+    reason?: string;
+    /** Optional invariant reference */
+    invariantRef?: string;
+    /** Optional explicit ID */
+    id?: string;
+}
+declare function addGuard(worldDir: string, input: AddGuardInput): Promise<AddResult>;
+interface AddRuleInput {
+    /** Human-readable label */
+    label: string;
+    /** Severity level */
+    severity: Rule['severity'];
+    /** Description of what this rule does */
+    description?: string;
+    /** Trigger conditions */
+    triggers: Rule['triggers'];
+    /** Effects when triggered */
+    effects?: Rule['effects'];
+    /** Optional collapse check */
+    collapseCheck?: Rule['collapse_check'];
+    /** Causal translation (human-readable explanation) */
+    causalTranslation?: Rule['causal_translation'];
+    /** Optional explicit ID */
+    id?: string;
+}
+declare function addRule(worldDir: string, input: AddRuleInput): Promise<AddResult>;
+interface AddInvariantInput {
+    /** Human-readable label (e.g., "Budget must never exceed 1000") */
+    label: string;
+    /** Enforcement type */
+    enforcement?: Invariant['enforcement'];
+    /** Optional explicit ID */
+    id?: string;
+}
+declare function addInvariant(worldDir: string, input: AddInvariantInput): Promise<AddResult>;
+/**
+ * Classify a natural-language intent into the correct construct type.
+ * This is a simple deterministic classifier — no LLM required.
+ *
+ * Returns 'guard' | 'rule' | 'invariant' | 'ambiguous'
+ */
+type ConstructType = 'guard' | 'rule' | 'invariant' | 'ambiguous';
+declare function classifyIntent(text: string): ConstructType;
+/**
+ * Parse a natural-language guard description into AddGuardInput.
+ * Handles common patterns like:
+ *   "Block dairy orders"
+ *   "Pause if cost > 500"
+ *   "Warn on shell access"
+ */
+declare function parseGuardDescription(text: string): AddGuardInput;
+
 /**
  * Derive Contract — AI-Assisted World Synthesis Types
  *
@@ -1501,12 +1803,26 @@ declare function explainWorld(world: WorldDefinition): ExplainOutput;
 declare function renderExplainText(output: ExplainOutput): string;
 
 /**
- * Simulate Engine — Deterministic State Evolution
+ * Simulate Engine — Deterministic State Evolution (Reference Simulator)
  *
  * Pure function: (world, options) → SimulationResult
  *
- * Evaluates all rules against the current state, applies effects,
- * classifies viability via gates, and produces a step-by-step trace.
+ * 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)
@@ -1519,6 +1835,7 @@ declare function renderExplainText(output: ExplainOutput): string;
  *   - 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 {
@@ -1613,4 +1930,266 @@ interface ImprovementReport {
 declare function improveWorld(world: WorldDefinition): ImprovementReport;
 declare function renderImproveText(report: ImprovementReport): string;
 
-export { type AIProvider, type AIProviderConfig, AdvanceResult, type AppliedEffect, type AuditEvent, type AuditLogger, type AuditSummary, BOOTSTRAP_EXIT_CODES, type BootstrapExitCode, type BootstrapResult, CONFIGURE_AI_EXIT_CODES, type ChatMessage, type CollectedSource, CompositeAuditLogger, type Condition, type ConditionOperator, type ConditionResult, ConsoleAuditLogger, DERIVE_EXIT_CODES, type DeriveExitCode, type DeriveFinding, type DeriveResult, type ExplainOutput, FileAuditLogger, type FindingCategory, type FindingSeverity, type FormatVerdictOptions, type GovernanceEngineOptions, type GovernanceHealth, GuardEngineOptions, GuardEvent, GuardVerdict, type ImpactReport, type ImprovementReport, McpGovernanceServer, type McpServerConfig, ModelAdapter, type ModelConfig, type ModelResponse, type NormalizationSummary, PROVIDERS, type ParseIssue, type ParsedAssumptionProfile, type ParsedEffect, type ParsedFrontmatter, type ParsedGate, type ParsedInvariant, type ParsedOutcome, type ParsedRule, type ParsedStateVariable, type ParsedTrigger, type ParsedWorld, PlanCheck, PlanDefinition, type PlanParseResult, PlanProgress, PlanVerdict, type PreventionCategory, type ProviderPreset, type RuleEvaluation, type SessionConfig, SessionManager, type SessionState, type SimulateOptions, type SimulationResult, type SimulationStep, StepEvidence, type Suggestion, type SuggestionCategory, type SuggestionPriority, type ToolCall, type ToolDefinition, VALIDATE_EXIT_CODES, type ValidateExitCode, type ValidateFinding, type ValidateReport, type ValidateSummary, type ValidationMode, type WorldInfo, advancePlan, buildPlanCheck, createGovernanceEngine, deriveWorld, describeActiveWorld, emitWorldDefinition, evaluateCondition, evaluateGuard, evaluatePlan, eventToAllowlistKey, explainWorld, extractWorldMarkdown, formatVerdict, formatVerdictOneLine, generateImpactReport, generateImpactReportFromFile, getActiveWorldName, getPlanProgress, improveWorld, listWorlds, loadWorld, loadWorldFromDirectory, normalizeWorldMarkdown, parsePlanMarkdown, parseWorldMarkdown, readAuditLog, renderExplainText, renderImpactReport, renderImproveText, renderSimulateText, resolveProvider, resolveWorldPath, runInteractiveMode, runPipeMode, setActiveWorld, simulateWorld, summarizeAuditEvents, validateWorld, verdictToAuditEvent };
+/**
+ * Runtime Types — Simple input types for HTTP/demo consumers
+ *
+ * These types are the "easy API" for code that doesn't load full world files.
+ * The govern() bridge converts these into the guard engine's native types.
+ */
+/**
+ * A plain-object description of an agent action.
+ * This is what HTTP clients and Python simulations send.
+ */
+interface AgentAction {
+    /** Agent or role identifier */
+    agentId: string;
+    /** Action type (e.g., "publish", "trade", "share", "cite") */
+    type: string;
+    /** Human-readable description of what the agent is doing */
+    description: string;
+    /** Action magnitude/intensity (0-1 scale) */
+    magnitude?: number;
+    /** Arbitrary context data */
+    context?: Record<string, unknown>;
+}
+/**
+ * Arbitrary key-value state passed alongside an action.
+ * Used by the simulation bridge to provide environmental context.
+ */
+type WorldState = Record<string, unknown>;
+/**
+ * Configuration for creating a governor instance.
+ */
+interface GovernorConfig {
+    /** Path to a .nv-world.md or .nv-world.zip file */
+    worldPath?: string;
+    /** Enable evaluation trace in verdicts */
+    trace?: boolean;
+    /** Enforcement level override */
+    level?: 'basic' | 'standard' | 'strict';
+}
+
+/**
+ * Govern — Thin bridge from HTTP/demo consumers to the real guard engine.
+ *
+ * This is NOT a second engine. It is NOT a parser.
+ * It converts AgentAction → GuardEvent, loads a world, and calls evaluateGuard().
+ * That's it. Zero intelligence. Zero interpretation.
+ *
+ * Rule parsing belongs in `neuroverse add`. Evaluation belongs in guard-engine.ts.
+ * This bridge just translates types and calls the real thing.
+ *
+ * Architecture:
+ *   [HTTP request] → govern(action, worldPath) → evaluateGuard(event, world) → GuardVerdict
+ */
+
+/**
+ * Convert an AgentAction (HTTP/demo format) → GuardEvent (engine format).
+ * Pure mapping. No interpretation. No intelligence.
+ */
+declare function actionToGuardEvent(action: AgentAction): GuardEvent;
+/**
+ * Evaluate a single action against a loaded world.
+ *
+ * This is the entire bridge. AgentAction in, GuardVerdict out.
+ * Uses the same evaluateGuard() as `neuroverse guard`.
+ */
+declare function govern(action: AgentAction, world: WorldDefinition, options?: GuardEngineOptions): GuardVerdict;
+/**
+ * A governor holds a loaded world and evaluates actions against it.
+ * Used by the demo server to avoid re-loading the world on every request.
+ */
+interface Governor {
+    /** Evaluate an action against the loaded world */
+    evaluate(action: AgentAction): GuardVerdict;
+    /** Reload the world from disk (call after rules change) */
+    reload(): Promise<void>;
+    /** The loaded world definition */
+    readonly world: WorldDefinition;
+}
+/**
+ * Create a governor instance that holds a loaded world.
+ *
+ * Usage:
+ *   const gov = await createGovernor({ worldPath: '/tmp/neuroverse-demo' });
+ *   const verdict = gov.evaluate(action);
+ *   // After rule changes:
+ *   await gov.reload();
+ */
+declare function createGovernor(config: GovernorConfig): Promise<Governor>;
+/**
+ * Write a minimal world directory from plain-text rules.
+ *
+ * This is for the demo server: UI sends plain-text rules,
+ * we write them as kernel forbidden_patterns, then load
+ * the world through the normal loadWorld() path.
+ *
+ * NO interpretation. Each rule line becomes a kernel forbidden pattern.
+ * The guard engine does the matching.
+ */
+declare function writeTempWorld(dir: string, policyLines: string[]): Promise<void>;
+
+/**
+ * Behavioral Contract — Types for the Behavioral Analysis Engine
+ *
+ * Extracted from behavioral-engine.ts so other modules (CLI, API, tests)
+ * can depend on the contract without pulling in implementation.
+ *
+ * Types:
+ *   ActionCategory  — Categories of agent actions for behavioral shift tracking
+ *   Adaptation      — A classified behavioral adaptation (what an agent did instead)
+ *   BehavioralPattern — An emergent behavioral pattern detected across agents
+ *   NetworkContext  — Network-level context for narrative generation
+ */
+
+/** Categories of agent actions for behavioral shift tracking */
+type ActionCategory = 'amplifying' | 'passive' | 'engaging' | 'corrective' | 'transactional' | 'creative' | 'analytical' | 'unknown';
+/** A classified behavioral adaptation — what an agent did instead */
+interface Adaptation {
+    /** Agent identifier */
+    agentId: string;
+    /** What the agent intended to do */
+    intendedAction: string;
+    /** What the agent actually did (after governance) */
+    executedAction: string;
+    /** Named behavioral shift category */
+    shiftType: string;
+    /** Governance status that caused the shift */
+    verdict: GuardStatus;
+    /** Rule that caused the shift */
+    ruleId?: string;
+    /** Human-readable reason */
+    reason?: string;
+}
+/** An emergent behavioral pattern detected across multiple agents */
+interface BehavioralPattern {
+    /** Pattern type identifier */
+    type: string;
+    /** Human-readable description */
+    description: string;
+    /** Pattern strength (0-1), based on fraction of agents affected */
+    strength: number;
+    /** Number of agents exhibiting this pattern */
+    agentsAffected: number;
+}
+/** Network-level context for narrative generation */
+interface NetworkContext {
+    mood?: string;
+    misinfoLevel?: number;
+    totalAgents?: number;
+    totalActions?: number;
+    [key: string]: unknown;
+}
+
+/**
+ * Behavioral Analysis Engine — What Governance UNLOCKS
+ *
+ * This is the differentiator. Every governance system can tell you
+ * what it blocked. Only NeuroVerse tells you:
+ *   - What agents did INSTEAD (adaptation classification)
+ *   - What patterns emerged COLLECTIVELY (behavioral detection)
+ *   - WHY it matters IN PROSE (narrative generation)
+ *
+ * "Governance is the engine — but we also always want to show people
+ *  the knowledge that constraining unlocks."
+ *
+ * Architecture:
+ *   GuardVerdict[] → classifyAdaptation() → Adaptation[]
+ *   Adaptation[]   → detectBehavioralPatterns() → BehavioralPattern[]
+ *   Pattern[]      → generateAdaptationNarrative() → string
+ *
+ * Pure functions. No network. No LLM. Deterministic.
+ */
+
+/**
+ * Classify what behavioral shift governance caused for a single agent action.
+ *
+ * Takes the original intent and the actual execution, returns a named shift.
+ * Pure function. No side effects.
+ */
+declare function classifyAdaptation(intendedAction: string, executedAction: string): string;
+/**
+ * Build an Adaptation from a GuardVerdict with intent tracking.
+ * Uses the IntentRecord attached to the verdict (if present).
+ */
+declare function adaptationFromVerdict(agentId: string, intendedAction: string, executedAction: string, verdict: GuardVerdict): Adaptation;
+/**
+ * Detect emergent collective patterns from a batch of adaptations.
+ *
+ * This is NOT just counting. It detects:
+ *   - Coordinated silence (many agents forced idle)
+ *   - Misinformation suppression (amplification specifically blocked)
+ *   - Constructive redirection (agents shifted to positive actions)
+ *   - High governance impact (large fraction of agents affected)
+ *   - Trading halt (transactional agents stopped)
+ *
+ * Pure function. Deterministic. Same inputs → same patterns.
+ */
+declare function detectBehavioralPatterns(adaptations: Adaptation[], totalAgents: number): BehavioralPattern[];
+/**
+ * Generate a human-readable cause-effect narrative from patterns.
+ *
+ * This is the "money moment" — the prose explanation of what governance
+ * caused to happen. Not a log. Not a report. A story.
+ *
+ * "5 agents went silent instead of amplifying. 3 redirected to fact-checking.
+ *  Network mood: polarized, misinfo level: 45%"
+ */
+declare function generateAdaptationNarrative(patterns: BehavioralPattern[], context?: NetworkContext): string;
+
+/**
+ * API Handlers — Server-side request handlers for the demo server.
+ *
+ * These are pure functions that handle HTTP request bodies and return
+ * response objects. No HTTP framework dependency — just data in, data out.
+ *
+ * The demo server (src/cli/demo.ts) wires these to routes.
+ */
+declare function handleHealthCheck(): {
+    status: string;
+    engine: string;
+    version: string;
+    capabilities: string[];
+};
+declare function handleListPresets(policiesDir?: string): Promise<{
+    presets: Array<{
+        id: string;
+        name: string;
+        description: string;
+        rules: string;
+    }>;
+}>;
+/**
+ * Run governed reasoning on a scenario.
+ * Takes a scenario description + world path, evaluates through the guard engine.
+ */
+declare function handleReasonRequest(body: {
+    scenario?: string;
+    worldPath?: string;
+    intent?: string;
+    tool?: string;
+    roleId?: string;
+}): Promise<Record<string, unknown>>;
+/**
+ * Create a shareable scenario capsule — a self-contained snapshot
+ * of a governance scenario that can be shared or replayed.
+ */
+declare function handleCreateCapsule(body: {
+    scenario?: string;
+    rules?: string[];
+    events?: Array<{
+        intent: string;
+        tool?: string;
+    }>;
+}): {
+    capsuleId: string;
+    scenario: string;
+    rules: string[];
+    events: Array<{
+        intent: string;
+        tool?: string;
+    }>;
+    createdAt: string;
+};
+
+export { type AIProvider, type AIProviderConfig, type ActionCategory, type Adaptation, type AddGuardInput, type AddInvariantInput, type AddResult, type AddRuleInput, AdvanceResult, type AgentAction, AgentBehaviorState, type AppliedEffect, type AuditEvent, type AuditLogger, type AuditSummary, BOOTSTRAP_EXIT_CODES, type BehavioralPattern, type BootstrapExitCode, type BootstrapResult, CONFIGURE_AI_EXIT_CODES, type ChatMessage, type CollectedSource, CompositeAuditLogger, type Condition, type ConditionOperator, type ConditionResult, Consequence, ConsoleAuditLogger, type ConstructType, DERIVE_EXIT_CODES, type DecisionFlow, type DecisionFlowMetrics, type DeriveExitCode, type DeriveFinding, type DeriveResult, type ExplainOutput, FileAuditLogger, type FindingCategory, type FindingSeverity, type FlowPath, type FormatVerdictOptions, type GovernanceEngineOptions, type GovernanceHealth, type Governor, type GovernorConfig, GuardEngineOptions, GuardEvent, GuardStatus, GuardVerdict, type ImpactReport, type ImprovementReport, type IntentCluster, McpGovernanceServer, type McpServerConfig, ModelAdapter, type ModelConfig, type ModelResponse, type NetworkContext, type NormalizationSummary, type OutcomeCluster, PROVIDERS, type ParseIssue, type ParsedAssumptionProfile, type ParsedEffect, type ParsedFrontmatter, type ParsedGate, type ParsedInvariant, type ParsedOutcome, type ParsedRule, type ParsedStateVariable, type ParsedTrigger, type ParsedWorld, PlanCheck, PlanDefinition, type PlanParseResult, PlanProgress, PlanVerdict, type PreventionCategory, type ProviderPreset, Reward, type RuleEvaluation, type RuleObstacle, type SessionConfig, SessionManager, type SessionState, type SimulateOptions, type SimulationResult, type SimulationStep, StepEvidence, type Suggestion, type SuggestionCategory, type SuggestionPriority, type ToolCall, type ToolDefinition, VALIDATE_EXIT_CODES, type ValidateExitCode, type ValidateFinding, type ValidateReport, type ValidateSummary, type ValidationMode, type WorldInfo, type WorldState, actionToGuardEvent, adaptationFromVerdict, addGuard, addInvariant, addRule, advancePlan, applyConsequence, applyReward, buildPlanCheck, classifyAdaptation, classifyIntent, createAgentState, createGovernanceEngine, createGovernor, deriveWorld, describeActiveWorld, detectBehavioralPatterns, emitWorldDefinition, evaluateCondition, evaluateGuard, evaluatePlan, eventToAllowlistKey, explainWorld, extractWorldMarkdown, formatVerdict, formatVerdictOneLine, generateAdaptationNarrative, generateDecisionFlow, generateImpactReport, generateImpactReportFromFile, getActiveWorldName, getPlanProgress, govern, handleCreateCapsule, handleHealthCheck, handleListPresets, handleReasonRequest, improveWorld, listWorlds, loadWorld, loadWorldFromDirectory, normalizeWorldMarkdown, parseGuardDescription, parsePlanMarkdown, parseWorldMarkdown, readAuditLog, renderDecisionFlow, renderExplainText, renderImpactReport, renderImproveText, renderSimulateText, resolveProvider, resolveWorldPath, runInteractiveMode, runPipeMode, setActiveWorld, simulateWorld, summarizeAuditEvents, tickAgentStates, validateWorld, verdictToAuditEvent, writeTempWorld };