@neuroverseos/governance 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -1,33 +1,1147 @@
+import { a as GuardEvent, W as WorldDefinition, b as GuardEngineOptions, G as GuardVerdict, V as ViabilityStatus } from './guard-contract-D_RQz9kt.js';
+export { E as EvaluationTrace, c as GUARD_EXIT_CODES, d as GuardCheck, e as GuardExitCode, f as GuardStatus, I as InvariantCheck, K as KernelRuleCheck, L as LevelCheck, P as PrecedenceResolution, R as RoleCheck, S as SafetyCheck, g as VerdictEvidence } from './guard-contract-D_RQz9kt.js';
+
 /**
- * NeuroVerseOS Governance Plugin for OpenClaw
+ * Guard Engine — Deterministic Governance Evaluator
  *
- * A governance layer that intercepts tool calls and enforces
- * ALLOW / PAUSE / BLOCK verdicts against structured world rules.
+ * Pure function: (event, world, options) → verdict
  *
- * Performance: Deterministic, local, no model calls. Sub-millisecond
- * per evaluation. Condition engine against world.json rules.
+ * Evaluates a GuardEvent against a loaded WorldDefinition and produces
+ * a GuardVerdict with evidence and optional evaluation trace.
  *
- * Logging: Quiet by default. Only BLOCK and PAUSE print to terminal.
- * Set "verbose": true to see all verdicts including ALLOW.
+ * Evaluation chain (first-match-wins on BLOCK/PAUSE):
+ *   1. Safety checks (prompt injection, scope escape)    → PAUSE
+ *   2. Role-specific rules (cannotDo, requiresApproval)  → BLOCK/PAUSE
+ *   3. Declarative guards (guards.json)                  → BLOCK/PAUSE/WARN
+ *   4. Kernel rules (kernel.json forbidden patterns)     → BLOCK
+ *   5. Level constraints (basic/standard/strict)         → PAUSE
+ *   6. Default                                           → ALLOW
  *
- * Audit: Every verdict logged to .neuroverseos/audit.jsonl.
+ * Invariant checks run unconditionally and are recorded in evidence
+ * but do not produce verdicts — they measure world health.
  *
- * Install:
- *   openclaw plugins install neuroverseos-governance
+ * INVARIANTS:
+ *   - Deterministic: same event + same world → same verdict.
+ *   - Zero network calls. Zero LLM calls. Zero async.
+ *   - Every check is recorded in the trace, not just the decider.
+ *   - 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.
+ *
+ * Format: `tool::intent` (both lowercased, intent trimmed).
+ * Tool defaults to '*' when absent.
+ *
+ * Callers use this to:
+ *   1. Add keys to the allowlist set (on user "allow-always" decision)
+ *   2. The engine uses it to check membership before evaluation
+ *
+ * The key is opaque — callers should always use this function
+ * rather than constructing keys manually.
+ */
+declare function eventToAllowlistKey(event: GuardEvent): string;
+
+/**
+ * Audit Logger — Runtime Governance Telemetry
+ *
+ * Records every action evaluated by the governance engine.
+ * Provides the governance paper trail: what happened, why, and when.
+ *
+ * Architecture:
+ *   - AuditEvent is the atomic record (one per evaluateGuard call)
+ *   - AuditLogger is the pluggable interface (file, database, stream)
+ *   - FileAuditLogger is the built-in file-based implementation
+ *   - createGovernanceEngine wraps evaluateGuard with automatic logging
+ *
+ * INVARIANTS:
+ *   - Logging never blocks or fails the governance decision
+ *   - Every AuditEvent includes the full verdict + evidence
+ *   - Events are append-only (immutable log)
+ */
+
+/**
+ * A single governance evaluation record.
+ * One of these is produced for every call to evaluateGuard.
+ */
+interface AuditEvent {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** World identity */
+    worldId: string;
+    worldName: string;
+    worldVersion: string;
+    /** The action that was evaluated */
+    intent: string;
+    tool?: string;
+    scope?: string;
+    actor?: string;
+    direction?: 'input' | 'output';
+    /** The governance decision */
+    decision: 'ALLOW' | 'BLOCK' | 'PAUSE';
+    reason?: string;
+    ruleId?: string;
+    warning?: string;
+    /** Which rules/guards matched */
+    guardsMatched: string[];
+    rulesMatched: string[];
+    /** Invariant health */
+    invariantsSatisfied: number;
+    invariantsTotal: number;
+    /** Enforcement level used */
+    enforcementLevel: string;
+    /** Evaluation duration in milliseconds (if trace was enabled) */
+    durationMs?: number;
+    /** Full event args (optional, for detailed audit) */
+    args?: Record<string, unknown>;
+}
+/**
+ * Summary of governance activity over a set of audit events.
+ */
+interface AuditSummary {
+    totalActions: number;
+    allowed: number;
+    blocked: number;
+    paused: number;
+    /** Unique actors seen */
+    actors: string[];
+    /** Actions grouped by intent */
+    topIntents: {
+        intent: string;
+        count: number;
+        blocked: number;
+        paused: number;
+    }[];
+    /** Most frequently triggered rules */
+    topRules: {
+        ruleId: string;
+        count: number;
+    }[];
+    /** Time range */
+    firstEvent: string;
+    lastEvent: string;
+}
+/**
+ * Pluggable audit logger interface.
+ * Implement this to send audit events to any destination.
+ */
+interface AuditLogger {
+    /** Append an audit event. Must not throw. */
+    log(event: AuditEvent): void | Promise<void>;
+    /** Flush any buffered events. */
+    flush?(): void | Promise<void>;
+}
+/**
+ * Append-only file logger using newline-delimited JSON (NDJSON).
+ * Each line is a self-contained JSON audit event.
+ *
+ * Log file location defaults to .neuroverse/audit.ndjson
+ */
+declare class FileAuditLogger implements AuditLogger {
+    private logPath;
+    private buffer;
+    private flushTimer;
+    private flushIntervalMs;
+    constructor(logPath: string, options?: {
+        flushIntervalMs?: number;
+    });
+    log(event: AuditEvent): void;
+    flush(): Promise<void>;
+}
+/**
+ * Simple logger that writes to stderr. Useful for development.
+ */
+declare class ConsoleAuditLogger implements AuditLogger {
+    log(event: AuditEvent): void;
+}
+/**
+ * Sends events to multiple loggers. Useful for file + console, file + webhook, etc.
+ */
+declare class CompositeAuditLogger implements AuditLogger {
+    private loggers;
+    constructor(...loggers: AuditLogger[]);
+    log(event: AuditEvent): void;
+    flush(): Promise<void>;
+}
+/**
+ * Convert a GuardEvent + GuardVerdict into an AuditEvent.
+ */
+declare function verdictToAuditEvent(event: GuardEvent, verdict: GuardVerdict): AuditEvent;
+interface GovernanceEngineOptions extends GuardEngineOptions {
+    /** Audit logger instance. If provided, every evaluation is logged. */
+    auditLogger?: AuditLogger;
+    /** Include args in audit events. Default: false (privacy). */
+    auditArgs?: boolean;
+}
+/**
+ * Create a governed evaluation function that wraps evaluateGuard
+ * with automatic audit logging.
+ *
+ * Usage:
+ *   const engine = createGovernanceEngine(world, {
+ *     auditLogger: new FileAuditLogger('.neuroverse/audit.ndjson'),
+ *   });
+ *
+ *   const verdict = engine.evaluate(event);
+ */
+declare function createGovernanceEngine(world: WorldDefinition, options?: GovernanceEngineOptions): {
+    /**
+     * Evaluate a governance event and log the result.
+     */
+    evaluate(event: GuardEvent): GuardVerdict;
+    /** Flush the audit logger. */
+    flush(): Promise<void>;
+    /** The underlying world definition. */
+    world: WorldDefinition;
+};
+/**
+ * Read audit events from an NDJSON log file.
+ *
+ * @param logPath - Path to the audit log file
+ * @param filter - Optional filter function
+ * @returns Array of matching audit events
+ */
+declare function readAuditLog(logPath: string, filter?: (event: AuditEvent) => boolean): Promise<AuditEvent[]>;
+/**
+ * Summarize a set of audit events.
+ */
+declare function summarizeAuditEvents(events: AuditEvent[]): AuditSummary;
+
+/**
+ * Verdict Formatter — Human-Readable Verdict Output
+ *
+ * Converts a GuardVerdict into a consistent, human-readable string.
+ * Used by adapters, CLIs, and UIs to display governance decisions.
+ *
+ * Design:
+ *   - One function, one concern: verdict → string
+ *   - No side effects, no I/O
+ *   - Adapters call this so every integration has consistent messaging
+ */
+
+interface FormatVerdictOptions {
+    /** Include rule/guard ID. Default: true. */
+    showRuleId?: boolean;
+    /** Include evidence summary. Default: false. */
+    showEvidence?: boolean;
+    /** Include warning if present. Default: true. */
+    showWarning?: boolean;
+    /** Use ANSI colors in output. Default: false. */
+    color?: boolean;
+    /** Compact single-line format. Default: false. */
+    compact?: boolean;
+}
+/**
+ * Format a GuardVerdict as a human-readable string.
+ *
+ * Examples:
+ *   formatVerdict(verdict)
+ *   // "BLOCKED\n  Rule: margin_floor\n  Reason: margin ratio below 10%"
+ *
+ *   formatVerdict(verdict, { compact: true })
+ *   // "BLOCKED — margin_floor: margin ratio below 10%"
+ *
+ *   formatVerdict(verdict, { color: true })
+ *   // Same but with ANSI colors
+ */
+declare function formatVerdict(verdict: GuardVerdict, options?: FormatVerdictOptions): string;
+/**
+ * Format a verdict as a short one-line status message.
+ * Useful for logging, status bars, and notifications.
+ *
+ * Example: "BLOCKED: margin_floor — margin ratio below 10%"
+ */
+declare function formatVerdictOneLine(verdict: GuardVerdict): string;
+
+/**
+ * Governance Impact Report — Counterfactual Audit
+ *
+ * Answers: "What would have happened if governance did not exist?"
+ *
+ * This is the killer enterprise feature. It doesn't just log what happened —
+ * it proves the value of governance by showing what it prevented.
+ *
+ * Architecture:
+ *   - Reads audit events (from FileAuditLogger NDJSON)
+ *   - Classifies blocked/paused actions by risk category
+ *   - Produces an ImpactReport with aggregated prevention metrics
+ *   - CLI renders as human-readable or JSON
+ *
+ * INVARIANTS:
+ *   - No speculation — only reports on actual evaluated actions
+ *   - Risk categories derived from world rules, not invented
+ *   - All numbers are exact counts from the audit log
+ */
+
+/**
+ * A counterfactual governance impact report.
+ */
+interface ImpactReport {
+    /** Report metadata */
+    generatedAt: string;
+    periodStart: string;
+    periodEnd: string;
+    worldName: string;
+    /** High-level stats */
+    totalEvaluations: number;
+    totalBlocked: number;
+    totalPaused: number;
+    totalAllowed: number;
+    /** Prevention rate: (blocked + paused) / total */
+    preventionRate: number;
+    /** Blocked actions grouped by category */
+    preventedByCategory: PreventionCategory[];
+    /** Top prevented intents */
+    topPreventedIntents: {
+        intent: string;
+        count: number;
+        topRule: string;
+    }[];
+    /** Actors with most blocked actions (potential policy violations) */
+    hotActors: {
+        actor: string;
+        blocked: number;
+        paused: number;
+        total: number;
+    }[];
+    /** Rules that triggered most often */
+    mostActiveRules: {
+        ruleId: string;
+        blockCount: number;
+        pauseCount: number;
+    }[];
+    /** Hourly activity pattern (governance load) */
+    hourlyDistribution: {
+        hour: number;
+        total: number;
+        blocked: number;
+    }[];
+    /** Repeat offenders: actions attempted more than once after being blocked */
+    repeatViolations: {
+        intent: string;
+        actor: string;
+        attempts: number;
+        firstSeen: string;
+        lastSeen: string;
+    }[];
+}
+interface PreventionCategory {
+    category: string;
+    count: number;
+    /** Example intents in this category */
+    examples: string[];
+}
+/**
+ * Generate a governance impact report from audit events.
+ */
+declare function generateImpactReport(events: AuditEvent[]): ImpactReport;
+/**
+ * Render an impact report as human-readable text.
+ */
+declare function renderImpactReport(report: ImpactReport): string;
+/**
+ * Generate an impact report directly from an audit log file.
+ */
+declare function generateImpactReportFromFile(logPath: string): Promise<ImpactReport>;
+
+/**
+ * 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
+ *
+ * Used by: neuroverse guard, neuroverse validate, neuroverse init
+ * Not used by: neuroverse bootstrap (which produces world files, not consumes them)
+ */
+
+/**
+ * Load a WorldDefinition from a directory of JSON files.
+ *
+ * Reads all standard world files and assembles them into a WorldDefinition.
+ * Missing optional files are handled gracefully with defaults.
+ * Missing required files (world.json) throw.
+ */
+declare function loadWorldFromDirectory(dirPath: string): Promise<WorldDefinition>;
+/**
+ * Load a world from a path — auto-detects directory vs .nv-world.zip.
+ */
+declare function loadWorld(worldPath: string): Promise<WorldDefinition>;
+
+/**
+ * Condition Engine — Structured operator evaluation
+ *
+ * Ported from the OpenClaw governance plugin. Provides 12 operators
+ * for evaluating conditions against guard events:
+ *
+ *   ==, !=, >, <, >=, <=, in,
+ *   contains, contains_any, matches_pattern, starts_with, ends_with
+ *
+ * Supports dot-notation field resolution (e.g. "args.command", "args.file_path")
+ * for inspecting tool arguments.
+ *
+ * Deterministic. No AI. No network. Sub-millisecond per evaluation.
+ */
+
+type ConditionOperator = '==' | '!=' | '>' | '<' | '>=' | '<=' | 'in' | 'contains' | 'contains_any' | 'matches_pattern' | 'starts_with' | 'ends_with';
+interface Condition {
+    field: string;
+    operator: ConditionOperator;
+    value: string | string[] | number | boolean;
+}
+interface ConditionResult {
+    matched: boolean;
+    evidence: string | null;
+}
+/**
+ * Evaluate a single condition against a guard event.
+ * Returns whether it matched and what evidence was found.
+ */
+declare function evaluateCondition(condition: Condition, event: GuardEvent): ConditionResult;
+
+/**
+ * Validate Contract — CLI World File Static Analysis Types
+ *
+ * Defines the input/output contract for `neuroverse validate`.
+ *
+ * WorldDefinition comes in (loaded from .nv-world.zip or directory).
+ * ValidateReport goes out (stdout JSON).
+ * Exit code encodes health: 0=PASS, 1=FAIL, 2=WARN.
+ *
+ * The validate engine performs static analysis on world files:
+ *   - Completeness: Are all required blocks present and non-empty?
+ *   - Referential integrity: Do rules reference declared state variables?
+ *   - Guard coverage: Do invariants have backing structural guards?
+ *   - Contradiction detection: Do rules conflict with each other?
+ *   - Orphan detection: Are there unreachable rules or unused variables?
+ *
+ * INVARIANTS:
+ *   - Deterministic: same world → same report.
+ *   - Zero network calls.
+ *   - Every finding includes the source block and a human-readable message.
+ */
+type FindingSeverity = 'error' | 'warning' | 'info';
+type FindingCategory = 'completeness' | 'referential-integrity' | 'guard-coverage' | 'contradiction' | 'orphan' | 'schema-violation' | 'semantic-tension';
+/**
+ * A single finding from static analysis.
+ */
+interface ValidateFinding {
+    /** Unique ID for this finding type (e.g., "missing-thesis", "orphan-rule-003") */
+    id: string;
+    /** Human-readable message */
+    message: string;
+    /** Error, warning, or informational */
+    severity: FindingSeverity;
+    /** What category of issue this is */
+    category: FindingCategory;
+    /** Which world file block(s) are affected */
+    affectedBlocks: string[];
+    /** Specific field or rule ID that triggered this finding */
+    source?: string;
+    /** Suggested fix (when deterministically derivable) */
+    suggestion?: string;
+}
+/**
+ * Summary of world health by category.
+ */
+interface ValidateSummary {
+    /** Total findings by severity */
+    errors: number;
+    warnings: number;
+    info: number;
+    /** Block completeness score (0-100) */
+    completenessScore: number;
+    /** Invariant coverage percentage (invariants with backing guards) */
+    invariantCoverage: number;
+    /** Whether the world is valid enough to run */
+    canRun: boolean;
+    /** Whether the world passes full validation (no errors) */
+    isHealthy: boolean;
+}
+/**
+ * The validate report — what goes to stdout.
+ *
+ * Exit codes:
+ *   0 = PASS  (no errors, world is healthy)
+ *   1 = FAIL  (errors found, world cannot run safely)
+ *   2 = WARN  (warnings found but world can run)
+ *   3 = ERROR (invalid input, could not parse world)
+ */
+interface ValidateReport {
+    /** World identity */
+    worldId: string;
+    worldName: string;
+    worldVersion: string;
+    /** When the validation ran */
+    validatedAt: number;
+    /** Duration of validation */
+    durationMs: number;
+    /** High-level summary */
+    summary: ValidateSummary;
+    /** All findings, ordered by severity (errors first) */
+    findings: ValidateFinding[];
+}
+declare const VALIDATE_EXIT_CODES: {
+    readonly PASS: 0;
+    readonly FAIL: 1;
+    readonly WARN: 2;
+    readonly ERROR: 3;
+};
+type ValidateExitCode = (typeof VALIDATE_EXIT_CODES)[keyof typeof VALIDATE_EXIT_CODES];
+
+/**
+ * Validate Engine — World File Static Analysis
+ *
+ * Pure function: (world) → report
+ *
+ * Performs comprehensive static analysis on a WorldDefinition:
+ *   1. Completeness — are required blocks present and non-empty?
+ *   2. Referential integrity — do rules reference declared variables?
+ *   3. Guard coverage — do invariants have backing structural guards?
+ *   4. Contradiction detection — do rules conflict?
+ *   5. Orphan detection — unused variables, unreachable rules
+ *   6. Schema validation — values within declared ranges
+ *
+ * INVARIANTS:
+ *   - Deterministic: same world → same report, always.
+ *   - Zero network calls. Zero LLM calls. Zero async.
+ *   - Every finding is traceable to specific world file blocks.
+ */
+
+/**
+ * Validate a world definition and produce a report.
+ *
+ * This is the entire validate engine. One function. Deterministic.
+ */
+declare function validateWorld(world: WorldDefinition): ValidateReport;
+
+/**
+ * Bootstrap Contract — Markdown → WorldDefinition Compilation Types
+ *
+ * Defines the input/output contract for `neuroverse bootstrap`.
+ *
+ * Input:  .nv-world.md file (structured markdown)
+ * Output: WorldDefinition (passed to validate, guard, or compileWorldToZip)
+ *
+ * The markdown format is:
+ *   - YAML frontmatter for world identity and metadata
+ *   - H1 sections for each block (Thesis, Invariants, State, etc.)
+ *   - Structured sub-sections within each block
+ *   - Deterministically parseable — no LLM, no heuristics
+ *
+ * Exit codes:
+ *   0 = SUCCESS  (compiled cleanly)
+ *   1 = FAIL     (parse errors, missing required sections)
+ *   3 = ERROR    (file not found, invalid input)
+ */
+type ParseSeverity = 'error' | 'warning' | 'info';
+/**
+ * A single parse issue found during markdown compilation.
+ */
+interface ParseIssue {
+    /** Line number in the source markdown (1-based) */
+    line: number;
+    /** Which section the issue was found in */
+    section: string;
+    /** Human-readable message */
+    message: string;
+    /** Severity */
+    severity: ParseSeverity;
+}
+/**
+ * The result of parsing a .nv-world.md file.
+ */
+interface BootstrapResult {
+    /** Whether compilation succeeded (no errors) */
+    success: boolean;
+    /** Source file path */
+    sourcePath: string;
+    /** All parse issues */
+    issues: ParseIssue[];
+    /** Parsed sections (for debugging) */
+    parsedSections: string[];
+    /** Duration */
+    durationMs: number;
+}
+/**
+ * YAML frontmatter parsed from the markdown header.
+ */
+interface ParsedFrontmatter {
+    world_id: string;
+    name: string;
+    version?: string;
+    runtime_mode?: string;
+    default_profile?: string;
+    alternative_profile?: string;
+}
+/**
+ * A parsed invariant from the Invariants section.
+ */
+interface ParsedInvariant {
+    id: string;
+    label: string;
+    enforcement: string;
+    mutable: boolean;
+    line: number;
+}
+/**
+ * A parsed state variable from the State section.
+ */
+interface ParsedStateVariable {
+    id: string;
+    type: 'number' | 'enum' | 'boolean';
+    default: string | number | boolean;
+    label: string;
+    description: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: string[];
+    line: number;
+}
+/**
+ * A parsed assumption profile from the Assumptions section.
+ */
+interface ParsedAssumptionProfile {
+    id: string;
+    name: string;
+    description: string;
+    parameters: Record<string, string | number | boolean>;
+    line: number;
+}
+/**
+ * A parsed trigger from a rule.
+ */
+interface ParsedTrigger {
+    field: string;
+    operator: string;
+    value: string | number | boolean;
+    source: 'state' | 'assumption';
+}
+/**
+ * A parsed effect from a rule.
+ */
+interface ParsedEffect {
+    target: string;
+    operation: string;
+    value: number | boolean | string;
+}
+/**
+ * A parsed rule from the Rules section.
+ */
+interface ParsedRule {
+    id: string;
+    label: string;
+    severity: string;
+    description?: string;
+    order: number;
+    triggers: ParsedTrigger[];
+    effects: ParsedEffect[];
+    collapse_check?: {
+        field: string;
+        operator: string;
+        value: number;
+    };
+    causal_translation?: {
+        trigger_text: string;
+        rule_text: string;
+        shift_text: string;
+        effect_text: string;
+    };
+    line: number;
+}
+/**
+ * A parsed gate from the Gates section.
+ */
+interface ParsedGate {
+    status: string;
+    field: string;
+    operator: string;
+    value: number;
+    line: number;
+}
+/**
+ * A parsed outcome from the Outcomes section.
+ */
+interface ParsedOutcome {
+    id: string;
+    type: string;
+    range?: [number, number];
+    display?: string;
+    label: string;
+    primary?: boolean;
+    assignment?: string;
+    line: number;
+}
+/**
+ * The full parsed intermediate representation.
+ */
+interface ParsedWorld {
+    frontmatter: ParsedFrontmatter;
+    thesis: string;
+    invariants: ParsedInvariant[];
+    stateVariables: ParsedStateVariable[];
+    assumptions: ParsedAssumptionProfile[];
+    rules: ParsedRule[];
+    gates: ParsedGate[];
+    outcomes: ParsedOutcome[];
+}
+declare const BOOTSTRAP_EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly FAIL: 1;
+    readonly ERROR: 3;
+};
+type BootstrapExitCode = (typeof BOOTSTRAP_EXIT_CODES)[keyof typeof BOOTSTRAP_EXIT_CODES];
+
+/**
+ * Bootstrap Parser — .nv-world.md → ParsedWorld
+ *
+ * Deterministic markdown parser for the NeuroVerse world authoring format.
+ * No LLM calls. No heuristics. Pattern matching on structured markdown.
+ *
+ * ## Markdown Format (.nv-world.md)
+ *
+ * ```markdown
+ * ---
+ * world_id: my-world
+ * name: My World
+ * version: 1.0.0
+ * default_profile: baseline
+ * alternative_profile: alternative
+ * ---
+ *
+ * # Thesis
+ * The structural claim this world tests...
+ *
+ * # Invariants
+ * - `invariant_id` — Label text (structural, immutable)
+ * - `another_id` — Another label (structural, immutable)
+ *
+ * # State
+ * ## variable_name
+ * - type: number
+ * - min: 0
+ * - max: 100
+ * - step: 5
+ * - default: 50
+ * - label: Human Label
+ * - description: What this variable represents
+ *
+ * ## another_variable
+ * - type: enum
+ * - options: option_a, option_b, option_c
+ * - default: option_a
+ * - label: Another Variable
+ * - description: Description here
+ *
+ * # Assumptions
+ * ## baseline
+ * - name: Baseline Scenario
+ * - description: The default conditions
+ * - param_key: param_value
+ *
+ * ## alternative
+ * - name: Alternative Scenario
+ * - description: What changes
+ * - param_key: different_value
+ *
+ * # Rules
+ * ## rule-001: Rule Label (structural)
+ * Description of what this rule does.
+ *
+ * When field == "value" [state] AND other_field > 50 [assumption]
+ * Then target *= 0.30, other_target = false
+ * Collapse: field < 0.03
+ *
+ * > trigger: Trigger text here
+ * > rule: Rule text here
+ * > shift: Shift text here
+ * > effect: Effect text here
+ *
+ * # Gates
+ * - THRIVING: effective_margin >= 40
+ * - STABLE: effective_margin >= 20
+ * - COMPRESSED: effective_margin >= 10
+ * - CRITICAL: effective_margin > 3
+ * - MODEL_COLLAPSES: effective_margin <= 3
+ *
+ * # Outcomes
+ * ## outcome_id
+ * - type: number
+ * - range: 0-100
+ * - display: percentage
+ * - label: Outcome Label
+ * - primary: true
+ * ```
+ */
+
+/**
+ * Parse a .nv-world.md string into a ParsedWorld.
+ *
+ * Returns the parsed world and a list of issues.
+ * Callers should check issues for severity === 'error' before proceeding.
+ */
+declare function parseWorldMarkdown(markdown: string): {
+    world: ParsedWorld | null;
+    issues: ParseIssue[];
+};
+
+/**
+ * Bootstrap Emitter — ParsedWorld → WorldDefinition
+ *
+ * Converts the intermediate representation from the parser
+ * into a proper WorldDefinition that the guard engine, validate engine,
+ * and compileWorldToZip() all consume.
+ *
+ * Fills in sensible defaults for optional fields.
+ * Reports issues when the parsed data can't cleanly map to the target type.
+ *
+ * Deterministic. Same parsed input → same WorldDefinition output.
+ */
+
+/**
+ * Convert a ParsedWorld into a WorldDefinition.
+ *
+ * Returns the world definition and any issues encountered during emission.
+ */
+declare function emitWorldDefinition(parsed: ParsedWorld): {
+    world: WorldDefinition;
+    issues: ParseIssue[];
+};
+
+/**
+ * Derive Contract — AI-Assisted World Synthesis Types
+ *
+ * Defines the input/output contract for `neuroverse derive`.
+ *
+ * Input:  Arbitrary markdown files/directories
+ * Output: .nv-world.md file constrained by DerivationWorld
+ *
+ * Exit codes:
+ *   0 = SUCCESS          (valid file written)
+ *   1 = VALIDATION_FAIL  (output failed parseWorldMarkdown)
+ *   2 = INPUT_ERROR      (missing input, empty dir, unreadable)
+ *   3 = PROVIDER_ERROR   (no config, API failure, timeout)
+ */
+declare const DERIVE_EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly VALIDATION_FAIL: 1;
+    readonly INPUT_ERROR: 2;
+    readonly PROVIDER_ERROR: 3;
+};
+type DeriveExitCode = (typeof DERIVE_EXIT_CODES)[keyof typeof DERIVE_EXIT_CODES];
+declare const CONFIGURE_AI_EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly VALIDATION_FAIL: 1;
+    readonly ERROR: 3;
+};
+interface DeriveResult {
+    success: boolean;
+    outputPath: string;
+    sectionsDetected: string[];
+    validationErrors: number;
+    validationWarnings: number;
+    findings: DeriveFinding[];
+    gate?: string;
+    normalization?: NormalizationSummary;
+    durationMs: number;
+}
+interface NormalizationSummary {
+    fixCount: number;
+    invariantIds: number;
+    gateThresholds: number;
+    triggerTags: number;
+}
+interface DeriveFinding {
+    severity: 'error' | 'warning';
+    section: string;
+    message: string;
+    line?: number;
+}
+interface CollectedSource {
+    filename: string;
+    content: string;
+}
+interface AIProviderConfig {
+    provider: string;
+    model: string;
+    apiKey: string;
+    endpoint: string | null;
+}
+interface AIProvider {
+    complete(systemPrompt: string, userPrompt: string): Promise<string>;
+}
+
+/**
+ * Derive Engine — AI-Assisted World Synthesis Pipeline
+ *
+ * Pipeline:
+ *   collect → prompt → AI → extract → parseWorldMarkdown → write → JSON
+ *
+ * DerivationWorld is advisory only:
+ *   - Gate status is reported but never blocks file writing
+ *   - parseWorldMarkdown errors ARE blocking (invalid .nv-world.md)
+ *   - Governance engine does NOT run during derive
+ */
+
+/**
+ * Extract .nv-world.md content from LLM response.
+ *
+ * Handles:
+ *   - Triple backtick fences (```markdown ... ``` or ``` ... ```)
+ *   - Sentinel markers (BEGIN NV WORLD / END NV WORLD)
+ *   - Raw content starting with ---
+ *
+ * Pre-parse safety: output must contain `world_id:` in frontmatter.
+ */
+declare function extractWorldMarkdown(raw: string): string | null;
+interface DeriveOptions {
+    inputPath: string;
+    outputPath: string;
+    validate: boolean;
+    dryRun: boolean;
+    providerOverride?: Partial<AIProviderConfig>;
+}
+declare function deriveWorld(options: DeriveOptions): Promise<{
+    result: DeriveResult;
+    exitCode: number;
+    dryRunOutput?: {
+        systemPrompt: string;
+        userPrompt: string;
+    };
+}>;
+
+/**
+ * Derive Normalizer — Post-processing pass for AI output drift
+ *
+ * Runs AFTER AI generation but BEFORE parsing. Normalizes common
+ * deviations from the strict .nv-world.md grammar so the parser
+ * can accept the output.
+ *
+ * Transformations:
+ *   1. Invariant lines: adds backtick-wrapped IDs when missing
+ *   2. Gate lines: converts symbolic values to numeric thresholds
+ *   3. Trigger lines: ensures [state] / [assumption] source tags
+ *
+ * INVARIANTS:
+ *   - Deterministic: same input → same output, always.
+ *   - Zero network calls. Zero LLM calls.
+ *   - Never removes content — only reformats.
+ *   - Operates on raw markdown string, not parsed structures.
+ */
+interface NormalizerReport {
+    /** Total number of lines fixed */
+    fixCount: number;
+    /** Number of invariant IDs wrapped in backticks */
+    invariantIds: number;
+    /** Number of symbolic gate thresholds converted to numeric */
+    gateThresholds: number;
+    /** Number of triggers tagged with [state] */
+    triggerTags: number;
+}
+/**
+ * Normalize AI-generated .nv-world.md content to fix common drift patterns.
+ *
+ * Returns the normalized markdown string and a detailed fix report.
+ */
+declare function normalizeWorldMarkdown(markdown: string): {
+    normalized: string;
+    fixCount: number;
+    report: NormalizerReport;
+};
+
+/**
+ * Explain Engine — Generates human-readable narrative summaries from compiled worlds.
+ *
+ * No AI calls. Pure template-based rendering from WorldDefinition data.
+ *
+ * Sections:
+ *   1. Core thesis and identity
+ *   2. Key dynamics (rules with causal_translation)
+ *   3. State variables (what can change)
+ *   4. Invariants (what cannot change)
+ *   5. Viability gates (health thresholds)
+ *   6. Dramatic tensions (opposing rule effects)
+ *   7. Outcomes (what gets measured)
+ */
+
+interface ExplainOutput {
+    worldName: string;
+    worldId: string;
+    thesis: string;
+    dynamics: DynamicSummary[];
+    stateVariables: VariableSummary[];
+    invariants: InvariantSummary[];
+    gates: GateSummary[];
+    tensions: TensionSummary[];
+    outcomes: OutcomeSummary[];
+    stats: WorldStats;
+}
+interface DynamicSummary {
+    ruleId: string;
+    label: string;
+    severity: string;
+    triggerDescription: string;
+    effectDescription: string;
+    targets: string[];
+}
+interface VariableSummary {
+    name: string;
+    label: string;
+    type: string;
+    defaultValue: string | number | boolean;
+    range?: string;
+}
+interface InvariantSummary {
+    id: string;
+    label: string;
+    enforcement: string;
+}
+interface GateSummary {
+    status: string;
+    field: string;
+    threshold: string;
+}
+interface TensionSummary {
+    variable: string;
+    increasedBy: string[];
+    decreasedBy: string[];
+}
+interface OutcomeSummary {
+    id: string;
+    label: string;
+    type: string;
+    primary: boolean;
+}
+interface WorldStats {
+    invariants: number;
+    stateVariables: number;
+    rules: number;
+    gates: number;
+    outcomes: number;
+    assumptions: number;
+}
+declare function explainWorld(world: WorldDefinition): ExplainOutput;
+declare function renderExplainText(output: ExplainOutput): string;
+
+/**
+ * Simulate Engine — Deterministic State Evolution
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+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;
+}
+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;
+}
+interface SimulationStep {
+    step: number;
+    rulesEvaluated: RuleEvaluation[];
+    rulesFired: number;
+    stateAfter: Record<string, string | number | boolean>;
+    viability: ViabilityStatus;
+    collapsed: boolean;
+}
+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;
+
+/**
+ * Improve Engine — Actionable Suggestions from World Analysis
+ *
+ * Pure function: (world) → ImprovementReport
+ *
+ * Runs validation, simulation, and structural analysis to produce
+ * prioritized, actionable suggestions for improving a world.
+ *
+ * Categories:
+ *   1. Critical fixes — errors that prevent the world from running
+ *   2. Structural gaps — missing guards, orphan variables, etc.
+ *   3. Balance suggestions — detected from simulation dynamics
+ *   4. Completeness — optional blocks that would strengthen the world
  *
- * Commands:
- *   /world              — Quick status dashboard
- *   /world summary      — One-line protection status
- *   /world status       — Full governance metrics (drift, audit, friction)
- *   /world laws         — Display the full constitution
- *   /world bootstrap    — Generate world.json from your .md files
- *   /world bind         — Bind agent identity to governance role
- *   /world unbind       — Remove agent role binding
- *   /world bindings     — Show all agent-to-role bindings
- *   /world propose      — Agent recommends governance amendments
- *   /world approve <id> — Human approves a proposed amendment
- *   /world export       — Export for use in other tools
- *   /world help         — Command reference
+ * INVARIANTS:
+ *   - Deterministic: same world → same report.
+ *   - Zero network calls. Zero LLM calls. Zero async.
  */
-export default function register(api: any): void;
-//# sourceMappingURL=index.d.ts.map
+
+type SuggestionPriority = 'critical' | 'high' | 'medium' | 'low';
+type SuggestionCategory = 'fix' | 'structure' | 'balance' | 'completeness' | 'coverage';
+interface Suggestion {
+    id: string;
+    priority: SuggestionPriority;
+    category: SuggestionCategory;
+    title: string;
+    description: string;
+    action: string;
+    affectedFiles: string[];
+}
+interface ImprovementReport {
+    worldId: string;
+    worldName: string;
+    score: number;
+    suggestions: Suggestion[];
+    stats: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+    };
+}
+declare function improveWorld(world: WorldDefinition): ImprovementReport;
+declare function renderImproveText(report: ImprovementReport): string;
+
+export { type AIProvider, type AIProviderConfig, type AppliedEffect, type AuditEvent, type AuditLogger, type AuditSummary, BOOTSTRAP_EXIT_CODES, type BootstrapExitCode, type BootstrapResult, CONFIGURE_AI_EXIT_CODES, 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, GuardEngineOptions, GuardEvent, GuardVerdict, type ImpactReport, type ImprovementReport, type NormalizationSummary, type ParseIssue, type ParsedAssumptionProfile, type ParsedEffect, type ParsedFrontmatter, type ParsedGate, type ParsedInvariant, type ParsedOutcome, type ParsedRule, type ParsedStateVariable, type ParsedTrigger, type ParsedWorld, type PreventionCategory, type RuleEvaluation, type SimulateOptions, type SimulationResult, type SimulationStep, type Suggestion, type SuggestionCategory, type SuggestionPriority, VALIDATE_EXIT_CODES, type ValidateExitCode, type ValidateFinding, type ValidateReport, type ValidateSummary, createGovernanceEngine, deriveWorld, emitWorldDefinition, evaluateCondition, evaluateGuard, eventToAllowlistKey, explainWorld, extractWorldMarkdown, formatVerdict, formatVerdictOneLine, generateImpactReport, generateImpactReportFromFile, improveWorld, loadWorld, loadWorldFromDirectory, normalizeWorldMarkdown, parseWorldMarkdown, readAuditLog, renderExplainText, renderImpactReport, renderImproveText, renderSimulateText, simulateWorld, summarizeAuditEvents, validateWorld, verdictToAuditEvent };