koota-kit 0.1.1

package/docs/API.md

@@ -0,0 +1,119 @@
+# API reference
+
+All functions and types are exported from `koota-kit`. The
+module-specific import paths shown below can reduce coupling in larger
+codebases.
+
+## `world`
+
+### `createSimWorld(seeds)`
+
+```ts
+function createSimWorld(seeds: RngSeeds): WorldHandle;
+```
+
+Creates a Koota `World`, two seeded RNG streams, immutable copied seeds, a
+zeroed clock, and an empty scratch map. Seeds must be strings or finite
+numbers. Validation happens before the Koota world is allocated.
+
+### `destroySimWorld(handle)`
+
+```ts
+function destroySimWorld(handle: WorldHandle): void;
+```
+
+Clears scratch state and destroys the Koota world if it is still active. The
+operation is idempotent.
+
+### `advanceClock(handle, dt)`
+
+```ts
+function advanceClock(handle: WorldHandle, dt: number): void;
+```
+
+Advances `tickIndex` by one and adds `dt` to `simSeconds`. `dt` must be finite
+and non-negative. A zero-duration tick is allowed. Overflow and corrupted clock
+values raise `RangeError` without changing the clock.
+
+### `snapshotWorld(handle)` / `restoreWorldHeader(handle, snapshot)`
+
+```ts
+function snapshotWorld(handle: WorldHandle): WorldSnapshot;
+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.
+
+### Koota exports
+
+`createActions`, `relation`, and `trait` are re-exported so simulation code can
+keep its Koota imports at one boundary. `Entity` and `World` are exported as
+types.
+
+## `rng`
+
+```ts
+type RngSeeds = {
+  readonly gen: string | number;
+  readonly events: string | number;
+};
+
+function createRng(seeds: RngSeeds): RngLayers;
+function nextU32(stream: RngStream): number;
+function nextFloat(stream: RngStream): number;
+function nextInt(stream: RngStream, minInclusive: number, maxExclusive: number): number;
+function chance(stream: RngStream, probability: number): boolean;
+function snapshotStream(stream: RngStream): RngStreamSnapshot;
+function restoreStream(snapshot: RngStreamSnapshot): RngStream;
+function snapshotLayers(layers: RngLayers): RngLayersSnapshot;
+function restoreLayers(snapshot: RngLayersSnapshot): RngLayers;
+```
+
+- `nextU32` returns an unsigned 32-bit integer.
+- `nextFloat` returns a value in `[0, 1)`.
+- `nextInt` uses half-open bounds and exactly one float draw after validation.
+- `chance` consumes one draw for every valid probability, including `0` and
+  `1`, keeping later draw positions predictable.
+- Restore functions reject malformed ARC4 state and clone accepted state so a
+  snapshot can seed multiple independent replays.
+
+## `traits`
+
+```ts
+function defineTrait<S extends Schema>(schema: S & SafeSchema<S>): Trait<Norm<S>>;
+```
+
+Pass primitive fields directly. Wrap each object- or array-valued field in a
+factory, or use a whole-trait factory:
+
+```ts
+const Health = defineTrait({ value: 100 });
+const Path = defineTrait({ points: () => [] as Array<{ x: number; y: number }> });
+const Pose = defineTrait(() => ({ position: { x: 0, y: 0 } }));
+```
+
+Bare object and array fields are rejected by `SafeSchema` and by the runtime
+guard.
+
+## `eventLog`
+
+```ts
+type EventLog<T> = {
+  readonly key: string;
+  push(handle: WorldHandle, event: T): void;
+  drain(handle: WorldHandle): T[];
+  peek(handle: WorldHandle): readonly T[];
+  clear(handle: WorldHandle): void;
+  size(handle: WorldHandle): number;
+};
+
+function defineEventLog<T>(key: string): EventLog<T>;
+```
+
+Logs are created once at module scope but store their arrays in each handle's
+scratch map. `drain` truncates the live array in place so an existing internal
+reference is not orphaned. Empty reads do not create a scratch entry. `peek`
+returns a detached array; `size` does not allocate.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,57 @@
+# Architecture
+
+koota-kit is intentionally a convention layer, not an abstraction over every
+Koota capability. Consumers still use Koota entities, traits, relations,
+queries, and actions directly.
+
+## Module boundaries
+
+```text
+traits ───────────────> koota
+rng ──────────────────> seedrandom
+world ────────────────> koota + rng
+eventLog ─────────────> WorldHandle scratch
+index ────────────────> public re-exports only
+```
+
+`traits` is a leaf module: it imports Koota but no sibling runtime module. This
+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.
+
+`world` owns allocation, teardown, time, and facade-owned persistence. It does
+not own application entity serialization.
+
+`eventLog` uses the handle's scratch map so event lifetime matches world
+lifetime. It does not use a process-global queue.
+
+## Invariants
+
+1. Seed values on a handle are copied and frozen at creation.
+2. World-generation and runtime-event draws never share a PRNG instance.
+3. Invalid draw parameters do not advance a stream.
+4. Restoring a header is atomic from the caller's perspective.
+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.
+
+## Performance choices
+
+- RNG draws delegate directly to seedrandom after one small validation step.
+- Snapshots clone the 256-byte permutation explicitly instead of serializing
+  through JSON.
+- Event logs allocate on first push, leave scratch untouched for empty reads,
+  truncate in place on drain, and expose a non-allocating `size` operation.
+- The package is not bundled. ESM and CommonJS outputs preserve small subpath
+  entry points and let application bundlers tree-shake normally.
+
+## 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 automatic derived-key hashing: the application owns stable domain keys.
+- No multi-consumer queue semantics: publish separate logs when two systems
+  must independently consume the same fact.

package/docs/assets/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill-rule="evenodd" d="M81 36 64 0 47 36l-1 2-9-10a6 6 0 0 0-9 9l10 10h-2L0 64l36 17h2L28 91a6 6 0 1 0 9 9l9-10 1 2 17 36 17-36v-2l9 10a6 6 0 1 0 9-9l-9-9 2-1 36-17-36-17-2-1 9-9a6 6 0 1 0-9-9l-9 10v-2Zm-17 2-2 5c-4 8-11 15-19 19l-5 2 5 2c8 4 15 11 19 19l2 5 2-5c4-8 11-15 19-19l5-2-5-2c-8-4-15-11-19-19l-2-5Z" clip-rule="evenodd"/><path d="M118 19a6 6 0 0 0-9-9l-3 3a6 6 0 1 0 9 9l3-3Zm-96 4c-2 2-6 2-9 0l-3-3a6 6 0 1 1 9-9l3 3c3 2 3 6 0 9Zm0 82c-2-2-6-2-9 0l-3 3a6 6 0 1 0 9 9l3-3c3-2 3-6 0-9Zm96 4a6 6 0 0 1-9 9l-3-3a6 6 0 1 1 9-9l3 3Z"/></svg>

package/docs/changelog.md

@@ -0,0 +1,13 @@
+---
+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.

package/docs/contributing.md

@@ -0,0 +1,28 @@
+---
+title: Contributing
+description: Set up koota-kit, validate a change, and contribute through the protected workflow.
+---
+
+## Local workflow
+
+```sh
+mise install
+pnpm install --frozen-lockfile
+pnpm verify
+pnpm docs:build
+```
+
+`pnpm verify` is the library gate: Biome, Markdown linting, strict TypeScript,
+100% coverage, dual-format builds, runnable examples, package validation, and
+a clean-consumer runtime check. `pnpm docs:build` validates and renders the
+Sourcey site.
+
+Branch from `main`, make a focused Conventional Commit, open an upstream pull
+request, and keep the branch current by merging `main` into it when necessary.
+The protected path uses automated checks rather than a routine human approval;
+merge commits preserve the constituent history. Do not hand-edit versions or
+`CHANGELOG.md`: Release Please owns them.
+
+Read the repository [contribution guide](https://github.com/jbcom/koota-kit/blob/main/CONTRIBUTING.md)
+and [agent instructions](https://github.com/jbcom/koota-kit/blob/main/AGENTS.md)
+before changing public APIs.

package/examples/basic.mjs

@@ -0,0 +1,27 @@
+import {
+  advanceClock,
+  createSimWorld,
+  defineEventLog,
+  defineTrait,
+  destroySimWorld,
+  nextInt,
+  snapshotWorld,
+} from "koota-kit";
+
+const Position = defineTrait({ x: 0, y: 0 });
+const moves = defineEventLog("movement:completed");
+const sim = createSimWorld({ gen: "map-42", events: "run-1" });
+
+try {
+  const scout = sim.world.spawn(Position({ x: 4, y: 9 }));
+  advanceClock(sim, 1 / 60);
+
+  const distance = nextInt(sim.rng.events, 1, 5);
+  scout.set(Position, ({ x, y }) => ({ x: x + distance, y }));
+  moves.push(sim, { entity: Number(scout), distance });
+
+  const saveHeader = snapshotWorld(sim);
+  console.log({ position: scout.get(Position), events: moves.drain(sim), saveHeader });
+} finally {
+  destroySimWorld(sim);
+}

package/examples/commonjs.cjs

@@ -0,0 +1,8 @@
+const { createSimWorld, destroySimWorld, nextU32 } = require("koota-kit");
+
+const sim = createSimWorld({ gen: "commonjs", events: "run-1" });
+try {
+  console.log({ firstEventDraw: nextU32(sim.rng.events) });
+} finally {
+  destroySimWorld(sim);
+}

package/package.json

@@ -0,0 +1,173 @@
+{
+  "name": "koota-kit",
+  "version": "0.1.1",
+  "description": "Deterministic Koota simulation conventions: world lifecycle, dual RNG streams, safe object traits, and world-scoped event logs.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "sideEffects": false,
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./world": {
+      "import": {
+        "types": "./dist/esm/world.d.ts",
+        "default": "./dist/esm/world.js"
+      },
+      "require": {
+        "types": "./dist/cjs/world.d.cts",
+        "default": "./dist/cjs/world.cjs"
+      }
+    },
+    "./rng": {
+      "import": {
+        "types": "./dist/esm/rng.d.ts",
+        "default": "./dist/esm/rng.js"
+      },
+      "require": {
+        "types": "./dist/cjs/rng.d.cts",
+        "default": "./dist/cjs/rng.cjs"
+      }
+    },
+    "./traits": {
+      "import": {
+        "types": "./dist/esm/traits/index.d.ts",
+        "default": "./dist/esm/traits/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/traits/index.d.cts",
+        "default": "./dist/cjs/traits/index.cjs"
+      }
+    },
+    "./eventLog": {
+      "import": {
+        "types": "./dist/esm/eventLog.d.ts",
+        "default": "./dist/esm/eventLog.js"
+      },
+      "require": {
+        "types": "./dist/cjs/eventLog.d.cts",
+        "default": "./dist/cjs/eventLog.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "dist",
+    "docs/API.md",
+    "docs/ARCHITECTURE.md",
+    "docs/assets",
+    "examples"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "examples:check": "node examples/basic.mjs && node examples/commonjs.cjs",
+    "lint:docs": "markdownlint-cli2 README.md CONTRIBUTING.md SECURITY.md CODE_OF_CONDUCT.md CHANGELOG.md AGENTS.md \"docs/**/*.md\" \"!docs/node_modules/**\" \"!docs/dist/**\" \"!docs/superpowers/**\" .github/PULL_REQUEST_TEMPLATE.md",
+    "package:check": "publint && attw --pack . && node scripts/verify-package.mjs",
+    "verify": "pnpm run lint && pnpm run lint:docs && pnpm run typecheck && pnpm run coverage && pnpm run build && pnpm run examples:check && pnpm run package:check",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "prepack": "node scripts/build.mjs",
+    "docs:dev": "pnpm --filter koota-kit-docs dev",
+    "docs:build": "pnpm --filter koota-kit-docs build",
+    "docs:check": "pnpm --filter koota-kit-docs check",
+    "prepare": "simple-git-hooks"
+  },
+  "dependencies": {
+    "@types/seedrandom": "^3.0.8",
+    "seedrandom": "^3.0.5"
+  },
+  "peerDependencies": {
+    "koota": "^0.6.6"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@biomejs/biome": "^2.5.5",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@vitest/coverage-v8": "^3.2.7",
+    "koota": "^0.6.6",
+    "lint-staged": "^17.3.0",
+    "markdownlint-cli2": "^0.23.2",
+    "publint": "^0.3.24",
+    "simple-git-hooks": "^2.13.1",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm exec lint-staged",
+    "commit-msg": "pnpm exec commitlint --edit $1"
+  },
+  "lint-staged": {
+    "*.{ts,js,mjs,cjs,json}": [
+      "biome check --write --no-errors-on-unmatched"
+    ],
+    "!(docs/superpowers/**)*.md": [
+      "markdownlint-cli2"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jbcom/koota-kit.git"
+  },
+  "packageManager": "pnpm@11.23.0+sha512.f00082e5b283a199b74e079da28d155c008fe232f44c8a06ea7ddfa014ecf719fc362f790ecc67b28106ddac2afb24c49a9a079159da560b2ce7d1e98efd11af",
+  "bugs": {
+    "url": "https://github.com/jbcom/koota-kit/issues"
+  },
+  "homepage": "https://github.com/jbcom/koota-kit#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "typesVersions": {
+    "*": {
+      "world": [
+        "./dist/esm/world.d.ts"
+      ],
+      "rng": [
+        "./dist/esm/rng.d.ts"
+      ],
+      "traits": [
+        "./dist/esm/traits/index.d.ts"
+      ],
+      "eventLog": [
+        "./dist/esm/eventLog.d.ts"
+      ],
+      "*": [
+        "./dist/esm/index.d.ts"
+      ]
+    }
+  },
+  "author": "Jon Bogaty <jon@jonbogaty.com>",
+  "keywords": [
+    "koota",
+    "ecs",
+    "deterministic",
+    "rng",
+    "seedrandom",
+    "game-dev",
+    "simulation",
+    "procedural-generation",
+    "replay"
+  ]
+}