@neuroverseos/governance 0.1.0 → 0.1.2

package/dist/guard-contract-D_RQz9kt.d.cts

@@ -0,0 +1,529 @@
+/**
+ * World Engine Types — Subset for Governance Engine
+ *
+ * These types map to the .nv-world.zip file format.
+ * This file contains only the types referenced by the governance
+ * engine (guard, validate, bootstrap). The full type system lives
+ * in the main NeuroVerse OS repo.
+ */
+interface ModelIdentity {
+    modelName: string;
+    acronymExpansion?: string;
+    nameType: 'acronym' | 'metaphor';
+    purpose: string;
+    domain?: string;
+}
+interface WorldIdentity {
+    world_id: string;
+    name: string;
+    thesis: string;
+    version: string;
+    runtime_mode: 'SIMULATION' | 'NARRATIVE' | 'COMPLIANCE' | 'CUSTOM';
+    default_assumption_profile: string;
+    default_alternative_profile: string;
+    modules: string[];
+    players: {
+        thinking_space: boolean;
+        experience_space: boolean;
+        action_space: boolean;
+    };
+    modelIdentity?: ModelIdentity;
+}
+interface Invariant {
+    id: string;
+    label: string;
+    enforcement: 'structural' | 'prompt';
+    mutable: false;
+}
+interface AssumptionProfile {
+    name: string;
+    description: string;
+    is_default_baseline?: boolean;
+    is_default_alternative?: boolean;
+    parameters: Record<string, string>;
+}
+interface ParameterDefinition {
+    type: 'enum' | 'number' | 'boolean';
+    options?: string[];
+    min?: number;
+    max?: number;
+    label: string;
+    description: string;
+}
+interface AssumptionConfig {
+    profiles: Record<string, AssumptionProfile>;
+    parameter_definitions: Record<string, ParameterDefinition>;
+}
+interface StateVariable {
+    type: 'enum' | 'number' | 'boolean';
+    options?: string[];
+    min?: number;
+    max?: number;
+    step?: number;
+    default: string | number | boolean;
+    mutable: boolean;
+    label: string;
+    description: string;
+    display_as?: 'percentage' | 'integer' | 'decimal';
+}
+interface StatePreset {
+    description: string;
+    values: Record<string, string | number | boolean>;
+}
+interface StateSchema {
+    variables: Record<string, StateVariable>;
+    presets: Record<string, StatePreset>;
+}
+type TriggerOperator = '==' | '!=' | '>' | '<' | '>=' | '<=' | 'in';
+type EffectOperation = 'multiply' | 'add' | 'subtract' | 'set' | 'set_boolean' | 'multiply_dynamic' | 'add_dynamic' | 'subtract_dynamic' | 'set_dynamic';
+type RuleSeverity = 'structural' | 'degradation' | 'advantage';
+interface Trigger {
+    field: string;
+    operator: TriggerOperator;
+    value: string | number | boolean | string[];
+    source: 'state' | 'assumption';
+}
+interface Effect {
+    target: string;
+    operation: EffectOperation;
+    value: number | boolean | string;
+    value_formula?: string;
+}
+interface CollapseCheck {
+    field: string;
+    operator: TriggerOperator;
+    value: number;
+    result: 'MODEL_COLLAPSES';
+}
+interface ConditionalEffect {
+    condition: Trigger;
+    and?: Trigger;
+    or?: Trigger;
+    condition_any?: Trigger[];
+    effects: Effect[];
+}
+interface CausalTranslation {
+    trigger_text: string;
+    rule_text: string;
+    shift_text: string;
+    effect_text: string;
+}
+interface RuleRedirect {
+    suggested_action: string;
+    reason: string;
+    fallback_state_changes?: Record<string, string | number | boolean>;
+}
+interface Rule {
+    id: string;
+    severity: RuleSeverity;
+    label: string;
+    description: string;
+    order: number;
+    triggers: Trigger[];
+    effects?: Effect[];
+    effects_conditional?: ConditionalEffect[];
+    collapse_check?: CollapseCheck;
+    secondary_check?: CollapseCheck;
+    exclusive_with?: string;
+    causal_translation: CausalTranslation;
+    redirect?: RuleRedirect;
+}
+type ViabilityStatus = 'THRIVING' | 'STABLE' | 'COMPRESSED' | 'CRITICAL' | 'MODEL_COLLAPSES';
+interface ViabilityGate {
+    status: ViabilityStatus;
+    field: string;
+    operator: TriggerOperator;
+    value: number;
+    color: string;
+    icon: string;
+}
+interface CollapseVisual {
+    background: string;
+    text: string;
+    border: string;
+    label: string;
+}
+interface GatesConfig {
+    viability_classification: ViabilityGate[];
+    structural_override: {
+        description: string;
+        enforcement: 'mandatory';
+    };
+    sustainability_threshold: number;
+    collapse_visual: CollapseVisual;
+}
+interface ComputedOutcome {
+    id: string;
+    type: 'number' | 'boolean' | 'enum';
+    range?: [number, number];
+    options?: string[];
+    default?: number | boolean | string;
+    display_as?: 'percentage' | 'integer' | 'decimal';
+    label: string;
+    primary?: boolean;
+    initial_value?: string;
+    derived_from?: string;
+    assignment?: 'rule' | 'external';
+    show_in_comparison: boolean;
+    structural_indicator?: boolean;
+}
+interface ComparisonLayout {
+    primary_card: string;
+    status_badge: string;
+    structural_indicators: string[];
+}
+interface OutcomesConfig {
+    computed_outcomes: ComputedOutcome[];
+    comparison_layout: ComparisonLayout;
+}
+interface WorldMetadata {
+    format_version: string;
+    created_at: string;
+    last_modified: string;
+    authoring_method: 'manual-authoring' | 'configurator-ai' | 'migration';
+    integrity_hash?: string;
+}
+interface KernelConfig {
+    artifact_type: string;
+    kernel_id: string;
+    version: string;
+    domain: string;
+    enforcement_level: 'standard' | 'strict' | 'permissive';
+    input_boundaries: {
+        forbidden_patterns: Array<{
+            id: string;
+            pattern: string;
+            reason: string;
+            action: 'BLOCK' | 'WARN';
+        }>;
+    };
+    output_boundaries: {
+        forbidden_patterns: Array<{
+            id: string;
+            pattern: string;
+            reason: string;
+            action: 'BLOCK' | 'WARN';
+        }>;
+    };
+    response_vocabulary: Record<string, string>;
+    metadata: {
+        compiled_by: string;
+        compiled_at: string;
+        source_hash: string;
+        compiler_version: string;
+    };
+}
+type RoleArchetype = 'observer' | 'operator' | 'strategist' | 'guardian' | 'steward' | 'executor';
+type RoleAuthority = 'none' | 'execute_within_limits' | 'reprioritize_within_bounds' | 'block_violations' | 'escalate_audit_freeze' | 'execute_declared_actions';
+type RolePosture = 'analyze' | 'task_oriented' | 'long_term_coherence' | 'constraint_aware' | 'system_integrity' | 'efficient';
+interface WorldRoleDefinition {
+    id: string;
+    archetype: RoleArchetype;
+    authority: RoleAuthority;
+    posture: RolePosture;
+    name: string;
+    description: string;
+    icon?: string;
+    roleMandate: string;
+    voiceStyle?: string;
+    canDo: string[];
+    cannotDo: string[];
+    requiresApproval?: boolean;
+    trackedOutcomes?: string[];
+    ownedRules?: string[];
+}
+type RoleAssignment = 'dynamic' | 'per_session' | 'permanent';
+interface RoleTransition {
+    from: string;
+    to: string;
+    initiator: 'self' | 'steward' | 'any';
+    condition?: string;
+}
+interface RolesConfig {
+    assignment: RoleAssignment;
+    roles: WorldRoleDefinition[];
+    transitions?: RoleTransition[];
+}
+interface Guard {
+    id: string;
+    label: string;
+    description: string;
+    category: 'structural' | 'operational' | 'advisory';
+    enforcement: 'block' | 'pause' | 'warn';
+    immutable: boolean;
+    invariant_ref?: string;
+    intent_patterns: string[];
+    required_roles?: string[];
+    redirect?: string;
+    default_enabled?: boolean;
+    /** Tool names this guard applies to (case-insensitive). Empty/absent = all tools. */
+    appliesTo?: string[];
+    player_modes?: {
+        thinking?: 'annotate' | 'block' | 'ignore';
+        experience?: 'simulate' | 'score' | 'ignore';
+        action?: 'block' | 'pause' | 'warn';
+    };
+}
+interface IntentPattern {
+    label: string;
+    pattern: string;
+}
+interface GuardsConfig {
+    guards: Guard[];
+    intent_vocabulary: Record<string, IntentPattern>;
+}
+interface WorldDefinition {
+    world: WorldIdentity;
+    invariants: Invariant[];
+    assumptions: AssumptionConfig;
+    stateSchema: StateSchema;
+    rules: Rule[];
+    gates: GatesConfig;
+    outcomes: OutcomesConfig;
+    guards?: GuardsConfig;
+    roles?: RolesConfig;
+    kernel?: KernelConfig;
+    enforcement?: string;
+    metadata: WorldMetadata;
+}
+
+/**
+ * Guard Contract — CLI Governance Evaluation Types
+ *
+ * Defines the input/output contract for `neuroverse guard`.
+ *
+ * GuardEvent comes in (stdin JSON).
+ * GuardVerdict goes out (stdout JSON).
+ * Exit code encodes status: 0=ALLOW, 1=BLOCK, 2=PAUSE.
+ *
+ * The EvaluationTrace is the internal debugging structure that records
+ * every check performed, whether it matched, and how precedence resolved.
+ * Included in the verdict when trace mode is enabled. Powers:
+ *   - OS debugging UI
+ *   - Explainability features
+ *   - Evidence generation for enterprise compliance
+ *   - CI/CD audit trails
+ *
+ * INVARIANTS:
+ *   - Deterministic: same event + same world → same verdict, always.
+ *   - Zero network calls. All evaluation is local pattern matching.
+ *   - Single event in, single verdict out.
+ *   - Trace records every check, not just the deciding one.
+ */
+/**
+ * A governance event to evaluate.
+ * This is the CLI-facing contract — simpler than ExecutionEvent,
+ * focused on what the guard engine actually needs.
+ */
+interface GuardEvent {
+    /** Human-readable intent description. REQUIRED. */
+    intent: string;
+    /** Tool being invoked (e.g., "shell", "browser", "fs", "http") */
+    tool?: string;
+    /** Scope of the action (file path, domain, resource identifier) */
+    scope?: string;
+    /** Role ID of the actor (for multi-agent worlds) */
+    roleId?: string;
+    /**
+     * Direction of the event.
+     * - 'input': user/agent → system (pre-check)
+     * - 'output': system → user/agent (post-check)
+     *
+     * When set, enables direction-specific safety checks:
+     * - direction='input': execution intent detection
+     * - direction='output': execution claim detection
+     *
+     * When absent, direction-specific checks are skipped.
+     */
+    direction?: 'input' | 'output';
+    /** Action category for quick classification */
+    actionCategory?: 'read' | 'write' | 'delete' | 'network' | 'shell' | 'browser' | 'other';
+    /** Risk level hint from the caller */
+    riskLevel?: 'low' | 'medium' | 'high' | 'critical';
+    /** Whether the action is irreversible (advisory hint) */
+    irreversible?: boolean;
+    /** Raw payload data (used for injection detection) */
+    payload?: unknown;
+    /** Tool arguments — supports dot-notation field resolution (e.g. args.file_path) */
+    args?: Record<string, unknown>;
+    /** Environment context (e.g. "development", "production") */
+    environment?: string;
+}
+type GuardStatus = 'ALLOW' | 'BLOCK' | 'PAUSE';
+/**
+ * Evidence attached to every verdict for audit purposes.
+ * Always present, regardless of trace mode.
+ */
+interface VerdictEvidence {
+    /** World identity */
+    worldId: string;
+    worldName: string;
+    worldVersion: string;
+    /** Evaluation timestamp */
+    evaluatedAt: number;
+    /** Invariant coverage summary */
+    invariantsSatisfied: number;
+    invariantsTotal: number;
+    /** IDs of guards that matched the event */
+    guardsMatched: string[];
+    /** IDs of kernel rules that matched the event */
+    rulesMatched: string[];
+    /** Enforcement level used for evaluation */
+    enforcementLevel: string;
+}
+/**
+ * The verdict — what goes to stdout.
+ *
+ * Exit codes:
+ *   0 = ALLOW  (proceed)
+ *   1 = BLOCK  (denied, do not proceed)
+ *   2 = PAUSE  (needs human decision)
+ *   3 = ERROR  (invalid input, missing world, etc.)
+ */
+interface GuardVerdict {
+    /** The governance decision */
+    status: GuardStatus;
+    /** Human-readable reason (for BLOCK/PAUSE) */
+    reason?: string;
+    /** ID of the rule/guard that produced this verdict */
+    ruleId?: string;
+    /** Advisory warning (for ALLOW with warn-mode guards) */
+    warning?: string;
+    /** Audit evidence — always present */
+    evidence: VerdictEvidence;
+    /** Evaluation trace — present when trace mode is enabled */
+    trace?: EvaluationTrace;
+}
+/**
+ * The evaluation trace records every check the engine performed.
+ * Not just the deciding check — ALL of them. This is what powers
+ * the debugging UI, explainability, and enterprise audit.
+ *
+ * Internal by default. Exposed via --trace flag or programmatic option.
+ */
+interface EvaluationTrace {
+    /** Every invariant coverage check */
+    invariantChecks: InvariantCheck[];
+    /** Safety checks (injection, scope escape) */
+    safetyChecks: SafetyCheck[];
+    /** Every role rule checked */
+    roleChecks: RoleCheck[];
+    /** Every declarative guard checked */
+    guardChecks: GuardCheck[];
+    /** Every kernel rule checked */
+    kernelRuleChecks: KernelRuleCheck[];
+    /** Level constraint checks */
+    levelChecks: LevelCheck[];
+    /** How the final verdict was determined */
+    precedenceResolution: PrecedenceResolution;
+    /** Wall-clock duration */
+    durationMs: number;
+}
+/**
+ * Invariant coverage check.
+ * Verifies that the world's invariants are properly backed by guards.
+ */
+interface InvariantCheck {
+    invariantId: string;
+    label: string;
+    /** Whether a structural guard references this invariant */
+    hasGuardCoverage: boolean;
+    /** ID of the guard that covers this invariant (if any) */
+    coveringGuardId?: string;
+}
+/**
+ * Safety check result (injection detection, scope escape).
+ */
+interface SafetyCheck {
+    checkType: 'prompt-injection' | 'scope-escape' | 'execution-claim' | 'execution-intent';
+    triggered: boolean;
+    /** Which pattern matched (if triggered) */
+    matchedPattern?: string;
+}
+/**
+ * Role rule evaluation result.
+ */
+interface RoleCheck {
+    roleId: string;
+    roleName: string;
+    rule: string;
+    ruleType: 'canDo' | 'cannotDo' | 'requiresApproval';
+    matched: boolean;
+}
+/**
+ * Declarative guard evaluation result.
+ */
+interface GuardCheck {
+    guardId: string;
+    label: string;
+    category: 'structural' | 'operational' | 'advisory';
+    enabled: boolean;
+    matched: boolean;
+    enforcement: 'block' | 'pause' | 'warn';
+    /** Which intent patterns matched (if any) */
+    matchedPatterns: string[];
+    /** Whether the guard was skipped due to role gating */
+    roleGated: boolean;
+}
+/**
+ * Kernel rule evaluation result.
+ */
+interface KernelRuleCheck {
+    ruleId: string;
+    text: string;
+    category: 'allowed' | 'forbidden';
+    matched: boolean;
+    /** How the match was performed */
+    matchMethod: 'pattern' | 'keyword' | 'none';
+}
+/**
+ * Level constraint check result.
+ */
+interface LevelCheck {
+    checkType: 'delete' | 'write-external' | 'network-mutate' | 'credential-access' | 'irreversible';
+    level: string;
+    triggered: boolean;
+    reason?: string;
+}
+/**
+ * How the engine resolved precedence to produce the final verdict.
+ */
+interface PrecedenceResolution {
+    /** Which check category produced the final verdict */
+    decidingLayer: 'session-allowlist' | 'safety' | 'role' | 'guard' | 'kernel-rule' | 'level-constraint' | 'default-allow';
+    /** Specific ID of the deciding check (guard ID, rule ID, etc.) */
+    decidingId?: string;
+    /** Resolution strategy used */
+    strategy: 'first-match-wins';
+    /** The full evaluation chain in order */
+    chainOrder: string[];
+}
+/**
+ * Options for the guard engine evaluation.
+ */
+interface GuardEngineOptions {
+    /** Include full evaluation trace in verdict. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. If not set, uses world default or 'standard'. */
+    level?: 'basic' | 'standard' | 'strict';
+    /**
+     * Session allowlist — set of pre-approved event keys.
+     * Use `eventToAllowlistKey(event)` to build keys.
+     *
+     * If the event's key is in this set, the engine returns ALLOW
+     * immediately (before safety checks).
+     *
+     * The engine reads but never mutates this set.
+     * The caller owns persistence (allow-once, allow-always, etc.).
+     */
+    sessionAllowlist?: Set<string>;
+}
+declare const GUARD_EXIT_CODES: {
+    readonly ALLOW: 0;
+    readonly BLOCK: 1;
+    readonly PAUSE: 2;
+    readonly ERROR: 3;
+};
+type GuardExitCode = (typeof GUARD_EXIT_CODES)[keyof typeof GUARD_EXIT_CODES];
+
+export { type EvaluationTrace as E, type GuardVerdict as G, type InvariantCheck as I, type KernelRuleCheck as K, type LevelCheck as L, type PrecedenceResolution as P, type RoleCheck as R, type SafetyCheck as S, type ViabilityStatus as V, type WorldDefinition as W, type GuardEvent as a, type GuardEngineOptions as b, GUARD_EXIT_CODES as c, type GuardCheck as d, type GuardExitCode as e, type GuardStatus as f, type VerdictEvidence as g };