paracosm 0.8.608 → 0.8.649

package/README.md

@@ -5,14 +5,14 @@
 <h1 align="center">PARACOSM</h1>
 
 <p align="center">
-  <em>Counterfactual world simulations for AI agents. From a prompt to a structured world model to forked futures.</em>
+  <em>A structured world model for AI agents. Prompt to runnable world to forked futures.</em>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/paracosm"><img src="https://img.shields.io/npm/v/paracosm?style=flat-square&color=e8b44a&labelColor=14110e" alt="npm" /></a>
   <a href="https://github.com/framersai/paracosm/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-e06530?style=flat-square&labelColor=14110e" alt="License" /></a>
   <a href="https://paracosm.agentos.sh/docs"><img src="https://img.shields.io/badge/docs-API%20Reference-4ca8a8?style=flat-square&labelColor=14110e" alt="Docs" /></a>
-  <a href="https://agentos.sh"><img src="https://img.shields.io/badge/built%20on-AgentOS-e06530?style=flat-square&labelColor=14110e" alt="AgentOS" /></a>
+  <a href="https://agentos.sh/en"><img src="https://img.shields.io/badge/built%20on-AgentOS-e06530?style=flat-square&labelColor=14110e" alt="AgentOS" /></a>
 </p>
 
 <p align="center">
@@ -27,7 +27,7 @@
 
 Paracosm is a structured world model for AI agents. It compiles a JSON scenario draft (or a prompt, or an extracted document) into a runnable world, plays it through a deterministic kernel, and lets agents with HEXACO personality profiles decide turn by turn how the world unfolds. Snapshots persist on disk. Runs replay byte-for-byte. Any past turn can be forked with a different actor, a different seed, or a custom event, and the divergent branch streams alongside the trunk so the contrast is visible in the artifact, not promised in copy.
 
-The product is the contrast. Same compiled world, same crises, same kernel: swap one variable and the trajectory measurably moves. That is what `WorldModel.fork()` is for.
+The product is the contrast. Same compiled world, same crises, same kernel: swap one variable and the trajectory measurably moves.
 
 ---
 
@@ -37,7 +37,7 @@ The product is the contrast. Same compiled world, same crises, same kernel: swap
 >
 > Jorge Luis Borges, *The Garden of Forking Paths*, 1941
 
-A counterfactual world simulation needs three things: a deterministic substrate that can be rewound, an LLM reasoner that can be replayed against the same state, and a contract for what state actually means. Paracosm carries all three. Snapshots are JSON, the kernel round-trips through `JSON.stringify`, and every fork resumes from the captured state without recomputing the prefix.
+A world model that can be forked needs three things: a deterministic substrate that can be rewound, an LLM reasoner that can be replayed against the same state, and a contract for what state actually means. Paracosm carries all three. Snapshots are JSON, the kernel round-trips through `JSON.stringify`, and every fork resumes from the captured state without recomputing the prefix.
 
 ```typescript
 import { WorldModel } from 'paracosm/world-model';
@@ -192,16 +192,7 @@ The authoring contract is JSON because JSON validates, diffs, caches, and snapsh
 }
 ```
 
-Every scenario declares its own vocabulary via `labels.populationNoun` (plural), `labels.settlementNoun` (singular), and `labels.timeUnitNoun`. The dashboard, kernel, and progression hooks pick those up everywhere user-facing copy renders. Without overrides, paracosm falls back to `colonists` / `colony` / `tick`. A handful of working shapes:
-
-| Scenario          | settlementNoun | populationNoun | timeUnitNoun |
-|-------------------|----------------|----------------|--------------|
-| Mars Genesis      | colony         | colonists      | year         |
-| Submarine patrol  | habitat        | crew           | day          |
-| Medieval kingdom  | kingdom        | subjects       | year         |
-| Corporate strategy| company        | employees      | quarter      |
-| Generation ship   | vessel         | passengers     | year         |
-| Benchmark arena   | session        | agents         | tick         |
+Every scenario declares its own vocabulary via `labels.populationNoun` (plural), `labels.settlementNoun` (singular), and `labels.timeUnitNoun`. The dashboard, kernel, and progression hooks pick those up everywhere user-facing copy renders. Without overrides, paracosm falls back to `colonists` / `colony` / `tick`.
 
 Time is unit-agnostic. `setup.defaultTimePerTurn` and `setup.defaultStartTime` are plain numbers; whether they represent years, quarters, hours, or ticks is decided by `timeUnitNoun`. The dashboard turn header reads `Quarter 5`, `Day 22`, or `Year 2043` straight from the label.
 
@@ -287,7 +278,7 @@ For non-TypeScript consumers, `npm run export:json-schema` emits `schema/run-art
 
 ## Digital twins: subjects and interventions
 
-For simulations that revolve around a single subject under a counterfactual intervention, paracosm exposes a `DigitalTwin` subpath plus `SubjectConfig` and `InterventionConfig` as first-class input primitives.
+For simulations that revolve around a single subject under an intervention, paracosm exposes a `DigitalTwin` subpath plus `SubjectConfig` and `InterventionConfig` as first-class input primitives.
 
 ```typescript
 import { DigitalTwin } from 'paracosm/digital-twin';
@@ -479,6 +470,8 @@ curl -s -X POST http://localhost:3456/simulate \
 
 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`.
 
+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
@@ -536,15 +529,9 @@ The engine owns the chassis. The scenario owns the domain. The kernel handles st
 
 ---
 
-## What paracosm is not
-
-- Not a generative visual world model. Sora, Genie 3, and World Labs Marble produce pixels or 3D scenes. Paracosm produces a structured `RunArtifact`: metrics, decisions, specialist notes, citations, forged tools.
-- Not a JEPA-style predictive-representation model. LeCun's AMI Labs trains neural representations from sensor streams. Paracosm composes a kernel with an LLM reasoner; no training pipeline.
-- Not a multi-agent task orchestration framework. LangGraph, AutoGen, CrewAI, and the OpenAI Agents SDK execute real tasks. Paracosm is a simulation; nothing leaves the run.
-- Not a bottom-up swarm intelligence simulator. MiroFish and OASIS simulate millions of emergent agents for aggregate prediction. Paracosm is top-down (one actor decides), runs on the order of 100 agents by design, and outputs a deterministic trajectory plus divergence across actors.
-- Not a generative-agents library. Stanford Generative Agents and Concordia build emergent social simulacra in open-ended sandboxes. Paracosm ships a deterministic turn loop, personality drift, runtime tool forging, and a universal result schema.
+## Background
 
-Paracosm sits in the lineage of structured world models ([Xing 2025](https://arxiv.org/abs/2507.05169), [ACM CSUR 2025](https://dl.acm.org/doi/full/10.1145/3746449)) and counterfactual world simulation ([Kirfel et al, 2025](https://link.springer.com/article/10.1007/s43681-025-00718-4)), and the LLM-world-model anchor closest to the implementation is [Yang et al, 2026](https://openreview.net/forum?id=XmYCERErcD). Full taxonomy mapping in [`docs/positioning/world-model-mapping.md`](docs/positioning/world-model-mapping.md).
+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).
 
 ---
 
@@ -554,7 +541,7 @@ Paracosm sits in the lineage of structured world models ([Xing 2025](https://arx
 >
 > *SOMA*, Frictional Games, 2015
 
-Paracosm uses [AgentOS](https://agentos.sh) for agent orchestration, LLM dispatch, tool forging, and memory. The composition is what makes the runs feel inhabited rather than scripted: department heads remember, specialists invent tools mid-decision, and the LLM judge holds the line on safety before any forge enters the pipeline.
+Paracosm uses [AgentOS](https://agentos.sh/en) for agent orchestration, LLM dispatch, tool forging, and memory. The composition is what makes the runs feel inhabited rather than scripted: department heads remember, specialists invent tools mid-decision, and the LLM judge holds the line on safety before any forge enters the pipeline.
 
 | AgentOS API                  | Used for                                                              |
 |------------------------------|-----------------------------------------------------------------------|
@@ -590,7 +577,7 @@ The open-source engine is the permanent foundation. The hosted product targets o
 | Landing page   | [paracosm.agentos.sh](https://paracosm.agentos.sh)           |
 | API docs       | [paracosm.agentos.sh/docs](https://paracosm.agentos.sh/docs) |
 | npm            | [npmjs.com/package/paracosm](https://www.npmjs.com/package/paracosm) |
-| AgentOS        | [agentos.sh](https://agentos.sh)                              |
+| AgentOS        | [agentos.sh](https://agentos.sh/en)                              |
 | Discord        | [wilds.ai/discord](https://wilds.ai/discord)                  |
 
 ## License

package/dist/cli/server-app.js

@@ -2273,7 +2273,7 @@ export function createMarsServer(options = {}) {
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="22" height="22" style="margin-right:8px;flex-shrink:0;display:block" role="img" aria-label="Paracosm"><style>.ph{animation:ph-p 4s ease-in-out infinite}.pg{animation:ph-g 4s ease-in-out infinite}@keyframes ph-p{0%,100%{opacity:1}50%{opacity:.75}}@keyframes ph-g{0%,100%{opacity:.06}50%{opacity:.15}}@media(prefers-reduced-motion:reduce){.ph,.pg{animation:none!important}}</style><line x1="32" y1="32" x2="37.63" y2="10.98" stroke="#f5f0e4" stroke-width="1.6" opacity=".5"/><line x1="32" y1="32" x2="53.02" y2="26.37" stroke="#f5f0e4" stroke-width="1.6" opacity=".5"/><line x1="32" y1="32" x2="47.39" y2="47.39" stroke="#f5f0e4" stroke-width="1.6" opacity=".5"/><line x1="32" y1="32" x2="26.37" y2="53.02" stroke="#f5f0e4" stroke-width="1.6" opacity=".5"/><line x1="32" y1="32" x2="10.98" y2="37.63" stroke="#f5f0e4" stroke-width="1.6" opacity=".5"/><line x1="32" y1="32" x2="16.61" y2="16.61" stroke="#f5f0e4" stroke-width="1.6" opacity=".5"/><line x1="37.63" y1="10.98" x2="47.39" y2="47.39" stroke="#f5f0e4" stroke-width="1.1" opacity=".18"/><line x1="53.02" y1="26.37" x2="26.37" y2="53.02" stroke="#f5f0e4" stroke-width="1.1" opacity=".18"/><line x1="47.39" y1="47.39" x2="10.98" y2="37.63" stroke="#f5f0e4" stroke-width="1.1" opacity=".18"/><line x1="26.37" y1="53.02" x2="16.61" y2="16.61" stroke="#f5f0e4" stroke-width="1.1" opacity=".18"/><line x1="10.98" y1="37.63" x2="37.63" y2="10.98" stroke="#f5f0e4" stroke-width="1.1" opacity=".18"/><line x1="16.61" y1="16.61" x2="53.02" y2="26.37" stroke="#f5f0e4" stroke-width="1.1" opacity=".18"/><circle class="pg" cx="32" cy="32" r="9.2" fill="#e8b44a"/><circle class="ph" cx="32" cy="32" r="5.12" fill="#e8b44a"/><circle cx="37.63" cy="10.98" r="3.52" fill="#e06530"/><circle cx="53.02" cy="26.37" r="3.52" fill="#e8b44a"/><circle cx="47.39" cy="47.39" r="3.52" fill="#4ca8a8"/><circle cx="26.37" cy="53.02" r="3.52" fill="#e06530"/><circle cx="10.98" cy="37.63" r="3.52" fill="#4ca8a8"/><circle cx="16.61" cy="16.61" r="3.52" fill="#e8b44a"/></svg>
       <span class="pdh-brand">PARA<span style="color:#e8b44a">COSM</span></span>
     </a>
-    <a href="https://agentos.sh" target="_blank" rel="noopener" class="pdh-tag">AGENTOS</a>
+    <a href="https://agentos.sh/en" target="_blank" rel="noopener" class="pdh-tag">AGENTOS</a>
     <span class="pdh-sep">|</span>
     <span class="pdh-current">API Reference v${PARACOSM_VERSION}</span>
   </div>
@@ -2294,7 +2294,7 @@ export function createMarsServer(options = {}) {
   <a href="/docs">API Docs</a>
   <a href="https://github.com/framersai/paracosm" target="_blank" rel="noopener">GitHub</a>
   <a href="https://www.npmjs.com/package/paracosm" target="_blank" rel="noopener">npm</a>
-  <a href="https://agentos.sh" target="_blank" rel="noopener">AgentOS</a>
+  <a href="https://agentos.sh/en" target="_blank" rel="noopener">AgentOS</a>
   <a href="https://wilds.ai/discord" target="_blank" rel="noopener">Discord</a>
 </div>
 <script>
@@ -2338,7 +2338,7 @@ export function createMarsServer(options = {}) {
                         // Inject footer before </body>
                         html = html.replace('</body>', `<div class="paracosm-docs-footer">
   <div class="pdf-links">
-    <a href="https://agentos.sh">agentos.sh</a>
+    <a href="https://agentos.sh/en">agentos.sh</a>
     <a href="https://github.com/framersai/paracosm">GitHub</a>
     <a href="https://www.npmjs.com/package/paracosm">npm</a>
     <a href="https://frame.dev">Frame.dev</a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paracosm",
-  "version": "0.8.608",
+  "version": "0.8.649",
   "description": "Prompt/document/URL-grounded structured world model for AI agents: typed ScenarioPackages, deterministic kernels, HEXACO actors, LLM events, runtime tool forging, and reproducible counterfactual RunArtifacts. Built on AgentOS.",
   "type": "module",
   "main": "dist/engine/index.js",
@@ -82,11 +82,11 @@
     "leader:b": "npx tsx src/cli/run-b.ts"
   },
   "dependencies": {
-    "@framers/agentos": "^0.5.2",
+    "@framers/agentos": "^0.5.12",
     "@framers/sql-storage-adapter": "^0.6.3",
     "better-sqlite3": "^12.9.0",
-    "pdfjs-dist": "^4.10.38",
-    "zod": "^4.3.6"
+    "pdfjs-dist": "^5.7.284",
+    "zod": "^4.4.1"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
@@ -125,5 +125,5 @@
     "type": "git",
     "url": "https://github.com/framersai/paracosm"
   },
-  "homepage": "https://agentos.sh"
+  "homepage": "https://agentos.sh/en"
 }