koota-kit 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.6.0](https://github.com/jbcom/koota-kit/compare/v0.5.0...v0.6.0) (2026-10-10)
+
+
+### Features
+
+* **schedule:** add createSchedule, a fixed-step system schedule ([bb69bd6](https://github.com/jbcom/koota-kit/commit/bb69bd638e7a3dc6315ede827e4c58820facea3a))
+* **schedule:** add createSchedule, a fixed-step system schedule ([21f6ffb](https://github.com/jbcom/koota-kit/commit/21f6ffbb2a6f4fae819f88197d02e30f50cc98ea))
+
+
+### Bug Fixes
+
+* **schedule:** pause means no steps, and a refused step is never debited ([e2fbfad](https://github.com/jbcom/koota-kit/commit/e2fbfadb363764bc8c43232e19862223ef250ee6))
+
 ## [0.5.0](https://github.com/jbcom/koota-kit/compare/v0.4.0...v0.5.0) (2026-10-10)
 
 

package/README.md

@@ -137,6 +137,26 @@ defineTrait({ storage: { logs: 0 } });         // TypeError: shared object footg
 Declare traits once in a leaf module and export each trait from one location.
 Koota identifies traits by reference, not by a string name.
 
+### A fixed-step schedule removes the frame rate from the sim
+
+`createSchedule(systems, { step, maxSteps })` returns a `tick(handle, frameDt)`
+for your frame loop. The frame's dt fills an accumulator kept in `handle.scratch`
+(so it dies with the run); each whole `step` advances the clock, then calls every
+system in order with `dt === step`. At most `maxSteps` run per tick and any
+excess is dropped, so one huge dt after a backgrounded tab cannot cause a
+catch-up storm. `tick(handle, 0)` is a valid pause and returns the steps run.
+
+```ts
+import { createSchedule } from "koota-kit";
+
+const schedule = createSchedule([stove, mixer, serving], { step: 1 / 60, maxSteps: 6 });
+// once per rendered frame:
+const steps = schedule.tick(sim, frameDt);
+```
+
+Sixty frames of 1/60 s and thirty of 1/30 s run the same sixty steps.
+`schedule.remainder(sim) / schedule.step` is the interpolation alpha.
+
 ### Event logs have one consuming owner
 
 `push` appends, `drain` returns every pending event and empties the log, and
@@ -205,6 +225,7 @@ are also available:
 | `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/schedule` | Fixed-step system schedule with a step cap |
 | `koota-kit/eventLog` | World-scoped publish/drain logs |
 | `koota-kit/react` | `SimWorldProvider` and `useSimWorld` (optional React peer) |
 
@@ -224,6 +245,8 @@ For task-oriented usage, read the Sourcey guides on
 - `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.
+- `createSchedule` needs a finite `step > 0` and a safe-integer `maxSteps >= 1`;
+  a negative, `NaN` or infinite `frameDt` counts as `0`.
 - `nextInt` requires safe-integer bounds with `maxExclusive > minInclusive` and
   a range no larger than `2**32`.
 - `chance` accepts only finite probabilities in `[0, 1]`.

package/dist/cjs/index.cjs

@@ -1,8 +1,9 @@
 "use strict";
 // koota-kit — thin koota ECS conventions layer.
 //
-// Five modules, also importable as subpaths:
+// Six modules, also importable as subpaths:
 //   ./world    — WorldHandle lifecycle (world + dual-stream rng + clock + scratch)
+//   ./schedule — fixed-step system schedule (accumulator in scratch, step cap)
 //   ./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
@@ -12,7 +13,7 @@
 //   ./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.MASTER_SEED_BYTES = exports.isMasterSeed = exports.deriveSeed = exports.createMasterSeed = exports.substream = exports.snapshotSubstreams = exports.snapshotStream = exports.snapshotLayers = exports.shuffle = exports.restoreSubstreams = exports.restoreStream = exports.restoreLayers = exports.pick = 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;
+exports.defineTrait = exports.defineEventLog = exports.createSchedule = exports.MASTER_SEED_BYTES = exports.isMasterSeed = exports.deriveSeed = exports.createMasterSeed = exports.substream = exports.snapshotSubstreams = exports.snapshotStream = exports.snapshotLayers = exports.shuffle = exports.restoreSubstreams = exports.restoreStream = exports.restoreLayers = exports.pick = 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; } });
@@ -44,6 +45,8 @@ Object.defineProperty(exports, "createMasterSeed", { enumerable: true, get: func
 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 schedule_js_1 = require("./schedule.cjs");
+Object.defineProperty(exports, "createSchedule", { enumerable: true, get: function () { return schedule_js_1.createSchedule; } });
 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

@@ -4,6 +4,8 @@ export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt,
 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 { createSchedule } from "./schedule.cjs";
+export type { Schedule, ScheduleOptions, System } from "./schedule.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":"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,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,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,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,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,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvE,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/schedule.cjs

@@ -0,0 +1,131 @@
+"use strict";
+// Fixed-step system schedule — the loop that turns "a frame passed" into
+// "the sim advanced by whole steps".
+//
+// A simulation that integrates the frame's own dt drifts with the frame rate:
+// a 120 Hz phone and a test that advances three seconds in one call disagree,
+// and anything counted in real time (a save every 0.25 s) lands on different
+// ticks. A fixed-step schedule removes the frame rate from the sim: the frame's
+// dt fills an accumulator, and the sim only ever advances by whole `step`s.
+//
+// The loop is generic sim plumbing, so it lives here and not in the game: it
+// knows nothing about React, a renderer, or what a system does. A renderer's
+// frame callback calls `schedule.tick(handle, dt)` and that is the entire
+// integration. The accumulator lives in the handle's `scratch`, so it dies with
+// the run: a new world starts with nothing owed, and two schedules (or two
+// worlds) never share one.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSchedule = createSchedule;
+const world_js_1 = require("./world.cjs");
+let nextScheduleId = 0;
+// Keys are process-wide because schedules are declared once at module scope and
+// used on many handles. An explicit key may be shared on purpose; a generated
+// one must stay private to its schedule.
+const claimedKeys = new Set();
+const generatedKeys = new Set();
+// Float accumulation: 432 frames of 1/144 add up to a hair under 3 s, and
+// without a tolerance the sim would owe — and run — one step fewer than the
+// same time delivered at 60 Hz. A billionth of a step is far below anything a
+// frame clock can resolve, so treating "within it" as whole costs nothing.
+const STEP_TOLERANCE = 1e-9;
+/**
+ * Build a fixed-step schedule over `systems`, run in the order given.
+ *
+ * ```ts
+ * const schedule = createSchedule([intro, stove, mixer, serving], {
+ *   step: 1 / 60,
+ *   maxSteps: 6,
+ * });
+ * // once per rendered frame, with the frame's dt:
+ * schedule.tick(run, frameDt);
+ * ```
+ *
+ * The systems array is copied; later changes to it do not affect the schedule.
+ */
+function createSchedule(systems, options) {
+    if (!Array.isArray(systems)) {
+        throw new TypeError("createSchedule: systems must be an array of functions.");
+    }
+    const { step, maxSteps } = options;
+    if (!Number.isFinite(step) || step <= 0) {
+        throw new RangeError(`createSchedule: step must be finite and greater than zero; received ${step}.`);
+    }
+    if (!Number.isSafeInteger(maxSteps) || maxSteps < 1) {
+        throw new RangeError(`createSchedule: maxSteps must be a safe integer of at least 1; received ${maxSteps}.`);
+    }
+    if (options.key !== undefined && (typeof options.key !== "string" || options.key === "")) {
+        throw new TypeError("createSchedule: key must be a non-empty string when provided.");
+    }
+    const ordered = Object.freeze([...systems]);
+    for (const system of ordered) {
+        if (typeof system !== "function") {
+            throw new TypeError("createSchedule: every system must be a function.");
+        }
+    }
+    let key;
+    if (options.key === undefined) {
+        // Skip any key a caller has already named, so a default never lands on one.
+        do {
+            key = `schedule:${nextScheduleId++}`;
+        } while (claimedKeys.has(key));
+        generatedKeys.add(key);
+    }
+    else {
+        if (generatedKeys.has(options.key)) {
+            throw new TypeError(`createSchedule: key "${options.key}" is already the generated key of another schedule.`);
+        }
+        key = options.key;
+    }
+    claimedKeys.add(key);
+    const tolerance = step * STEP_TOLERANCE;
+    function read(handle) {
+        const stored = handle.scratch.get(key);
+        if (stored === undefined)
+            return 0;
+        if (typeof stored !== "number" || !Number.isFinite(stored) || stored < 0) {
+            throw new TypeError(`createSchedule: scratch key "${key}" already holds something other than a schedule accumulator.`);
+        }
+        return stored;
+    }
+    function tick(handle, frameDt) {
+        const previous = read(handle);
+        // A pause (and any frame dt that counts as 0) runs nothing, even if a
+        // failed tick left whole steps owed: those wait for a frame that moves time.
+        if (!(Number.isFinite(frameDt) && frameDt > 0))
+            return 0;
+        const sum = previous + frameDt;
+        // Two huge finite frames can sum past the double range; saturate instead of
+        // letting Infinity poison the stored accumulator.
+        let owed = Number.isFinite(sum) ? sum : Number.MAX_VALUE;
+        let ran = 0;
+        try {
+            while (owed + tolerance >= step && ran < maxSteps) {
+                // The clock moves first, so a step it refuses (an exhausted clock) is
+                // never debited. After that the step is spent before any system runs:
+                // if one throws, this step's time is gone with the tick it caused.
+                (0, world_js_1.advanceClock)(handle, step);
+                owed = Math.max(0, owed - step);
+                ran++;
+                for (const system of ordered)
+                    system(handle, step);
+            }
+            if (owed + tolerance >= step) {
+                // Capped with whole steps still owed: drop them, keep the fraction.
+                owed %= step;
+                if (owed + tolerance >= step)
+                    owed = 0;
+            }
+        }
+        finally {
+            handle.scratch.set(key, owed);
+        }
+        return ran;
+    }
+    return Object.freeze({
+        step,
+        maxSteps,
+        key,
+        tick,
+        remainder: read,
+    });
+}

package/dist/cjs/schedule.d.cts

@@ -0,0 +1,69 @@
+import type { WorldHandle } from "./world.cjs";
+/**
+ * One unit of sim work, run once per fixed step.
+ *
+ * `dt` is always the schedule's `step`, never the frame's dt, so a system can
+ * integrate it without knowing the frame rate. Systems that need randomness
+ * should draw from a named substream rather than the handle's positional `rng`,
+ * so adding a system does not shift another system's draws.
+ */
+export type System = (handle: WorldHandle, dt: number) => void;
+export type ScheduleOptions = {
+    /** Seconds of sim time one step represents. Finite and greater than zero. */
+    step: number;
+    /**
+     * The most steps a single `tick` may run. A safe integer of at least 1. Time
+     * owed beyond this is dropped, not carried, so one huge frame dt (a hidden
+     * tab returning after a minute) cannot trigger a catch-up storm.
+     */
+    maxSteps: number;
+    /**
+     * The `scratch` key holding this schedule's accumulator, for callers who want
+     * to namespace it (`"run:schedule"`). Defaults to a key unique to this
+     * schedule. Two schedules given the same key share one accumulator.
+     */
+    key?: string;
+};
+export type Schedule = {
+    readonly step: number;
+    readonly maxSteps: number;
+    /** The `scratch` key holding this schedule's accumulator on a handle. */
+    readonly key: string;
+    /**
+     * Add `frameDt` seconds to `handle`'s accumulator and run every whole step it
+     * now covers, up to `maxSteps`: each step advances the clock by `step`, then
+     * calls every system in order with `dt === step`. Returns how many steps ran.
+     *
+     * A `frameDt` that is negative, `NaN` or infinite counts as `0`, and `0` is a
+     * valid pause: no step runs and the clock does not move. Whole steps beyond
+     * `maxSteps` are dropped; the sub-step remainder is kept.
+     *
+     * If a system throws, the steps that had already started are consumed (the
+     * clock moved for them) and the rest stay owed, so a retry does not replay
+     * time the sim already spent.
+     */
+    tick: (handle: WorldHandle, frameDt: number) => number;
+    /**
+     * Seconds currently owed to the next step, in `[0, step)` between ticks.
+     * Dividing it by `step` gives the interpolation alpha for a renderer drawing
+     * between the previous and current sim state. `0` on a handle that has not
+     * ticked.
+     */
+    remainder: (handle: WorldHandle) => number;
+};
+/**
+ * Build a fixed-step schedule over `systems`, run in the order given.
+ *
+ * ```ts
+ * const schedule = createSchedule([intro, stove, mixer, serving], {
+ *   step: 1 / 60,
+ *   maxSteps: 6,
+ * });
+ * // once per rendered frame, with the frame's dt:
+ * schedule.tick(run, frameDt);
+ * ```
+ *
+ * The systems array is copied; later changes to it do not affect the schedule.
+ */
+export declare function createSchedule(systems: readonly System[], options: ScheduleOptions): Readonly<Schedule>;
+//# sourceMappingURL=schedule.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/schedule.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;AAE/D,MAAM,MAAM,eAAe,GAAG;IAC5B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACvD;;;;;OAKG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,MAAM,CAAC;CAC5C,CAAC;AAeF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,eAAe,GACvB,QAAQ,CAAC,QAAQ,CAAC,CA2FpB"}

package/dist/esm/index.d.ts

@@ -4,6 +4,8 @@ export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt,
 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 { createSchedule } from "./schedule.js";
+export type { Schedule, ScheduleOptions, System } from "./schedule.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":"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,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,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,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,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,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvE,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,7 +1,8 @@
 // koota-kit — thin koota ECS conventions layer.
 //
-// Five modules, also importable as subpaths:
+// Six modules, also importable as subpaths:
 //   ./world    — WorldHandle lifecycle (world + dual-stream rng + clock + scratch)
+//   ./schedule — fixed-step system schedule (accumulator in scratch, step cap)
 //   ./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
@@ -13,5 +14,6 @@
 export { advanceClock, createActions, createSimWorld, destroySimWorld, relation, restoreWorldHeader, snapshotWorld, trait, } from "./world.js";
 export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt, nextU32, pick, restoreLayers, restoreStream, restoreSubstreams, shuffle, snapshotLayers, snapshotStream, snapshotSubstreams, substream, } from "./rng.js";
 export { createMasterSeed, deriveSeed, isMasterSeed, MASTER_SEED_BYTES } from "./seed.js";
+export { createSchedule } from "./schedule.js";
 export { defineEventLog } from "./eventLog.js";
 export { defineTrait } from "./traits/index.js";

package/dist/esm/schedule.d.ts

@@ -0,0 +1,69 @@
+import type { WorldHandle } from "./world.js";
+/**
+ * One unit of sim work, run once per fixed step.
+ *
+ * `dt` is always the schedule's `step`, never the frame's dt, so a system can
+ * integrate it without knowing the frame rate. Systems that need randomness
+ * should draw from a named substream rather than the handle's positional `rng`,
+ * so adding a system does not shift another system's draws.
+ */
+export type System = (handle: WorldHandle, dt: number) => void;
+export type ScheduleOptions = {
+    /** Seconds of sim time one step represents. Finite and greater than zero. */
+    step: number;
+    /**
+     * The most steps a single `tick` may run. A safe integer of at least 1. Time
+     * owed beyond this is dropped, not carried, so one huge frame dt (a hidden
+     * tab returning after a minute) cannot trigger a catch-up storm.
+     */
+    maxSteps: number;
+    /**
+     * The `scratch` key holding this schedule's accumulator, for callers who want
+     * to namespace it (`"run:schedule"`). Defaults to a key unique to this
+     * schedule. Two schedules given the same key share one accumulator.
+     */
+    key?: string;
+};
+export type Schedule = {
+    readonly step: number;
+    readonly maxSteps: number;
+    /** The `scratch` key holding this schedule's accumulator on a handle. */
+    readonly key: string;
+    /**
+     * Add `frameDt` seconds to `handle`'s accumulator and run every whole step it
+     * now covers, up to `maxSteps`: each step advances the clock by `step`, then
+     * calls every system in order with `dt === step`. Returns how many steps ran.
+     *
+     * A `frameDt` that is negative, `NaN` or infinite counts as `0`, and `0` is a
+     * valid pause: no step runs and the clock does not move. Whole steps beyond
+     * `maxSteps` are dropped; the sub-step remainder is kept.
+     *
+     * If a system throws, the steps that had already started are consumed (the
+     * clock moved for them) and the rest stay owed, so a retry does not replay
+     * time the sim already spent.
+     */
+    tick: (handle: WorldHandle, frameDt: number) => number;
+    /**
+     * Seconds currently owed to the next step, in `[0, step)` between ticks.
+     * Dividing it by `step` gives the interpolation alpha for a renderer drawing
+     * between the previous and current sim state. `0` on a handle that has not
+     * ticked.
+     */
+    remainder: (handle: WorldHandle) => number;
+};
+/**
+ * Build a fixed-step schedule over `systems`, run in the order given.
+ *
+ * ```ts
+ * const schedule = createSchedule([intro, stove, mixer, serving], {
+ *   step: 1 / 60,
+ *   maxSteps: 6,
+ * });
+ * // once per rendered frame, with the frame's dt:
+ * schedule.tick(run, frameDt);
+ * ```
+ *
+ * The systems array is copied; later changes to it do not affect the schedule.
+ */
+export declare function createSchedule(systems: readonly System[], options: ScheduleOptions): Readonly<Schedule>;
+//# sourceMappingURL=schedule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/schedule.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;AAE/D,MAAM,MAAM,eAAe,GAAG;IAC5B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACvD;;;;;OAKG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,MAAM,CAAC;CAC5C,CAAC;AAeF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,eAAe,GACvB,QAAQ,CAAC,QAAQ,CAAC,CA2FpB"}

package/dist/esm/schedule.js

@@ -0,0 +1,128 @@
+// Fixed-step system schedule — the loop that turns "a frame passed" into
+// "the sim advanced by whole steps".
+//
+// A simulation that integrates the frame's own dt drifts with the frame rate:
+// a 120 Hz phone and a test that advances three seconds in one call disagree,
+// and anything counted in real time (a save every 0.25 s) lands on different
+// ticks. A fixed-step schedule removes the frame rate from the sim: the frame's
+// dt fills an accumulator, and the sim only ever advances by whole `step`s.
+//
+// The loop is generic sim plumbing, so it lives here and not in the game: it
+// knows nothing about React, a renderer, or what a system does. A renderer's
+// frame callback calls `schedule.tick(handle, dt)` and that is the entire
+// integration. The accumulator lives in the handle's `scratch`, so it dies with
+// the run: a new world starts with nothing owed, and two schedules (or two
+// worlds) never share one.
+import { advanceClock } from "./world.js";
+let nextScheduleId = 0;
+// Keys are process-wide because schedules are declared once at module scope and
+// used on many handles. An explicit key may be shared on purpose; a generated
+// one must stay private to its schedule.
+const claimedKeys = new Set();
+const generatedKeys = new Set();
+// Float accumulation: 432 frames of 1/144 add up to a hair under 3 s, and
+// without a tolerance the sim would owe — and run — one step fewer than the
+// same time delivered at 60 Hz. A billionth of a step is far below anything a
+// frame clock can resolve, so treating "within it" as whole costs nothing.
+const STEP_TOLERANCE = 1e-9;
+/**
+ * Build a fixed-step schedule over `systems`, run in the order given.
+ *
+ * ```ts
+ * const schedule = createSchedule([intro, stove, mixer, serving], {
+ *   step: 1 / 60,
+ *   maxSteps: 6,
+ * });
+ * // once per rendered frame, with the frame's dt:
+ * schedule.tick(run, frameDt);
+ * ```
+ *
+ * The systems array is copied; later changes to it do not affect the schedule.
+ */
+export function createSchedule(systems, options) {
+    if (!Array.isArray(systems)) {
+        throw new TypeError("createSchedule: systems must be an array of functions.");
+    }
+    const { step, maxSteps } = options;
+    if (!Number.isFinite(step) || step <= 0) {
+        throw new RangeError(`createSchedule: step must be finite and greater than zero; received ${step}.`);
+    }
+    if (!Number.isSafeInteger(maxSteps) || maxSteps < 1) {
+        throw new RangeError(`createSchedule: maxSteps must be a safe integer of at least 1; received ${maxSteps}.`);
+    }
+    if (options.key !== undefined && (typeof options.key !== "string" || options.key === "")) {
+        throw new TypeError("createSchedule: key must be a non-empty string when provided.");
+    }
+    const ordered = Object.freeze([...systems]);
+    for (const system of ordered) {
+        if (typeof system !== "function") {
+            throw new TypeError("createSchedule: every system must be a function.");
+        }
+    }
+    let key;
+    if (options.key === undefined) {
+        // Skip any key a caller has already named, so a default never lands on one.
+        do {
+            key = `schedule:${nextScheduleId++}`;
+        } while (claimedKeys.has(key));
+        generatedKeys.add(key);
+    }
+    else {
+        if (generatedKeys.has(options.key)) {
+            throw new TypeError(`createSchedule: key "${options.key}" is already the generated key of another schedule.`);
+        }
+        key = options.key;
+    }
+    claimedKeys.add(key);
+    const tolerance = step * STEP_TOLERANCE;
+    function read(handle) {
+        const stored = handle.scratch.get(key);
+        if (stored === undefined)
+            return 0;
+        if (typeof stored !== "number" || !Number.isFinite(stored) || stored < 0) {
+            throw new TypeError(`createSchedule: scratch key "${key}" already holds something other than a schedule accumulator.`);
+        }
+        return stored;
+    }
+    function tick(handle, frameDt) {
+        const previous = read(handle);
+        // A pause (and any frame dt that counts as 0) runs nothing, even if a
+        // failed tick left whole steps owed: those wait for a frame that moves time.
+        if (!(Number.isFinite(frameDt) && frameDt > 0))
+            return 0;
+        const sum = previous + frameDt;
+        // Two huge finite frames can sum past the double range; saturate instead of
+        // letting Infinity poison the stored accumulator.
+        let owed = Number.isFinite(sum) ? sum : Number.MAX_VALUE;
+        let ran = 0;
+        try {
+            while (owed + tolerance >= step && ran < maxSteps) {
+                // The clock moves first, so a step it refuses (an exhausted clock) is
+                // never debited. After that the step is spent before any system runs:
+                // if one throws, this step's time is gone with the tick it caused.
+                advanceClock(handle, step);
+                owed = Math.max(0, owed - step);
+                ran++;
+                for (const system of ordered)
+                    system(handle, step);
+            }
+            if (owed + tolerance >= step) {
+                // Capped with whole steps still owed: drop them, keep the fraction.
+                owed %= step;
+                if (owed + tolerance >= step)
+                    owed = 0;
+            }
+        }
+        finally {
+            handle.scratch.set(key, owed);
+        }
+        return ran;
+    }
+    return Object.freeze({
+        step,
+        maxSteps,
+        key,
+        tick,
+        remainder: read,
+    });
+}

package/docs/API.md

@@ -174,6 +174,63 @@ const Pose = defineTrait(() => ({ position: { x: 0, y: 0 } }));
 Bare object and array fields are rejected by `SafeSchema` and by the runtime
 guard.
 
+## `schedule`
+
+Import from `koota-kit/schedule` or the root.
+
+```ts
+type System = (handle: WorldHandle, dt: number) => void;
+
+type ScheduleOptions = {
+  step: number;     // seconds per step; finite, > 0
+  maxSteps: number; // safe integer >= 1: most steps one tick may run
+  key?: string;     // scratch key for the accumulator; unique by default
+};
+
+type Schedule = {
+  readonly step: number;
+  readonly maxSteps: number;
+  readonly key: string;
+  tick(handle: WorldHandle, frameDt: number): number;
+  remainder(handle: WorldHandle): number;
+};
+
+function createSchedule(systems: readonly System[], options: ScheduleOptions): Readonly<Schedule>;
+```
+
+`createSchedule` copies `systems` and validates `step`, `maxSteps`, `key` and
+every system before returning; bad configuration throws `TypeError` or
+`RangeError` naming `createSchedule`.
+
+`tick(handle, frameDt)` adds `frameDt` to an accumulator stored in
+`handle.scratch` under `key`, then, while at least one whole `step` is owed and
+fewer than `maxSteps` have run, calls `advanceClock(handle, step)` and then
+every system in order with `dt === step`. It returns the number of steps run.
+Systems read `dt`, never the frame's dt, so the same elapsed time gives the same
+run at any frame rate, provided no single tick owes more than `maxSteps` (the
+excess is dropped, so one long frame and many short ones then differ).
+
+- A `frameDt` that is negative, `NaN` or infinite counts as `0`. `0` is a valid
+  pause: no step runs and the clock does not move, even if a failed tick left
+  whole steps owed; those wait for the next frame that moves time.
+- When `maxSteps` is reached with whole steps still owed, those steps are
+  dropped, not carried. The sub-step fraction is kept, so phase is preserved.
+- Owed time saturates at the largest finite double instead of overflowing.
+- A billionth of a step of tolerance absorbs float drift, so 432 frames of
+  1/144 s run the same 180 steps as 180 frames of 1/60 s.
+- The accumulator lives in `scratch`, so it dies with the world and two
+  handles never share one. A `key` already holding something other than a
+  schedule accumulator throws `TypeError` before the clock moves. Two schedules
+  given the same explicit `key` share one accumulator, but an explicit `key`
+  may not equal another schedule's generated key, and a generated key skips any
+  explicit one.
+- If a system throws, the step it was in is already spent (the clock moved) and
+  the steps not yet started stay owed, so a retry does not replay spent time.
+
+`remainder(handle)` returns the seconds currently owed, in `[0, step)` between
+ticks (`0` on a handle that has not ticked). `remainder / step` is the
+interpolation alpha for a renderer drawing between sim states.
+
 ## `eventLog`
 
 ```ts

package/docs/ARCHITECTURE.md

@@ -11,6 +11,7 @@ traits ───────────────> koota
 seed ─────────────────> (leaf: built-in SHA-256)
 rng ──────────────────> seedrandom + seed
 world ────────────────> koota + rng
+schedule ─────────────> world (advanceClock) + WorldHandle scratch
 eventLog ─────────────> WorldHandle scratch
 react ────────────────> koota/react + react + world (type only)
 index ────────────────> public re-exports only (never react)
@@ -34,6 +35,12 @@ 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.
 
+`schedule` turns a frame's dt into whole fixed steps. Its accumulator lives in
+the handle's scratch map, so time owed dies with the run and two schedules or
+two worlds never share it. It imports no renderer: a frame callback calls
+`tick` and that is the whole integration. The step cap drops excess time rather
+than carrying it, so one huge dt cannot cause a catch-up storm.
+
 `eventLog` uses the handle's scratch map so event lifetime matches world
 lifetime. It does not use a process-global queue.
 
@@ -59,6 +66,10 @@ it reaches `react` or `koota/react`.
 8. A named substream's sequence depends only on its seed and name; creating or
    consuming another substream never shifts it.
 9. Only `koota-kit/react` imports React; every other entry stays React-free.
+10. A schedule's systems only ever see `dt === step`; the same elapsed time
+    delivered at any frame rate runs the same steps in the same order, as long
+    as no single tick owes more than `maxSteps` (beyond that, the excess is
+    dropped by design, so a one-second frame and sixty 1/60 s frames differ).
 
 ## Performance choices
 
@@ -73,8 +84,10 @@ it reaches `react` or `koota/react`.
 ## Intentional limits
 
 - No entity/trait serializer: applications need versioned domain schemas.
-- No scheduler or system runner: Koota's queries/actions remain the execution
-  model.
+- No system graph: `createSchedule` runs an ordered list once per fixed step,
+  and nothing more. There is no dependency resolution, parallelism, or
+  per-system rate; a system that wants a slower cadence counts steps itself.
+  Koota's queries/actions remain the execution model inside each system.
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koota-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Deterministic Koota simulation conventions: world lifecycle, dual RNG streams, safe object traits, and world-scoped event logs.",
   "type": "module",
   "license": "MIT",
@@ -63,6 +63,16 @@
         "default": "./dist/cjs/traits/index.cjs"
       }
     },
+    "./schedule": {
+      "import": {
+        "types": "./dist/esm/schedule.d.ts",
+        "default": "./dist/esm/schedule.js"
+      },
+      "require": {
+        "types": "./dist/cjs/schedule.d.cts",
+        "default": "./dist/cjs/schedule.cjs"
+      }
+    },
     "./eventLog": {
       "import": {
         "types": "./dist/esm/eventLog.d.ts",
@@ -188,6 +198,9 @@
       "traits": [
         "./dist/esm/traits/index.d.ts"
       ],
+      "schedule": [
+        "./dist/esm/schedule.d.ts"
+      ],
       "eventLog": [
         "./dist/esm/eventLog.d.ts"
       ],