paracosm 0.9.763 → 0.9.767

package/README.md

@@ -24,9 +24,19 @@
 </p>
 
 <p align="center">
-  <a href="https://paracosm.agentos.sh/demo/e2e-atlas-8-hero.mp4">▶ Watch the 90-second end-to-end demo</a>
+  <img src="assets/blog/readme/paracosm-hero.gif" alt="Paracosm end-to-end: paragraph in, two leaders running, fork-and-replay out" width="720" />
+</p>
+
+<p align="center">
+  <em>Type a what-if. Compile a typed world. Run two LLM commanders against it. Fork any past turn. Watch the trajectories diverge.</em>
+</p>
+
+<p align="center">
+  <a href="https://paracosm.agentos.sh/demo/e2e-atlas-8-hero.mp4">▶ Full 90-second demo</a>
+  &nbsp;·&nbsp;
+  <a href="https://paracosm.agentos.sh/demo/digital-twin-maria-2-hero.mp4">▶ Digital twin</a>
   &nbsp;·&nbsp;
-  <a href="https://paracosm.agentos.sh/demo/digital-twin-maria-2-hero.mp4">▶ Digital twin walkthrough</a>
+  <a href="https://paracosm.agentos.sh/demo/branches.mp4">▶ Branches & forks</a>
 </p>
 
 ---
@@ -391,135 +401,27 @@ Numbers assume 6 turns, 5 departments, 100 agents, up to 3 events per turn. Forg
 
 ## How a turn runs
 
-```
-1. EVENT DIRECTOR     Reads world state, prior decisions, tool intelligence.
-                      Generates an event that targets actual weaknesses.
-
-2. KERNEL ADVANCE     Deterministic time progression: births, deaths, aging,
-                      health decay, resource consumption. Seeded PRNG.
-
-3. DEPARTMENT ANALYSIS  All active departments analyze the event in parallel.
-                        Each head uses personality plus tools. Specialists can
-                        forge new computational tools at runtime in a hardened
-                        node:vm sandbox. An LLM judge approves each forge.
-
-4. COMMANDER DECISION   Reads all department reports. Selects an option.
-                        Personality shapes risk tolerance and priority weighting.
-
-5. OUTCOME              Kernel classifies the outcome (risky success, risky
-                        failure, safe success, safe failure) from option,
-                        probability, and colony state.
-
-6. EFFECTS              Kernel applies deltas (population, morale, food,
-                        power, etc.) per outcome and event category.
-
-7. AGENT REACTIONS      ~100 agents react in parallel using a cheap model.
-                        Each reaction is shaped by the agent's personality,
-                        health, relationships, and accumulated memories.
-
-8. MEMORY               Reactions become persistent memories. Short-term
-                        consolidates into long-term. Stances drift.
-                        Relationships shift on shared experience.
-
-9. PERSONALITY DRIFT    HEXACO traits shift through actor pull, role activation,
-                        and outcome reinforcement. The commander drifts alongside
-                        their agents using peer-reviewed outcome-pull tables.
-```
-
-Every structured LLM call (director events, department reports, commander decisions, reactions, verdict, promotions) runs through Zod schema validation with automatic retry-with-feedback on failure. Schemas live under [`src/runtime/schemas/`](src/runtime/schemas/). Two wrappers (`generateValidatedObject` for one-shot, `sendAndValidate` for session-aware) preserve conversation memory while enforcing validation discipline.
-
----
-
-## Seed enrichment and citations
-
-Real source material grounds the scenario all the way through to department reports.
-
-```bash
-paracosm compile scenarios/lunar.json --seed-text "$(cat ./papers/iss-radiation.md)"
-paracosm compile scenarios/lunar.json --seed-url https://ntrs.nasa.gov/citations/20210018970
-```
-
-The pipeline runs eight steps: extract topics and search queries from the seed, fan out to Firecrawl / Tavily / Serper / Brave in parallel, dedup and rerank with Cohere `rerank-v3.5`, assemble a `KnowledgeBundle`, ingest into an AgentOS `AgentMemory.sqlite()` store, recall per event during runtime, inject `[claim](url)` markdown into department prompts, and surface citations in the dashboard's Reports tab. The seed bundle is cached separately from the hook cache, keyed on the seed signature, so the same URL never re-extracts.
-
----
-
-## Built-in scenarios
+Director event → Kernel advance (deterministic, seeded) → Department analysis in parallel (with optional runtime tool forging in a hardened `node:vm` sandbox; an LLM judge approves each forge) → Commander decision (HEXACO-weighted) → Outcome classification → Kernel effects → Agent reactions → Memory consolidation → Personality drift.
 
-| Scenario      | Description                                                                                                       |
-|---------------|-------------------------------------------------------------------------------------------------------------------|
-| Mars Genesis  | 100 colonists, 6 turns over 48 years. 5 departments, emergent dust storms, water crises, first Marsborn generation. |
-| Lunar Outpost | 50-person crew at the south pole. Mining, life support, comms. Regolith toxicity, 1/6g atrophy.                    |
-
-Both ship as `marsScenario` and `lunarScenario` named exports from the `paracosm` root and serve as references for building custom scenarios.
+Every structured LLM call (director, departments, commander, reactions, verdict) is Zod-validated with retry-with-feedback. Schemas under [`src/runtime/schemas/`](src/runtime/schemas/). Full per-stage breakdown in [docs/architecture.md](docs/architecture.md).
 
 ---
 
-## Programmatic API
-
-| Import                              | Surface                                                                                                  |
-|-------------------------------------|-----------------------------------------------------------------------------------------------------------|
-| `paracosm` (root)                   | `run`, `runMany`, `WorldModel`, `compileScenario`, `marsScenario`, `lunarScenario`, `ACTOR_PRESETS`, `createParacosmClient`, all public types |
-| `paracosm/compiler`                 | `compileScenario`, `ingestSeed`, `ingestFromUrl`, `CompileOptions` (deep authoring path)                  |
-| `paracosm/schema`                   | Zod runtime validators: `RunArtifactSchema`, `StreamEventSchema`, etc.                                    |
-| `paracosm/swarm`                    | Post-run swarm inspection helpers                                                                         |
-| `paracosm/digital-twin`             | `DigitalTwin` (alias of `WorldModel`) and digital-twin schemas                                            |
-| `paracosm/core`                     | Kernel internals: `SimulationKernel`, `SeededRng`, `generateInitialPopulation`, kernel state types        |
-
-`createParacosmClient` pins `provider`, `costPreset`, per-role `models`, and compile-time options once, then hands back methods that inherit those defaults. Per-call overrides still win, merged at the per-role level. Env vars feed the same defaults; explicit args win over env, env wins over library defaults.
-
-```bash
-PARACOSM_PROVIDER=anthropic \
-PARACOSM_COST_PRESET=economy \
-PARACOSM_MODEL_DEPARTMENTS=claude-sonnet-4-6 \
-  node my-runner.js
-```
+## Seed enrichment
 
-`runSimulation` accepts an `AbortSignal` and short-circuits at the next turn boundary on cancel, returning the partial result with `output.aborted === true`. Custom events at fixed turns ride the same options bag (`customEvents: [{ turn: 3, title, description }]`). Provider-key failures throw `ProviderKeyMissingError` once at the top of the run instead of retrying silently per call.
+`paracosm compile <scenario.json> --seed-text "..."` or `--seed-url <url>` extracts topics, searches across Firecrawl + Tavily + Serper + Brave in parallel, reranks with Cohere `rerank-v3.5`, ingests the result into an AgentOS `AgentMemory.sqlite()` store, and threads citations into department prompts. Bundle cached per-seed. Surface citations land in the dashboard's Reports tab.
 
 ---
 
-## HTTP API: `POST /simulate`
-
-For non-SSE consumers (curl, Python integrations, third-party dashboards) a plain request-response endpoint runs a simulation in one call. Gated behind `PARACOSM_ENABLE_SIMULATE_ENDPOINT=true` so the hosted demo's SSE-first path stays the default.
+## Built-in scenarios + APIs
 
-```bash
-export PARACOSM_ENABLE_SIMULATE_ENDPOINT=true
-paracosm dashboard
+`marsScenario` (100 colonists, 6 turns over 48 years; 5 departments) and `lunarScenario` (50-person south-pole crew; regolith + 1/6g) ship from the `paracosm` root as references for custom scenarios.
 
-curl -s -X POST http://localhost:3456/simulate \
-  -H 'Content-Type: application/json' \
-  -H 'X-Anthropic-Key: sk-ant-...' \
-  -d @run.json | jq '.artifact.fingerprint'
-```
+Programmatic surfaces: `paracosm` root (`run`, `runMany`, `WorldModel`, `compileScenario`, `createParacosmClient`), plus `paracosm/{compiler,schema,swarm,digital-twin,core}` for deeper paths. Provider / preset / model defaults can be pinned per client or via `PARACOSM_*` env vars. Full reference + every method signature: [`docs/COOKBOOK.md`](docs/COOKBOOK.md).
 
-The body accepts either a pre-compiled `ScenarioPackage` or a raw scenario draft (auto-compiled server-side with optional `options.seedText` / `options.seedUrl` grounding). The response is `{ artifact, scenario, durationMs }`. Rate limiting and the 5 MiB body cap match `/setup`.
+For non-SSE consumers there's `POST /simulate` (gated on `PARACOSM_ENABLE_SIMULATE_ENDPOINT=true`) and nine read-and-replay routes under `/api/v1/*`. Wire-level details: [`docs/HTTP_API.md`](docs/HTTP_API.md).
 
-The dashboard server also exposes nine read-and-replay routes under `/api/v1/*` (list runs, fetch artifacts, re-execute, import). Wire-level reference: [`docs/HTTP_API.md`](docs/HTTP_API.md).
-
----
-
-## Storage
-
-Run history (Library tab) and replayable session blobs (Load menu) persist through [`@framers/sql-storage-adapter`](https://github.com/framersai/sql-storage-adapter). The same code paths run unchanged against SQLite, Postgres, sql.js, and IndexedDB; switching backends is one env var.
-
-```bash
-paracosm dashboard                                                 # SQLite, ./data/runs.db
-STORAGE_ADAPTER=postgres DATABASE_URL=... paracosm dashboard       # Postgres in production
-STORAGE_ADAPTER=sqljs paracosm dashboard                           # pure-WASM fallback
-```
-
-`runs` and `sessions` schemas bootstrap idempotently on first boot. Legacy v0.7 databases auto-migrate `leader_*` columns to `actor_*` in place via `ALTER TABLE RENAME COLUMN`.
-
-### Admin endpoints
-
-Two destructive admin routes ship with the dashboard, gated by **two** env vars on the server:
-
-| Env var               | Purpose                                                                                              |
-|-----------------------|------------------------------------------------------------------------------------------------------|
-| `ADMIN_WRITE=true`    | Master switch. Off, every `/admin/*` route returns `403`.                                            |
-| `ADMIN_TOKEN=<secret>`| Per-request bearer token in `X-Admin-Token`. With `ADMIN_WRITE=true` and no token, the server returns `503` (fail-closed).|
-
-`POST /admin/sessions/save` snapshots the current event buffer as a replayable session. `POST /admin/data/wipe` clears `runs.db`, `sessions.db`, on-disk artifact JSONs, and the SSE event buffer. The dashboard's Wipe All control prompts for the token on first use and stores it in `localStorage`.
+Storage: SQLite by default, Postgres / sql.js / IndexedDB via `STORAGE_ADAPTER=` env. Run history (Library) and session blobs (Load menu) share the same schema. Admin write routes (`/admin/sessions/save`, `/admin/data/wipe`) require both `ADMIN_WRITE=true` and an `ADMIN_TOKEN` bearer; off by default.
 
 ---
 
@@ -553,12 +455,6 @@ The engine owns the chassis. The scenario owns the domain. The kernel handles st
 
 ---
 
-## Background
-
-Paracosm sits in the structured world model lineage ([Xing 2025](https://arxiv.org/abs/2507.05169), [ACM CSUR 2025](https://dl.acm.org/doi/full/10.1145/3746449)). The LLM-world-model implementation closest to it is [Yang et al, 2026](https://openreview.net/forum?id=XmYCERErcD), which evaluates LLM-based world models through policy verification, action proposal, and policy planning. Full taxonomy mapping in [`docs/positioning/world-model-mapping.md`](docs/positioning/world-model-mapping.md).
-
----
-
 ## Built on AgentOS
 
 > "You are not the kind of dead that can be brought back."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paracosm",
-  "version": "0.9.763",
+  "version": "0.9.767",
   "description": "Agent swarm simulation for structured world modeling with LLMs. Multi-agent worlds with HEXACO personalities, deterministic kernels, runtime tool forging, and reproducible forkable RunArtifacts. Built on AgentOS.",
   "type": "module",
   "main": "dist/engine/index.js",