koota-kit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.3.0](https://github.com/jbcom/koota-kit/compare/v0.2.1...v0.3.0) (2026-10-06)
+
+
+### Features
+
+* add named RNG substreams, seed derivation, and master seeds ([a120cb7](https://github.com/jbcom/koota-kit/commit/a120cb7209eac1d16b964c6f3af2d97061cfcfc3))
+
+
+### Bug Fixes
+
+* type EntropySource so Web Crypto implementations satisfy it ([7b8d3cb](https://github.com/jbcom/koota-kit/commit/7b8d3cb3ee8a5a994b1578f3000270d40b5295f9))
+
+## [0.2.1](https://github.com/jbcom/koota-kit/compare/v0.2.0...v0.2.1) (2026-10-06)
+
+
+### Bug Fixes
+
+* sync the lockfile with the docs sourcey range ([eab4ae1](https://github.com/jbcom/koota-kit/commit/eab4ae1df3194cc1157b2a59ea0b04c3bc5345eb))
+* sync the lockfile with the docs sourcey range ([be276e5](https://github.com/jbcom/koota-kit/commit/be276e52f7d58621fd3730a5762b8c4eccbc5cbb))
+
 ## [0.2.0](https://github.com/jbcom/koota-kit/compare/v0.1.1...v0.2.0) (2026-08-24)
 
 

package/README.md

@@ -106,15 +106,20 @@ stream in query iteration order. Entity IDs contain process-global world and
 generation bits. Derive a local stream from a stable domain key instead:
 
 ```ts
-import { createRng, nextU32 } from "koota-kit/rng";
+import { nextU32, substream } from "koota-kit/rng";
+import { deriveSeed } from "koota-kit/seed";
 
-const tileRng = createRng({
-  gen: `${String(sim.seeds.gen)}/tile:12,8`,
-  events: 0,
-});
-const terrainVariant = nextU32(tileRng.gen);
+const tileSeed = deriveSeed(sim.seeds.gen, "tile", 12, 8);
+const terrainVariant = nextU32(substream(tileSeed, "terrain"));
 ```
 
+`deriveSeed` hashes length-prefixed parts into a 128-bit hex seed, so seed
+chains such as master seed → run → level never collide by accident.
+`substream(seed, name)` gives each generator its own stream; adding a new
+named substream never shifts an existing one. `createMasterSeed()` makes a
+128-bit root seed from `crypto.getRandomValues`, and accepts an injected
+entropy source for tests.
+
 ### Object-valued traits need factories
 
 Koota's structure-of-arrays layout can alias a bare object literal across
@@ -137,9 +142,12 @@ the system responsible for acting on the event should drain.
 ## Persistence boundary
 
 `snapshotWorld` stores the clock and both RNG states. It intentionally does not
-serialize entities or traits: those are application data with application-
-specific schemas and migrations. `restoreWorldHeader` validates a parsed save
-before changing the handle and restores atomically.
+serialize immutable seeds, entities, or traits: persist `sim.seeds` beside the
+header so a fresh handle can retain stable derived randomness, and keep entity
+data in application-specific schemas and migrations. Stage a fresh handle when
+loading so old scratch caches and event logs cannot leak into the restored run.
+`restoreWorldHeader` validates a parsed save before changing that staged handle
+and restores atomically.
 
 Persist a version beside the header and your ECS state so the application can
 migrate its own schema.
@@ -151,7 +159,8 @@ The root package exports the full API. Focused entry points are also available:
 | Entry point | Purpose |
 | --- | --- |
 | `koota-kit/world` | World lifecycle, clock, Koota facade, world snapshots |
-| `koota-kit/rng` | Seeded streams, bounded draws, snapshots |
+| `koota-kit/rng` | Seeded streams, named substreams, bounded draws, snapshots |
+| `koota-kit/seed` | Seed derivation and 128-bit master seeds |
 | `koota-kit/traits` | Safe trait declaration |
 | `koota-kit/eventLog` | World-scoped publish/drain logs |
 
@@ -159,9 +168,17 @@ See the [API reference](./docs/API.md) for signatures and validation behavior,
 and [architecture notes](./docs/ARCHITECTURE.md) for module boundaries and
 invariants.
 
+For task-oriented usage, read the Sourcey guides on
+[deterministic randomness](https://jonbogaty.com/koota-kit/determinism/),
+[save headers](https://jonbogaty.com/koota-kit/persistence/), and
+[event ownership](https://jonbogaty.com/koota-kit/event-logs/).
+
 ## Errors and edge cases
 
-- Seeds must be strings or finite numbers.
+- Seeds must be strings or finite numbers. Substream names must be non-empty
+  strings.
+- `createMasterSeed` throws when no entropy source exists or the source leaves
+  the buffer all zero.
 - `advanceClock` accepts finite, non-negative `dt`; `0` is a valid paused tick.
 - `nextInt` requires safe-integer bounds with `maxExclusive > minInclusive` and
   a range no larger than `2**32`.

package/dist/cjs/index.cjs

@@ -1,16 +1,18 @@
 "use strict";
 // koota-kit — thin koota ECS conventions layer.
 //
-// Four modules, also importable as subpaths:
+// Five modules, also importable as subpaths:
 //   ./world    — WorldHandle lifecycle (world + dual-stream rng + clock + scratch)
-//   ./rng      — dual-layer deterministic seedrandom PRNG with byte-exact
-//                snapshot/restore
+//   ./rng      — dual-layer deterministic seedrandom PRNG and named substreams
+//                with byte-exact snapshot/restore
+//   ./seed     — length-prefixed SHA-256 seed derivation and 128-bit master
+//                seeds (leaf module, zero runtime dependencies)
 //   ./traits   — defineTrait AoS-aliasing guard (leaf module, zero sibling
 //                imports)
 //   ./eventLog — scratch-backed publish/drain event logs with a peek seam for
 //                observers (harnesses, tests, HUDs)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineTrait = exports.defineEventLog = exports.snapshotStream = exports.snapshotLayers = exports.restoreStream = exports.restoreLayers = exports.nextU32 = exports.nextInt = exports.nextFloat = exports.createRng = exports.chance = exports.trait = exports.snapshotWorld = exports.restoreWorldHeader = exports.relation = exports.destroySimWorld = exports.createSimWorld = exports.createActions = exports.advanceClock = void 0;
+exports.defineTrait = exports.defineEventLog = exports.MASTER_SEED_BYTES = exports.isMasterSeed = exports.deriveSeed = exports.createMasterSeed = exports.substream = exports.snapshotSubstreams = exports.snapshotStream = exports.snapshotLayers = exports.restoreSubstreams = exports.restoreStream = exports.restoreLayers = exports.nextU32 = exports.nextInt = exports.nextFloat = exports.getSubstream = exports.createSubstreams = exports.createRng = exports.chance = exports.trait = exports.snapshotWorld = exports.restoreWorldHeader = exports.relation = exports.destroySimWorld = exports.createSimWorld = exports.createActions = exports.advanceClock = void 0;
 var world_js_1 = require("./world.cjs");
 Object.defineProperty(exports, "advanceClock", { enumerable: true, get: function () { return world_js_1.advanceClock; } });
 Object.defineProperty(exports, "createActions", { enumerable: true, get: function () { return world_js_1.createActions; } });
@@ -23,13 +25,23 @@ Object.defineProperty(exports, "trait", { enumerable: true, get: function () { r
 var rng_js_1 = require("./rng.cjs");
 Object.defineProperty(exports, "chance", { enumerable: true, get: function () { return rng_js_1.chance; } });
 Object.defineProperty(exports, "createRng", { enumerable: true, get: function () { return rng_js_1.createRng; } });
+Object.defineProperty(exports, "createSubstreams", { enumerable: true, get: function () { return rng_js_1.createSubstreams; } });
+Object.defineProperty(exports, "getSubstream", { enumerable: true, get: function () { return rng_js_1.getSubstream; } });
 Object.defineProperty(exports, "nextFloat", { enumerable: true, get: function () { return rng_js_1.nextFloat; } });
 Object.defineProperty(exports, "nextInt", { enumerable: true, get: function () { return rng_js_1.nextInt; } });
 Object.defineProperty(exports, "nextU32", { enumerable: true, get: function () { return rng_js_1.nextU32; } });
 Object.defineProperty(exports, "restoreLayers", { enumerable: true, get: function () { return rng_js_1.restoreLayers; } });
 Object.defineProperty(exports, "restoreStream", { enumerable: true, get: function () { return rng_js_1.restoreStream; } });
+Object.defineProperty(exports, "restoreSubstreams", { enumerable: true, get: function () { return rng_js_1.restoreSubstreams; } });
 Object.defineProperty(exports, "snapshotLayers", { enumerable: true, get: function () { return rng_js_1.snapshotLayers; } });
 Object.defineProperty(exports, "snapshotStream", { enumerable: true, get: function () { return rng_js_1.snapshotStream; } });
+Object.defineProperty(exports, "snapshotSubstreams", { enumerable: true, get: function () { return rng_js_1.snapshotSubstreams; } });
+Object.defineProperty(exports, "substream", { enumerable: true, get: function () { return rng_js_1.substream; } });
+var seed_js_1 = require("./seed.cjs");
+Object.defineProperty(exports, "createMasterSeed", { enumerable: true, get: function () { return seed_js_1.createMasterSeed; } });
+Object.defineProperty(exports, "deriveSeed", { enumerable: true, get: function () { return seed_js_1.deriveSeed; } });
+Object.defineProperty(exports, "isMasterSeed", { enumerable: true, get: function () { return seed_js_1.isMasterSeed; } });
+Object.defineProperty(exports, "MASTER_SEED_BYTES", { enumerable: true, get: function () { return seed_js_1.MASTER_SEED_BYTES; } });
 var eventLog_js_1 = require("./eventLog.cjs");
 Object.defineProperty(exports, "defineEventLog", { enumerable: true, get: function () { return eventLog_js_1.defineEventLog; } });
 var index_js_1 = require("./traits/index.cjs");

package/dist/cjs/index.d.cts

@@ -1,7 +1,9 @@
 export { advanceClock, createActions, createSimWorld, destroySimWorld, relation, restoreWorldHeader, snapshotWorld, trait, } from "./world.cjs";
 export type { Entity, World, WorldHandle, WorldSnapshot } from "./world.cjs";
-export { chance, createRng, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, snapshotLayers, snapshotStream, } from "./rng.cjs";
-export type { RngLayers, RngLayersSnapshot, RngSeeds, RngStream, RngStreamSnapshot, } from "./rng.cjs";
+export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, restoreSubstreams, snapshotLayers, snapshotStream, snapshotSubstreams, substream, } from "./rng.cjs";
+export type { RngLayers, RngLayersSnapshot, RngSeeds, RngStream, RngStreamSnapshot, Substreams, SubstreamsSnapshot, } from "./rng.cjs";
+export { createMasterSeed, deriveSeed, isMasterSeed, MASTER_SEED_BYTES } from "./seed.cjs";
+export type { EntropySource, SeedPart } from "./seed.cjs";
 export { defineEventLog } from "./eventLog.cjs";
 export type { EventLog } from "./eventLog.cjs";
 export { defineTrait } from "./traits/index.cjs";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,SAAS,EACT,OAAO,EACP,OAAO,EACP,aAAa,EACb,aAAa,EACb,cAAc,EACd,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/cjs/rng.cjs

@@ -32,7 +32,13 @@ exports.snapshotStream = snapshotStream;
 exports.snapshotLayers = snapshotLayers;
 exports.restoreStream = restoreStream;
 exports.restoreLayers = restoreLayers;
+exports.substream = substream;
+exports.createSubstreams = createSubstreams;
+exports.getSubstream = getSubstream;
+exports.snapshotSubstreams = snapshotSubstreams;
+exports.restoreSubstreams = restoreSubstreams;
 const seedrandom_1 = __importDefault(require("seedrandom"));
+const seed_js_1 = require("./seed.cjs");
 function assertSeed(seed, name) {
     if (typeof seed !== "string" && typeof seed !== "number") {
         throw new TypeError(`createRng: seeds.${name} must be a string or finite number.`);
@@ -166,3 +172,77 @@ function restoreLayers(snap) {
     }
     return { gen: restoreStream(snap.gen), events: restoreStream(snap.events) };
 }
+function assertSubstreamName(name, api) {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new TypeError(`${api}: name must be a non-empty string.`);
+    }
+}
+function assertSubstreamSeed(seed, api) {
+    if (typeof seed !== "string" && !(typeof seed === "number" && Number.isFinite(seed))) {
+        throw new TypeError(`${api}: seed must be a string or finite number.`);
+    }
+}
+/**
+ * Create the stream named `name` under `seed`: a fresh stream seeded by
+ * `deriveSeed(seed, name)`. Creating or consuming any other substream never
+ * shifts this one.
+ */
+function substream(seed, name) {
+    assertSubstreamName(name, "substream");
+    return makeStream((0, seed_js_1.deriveSeed)(seed, name));
+}
+/** Create an empty, lazily populated set of named substreams under `seed`. */
+function createSubstreams(seed) {
+    assertSubstreamSeed(seed, "createSubstreams");
+    return { seed, streams: new Map() };
+}
+/**
+ * Return the set's stream for `name`, creating it from the set's seed on first
+ * use. The same name always returns the same live stream instance.
+ */
+function getSubstream(substreams, name) {
+    assertSubstreamName(name, "getSubstream");
+    const existing = substreams.streams.get(name);
+    if (existing)
+        return existing;
+    const stream = substream(substreams.seed, name);
+    substreams.streams.set(name, stream);
+    return stream;
+}
+/**
+ * Capture the set's seed plus every stream created so far, with names in
+ * sorted order. JSON-serializable and detached from later draws.
+ */
+function snapshotSubstreams(substreams) {
+    // Object.fromEntries defines own data properties, so a stream named
+    // "__proto__" is captured instead of hitting the prototype setter.
+    const streams = Object.fromEntries([...substreams.streams.keys()]
+        // UTF-16 code-unit order, never localeCompare: the order must not vary
+        // by runtime locale. Branch-free because names in a Map are unique.
+        .sort((left, right) => Number(left > right) - Number(left < right))
+        .map((name) => [name, snapshotStream(substreams.streams.get(name))]));
+    return { seed: substreams.seed, streams };
+}
+/**
+ * Rebuild a substream set from `snapshotSubstreams` output. Validates the
+ * complete snapshot before building anything; streams that were never created
+ * restore lazily from the seed on first `getSubstream`.
+ */
+function restoreSubstreams(snapshot) {
+    if (typeof snapshot !== "object" || snapshot === null) {
+        throw new TypeError("restoreSubstreams: snapshot must contain a seed and streams.");
+    }
+    assertSubstreamSeed(snapshot.seed, "restoreSubstreams");
+    const entries = snapshot.streams;
+    if (typeof entries !== "object" || entries === null || Array.isArray(entries)) {
+        throw new TypeError("restoreSubstreams: streams must be an object keyed by stream name.");
+    }
+    const restored = new Map();
+    for (const [name, stream] of Object.entries(entries)) {
+        if (name.length === 0) {
+            throw new TypeError("restoreSubstreams: stream names must be non-empty strings.");
+        }
+        restored.set(name, restoreStream(stream));
+    }
+    return { seed: snapshot.seed, streams: restored };
+}

package/dist/cjs/rng.d.cts

@@ -82,5 +82,39 @@ export declare function restoreStream(snap: RngStreamSnapshot): RngStream;
  * `restoreStream` — applied independently to `gen` and `events`.
  */
 export declare function restoreLayers(snap: RngLayersSnapshot): RngLayers;
+export type Substreams = {
+    /** The seed every member stream is derived from. */
+    readonly seed: string | number;
+    /** Streams created so far, keyed by name. Create members with `getSubstream`. */
+    readonly streams: ReadonlyMap<string, RngStream>;
+};
+export type SubstreamsSnapshot = {
+    seed: string | number;
+    streams: Record<string, RngStreamSnapshot>;
+};
+/**
+ * Create the stream named `name` under `seed`: a fresh stream seeded by
+ * `deriveSeed(seed, name)`. Creating or consuming any other substream never
+ * shifts this one.
+ */
+export declare function substream(seed: string | number, name: string): RngStream;
+/** Create an empty, lazily populated set of named substreams under `seed`. */
+export declare function createSubstreams(seed: string | number): Substreams;
+/**
+ * Return the set's stream for `name`, creating it from the set's seed on first
+ * use. The same name always returns the same live stream instance.
+ */
+export declare function getSubstream(substreams: Substreams, name: string): RngStream;
+/**
+ * Capture the set's seed plus every stream created so far, with names in
+ * sorted order. JSON-serializable and detached from later draws.
+ */
+export declare function snapshotSubstreams(substreams: Substreams): SubstreamsSnapshot;
+/**
+ * Rebuild a substream set from `snapshotSubstreams` output. Validates the
+ * complete snapshot before building anything; streams that were never created
+ * restore lazily from the seed on first `getSubstream`.
+ */
+export declare function restoreSubstreams(snapshot: SubstreamsSnapshot): Substreams;
 export {};
 //# sourceMappingURL=rng.d.cts.map

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

@@ -1 +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"}
+{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../../src/rng.ts"],"names":[],"mappings":"AAqBA,OAAO,UAAU,MAAM,YAAY,CAAC;AAGpC,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;AAUD,MAAM,MAAM,UAAU,GAAG;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC5C,CAAC;AAcF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAGxE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAGlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAO5E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,kBAAkB,CAW7E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,UAAU,CAiB1E"}

package/dist/cjs/seed.cjs

@@ -0,0 +1,188 @@
+"use strict";
+// Seed derivation and master seeds.
+//
+// A seeded game usually has a chain of seeds: a buried master seed for the
+// profile, a run seed derived from it, a level seed derived from that, and
+// one stream per generator. Building those keys by string concatenation is
+// ambiguous ("1" + "23" === "12" + "3"), so `deriveSeed` hashes length-prefixed
+// parts instead. Leaf module: no runtime dependency, so it is identical in
+// browsers and Node and in both the ESM and CommonJS builds.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MASTER_SEED_BYTES = void 0;
+exports.deriveSeed = deriveSeed;
+exports.createMasterSeed = createMasterSeed;
+exports.isMasterSeed = isMasterSeed;
+/** Byte length of a master seed (128 bits). */
+exports.MASTER_SEED_BYTES = 16;
+// Changing the domain tag or the encoding changes every derived seed in every
+// consumer's saves. Treat both as a frozen public contract.
+const DERIVE_DOMAIN = "koota-kit:deriveSeed:v1";
+const HEX_SEED = /^[0-9a-f]{32}$/;
+function canonicalPart(value, label, api) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    throw new TypeError(`${api}: ${label} must be a string or finite number.`);
+}
+/** UTF-8 encode, mapping lone surrogates to U+FFFD exactly like TextEncoder. */
+function utf8(text) {
+    const bytes = [];
+    // String iteration yields whole code points; an unpaired surrogate arrives
+    // alone as its own code unit, so it is the only surrogate value seen here.
+    for (const char of text) {
+        let code = char.codePointAt(0);
+        if (code >= 0xd800 && code <= 0xdfff)
+            code = 0xfffd;
+        if (code < 0x80) {
+            bytes.push(code);
+        }
+        else if (code < 0x800) {
+            bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+        }
+        else if (code < 0x10000) {
+            bytes.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+        }
+        else {
+            bytes.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 0x3f), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+        }
+    }
+    return bytes;
+}
+const K = [
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+const rotr = (value, bits) => (value >>> bits) | (value << (32 - bits));
+/** FIPS 180-4 SHA-256 of `message`, as eight big-endian 32-bit words. */
+function sha256(message) {
+    const bitLength = message.length * 8;
+    const zeroPadding = (55 - (message.length % 64) + 64) % 64;
+    // Seed inputs are far below 2**32 bits, so the high length word is zero.
+    const padded = [
+        ...message,
+        0x80,
+        ...new Array(zeroPadding).fill(0),
+        0,
+        0,
+        0,
+        0,
+        bitLength >>> 24,
+        (bitLength >>> 16) & 0xff,
+        (bitLength >>> 8) & 0xff,
+        bitLength & 0xff,
+    ];
+    const hash = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let t = 0; t < 16; t += 1) {
+            const i = offset + t * 4;
+            w[t] =
+                (padded[i] << 24) |
+                    (padded[i + 1] << 16) |
+                    (padded[i + 2] << 8) |
+                    padded[i + 3];
+        }
+        for (let t = 16; t < 64; t += 1) {
+            const w15 = w[t - 15];
+            const w2 = w[t - 2];
+            const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+            const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+            w[t] = (w[t - 16] + s0 + w[t - 7] + s1) >>> 0;
+        }
+        let a = hash[0];
+        let b = hash[1];
+        let c = hash[2];
+        let d = hash[3];
+        let e = hash[4];
+        let f = hash[5];
+        let g = hash[6];
+        let h = hash[7];
+        for (let t = 0; t < 64; t += 1) {
+            const t1 = (h +
+                (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) +
+                ((e & f) ^ (~e & g)) +
+                K[t] +
+                w[t]) >>>
+                0;
+            const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        hash[0] = (hash[0] + a) >>> 0;
+        hash[1] = (hash[1] + b) >>> 0;
+        hash[2] = (hash[2] + c) >>> 0;
+        hash[3] = (hash[3] + d) >>> 0;
+        hash[4] = (hash[4] + e) >>> 0;
+        hash[5] = (hash[5] + f) >>> 0;
+        hash[6] = (hash[6] + g) >>> 0;
+        hash[7] = (hash[7] + h) >>> 0;
+    }
+    return hash;
+}
+const toHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+/**
+ * Derive a child seed from `parent` and ordered `parts`. Returns the first 128
+ * bits of SHA-256 over a domain tag plus each value as a 4-byte big-endian
+ * UTF-8 length and its UTF-8 text, as 32 lowercase hex characters. Numbers
+ * canonicalize to their string form, matching `createRng`.
+ */
+function deriveSeed(parent, ...parts) {
+    const values = [canonicalPart(parent, "parent", "deriveSeed")];
+    parts.forEach((part, index) => {
+        values.push(canonicalPart(part, `parts[${index}]`, "deriveSeed"));
+    });
+    const chunks = [utf8(DERIVE_DOMAIN)];
+    for (const value of values) {
+        const encoded = utf8(value);
+        const length = encoded.length;
+        const prefix = [
+            (length >>> 24) & 0xff,
+            (length >>> 16) & 0xff,
+            (length >>> 8) & 0xff,
+            length & 0xff,
+        ];
+        chunks.push(prefix, encoded);
+    }
+    const digest = sha256(chunks.flat());
+    return Array.from(digest.subarray(0, 4), (word) => word.toString(16).padStart(8, "0")).join("");
+}
+/**
+ * Create a 128-bit master seed from `entropy` (default `globalThis.crypto`)
+ * as 32 lowercase hex characters. Fails closed when no source exists, when it
+ * returns anything but the requested 16-byte buffer, or when the buffer is
+ * still all zero (an unfilled stub, not entropy).
+ */
+function createMasterSeed(entropy) {
+    const source = entropy ?? globalThis.crypto;
+    if (!source || typeof source.getRandomValues !== "function") {
+        throw new TypeError("createMasterSeed: no entropy source with getRandomValues is available.");
+    }
+    const requested = new Uint8Array(exports.MASTER_SEED_BYTES);
+    const bytes = source.getRandomValues(requested);
+    if (bytes !== requested) {
+        throw new TypeError("createMasterSeed: the entropy source must fill the requested 16-byte array.");
+    }
+    if (bytes.every((byte) => byte === 0)) {
+        throw new RangeError("createMasterSeed: the entropy source returned all zero bytes.");
+    }
+    return toHex(bytes);
+}
+/** True for exactly 32 lowercase hex characters: the shape of a master or derived seed. */
+function isMasterSeed(value) {
+    return typeof value === "string" && HEX_SEED.test(value);
+}

package/dist/cjs/seed.d.cts

@@ -0,0 +1,25 @@
+/** A value that can seed a stream or be mixed into a derived seed. */
+export type SeedPart = string | number;
+/** The subset of Web Crypto that `createMasterSeed` needs. Inject one in tests. */
+export type EntropySource = {
+    getRandomValues(array: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+};
+/** Byte length of a master seed (128 bits). */
+export declare const MASTER_SEED_BYTES = 16;
+/**
+ * Derive a child seed from `parent` and ordered `parts`. Returns the first 128
+ * bits of SHA-256 over a domain tag plus each value as a 4-byte big-endian
+ * UTF-8 length and its UTF-8 text, as 32 lowercase hex characters. Numbers
+ * canonicalize to their string form, matching `createRng`.
+ */
+export declare function deriveSeed(parent: SeedPart, ...parts: SeedPart[]): string;
+/**
+ * Create a 128-bit master seed from `entropy` (default `globalThis.crypto`)
+ * as 32 lowercase hex characters. Fails closed when no source exists, when it
+ * returns anything but the requested 16-byte buffer, or when the buffer is
+ * still all zero (an unfilled stub, not entropy).
+ */
+export declare function createMasterSeed(entropy?: EntropySource): string;
+/** True for exactly 32 lowercase hex characters: the shape of a master or derived seed. */
+export declare function isMasterSeed(value: unknown): value is string;
+//# sourceMappingURL=seed.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../src/seed.ts"],"names":[],"mappings":"AASA,sEAAsE;AACtE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,mFAAmF;AAGnF,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;CAC1E,CAAC;AAEF,+CAA+C;AAC/C,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAoIpC;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAmBzE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAgBhE;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE5D"}

package/dist/esm/index.d.ts

@@ -1,7 +1,9 @@
 export { advanceClock, createActions, createSimWorld, destroySimWorld, relation, restoreWorldHeader, snapshotWorld, trait, } from "./world.js";
 export type { Entity, World, WorldHandle, WorldSnapshot } from "./world.js";
-export { chance, createRng, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, snapshotLayers, snapshotStream, } from "./rng.js";
-export type { RngLayers, RngLayersSnapshot, RngSeeds, RngStream, RngStreamSnapshot, } from "./rng.js";
+export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, restoreSubstreams, snapshotLayers, snapshotStream, snapshotSubstreams, substream, } from "./rng.js";
+export type { RngLayers, RngLayersSnapshot, RngSeeds, RngStream, RngStreamSnapshot, Substreams, SubstreamsSnapshot, } from "./rng.js";
+export { createMasterSeed, deriveSeed, isMasterSeed, MASTER_SEED_BYTES } from "./seed.js";
+export type { EntropySource, SeedPart } from "./seed.js";
 export { defineEventLog } from "./eventLog.js";
 export type { EventLog } from "./eventLog.js";
 export { defineTrait } from "./traits/index.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,SAAS,EACT,OAAO,EACP,OAAO,EACP,aAAa,EACb,aAAa,EACb,cAAc,EACd,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/index.js

@@ -1,14 +1,17 @@
 // koota-kit — thin koota ECS conventions layer.
 //
-// Four modules, also importable as subpaths:
+// Five modules, also importable as subpaths:
 //   ./world    — WorldHandle lifecycle (world + dual-stream rng + clock + scratch)
-//   ./rng      — dual-layer deterministic seedrandom PRNG with byte-exact
-//                snapshot/restore
+//   ./rng      — dual-layer deterministic seedrandom PRNG and named substreams
+//                with byte-exact snapshot/restore
+//   ./seed     — length-prefixed SHA-256 seed derivation and 128-bit master
+//                seeds (leaf module, zero runtime dependencies)
 //   ./traits   — defineTrait AoS-aliasing guard (leaf module, zero sibling
 //                imports)
 //   ./eventLog — scratch-backed publish/drain event logs with a peek seam for
 //                observers (harnesses, tests, HUDs)
 export { advanceClock, createActions, createSimWorld, destroySimWorld, relation, restoreWorldHeader, snapshotWorld, trait, } from "./world.js";
-export { chance, createRng, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, snapshotLayers, snapshotStream, } from "./rng.js";
+export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, restoreSubstreams, snapshotLayers, snapshotStream, snapshotSubstreams, substream, } from "./rng.js";
+export { createMasterSeed, deriveSeed, isMasterSeed, MASTER_SEED_BYTES } from "./seed.js";
 export { defineEventLog } from "./eventLog.js";
 export { defineTrait } from "./traits/index.js";

package/dist/esm/rng.d.ts

@@ -82,5 +82,39 @@ export declare function restoreStream(snap: RngStreamSnapshot): RngStream;
  * `restoreStream` — applied independently to `gen` and `events`.
  */
 export declare function restoreLayers(snap: RngLayersSnapshot): RngLayers;
+export type Substreams = {
+    /** The seed every member stream is derived from. */
+    readonly seed: string | number;
+    /** Streams created so far, keyed by name. Create members with `getSubstream`. */
+    readonly streams: ReadonlyMap<string, RngStream>;
+};
+export type SubstreamsSnapshot = {
+    seed: string | number;
+    streams: Record<string, RngStreamSnapshot>;
+};
+/**
+ * Create the stream named `name` under `seed`: a fresh stream seeded by
+ * `deriveSeed(seed, name)`. Creating or consuming any other substream never
+ * shifts this one.
+ */
+export declare function substream(seed: string | number, name: string): RngStream;
+/** Create an empty, lazily populated set of named substreams under `seed`. */
+export declare function createSubstreams(seed: string | number): Substreams;
+/**
+ * Return the set's stream for `name`, creating it from the set's seed on first
+ * use. The same name always returns the same live stream instance.
+ */
+export declare function getSubstream(substreams: Substreams, name: string): RngStream;
+/**
+ * Capture the set's seed plus every stream created so far, with names in
+ * sorted order. JSON-serializable and detached from later draws.
+ */
+export declare function snapshotSubstreams(substreams: Substreams): SubstreamsSnapshot;
+/**
+ * Rebuild a substream set from `snapshotSubstreams` output. Validates the
+ * complete snapshot before building anything; streams that were never created
+ * restore lazily from the seed on first `getSubstream`.
+ */
+export declare function restoreSubstreams(snapshot: SubstreamsSnapshot): Substreams;
 export {};
 //# sourceMappingURL=rng.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../../src/rng.ts"],"names":[],"mappings":"AAqBA,OAAO,UAAU,MAAM,YAAY,CAAC;AAGpC,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;AAUD,MAAM,MAAM,UAAU,GAAG;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC5C,CAAC;AAcF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAGxE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAGlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAO5E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,kBAAkB,CAW7E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,UAAU,CAiB1E"}

package/dist/esm/rng.js

@@ -19,6 +19,7 @@
 // Forbidden in sim code: `Math.random()`. Use `nextFloat(rng.gen)` or
 // `nextFloat(rng.events)` depending on the layer.
 import seedrandom from "seedrandom";
+import { deriveSeed } from "./seed.js";
 function assertSeed(seed, name) {
     if (typeof seed !== "string" && typeof seed !== "number") {
         throw new TypeError(`createRng: seeds.${name} must be a string or finite number.`);
@@ -152,3 +153,77 @@ export function restoreLayers(snap) {
     }
     return { gen: restoreStream(snap.gen), events: restoreStream(snap.events) };
 }
+function assertSubstreamName(name, api) {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new TypeError(`${api}: name must be a non-empty string.`);
+    }
+}
+function assertSubstreamSeed(seed, api) {
+    if (typeof seed !== "string" && !(typeof seed === "number" && Number.isFinite(seed))) {
+        throw new TypeError(`${api}: seed must be a string or finite number.`);
+    }
+}
+/**
+ * Create the stream named `name` under `seed`: a fresh stream seeded by
+ * `deriveSeed(seed, name)`. Creating or consuming any other substream never
+ * shifts this one.
+ */
+export function substream(seed, name) {
+    assertSubstreamName(name, "substream");
+    return makeStream(deriveSeed(seed, name));
+}
+/** Create an empty, lazily populated set of named substreams under `seed`. */
+export function createSubstreams(seed) {
+    assertSubstreamSeed(seed, "createSubstreams");
+    return { seed, streams: new Map() };
+}
+/**
+ * Return the set's stream for `name`, creating it from the set's seed on first
+ * use. The same name always returns the same live stream instance.
+ */
+export function getSubstream(substreams, name) {
+    assertSubstreamName(name, "getSubstream");
+    const existing = substreams.streams.get(name);
+    if (existing)
+        return existing;
+    const stream = substream(substreams.seed, name);
+    substreams.streams.set(name, stream);
+    return stream;
+}
+/**
+ * Capture the set's seed plus every stream created so far, with names in
+ * sorted order. JSON-serializable and detached from later draws.
+ */
+export function snapshotSubstreams(substreams) {
+    // Object.fromEntries defines own data properties, so a stream named
+    // "__proto__" is captured instead of hitting the prototype setter.
+    const streams = Object.fromEntries([...substreams.streams.keys()]
+        // UTF-16 code-unit order, never localeCompare: the order must not vary
+        // by runtime locale. Branch-free because names in a Map are unique.
+        .sort((left, right) => Number(left > right) - Number(left < right))
+        .map((name) => [name, snapshotStream(substreams.streams.get(name))]));
+    return { seed: substreams.seed, streams };
+}
+/**
+ * Rebuild a substream set from `snapshotSubstreams` output. Validates the
+ * complete snapshot before building anything; streams that were never created
+ * restore lazily from the seed on first `getSubstream`.
+ */
+export function restoreSubstreams(snapshot) {
+    if (typeof snapshot !== "object" || snapshot === null) {
+        throw new TypeError("restoreSubstreams: snapshot must contain a seed and streams.");
+    }
+    assertSubstreamSeed(snapshot.seed, "restoreSubstreams");
+    const entries = snapshot.streams;
+    if (typeof entries !== "object" || entries === null || Array.isArray(entries)) {
+        throw new TypeError("restoreSubstreams: streams must be an object keyed by stream name.");
+    }
+    const restored = new Map();
+    for (const [name, stream] of Object.entries(entries)) {
+        if (name.length === 0) {
+            throw new TypeError("restoreSubstreams: stream names must be non-empty strings.");
+        }
+        restored.set(name, restoreStream(stream));
+    }
+    return { seed: snapshot.seed, streams: restored };
+}

package/dist/esm/seed.d.ts

@@ -0,0 +1,25 @@
+/** A value that can seed a stream or be mixed into a derived seed. */
+export type SeedPart = string | number;
+/** The subset of Web Crypto that `createMasterSeed` needs. Inject one in tests. */
+export type EntropySource = {
+    getRandomValues(array: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+};
+/** Byte length of a master seed (128 bits). */
+export declare const MASTER_SEED_BYTES = 16;
+/**
+ * Derive a child seed from `parent` and ordered `parts`. Returns the first 128
+ * bits of SHA-256 over a domain tag plus each value as a 4-byte big-endian
+ * UTF-8 length and its UTF-8 text, as 32 lowercase hex characters. Numbers
+ * canonicalize to their string form, matching `createRng`.
+ */
+export declare function deriveSeed(parent: SeedPart, ...parts: SeedPart[]): string;
+/**
+ * Create a 128-bit master seed from `entropy` (default `globalThis.crypto`)
+ * as 32 lowercase hex characters. Fails closed when no source exists, when it
+ * returns anything but the requested 16-byte buffer, or when the buffer is
+ * still all zero (an unfilled stub, not entropy).
+ */
+export declare function createMasterSeed(entropy?: EntropySource): string;
+/** True for exactly 32 lowercase hex characters: the shape of a master or derived seed. */
+export declare function isMasterSeed(value: unknown): value is string;
+//# sourceMappingURL=seed.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../src/seed.ts"],"names":[],"mappings":"AASA,sEAAsE;AACtE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,mFAAmF;AAGnF,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;CAC1E,CAAC;AAEF,+CAA+C;AAC/C,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAoIpC;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAmBzE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAgBhE;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE5D"}

package/dist/esm/seed.js

@@ -0,0 +1,182 @@
+// Seed derivation and master seeds.
+//
+// A seeded game usually has a chain of seeds: a buried master seed for the
+// profile, a run seed derived from it, a level seed derived from that, and
+// one stream per generator. Building those keys by string concatenation is
+// ambiguous ("1" + "23" === "12" + "3"), so `deriveSeed` hashes length-prefixed
+// parts instead. Leaf module: no runtime dependency, so it is identical in
+// browsers and Node and in both the ESM and CommonJS builds.
+/** Byte length of a master seed (128 bits). */
+export const MASTER_SEED_BYTES = 16;
+// Changing the domain tag or the encoding changes every derived seed in every
+// consumer's saves. Treat both as a frozen public contract.
+const DERIVE_DOMAIN = "koota-kit:deriveSeed:v1";
+const HEX_SEED = /^[0-9a-f]{32}$/;
+function canonicalPart(value, label, api) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    throw new TypeError(`${api}: ${label} must be a string or finite number.`);
+}
+/** UTF-8 encode, mapping lone surrogates to U+FFFD exactly like TextEncoder. */
+function utf8(text) {
+    const bytes = [];
+    // String iteration yields whole code points; an unpaired surrogate arrives
+    // alone as its own code unit, so it is the only surrogate value seen here.
+    for (const char of text) {
+        let code = char.codePointAt(0);
+        if (code >= 0xd800 && code <= 0xdfff)
+            code = 0xfffd;
+        if (code < 0x80) {
+            bytes.push(code);
+        }
+        else if (code < 0x800) {
+            bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+        }
+        else if (code < 0x10000) {
+            bytes.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+        }
+        else {
+            bytes.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 0x3f), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+        }
+    }
+    return bytes;
+}
+const K = [
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+const rotr = (value, bits) => (value >>> bits) | (value << (32 - bits));
+/** FIPS 180-4 SHA-256 of `message`, as eight big-endian 32-bit words. */
+function sha256(message) {
+    const bitLength = message.length * 8;
+    const zeroPadding = (55 - (message.length % 64) + 64) % 64;
+    // Seed inputs are far below 2**32 bits, so the high length word is zero.
+    const padded = [
+        ...message,
+        0x80,
+        ...new Array(zeroPadding).fill(0),
+        0,
+        0,
+        0,
+        0,
+        bitLength >>> 24,
+        (bitLength >>> 16) & 0xff,
+        (bitLength >>> 8) & 0xff,
+        bitLength & 0xff,
+    ];
+    const hash = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let t = 0; t < 16; t += 1) {
+            const i = offset + t * 4;
+            w[t] =
+                (padded[i] << 24) |
+                    (padded[i + 1] << 16) |
+                    (padded[i + 2] << 8) |
+                    padded[i + 3];
+        }
+        for (let t = 16; t < 64; t += 1) {
+            const w15 = w[t - 15];
+            const w2 = w[t - 2];
+            const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+            const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+            w[t] = (w[t - 16] + s0 + w[t - 7] + s1) >>> 0;
+        }
+        let a = hash[0];
+        let b = hash[1];
+        let c = hash[2];
+        let d = hash[3];
+        let e = hash[4];
+        let f = hash[5];
+        let g = hash[6];
+        let h = hash[7];
+        for (let t = 0; t < 64; t += 1) {
+            const t1 = (h +
+                (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) +
+                ((e & f) ^ (~e & g)) +
+                K[t] +
+                w[t]) >>>
+                0;
+            const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        hash[0] = (hash[0] + a) >>> 0;
+        hash[1] = (hash[1] + b) >>> 0;
+        hash[2] = (hash[2] + c) >>> 0;
+        hash[3] = (hash[3] + d) >>> 0;
+        hash[4] = (hash[4] + e) >>> 0;
+        hash[5] = (hash[5] + f) >>> 0;
+        hash[6] = (hash[6] + g) >>> 0;
+        hash[7] = (hash[7] + h) >>> 0;
+    }
+    return hash;
+}
+const toHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+/**
+ * Derive a child seed from `parent` and ordered `parts`. Returns the first 128
+ * bits of SHA-256 over a domain tag plus each value as a 4-byte big-endian
+ * UTF-8 length and its UTF-8 text, as 32 lowercase hex characters. Numbers
+ * canonicalize to their string form, matching `createRng`.
+ */
+export function deriveSeed(parent, ...parts) {
+    const values = [canonicalPart(parent, "parent", "deriveSeed")];
+    parts.forEach((part, index) => {
+        values.push(canonicalPart(part, `parts[${index}]`, "deriveSeed"));
+    });
+    const chunks = [utf8(DERIVE_DOMAIN)];
+    for (const value of values) {
+        const encoded = utf8(value);
+        const length = encoded.length;
+        const prefix = [
+            (length >>> 24) & 0xff,
+            (length >>> 16) & 0xff,
+            (length >>> 8) & 0xff,
+            length & 0xff,
+        ];
+        chunks.push(prefix, encoded);
+    }
+    const digest = sha256(chunks.flat());
+    return Array.from(digest.subarray(0, 4), (word) => word.toString(16).padStart(8, "0")).join("");
+}
+/**
+ * Create a 128-bit master seed from `entropy` (default `globalThis.crypto`)
+ * as 32 lowercase hex characters. Fails closed when no source exists, when it
+ * returns anything but the requested 16-byte buffer, or when the buffer is
+ * still all zero (an unfilled stub, not entropy).
+ */
+export function createMasterSeed(entropy) {
+    const source = entropy ?? globalThis.crypto;
+    if (!source || typeof source.getRandomValues !== "function") {
+        throw new TypeError("createMasterSeed: no entropy source with getRandomValues is available.");
+    }
+    const requested = new Uint8Array(MASTER_SEED_BYTES);
+    const bytes = source.getRandomValues(requested);
+    if (bytes !== requested) {
+        throw new TypeError("createMasterSeed: the entropy source must fill the requested 16-byte array.");
+    }
+    if (bytes.every((byte) => byte === 0)) {
+        throw new RangeError("createMasterSeed: the entropy source returned all zero bytes.");
+    }
+    return toHex(bytes);
+}
+/** True for exactly 32 lowercase hex characters: the shape of a master or derived seed. */
+export function isMasterSeed(value) {
+    return typeof value === "string" && HEX_SEED.test(value);
+}

package/docs/API.md

@@ -43,9 +43,11 @@ function restoreWorldHeader(handle: WorldHandle, snapshot: WorldSnapshot): void;
 ```
 
 Snapshots and restores both RNG streams plus the simulation clock. The plain
-object can be round-tripped through JSON. Entity and trait data are outside
-this package's persistence boundary. Restore validates the complete replacement
-before mutating the handle.
+object can be round-tripped through JSON. It does not include `WorldHandle.seeds`:
+persist the immutable seeds separately and use them when creating a fresh
+handle for loading. Entity and trait data are also outside this package's
+persistence boundary. Restore validates the complete replacement before
+mutating the handle.
 
 ### Koota exports
 
@@ -80,6 +82,72 @@ function restoreLayers(snapshot: RngLayersSnapshot): RngLayers;
 - Restore functions reject malformed ARC4 state and clone accepted state so a
   snapshot can seed multiple independent replays.
 
+### Named substreams
+
+```ts
+type Substreams = {
+  readonly seed: string | number;
+  readonly streams: ReadonlyMap<string, RngStream>;
+};
+type SubstreamsSnapshot = {
+  seed: string | number;
+  streams: Record<string, RngStreamSnapshot>;
+};
+
+function substream(seed: string | number, name: string): RngStream;
+function createSubstreams(seed: string | number): Substreams;
+function getSubstream(substreams: Substreams, name: string): RngStream;
+function snapshotSubstreams(substreams: Substreams): SubstreamsSnapshot;
+function restoreSubstreams(snapshot: SubstreamsSnapshot): Substreams;
+```
+
+- `substream(seed, name)` returns a fresh stream seeded by
+  `deriveSeed(seed, name)`. Its sequence depends only on `seed` and `name`, so
+  adding, removing, reordering, or consuming another substream never shifts it.
+- `name` must be a non-empty string. Invalid input throws before anything is
+  allocated.
+- `createSubstreams` holds one lazily created stream per name, so generators
+  that share a set keep drawing where they left off. `getSubstream` returns the
+  same stream instance for the same name.
+- `snapshotSubstreams` captures the seed plus every stream created so far, with
+  names in sorted order. `restoreSubstreams` validates the whole snapshot
+  before building anything and reproduces every later draw byte-exact. Streams
+  that were never created restore lazily from the seed.
+
+## `seed`
+
+```ts
+type SeedPart = string | number;
+type EntropySource = {
+  getRandomValues(array: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+}; // `globalThis.crypto` satisfies it, with or without DOM typings
+
+const MASTER_SEED_BYTES = 16;
+
+function deriveSeed(parent: SeedPart, ...parts: SeedPart[]): string;
+function createMasterSeed(entropy?: EntropySource): string;
+function isMasterSeed(value: unknown): value is string;
+```
+
+- `deriveSeed` hashes the parent seed and every part with SHA-256 and returns
+  the first 128 bits as 32 lowercase hex characters. The result is a valid
+  seed for `createRng`, `createSimWorld`, `substream`, and further
+  `deriveSeed` calls.
+- Every value is length-prefixed before hashing, so `("a", "bc")` and
+  `("ab", "c")` derive different seeds. Order matters.
+- Numbers canonicalize to their string form, matching `createRng`, so
+  `deriveSeed(7, "x") === deriveSeed("7", "x")`. Non-finite numbers and
+  non-string, non-number values throw.
+- The output is stable across platforms and package versions. A change to the
+  derivation would be a breaking change.
+- `createMasterSeed` fills 16 bytes from `entropy` (default
+  `globalThis.crypto`) and returns them as 32 lowercase hex characters. It
+  throws when no entropy source exists, when the source returns something
+  other than the requested 16-byte array, or when it returns all zero bytes,
+  which signals an unfilled buffer rather than real entropy.
+- `isMasterSeed` accepts exactly 32 lowercase hex characters. Use it to
+  validate a persisted seed before deriving from it.
+
 ## `traits`
 
 ```ts

package/docs/ARCHITECTURE.md

@@ -8,7 +8,8 @@ queries, and actions directly.
 
 ```text
 traits ───────────────> koota
-rng ──────────────────> seedrandom
+seed ─────────────────> (leaf: built-in SHA-256)
+rng ──────────────────> seedrandom + seed
 world ────────────────> koota + rng
 eventLog ─────────────> WorldHandle scratch
 index ────────────────> public re-exports only
@@ -19,7 +20,15 @@ keeps trait declarations out of world/scenario evaluation cycles and preserves
 the reference identity Koota uses to identify traits.
 
 `rng` has no Koota dependency. Its serialized contract is the seedrandom ARC4
-state plus a two-stream container.
+state plus a two-stream container, or a seed plus named-substream container.
+
+`seed` is a leaf module with no runtime dependency at all. `deriveSeed` uses a
+small built-in synchronous SHA-256 so it behaves identically in browsers and
+Node, in both the ESM and the CommonJS build (Web Crypto's digest is async, and
+the common hash packages are ESM-only). The test suite checks it against
+`node:crypto` and a frozen golden vector. Its byte encoding (a
+domain tag, then each value as a 4-byte big-endian UTF-8 length plus its UTF-8
+text) is a stable contract: changing it would change every derived world.
 
 `world` owns allocation, teardown, time, and facade-owned persistence. It does
 not own application entity serialization.
@@ -36,6 +45,8 @@ lifetime. It does not use a process-global queue.
 5. Object-valued structure-of-arrays fields use factories.
 6. Event logs have one consuming owner; observers use `peek`.
 7. World teardown clears facade-owned scratch state and releases the Koota ID.
+8. A named substream's sequence depends only on its seed and name; creating or
+   consuming another substream never shifts it.
 
 ## Performance choices
 
@@ -52,6 +63,7 @@ lifetime. It does not use a process-global queue.
 - No entity/trait serializer: applications need versioned domain schemas.
 - No scheduler or system runner: Koota's queries/actions remain the execution
   model.
-- No automatic derived-key hashing: the application owns stable domain keys.
+- No implicit derived keys: `deriveSeed` hashes only the parts the application
+  passes, so the application still owns stable domain keys.
 - No multi-consumer queue semantics: publish separate logs when two systems
   must independently consume the same fact.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koota-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Deterministic Koota simulation conventions: world lifecycle, dual RNG streams, safe object traits, and world-scoped event logs.",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,16 @@
         "default": "./dist/cjs/rng.cjs"
       }
     },
+    "./seed": {
+      "import": {
+        "types": "./dist/esm/seed.d.ts",
+        "default": "./dist/esm/seed.js"
+      },
+      "require": {
+        "types": "./dist/cjs/seed.d.cts",
+        "default": "./dist/cjs/seed.cjs"
+      }
+    },
     "./traits": {
       "import": {
         "types": "./dist/esm/traits/index.d.ts",
@@ -147,6 +157,9 @@
       "rng": [
         "./dist/esm/rng.d.ts"
       ],
+      "seed": [
+        "./dist/esm/seed.d.ts"
+      ],
       "traits": [
         "./dist/esm/traits/index.d.ts"
       ],

package/docs/changelog.md

@@ -1,13 +0,0 @@
----
-title: Changelog
-description: Release history maintained by Release Please from Conventional Commits.
----
-
-Release Please maintains the canonical
-[CHANGELOG.md](https://github.com/jbcom/koota-kit/blob/main/CHANGELOG.md),
-version metadata, tags, and GitHub Releases. Published releases use npm
-provenance and the project supports the latest `0.x` line.
-
-For planned changes, use a Conventional Commit type such as `fix:`, `feat:`,
-`docs:`, `refactor:`, `test:`, or `chore:`. Breaking public API changes need a
-`!` or `BREAKING CHANGE:` footer.