@its-not-rocket-science/ananke 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -10,6 +10,20 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- **CE-16 · Modding Support** (`src/modding.ts`)
+  - Layer 1 — `hashMod(json)`: deterministic FNV-1a fingerprint (8-char hex) for any
+    parsed JSON mod file; canonical key-sorted serialisation ensures order-independence.
+  - Layer 2 — Post-tick behavior hooks: `registerPostTickHook / unregisterPostTickHook /
+    runPostTickHooks / listPostTickHooks / clearPostTickHooks`; hooks fire after
+    `stepWorld`, are purely observational (logging, analytics, renderer updates).
+  - Layer 3 — AI behavior node registry: `registerBehaviorNode / unregisterBehaviorNode /
+    getBehaviorNode / listBehaviorNodes / clearBehaviorNodes`; custom `BehaviorNode`
+    factories registered by id for scenario and behavior-tree composition.
+  - Session fingerprint: `computeModManifest(catalogIds)` returns sorted id lists and a
+    single fingerprint covering all three layers for multiplayer client validation.
+  - `clearAllMods()` resets hooks and behavior nodes (catalog unchanged).
+  - 42 tests in `test/modding.test.ts`; exported via `src/index.ts`.
+
 - **CE-14 · Socio-Economic Campaign Layer → Stable Promotion**
   - Promote `stepPolityDay`, `declareWar`, `makePeace`, `areAtWar`,
     `createPolity`, `createPolityRegistry`, `Polity`, `PolityRegistry`,
@@ -84,6 +98,18 @@ Adding new **optional** fields to these interfaces is never a breaking change.
 
 ---
 
+## [0.1.10] — 2026-03-24
+
+  ### Added
+
+  - **CE-16 · Modding Support — HashMod, Post-tick Hooks, Behaviour Node Registry** (`src/parallel.ts`)
+    - Three-layer modding contract: FNV-1a data fingerprinting, observational
+      post-tick hooks, and named AI behavior node factories. computeModManifest()
+      provides a single session fingerprint for multiplayer client validation.
+    - exported via src/index.ts.
+
+---
+
 ## [0.1.8] — 2026-03-24
 
   ### Added

package/dist/src/index.d.ts

@@ -23,3 +23,4 @@ export * from "./sim/cover.js";
 export * from "./sim/ai/behavior-trees.js";
 export * from "./snapshot.js";
 export * from "./parallel.js";
+export * from "./modding.js";

package/dist/src/index.js

@@ -32,3 +32,4 @@ export * from "./sim/cover.js"; // CE-15: CoverSegment, computeCoverProtection()
 export * from "./sim/ai/behavior-trees.js"; // CE-10: BehaviorNode, FlankTarget, RetreatTo, ProtectAlly, GuardPosition, HealTarget, Sequence, Fallback
 export * from "./snapshot.js"; // CE-9: diffWorldState(), applyDiff(), packDiff(), unpackDiff(), WorldStateDiff
 export * from "./parallel.js"; // CE-7: partitionWorld(), mergePartitions(), detectBoundaryPairs(), assignEntitiesToPartitions()
+export * from "./modding.js"; // CE-16: hashMod(), registerPostTickHook(), runPostTickHooks(), registerBehaviorNode(), computeModManifest()

package/dist/src/modding.d.ts

@@ -0,0 +1,137 @@
+/**
+ * CE-16 — Modding Support
+ *
+ * Three-layer modding contract built on CE-12 (data-driven catalog) and the stable API:
+ *
+ * **Layer 1 — Data mod fingerprinting**
+ *   `hashMod(json)` produces a deterministic 8-char hex fingerprint of any parsed JSON
+ *   mod file.  The network replication layer (CE-11) compares fingerprints across clients
+ *   to guarantee all participants use identical mod definitions.
+ *
+ * **Layer 2 — Post-tick behavior hooks**
+ *   `registerPostTickHook(id, fn)` registers an observer callback that the host fires
+ *   after each `stepWorld` call via `runPostTickHooks(world)`.  Hooks are purely
+ *   observational — they MUST NOT mutate `WorldState` during the call.  Because they run
+ *   outside the kernel path they cannot break determinism.
+ *
+ * **Layer 3 — AI behavior node overrides**
+ *   `registerBehaviorNode(id, factory)` installs a named factory for custom
+ *   `BehaviorNode` implementations.  `loadScenario` (CE-3) can reference them by id in
+ *   scenario JSON.  AI overrides require explicit host opt-in.
+ *
+ * **Session fingerprint**
+ *   `computeModManifest()` returns a single fingerprint covering all three registries,
+ *   suitable for multiplayer session validation.
+ */
+import type { WorldState } from "./sim/world.js";
+import type { BehaviorNode } from "./sim/ai/behavior-trees.js";
+/**
+ * Produce a deterministic 8-character hex fingerprint for a parsed JSON mod
+ * object (archetype, weapon, armour, or any CE-12 catalog entry).
+ *
+ * Keys are sorted before hashing so `{ a:1, b:2 }` and `{ b:2, a:1 }` produce
+ * the same fingerprint.  The result is stable across JS engines and Node versions
+ * as long as the JSON content is identical.
+ *
+ * Use `computeModManifest()` to fingerprint the full active mod set for session
+ * validation.
+ */
+export declare function hashMod(json: unknown): string;
+export type PostTickHook = (world: WorldState) => void;
+/**
+ * Register an observational callback that fires after each `stepWorld` tick.
+ *
+ * The host is responsible for calling `runPostTickHooks(world)` immediately after
+ * `stepWorld(world, cmds, ctx)`.  Hooks MUST NOT mutate `WorldState`; they are
+ * intended for analytics, logging, renderer updates, and network broadcast.
+ *
+ * Re-registering an existing id overwrites the previous hook.
+ */
+export declare function registerPostTickHook(id: string, fn: PostTickHook): void;
+/**
+ * Remove a previously registered post-tick hook.
+ * Returns `true` if the hook existed and was removed.
+ */
+export declare function unregisterPostTickHook(id: string): boolean;
+/**
+ * Invoke all registered post-tick hooks in registration order.
+ *
+ * Call this immediately after `stepWorld`:
+ * ```typescript
+ * stepWorld(world, cmds, ctx);
+ * runPostTickHooks(world);
+ * ```
+ *
+ * Errors thrown by individual hooks are caught and re-thrown after all hooks
+ * have been attempted, to avoid silently dropping subsequent hooks.
+ */
+export declare function runPostTickHooks(world: WorldState): void;
+/** Return the ids of all registered post-tick hooks in registration order. */
+export declare function listPostTickHooks(): string[];
+/** Remove all post-tick hooks (useful for testing and hot-reload scenarios). */
+export declare function clearPostTickHooks(): void;
+export type BehaviorNodeFactory = (...args: unknown[]) => BehaviorNode;
+/**
+ * Register a named factory for a custom `BehaviorNode` implementation.
+ *
+ * The factory will be looked up by id when `loadScenario` (CE-3) encounters an
+ * `"aiOverride"` reference in scenario JSON, or when a host builds a behavior
+ * tree programmatically:
+ *
+ * ```typescript
+ * registerBehaviorNode("patrol_guard", (waypointX, waypointY) =>
+ *   PatrolGuard(Number(waypointX), Number(waypointY))
+ * );
+ * const factory = getBehaviorNode("patrol_guard");
+ * const node = factory?.(1000, 2000);
+ * ```
+ *
+ * **Deterministic multiplayer**: AI overrides affect simulation output.  All
+ * clients must register the same behavior nodes (verified via `computeModManifest`)
+ * before joining a session.
+ *
+ * Re-registering an existing id overwrites the previous factory.
+ */
+export declare function registerBehaviorNode(id: string, factory: BehaviorNodeFactory): void;
+/**
+ * Remove a previously registered behavior node factory.
+ * Returns `true` if the factory existed and was removed.
+ */
+export declare function unregisterBehaviorNode(id: string): boolean;
+/**
+ * Look up a registered behavior node factory by id.
+ * Returns `undefined` if not found.
+ */
+export declare function getBehaviorNode(id: string): BehaviorNodeFactory | undefined;
+/** Return the ids of all registered behavior node factories in registration order. */
+export declare function listBehaviorNodes(): string[];
+/** Remove all behavior node factories (useful for testing and hot-reload scenarios). */
+export declare function clearBehaviorNodes(): void;
+export interface ModManifest {
+    /** Sorted list of all data mod ids currently in the CE-12 catalog. */
+    dataIds: string[];
+    /** Sorted list of all registered post-tick hook ids. */
+    hookIds: string[];
+    /** Sorted list of all registered behavior node ids. */
+    behaviorIds: string[];
+    /**
+     * Single fingerprint covering all three id lists.
+     * Two clients are mod-compatible iff their `fingerprint` values match.
+     */
+    fingerprint: string;
+}
+/**
+ * Compute a session manifest covering all active mods (CE-12 catalog entries,
+ * post-tick hooks, and AI behavior node overrides).
+ *
+ * The `fingerprint` is a deterministic 8-char hex string suitable for
+ * multiplayer session comparison.  Clients are considered mod-compatible iff
+ * their fingerprints match.
+ *
+ * @param catalogIds Sorted list of CE-12 catalog entry ids (pass `listCatalog()`).
+ *   Provided as a parameter to keep this module free of a circular dependency
+ *   on `catalog.ts`.
+ */
+export declare function computeModManifest(catalogIds?: string[]): ModManifest;
+/** Remove all hooks and behavior node factories. Does not affect the CE-12 catalog. */
+export declare function clearAllMods(): void;

package/dist/src/modding.js

@@ -0,0 +1,188 @@
+/**
+ * CE-16 — Modding Support
+ *
+ * Three-layer modding contract built on CE-12 (data-driven catalog) and the stable API:
+ *
+ * **Layer 1 — Data mod fingerprinting**
+ *   `hashMod(json)` produces a deterministic 8-char hex fingerprint of any parsed JSON
+ *   mod file.  The network replication layer (CE-11) compares fingerprints across clients
+ *   to guarantee all participants use identical mod definitions.
+ *
+ * **Layer 2 — Post-tick behavior hooks**
+ *   `registerPostTickHook(id, fn)` registers an observer callback that the host fires
+ *   after each `stepWorld` call via `runPostTickHooks(world)`.  Hooks are purely
+ *   observational — they MUST NOT mutate `WorldState` during the call.  Because they run
+ *   outside the kernel path they cannot break determinism.
+ *
+ * **Layer 3 — AI behavior node overrides**
+ *   `registerBehaviorNode(id, factory)` installs a named factory for custom
+ *   `BehaviorNode` implementations.  `loadScenario` (CE-3) can reference them by id in
+ *   scenario JSON.  AI overrides require explicit host opt-in.
+ *
+ * **Session fingerprint**
+ *   `computeModManifest()` returns a single fingerprint covering all three registries,
+ *   suitable for multiplayer session validation.
+ */
+// ── Internal: FNV-1a 32-bit hash ──────────────────────────────────────────────
+/** FNV-1a 32-bit hash over a UTF-16 code-unit string. */
+function fnv1a32(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) | 0;
+    }
+    return h >>> 0;
+}
+/** Serialize any JSON-compatible value in canonical (key-sorted) form. */
+function canonicalJson(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return "[" + v.map(canonicalJson).join(",") + "]";
+    const obj = v;
+    return "{" + Object.keys(obj).sort().map(k => JSON.stringify(k) + ":" + canonicalJson(obj[k])).join(",") + "}";
+}
+// ── Layer 1: Data mod fingerprinting ─────────────────────────────────────────
+/**
+ * Produce a deterministic 8-character hex fingerprint for a parsed JSON mod
+ * object (archetype, weapon, armour, or any CE-12 catalog entry).
+ *
+ * Keys are sorted before hashing so `{ a:1, b:2 }` and `{ b:2, a:1 }` produce
+ * the same fingerprint.  The result is stable across JS engines and Node versions
+ * as long as the JSON content is identical.
+ *
+ * Use `computeModManifest()` to fingerprint the full active mod set for session
+ * validation.
+ */
+export function hashMod(json) {
+    return fnv1a32(canonicalJson(json)).toString(16).padStart(8, "0");
+}
+const _hooks = new Map();
+/**
+ * Register an observational callback that fires after each `stepWorld` tick.
+ *
+ * The host is responsible for calling `runPostTickHooks(world)` immediately after
+ * `stepWorld(world, cmds, ctx)`.  Hooks MUST NOT mutate `WorldState`; they are
+ * intended for analytics, logging, renderer updates, and network broadcast.
+ *
+ * Re-registering an existing id overwrites the previous hook.
+ */
+export function registerPostTickHook(id, fn) {
+    if (!id)
+        throw new Error("Hook id must be a non-empty string");
+    _hooks.set(id, fn);
+}
+/**
+ * Remove a previously registered post-tick hook.
+ * Returns `true` if the hook existed and was removed.
+ */
+export function unregisterPostTickHook(id) {
+    return _hooks.delete(id);
+}
+/**
+ * Invoke all registered post-tick hooks in registration order.
+ *
+ * Call this immediately after `stepWorld`:
+ * ```typescript
+ * stepWorld(world, cmds, ctx);
+ * runPostTickHooks(world);
+ * ```
+ *
+ * Errors thrown by individual hooks are caught and re-thrown after all hooks
+ * have been attempted, to avoid silently dropping subsequent hooks.
+ */
+export function runPostTickHooks(world) {
+    const errors = [];
+    for (const fn of _hooks.values()) {
+        try {
+            fn(world);
+        }
+        catch (e) {
+            errors.push(e);
+        }
+    }
+    if (errors.length > 0)
+        throw errors[0];
+}
+/** Return the ids of all registered post-tick hooks in registration order. */
+export function listPostTickHooks() {
+    return [..._hooks.keys()];
+}
+/** Remove all post-tick hooks (useful for testing and hot-reload scenarios). */
+export function clearPostTickHooks() {
+    _hooks.clear();
+}
+const _behaviorNodes = new Map();
+/**
+ * Register a named factory for a custom `BehaviorNode` implementation.
+ *
+ * The factory will be looked up by id when `loadScenario` (CE-3) encounters an
+ * `"aiOverride"` reference in scenario JSON, or when a host builds a behavior
+ * tree programmatically:
+ *
+ * ```typescript
+ * registerBehaviorNode("patrol_guard", (waypointX, waypointY) =>
+ *   PatrolGuard(Number(waypointX), Number(waypointY))
+ * );
+ * const factory = getBehaviorNode("patrol_guard");
+ * const node = factory?.(1000, 2000);
+ * ```
+ *
+ * **Deterministic multiplayer**: AI overrides affect simulation output.  All
+ * clients must register the same behavior nodes (verified via `computeModManifest`)
+ * before joining a session.
+ *
+ * Re-registering an existing id overwrites the previous factory.
+ */
+export function registerBehaviorNode(id, factory) {
+    if (!id)
+        throw new Error("Behavior node id must be a non-empty string");
+    _behaviorNodes.set(id, factory);
+}
+/**
+ * Remove a previously registered behavior node factory.
+ * Returns `true` if the factory existed and was removed.
+ */
+export function unregisterBehaviorNode(id) {
+    return _behaviorNodes.delete(id);
+}
+/**
+ * Look up a registered behavior node factory by id.
+ * Returns `undefined` if not found.
+ */
+export function getBehaviorNode(id) {
+    return _behaviorNodes.get(id);
+}
+/** Return the ids of all registered behavior node factories in registration order. */
+export function listBehaviorNodes() {
+    return [..._behaviorNodes.keys()];
+}
+/** Remove all behavior node factories (useful for testing and hot-reload scenarios). */
+export function clearBehaviorNodes() {
+    _behaviorNodes.clear();
+}
+/**
+ * Compute a session manifest covering all active mods (CE-12 catalog entries,
+ * post-tick hooks, and AI behavior node overrides).
+ *
+ * The `fingerprint` is a deterministic 8-char hex string suitable for
+ * multiplayer session comparison.  Clients are considered mod-compatible iff
+ * their fingerprints match.
+ *
+ * @param catalogIds Sorted list of CE-12 catalog entry ids (pass `listCatalog()`).
+ *   Provided as a parameter to keep this module free of a circular dependency
+ *   on `catalog.ts`.
+ */
+export function computeModManifest(catalogIds = []) {
+    const dataIds = [...catalogIds].sort();
+    const hookIds = listPostTickHooks().slice().sort();
+    const behaviorIds = listBehaviorNodes().slice().sort();
+    const combined = JSON.stringify({ dataIds, hookIds, behaviorIds });
+    const fingerprint = fnv1a32(combined).toString(16).padStart(8, "0");
+    return { dataIds, hookIds, behaviorIds, fingerprint };
+}
+/** Remove all hooks and behavior node factories. Does not affect the CE-12 catalog. */
+export function clearAllMods() {
+    _hooks.clear();
+    _behaviorNodes.clear();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",