koota-kit 0.1.1

package/dist/cjs/rng.cjs

@@ -0,0 +1,168 @@
+"use strict";
+// Dual-layer deterministic PRNG (seedrandom-backed).
+//
+// `gen` — worldgen / layouts / spawn locations / map composition / one-time
+//   seeded decisions. Replays a world reliably from the gen seed alone, even
+//   when play diverges. Snapshot it once at world creation and you can
+//   re-derive the same world forever.
+//
+// `events` — per-tick runtime decisions (weather rolls, event triggers, mood
+//   drift, combat dice). Diverges based on play history. Snapshot/restore
+//   independently so a worldgen replay doesn't carry play state with it.
+//
+// Why two streams: a single stream couples worldgen to play, so seeding a
+// "same map, fresh playthrough" scenario requires you to either re-derive
+// worldgen mid-restore (fragile) or snapshot the stream at the exact tick
+// worldgen finished (brittle to system ordering). Two streams: snapshot gen
+// once, never touch it again; snapshot events on demand. Each layer's
+// determinism contract is independent.
+//
+// Forbidden in sim code: `Math.random()`. Use `nextFloat(rng.gen)` or
+// `nextFloat(rng.events)` depending on the layer.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRng = createRng;
+exports.nextU32 = nextU32;
+exports.nextFloat = nextFloat;
+exports.nextInt = nextInt;
+exports.chance = chance;
+exports.snapshotStream = snapshotStream;
+exports.snapshotLayers = snapshotLayers;
+exports.restoreStream = restoreStream;
+exports.restoreLayers = restoreLayers;
+const seedrandom_1 = __importDefault(require("seedrandom"));
+function assertSeed(seed, name) {
+    if (typeof seed !== "string" && typeof seed !== "number") {
+        throw new TypeError(`createRng: seeds.${name} must be a string or finite number.`);
+    }
+    if (typeof seed === "number" && !Number.isFinite(seed)) {
+        throw new RangeError(`createRng: seeds.${name} must be finite; received ${String(seed)}.`);
+    }
+}
+function makeStream(seed) {
+    const prng = (0, seedrandom_1.default)(String(seed), { state: true });
+    return { prng };
+}
+/**
+ * Create both RNG layers from their seeds. Called once at world creation
+ * (see `createSimWorld` in `./world`) — `gen` and `events` are independent
+ * seedrandom instances from this point on, so consuming one never perturbs
+ * the other's sequence.
+ */
+function createRng(seeds) {
+    if (typeof seeds !== "object" || seeds === null) {
+        throw new TypeError("createRng: seeds must be an object with gen and events values.");
+    }
+    assertSeed(seeds.gen, "gen");
+    assertSeed(seeds.events, "events");
+    return {
+        gen: makeStream(seeds.gen),
+        events: makeStream(seeds.events),
+    };
+}
+/**
+ * Draw the next raw unsigned 32-bit integer from `stream` (range
+ * `[0, 2**32)`). The lowest-level draw primitive — `nextFloat`, `nextInt`,
+ * and `chance` are all expressed in terms of `quick()`, not this function;
+ * reach for `nextU32` directly only when you need the full 32 bits of
+ * entropy (e.g. seeding another PRNG, hashing).
+ */
+function nextU32(stream) {
+    return stream.prng.int32() >>> 0;
+}
+/**
+ * Draw the next float from `stream` in the half-open range `[0, 1)`. The
+ * primitive every other draw helper in this module (`nextInt`, `chance`)
+ * is built on.
+ */
+function nextFloat(stream) {
+    return stream.prng.quick();
+}
+/**
+ * Draw a random integer from `stream` in the half-open range
+ * `[minInclusive, maxExclusive)`. Bounds must be safe integers, the range must
+ * be non-empty and no larger than `2**32`, and valid calls consume exactly one
+ * `nextFloat` draw. Invalid calls do not consume the stream.
+ */
+function nextInt(stream, minInclusive, maxExclusive) {
+    if (!Number.isSafeInteger(minInclusive) || !Number.isSafeInteger(maxExclusive)) {
+        throw new TypeError("nextInt: bounds must be safe integers.");
+    }
+    if (maxExclusive <= minInclusive) {
+        throw new RangeError(`nextInt: maxExclusive (${maxExclusive}) must be greater than minInclusive (${minInclusive}).`);
+    }
+    if (maxExclusive - minInclusive > 2 ** 32) {
+        throw new RangeError("nextInt: the requested range cannot exceed 2**32 values.");
+    }
+    const span = maxExclusive - minInclusive;
+    return minInclusive + Math.floor(nextFloat(stream) * span);
+}
+/**
+ * Roll a boolean weighted by finite probability `p` in `[0, 1]` (`0` never
+ * true, `1` always true). Valid calls consume exactly one `nextFloat` draw
+ * from `stream`, so calling `chance` where a system might otherwise skip a
+ * draw entirely will shift every later draw on that stream — keep draw counts
+ * deterministic across codepaths that must replay identically.
+ */
+function chance(stream, p) {
+    if (!Number.isFinite(p) || p < 0 || p > 1) {
+        throw new RangeError(`chance: probability must be a finite number in [0, 1]; received ${p}.`);
+    }
+    return nextFloat(stream) < p;
+}
+/**
+ * Capture `stream`'s internal seedrandom state as a plain, JSON-serializable
+ * object (deep-cloned, so later draws on `stream` cannot mutate the
+ * snapshot). Restoring it with `restoreStream` reproduces every subsequent
+ * draw byte-exact.
+ */
+function snapshotStream(stream) {
+    const state = stream.prng.state();
+    return { state: { i: state.i, j: state.j, S: [...state.S] } };
+}
+/**
+ * Snapshot both RNG layers at once. See `snapshotStream` — this just applies
+ * it to `gen` and `events` independently and returns both.
+ */
+function snapshotLayers(rng) {
+    return { gen: snapshotStream(rng.gen), events: snapshotStream(rng.events) };
+}
+/**
+ * Rebuild an `RngStream` from a snapshot taken by `snapshotStream`. The next
+ * draw on the returned stream reproduces the exact next draw the snapshotted
+ * stream would have produced — the seed string passed to `seedrandom` here
+ * is irrelevant because `{ state: snap.state }` fully overrides it. Malformed
+ * persisted state is rejected before seedrandom sees it.
+ */
+function restoreStream(snap) {
+    const state = snap?.state;
+    if (!state ||
+        !Number.isInteger(state.i) ||
+        state.i < 0 ||
+        state.i > 255 ||
+        !Number.isInteger(state.j) ||
+        state.j < 0 ||
+        state.j > 255 ||
+        !Array.isArray(state.S) ||
+        state.S.length !== 256 ||
+        state.S.some((value) => !Number.isInteger(value) || value < 0 || value > 255) ||
+        new Set(state.S).size !== 256) {
+        throw new TypeError("restoreStream: snapshot must contain a valid seedrandom ARC4 state.");
+    }
+    // Clone the permutation so the same immutable snapshot can safely seed more
+    // than one replay, even if seedrandom changes its internal copy behavior.
+    const prng = (0, seedrandom_1.default)("", { state: { i: state.i, j: state.j, S: [...state.S] } });
+    return { prng };
+}
+/**
+ * Rebuild both RNG layers from a snapshot taken by `snapshotLayers`. See
+ * `restoreStream` — applied independently to `gen` and `events`.
+ */
+function restoreLayers(snap) {
+    if (typeof snap !== "object" || snap === null) {
+        throw new TypeError("restoreLayers: snapshot must contain gen and events stream states.");
+    }
+    return { gen: restoreStream(snap.gen), events: restoreStream(snap.events) };
+}

package/dist/cjs/rng.d.cts

@@ -0,0 +1,86 @@
+import seedrandom from "seedrandom";
+type State = seedrandom.State.Arc4;
+type Stateful = seedrandom.StatefulPRNG<State>;
+export type RngStream = {
+    prng: Stateful;
+};
+export type RngLayers = {
+    gen: RngStream;
+    events: RngStream;
+};
+export type RngSeeds = {
+    /** World-generation seed (immutable, defines the world's identity). */
+    readonly gen: string | number;
+    /** Per-playthrough events seed (changes per cycle for new playthroughs of the same world). */
+    readonly events: string | number;
+};
+/**
+ * Create both RNG layers from their seeds. Called once at world creation
+ * (see `createSimWorld` in `./world`) — `gen` and `events` are independent
+ * seedrandom instances from this point on, so consuming one never perturbs
+ * the other's sequence.
+ */
+export declare function createRng(seeds: RngSeeds): RngLayers;
+/**
+ * Draw the next raw unsigned 32-bit integer from `stream` (range
+ * `[0, 2**32)`). The lowest-level draw primitive — `nextFloat`, `nextInt`,
+ * and `chance` are all expressed in terms of `quick()`, not this function;
+ * reach for `nextU32` directly only when you need the full 32 bits of
+ * entropy (e.g. seeding another PRNG, hashing).
+ */
+export declare function nextU32(stream: RngStream): number;
+/**
+ * Draw the next float from `stream` in the half-open range `[0, 1)`. The
+ * primitive every other draw helper in this module (`nextInt`, `chance`)
+ * is built on.
+ */
+export declare function nextFloat(stream: RngStream): number;
+/**
+ * Draw a random integer from `stream` in the half-open range
+ * `[minInclusive, maxExclusive)`. Bounds must be safe integers, the range must
+ * be non-empty and no larger than `2**32`, and valid calls consume exactly one
+ * `nextFloat` draw. Invalid calls do not consume the stream.
+ */
+export declare function nextInt(stream: RngStream, minInclusive: number, maxExclusive: number): number;
+/**
+ * Roll a boolean weighted by finite probability `p` in `[0, 1]` (`0` never
+ * true, `1` always true). Valid calls consume exactly one `nextFloat` draw
+ * from `stream`, so calling `chance` where a system might otherwise skip a
+ * draw entirely will shift every later draw on that stream — keep draw counts
+ * deterministic across codepaths that must replay identically.
+ */
+export declare function chance(stream: RngStream, p: number): boolean;
+export type RngStreamSnapshot = {
+    state: State;
+};
+export type RngLayersSnapshot = {
+    gen: RngStreamSnapshot;
+    events: RngStreamSnapshot;
+};
+/**
+ * Capture `stream`'s internal seedrandom state as a plain, JSON-serializable
+ * object (deep-cloned, so later draws on `stream` cannot mutate the
+ * snapshot). Restoring it with `restoreStream` reproduces every subsequent
+ * draw byte-exact.
+ */
+export declare function snapshotStream(stream: RngStream): RngStreamSnapshot;
+/**
+ * Snapshot both RNG layers at once. See `snapshotStream` — this just applies
+ * it to `gen` and `events` independently and returns both.
+ */
+export declare function snapshotLayers(rng: RngLayers): RngLayersSnapshot;
+/**
+ * Rebuild an `RngStream` from a snapshot taken by `snapshotStream`. The next
+ * draw on the returned stream reproduces the exact next draw the snapshotted
+ * stream would have produced — the seed string passed to `seedrandom` here
+ * is irrelevant because `{ state: snap.state }` fully overrides it. Malformed
+ * persisted state is rejected before seedrandom sees it.
+ */
+export declare function restoreStream(snap: RngStreamSnapshot): RngStream;
+/**
+ * Rebuild both RNG layers from a snapshot taken by `snapshotLayers`. See
+ * `restoreStream` — applied independently to `gen` and `events`.
+ */
+export declare function restoreLayers(snap: RngLayersSnapshot): RngLayers;
+export {};
+//# sourceMappingURL=rng.d.cts.map

package/dist/cjs/rng.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../../src/rng.ts"],"names":[],"mappings":"AAqBA,OAAO,UAAU,MAAM,YAAY,CAAC;AAEpC,KAAK,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;AACnC,KAAK,QAAQ,GAAG,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;AAE/C,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC,CAAC;AAgBF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAUpD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAc7F;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AACjD,MAAM,MAAM,iBAAiB,GAAG;IAAE,GAAG,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEtF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAGnE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,SAAS,GAAG,iBAAiB,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAqBhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAKhE"}

package/dist/cjs/traits/index.cjs

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * `src/traits/` — trait-authoring conventions, kept in a LEAF sub-package.
+ *
+ * Packaging pattern (from medieval-hexagon-gameboard): trait declarations
+ * live in a leaf sub-package with ZERO sibling imports — this file imports
+ * only `koota` (the npm dep) and pure types, never runtime values from
+ * sibling modules like ./world or ./rng. That is what prevents the
+ * koota ↔ world-facade ↔ game-scenario top-level evaluation cycle that a
+ * flat layout only dodges accidentally. Games adopting this package should
+ * follow the same rule: declare traits in their own leaf module, exported
+ * from exactly one location so trait reference-identity holds regardless of
+ * which subpath a consumer imports from.
+ *
+ * The AoS-aliasing footgun this module guards against (timber-town's
+ * documented convention): object-valued fields in a SoA schema must use the
+ * AoS-factory pattern (`() => ({...})`) so each entity gets its own object
+ * instance — koota's SoA pattern would otherwise alias state across
+ * entities (one shared object literal mutated by every entity that has the
+ * trait).
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTrait = defineTrait;
+const koota_1 = require("koota");
+/**
+ * Thin wrapper over koota's `trait()` that enforces the AoS-factory
+ * convention for object-valued fields, at both type level (see SafeSchema)
+ * and runtime (throws with an explanation instead of silently aliasing).
+ *
+ * Accepted forms:
+ *   defineTrait({ count: 0, label: "x" })            // SoA, primitives
+ *   defineTrait({ pos: () => ({ x: 0, y: 0 }) })     // SoA, per-field factory
+ *   defineTrait(() => ({ pos: { x: 0, y: 0 } }))     // whole-trait AoS factory
+ *
+ * Rejected (the footgun):
+ *   defineTrait({ pos: { x: 0, y: 0 } })             // shared literal → aliased
+ */
+function defineTrait(schema) {
+    if (typeof schema !== "function") {
+        for (const [key, value] of Object.entries(schema)) {
+            if (value !== null && typeof value === "object") {
+                throw new TypeError(`defineTrait: field "${key}" is a bare object literal. koota's SoA layout ` +
+                    `would share this single instance across every entity holding the trait ` +
+                    `(state aliasing). Use an AoS factory instead: ${key}: () => ({...}).`);
+            }
+        }
+    }
+    // Pin Koota's normalization generic to the caller's schema. Passing the
+    // guard intersection through inference makes Koota 0.6.x normalize
+    // `S & SafeSchema<S>` and produces a narrower, incompatible Trait type.
+    return (0, koota_1.trait)(schema);
+}

package/dist/cjs/traits/index.d.cts

@@ -0,0 +1,48 @@
+/**
+ * `src/traits/` — trait-authoring conventions, kept in a LEAF sub-package.
+ *
+ * Packaging pattern (from medieval-hexagon-gameboard): trait declarations
+ * live in a leaf sub-package with ZERO sibling imports — this file imports
+ * only `koota` (the npm dep) and pure types, never runtime values from
+ * sibling modules like ./world or ./rng. That is what prevents the
+ * koota ↔ world-facade ↔ game-scenario top-level evaluation cycle that a
+ * flat layout only dodges accidentally. Games adopting this package should
+ * follow the same rule: declare traits in their own leaf module, exported
+ * from exactly one location so trait reference-identity holds regardless of
+ * which subpath a consumer imports from.
+ *
+ * The AoS-aliasing footgun this module guards against (timber-town's
+ * documented convention): object-valued fields in a SoA schema must use the
+ * AoS-factory pattern (`() => ({...})`) so each entity gets its own object
+ * instance — koota's SoA pattern would otherwise alias state across
+ * entities (one shared object literal mutated by every entity that has the
+ * trait).
+ *
+ * @module
+ */
+import type { Norm, Schema, Trait } from "koota";
+/**
+ * Compile-time guard: any object-valued field in a SoA schema must be an
+ * AoS factory (`() => ({...})`), never a bare object literal. Fields that
+ * are functions, primitives, null, or undefined pass through unchanged;
+ * bare object/array literals map to `never`, producing a type error at the
+ * call site.
+ */
+export type SafeSchema<S> = S extends (...args: never[]) => unknown ? S : {
+    [K in keyof S]: S[K] extends (...args: never[]) => unknown ? S[K] : S[K] extends object ? never : S[K];
+};
+/**
+ * Thin wrapper over koota's `trait()` that enforces the AoS-factory
+ * convention for object-valued fields, at both type level (see SafeSchema)
+ * and runtime (throws with an explanation instead of silently aliasing).
+ *
+ * Accepted forms:
+ *   defineTrait({ count: 0, label: "x" })            // SoA, primitives
+ *   defineTrait({ pos: () => ({ x: 0, y: 0 }) })     // SoA, per-field factory
+ *   defineTrait(() => ({ pos: { x: 0, y: 0 } }))     // whole-trait AoS factory
+ *
+ * Rejected (the footgun):
+ *   defineTrait({ pos: { x: 0, y: 0 } })             // shared literal → aliased
+ */
+export declare function defineTrait<S extends Schema>(schema: S & SafeSchema<S>): Trait<Norm<S>>;
+//# sourceMappingURL=index.d.cts.map

package/dist/cjs/traits/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/traits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGjD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAC/D,CAAC,GACD;KACG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GACtD,CAAC,CAAC,CAAC,CAAC,GACJ,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACjB,KAAK,GACL,CAAC,CAAC,CAAC,CAAC;CACX,CAAC;AAEN;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAgBvF"}

package/dist/cjs/world.cjs

@@ -0,0 +1,111 @@
+"use strict";
+// World facade. Wraps koota's createWorld + trait helper so the rest of a
+// game's codebase imports from here and lifecycle/determinism conventions stay
+// behind one boundary.
+//
+// Games declare their traits with `defineTrait` (see ./traits) and drive the
+// sim through the WorldHandle: world creation, trait re-export, tick clock,
+// dual-layer RNG plumbing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trait = exports.relation = exports.createActions = void 0;
+exports.createSimWorld = createSimWorld;
+exports.destroySimWorld = destroySimWorld;
+exports.advanceClock = advanceClock;
+exports.snapshotWorld = snapshotWorld;
+exports.restoreWorldHeader = restoreWorldHeader;
+const koota_1 = require("koota");
+Object.defineProperty(exports, "createActions", { enumerable: true, get: function () { return koota_1.createActions; } });
+Object.defineProperty(exports, "relation", { enumerable: true, get: function () { return koota_1.relation; } });
+Object.defineProperty(exports, "trait", { enumerable: true, get: function () { return koota_1.trait; } });
+const rng_js_1 = require("./rng.cjs");
+/**
+ * Create a fresh `WorldHandle`: a new koota world, both RNG layers seeded
+ * from `seeds`, a zeroed clock, and an empty scratch map. This is the one
+ * entry point for standing up a sim — call it once per world (per game
+ * session, per test, per worldgen run) rather than constructing the koota
+ * world and RNG separately, so the facade's invariants (immutable `seeds`,
+ * clock starting at zero, scratch starting empty) always hold.
+ */
+function createSimWorld(seeds) {
+    // Validate before allocating a Koota world: invalid input must not consume a
+    // process-global world id or leave a world that the caller cannot destroy.
+    const rng = (0, rng_js_1.createRng)(seeds);
+    const immutableSeeds = Object.freeze({ gen: seeds.gen, events: seeds.events });
+    return {
+        world: (0, koota_1.createWorld)(),
+        rng,
+        seeds: immutableSeeds,
+        clock: { tickIndex: 0, simSeconds: 0 },
+        scratch: new Map(),
+    };
+}
+/**
+ * Tear down a simulation handle. This clears facade-owned scratch state and
+ * releases Koota's process-global world id. The operation is idempotent, which
+ * makes it safe to call from cleanup paths that may run more than once.
+ */
+function destroySimWorld(handle) {
+    handle.scratch.clear();
+    if (handle.world.isInitialized) {
+        handle.world.destroy();
+    }
+}
+/**
+ * Advance `handle`'s clock by one fixed-timestep tick: increments
+ * `tickIndex` by 1 and accumulates `dt` seconds into `simSeconds`. Call once
+ * per sim tick, before running that tick's systems, so `clock` always
+ * reflects "how far the sim has progressed" rather than "how far it will
+ * have progressed after this tick's work."
+ */
+function advanceClock(handle, dt) {
+    if (!Number.isFinite(dt) || dt < 0) {
+        throw new RangeError(`advanceClock: dt must be a finite, non-negative number; received ${dt}.`);
+    }
+    if (!Number.isSafeInteger(handle.clock.tickIndex) || handle.clock.tickIndex < 0) {
+        throw new RangeError("advanceClock: clock.tickIndex must be a non-negative safe integer.");
+    }
+    if (!Number.isFinite(handle.clock.simSeconds) || handle.clock.simSeconds < 0) {
+        throw new RangeError("advanceClock: clock.simSeconds must be finite and non-negative.");
+    }
+    const tickIndex = handle.clock.tickIndex + 1;
+    const simSeconds = handle.clock.simSeconds + dt;
+    if (!Number.isSafeInteger(tickIndex) || !Number.isFinite(simSeconds)) {
+        throw new RangeError("advanceClock: advancing the clock would exceed its numeric range.");
+    }
+    handle.clock.tickIndex = tickIndex;
+    handle.clock.simSeconds = simSeconds;
+}
+/**
+ * Capture `handle`'s RNG state and clock into a plain, JSON-serializable
+ * `WorldSnapshot`. Pair with `restoreWorldHeader` for save/load — restoring
+ * a snapshot reproduces every subsequent RNG draw on both layers byte-exact
+ * and resumes the clock from the exact tick/second it was captured at.
+ */
+function snapshotWorld(handle) {
+    return {
+        rng: (0, rng_js_1.snapshotLayers)(handle.rng),
+        clock: { tickIndex: handle.clock.tickIndex, simSeconds: handle.clock.simSeconds },
+    };
+}
+/**
+ * Restore `handle`'s RNG layers and clock from a `WorldSnapshot` taken by
+ * `snapshotWorld`. Mutates `handle` in place (replaces `handle.rng` and
+ * `handle.clock` with freshly rebuilt values) — entity/component state is
+ * untouched, since the facade never captured it in the first place; restore
+ * that separately using whatever serialization your game chose.
+ */
+function restoreWorldHeader(handle, snap) {
+    const clock = snap?.clock;
+    if (!clock ||
+        !Number.isSafeInteger(clock.tickIndex) ||
+        clock.tickIndex < 0 ||
+        !Number.isFinite(clock.simSeconds) ||
+        clock.simSeconds < 0) {
+        throw new TypeError("restoreWorldHeader: snapshot.clock must contain a non-negative safe integer tickIndex and finite, non-negative simSeconds.");
+    }
+    // Build and validate every replacement before mutating the handle so a bad
+    // persisted snapshot cannot leave it half-restored.
+    const rng = (0, rng_js_1.restoreLayers)(snap.rng);
+    handle.rng = rng;
+    handle.clock = { tickIndex: clock.tickIndex, simSeconds: clock.simSeconds };
+}

package/dist/cjs/world.d.cts

@@ -0,0 +1,83 @@
+import type { World } from "koota";
+import { createActions, relation, trait } from "koota";
+import type { RngLayers, RngLayersSnapshot, RngSeeds } from "./rng.cjs";
+export type { Entity } from "koota";
+export type { World };
+export { createActions, relation, trait };
+export type WorldHandle = {
+    readonly world: World;
+    rng: RngLayers;
+    /**
+     * The immutable seeds this world was created from. Stored so systems
+     * can derive deterministic per-entity seeds (e.g. noise keyed on an
+     * entity's stable grid coordinates) WITHOUT lazily consuming the
+     * rng.gen stream in query-iteration order — koota entity ids are not
+     * reset between worlds, so iteration-order rng draws are
+     * non-deterministic across two runs in one process. Derive from
+     * `seeds.gen`, never a lazy draw.
+     */
+    readonly seeds: Readonly<RngSeeds>;
+    clock: {
+        tickIndex: number;
+        simSeconds: number;
+    };
+    /**
+     * Per-system scratch caches owned by the WorldHandle (so they lifecycle with
+     * the world, not at module scope). Systems read/write via well-known keys.
+     * Examples: per-region noise fns, pathfinding grids, behavior-tree instances.
+     */
+    readonly scratch: Map<string, unknown>;
+};
+/**
+ * Create a fresh `WorldHandle`: a new koota world, both RNG layers seeded
+ * from `seeds`, a zeroed clock, and an empty scratch map. This is the one
+ * entry point for standing up a sim — call it once per world (per game
+ * session, per test, per worldgen run) rather than constructing the koota
+ * world and RNG separately, so the facade's invariants (immutable `seeds`,
+ * clock starting at zero, scratch starting empty) always hold.
+ */
+export declare function createSimWorld(seeds: RngSeeds): WorldHandle;
+/**
+ * Tear down a simulation handle. This clears facade-owned scratch state and
+ * releases Koota's process-global world id. The operation is idempotent, which
+ * makes it safe to call from cleanup paths that may run more than once.
+ */
+export declare function destroySimWorld(handle: WorldHandle): void;
+/**
+ * Advance `handle`'s clock by one fixed-timestep tick: increments
+ * `tickIndex` by 1 and accumulates `dt` seconds into `simSeconds`. Call once
+ * per sim tick, before running that tick's systems, so `clock` always
+ * reflects "how far the sim has progressed" rather than "how far it will
+ * have progressed after this tick's work."
+ */
+export declare function advanceClock(handle: WorldHandle, dt: number): void;
+/**
+ * The serializable "header" of a world: both RNG layers' byte-exact state
+ * plus the clock. Deliberately excludes entity/component state — koota
+ * entities are the caller's data to serialize however their game needs
+ * (full ECS dump, delta log, etc.); this snapshot only covers what the
+ * facade itself owns.
+ */
+export type WorldSnapshot = {
+    rng: RngLayersSnapshot;
+    clock: {
+        tickIndex: number;
+        simSeconds: number;
+    };
+};
+/**
+ * Capture `handle`'s RNG state and clock into a plain, JSON-serializable
+ * `WorldSnapshot`. Pair with `restoreWorldHeader` for save/load — restoring
+ * a snapshot reproduces every subsequent RNG draw on both layers byte-exact
+ * and resumes the clock from the exact tick/second it was captured at.
+ */
+export declare function snapshotWorld(handle: WorldHandle): WorldSnapshot;
+/**
+ * Restore `handle`'s RNG layers and clock from a `WorldSnapshot` taken by
+ * `snapshotWorld`. Mutates `handle` in place (replaces `handle.rng` and
+ * `handle.clock` with freshly rebuilt values) — entity/component state is
+ * untouched, since the facade never captured it in the first place; restore
+ * that separately using whatever serialization your game chose.
+ */
+export declare function restoreWorldHeader(handle: WorldHandle, snap: WorldSnapshot): void;
+//# sourceMappingURL=world.d.cts.map

package/dist/cjs/world.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../src/world.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,aAAa,EAAe,QAAQ,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGvE,YAAY,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACpC,YAAY,EAAE,KAAK,EAAE,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAE1C,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,GAAG,EAAE,SAAS,CAAC;IACf;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,CAY3D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAKzD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAiBlE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,iBAAiB,CAAC;IACvB,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,CAKhE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAkBjF"}

package/dist/esm/eventLog.d.ts

@@ -0,0 +1,49 @@
+import type { WorldHandle } from "./world.js";
+/**
+ * A published event log: append here, drain or peek from the other side.
+ *
+ * Returned as an object rather than loose functions so a system declares its log
+ * ONCE at module scope and the key is written in exactly one place. Two string
+ * literals for the same log is the typo that produces an event stream nobody
+ * receives, and no type checker can catch it.
+ */
+export type EventLog<T> = {
+    /** The scratch key, exposed for debugging and for snapshot tooling. */
+    readonly key: string;
+    /** Append an event. Called by the system that owns the fact. */
+    push: (handle: WorldHandle, event: T) => void;
+    /**
+     * Take every event and EMPTY the log — for the single consuming system.
+     *
+     * If two systems both need the same events, that is a design question and not
+     * a reason to drain twice: publish two logs, or have the second peek. A log
+     * drained by two consumers delivers each event to whichever ran first.
+     */
+    drain: (handle: WorldHandle) => T[];
+    /**
+     * Read every event WITHOUT emptying — for observers: harnesses, tests, HUDs.
+     *
+     * Returns a readonly copy, so a caller cannot mutate the live array and
+     * cannot hold a reference that changes underneath them.
+     */
+    peek: (handle: WorldHandle) => readonly T[];
+    /** Drop everything without reading. For run teardown and test setup. */
+    clear: (handle: WorldHandle) => void;
+    /** How many events are pending, without allocating a copy. */
+    size: (handle: WorldHandle) => number;
+};
+/**
+ * Declare an event log under `key`.
+ *
+ * The array is created lazily on first use and lives in `handle.scratch`, so it
+ * lifecycles with the world: a new run starts with empty logs and cannot inherit
+ * the last one's events. That is not a detail — a log at module scope survives
+ * the world that produced it, and stale events replay into a fresh run.
+ *
+ * Keys should be namespaced by system (`"combat:hits"`, `"voices:events"`) for
+ * the same reason trait names are: scratch is one flat map shared by every
+ * system in the world. Empty keys are rejected, as is a collision with an
+ * existing non-array scratch value.
+ */
+export declare function defineEventLog<T>(key: string): EventLog<T>;
+//# sourceMappingURL=eventLog.d.ts.map

package/dist/esm/eventLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventLog.d.ts","sourceRoot":"","sources":["../../src/eventLog.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IACxB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC9C;;;;;;OAMG;IACH,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,CAAC,EAAE,CAAC;IACpC;;;;;OAKG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,SAAS,CAAC,EAAE,CAAC;IAC5C,wEAAwE;IACxE,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IACrC,8DAA8D;IAC9D,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,MAAM,CAAC;CACvC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CA6C1D"}