@gridlock/kernel

Generic agent-based modelling substrate for gridlock games — deterministic schedulers, a graph-space environment, event emission, and the ledger / journal / taxonomy / narrative / social layers built on top.

Engine-level with zero product coupling: the kernel knows about agents, ticks and events, and nothing about what any particular game's agents are. Hosts wire it to a product through adapters, not subclassing.

Zero runtime dependencies.

What you get

| Symbol | Purpose | |---|---| | Model, ModelConfig | The simulation container — holds agents, space and bus, and drives ticks. | | RandomScheduler, SimultaneousScheduler, FixedOrderScheduler | Tick ordering policies. Determinism comes from the injected Rng, so a seeded run replays exactly. | | createRng, Rng | Seeded PRNG. Every stochastic decision in the kernel draws from it. | | GraphSpace | Graph-structured environment — nodes, edges, agent placement and neighbourhood queries. | | EventBus, EventSubscriber | In-process event emission for the tick loop. | | Ledger, LedgerSnapshot, LedgerQuery, ObserverScope | Append-only, replayable, observer-scoped view over the bus. Adds what the raw bus lacks: a serialization boundary for cross-session replay, structured queries (by actor, kind, tick range), and scoping — what a given observer is allowed to have seen. | | Journal, JournalEntry, JournalConfig | Entry-typed player journal — player-authored records of their own reasoning, explicitly not system truth. Vocabulary-neutral: products register their own entry types, statuses and transition rules. | | Taxonomy: MOVEMENT, COMMUNICATION, MEETING, TRANSFER, RELATIONSHIP + movementEvent(…) etc. + isMovement(…) etc. | A shared five-kind event vocabulary with constructors and type guards, so downstream layers can reason about events without a per-game schema. | | salience, topHighlights, buildTimeline, firedStorylets, detectAnomalies | Narrative projection — scoring which events matter, assembling timelines, and flagging outliers. | | SocialState, SocialGraph, createCharacterState | Relationship, memory, motive and faction state between agents. | | createProjection, createCompositeProjection, ProjectionRegistry | Workspace projections — filtered/transformed views of kernel state for a host UI. |

Installation

npm install @gridlock/kernel

Status

Pre-1.0 (0.1.x). The engine is developed inside a private monorepo and published from there; there is no public issue tracker or support commitment. See the @gridlock org on npm for the rest of the packages.

MIT licensed.