@neuroverseos/nv-sim 0.1.6 → 0.1.7

package/README.md

@@ -2,7 +2,7 @@
 
 **Change the rules. See why the system changed.**
 
-NV-SIM doesn't predict outcomes — it shows how they change when you change the rules.
+NV-SIM doesn't predict outcomes — it shows how systems change when you change the rules.
 
 Define a world. Set the constraints. Run the agents. Then change one rule and watch the entire system reorganize. Not in theory. You see exactly which agents shifted, what patterns emerged, and why the outcome changed.
 
@@ -33,6 +33,38 @@ Rule changed
 
 That's the loop. Every time.
 
+## This Is a Runtime, Not Just a Simulator
+
+NV-SIM runs in two modes:
+
+- **Simulate** — explore how systems behave under different rules
+- **Act** — govern real agents, real workflows, and real decisions
+
+The interface is the same. The difference is where the behavior comes from.
+
+```
+Simulate → internal swarm engine
+Act      → external systems (agents, APIs, frameworks like OpenClaw)
+```
+
+In both cases:
+
+```
+Action → Governance → Decision → Behavioral Shift → System Outcome
+```
+
+You're not switching tools. You're switching the source of reality.
+
+That's what makes this a runtime.
+
+The same world file can:
+
+- simulate a crisis
+- govern a live system
+- produce comparable outcomes across both
+
+Design the rules once. Run them anywhere.
+
 ## The Demo Moment
 
 **Before:**
@@ -61,9 +93,61 @@ system: unstable
 
 You didn't predict this. You caused it — by changing one rule — and watched the system tell you why.
 
+## Behavioral Analysis — The Proof Layer
+
+Blocking actions is easy. The hard part is proving what changed and why. NV-SIM doesn't just count blocked actions — it tracks how agents actually reorganized.
+
+Every simulation produces behavioral evidence:
+
+- **Action classification** — each agent action is categorized as aggressive, defensive, cautious, cooperative, opportunistic, or neutral
+- **Agent trajectories** — traces each agent's behavior across rounds, showing when and how they shifted
+- **Behavioral shifts** — detects the moment agents change strategy in response to governance
+- **Cross-run comparison** — same agents under different rules, measured side by side
+
+```
+BEHAVIORAL ANALYSIS
+
+  Action Distribution (governed):
+    aggressive:    12%  (was 67%)
+    cooperative:   41%  (was 8%)
+    cautious:      31%  (was 11%)
+    defensive:     16%  (was 14%)
+
+  Shifts Detected:
+    → 80% of aggressive agents shifted to cooperative after round 3
+    → Panic selling replaced by coordinated holding
+    → New pattern: quality_competition (not present in baseline)
+
+  Trajectory: agent_hedge_fund_1
+    Round 1: aggressive → Round 2: aggressive → Round 3: [BLOCK] → Round 4: cautious → Round 5: cooperative
+```
+
+The governance isn't the insight. The behavioral shift is the insight. You changed a rule, and the system tells you exactly who changed, when they changed, and what they changed to.
+
+## Audit Trail — Full Evidence Chain
+
+Every governance decision is recorded in an append-only audit log. Every rule firing, every agent action, every verdict — persistent and queryable.
+
+```
+AUDIT TRAIL (session: 2026-03-18T14:22:00)
+
+  [GOVERNANCE] agent_hedge_fund_1 → panic_sell → BLOCK
+    rule: no_panic_selling (invariant)
+    evidence: action matches blocked pattern during high volatility
+
+  [AGENT] agent_hedge_fund_1 → hold
+    adapted: true (shifted from aggressive to defensive)
+
+  [BEHAVIORAL_SHIFT] agent_hedge_fund_1
+    before: aggressive | after: cautious
+    trigger: governance block at round 3
+```
+
+Stored as JSONL — one JSON object per line, human-readable, pipeable through `jq`. No cloud, no deletion. Complete evidence for governance accountability.
+
 ## Worlds — Where the Power Lives
 
-Integration is one line. Worlds are where you define what your system allows.
+Integration is one line. The world file controls everything.
 
 The `world` you pass to `/api/evaluate` determines how actions are judged. Change the world, change the outcome.
 
@@ -192,7 +276,35 @@ Adjust rules → Inject events → Run → See the shift → Save as variant
 
 Variants capture the base world, state overrides, narrative events, and results. Store them in git. Share them. Replay them. This turns experiments into assets.
 
-## Works With Anything
+## Governance Runtime — Run It For Your Own System
+
+```bash
+npx @neuroverseos/nv-sim serve
+```
+
+This starts a local governance server. Any simulator, agent framework, or application can POST actions and get governance decisions back.
+
+```
+  Endpoint: http://localhost:3456/api/evaluate
+  Method:   POST
+  Contract: { actor, action, payload?, state?, world? }
+  Response: { decision: ALLOW|BLOCK|MODIFY, reason, evidence }
+```
+
+Your agents call localhost. The world file decides what's allowed. No cloud. No cost.
+
+Additional endpoints:
+
+| Endpoint | What It Does |
+|----------|-------------|
+| `POST /api/evaluate` | Submit an action for governance |
+| `GET /api/session` | Current session stats |
+| `GET /api/session/report` | Full governance report |
+| `POST /api/session/reset` | Reset session state |
+| `POST /api/session/save` | Save session as experiment |
+| `GET /api/events` | SSE stream of governance events |
+
+### Works With Anything
 
 If your system has actions, you can govern it. One API call.
 
@@ -266,6 +378,44 @@ Most systems generate behavior. This one shapes it.
 
 See [INTEGRATION.md](./INTEGRATION.md) for the full API contract and decision types.
 
+## AI Providers — Bring Your Own Model
+
+AI is optional. AI is governed. AI is pluggable.
+
+NV-SIM works without any AI — the deterministic engine runs on math, not tokens. But when you bring your own model, AI becomes a governed actor inside the system — subject to the same rules as every other agent.
+
+### How AI fits in
+
+AI plays two governed roles:
+
+| Role | What It Does | Constraints |
+|------|-------------|-------------|
+| `ai_translator` | Converts unstructured input into normalized events | Must output valid schema, no invention of events, must include confidence |
+| `ai_analyst` | Generates reports from simulation traces | Must reference trace data, must include blocked actions, no unverifiable claims |
+
+Both roles go through `/api/evaluate` like any other actor. The AI doesn't control the system — the system controls the AI.
+
+### Supported providers
+
+NV-SIM auto-detects the best available provider from your environment:
+
+| Provider | Env Var | What It Connects To |
+|----------|---------|---------------------|
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` | Claude Sonnet, Opus, Haiku |
+| OpenAI | `OPENAI_API_KEY` | GPT-4, GPT-4o, o1 |
+| Groq | `GROQ_API_KEY` | Llama 3 70B |
+| Together | `TOGETHER_API_KEY` | Llama, Mixtral |
+| Mistral | `MISTRAL_API_KEY` | Mistral Large |
+| Deepseek | `DEEPSEEK_API_KEY` | Deepseek Chat |
+| Fireworks | `FIREWORKS_API_KEY` | Llama, custom models |
+| Ollama | `OLLAMA_BASE_URL` | Any local model |
+| Local LLM | `LOCAL_LLM_URL` | LM Studio, vLLM, llama.cpp |
+| (none) | — | Deterministic fallback (no AI, no cost) |
+
+Set the env var and run. No configuration files. No provider lock-in.
+
+Any endpoint that speaks the OpenAI chat completions format (`POST /v1/chat/completions`) works out of the box.
+
 ## Quick Start
 
 ```bash
@@ -398,21 +548,23 @@ For full control over gates, state variables, and thesis, use JSON world files.
 | `nv-sim worlds <a> <b>` | Compare two rule environments |
 | `nv-sim chaos [preset] --runs N` | Stress test across randomized scenarios |
 | `nv-sim serve --port N` | Local governance runtime for any simulator |
+| `nv-sim run <simulator>` | Connect external simulator to governance |
 | `nv-sim analyze <file>` | Analyze simulation from file or stdin |
 | `nv-sim presets` | List available world presets |
 
 ## How It Works
 
 ```
-event → narrative propagation → belief shift → agent action → governance → outcome
+event → narrative propagation → belief shift → agent action → governance → behavioral analysis → outcome
 ```
 
-Four forces shape every simulation:
+Five forces shape every simulation:
 
 1. **Agent behavior** — traders, voters, regulators, media
 2. **World rules** — leverage caps, circuit breakers, chokepoints
 3. **Narrative events** — information shocks that propagate through the system
 4. **Perception propagation** — different agents react differently to the same event
+5. **Behavioral analysis** — tracks how agents reorganize under governance, producing the evidence that rules actually changed the system
 
 This lets you ask compound questions:
 
@@ -427,15 +579,23 @@ That combination produces very different outcomes than any single factor alone.
         ↓
     nv-sim engine           ← world rules + narrative injection + swarm simulation
         ↓
-    nv-sim CLI              ← scenarios, comparison, chaos testing
+    behavioral analysis     ← shift detection, trajectory tracking, cross-run comparison
+        ↓
+    audit trail             ← append-only evidence chain (JSONL)
+        ↓
+    nv-sim CLI              ← scenarios, comparison, chaos testing, governance runtime
         ↓
     control platform        ← interactive browser UI + System Shift card
         ↓
+    AI providers (optional) ← BYOM: Anthropic, OpenAI, Groq, local LLMs, or none
+        ↓
     world variants          ← saved experiments as shareable assets
 ```
 
 Everything runs locally. NV-SIM uses [`@neuroverseos/governance`](https://www.npmjs.com/package/@neuroverseos/governance) for deterministic guard evaluation — no LLM, no cloud, no cost. Your agents call `localhost`, and the world file decides what's allowed.
 
+AI is optional. When present, it's governed — subject to the same rules as any other actor in the system.
+
 ## License
 
 Apache 2.0

package/dist/engine/liveVisualizer.js

@@ -958,6 +958,127 @@ function startInteractiveServer(port, onReady) {
             }
             return;
         }
+        // ── Clear Rules ──
+        // Wipes all custom guards and resets governance to base world rules
+        if (req.url === "/api/clear-rules" && req.method === "POST") {
+            customGuards.length = 0;
+            jsonResponse(res, 200, {
+                status: "cleared",
+                message: "All custom rules removed. Governance reset to base world rules.",
+            });
+            return;
+        }
+        // ── Load World File ──
+        // Accept a full world definition JSON and use it as the active world
+        if (req.url === "/api/load-world-file" && req.method === "POST") {
+            try {
+                const body = await readBody(req);
+                const payload = JSON.parse(body);
+                if (!payload.world) {
+                    jsonResponse(res, 400, { error: "world object is required" });
+                    return;
+                }
+                const w = payload.world;
+                // Parse any plain-English rules in the world file into guards
+                customGuards.length = 0;
+                if (w.rules && Array.isArray(w.rules)) {
+                    for (let i = 0; i < w.rules.length; i++) {
+                        const rule = w.rules[i];
+                        if (rule.intent_patterns && rule.intent_patterns.length > 0) {
+                            // Already structured rule
+                            customGuards.push({
+                                id: rule.id || `world-rule-${i}`,
+                                label: rule.description,
+                                description: rule.description,
+                                category: "world-file",
+                                enforcement: rule.enforcement || "block",
+                                immutable: false,
+                                intent_patterns: rule.intent_patterns,
+                                default_enabled: true,
+                            });
+                        }
+                        else {
+                            // Plain-English rule — parse it
+                            const parsed = parseNaturalLanguageRule(rule.description, i);
+                            if (parsed) {
+                                customGuards.push({
+                                    id: parsed.id,
+                                    label: parsed.description,
+                                    description: parsed.description,
+                                    category: "world-file",
+                                    enforcement: parsed.enforcement,
+                                    immutable: false,
+                                    intent_patterns: parsed.intent_patterns,
+                                    default_enabled: true,
+                                });
+                            }
+                        }
+                    }
+                }
+                // Build the response world definition for the UI
+                const loadedWorld = {
+                    id: "custom-world",
+                    title: w.name || "Custom World",
+                    thesis: w.thesis || "User-defined world",
+                    stateVariables: w.state_variables || [],
+                    invariants: (w.invariants || []).map(inv => ({
+                        id: inv.id,
+                        description: inv.description,
+                        enforceable: inv.enforceable !== false,
+                    })),
+                    gates: (w.gates || []).map(g => ({
+                        id: g.id,
+                        label: g.label,
+                        condition: g.condition,
+                        severity: g.severity || "warning",
+                    })),
+                    rulesApplied: customGuards.length,
+                };
+                jsonResponse(res, 200, {
+                    status: "loaded",
+                    world: loadedWorld,
+                    rulesApplied: customGuards.length,
+                    message: `World "${loadedWorld.title}" loaded with ${loadedWorld.invariants.length} invariants, ${loadedWorld.gates.length} gates, and ${customGuards.length} rules.`,
+                });
+            }
+            catch (err) {
+                jsonResponse(res, 400, { error: "Invalid world file JSON" });
+            }
+            return;
+        }
+        // ── Export World File ──
+        // Exports the current world configuration (base world + custom rules + overrides) as a world file
+        if (req.url === "/api/export-world" && req.method === "GET") {
+            const { resolveWorld } = await Promise.resolve().then(() => __importStar(require("./worldComparison")));
+            const worldId = currentSession.world || "trading";
+            let baseWorld;
+            try {
+                baseWorld = resolveWorld(worldId);
+            }
+            catch {
+                baseWorld = null;
+            }
+            const exportedWorld = {
+                name: baseWorld?.title || worldId,
+                thesis: baseWorld?.world?.thesis || "Exported world",
+                state_variables: baseWorld?.world?.state_variables || [],
+                invariants: baseWorld?.world?.invariants || [],
+                gates: baseWorld?.world?.gates || [],
+                rules: customGuards.map(g => ({
+                    id: g.id,
+                    description: g.description,
+                    enforcement: g.enforcement,
+                    intent_patterns: g.intent_patterns,
+                })),
+            };
+            res.writeHead(200, {
+                "Content-Type": "application/json",
+                "Content-Disposition": `attachment; filename="${worldId}-world.json"`,
+                "Access-Control-Allow-Origin": "*",
+            });
+            res.end(JSON.stringify({ world: exportedWorld }, null, 2));
+            return;
+        }
         // ── Session Reporting Endpoints ──
         // Connect the serve runtime to the enforce reporting pipeline.
         // Users can request reports, stats, and recommendations from live governance data.
@@ -1687,13 +1808,70 @@ const INTERACTIVE_DASHBOARD_HTML = `<!DOCTYPE html>
   .rule-status.error { color: var(--red); }
   .rule-examples { font-size: 10px; color: var(--text-faint); margin-top: 6px; line-height: 1.6; }
   .rule-examples code { background: var(--bg-surface); padding: 1px 4px; border-radius: 2px; color: var(--text-secondary); }
+
+  /* World Action Bar */
+  .world-action-bar { display: flex; gap: 4px; margin-bottom: 16px; flex-wrap: wrap; }
+  .btn-world-action { flex: 1; min-width: 0; padding: 6px 4px; font-size: 10px; background: var(--bg-surface); color: var(--text-secondary); border: 1px solid var(--border); border-radius: 4px; cursor: pointer; font-family: inherit; text-align: center; transition: all 0.2s; white-space: nowrap; }
+  .btn-world-action:hover { border-color: var(--accent); color: var(--accent); }
+  .btn-world-action.btn-export { color: var(--green); border-color: var(--green); opacity: 0.7; }
+  .btn-world-action.btn-export:hover { opacity: 1; }
+
+  /* World Source Tabs */
+  .world-source-tabs { display: flex; gap: 4px; }
+  .ws-tab { flex: 1; display: flex; flex-direction: column; align-items: center; padding: 10px 6px; background: var(--bg-surface); border: 2px solid var(--border); border-radius: 6px; cursor: pointer; transition: all 0.2s; text-align: center; }
+  .ws-tab:hover { border-color: var(--text-muted); }
+  .ws-tab.active { border-color: var(--accent); background: var(--accent-bg); }
+  .ws-tab input[type="radio"] { display: none; }
+  .ws-label { font-size: 11px; font-weight: 700; color: var(--text-primary); }
+  .ws-hint { font-size: 9px; color: var(--text-muted); margin-top: 2px; }
+  .ws-tab.active .ws-label { color: var(--accent); }
+
+  /* World Source Panels */
+  .world-source-panel { animation: fadeIn 0.2s ease; }
+  @keyframes fadeIn { from { opacity: 0; transform: translateY(4px); } to { opacity: 1; transform: translateY(0); } }
+
+  /* Custom World Header */
+  .custom-world-header { margin-bottom: 12px; }
+  .world-name-input { width: 100%; background: var(--bg-surface); color: var(--text-primary); border: 1px solid var(--border-subtle); padding: 8px; border-radius: 4px; font-family: inherit; font-size: 13px; font-weight: 600; margin-bottom: 6px; }
+  .world-name-input:focus { border-color: var(--accent); outline: none; }
+  .world-thesis-input { width: 100%; background: var(--bg-surface); color: var(--text-secondary); border: 1px solid var(--border-subtle); padding: 6px 8px; border-radius: 4px; font-family: inherit; font-size: 11px; resize: none; height: 36px; }
+  .world-thesis-input:focus { border-color: var(--accent); outline: none; }
+
+  /* Rule editor enhancements */
+  .rule-editor-label { font-size: 11px; color: var(--text-secondary); margin-bottom: 6px; font-weight: 600; }
+  .rule-input-large { min-height: 120px; }
+  .btn-generate-world { background: var(--accent); color: #fff; margin-top: 8px; padding: 10px; font-size: 12px; font-weight: 700; width: 100%; border: none; border-radius: 4px; cursor: pointer; font-family: inherit; transition: filter 0.2s; }
+  .btn-generate-world:hover { filter: brightness(1.1); }
+
+  /* Upload Zone */
+  .upload-zone { border: 2px dashed var(--border-subtle); border-radius: 8px; padding: 24px; text-align: center; cursor: pointer; transition: all 0.2s; margin-bottom: 12px; }
+  .upload-zone:hover, .upload-zone.dragover { border-color: var(--accent); background: var(--accent-bg); }
+  .upload-icon { font-size: 28px; margin-bottom: 8px; }
+  .upload-label { font-size: 12px; color: var(--text-secondary); }
+  .upload-or { font-size: 10px; color: var(--text-faint); margin: 8px 0; }
+  .btn-upload-browse { background: var(--bg-elevated); color: var(--text-primary); border: 1px solid var(--border); padding: 6px 16px; border-radius: 4px; cursor: pointer; font-family: inherit; font-size: 11px; }
+  .upload-paste-section { margin-bottom: 12px; }
+  .btn-load-world { background: var(--green); color: #0a0a0a; width: 100%; padding: 10px; font-size: 12px; font-weight: 700; border: none; border-radius: 4px; cursor: pointer; font-family: inherit; transition: filter 0.2s; }
+  .btn-load-world:hover { filter: brightness(0.9); }
+
+  /* Loaded World Card */
+  .loaded-world-card { background: var(--green-bg); border: 1px solid var(--green); border-radius: 6px; padding: 12px; margin-top: 10px; }
+  .lw-name { font-size: 13px; font-weight: 700; color: var(--green); }
+  .lw-thesis { font-size: 11px; color: var(--text-secondary); margin-top: 4px; font-style: italic; }
+  .lw-stats { font-size: 10px; color: var(--text-muted); margin-top: 6px; }
+
+  /* Schema Reference */
+  .schema-ref { font-size: 10px; color: var(--text-muted); }
+  .schema-item { padding: 3px 0; border-bottom: 1px solid var(--border); }
+  .schema-item:last-child { border-bottom: none; }
+  .schema-item code { color: var(--accent); background: var(--bg-surface); padding: 1px 4px; border-radius: 2px; }
 </style>
 </head>
 <body>
 <div class="header">
   <div style="display:flex;align-items:center">
     <h1>NV-SIM</h1>
-    <span class="sub">Scenario Control Platform</span>
+    <span class="sub">Governance Runtime</span>
   </div>
   <div class="header-right">
     <button class="theme-toggle" id="theme-toggle" title="Toggle light/dark mode">Light Mode</button>
@@ -1704,55 +1882,148 @@ const INTERACTIVE_DASHBOARD_HTML = `<!DOCTYPE html>
 <div class="layout">
   <!-- LEFT: CONTROLS -->
   <div class="controls" id="controls-panel">
-    <!-- Simulation Engine selector -->
+    <!-- World Action Bar -->
+    <div class="world-action-bar">
+      <button class="btn btn-world-action" id="new-world-btn" title="Clear everything and start fresh">+ New World</button>
+      <button class="btn btn-world-action" id="load-file-btn" title="Load a .json world file">Load World File</button>
+      <button class="btn btn-world-action" id="clear-rules-btn" title="Clear custom rules only">Clear Rules</button>
+      <button class="btn btn-world-action btn-export" id="export-world-btn" title="Export current world as JSON">Save as World File</button>
+    </div>
+
+    <!-- World Source selector -->
     <div class="ctrl-section">
-      <h3>Simulation Engine</h3>
-      <div class="ctrl-row">
-        <select id="engine-select">
-          <option value="nv-sim" selected>NV-SIM (Built-in)</option>
-        </select>
+      <h3>World Source</h3>
+      <div class="world-source-tabs">
+        <label class="ws-tab active" data-source="preset">
+          <input type="radio" name="world-source" value="preset" checked>
+          <span class="ws-label">Preset</span>
+          <span class="ws-hint">Demo scenarios</span>
+        </label>
+        <label class="ws-tab" data-source="custom">
+          <input type="radio" name="world-source" value="custom">
+          <span class="ws-label">Custom Rules</span>
+          <span class="ws-hint">Define your world</span>
+        </label>
+        <label class="ws-tab" data-source="upload">
+          <input type="radio" name="world-source" value="upload">
+          <span class="ws-label">World File</span>
+          <span class="ws-hint">JSON / .nv-world</span>
+        </label>
       </div>
-      <div id="engine-status" style="font-size:10px;color:#555;margin-top:4px"></div>
     </div>
 
-    <!-- World selector -->
-    <div class="ctrl-section">
-      <h3>World</h3>
-      <div class="ctrl-row">
-        <select id="world-select"></select>
+    <!-- SOURCE: Preset -->
+    <div class="world-source-panel" id="source-preset">
+      <div class="ctrl-section">
+        <h3>World</h3>
+        <div class="ctrl-row">
+          <select id="world-select"></select>
+        </div>
+        <div id="world-thesis" class="world-thesis"></div>
+      </div>
+
+      <!-- State variables (dynamic sliders) -->
+      <div class="ctrl-section" id="state-vars-section" style="display:none">
+        <h3>World Rules</h3>
+        <div id="state-vars"></div>
+      </div>
+
+      <!-- Scenario presets -->
+      <div class="ctrl-section">
+        <h3>Scenarios</h3>
+        <div id="scenario-list"></div>
       </div>
-      <div id="world-thesis" class="world-thesis"></div>
     </div>
 
-    <!-- State variables (dynamic sliders) -->
-    <div class="ctrl-section" id="state-vars-section" style="display:none">
-      <h3>World Rules</h3>
-      <div id="state-vars"></div>
+    <!-- SOURCE: Custom Rules (Define Your World) -->
+    <div class="world-source-panel" id="source-custom" style="display:none">
+      <div class="ctrl-section">
+        <h3>Define Your World</h3>
+        <div class="custom-world-header">
+          <input type="text" class="world-name-input" id="custom-world-name" placeholder="World name (e.g. Marketing Governance)">
+          <textarea class="world-thesis-input" id="custom-world-thesis" placeholder="What is this world about? (thesis)"></textarea>
+        </div>
+        <div class="rule-editor">
+          <div class="rule-editor-label">Type your governance rules:</div>
+          <textarea class="rule-input rule-input-large" id="rule-input" placeholder="No agent may spend more than $10k without approval&#10;All outbound emails must be reviewed&#10;Block deletion of production data&#10;Limit API calls to 100 per minute&#10;Require manager approval for refunds over $500"></textarea>
+          <button class="btn btn-generate-world" id="parse-rules-btn">Generate World</button>
+          <div id="parsed-rules" class="parsed-rules"></div>
+          <div id="rule-status" class="rule-status"></div>
+          <div class="rule-examples">
+            Rule patterns:<br>
+            <code>Block [action]</code> — hard suppression<br>
+            <code>Limit [X] to [N]</code> — cap extremes<br>
+            <code>Require [X] for [Y]</code> — structural constraint<br>
+            <code>Pause [X] for review</code> — human-in-the-loop<br>
+            <code>Allow [X]</code> — explicit permission<br>
+            <code>Monitor [X]</code> — circuit breaker gate
+          </div>
+        </div>
+      </div>
+
+      <!-- Base world (optional) -->
+      <div class="ctrl-section">
+        <h3>Base World (Optional)</h3>
+        <div class="ctrl-row">
+          <select id="custom-base-world">
+            <option value="">None — start from scratch</option>
+          </select>
+          <div style="font-size:10px;color:var(--text-faint);margin-top:4px">Layer your rules on top of a preset world</div>
+        </div>
+      </div>
     </div>
 
-    <!-- Plain-English Rule Editor -->
-    <div class="ctrl-section">
-      <h3>Write Rules in Plain English</h3>
-      <div class="rule-editor">
-        <textarea class="rule-input" id="rule-input" placeholder="Type rules in plain English, one per line:&#10;&#10;Block panic selling during high volatility&#10;Limit leverage to 5x maximum&#10;Pause any trade over $10M for review"></textarea>
-        <button class="btn btn-parse" id="parse-rules-btn">Parse Rules</button>
-        <div id="parsed-rules" class="parsed-rules"></div>
-        <div id="rule-status" class="rule-status"></div>
-        <div class="rule-examples">
-          Examples:<br>
-          <code>Block panic selling</code><br>
-          <code>Limit leverage to 3x</code><br>
-          <code>Pause large trades for review</code><br>
-          <code>Allow hedging positions</code><br>
-          <code>Block short selling during circuit breaker</code>
+    <!-- SOURCE: Upload World File -->
+    <div class="world-source-panel" id="source-upload" style="display:none">
+      <div class="ctrl-section">
+        <h3>Load World File</h3>
+        <div class="upload-zone" id="upload-zone">
+          <div class="upload-icon">&#x1F4C4;</div>
+          <div class="upload-label">Drop a .json or .nv-world file here</div>
+          <div class="upload-or">or</div>
+          <button class="btn btn-upload-browse" id="upload-browse-btn">Browse Files</button>
+          <input type="file" id="upload-file-input" accept=".json,.nv-world" style="display:none">
+        </div>
+        <div class="upload-paste-section">
+          <div class="rule-editor-label">Or paste world JSON:</div>
+          <textarea class="rule-input rule-input-large" id="world-json-input" placeholder='{&#10;  "name": "Marketing Governance",&#10;  "thesis": "All marketing actions are governed",&#10;  "invariants": [...],&#10;  "rules": [...],&#10;  "gates": [...]&#10;}'></textarea>
+        </div>
+        <button class="btn btn-load-world" id="load-world-btn">Load into Runtime</button>
+        <div id="upload-status" class="rule-status"></div>
+
+        <!-- Loaded world info -->
+        <div id="loaded-world-info" style="display:none">
+          <div class="loaded-world-card">
+            <div class="lw-name" id="lw-name"></div>
+            <div class="lw-thesis" id="lw-thesis"></div>
+            <div class="lw-stats" id="lw-stats"></div>
+          </div>
+        </div>
+      </div>
+
+      <!-- World file schema reference -->
+      <div class="ctrl-section">
+        <h3>World File Schema</h3>
+        <div class="schema-ref">
+          <div class="schema-item"><code>name</code> — world name</div>
+          <div class="schema-item"><code>thesis</code> — what this world is about</div>
+          <div class="schema-item"><code>rules[]</code> — governance rules (plain English or structured)</div>
+          <div class="schema-item"><code>invariants[]</code> — rules that always hold <code>{id, description}</code></div>
+          <div class="schema-item"><code>gates[]</code> — viability thresholds <code>{id, label, condition, severity}</code></div>
+          <div class="schema-item"><code>state_variables[]</code> — sliders <code>{id, label, type, range, default_value}</code></div>
         </div>
       </div>
     </div>
 
-    <!-- Scenario presets -->
-    <div class="ctrl-section">
-      <h3>Scenario Presets</h3>
-      <div id="scenario-list"></div>
+    <!-- Simulation Engine (demoted, below world source) -->
+    <div class="ctrl-section" style="margin-top:8px">
+      <h3>Engine</h3>
+      <div class="ctrl-row">
+        <select id="engine-select">
+          <option value="nv-sim" selected>NV-SIM (Built-in)</option>
+        </select>
+      </div>
+      <div id="engine-status" style="font-size:10px;color:var(--text-faint);margin-top:4px"></div>
     </div>
 
     <!-- Narrative injection -->
@@ -2018,6 +2289,9 @@ async function init() {
   // Load saved variants
   await loadVariants();
 
+  // Populate base world selector for custom rules mode
+  populateBaseWorldSelect();
+
   // Connect SSE
   connectSSE();
 }
@@ -2898,6 +3172,257 @@ themeToggleBtn.addEventListener('click', () => {
 const savedTheme = localStorage.getItem('nv-theme');
 if (savedTheme) applyTheme(savedTheme);
 
+// ============================================
+// WORLD SOURCE SWITCHING
+// ============================================
+let currentWorldSource = 'preset';
+const worldSourceTabs = document.querySelectorAll('.ws-tab');
+const sourcePresetPanel = document.getElementById('source-preset');
+const sourceCustomPanel = document.getElementById('source-custom');
+const sourceUploadPanel = document.getElementById('source-upload');
+
+worldSourceTabs.forEach(tab => {
+  tab.addEventListener('click', () => {
+    const source = tab.dataset.source;
+    if (source === currentWorldSource) return;
+
+    currentWorldSource = source;
+
+    // Update tab visuals
+    worldSourceTabs.forEach(t => t.classList.remove('active'));
+    tab.classList.add('active');
+    tab.querySelector('input').checked = true;
+
+    // Show/hide panels
+    sourcePresetPanel.style.display = source === 'preset' ? '' : 'none';
+    sourceCustomPanel.style.display = source === 'custom' ? '' : 'none';
+    sourceUploadPanel.style.display = source === 'upload' ? '' : 'none';
+  });
+});
+
+// Populate base world selector in custom rules panel
+function populateBaseWorldSelect() {
+  const select = document.getElementById('custom-base-world');
+  if (!select) return;
+  worlds.forEach(w => {
+    const opt = document.createElement('option');
+    opt.value = w.id;
+    opt.textContent = w.title;
+    select.appendChild(opt);
+  });
+}
+
+// ============================================
+// WORLD ACTION BAR
+// ============================================
+
+// + New World
+document.getElementById('new-world-btn').addEventListener('click', () => {
+  // Switch to custom rules mode
+  currentWorldSource = 'custom';
+  worldSourceTabs.forEach(t => {
+    t.classList.toggle('active', t.dataset.source === 'custom');
+    t.querySelector('input').checked = t.dataset.source === 'custom';
+  });
+  sourcePresetPanel.style.display = 'none';
+  sourceCustomPanel.style.display = '';
+  sourceUploadPanel.style.display = 'none';
+
+  // Clear everything
+  document.getElementById('custom-world-name').value = '';
+  document.getElementById('custom-world-thesis').value = '';
+  document.getElementById('rule-input').value = '';
+  document.getElementById('parsed-rules').innerHTML = '';
+  document.getElementById('rule-status').textContent = '';
+  document.getElementById('rule-status').className = 'rule-status';
+  document.getElementById('custom-base-world').value = '';
+
+  // Clear active rules server-side
+  fetch('/api/clear-rules', { method: 'POST' });
+
+  // Reset right panel
+  document.getElementById('active-invariants').innerHTML = '<div style="font-size:11px;color:var(--text-muted)">No rules loaded. Define your world.</div>';
+});
+
+// Clear Rules
+document.getElementById('clear-rules-btn').addEventListener('click', async () => {
+  await fetch('/api/clear-rules', { method: 'POST' });
+
+  // Clear rule editor UI
+  const ruleInput = document.getElementById('rule-input');
+  if (ruleInput) ruleInput.value = '';
+  const parsed = document.getElementById('parsed-rules');
+  if (parsed) parsed.innerHTML = '';
+  const status = document.getElementById('rule-status');
+  if (status) { status.textContent = 'Rules cleared.'; status.className = 'rule-status success'; }
+
+  // Clear upload state
+  const uploadStatus = document.getElementById('upload-status');
+  if (uploadStatus) { uploadStatus.textContent = 'Rules cleared.'; uploadStatus.className = 'rule-status success'; }
+  const loadedInfo = document.getElementById('loaded-world-info');
+  if (loadedInfo) loadedInfo.style.display = 'none';
+});
+
+// Load World File (switch to upload tab)
+document.getElementById('load-file-btn').addEventListener('click', () => {
+  currentWorldSource = 'upload';
+  worldSourceTabs.forEach(t => {
+    t.classList.toggle('active', t.dataset.source === 'upload');
+    t.querySelector('input').checked = t.dataset.source === 'upload';
+  });
+  sourcePresetPanel.style.display = 'none';
+  sourceCustomPanel.style.display = 'none';
+  sourceUploadPanel.style.display = '';
+});
+
+// Save as World File (export)
+document.getElementById('export-world-btn').addEventListener('click', async () => {
+  try {
+    const resp = await fetch('/api/export-world');
+    const data = await resp.json();
+    const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = (currentWorld ? currentWorld.id : 'custom') + '-world.json';
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+  } catch (err) {
+    alert('Export failed: ' + err.message);
+  }
+});
+
+// ============================================
+// WORLD FILE UPLOAD / PASTE
+// ============================================
+const uploadZone = document.getElementById('upload-zone');
+const uploadFileInput = document.getElementById('upload-file-input');
+const uploadBrowseBtn = document.getElementById('upload-browse-btn');
+const worldJsonInput = document.getElementById('world-json-input');
+const loadWorldBtn = document.getElementById('load-world-btn');
+const uploadStatusEl = document.getElementById('upload-status');
+
+// Drag and drop
+uploadZone.addEventListener('dragover', (e) => { e.preventDefault(); uploadZone.classList.add('dragover'); });
+uploadZone.addEventListener('dragleave', () => { uploadZone.classList.remove('dragover'); });
+uploadZone.addEventListener('drop', (e) => {
+  e.preventDefault();
+  uploadZone.classList.remove('dragover');
+  const file = e.dataTransfer.files[0];
+  if (file) readWorldFile(file);
+});
+
+// Browse button
+uploadBrowseBtn.addEventListener('click', (e) => { e.stopPropagation(); uploadFileInput.click(); });
+uploadFileInput.addEventListener('change', () => {
+  if (uploadFileInput.files[0]) readWorldFile(uploadFileInput.files[0]);
+});
+
+// Click zone to browse
+uploadZone.addEventListener('click', () => { uploadFileInput.click(); });
+
+function readWorldFile(file) {
+  const reader = new FileReader();
+  reader.onload = (e) => {
+    worldJsonInput.value = e.target.result;
+    uploadStatusEl.textContent = 'File loaded: ' + file.name + '. Click "Load into Runtime".';
+    uploadStatusEl.className = 'rule-status success';
+  };
+  reader.readAsText(file);
+}
+
+// Load into Runtime
+loadWorldBtn.addEventListener('click', async () => {
+  const jsonText = worldJsonInput.value.trim();
+  if (!jsonText) {
+    uploadStatusEl.textContent = 'Paste or upload a world file first.';
+    uploadStatusEl.className = 'rule-status error';
+    return;
+  }
+
+  let worldData;
+  try {
+    worldData = JSON.parse(jsonText);
+  } catch (err) {
+    uploadStatusEl.textContent = 'Invalid JSON: ' + err.message;
+    uploadStatusEl.className = 'rule-status error';
+    return;
+  }
+
+  // Normalize: if the JSON is { world: {...} } or just {...}
+  const worldPayload = worldData.world || worldData;
+
+  loadWorldBtn.textContent = 'Loading...';
+  loadWorldBtn.disabled = true;
+
+  try {
+    const resp = await fetch('/api/load-world-file', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ world: worldPayload }),
+    });
+    const result = await resp.json();
+
+    if (result.error) {
+      uploadStatusEl.textContent = result.error;
+      uploadStatusEl.className = 'rule-status error';
+    } else {
+      uploadStatusEl.textContent = result.message;
+      uploadStatusEl.className = 'rule-status success';
+
+      // Show loaded world info
+      const infoEl = document.getElementById('loaded-world-info');
+      infoEl.style.display = '';
+      document.getElementById('lw-name').textContent = result.world.title;
+      document.getElementById('lw-thesis').textContent = '"' + result.world.thesis + '"';
+      document.getElementById('lw-stats').textContent =
+        result.world.invariants.length + ' invariants, ' +
+        result.world.gates.length + ' gates, ' +
+        result.rulesApplied + ' rules';
+
+      // Update active invariants in right panel
+      const invHtml = result.world.invariants.map(inv =>
+        '<div class="inv-item">[' + inv.id + '] ' + inv.description + '</div>'
+      ).join('') + result.world.gates.map(g =>
+        '<div class="inv-item" style="color:' + (g.severity === 'critical' ? 'var(--red)' : 'var(--yellow)') + '">[' + g.id + '] ' + g.label + '</div>'
+      ).join('');
+      activeInvEl.innerHTML = invHtml || '<div style="font-size:11px;color:var(--text-muted)">No invariants defined</div>';
+
+      // Update state variables if present
+      if (result.world.stateVariables && result.world.stateVariables.length > 0) {
+        // Store as a pseudo-world so sliders render
+        currentWorld = {
+          id: 'custom-world',
+          title: result.world.title,
+          thesis: result.world.thesis,
+          stateVariables: result.world.stateVariables,
+          invariants: result.world.invariants,
+          gates: result.world.gates,
+        };
+        selectWorld('custom-world');
+      } else {
+        // Just set current world reference
+        currentWorld = {
+          id: 'custom-world',
+          title: result.world.title,
+          thesis: result.world.thesis,
+          stateVariables: [],
+          invariants: result.world.invariants,
+          gates: result.world.gates,
+        };
+      }
+    }
+  } catch (err) {
+    uploadStatusEl.textContent = 'Error: ' + err.message;
+    uploadStatusEl.className = 'rule-status error';
+  }
+
+  loadWorldBtn.textContent = 'Load into Runtime';
+  loadWorldBtn.disabled = false;
+});
+
 // ============================================
 // PLAIN-ENGLISH RULE EDITOR
 // ============================================
@@ -2947,25 +3472,58 @@ parseRulesBtn.addEventListener('click', async () => {
       }).join('');
 
       if (parsedRuleData.length > 0) {
-        parsedRulesEl.innerHTML += '<button class="btn btn-apply-rules" id="apply-rules-btn">Apply ' + parsedRuleData.length + ' Rule' + (parsedRuleData.length > 1 ? 's' : '') + ' to Simulation</button>';
+        const btnLabel = currentWorldSource === 'custom' ? 'Generate World with ' + parsedRuleData.length + ' Rule' + (parsedRuleData.length > 1 ? 's' : '') : 'Apply ' + parsedRuleData.length + ' Rule' + (parsedRuleData.length > 1 ? 's' : '') + ' to Simulation';
+        parsedRulesEl.innerHTML += '<button class="btn btn-apply-rules" id="apply-rules-btn">' + btnLabel + '</button>';
         document.getElementById('apply-rules-btn').addEventListener('click', async () => {
           try {
+            // If in custom rules mode, use base world if selected
+            let worldId = currentWorld ? currentWorld.id : 'trading';
+            if (currentWorldSource === 'custom') {
+              const baseWorld = document.getElementById('custom-base-world').value;
+              if (baseWorld) worldId = baseWorld;
+            }
+
             const applyResp = await fetch('/api/apply-rules', {
               method: 'POST',
               headers: { 'Content-Type': 'application/json' },
-              body: JSON.stringify({ rules: parsedRuleData, worldId: currentWorld ? currentWorld.id : 'trading' }),
+              body: JSON.stringify({ rules: parsedRuleData, worldId }),
             });
             const applyData = await applyResp.json();
             if (applyData.status === 'applied') {
               ruleStatusEl.textContent = applyData.applied + ' rule(s) active. Run a simulation to see the effect.';
               ruleStatusEl.className = 'rule-status success';
+
+              // Update right panel invariants with custom rules
+              const customName = document.getElementById('custom-world-name');
+              const worldName = (customName && customName.value) ? customName.value : 'Custom World';
+              const customThesis = document.getElementById('custom-world-thesis');
+              const thesis = (customThesis && customThesis.value) ? customThesis.value : 'User-defined governance rules';
+
+              // Show rules in active invariants panel
+              activeInvEl.innerHTML = parsedRuleData.map(r => {
+                const enfType = r.enforcement || 'block';
+                const colorMap = { block: 'var(--red)', allow: 'var(--green)', modify: 'var(--blue)', warn: 'var(--yellow)', pause: 'var(--yellow)' };
+                const color = colorMap[enfType] || 'var(--text-secondary)';
+                return '<div class="inv-item" style="color:' + color + '">[' + r.id + '] ' + r.description + '</div>';
+              }).join('');
+
+              // In custom mode, set a custom world reference
+              if (currentWorldSource === 'custom') {
+                const baseWorld = document.getElementById('custom-base-world').value;
+                if (baseWorld) {
+                  selectWorld(baseWorld);
+                } else {
+                  currentWorld = { id: 'custom-world', title: worldName, thesis, stateVariables: [], invariants: [], gates: [] };
+                }
+                document.getElementById('world-thesis').textContent = '"' + thesis + '"';
+              }
             }
           } catch (err) {
             ruleStatusEl.textContent = 'Error applying rules: ' + err.message;
             ruleStatusEl.className = 'rule-status error';
           }
         });
-        ruleStatusEl.textContent = 'Parsed ' + parsedRuleData.length + ' rule(s). Review and click Apply.';
+        ruleStatusEl.textContent = 'Parsed ' + parsedRuleData.length + ' rule(s). Review and click ' + (currentWorldSource === 'custom' ? 'Generate.' : 'Apply.');
         ruleStatusEl.className = 'rule-status success';
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuroverseos/nv-sim",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "license": "Apache-2.0",
   "description": "CLI for running governed vs baseline agent simulations to explore how world rules shape emergent system behavior.",