@neuroverseos/governance 0.2.2 → 0.2.3

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { a as GuardEvent, W as WorldDefinition, c as GuardEngineOptions, G 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-Cm91Kp4j.cjs';
-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-Cm91Kp4j.cjs';
+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, V as ViabilityStatus } from './guard-contract-C9_zKbzd.cjs';
+export { E as EvaluationTrace, h as GUARD_EXIT_CODES, i as GuardCheck, j as GuardExitCode, I as IntentRecord, k as InvariantCheck, K as KernelRuleCheck, L as LevelCheck, l as PLAN_EXIT_CODES, m as PlanCompletionMode, n as PlanConstraint, o as PlanExitCode, p as PlanStatus, q as PlanStep, r as PrecedenceResolution, s as RoleCheck, t as SafetyCheck, u as VerdictEvidence } from './guard-contract-C9_zKbzd.cjs';
 
 /**
  * Guard Engine — Deterministic Governance Evaluator
@@ -291,6 +291,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 +315,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 +475,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 +517,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 +529,8 @@ interface AuditSummary {
         count: number;
         blocked: number;
         paused: number;
+        penalized: number;
+        rewarded: number;
     }[];
     /** Most frequently triggered rules */
     topRules: {
@@ -500,6 +540,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 +714,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,6 +777,166 @@ 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
  *
@@ -1613,4 +1826,4 @@ 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 };
+export { type AIProvider, type AIProviderConfig, AdvanceResult, AgentBehaviorState, 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, Consequence, ConsoleAuditLogger, 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, GuardEngineOptions, GuardEvent, GuardStatus, GuardVerdict, type ImpactReport, type ImprovementReport, type IntentCluster, McpGovernanceServer, type McpServerConfig, ModelAdapter, type ModelConfig, type ModelResponse, 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, advancePlan, applyConsequence, applyReward, buildPlanCheck, createAgentState, createGovernanceEngine, deriveWorld, describeActiveWorld, emitWorldDefinition, evaluateCondition, evaluateGuard, evaluatePlan, eventToAllowlistKey, explainWorld, extractWorldMarkdown, formatVerdict, formatVerdictOneLine, generateDecisionFlow, generateImpactReport, generateImpactReportFromFile, getActiveWorldName, getPlanProgress, improveWorld, listWorlds, loadWorld, loadWorldFromDirectory, normalizeWorldMarkdown, parsePlanMarkdown, parseWorldMarkdown, readAuditLog, renderDecisionFlow, renderExplainText, renderImpactReport, renderImproveText, renderSimulateText, resolveProvider, resolveWorldPath, runInteractiveMode, runPipeMode, setActiveWorld, simulateWorld, summarizeAuditEvents, tickAgentStates, validateWorld, verdictToAuditEvent };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as GuardEvent, W as WorldDefinition, c as GuardEngineOptions, G 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-Cm91Kp4j.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-Cm91Kp4j.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, V as ViabilityStatus } from './guard-contract-C9_zKbzd.js';
+export { E as EvaluationTrace, h as GUARD_EXIT_CODES, i as GuardCheck, j as GuardExitCode, I as IntentRecord, k as InvariantCheck, K as KernelRuleCheck, L as LevelCheck, l as PLAN_EXIT_CODES, m as PlanCompletionMode, n as PlanConstraint, o as PlanExitCode, p as PlanStatus, q as PlanStep, r as PrecedenceResolution, s as RoleCheck, t as SafetyCheck, u as VerdictEvidence } from './guard-contract-C9_zKbzd.js';
 
 /**
  * Guard Engine — Deterministic Governance Evaluator
@@ -291,6 +291,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 +315,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 +475,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 +517,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 +529,8 @@ interface AuditSummary {
         count: number;
         blocked: number;
         paused: number;
+        penalized: number;
+        rewarded: number;
     }[];
     /** Most frequently triggered rules */
     topRules: {
@@ -500,6 +540,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 +714,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,6 +777,166 @@ 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
  *
@@ -1613,4 +1826,4 @@ 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 };
+export { type AIProvider, type AIProviderConfig, AdvanceResult, AgentBehaviorState, 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, Consequence, ConsoleAuditLogger, 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, GuardEngineOptions, GuardEvent, GuardStatus, GuardVerdict, type ImpactReport, type ImprovementReport, type IntentCluster, McpGovernanceServer, type McpServerConfig, ModelAdapter, type ModelConfig, type ModelResponse, 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, advancePlan, applyConsequence, applyReward, buildPlanCheck, createAgentState, createGovernanceEngine, deriveWorld, describeActiveWorld, emitWorldDefinition, evaluateCondition, evaluateGuard, evaluatePlan, eventToAllowlistKey, explainWorld, extractWorldMarkdown, formatVerdict, formatVerdictOneLine, generateDecisionFlow, generateImpactReport, generateImpactReportFromFile, getActiveWorldName, getPlanProgress, improveWorld, listWorlds, loadWorld, loadWorldFromDirectory, normalizeWorldMarkdown, parsePlanMarkdown, parseWorldMarkdown, readAuditLog, renderDecisionFlow, renderExplainText, renderImpactReport, renderImproveText, renderSimulateText, resolveProvider, resolveWorldPath, runInteractiveMode, runPipeMode, setActiveWorld, simulateWorld, summarizeAuditEvents, tickAgentStates, validateWorld, verdictToAuditEvent };