paracosm 0.7.407 → 0.7.409

package/dist/runtime/world-model/index.js

@@ -0,0 +1,285 @@
+/**
+ * Paracosm WorldModel façade: a one-object surface over the
+ * `compileScenario + runSimulation + runBatch` trio, plus the
+ * snapshot + fork API that operationalizes paracosm's CWSM
+ * (counterfactual world simulation model) positioning.
+ *
+ * Why it exists: paracosm positions itself as a structured world model
+ * for AI agents (see `docs/positioning/world-model-mapping.md`). The
+ * existing APIs (`compileScenario`, `runSimulation`, `runBatch`) are all
+ * first-class and unchanged. `WorldModel` is an additive thin wrapper
+ * that lets consumers write code in the same vocabulary the docs use:
+ *
+ * ```ts
+ * import { WorldModel } from 'paracosm/world-model';
+ *
+ * const wm = await WorldModel.fromJson(worldJson, { provider: 'anthropic' });
+ * const result = await wm.simulate(leader, { maxTurns: 6, seed: 42 });
+ * ```
+ *
+ * Every method dispatches to the underlying API with the `scenario`
+ * slot pinned to this world. Per-call options are passed through
+ * verbatim. Nothing here changes orchestrator semantics, kernel
+ * behavior, or the returned `RunArtifact` shape.
+ *
+ * The façade lives in `runtime/` rather than `engine/` because it
+ * depends on `runSimulation` + `runBatch`; the engine layer does not
+ * import from runtime (one-way dependency).
+ *
+ * @module paracosm/world-model
+ */
+import { runSimulation } from '../orchestrator.js';
+import { runBatch } from '../batch.js';
+import { compileScenario } from '../../engine/compiler/index.js';
+/**
+ * A compiled, runnable world. Wraps a {@link ScenarioPackage} with
+ * convenience methods for simulating single leaders or running a batch.
+ *
+ * Construct via {@link WorldModel.fromJson} (compile from raw JSON) or
+ * {@link WorldModel.fromScenario} (wrap an already-compiled scenario,
+ * e.g. `marsScenario`).
+ *
+ * The underlying scenario is exposed via {@link WorldModel.scenario} as
+ * an escape hatch for callers that want the raw
+ * {@link ScenarioPackage}: direct `runSimulation(leader, [], { scenario: wm.scenario, ... })`
+ * still works and is unchanged.
+ *
+ * @example Single-leader simulation
+ * ```ts
+ * import { WorldModel } from 'paracosm/world-model';
+ * import worldJson from './my-world.json' with { type: 'json' };
+ *
+ * const wm = await WorldModel.fromJson(worldJson, { provider: 'anthropic' });
+ * const artifact = await wm.simulate(leader, { maxTurns: 6, seed: 42 });
+ * ```
+ *
+ * @example Counterfactual branch via fork
+ * ```ts
+ * const wm = await WorldModel.fromJson(worldJson);
+ * const trunk = await wm.simulate(visionary, {
+ *   maxTurns: 6, seed: 42, captureSnapshots: true,
+ * });
+ * const branch = await (await wm.forkFromArtifact(trunk, 3)).simulate(
+ *   pragmatist, { maxTurns: 3, seed: 42 },
+ * );
+ * // branch.metadata.forkedFrom === { parentRunId: trunk.metadata.runId, atTurn: 3 }
+ * ```
+ *
+ * @example Pre-compiled scenario
+ * ```ts
+ * import { marsScenario } from 'paracosm/mars';
+ * import { WorldModel } from 'paracosm/world-model';
+ *
+ * const wm = WorldModel.fromScenario(marsScenario);
+ * const artifact = await wm.simulate(leader, { maxTurns: 8 });
+ * ```
+ */
+export class WorldModel {
+    /**
+     * The underlying compiled scenario. Exposed so callers can drop down
+     * to direct `runSimulation` / `runBatch` calls when they need options
+     * the façade does not surface.
+     */
+    scenario;
+    /**
+     * Snapshot of the kernel at the end of the most recent successful
+     * `simulate()` call. Populated when that simulate() was invoked with
+     * `captureSnapshots: true`. Used by {@link WorldModel.snapshot} to
+     * emit a {@link WorldModelSnapshot} without requiring callers to
+     * plumb the kernel themselves. Undefined otherwise.
+     */
+    _lastKernelSnapshot;
+    /**
+     * Run id of the most recent successful `simulate()` call. Used by
+     * {@link WorldModel.snapshot} to populate
+     * {@link WorldModelSnapshot.parentRunId} so child runs record
+     * `forkedFrom.parentRunId`.
+     */
+    _lastRunId;
+    /**
+     * When this WorldModel was produced by {@link WorldModel.fork} or
+     * {@link WorldModel.forkFromArtifact}, this holds the `forkedFrom`
+     * link that the next {@link WorldModel.simulate} call threads into
+     * the child RunArtifact's `metadata.forkedFrom`. Cleared after
+     * simulate() consumes it.
+     */
+    _pendingForkedFrom;
+    /**
+     * When this WorldModel was produced by {@link WorldModel.fork}, this
+     * holds the kernel snapshot that {@link WorldModel.simulate} must
+     * restore before running. Cleared after simulate() consumes it.
+     */
+    _pendingResumeFrom;
+    constructor(scenario) {
+        this.scenario = scenario;
+    }
+    /**
+     * Compile a raw scenario JSON into a runnable {@link WorldModel}.
+     *
+     * Delegates to {@link compileScenario} under the hood; all
+     * {@link CompileOptions} (cache, provider, model, seed ingestion) are
+     * supported.
+     */
+    static async fromJson(worldJson, options = {}) {
+        const scenario = await compileScenario(worldJson, options);
+        return new WorldModel(scenario);
+    }
+    /**
+     * Wrap an already-compiled {@link ScenarioPackage} (e.g. `marsScenario`,
+     * `lunarScenario`, or any cached result of a prior `compileScenario`
+     * call).
+     *
+     * Pure construction, no I/O.
+     */
+    static fromScenario(scenario) {
+        return new WorldModel(scenario);
+    }
+    /**
+     * Run a single simulation through this world with the given leader.
+     * Delegates to {@link runSimulation} with `scenario` pinned to this
+     * instance.
+     *
+     * `keyPersonnel` is optional for parity with the underlying API; most
+     * callers pass `[]` or omit it. The returned {@link RunArtifact} is
+     * the universal Zod-validated contract exported from `paracosm/schema`.
+     *
+     * When this WorldModel was produced by {@link WorldModel.fork} or
+     * {@link WorldModel.forkFromArtifact}, the pending
+     * `_resumeFrom` + `_forkedFrom` context is threaded into the
+     * underlying runSimulation via the internal `_resumeFrom` /
+     * `_forkedFrom` fields on {@link RunOptions}. Both are cleared after
+     * simulate() consumes them so a second simulate() on the same
+     * WorldModel does not double-apply.
+     */
+    async simulate(leader, options = {}, keyPersonnel = []) {
+        const mergedOpts = {
+            ...options,
+            scenario: this.scenario,
+            _forkedFrom: this._pendingForkedFrom,
+            _resumeFrom: this._pendingResumeFrom,
+        };
+        // Drop the pending context so subsequent simulate calls on the
+        // same WorldModel don't double-apply.
+        this._pendingForkedFrom = undefined;
+        this._pendingResumeFrom = undefined;
+        const artifact = await runSimulation(leader, keyPersonnel, mergedOpts);
+        this._lastRunId = artifact.metadata.runId;
+        // Pull the terminal kernel snapshot from the artifact's embedded
+        // per-turn snapshots (populated when captureSnapshots: true was
+        // on). When captureSnapshots was off, snapshot() is degraded /
+        // unavailable; snapshot() throws with a pointer to the flag.
+        const perTurn = artifact.scenarioExtensions?.kernelSnapshotsPerTurn;
+        if (perTurn && perTurn.length > 0) {
+            this._lastKernelSnapshot = perTurn[perTurn.length - 1];
+        }
+        else {
+            this._lastKernelSnapshot = undefined;
+        }
+        return artifact;
+    }
+    /**
+     * Run N leaders through this world in parallel via {@link runBatch}.
+     * `scenarios` is fixed to `[this.scenario]`; supply `leaders`, `turns`,
+     * `seed`, and any other {@link BatchConfig} fields.
+     *
+     * For N-scenarios-×-M-leaders sweeps that span multiple worlds, call
+     * {@link runBatch} directly with an explicit `scenarios` array.
+     */
+    async batch(options) {
+        return runBatch({
+            ...options,
+            scenarios: [this.scenario],
+        });
+    }
+    /**
+     * Capture a {@link WorldModelSnapshot} of the state at the end of
+     * this WorldModel's most recent `simulate()` call. Requires
+     * `simulate(..., { captureSnapshots: true })` on that prior call;
+     * throws with a clear pointer otherwise.
+     *
+     * The returned snapshot is plain JSON-safe; serialize to disk with
+     * `JSON.stringify` and reload with `JSON.parse` + `fork()`.
+     *
+     * @throws Error when this WorldModel has never run simulate(), or
+     *   when the last simulate() did not set `captureSnapshots: true`.
+     */
+    snapshot() {
+        if (!this._lastKernelSnapshot) {
+            throw new Error('WorldModel.snapshot() requires a prior `simulate(..., { captureSnapshots: true })` ' +
+                'call on this WorldModel. Either enable snapshot capture on your simulation run or ' +
+                'use `forkFromArtifact(artifact, atTurn)` to fork from a stored RunArtifact.');
+        }
+        return {
+            snapshotVersion: 1,
+            kernel: this._lastKernelSnapshot,
+            parentRunId: this._lastRunId,
+        };
+    }
+    /**
+     * Construct a new WorldModel positioned at the snapshot's turn. The
+     * new WorldModel has no prior run of its own; calling `.simulate()`
+     * on it resumes from the snapshot's kernel state, optionally with a
+     * different leader, seed, or custom events.
+     *
+     * `metadata.forkedFrom` on the subsequent `.simulate()` call's
+     * returned RunArtifact is set to
+     * `{ parentRunId: snapshot.parentRunId, atTurn: snapshot.kernel.turn }`.
+     *
+     * The `opts` argument is accepted for API symmetry but not consumed
+     * at fork time; the caller passes `opts.leader` / `opts.seed` /
+     * `opts.customEvents` through to the subsequent `.simulate()` call
+     * directly. A future spec may fold this into a single-call API.
+     *
+     * @throws Error when `snapshot.kernel.scenarioId !== this.scenario.id`.
+     */
+    async fork(snapshot, opts = {}) {
+        if (snapshot.kernel.scenarioId !== this.scenario.id) {
+            throw new Error(`WorldModel.fork: scenario id mismatch. Snapshot was taken against ` +
+                `'${snapshot.kernel.scenarioId}' but this WorldModel wraps ` +
+                `'${this.scenario.id}'. Cross-scenario forks are not supported.`);
+        }
+        const child = new WorldModel(this.scenario);
+        child._pendingResumeFrom = snapshot.kernel;
+        if (snapshot.parentRunId) {
+            child._pendingForkedFrom = {
+                parentRunId: snapshot.parentRunId,
+                atTurn: snapshot.kernel.turn,
+            };
+        }
+        // `opts` (leader / seed / customEvents) are documented at the
+        // interface boundary and intended for the subsequent simulate()
+        // call; fork() itself only needs the snapshot. Silence
+        // unused-parameter warnings explicitly.
+        void opts;
+        return child;
+    }
+    /**
+     * Convenience: pulls the kernel snapshot at `atTurn` from
+     * `artifact.scenarioExtensions.kernelSnapshotsPerTurn` (populated
+     * when the parent run was created with `captureSnapshots: true`)
+     * and calls {@link WorldModel.fork} with it.
+     *
+     * @throws Error when the artifact has no embedded per-turn
+     *   snapshots (parent wasn't run with `captureSnapshots: true`) or
+     *   when `atTurn` is out of range of the available snapshots.
+     */
+    async forkFromArtifact(artifact, atTurn, opts = {}) {
+        const perTurn = artifact.scenarioExtensions?.kernelSnapshotsPerTurn;
+        if (!perTurn || perTurn.length === 0) {
+            throw new Error(`WorldModel.forkFromArtifact: artifact has no embedded kernel snapshots. ` +
+                `Re-run the parent simulation with \`captureSnapshots: true\` on its RunOptions ` +
+                `to enable forking from the stored artifact.`);
+        }
+        const snap = perTurn.find(s => s.turn === atTurn);
+        if (!snap) {
+            throw new Error(`WorldModel.forkFromArtifact: no snapshot at turn ${atTurn}. ` +
+                `Available turns: [${perTurn.map(s => s.turn).join(', ')}].`);
+        }
+        return this.fork({
+            snapshotVersion: 1,
+            kernel: snap,
+            parentRunId: artifact.metadata.runId,
+        }, opts);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/runtime/world-model/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/world-model/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "paracosm",
-  "version": "0.7.407",
-  "description": "AI agent swarm simulation engine with emergent crises, runtime tool forging, HEXACO personality drift, and deterministic kernels. Built on AgentOS.",
+  "version": "0.7.409",
+  "description": "Structured world model for AI agents: reproducible counterfactual simulations with deterministic kernels, HEXACO-personality leaders, LLM-driven events, and runtime tool forging. Covers turn-loop civ sims, batch-trajectory digital twins, and batch-point forecasts via one universal Zod-validated RunArtifact. Built on AgentOS.",
   "type": "module",
   "main": "dist/engine/index.js",
   "types": "dist/engine/index.d.ts",
@@ -37,6 +37,10 @@
     "./schema": {
       "import": "./dist/engine/schema/index.js",
       "types": "./dist/engine/schema/index.d.ts"
+    },
+    "./world-model": {
+      "import": "./dist/runtime/world-model/index.js",
+      "types": "./dist/runtime/world-model/index.d.ts"
     }
   },
   "files": [
@@ -81,9 +85,18 @@
   },
   "keywords": [
     "paracosm",
+    "world-model",
+    "structured-world-model",
+    "llm-world-model",
+    "counterfactual-simulation",
+    "cwsm",
+    "digital-twin",
+    "decision-simulation",
     "simulation",
     "multi-agent",
     "ai-agents",
+    "llm-agents",
+    "agent-based-modeling",
     "emergent-behavior",
     "tool-forging",
     "hexaco",