@neuroverseos/governance 0.4.0 → 0.4.1

package/dist/index.d.cts

@@ -1,61 +1,13 @@
-import { G as GuardEvent, W as WorldDefinition, b as GuardEngineOptions, a as GuardVerdict, d as GuardStatus, e as GovernanceEvent, P as PlanDefinition, S as StepEvidence, A as AdvanceResult, f as PlanVerdict, g as PlanCheck, c as PlanProgress, h as AgentBehaviorState, C as Consequence, R as Reward, i as Guard, I as Invariant, j as Rule, V as ViabilityStatus } from './guard-contract-CLBbTGK_.cjs';
-export { E as EvaluationTrace, k as GUARD_EXIT_CODES, l as GuardCheck, m as GuardExitCode, n as IntentRecord, o as InvariantCheck, K as KernelRuleCheck, L as LevelCheck, p as PLAN_EXIT_CODES, q as PlanCompletionMode, r as PlanConstraint, s as PlanExitCode, t as PlanStatus, u as PlanStep, v as PrecedenceResolution, w as RoleCheck, x as SafetyCheck, y as VerdictEvidence } from './guard-contract-CLBbTGK_.cjs';
-
-/**
- * Guard Engine — Deterministic Governance Evaluator
- *
- * Pure function: (event, world, options) → verdict
- *
- * Evaluates a GuardEvent against a loaded WorldDefinition and produces
- * a GuardVerdict with evidence and optional evaluation trace.
- *
- * Evaluation chain (first-match-wins on BLOCK/PAUSE):
- *   1.   Safety checks (prompt injection, scope escape)    → PAUSE
- *   1.5  Plan enforcement (task scope)                     → BLOCK/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
- *
- * Invariant checks run unconditionally and are recorded in evidence
- * but do not produce verdicts — they measure world health.
- *
- * 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.
- */
-
-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;
-/**
- * Convert a guard verdict into a GovernanceEvent.
- *
- * The guard evaluation log IS the event stream.
- * No Kafka, no queues — just data flowing from Guard → Simulate.
- *
- * Mapping:
- *   ALLOW  → "action_allowed"
- *   BLOCK  → "action_blocked"
- *   PAUSE  → "action_paused"
- *   + semantic type from intent when available
- */
-declare function verdictToEvent(status: GuardStatus, intent?: string): GovernanceEvent;
+export { evaluateGuard, eventToAllowlistKey, verdictToEvent } from './engine/guard-engine.cjs';
+import { b as GuardEngineOptions, a as GuardVerdict, G as GuardEvent, P as PlanDefinition, S as StepEvidence, A as AdvanceResult, e as PlanVerdict, f as PlanCheck, c as PlanProgress, g as AgentBehaviorState, d as GuardStatus, C as Consequence, R as Reward } from './guard-contract-C991HDZp.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, V as VerdictEvidence } from './guard-contract-C991HDZp.cjs';
+import { WorldDefinition, Guard, Invariant, Rule } from './types.cjs';
+export { GovernanceEvent } from './types.cjs';
+export { parseWorldMarkdown } from './engine/bootstrap-parser.cjs';
+export { emitWorldDefinition } from './engine/bootstrap-emitter.cjs';
+export { B as BOOTSTRAP_EXIT_CODES, b as BootstrapExitCode, c as BootstrapResult, a as ParseIssue, d as ParsedAssumptionProfile, e as ParsedEffect, f as ParsedFrontmatter, g as ParsedGate, h as ParsedInvariant, i as ParsedOutcome, j as ParsedRule, k as ParsedStateVariable, l as ParsedTrigger, P as ParsedWorld } from './bootstrap-contract-DcV6t-8M.cjs';
+export { AppliedEffect, EventApplication, RuleEvaluation, SimulateOptions, SimulationResult, SimulationStep, renderSimulateText, simulateWorld } from './engine/simulate-engine.cjs';
+import { G as GovernanceBlockedError } from './shared-DGnn1jiS.cjs';
 
 /**
  * Derive Contract — AI-Assisted World Synthesis Types
@@ -1427,337 +1379,6 @@ type ValidateExitCode = (typeof VALIDATE_EXIT_CODES)[keyof typeof VALIDATE_EXIT_
  */
 declare function validateWorld(world: WorldDefinition, mode?: ValidationMode): 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;
-}
-/**
- * A parsed lens directive from the Lenses section.
- */
-interface ParsedLensDirective {
-    id: string;
-    scope: string;
-    instruction: string;
-    line: number;
-}
-/**
- * A parsed lens from the Lenses section.
- * Each lens is an H2 subsection with key-value properties and directives.
- */
-interface ParsedLens {
-    id: string;
-    name: string;
-    tagline: string;
-    description: string;
-    tags: string[];
-    /** Tone: formality, verbosity, emotion, confidence */
-    formality: string;
-    verbosity: string;
-    emotion: string;
-    confidence: string;
-    /** Which roles this lens is the default for */
-    defaultForRoles: string[];
-    /** Behavioral directives */
-    directives: ParsedLensDirective[];
-    /** Priority when stacking (higher = applied later) */
-    priority: number;
-    /** Whether it can be stacked with other lenses */
-    stackable: boolean;
-    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[];
-    lenses: ParsedLens[];
-    lensPolicy?: 'locked' | 'role_default' | 'user_choice';
-    lensLockPin?: string;
-}
-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[];
-};
-
 /**
  * Add Engine — Incremental Governance Authoring
  *
@@ -2007,108 +1628,6 @@ interface WorldStats {
 declare function explainWorld(world: WorldDefinition): ExplainOutput;
 declare function renderExplainText(output: ExplainOutput): string;
 
-/**
- * Simulate Engine — Deterministic State Evolution (Reference Simulator)
- *
- * Pure function: (world, options) → SimulationResult
- *
- * This is NeuroVerse's REFERENCE SIMULATOR — one way to model how a world
- * evolves over time. It is NOT the governance engine.
- *
- * simulateWorld() ≠ evaluateGuard()
- *
- *   evaluateGuard()  — Runtime enforcement. Decides if an action is allowed.
- *                      Includes safety layer, role checks, plan enforcement,
- *                      kernel rules, level constraints. Use for governance.
- *
- *   simulateWorld()  — State evolution modeling. Evaluates rule triggers,
- *                      applies effects, tracks viability over N steps.
- *                      Use for scenario planning and what-if analysis.
- *
- * World files (.nv-world.md) are portable — they define rules, roles, and
- * constraints that can be consumed by any simulator or governance engine.
- * This simulator is a reference implementation, not the only interpreter.
- *
- * Supports:
- *   - Single-step evaluation (default)
- *   - Multi-step iteration (--steps N)
- *   - State overrides (start from non-default values)
- *   - Assumption profile selection
- *   - Collapse detection (early termination)
- *
- * INVARIANTS:
- *   - Deterministic: same world + same options → same result.
- *   - Zero network calls. Zero LLM calls. Zero async.
- *   - Every rule evaluation is recorded in the trace.
- *   - World definition is REQUIRED — no world, no simulation.
- */
-
-interface SimulateOptions {
-    /** Number of simulation steps (default: 1) */
-    steps?: number;
-    /** State variable overrides (start values) */
-    stateOverrides?: Record<string, string | number | boolean>;
-    /** Assumption profile to use (default: world default) */
-    profile?: string;
-    /**
-     * Governance events to inject into the simulation.
-     * Events are applied before state-driven rules each step.
-     * This is the bridge: Guard → Events → Simulate → State Evolution.
-     *
-     * Events are distributed across steps (round-robin) or all applied to step 1
-     * if there are fewer steps than events.
-     */
-    events?: GovernanceEvent[];
-}
-interface SimulationResult {
-    worldId: string;
-    worldName: string;
-    profile: string;
-    initialState: Record<string, string | number | boolean>;
-    steps: SimulationStep[];
-    finalState: Record<string, string | number | boolean>;
-    finalViability: ViabilityStatus;
-    collapsed: boolean;
-    collapseStep?: number;
-    collapseRule?: string;
-    /** Total events consumed during simulation */
-    eventsConsumed: number;
-}
-interface SimulationStep {
-    step: number;
-    /** Events applied during this step (before rules) */
-    eventsApplied: EventApplication[];
-    rulesEvaluated: RuleEvaluation[];
-    rulesFired: number;
-    stateAfter: Record<string, string | number | boolean>;
-    viability: ViabilityStatus;
-    collapsed: boolean;
-}
-/** Record of an event applied during simulation */
-interface EventApplication {
-    eventType: string;
-    rulesTriggered: string[];
-    effects: AppliedEffect[];
-}
-interface RuleEvaluation {
-    ruleId: string;
-    label: string;
-    triggered: boolean;
-    excluded: boolean;
-    effects: AppliedEffect[];
-    collapsed: boolean;
-    collapseField?: string;
-}
-interface AppliedEffect {
-    target: string;
-    operation: string;
-    value: number | boolean | string;
-    before: string | number | boolean;
-    after: string | number | boolean;
-}
-declare function simulateWorld(world: WorldDefinition, options?: SimulateOptions): SimulationResult;
-declare function renderSimulateText(result: SimulationResult): string;
-
 /**
  * Improve Engine — Actionable Suggestions from World Analysis
  *
@@ -2361,6 +1880,226 @@ declare function detectBehavioralPatterns(adaptations: Adaptation[], totalAgents
  */
 declare function generateAdaptationNarrative(patterns: BehavioralPattern[], context?: NetworkContext): string;
 
+/**
+ * NeuroVerse Adapter — GitHub
+ *
+ * Governance middleware for GitHub-driven workflows. Evaluates GitHub events
+ * (PRs, issues, comments, pushes, releases, workflow runs) against world rules
+ * before allowing actions to proceed.
+ *
+ * Two modes:
+ *   1. Webhook mode — receives GitHub webhook payloads, evaluates, returns verdict
+ *   2. Action mode — wraps Octokit/GitHub API calls with governance checks
+ *
+ * Usage (Webhook):
+ *   import { createGitHubWebhookHandler } from 'neuroverse-governance/adapters/github';
+ *
+ *   const handler = await createGitHubWebhookHandler('./world/');
+ *   app.post('/webhook', async (req, res) => {
+ *     const verdict = handler.evaluate(req.headers['x-github-event'], req.body);
+ *     if (verdict.status === 'BLOCK') return res.status(403).json({ blocked: true });
+ *     // proceed with webhook processing...
+ *   });
+ *
+ * Usage (Action):
+ *   import { createGitHubGovernor } from 'neuroverse-governance/adapters/github';
+ *
+ *   const gov = await createGitHubGovernor('./world/');
+ *
+ *   // Before merging a PR:
+ *   const verdict = gov.evaluate({
+ *     action: 'merge_pull_request',
+ *     repository: 'myorg/myrepo',
+ *     ref: 'refs/heads/main',
+ *     actor: 'dependabot[bot]',
+ *     metadata: { pr_number: 42, labels: ['auto-merge'] },
+ *   });
+ *
+ *   if (verdict.status === 'ALLOW') await octokit.pulls.merge(...);
+ */
+
+/** GitHub webhook event names the adapter understands. */
+type GitHubWebhookEvent = 'push' | 'pull_request' | 'pull_request_review' | 'issues' | 'issue_comment' | 'release' | 'workflow_run' | 'workflow_dispatch' | 'check_run' | 'check_suite' | 'deployment' | 'deployment_status' | 'create' | 'delete' | 'fork' | 'member' | 'repository' | 'status' | string;
+/** A structured GitHub action to evaluate against governance. */
+interface GitHubAction {
+    /** What the actor wants to do (e.g., 'merge_pull_request', 'push_to_main', 'create_release'). */
+    action: string;
+    /** Full repository name (e.g., 'myorg/myrepo'). */
+    repository: string;
+    /** Git ref involved (e.g., 'refs/heads/main', 'refs/tags/v1.0.0'). */
+    ref?: string;
+    /** GitHub username or bot performing the action. */
+    actor?: string;
+    /** Branch being targeted (extracted from ref or PR base). */
+    branch?: string;
+    /** Additional context for guard evaluation. */
+    metadata?: Record<string, unknown>;
+}
+/** Result of evaluating a GitHub action. */
+interface GitHubGovernanceResult {
+    /** The guard verdict. */
+    verdict: GuardVerdict;
+    /** The GuardEvent that was evaluated (for audit/logging). */
+    event: GuardEvent;
+    /** The original action that triggered evaluation. */
+    action: GitHubAction;
+}
+/** Result of evaluating a webhook payload. */
+interface WebhookGovernanceResult {
+    /** The guard verdict. */
+    verdict: GuardVerdict;
+    /** The GuardEvent that was evaluated. */
+    event: GuardEvent;
+    /** The webhook event type. */
+    webhookEvent: string;
+    /** The webhook action (e.g., 'opened', 'closed', 'merged'). */
+    webhookAction?: string;
+}
+interface GitHubGovernorOptions {
+    /** Include full evaluation trace in verdicts. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called for every evaluation (logging/audit hook). */
+    onEvaluate?: (verdict: GuardVerdict, event: GuardEvent, action: GitHubAction) => void;
+    /** Custom mapping from GitHubAction to GuardEvent. */
+    mapAction?: (action: GitHubAction) => GuardEvent;
+    /** Active plan overlay for task-scoped governance. */
+    plan?: PlanDefinition;
+    /** Called when plan progress changes. */
+    onPlanProgress?: (progress: PlanProgress) => void;
+    /** Called when all plan steps are completed. */
+    onPlanComplete?: () => void;
+    /** Protected branches that require strict governance. Default: ['main', 'master', 'production']. */
+    protectedBranches?: string[];
+    /** Actors (bots, users) with restricted permissions. */
+    restrictedActors?: string[];
+}
+interface WebhookHandlerOptions extends GitHubGovernorOptions {
+    /** Webhook secret for signature verification (HMAC-SHA256). */
+    webhookSecret?: string;
+    /** Custom mapping from webhook payload to GitHubAction. */
+    mapWebhook?: (eventType: string, payload: Record<string, unknown>) => GitHubAction;
+}
+declare class GitHubGovernanceBlockedError extends GovernanceBlockedError {
+    readonly action: GitHubAction;
+    constructor(verdict: GuardVerdict, action: GitHubAction);
+}
+/**
+ * Evaluates GitHub actions against a NeuroVerse world.
+ * Use this when you're making GitHub API calls and want governance
+ * to approve/block them before execution.
+ */
+declare class GitHubGovernor {
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    activePlan?: PlanDefinition;
+    private protectedBranches;
+    private restrictedActors;
+    private mapFn;
+    constructor(world: WorldDefinition, options?: GitHubGovernorOptions);
+    /**
+     * Evaluate a GitHub action against governance rules.
+     * Returns a full result with verdict, event, and the original action.
+     */
+    evaluate(action: GitHubAction): GitHubGovernanceResult;
+    /**
+     * Evaluate and enforce — throws GitHubGovernanceBlockedError on BLOCK/PAUSE.
+     * Use this as a gate before executing GitHub API calls.
+     */
+    enforce(action: GitHubAction): GitHubGovernanceResult;
+    /**
+     * Check if pushing to a branch is allowed.
+     * Convenience method for the most common governance check.
+     */
+    canPush(repository: string, branch: string, actor?: string): GuardVerdict;
+    /**
+     * Check if merging a PR is allowed.
+     */
+    canMerge(repository: string, targetBranch: string, prNumber: number, actor?: string, labels?: string[]): GuardVerdict;
+    /**
+     * Check if creating a release is allowed.
+     */
+    canRelease(repository: string, tag: string, actor?: string, prerelease?: boolean): GuardVerdict;
+    /**
+     * Check if deploying to an environment is allowed.
+     */
+    canDeploy(repository: string, environment: string, ref?: string, actor?: string): GuardVerdict;
+}
+/**
+ * Evaluates incoming GitHub webhook payloads against a NeuroVerse world.
+ * Use this in your webhook endpoint to govern repository events.
+ */
+declare class GitHubWebhookHandler {
+    private governor;
+    private mapWebhookFn;
+    private webhookSecret?;
+    constructor(world: WorldDefinition, options?: WebhookHandlerOptions);
+    /**
+     * Evaluate a webhook payload.
+     *
+     * @param eventType - The X-GitHub-Event header value
+     * @param payload - The parsed webhook body
+     */
+    evaluate(eventType: string, payload: Record<string, unknown>): WebhookGovernanceResult;
+    /**
+     * Evaluate and enforce — throws on BLOCK/PAUSE.
+     */
+    enforce(eventType: string, payload: Record<string, unknown>): WebhookGovernanceResult;
+    /** Access the underlying governor for direct action evaluation. */
+    getGovernor(): GitHubGovernor;
+    /** Get the configured webhook secret (for signature verification in your server). */
+    getWebhookSecret(): string | undefined;
+}
+/**
+ * Guard evaluation result formatted for GitHub Actions output.
+ * Set step outputs and write to $GITHUB_OUTPUT.
+ */
+interface ActionsOutput {
+    /** 'allowed' or 'blocked' or 'paused' — for use in step conditions */
+    governance_status: string;
+    /** The full verdict status */
+    verdict_status: string;
+    /** Reason for block/pause (empty string if allowed) */
+    reason: string;
+    /** Matched rule ID (empty string if none) */
+    rule_id: string;
+    /** Formatted as GITHUB_OUTPUT lines */
+    outputLines: string;
+}
+/**
+ * Format a verdict for GitHub Actions step outputs.
+ * Write the .outputLines to $GITHUB_OUTPUT in your action.
+ *
+ * Usage in a GitHub Action:
+ *   const result = governor.evaluate(action);
+ *   const output = formatForActions(result.verdict);
+ *   fs.appendFileSync(process.env.GITHUB_OUTPUT!, output.outputLines);
+ */
+declare function formatForActions(verdict: GuardVerdict): ActionsOutput;
+/**
+ * Create a PR comment body from a governance verdict.
+ * Useful for posting governance status as a PR comment.
+ */
+declare function formatPRComment(verdict: GuardVerdict, action: GitHubAction): string;
+/**
+ * Create a GitHub Governor from a world path.
+ */
+declare function createGitHubGovernor(worldPath: string, options?: GitHubGovernorOptions): Promise<GitHubGovernor>;
+/**
+ * Create a GitHub Governor from a pre-loaded world.
+ */
+declare function createGitHubGovernorFromWorld(world: WorldDefinition, options?: GitHubGovernorOptions): GitHubGovernor;
+/**
+ * Create a GitHub Webhook Handler from a world path.
+ */
+declare function createGitHubWebhookHandler(worldPath: string, options?: WebhookHandlerOptions): Promise<GitHubWebhookHandler>;
+/**
+ * Create a GitHub Webhook Handler from a pre-loaded world.
+ */
+declare function createGitHubWebhookHandlerFromWorld(world: WorldDefinition, options?: WebhookHandlerOptions): GitHubWebhookHandler;
+
 /**
  * API Handlers — Server-side request handlers for the demo server.
  *
@@ -2416,4 +2155,4 @@ declare function handleCreateCapsule(body: {
     createdAt: string;
 };
 
-export { type AIGuardOptions, type AIGuardVerdict, 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 ClassifiedIntent, type CollectedSource, CompositeAuditLogger, type Condition, type ConditionOperator, type ConditionResult, Consequence, ConsoleAuditLogger, type ConstructType, type ContentFields, DERIVE_EXIT_CODES, type DecisionFlow, type DecisionFlowMetrics, type DeriveExitCode, type DeriveFinding, type DeriveResult, type EventApplication, type ExplainOutput, FileAuditLogger, type FindingCategory, type FindingSeverity, type FlowPath, type FormatVerdictOptions, type GovernanceEngineOptions, GovernanceEvent, type GovernanceHealth, type Governor, type GovernorConfig, GuardEngineOptions, GuardEvent, GuardStatus, GuardVerdict, type ImpactReport, type ImprovementReport, type IntentClassifierOptions, type IntentCluster, type IntentSource, 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, classifyIntentWithAI, createAgentState, createGovernanceEngine, createGovernor, deriveWorld, describeActiveWorld, detectBehavioralPatterns, emitWorldDefinition, evaluateCondition, evaluateGuard, evaluateGuardWithAI, evaluatePlan, eventToAllowlistKey, explainWorld, extractContentFields, 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, verdictToEvent, writeTempWorld };
+export { type AIGuardOptions, type AIGuardVerdict, type AIProvider, type AIProviderConfig, type ActionCategory, type ActionsOutput, type Adaptation, type AddGuardInput, type AddInvariantInput, type AddResult, type AddRuleInput, AdvanceResult, type AgentAction, AgentBehaviorState, type AuditEvent, type AuditLogger, type AuditSummary, type BehavioralPattern, CONFIGURE_AI_EXIT_CODES, type ChatMessage, type ClassifiedIntent, type CollectedSource, CompositeAuditLogger, type Condition, type ConditionOperator, type ConditionResult, Consequence, ConsoleAuditLogger, type ConstructType, type ContentFields, 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 GitHubAction, GitHubGovernanceBlockedError, type GitHubGovernanceResult, GitHubGovernor, type GitHubGovernorOptions, type GitHubWebhookEvent, GitHubWebhookHandler, type GovernanceEngineOptions, type GovernanceHealth, type Governor, type GovernorConfig, GuardEngineOptions, GuardEvent, GuardStatus, GuardVerdict, type ImpactReport, type ImprovementReport, type IntentClassifierOptions, type IntentCluster, type IntentSource, McpGovernanceServer, type McpServerConfig, ModelAdapter, type ModelConfig, type ModelResponse, type NetworkContext, type NormalizationSummary, type OutcomeCluster, PROVIDERS, PlanCheck, PlanDefinition, type PlanParseResult, PlanProgress, PlanVerdict, type PreventionCategory, type ProviderPreset, Reward, type RuleObstacle, type SessionConfig, SessionManager, type SessionState, 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 WebhookGovernanceResult, type WebhookHandlerOptions, type WorldInfo, type WorldState, actionToGuardEvent, adaptationFromVerdict, addGuard, addInvariant, addRule, advancePlan, applyConsequence, applyReward, buildPlanCheck, classifyAdaptation, classifyIntent, classifyIntentWithAI, createAgentState, createGitHubGovernor, createGitHubGovernorFromWorld, createGitHubWebhookHandler, createGitHubWebhookHandlerFromWorld, createGovernanceEngine, createGovernor, deriveWorld, describeActiveWorld, detectBehavioralPatterns, evaluateCondition, evaluateGuardWithAI, evaluatePlan, explainWorld, extractContentFields, extractWorldMarkdown, formatForActions, formatPRComment, formatVerdict, formatVerdictOneLine, generateAdaptationNarrative, generateDecisionFlow, generateImpactReport, generateImpactReportFromFile, getActiveWorldName, getPlanProgress, govern, handleCreateCapsule, handleHealthCheck, handleListPresets, handleReasonRequest, improveWorld, listWorlds, loadWorld, loadWorldFromDirectory, normalizeWorldMarkdown, parseGuardDescription, parsePlanMarkdown, readAuditLog, renderDecisionFlow, renderExplainText, renderImpactReport, renderImproveText, resolveProvider, resolveWorldPath, runInteractiveMode, runPipeMode, setActiveWorld, summarizeAuditEvents, tickAgentStates, validateWorld, verdictToAuditEvent, writeTempWorld };