@its-not-rocket-science/ananke 0.1.69 → 0.5.4

package/dist/src/plugins/types.d.ts

@@ -0,0 +1,31 @@
+export declare const PLUGIN_PERMISSIONS: readonly ["read:worldState", "write:worldState", "read:events", "write:telemetry", "write:artifacts"];
+export type PluginPermission = (typeof PLUGIN_PERMISSIONS)[number];
+export interface PluginManifest {
+    id: string;
+    version: string;
+    hooks: string[];
+    dependencies: Record<string, string>;
+    permissions: PluginPermission[];
+}
+export interface PluginHookContext {
+    worldState: Record<string, unknown>;
+    events?: unknown[];
+    [key: string]: unknown;
+}
+export type PluginHooks = Record<string, (context: PluginHookContext) => void | Promise<void>>;
+export interface PluginRuntimeApi {
+    readonly manifest: PluginManifest;
+    hasPermission(permission: PluginPermission): boolean;
+    readWorldState<T>(value: T): Readonly<T>;
+    mutateWorld<T>(worldState: T, mutator: (draft: T) => void): void;
+    emitTelemetry(metric: string, payload: unknown): void;
+    writeArtifact(path: string, contents: string): void;
+}
+export interface PluginModule {
+    setup(api: PluginRuntimeApi): PluginHooks;
+}
+export interface LoadedPlugin {
+    manifest: PluginManifest;
+    hooks: PluginHooks;
+    runHook(hook: string, context: PluginHookContext): Promise<void>;
+}

package/dist/src/plugins/types.js

@@ -0,0 +1,7 @@
+export const PLUGIN_PERMISSIONS = [
+    "read:worldState",
+    "write:worldState",
+    "read:events",
+    "write:telemetry",
+    "write:artifacts",
+];

package/dist/src/replay.js

@@ -6,6 +6,7 @@
 // Recording: snapshot the initial WorldState, then log commands per tick.
 // Replaying: restore the snapshot, apply logged commands in order.
 import { stepWorld } from "./sim/kernel.js";
+import { normalizeWorldInPlace } from "./sim/normalization.js";
 /**
  * Records commands applied each tick so the simulation can be replayed later.
  *
@@ -44,7 +45,7 @@ export class ReplayRecorder {
  * Pass `ctx.trace` to collect all replayed events for analysis.
  */
 export function replayTo(replay, targetTick, ctx) {
-    const world = structuredClone(replay.initialState);
+    const world = normalizeWorldInPlace(structuredClone(replay.initialState));
     for (const frame of replay.frames) {
         if (frame.tick > targetTick)
             break;
@@ -78,5 +79,7 @@ export function serializeReplay(replay) {
 }
 /** Deserialize a JSON string produced by `serializeReplay` back into a Replay. */
 export function deserializeReplay(json) {
-    return JSON.parse(json, mapAwareReviver);
+    const replay = JSON.parse(json, mapAwareReviver);
+    normalizeWorldInPlace(replay.initialState);
+    return replay;
 }

package/dist/src/scenario.js

@@ -4,6 +4,7 @@
  * Provides typed AnankeScenario interface, structural validation, and
  * a loadScenario() function that converts validated JSON into a WorldState.
  */
+import { normalizeWorldInPlace } from "./sim/normalization.js";
 import { createWorld } from "./world-factory.js";
 // ── Validation ────────────────────────────────────────────────────────────────
 /**
@@ -105,5 +106,5 @@ export function loadScenario(json) {
             spec.y_m = ent.y_m;
         return spec;
     });
-    return createWorld(scenario.seed, specs);
+    return normalizeWorldInPlace(createWorld(scenario.seed, specs));
 }

package/dist/src/serialization/binary.d.ts

@@ -0,0 +1,5 @@
+import type { WorldState } from "../sim/world.js";
+export declare function exportWorldState(world: WorldState): Uint8Array;
+export declare function importWorldState(data: Uint8Array): WorldState;
+export declare function resetSerializationContext(): void;
+export declare function exportLegacyV1WorldState(world: WorldState): Uint8Array;

package/dist/src/serialization/binary.js

@@ -0,0 +1,193 @@
+import { applyDiff, diffWorldState } from "../snapshot.js";
+import { migrateWorld } from "../schema-migration.js";
+const MAGIC = 0x414E4B57; // ANKW
+const FORMAT_VERSION = 2;
+const COMPRESSION_NONE = 0;
+const COMPRESSION_LZ4_WASM = 1;
+let lastExportedWorld;
+let lastImportedWorld;
+export function exportWorldState(world) {
+    const canDiff = lastExportedWorld !== undefined &&
+        lastExportedWorld.seed === world.seed &&
+        world.tick >= lastExportedWorld.tick;
+    const payload = canDiff
+        ? {
+            schemaVersion: FORMAT_VERSION,
+            tick: world.tick,
+            incremental: {
+                baseTick: lastExportedWorld.tick,
+                diff: diffWorldState(lastExportedWorld, world),
+            },
+        }
+        : {
+            schemaVersion: FORMAT_VERSION,
+            tick: world.tick,
+            full: worldToSerializable(world),
+        };
+    const payloadRaw = utf8(JSON.stringify(payload, mapAwareReplacer));
+    const { codec, bytes } = compress(payloadRaw);
+    const checksum = crc32(bytes);
+    const w = new BytesWriter(28 + bytes.length);
+    w.u32(MAGIC);
+    w.u32(FORMAT_VERSION);
+    w.u64(BigInt(Date.now()));
+    w.u32(checksum);
+    w.u8(codec);
+    w.u8(0); // reserved
+    w.u16(0); // reserved
+    w.u32(bytes.length);
+    w.bytes(bytes);
+    lastExportedWorld = structuredClone(world);
+    return w.finish();
+}
+export function importWorldState(data) {
+    const r = new BytesReader(data);
+    const magic = r.u32();
+    if (magic !== MAGIC)
+        throw new Error("serialization: bad magic");
+    const version = r.u32();
+    const _ts = r.u64();
+    const checksum = r.u32();
+    const codec = r.u8();
+    r.u8();
+    r.u16();
+    const payloadLen = r.u32();
+    const payloadBytes = r.bytes(payloadLen);
+    if (crc32(payloadBytes) !== checksum) {
+        throw new Error("serialization: checksum mismatch");
+    }
+    const payloadRaw = decompress(codec, payloadBytes);
+    const payload = JSON.parse(text(payloadRaw), mapAwareReviver);
+    let world;
+    if (version === 1) {
+        const legacy = payload;
+        const candidate = legacy.world;
+        const migrated = typeof candidate["_ananke_version"] === "string" ? migrateWorld(candidate) : candidate;
+        world = serializableToWorld(migrated);
+    }
+    else if (version === FORMAT_VERSION) {
+        const v2 = payload;
+        if (v2.full !== undefined) {
+            world = serializableToWorld(v2.full);
+        }
+        else {
+            if (!v2.incremental || !lastImportedWorld) {
+                throw new Error("serialization: incremental snapshot requires prior base world");
+            }
+            if (lastImportedWorld.tick !== v2.incremental.baseTick) {
+                throw new Error("serialization: incremental base tick mismatch");
+            }
+            world = applyDiff(lastImportedWorld, v2.incremental.diff);
+        }
+    }
+    else {
+        throw new Error(`serialization: unsupported version ${version}`);
+    }
+    lastImportedWorld = structuredClone(world);
+    return world;
+}
+export function resetSerializationContext() {
+    lastExportedWorld = undefined;
+    lastImportedWorld = undefined;
+}
+export function exportLegacyV1WorldState(world) {
+    const payloadRaw = utf8(JSON.stringify({ world: worldToSerializable(world) }, mapAwareReplacer));
+    const checksum = crc32(payloadRaw);
+    const w = new BytesWriter(28 + payloadRaw.length);
+    w.u32(MAGIC);
+    w.u32(1);
+    w.u64(BigInt(Date.now()));
+    w.u32(checksum);
+    w.u8(COMPRESSION_NONE);
+    w.u8(0);
+    w.u16(0);
+    w.u32(payloadRaw.length);
+    w.bytes(payloadRaw);
+    return w.finish();
+}
+function worldToSerializable(world) {
+    return structuredClone(world);
+}
+function serializableToWorld(payload) {
+    const cloned = structuredClone(payload);
+    delete cloned["_ananke_version"];
+    delete cloned["_schema"];
+    return cloned;
+}
+function mapAwareReplacer(_key, value) {
+    if (value instanceof Map)
+        return { __ananke_map__: true, entries: [...value.entries()] };
+    return value;
+}
+function mapAwareReviver(_key, value) {
+    if (value && typeof value === "object" && value.__ananke_map__ === true) {
+        return new Map(value.entries);
+    }
+    return value;
+}
+function compress(bytes) {
+    const maybe = globalThis.__ANANKE_LZ4_WASM__;
+    if (maybe)
+        return { codec: COMPRESSION_LZ4_WASM, bytes: maybe.compress(bytes) };
+    return { codec: COMPRESSION_NONE, bytes };
+}
+function decompress(codec, bytes) {
+    if (codec === COMPRESSION_NONE)
+        return bytes;
+    if (codec === COMPRESSION_LZ4_WASM) {
+        const maybe = globalThis.__ANANKE_LZ4_WASM__;
+        if (!maybe)
+            throw new Error("serialization: lz4 wasm codec unavailable");
+        return maybe.decompress(bytes);
+    }
+    throw new Error(`serialization: unknown compression codec ${codec}`);
+}
+function utf8(str) {
+    return new TextEncoder().encode(str);
+}
+function text(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+function crc32(data) {
+    let c = 0xFFFFFFFF;
+    for (let i = 0; i < data.length; i++) {
+        c ^= data[i];
+        for (let b = 0; b < 8; b++) {
+            c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1);
+        }
+    }
+    return (c ^ 0xFFFFFFFF) >>> 0;
+}
+class BytesWriter {
+    out;
+    cursor = 0;
+    view;
+    constructor(size) {
+        this.out = new Uint8Array(size);
+        this.view = new DataView(this.out.buffer);
+    }
+    u8(v) { this.view.setUint8(this.cursor, v); this.cursor += 1; }
+    u16(v) { this.view.setUint16(this.cursor, v, true); this.cursor += 2; }
+    u32(v) { this.view.setUint32(this.cursor, v >>> 0, true); this.cursor += 4; }
+    u64(v) { this.view.setBigUint64(this.cursor, v, true); this.cursor += 8; }
+    bytes(v) { this.out.set(v, this.cursor); this.cursor += v.length; }
+    finish() { return this.out.slice(0, this.cursor); }
+}
+class BytesReader {
+    data;
+    cursor = 0;
+    view;
+    constructor(data) {
+        this.data = data;
+        this.view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    }
+    u8() { const v = this.view.getUint8(this.cursor); this.cursor += 1; return v; }
+    u16() { const v = this.view.getUint16(this.cursor, true); this.cursor += 2; return v; }
+    u32() { const v = this.view.getUint32(this.cursor, true); this.cursor += 4; return v; }
+    u64() { const v = this.view.getBigUint64(this.cursor, true); this.cursor += 8; return v; }
+    bytes(n) {
+        const start = this.cursor;
+        this.cursor += n;
+        return this.data.slice(start, start + n);
+    }
+}

package/dist/src/session.d.ts

@@ -0,0 +1,115 @@
+import { type EntitySpec } from "./world-factory.js";
+import type { Command } from "./sim/commands.js";
+import type { KernelContext } from "./sim/context.js";
+import type { WorldState } from "./sim/world.js";
+import { getEvolutionSummary, type EvolutionRequest, type EvolutionRuleset, type EvolutionSession } from "./world-evolution.js";
+import { type WorldEvolutionRulesetId, type WorldEvolutionSnapshot } from "./world-evolution-backend/index.js";
+import { type AnankePackManifest, type LoadPackResult, type PackValidationError } from "./content-pack.js";
+import { type ReplayFrame } from "./replay.js";
+/** Tier 2 / experimental host session mode. */
+export type SessionMode = "tactical" | "world_evolution";
+export interface TacticalSessionConfig {
+    mode: "tactical";
+    /** Explicit tactical world snapshot. */
+    worldState?: WorldState;
+    /** Scenario JSON loaded via validateScenario + loadScenario. */
+    scenarioJson?: unknown;
+    /** Optional convenience bootstrap via createWorld(seed, entities). */
+    worldSeed?: number;
+    entities?: EntitySpec[];
+    /** Enable in-session replay recording. */
+    enableReplay?: boolean;
+    id?: string;
+}
+export interface WorldEvolutionSessionConfig {
+    mode: "world_evolution";
+    canonicalSnapshot: WorldEvolutionSnapshot;
+    rulesetId?: WorldEvolutionRulesetId;
+    ruleset?: EvolutionRuleset;
+    checkpointInterval?: number;
+    includeDeltas?: boolean;
+    label?: string;
+    id?: string;
+}
+export type SessionConfig = TacticalSessionConfig | WorldEvolutionSessionConfig;
+interface TacticalSessionState {
+    world: WorldState;
+    replay?: MutableReplay;
+}
+interface WorldEvolutionSessionState {
+    evolution: EvolutionSession;
+}
+interface MutableReplay {
+    initialState: WorldState;
+    frames: ReplayFrame[];
+}
+export type SessionHandle = {
+    mode: "tactical";
+    id: string;
+    createdAt: number;
+    state: TacticalSessionState;
+} | {
+    mode: "world_evolution";
+    id: string;
+    createdAt: number;
+    state: WorldEvolutionSessionState;
+};
+export interface RunSessionRequest {
+    /**
+     * Number of simulation steps to run. Defaults to 1 when omitted.
+     */
+    steps?: number;
+    /** Tactical command frames, one frame per requested step. */
+    tacticalCommandFrames?: ReadonlyArray<ReadonlyArray<readonly [entityId: number, cmds: ReadonlyArray<Command>]>>;
+    /** Alias for tacticalCommandFrames. Prefer this for new host integrations. */
+    commandFrames?: ReadonlyArray<ReadonlyArray<readonly [entityId: number, cmds: ReadonlyArray<Command>]>>;
+    tacticalContext?: KernelContext;
+    /** Alias for tacticalContext. Prefer this for new host integrations. */
+    context?: KernelContext;
+    evolution?: Omit<EvolutionRequest, "steps">;
+    /** Alias for evolution. Prefer this for new host integrations. */
+    worldEvolution?: Omit<EvolutionRequest, "steps">;
+}
+export interface RunSessionResult {
+    mode: SessionMode;
+    executedSteps: number;
+    summary: SessionSummary;
+}
+export type SessionSummary = {
+    mode: "tactical";
+    id: string;
+    tick: number;
+    entityCount: number;
+    hasReplay: boolean;
+} | {
+    mode: "world_evolution";
+    id: string;
+    summary: ReturnType<typeof getEvolutionSummary>;
+};
+export interface ForkSessionRequest {
+    id?: string;
+    label?: string;
+    rulesetId?: WorldEvolutionRulesetId;
+    ruleset?: EvolutionRuleset;
+    seed?: number;
+}
+export interface LoadSessionPackResult {
+    pack: LoadPackResult;
+    validationErrors: PackValidationError[];
+    scenarioJson?: unknown;
+    worldState?: WorldState;
+}
+export interface LoadSessionPackRequest {
+    manifest: AnankePackManifest;
+    scenarioId?: string;
+    instantiateScenario?: boolean;
+}
+export declare function createSession(config: SessionConfig): SessionHandle;
+export declare function runSession(session: SessionHandle, request: RunSessionRequest): RunSessionResult;
+export declare function stepSession(session: SessionHandle, request?: Omit<RunSessionRequest, "steps">): RunSessionResult;
+export declare function getSessionSummary(session: SessionHandle): SessionSummary;
+export declare function forkSession(session: SessionHandle, request?: ForkSessionRequest): SessionHandle;
+export declare function loadSessionPack(input: LoadSessionPackRequest | AnankePackManifest): LoadSessionPackResult;
+export declare function serializeSession(session: SessionHandle): string;
+export declare function deserializeSession(json: string): SessionHandle;
+export {};

package/dist/src/session.js

@@ -0,0 +1,228 @@
+import { ANANKE_ENGINE_VERSION } from "./version.js";
+import { createWorld } from "./world-factory.js";
+import { loadScenario, validateScenario } from "./scenario.js";
+import { stepWorld } from "./sim/kernel.js";
+import { q } from "./units.js";
+import { createEvolutionBranch, createEvolutionSession, deserializeEvolutionCheckpoint, forkEvolutionBranch, getEvolutionSummary, resumeEvolutionSessionFromCheckpoint, runEvolution, serializeEvolutionIntermediateState, stepEvolution, } from "./world-evolution.js";
+import { getPackScenario, instantiatePackScenario, loadPack, validatePack, } from "./content-pack.js";
+import { deserializeReplay, serializeReplay } from "./replay.js";
+const SESSION_SCHEMA_VERSION = "ananke.session.v1";
+export function createSession(config) {
+    if (config.mode === "tactical") {
+        const world = createTacticalWorld(config);
+        const replay = config.enableReplay
+            ? { initialState: structuredClone(world), frames: [] }
+            : undefined;
+        return {
+            mode: "tactical",
+            id: config.id ?? `session-tactical-${world.seed}-${world.tick}`,
+            createdAt: world.tick,
+            state: replay ? { world, replay } : { world },
+        };
+    }
+    const evolution = createEvolutionSession({
+        seed: config.canonicalSnapshot.worldSeed,
+        canonicalSnapshot: config.canonicalSnapshot,
+        ...(config.ruleset != null ? { ruleset: config.ruleset } : {}),
+        ...(config.rulesetId != null ? { rulesetId: config.rulesetId } : {}),
+        ...(config.checkpointInterval != null ? { checkpointInterval: config.checkpointInterval } : {}),
+        ...(config.includeDeltas != null ? { includeDeltas: config.includeDeltas } : {}),
+        ...(config.label != null ? { label: config.label } : {}),
+    });
+    return {
+        mode: "world_evolution",
+        id: config.id ?? evolution.sessionId,
+        createdAt: config.canonicalSnapshot.tick,
+        state: { evolution },
+    };
+}
+export function runSession(session, request) {
+    const requestedSteps = Math.max(0, Math.floor(request.steps ?? 1));
+    const commandFrames = request.commandFrames ?? request.tacticalCommandFrames;
+    const tacticalContext = request.context ?? request.tacticalContext;
+    const evolutionRequest = request.worldEvolution ?? request.evolution;
+    if (session.mode === "tactical") {
+        for (let i = 0; i < requestedSteps; i += 1) {
+            const frame = commandFrames?.[i] ?? [];
+            if (session.state.replay) {
+                session.state.replay.frames.push({
+                    tick: session.state.world.tick,
+                    commands: frame.map(([entityId, cmds]) => [entityId, [...cmds]]),
+                });
+            }
+            stepWorld(session.state.world, toCommandMap(frame), tacticalContext ?? { tractionCoeff: q(0.85) });
+        }
+        return { mode: "tactical", executedSteps: requestedSteps, summary: getSessionSummary(session) };
+    }
+    runEvolution(session.state.evolution, {
+        steps: requestedSteps,
+        ...(evolutionRequest?.checkpointInterval != null ? { checkpointInterval: evolutionRequest.checkpointInterval } : {}),
+        ...(evolutionRequest?.includeDeltas != null ? { includeDeltas: evolutionRequest.includeDeltas } : {}),
+        ...(evolutionRequest?.includeCheckpointDiffs != null ? { includeCheckpointDiffs: evolutionRequest.includeCheckpointDiffs } : {}),
+    });
+    return { mode: "world_evolution", executedSteps: requestedSteps, summary: getSessionSummary(session) };
+}
+export function stepSession(session, request = {}) {
+    const evolutionRequest = request.worldEvolution ?? request.evolution;
+    if (session.mode === "world_evolution") {
+        stepEvolution(session.state.evolution, evolutionRequest ?? {});
+        return { mode: "world_evolution", executedSteps: 1, summary: getSessionSummary(session) };
+    }
+    return runSession(session, { ...request, steps: 1 });
+}
+export function getSessionSummary(session) {
+    if (session.mode === "tactical") {
+        return {
+            mode: "tactical",
+            id: session.id,
+            tick: session.state.world.tick,
+            entityCount: session.state.world.entities.length,
+            hasReplay: session.state.replay != null,
+        };
+    }
+    return { mode: "world_evolution", id: session.id, summary: getEvolutionSummary(session.state.evolution) };
+}
+export function forkSession(session, request = {}) {
+    if (session.mode === "tactical") {
+        return {
+            mode: "tactical",
+            id: request.id ?? `${session.id}-fork-${session.state.world.tick}`,
+            createdAt: session.state.world.tick,
+            state: session.state.replay
+                ? {
+                    world: structuredClone(session.state.world),
+                    replay: structuredClone(session.state.replay),
+                }
+                : {
+                    world: structuredClone(session.state.world),
+                },
+        };
+    }
+    const baseBranch = createEvolutionBranch({
+        baseSnapshot: session.state.evolution.state.currentSnapshot,
+        baseStep: session.state.evolution.state.totalSteps,
+        metadata: {
+            name: `${session.id}-base`,
+            seed: session.state.evolution.seed,
+            rulesetProfile: session.state.evolution.ruleset,
+            createdAtStep: session.state.evolution.state.totalSteps,
+        },
+    });
+    const branch = forkEvolutionBranch(baseBranch, {
+        metadata: {
+            name: request.label ?? `${session.id}-fork`,
+            ...(request.seed != null ? { seed: request.seed } : {}),
+            ...(request.ruleset != null ? { rulesetProfile: request.ruleset } : {}),
+            ...(request.rulesetId != null ? { rulesetId: request.rulesetId } : {}),
+        },
+    });
+    const evolution = createEvolutionSession({
+        seed: branch.branchMetadata.seed,
+        canonicalSnapshot: branch.derivedState.currentSnapshot,
+        ruleset: branch.branchMetadata.rulesetProfile,
+        ...(request.label != null ? { label: request.label } : {}),
+    });
+    return {
+        mode: "world_evolution",
+        id: request.id ?? `${session.id}-fork-${session.state.evolution.state.totalSteps}`,
+        createdAt: evolution.state.currentSnapshot.tick,
+        state: { evolution },
+    };
+}
+export function loadSessionPack(input) {
+    const request = isPackManifest(input) ? { manifest: input } : input;
+    const validationErrors = validatePack(request.manifest);
+    const pack = loadPack(request.manifest);
+    const out = { pack, validationErrors };
+    if (request.scenarioId) {
+        out.scenarioJson = getPackScenario(pack.packId, request.scenarioId);
+        if (request.instantiateScenario && out.scenarioJson != null) {
+            out.worldState = instantiatePackScenario(pack.packId, request.scenarioId);
+        }
+    }
+    return out;
+}
+export function serializeSession(session) {
+    const envelope = session.mode === "tactical"
+        ? {
+            schemaVersion: SESSION_SCHEMA_VERSION,
+            engineVersion: ANANKE_ENGINE_VERSION,
+            mode: "tactical",
+            payload: {
+                id: session.id,
+                createdAt: session.createdAt,
+                worldReplayJson: serializeReplay({ initialState: session.state.world, frames: [] }),
+                ...(session.state.replay ? { replayJson: serializeReplay(session.state.replay) } : {}),
+            },
+        }
+        : {
+            schemaVersion: SESSION_SCHEMA_VERSION,
+            engineVersion: ANANKE_ENGINE_VERSION,
+            mode: "world_evolution",
+            payload: {
+                id: session.id,
+                createdAt: session.createdAt,
+                checkpointJson: serializeEvolutionIntermediateState(session.state.evolution),
+            },
+        };
+    return JSON.stringify(envelope);
+}
+export function deserializeSession(json) {
+    const envelope = JSON.parse(json);
+    if (envelope.schemaVersion !== SESSION_SCHEMA_VERSION) {
+        throw new Error(`deserializeSession: unsupported schemaVersion '${String(envelope.schemaVersion)}'`);
+    }
+    if (envelope.mode === "tactical") {
+        const payload = envelope.payload;
+        const worldReplay = deserializeReplay(payload.worldReplayJson);
+        const replay = payload.replayJson ? deserializeReplay(payload.replayJson) : undefined;
+        return {
+            mode: "tactical",
+            id: payload.id,
+            createdAt: payload.createdAt,
+            state: replay
+                ? {
+                    world: worldReplay.initialState,
+                    replay: {
+                        initialState: structuredClone(replay.initialState),
+                        frames: replay.frames.map((frame) => ({
+                            tick: frame.tick,
+                            commands: frame.commands.map(([entityId, cmds]) => [entityId, [...cmds]]),
+                        })),
+                    },
+                }
+                : {
+                    world: worldReplay.initialState,
+                },
+        };
+    }
+    const payload = envelope.payload;
+    const evolution = resumeEvolutionSessionFromCheckpoint(deserializeEvolutionCheckpoint(payload.checkpointJson));
+    return {
+        mode: "world_evolution",
+        id: payload.id,
+        createdAt: payload.createdAt,
+        state: { evolution },
+    };
+}
+function createTacticalWorld(config) {
+    if (config.worldState != null)
+        return structuredClone(config.worldState);
+    if (config.scenarioJson != null) {
+        const validation = validateScenario(config.scenarioJson);
+        if (validation.length > 0) {
+            throw new Error(`createSession(tactical): invalid scenario JSON:\n${validation.map((e) => `- ${e}`).join("\n")}`);
+        }
+        return loadScenario(config.scenarioJson);
+    }
+    if (config.worldSeed != null && config.entities != null) {
+        return createWorld(config.worldSeed, config.entities);
+    }
+    throw new Error("createSession(tactical): provide worldState, scenarioJson, or worldSeed+entities");
+}
+function toCommandMap(frame) {
+    return new Map(frame.map(([entityId, cmds]) => [entityId, [...cmds]]));
+}
+function isPackManifest(input) {
+    return !("manifest" in input);
+}

package/dist/src/sim/ai/decide.js

@@ -114,7 +114,7 @@ export function decideCommandsForEntity(world, index, spatial, self, policy, env
     // Self-defence override: if self has taken damage (shock > 0 or fluid loss > 0),
     // faction check is bypassed (attacker is fought back regardless of standing).
     if (target && self.faction) {
-        const factionRegistry = (world).__factionRegistry;
+        const factionRegistry = world.runtimeState?.factionRegistry;
         if (factionRegistry) {
             const standing = effectiveStanding(factionRegistry, self, target);
             const selfDefence = self.injury.shock > 0 || self.injury.fluidLoss > 0;

package/dist/src/sim/ai/personality.js

@@ -88,7 +88,7 @@ export function derivePersonalityFromCognition(attrs) {
 export function computeEffectiveLoyalty(self, world) {
     const personality = self.personality;
     const baseLoyalty = personality?.loyalty ?? q(0.50);
-    const partyRegistry = world.__partyRegistry;
+    const partyRegistry = world.runtimeState?.partyRegistry;
     if (!partyRegistry)
         return baseLoyalty;
     const partyId = self.party;
@@ -100,7 +100,7 @@ export function computeEffectiveLoyalty(self, world) {
     const leaderId = party.leaderId;
     if (leaderId === self.id)
         return baseLoyalty; // leader is self
-    const relationshipGraph = world.__relationshipGraph;
+    const relationshipGraph = world.runtimeState?.relationshipGraph;
     if (!relationshipGraph)
         return baseLoyalty;
     const companionLoyalty = computeCompanionLoyalty(self, leaderId, relationshipGraph);