@jgengine/core 0.10.0 → 0.11.0

package/README.md

@@ -10,4 +10,4 @@ import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
 
 The renderer-free world layer includes a Gerstner `waterSurface` (`world/water`) and a seeded `generateBuilding` kit (`world/buildings`), whose wave math and building component vocabulary were shaped from **[achrefelouafi](https://github.com/achrefelouafi)**'s MIT [OceanThreejs](https://github.com/achrefelouafi/OceanThreejs) and [BuildingGeneratorThreeJS](https://github.com/achrefelouafi/BuildingGeneratorThreeJS) — see [CREDITS.md](../../CREDITS.md).
 
-Part of [JGengine](https://github.com/Noisemaker111/jgengine). AGPL-3.0-only.
+Part of [JGengine](https://github.com/Noisemaker111/jgengine). Apache-2.0.

package/dist/ai/crowd.d.ts

@@ -1,4 +1,11 @@
 import type { NavGrid, NavPoint } from "../nav/navGrid.js";
+/**
+ * Deterministic 2D offset uniformly within a disc of `radius`, stable per `id` — so a crowd converging
+ * on one target (a flank point, a rally banner, a boss) fans out to distinct spots instead of all
+ * stacking on the same coordinate. Same `id` always yields the same offset, no per-entity state to store.
+  * @internal
+  */
+export declare function spreadOffset(id: string, radius: number): readonly [number, number];
 export interface FlowFieldOptions {
     clearance?: number;
     congestion?: (col: number, row: number) => number;
@@ -11,6 +18,7 @@ export interface FlowField {
     direction(point: NavPoint): NavPoint;
     next(point: NavPoint): NavPoint | null;
 }
+/** @internal */
 export declare function computeFlowField(grid: NavGrid, goals: readonly NavPoint[], options?: FlowFieldOptions): FlowField;
 export interface CrowdField {
     enter(point: NavPoint): void;
@@ -20,6 +28,7 @@ export interface CrowdField {
     penalty(weight?: number): (col: number, row: number) => number;
     reset(): void;
 }
+/** @internal */
 export declare function createCrowdField(grid: NavGrid): CrowdField;
 export interface Poi {
     id: string;
@@ -33,4 +42,50 @@ export interface SelectPoiOptions {
     distanceBias?: number;
     distance?: (from: NavPoint, poi: Poi) => number;
 }
+/** @internal */
 export declare function selectPoi(pois: readonly Poi[], from: NavPoint, options: SelectPoiOptions): Poi | null;
+/** A many-agent visitor's current step of the seek→travel→arrive→dwell→depart loop. */
+export type VisitorPhase = "seeking" | "traveling" | "dwelling" | "departing" | "done";
+/** One tick's result from a {@link VisitorLoop}: current phase, where to steer, and which POI it concerns. */
+export interface VisitorStep {
+    phase: VisitorPhase;
+    /** Where to steer this tick (feed `scene.entity.moveToward`/`moveTowardCommit`), or `null` once `done` or stuck `seeking` with no eligible POI. */
+    target: NavPoint | null;
+    poiId: string | null;
+}
+/** Config for {@link createVisitorLoop}: the POI catalog, dwell duration, and exit point every agent shares. */
+export interface VisitorLoopOptions {
+    pois: readonly Poi[];
+    /** How long (ms, sim time) a visitor lingers once it arrives at a POI. */
+    dwellMs: (poi: Poi) => number;
+    /** Where a visitor heads once its dwell ends — a fixed exit/despawn point, or one resolved per agent (multiple gates). */
+    exitPoint: NavPoint | ((agentId: string) => NavPoint);
+    /** Distance under which "traveling"/"departing" counts as arrived. Default 1. */
+    arriveRadius?: number;
+    occupancy?: (poiId: string) => number;
+    distanceBias?: number;
+    distance?: (from: NavPoint, poi: Poi) => number;
+    /** Fires once, on the traveling→dwelling transition (e.g. `crowdField.enter(poi.point)`). */
+    onArrive?: (agentId: string, poiId: string) => void;
+    /** Fires once, on the dwelling→departing transition (e.g. `crowdField.leave(poi.point)`). */
+    onDepart?: (agentId: string, poiId: string) => void;
+}
+/** Handle returned by {@link createVisitorLoop}: per-agent seek/travel/dwell/depart state machine. */
+export interface VisitorLoop {
+    /** Registers `agentId` in the `"seeking"` phase; `tick` also auto-spawns on first call. */
+    spawn(agentId: string): VisitorStep;
+    /** Advances one agent by `dtMs` from its current `position`; `roll()` feeds `selectPoi`'s weighted pick. */
+    tick(agentId: string, position: NavPoint, dtMs: number, roll: () => number): VisitorStep;
+    get(agentId: string): VisitorStep | null;
+    remove(agentId: string): void;
+    clear(): void;
+}
+/**
+ * A many-agent seek→travel→arrive→dwell→depart loop over weighted points of interest (park visitors,
+ * shoppers, tavern patrons) — `ai/crowd`'s `selectPoi` covers only the weighted-pick step; this owns
+ * the per-agent phase machine around it so the caller only supplies positions and drives movement.
+ *
+ * @capability visitor-loop many-agent seek/travel/dwell/depart state machine over weighted POIs
+  * @internal
+  */
+export declare function createVisitorLoop(options: VisitorLoopOptions): VisitorLoop;

package/dist/ai/crowd.js

@@ -1,4 +1,17 @@
+import { seededRng } from "../random/rng.js";
 const SQRT2 = Math.SQRT2;
+/**
+ * Deterministic 2D offset uniformly within a disc of `radius`, stable per `id` — so a crowd converging
+ * on one target (a flank point, a rally banner, a boss) fans out to distinct spots instead of all
+ * stacking on the same coordinate. Same `id` always yields the same offset, no per-entity state to store.
+  * @internal
+  */
+export function spreadOffset(id, radius) {
+    const rng = seededRng(id);
+    const angle = rng() * Math.PI * 2;
+    const r = Math.sqrt(rng()) * radius;
+    return [Math.cos(angle) * r, Math.sin(angle) * r];
+}
 function heapPush(heap, node) {
     heap.push(node);
     let i = heap.length - 1;
@@ -46,6 +59,7 @@ function passableWithClearance(grid, clearance) {
         return true;
     };
 }
+/** @internal */
 export function computeFlowField(grid, goals, options = {}) {
     const { cols, rows } = grid;
     const passable = passableWithClearance(grid, options.clearance ?? 0);
@@ -150,6 +164,7 @@ export function computeFlowField(grid, goals, options = {}) {
     };
     return field;
 }
+/** @internal */
 export function createCrowdField(grid) {
     const { cols, rows } = grid;
     const occupancy = new Int32Array(cols * rows);
@@ -183,6 +198,7 @@ export function createCrowdField(grid) {
 function euclidean(from, poi) {
     return Math.hypot(poi.point[0] - from[0], poi.point[1] - from[1]);
 }
+/** @internal */
 export function selectPoi(pois, from, options) {
     const distanceBias = options.distanceBias ?? 1;
     const distanceOf = options.distance ?? euclidean;
@@ -211,3 +227,101 @@ export function selectPoi(pois, from, options) {
     }
     return eligible[eligible.length - 1];
 }
+function toStep(state, poiOf, exitOf, agentId) {
+    if (state.phase === "seeking" || state.phase === "done") {
+        return { phase: state.phase, target: null, poiId: null };
+    }
+    if (state.phase === "departing") {
+        return { phase: "departing", target: exitOf(agentId), poiId: state.poiId };
+    }
+    const poi = state.poiId === null ? undefined : poiOf(state.poiId);
+    return { phase: state.phase, target: poi?.point ?? null, poiId: state.poiId };
+}
+/**
+ * A many-agent seek→travel→arrive→dwell→depart loop over weighted points of interest (park visitors,
+ * shoppers, tavern patrons) — `ai/crowd`'s `selectPoi` covers only the weighted-pick step; this owns
+ * the per-agent phase machine around it so the caller only supplies positions and drives movement.
+ *
+ * @capability visitor-loop many-agent seek/travel/dwell/depart state machine over weighted POIs
+  * @internal
+  */
+export function createVisitorLoop(options) {
+    const { pois, dwellMs, exitPoint, occupancy, distanceBias, distance } = options;
+    const arriveRadius = options.arriveRadius ?? 1;
+    const agents = new Map();
+    const poiById = new Map(pois.map((poi) => [poi.id, poi]));
+    function poiOf(id) {
+        return poiById.get(id);
+    }
+    function exitOf(agentId) {
+        return typeof exitPoint === "function" ? exitPoint(agentId) : exitPoint;
+    }
+    function ensure(agentId) {
+        let state = agents.get(agentId);
+        if (state === undefined) {
+            state = { phase: "seeking", poiId: null, dwellRemaining: 0 };
+            agents.set(agentId, state);
+        }
+        return state;
+    }
+    return {
+        spawn(agentId) {
+            const state = ensure(agentId);
+            return toStep(state, poiOf, exitOf, agentId);
+        },
+        tick(agentId, position, dtMs, roll) {
+            const state = ensure(agentId);
+            if (state.phase === "seeking") {
+                const poi = selectPoi(pois, position, {
+                    roll: roll(),
+                    ...(occupancy === undefined ? {} : { occupancy }),
+                    ...(distanceBias === undefined ? {} : { distanceBias }),
+                    ...(distance === undefined ? {} : { distance }),
+                });
+                if (poi !== null) {
+                    state.poiId = poi.id;
+                    state.phase = "traveling";
+                }
+            }
+            else if (state.phase === "traveling") {
+                const poi = state.poiId === null ? undefined : poiOf(state.poiId);
+                if (poi === undefined) {
+                    state.phase = "departing";
+                    state.poiId = null;
+                }
+                else if ((distance ?? euclidean)(position, poi) <= arriveRadius) {
+                    state.phase = "dwelling";
+                    state.dwellRemaining = dwellMs(poi);
+                    options.onArrive?.(agentId, poi.id);
+                }
+            }
+            else if (state.phase === "dwelling") {
+                state.dwellRemaining -= dtMs;
+                if (state.dwellRemaining <= 0) {
+                    const poiId = state.poiId;
+                    state.phase = "departing";
+                    if (poiId !== null)
+                        options.onDepart?.(agentId, poiId);
+                }
+            }
+            else if (state.phase === "departing") {
+                const exit = exitOf(agentId);
+                if (Math.hypot(exit[0] - position[0], exit[1] - position[1]) <= arriveRadius) {
+                    state.phase = "done";
+                    state.poiId = null;
+                }
+            }
+            return toStep(state, poiOf, exitOf, agentId);
+        },
+        get(agentId) {
+            const state = agents.get(agentId);
+            return state === undefined ? null : toStep(state, poiOf, exitOf, agentId);
+        },
+        remove(agentId) {
+            agents.delete(agentId);
+        },
+        clear() {
+            agents.clear();
+        },
+    };
+}

package/dist/ai/flock.d.ts

@@ -26,11 +26,14 @@ export interface FlockConfig {
  * (many-agents-to-POI) deliberately isn't. Pure: returns the desired acceleration for one agent;
  * `stepFlock` is the convenience integrator. O(neighbors) per agent — pre-filter with a spatial
  * grid past a few hundred agents.
- */
+  * @internal
+  */
 export declare function flockSteer(agent: FlockAgent, neighbors: readonly FlockAgent[], config: FlockConfig, target?: FlockVec3): FlockVec3;
 export interface FlockStepAgent {
     position: FlockVec3;
     velocity: FlockVec3;
 }
-/** Integrate one tick in place: steer every agent, clamp to `maxSpeed`, advance positions. */
+/** Integrate one tick in place: steer every agent, clamp to `maxSpeed`, advance positions.
+ * @internal
+ */
 export declare function stepFlock(agents: FlockStepAgent[], config: FlockConfig, dt: number, target?: FlockVec3): void;

package/dist/ai/flock.js

@@ -4,7 +4,8 @@
  * (many-agents-to-POI) deliberately isn't. Pure: returns the desired acceleration for one agent;
  * `stepFlock` is the convenience integrator. O(neighbors) per agent — pre-filter with a spatial
  * grid past a few hundred agents.
- */
+  * @internal
+  */
 export function flockSteer(agent, neighbors, config, target) {
     const separationWeight = config.separationWeight ?? 1.5;
     const cohesionWeight = config.cohesionWeight ?? 1;
@@ -142,7 +143,9 @@ function fillNeighbors(agents, agentIndex, invCell) {
     neighborScratch.length = count;
     return count;
 }
-/** Integrate one tick in place: steer every agent, clamp to `maxSpeed`, advance positions. */
+/** Integrate one tick in place: steer every agent, clamp to `maxSpeed`, advance positions.
+ * @internal
+ */
 export function stepFlock(agents, config, dt, target) {
     const count = agents.length;
     if (count === 0)

package/dist/ai/groupAssist.d.ts

@@ -16,4 +16,5 @@ export interface AssistNetwork {
     assistersOf(memberId: string): string[];
     addThreat(memberId: string, sourceId: string, amount: number): string[];
 }
+/** @internal */
 export declare function createAssistNetwork(config?: AssistNetworkConfig): AssistNetwork;

package/dist/ai/groupAssist.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createAssistNetwork(config = {}) {
     const radius = config.radius;
     const shareFraction = Math.max(0, config.shareFraction ?? 1);

package/dist/ai/heatSystem.d.ts

@@ -0,0 +1,76 @@
+import { type RandomSeed } from "../random/rng.js";
+/** A world-space `[x, z]` used for the heat system's spawn ring and witness proximity checks. */
+export type HeatPoint = readonly [number, number];
+/** One escalation tier — the heat threshold it begins at and the pursuer count it wants active. */
+export interface HeatLevelDef {
+    /** Ascending level number (1, 2, 3, ...); level 0 is implicit below the first threshold. */
+    level: number;
+    /** Cumulative heat at which this level begins. */
+    threshold: number;
+    /** Active pursuers this level wants once reached. */
+    pursuerBudget: number;
+}
+/** Tuning for {@link createHeatState}/{@link advanceHeat} — levels, decay, and pursuit-spawn ring. */
+export interface HeatConfig {
+    /** Sorted ascending by `threshold`. */
+    levels: readonly HeatLevelDef[];
+    maxHeat?: number;
+    /** Heat bled per second once decay is unblocked. */
+    decayPerSecond: number;
+    /** Seconds after the last witnessed gain before decay starts (a beat of "still hot" after the last crime). */
+    decayDelaySeconds?: number;
+    /** Seconds at level 0 with pursuers still alive before {@link HeatStep.standDown} fires. */
+    standDownSeconds?: number;
+    /** `[min, max]` radius for {@link HeatStep.spawnPoints}; omit to skip ring generation. */
+    spawnRingRadius?: readonly [number, number];
+    seed?: number;
+}
+/** Serializable heat-system state — round-trips through `createHeatState`/`advanceHeat` each tick. */
+export interface HeatState {
+    heat: number;
+    level: number;
+    sinceGain: number;
+    standDownElapsed: number;
+    /** Opaque PRNG cursor — round-trip it as part of the state, never read or set it directly. */
+    rng: RandomSeed;
+}
+/** One crime tick's contribution — only `witnessed` gains raise heat (unseen crimes are free, GTA-style). */
+export interface HeatGain {
+    amount: number;
+    witnessed: boolean;
+}
+/** Per-tick world facts {@link advanceHeat} needs but can't derive itself — witness proximity, pursuer count, origin. */
+export interface HeatTickContext {
+    /** True blocks decay this tick (a witness/pursuer is still close enough to keep the heat hot). */
+    nearWitness: boolean;
+    activePursuers: number;
+    around: HeatPoint;
+}
+/** One `advanceHeat` tick's result — updated state plus what the caller should spawn/despawn. */
+export interface HeatStep {
+    state: HeatState;
+    levelChanged: boolean;
+    pursuerBudget: number;
+    /** `max(0, pursuerBudget - activePursuers)` — how many more pursuers to spawn this tick. */
+    wantSpawns: number;
+    /** `wantSpawns` points on the configured ring around `ctx.around`; empty without `spawnRingRadius`. */
+    spawnPoints: HeatPoint[];
+    /** True exactly the tick pursuit should fully clear — despawn every remaining pursuer. */
+    standDown: boolean;
+}
+/**
+ * Escalating crime/heat/pursuit state machine (#533.4) — the star-meter every open-world crime sandbox
+ * hand-rolls: witness-scoped gain (unseen crimes don't raise heat), proximity-gated decay (still hot
+ * while a witness or pursuer is close), tiered pursuer budgets, ring-shaped spawn points around the
+ * player, and a stand-down countdown once heat clears so pursuit doesn't vanish instantly. Pure and
+ * seeded like `ai/spawnDirector` — the caller owns spawning/despawning the actual entities.
+  * @internal
+  */
+export declare function createHeatState(config: HeatConfig): HeatState;
+/**
+ * Advances {@link HeatState} by one tick: sums this tick's witnessed gains, bleeds heat once clear of
+ * witnesses past `decayDelaySeconds`, resolves the current {@link HeatLevelDef}, and reports how many
+ * pursuers to spawn (with ring points) or whether to stand pursuit down entirely.
+  * @internal
+  */
+export declare function advanceHeat(config: HeatConfig, state: HeatState, dt: number, gains: readonly HeatGain[], ctx: HeatTickContext): HeatStep;

package/dist/ai/heatSystem.js

@@ -0,0 +1,97 @@
+import { randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+function levelFor(levels, heat) {
+    let current = null;
+    for (const level of levels) {
+        if (heat >= level.threshold)
+            current = level;
+    }
+    return current;
+}
+/**
+ * Escalating crime/heat/pursuit state machine (#533.4) — the star-meter every open-world crime sandbox
+ * hand-rolls: witness-scoped gain (unseen crimes don't raise heat), proximity-gated decay (still hot
+ * while a witness or pursuer is close), tiered pursuer budgets, ring-shaped spawn points around the
+ * player, and a stand-down countdown once heat clears so pursuit doesn't vanish instantly. Pure and
+ * seeded like `ai/spawnDirector` — the caller owns spawning/despawning the actual entities.
+  * @internal
+  */
+export function createHeatState(config) {
+    return {
+        heat: 0,
+        level: 0,
+        sinceGain: Number.POSITIVE_INFINITY,
+        standDownElapsed: 0,
+        rng: randomSeedFrom(config.seed ?? 1),
+    };
+}
+function ringPoints(around, count, radius, rng) {
+    const points = [];
+    let seed = rng;
+    const [minR, maxR] = radius;
+    for (let i = 0; i < count; i += 1) {
+        let roll;
+        [roll, seed] = stepRandomSeed(seed);
+        const angle = roll * Math.PI * 2;
+        let spread;
+        [spread, seed] = stepRandomSeed(seed);
+        const distance = minR + spread * Math.max(0, maxR - minR);
+        points.push([around[0] + Math.sin(angle) * distance, around[1] + Math.cos(angle) * distance]);
+    }
+    return { points, rng: seed };
+}
+/**
+ * Advances {@link HeatState} by one tick: sums this tick's witnessed gains, bleeds heat once clear of
+ * witnesses past `decayDelaySeconds`, resolves the current {@link HeatLevelDef}, and reports how many
+ * pursuers to spawn (with ring points) or whether to stand pursuit down entirely.
+  * @internal
+  */
+export function advanceHeat(config, state, dt, gains, ctx) {
+    const maxHeat = config.maxHeat ?? Number.POSITIVE_INFINITY;
+    const decayDelay = config.decayDelaySeconds ?? 0;
+    const gained = gains.reduce((sum, gain) => (gain.witnessed ? sum + gain.amount : sum), 0);
+    let heat = state.heat;
+    let sinceGain = state.sinceGain;
+    if (gained > 0) {
+        heat = Math.min(maxHeat, heat + gained);
+        sinceGain = 0;
+    }
+    else {
+        sinceGain += dt;
+        if (sinceGain >= decayDelay && !ctx.nearWitness) {
+            heat = Math.max(0, heat - config.decayPerSecond * dt);
+        }
+    }
+    const resolvedLevel = levelFor(config.levels, heat);
+    const level = resolvedLevel?.level ?? 0;
+    const pursuerBudget = resolvedLevel?.pursuerBudget ?? 0;
+    const levelChanged = level !== state.level;
+    let standDownElapsed = state.standDownElapsed;
+    let standDown = false;
+    if (level === 0 && ctx.activePursuers > 0) {
+        standDownElapsed += dt;
+        const limit = config.standDownSeconds ?? 0;
+        if (standDownElapsed >= limit) {
+            standDown = true;
+            standDownElapsed = 0;
+        }
+    }
+    else {
+        standDownElapsed = 0;
+    }
+    const wantSpawns = Math.max(0, pursuerBudget - ctx.activePursuers);
+    let spawnPoints = [];
+    let rng = state.rng;
+    if (wantSpawns > 0 && config.spawnRingRadius !== undefined) {
+        const rolled = ringPoints(ctx.around, wantSpawns, config.spawnRingRadius, rng);
+        spawnPoints = rolled.points;
+        rng = rolled.rng;
+    }
+    return {
+        state: { heat, level, sinceGain, standDownElapsed, rng },
+        levelChanged,
+        pursuerBudget,
+        wantSpawns,
+        spawnPoints,
+        standDown,
+    };
+}

package/dist/ai/interestScheduler.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Interest scheduling: the scale primitive that lets far-away agents sleep instead of running
+ * acquisition and pathing every frame. A per-agent gate decides — from proximity to the nearest
+ * interest source plus explicit wake signals — whether this tick does expensive work, at what
+ * cadence, with hysteresis so it never thrashes at the boundary and deterministic staggering so a
+ * thousand siblings do not all wake on the same frame. State is a plain serializable object; the
+ * caller drives it from a bounded spatial query, never a full-world scan.
+ */
+/** Whether an agent's gate is doing work (`active`) or culled (`dormant`). */
+export type InterestState = "active" | "dormant";
+/** A distance-keyed cadence tier: nearer agents tick faster, farther-but-awake agents tick slower. */
+export interface InterestTier {
+    /** Applies when proximity is at or below this distance. */
+    readonly within: number;
+    /** Seconds between active ticks in this tier (`0` = every tick). */
+    readonly interval: number;
+}
+/** Static configuration shared by every gate of one behavior class. */
+export interface InterestSchedulerConfig {
+    /** Proximity at or below which a dormant agent wakes. */
+    readonly wakeRadius: number;
+    /**
+     * Proximity above which an active agent sleeps. Must be >= `wakeRadius`; the gap between them is
+     * the hysteresis band that stops sleep/wake thrash at the edge. Default: `wakeRadius` (no band).
+     */
+    readonly sleepRadius?: number;
+    /** Seconds between active ticks while awake (`0` = every tick). Overridden by a matching tier. */
+    readonly activeInterval?: number;
+    /**
+     * Distance-keyed cadence tiers, checked in array order with the first `proximity <= within` match
+     * winning — so order them nearest-first (smallest `within` first). Overrides `activeInterval`.
+     */
+    readonly tiers?: readonly InterestTier[];
+    /** After any wake signal, stay active at least this long regardless of proximity. Default `0`. */
+    readonly stayAwakeSeconds?: number;
+}
+/** Per-agent serializable gate state. Round-trip the whole object; never read fields to drive logic. */
+export interface InterestGateState {
+    state: InterestState;
+    /** Time accrued toward the next active tick. */
+    clock: number;
+    /** Remaining forced-awake time from the last wake signal. */
+    awakeHold: number;
+    /** Deterministic `[0,1)` cadence offset so sibling agents fire on different frames. */
+    phase: number;
+}
+/** Per-tick input the caller supplies to a gate. */
+export interface InterestGateInput {
+    /** Distance to the nearest interest source (player, threat, owner); `null` when none / unknown. */
+    readonly proximity?: number | null;
+    /** Explicit wake trigger — damage, event, ownership change, caller override. Forces active. */
+    readonly wake?: boolean;
+}
+/** Per-tick output that tells the caller whether to run expensive work. */
+export interface InterestGateStep {
+    /** The gate's state after this tick. */
+    readonly state: InterestState;
+    /** Run the expensive work (acquisition, pathing) this tick? */
+    readonly active: boolean;
+    /** Transitioned dormant→active this tick — the single-frame wake edge. */
+    readonly woke: boolean;
+    /** Transitioned active→dormant this tick — the single-frame sleep edge. */
+    readonly slept: boolean;
+}
+/**
+ * A deterministic `[0,1)` cadence phase derived from a stable id, for staggering sibling gates so a
+ * batch of agents spawned together does not fire their first active tick on the same frame. Pass the
+ * result as the `phase` argument to {@link createInterestGateState}.
+ *
+ * @capability interest-stagger deterministic per-id cadence phase that spreads sibling gate ticks across frames
+ */
+export declare function interestPhase(seed: string | number): number;
+/**
+ * Create a dormant gate state, staggered by `phase` (`[0,1)`, typically {@link interestPhase} of the
+ * agent id) so siblings created together do not all fire their first active tick on the same frame.
+ *
+ * @capability interest-gate per-agent sleep/wake + cadence gate state so far agents skip expensive ticks
+ */
+export declare function createInterestGateState(config: InterestSchedulerConfig, phase?: number): InterestGateState;
+/**
+ * Advance one gate by `dt` seconds against this tick's `input`, mutating `state` in place and
+ * returning what the caller should do. Sleeping skips the expensive work (`active: false`) while the
+ * gate's timers keep advancing, so state is preserved; a `wake` signal or crossing `wakeRadius`
+ * flips it back to active and fires an immediate tick.
+ *
+ * @capability interest-scheduler advance a sleep/wake gate with hysteresis, cadence tiers, and stagger
+ */
+export declare function advanceInterestGate(state: InterestGateState, config: InterestSchedulerConfig, dt: number, input?: InterestGateInput): InterestGateStep;
+/** Aggregate counts of active vs dormant gates — the metric the issue asks a scheduler to expose. */
+export interface InterestCensus {
+    active: number;
+    dormant: number;
+    total: number;
+}
+/** A running census accumulator; call `record` inside the caller's existing tick loop (no extra pass). */
+export interface InterestCensusAccumulator {
+    record(state: InterestState | InterestGateState): void;
+    snapshot(): InterestCensus;
+    reset(): void;
+}
+/**
+ * Create a census accumulator so the caller can tally active/dormant gates during the loop it already
+ * runs, avoiding any separate full-world scan just to report scheduler metrics.
+ *
+ * @capability interest-census running active/dormant gate tally folded into the caller's tick loop
+ */
+export declare function createInterestCensus(): InterestCensusAccumulator;