@jgengine/core 0.26.0 → 0.28.0

package/skills/jgengine-gameplay/capabilities.md

@@ -36,12 +36,15 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `cancelJob` (function) · `import { cancelJob } from "@jgengine/core/gameplay"`
 
-## carry-encumbrance — carried mass vs capacity into movement penalty tiers and a speed multiplier
+## carry-encumbrance — gate a pickup against the carrier's remaining capacity
 
+- `canCarry` (function) · `import { canCarry } from "@jgengine/core/inventory/carryLoad"`
+- `characterLoad` (function) · `import { characterLoad } from "@jgengine/core/inventory/carryLoad"`
 - `resolveEncumbrance` (function) · `import { resolveEncumbrance } from "@jgengine/core/inventory/encumbrance"`
 
-## carry-load — sum carried mass from item stacks via an injected mass resolver
+## carry-load — read carried stacks out of one or more inventories for a weight query
 
+- `carriedEntries` (function) · `import { carriedEntries } from "@jgengine/core/inventory/carryLoad"`
 - `totalLoad` (function) · `import { totalLoad } from "@jgengine/core/inventory/encumbrance"`
 
 ## cell-grid — immutable 2D board of cells with row clears, gravity collapse, and match runs
@@ -148,6 +151,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `enqueue` (function) · `import { enqueue } from "@jgengine/core/gameplay"`
 
+## equipment-slot-inventory — wear gear by slot with item-kind rules, two-handed blocking and replace-on-equip
+
+- `createEquipment` (function) · `import { createEquipment } from "@jgengine/core/inventory/equipment"`
+
 ## event-bus — typed publish/subscribe bus for gameplay events
 
 - `createGameEvents` (function) · `import { createGameEvents } from "@jgengine/core/gameplay"`
@@ -180,14 +187,23 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `ActionCodesMap` (type) · `import { ActionCodesMap } from "@jgengine/core/gameplay"`
 
-## game-save — save/load game state with a pluggable backend, autosave, slots, and migration
+## game-save — one versioned save document with per-system sections, named slots, caller-policy autosave, migration and a state digest
 
+- `createGameSave` (function) · `import { createGameSave } from "@jgengine/core/gameplay"`
 - `createSaveStore` (function) · `import { createSaveStore } from "@jgengine/core/gameplay"`
 
+## game-save-digest — hash a save document's state for a determinism test or a diff
+
+- `gameSaveDigest` (function) · `import { gameSaveDigest } from "@jgengine/core/gameplay"`
+
 ## game-system — declare a composable capability with its own schedule and lifecycle
 
 - `SystemDefinition` (interface) · `import { SystemDefinition } from "@jgengine/core/gameplay"`
 
+## gear-score — score a loadout from stat weights, level, rarity and slot coverage
+
+- `gearScore` (function) · `import { gearScore } from "@jgengine/core/gameplay"`
+
 ## group-credits — turn a flat list of credited things into ordered credit sections
 
 - `groupCredits` (function) · `import { groupCredits } from "@jgengine/core/game/credits"`
@@ -212,7 +228,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createEmptyInventory` (function) · `import { createEmptyInventory } from "@jgengine/core/inventory/inventoryModel"`
 
-## inventory-split — split a stack into a target or first-empty slot
+## inventory-split — split a stack into a target or first-empty slot, honoring a stack limit
 
 - `splitStack` (function) · `import { splitStack } from "@jgengine/core/inventory/inventoryModel"`
 
@@ -279,6 +295,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createLoadouts` (function) · `import { createLoadouts } from "@jgengine/core/gameplay"`
 
+## loan-schedule — build a loan's interest and principal repayment schedule in integer minor units
+
+- `buildLoanSchedule` (function) · `import { buildLoanSchedule } from "@jgengine/core/gameplay"`
+
+## loans — draw, schedule, service and default a loan with interest, posted to a ledger
+
+- `createLoanBook` (function) · `import { createLoanBook } from "@jgengine/core/gameplay"`
+
 ## local-save — persist a game to on-device localStorage (offline)
 
 - `localSaveBackend` (function) · `import { localSaveBackend } from "@jgengine/core/gameplay"`
@@ -287,20 +311,45 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `RarityStyle` (interface) · `import { RarityStyle } from "@jgengine/core/gameplay"`
 
+## loot-comparison — compare two rolled items with per-stat deltas and a weighted score
+
+- `compareLootItems` (function) · `import { compareLootItems } from "@jgengine/core/gameplay"`
+
 ## loot-filter — filter and highlight drops by rarity/name rules
 
 - `evaluateLootFilter` (function) · `import { evaluateLootFilter } from "@jgengine/core/gameplay"`
 
+## loot-generation — roll a named item from bases, parts, affixes, rarity weights, manufacturer personalities and level scaling
+
+- `rollLoot` (function) · `import { rollLoot } from "@jgengine/core/gameplay"`
+
 ## loot-pipeline — compose ordered loot pools with fallbacks, roll modifiers, and provenance
 
 - `createLootPipeline` (function) · `import { createLootPipeline } from "@jgengine/core/gameplay"`
 - `defineLootPipeline` (function) · `import { defineLootPipeline } from "@jgengine/core/gameplay"`
 
+## loot-roller — roll items from one validated catalog while counting drops per rarity for a debug probe
+
+- `createLootRoller` (function) · `import { createLootRoller } from "@jgengine/core/gameplay"`
+
+## loot-score — split one stat block into per-stat weighted contributions
+
+- `lootStatContributions` (function) · `import { lootStatContributions } from "@jgengine/core/gameplay"`
+- `scoreLootStats` (function) · `import { scoreLootStats } from "@jgengine/core/gameplay"`
+
 ## loot-table — register loot tables and roll weighted randomized drops
 
 - `createLootRegistry` (function) · `import { createLootRegistry } from "@jgengine/core/gameplay"`
 - `lootTable` (function) · `import { lootTable } from "@jgengine/core/gameplay"`
 
+## loot-validation — check a rolled item against its catalog and report each defect with its code
+
+- `validateLootItem` (function) · `import { validateLootItem } from "@jgengine/core/gameplay"`
+
+## loot-weapon — feed a rolled item into a weapon definition so generated gear fires through the weapon system
+
+- `lootWeaponDefinition` (function) · `import { lootWeaponDefinition } from "@jgengine/core/gameplay"`
+
 ## maturation-stage — resolve the baby/juvenile/adolescent/adult stage from elapsed maturation
 
 - `maturationStage` (function) · `import { maturationStage } from "@jgengine/core/game/breeding"`
@@ -309,6 +358,36 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `mergeCredits` (function) · `import { mergeCredits } from "@jgengine/core/game/credits"`
 
+## mission-compositions — build escort, chase and defend missions from the shared objective kinds
+
+- `chaseMission` (function) · `import { chaseMission } from "@jgengine/core/gameplay"`
+- `defendMission` (function) · `import { defendMission } from "@jgengine/core/gameplay"`
+- `escortMission` (function) · `import { escortMission } from "@jgengine/core/gameplay"`
+
+## mission-events — count constrained kills and fail a mission on a matching world event
+
+- `MissionWorldEvent` (interface) · `import { MissionWorldEvent } from "@jgengine/core/gameplay"`
+
+## mission-rewards — pay mission rewards through the quest appliers and the loot registry
+
+- `applyMissionRewards` (function) · `import { applyMissionRewards } from "@jgengine/core/gameplay"`
+
+## mission-runtime — missions as a data-driven objective state machine with fail states, timers, branches and rewards
+
+- `createMissionRuntime` (function) · `import { createMissionRuntime } from "@jgengine/core/gameplay"`
+
+## mission-triggers — start, advance and fail a mission from authored scene markers
+
+- `MISSION_TRIGGER_ACTIONS` (const) · `import { MISSION_TRIGGER_ACTIONS } from "@jgengine/core/gameplay"`
+- `createMissionTriggerBridge` (function) · `import { createMissionTriggerBridge } from "@jgengine/core/gameplay"`
+- `missionMarkers` (function) · `import { missionMarkers } from "@jgengine/core/gameplay"`
+- `registerMissionTriggerActions` (function) · `import { registerMissionTriggerActions } from "@jgengine/core/gameplay"`
+
+## mission-validation — tell whether an objective kind completes from a counter alone
+
+- `isCounterObjective` (function) · `import { isCounterObjective } from "@jgengine/core/gameplay"`
+- `validateMissionCatalog` (function) · `import { validateMissionCatalog } from "@jgengine/core/gameplay"`
+
 ## modular-item — attach parts into item mount slots to compute combined stats
 
 - `slotAccepts` (function) · `import { slotAccepts } from "@jgengine/core/gameplay"`
@@ -482,6 +561,21 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createVfxInstanceStore` (function) · `import { createVfxInstanceStore } from "@jgengine/core/gameplay"`
 
+## ride-appeal — how much one guest likes one ride, from its ratings and their taste
+
+- `rideAppeal` (function) · `import { rideAppeal } from "@jgengine/core/gameplay"`
+
+## ride-choice — guests pick rides by taste and queue tolerance through the utility brain
+
+- `createRideChooser` (function) · `import { createRideChooser } from "@jgengine/core/gameplay"`
+- `rideChoiceCandidates` (function) · `import { rideChoiceCandidates } from "@jgengine/core/gameplay"`
+- `rideChoiceOptions` (function) · `import { rideChoiceOptions } from "@jgengine/core/gameplay"`
+- `rideQueueCostWeight` (function) · `import { rideQueueCostWeight } from "@jgengine/core/gameplay"`
+
+## ride-sim — rides with capacity, cycles, queues, ratings, breakdowns and maintenance
+
+- `createRideSystem` (function) · `import { createRideSystem } from "@jgengine/core/gameplay"`
+
 ## routine-timeline — authored daily routines (home, work, meal) resolved against the world clock
 
 - `resolveRoutine` (function) · `import { resolveRoutine } from "@jgengine/core/gameplay"`
@@ -496,6 +590,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createRunDraft` (function) · `import { createRunDraft } from "@jgengine/core/gameplay"`
 
+## save-slot-index — refresh a save-select index from the game's save documents
+
+- `refreshSaveSlots` (function) · `import { refreshSaveSlots } from "@jgengine/core/game/saveSlotIndex"`
+
+## save-slot-meta — project a save document onto save-select display metadata
+
+- `saveSlotMeta` (function) · `import { saveSlotMeta } from "@jgengine/core/game/saveSlotIndex"`
+
 ## save-slots — serializable save-slot / profile metadata index — write/clear/rename/mostRecent over free-string per-slot meta, powering New/Continue/Load/Delete menus, with snapshot/restore
 
 - `createSaveSlots` (function) · `import { createSaveSlots } from "@jgengine/core/gameplay"`
@@ -523,11 +625,16 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## shaped-placement — find a shaped inventory item's first fit with ordered rotations, row-major placement, and an explicit search budget
 
 - `findShapedPlacement` (function) · `import { findShapedPlacement } from "@jgengine/core/inventory/shapedGrid"`
+- `fitShapedItem` (function) · `import { fitShapedItem } from "@jgengine/core/inventory/shapedGrid"`
 
 ## shop-grid — serializable vendor/shop stock with buy/sell over a caller-owned wallet — finite/unlimited qty, sell-back, restock/setPrice, snapshot/restore
 
 - `createShopStock` (function) · `import { createShopStock } from "@jgengine/core/gameplay"`
 
+## skill-tree — spend, refuse and refund points over an authored tree with passives, actives and synergies
+
+- `createSkillTree` (function) · `import { createSkillTree } from "@jgengine/core/gameplay"`
+
 ## social-emotes — emotes and social interactions between nearby players
 
 - `createSocial` (function) · `import { createSocial } from "@jgengine/core/gameplay"`
@@ -552,6 +659,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `statModifierContributions` (function) · `import { statModifierContributions } from "@jgengine/core/gameplay"`
 
+## supply-demand-pricing — price goods from finite stock and live demand on a stated curve
+
+- `createMarket` (function) · `import { createMarket } from "@jgengine/core/gameplay"`
+
 ## system-schedule — compile fixed/frame/interval system ticks into deterministic ordered stages
 
 - `compileSystemSchedule` (function) · `import { compileSystemSchedule } from "@jgengine/core/gameplay"`
@@ -582,6 +693,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `setTouchControlsMode` (function) · `import { setTouchControlsMode } from "@jgengine/core/gameplay"`
 - `touchButtonShape` (function) · `import { touchButtonShape } from "@jgengine/core/gameplay"`
 
+## transaction-ledger — record every money movement with its reason over per-account integer minor-unit balances
+
+- `createTransactionLedger` (function) · `import { createTransactionLedger } from "@jgengine/core/gameplay"`
+
 ## tribe-group — shared-ownership group (tribe/guild/clan) with ranked permissions, group vs personal assets, alliances, and a bounded event log
 
 - `createTribe` (function) · `import { createTribe } from "@jgengine/core/game/tribe"`
@@ -617,6 +732,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createUnlockCatalog` (function) · `import { createUnlockCatalog } from "@jgengine/core/gameplay"`
 
+## visitor-population — a crowd whose on-site and daily counts are the bodies the game made
+
+- `createVisitorPopulation` (function) · `import { createVisitorPopulation } from "@jgengine/core/gameplay"`
+
+## wait-queue — a real line whose wait estimate comes from its own measured throughput
+
+- `createWaitQueue` (function) · `import { createWaitQueue } from "@jgengine/core/gameplay"`
+
 ## wallet — hold currency balances with charge and affordability checks
 
 - `createEmptyWallet` (function) · `import { createEmptyWallet } from "@jgengine/core/gameplay"`
@@ -660,3 +783,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## work-queued-jobs — list jobs waiting for a slot, in selection order
 
 - `queuedJobs` (function) · `import { queuedJobs } from "@jgengine/core/gameplay"`
+
+## xp-curve — resolve an authored xp growth rule into per-level thresholds, totals and a level cap
+
+- `defineXpCurve` (function) · `import { defineXpCurve } from "@jgengine/core/gameplay"`

package/skills/jgengine-gameplay/reference-systems.md

@@ -28,6 +28,124 @@ and level state, then emits every reached level in ascending order. State stays
 in the caller's save format and round-trips as ordinary JSON. See the
 [portable XP/leveling recipe](recipes/portable-xp-leveling.md).
 
+## Procedural gear
+
+`loot/lootGen` rolls a whole named item from a caller-authored `LootCatalog`:
+bases (`baseStats`, affix `pools`, mount `slots`), parts, affix pools, weighted
+`RarityTier`s, `LootManufacturerDef`s (name, flat `bias`, per-stat `scale`,
+favored pools) and a `levelScale` curve of `[level, multiplier]` points. A roll
+picks maker, base, rarity, one part per slot and `affixCount` affixes; stats are
+`base × rarity.statScale × levelScale`, plus part stats/multipliers, maker
+personality, then additive affixes and multiplicative ones. Additive affix
+rolls scale with level; multiplicative ones do not. Names follow one rule:
+maker, rarity word, first part word, first prefix affix, base name, first suffix
+affix. Every random draw uses the injected `rng`, so a seed reproduces the item.
+
+```ts
+import { compareLootItems, createLootRoller, lootWeaponDefinition, seededRng } from "@jgengine/core/gameplay";
+
+const roller = createLootRoller(catalog, { devtoolsName: "loot" });
+const item = roller.roll(seededRng(dropSeed), { level: 30 });
+const delta = compareLootItems(item, equipped, { lowerIsBetter: ["reload"] });
+const weapon = lootWeaponDefinition(item, { template, stats: { damage: "power", roundsPerMinute: "cadence" } });
+```
+
+`validateLootItem` returns coded issues (`unknown-base`, `part-category`,
+`missing-slot-part`, `unknown-affix`, `empty-name`…) and the roller's counters
+snapshot/restore as plain data. Register a roll through
+`proceduralLootEntry` into `item/itemInstanceRegistry` and hand its runtime id
+to `game/lootTable`; the weapon projection only maps stats it is told to, so a
+catalog without weapon stats stays usable for non-weapon gear. Check a
+distribution with a fixed seed over 10,000 drops against each tier's 4σ
+binomial bound rather than eyeballing shares.
+
+## Progression and gear score
+
+`progression/xpCurve` turns one authored growth rule into the level table, the cap and a
+plain-words rule line, so the balance lives in save-visible data:
+
+```ts
+import { createSkillTree, defineXpCurve, gearScore } from "@jgengine/core/gameplay";
+
+const xp = defineXpCurve({ growth: "power", step: 100, growthRate: 1.5, maxLevel: 40, round: "floor" });
+// rule: "power: 100 x level^1.5, floor (levels 1-40)"; xpForLevel(2) is 282, xpForLevel(40) is 0
+xp.levelForXp(xp.totalXpFor(7)).level; // 7
+xp.track(); // the same thresholds as a `leveling` track for a stat adapter
+
+const tree = createSkillTree({ nodes, synergies, points: 6 }, { devtoolsName: "skills" });
+tree.spend("strike"); // { ok: true, spent: 1, pointsAvailable: 5 }
+tree.canSpend("sight"); // { ok: false, reason: "requires", detail: '...needs rank 1 of "focus"' }
+const { stats, actives, synergies: live } = tree.resolved();
+tree.respec(); // { refunded: 6, pointsAvailable: 6 }
+```
+
+A `SkillNodeDef` is `{ id, branch?, cost?, maxRank?, requires?, requiresPointsInBranch?,
+excludes?, passives?, actives?, tags? }`; a `SkillSynergyDef` lists at least two `requires` and
+adds passives/actives only while they all hold. `excludes` is symmetric, so two nodes named as
+alternatives block each other in both directions. Actives are `{ id, cooldownMs?, resourceCost?,
+castType?, groups? }`, shaped to bind into `createAbilityKit` slots. Snapshot/restore carries
+`{ points, ranks }`; restore refuses unknown nodes, over-ranked nodes and negative points without
+mutating. A tree where breadth beats depth is the point: in the test fixture, four points down
+`strike` give `damage +3`, while the same four points in `strike x2`, `focus`, `sight` give
+`damage +4` plus the `overload` synergy and its action.
+
+`gearScore(set, options)` scores `slot -> { stats, level?, rarity? }` as
+`Σ_stat value × weight × (lowerIsBetter ? -1 : 1) + levelWeight × level + rarityScore[rarity]`,
+summed over filled slots, minus `emptySlotPenalty` per expected-but-empty slot; it also returns
+`bySlot`, `byStat`, `average`, `coverage` and `emptySlots`. `compareGearSets` ranks two loadouts.
+The stat term comes from `lootStatContributions`, the same function behind `scoreLootStats` and
+`compareLootItems`, so per-item and whole-loadout scores cannot drift apart.
+
+## Inventory, equipment and weight
+
+A carried bag and a stash are two declared inventories, so they hold separate plain state from the
+first frame and persist as `InventorySet.snapshot()`:
+
+```ts
+import { createInventorySet } from "@jgengine/core/inventory/inventoryModel";
+import { canCarry, characterLoad } from "@jgengine/core/inventory/carryLoad";
+import { createEquipment } from "@jgengine/core/inventory/equipment";
+
+const items = createInventorySet({ bag: { slots: 24 }, stash: { slots: 60 } }, traits);
+items.move("bag", 3, "stash", 0); // across inventories; a rejected move leaves both untouched
+const saved = items.snapshot(); // detached; JSON-safe; restore() refuses a bad save without mutating
+
+const gear = createEquipment(
+  [{ id: "weapon", blocks: ["offhand"] }, { id: "offhand" }, { id: "chest", accepts: ["armor"] }],
+  (itemId) => baseDefs[registry.get(itemId)?.baseId ?? itemId]?.gear, // rolled item -> its base's gear facts
+  { devtoolsName: "gear" },
+);
+gear.equip("chest", "plate"); // { status: "ok", replaced: null, ... }
+gear.equipBest("greatsword"); // first free preferred slot, else the first one it may replace
+
+const load = characterLoad({
+  carried: [items.state("bag")],
+  worn: gear.worn().map((entry) => entry.itemId),
+  weightOf: (itemId) => baseDefs[itemId]?.weight ?? 0,
+  capacity: 60 + stats.value("carryCapacity"),
+});
+load.moveMultiplier; // 1 unencumbered, decays across the soft band, 0 at capacity
+canCarry(load, 12); // gate a pickup; the overload policy stays the game's
+```
+
+`EquipSlotDef` owns `accepts` (item kinds) and `blocks` (slots it occupies while filled), and
+`EquipItemDef` owns the `slots` an item may occupy plus its `kind`; a filled slot swaps and returns
+the replaced item, so nothing is silently destroyed, and `state()` / `restore()` carry
+`{ slots: [[slotId, itemId]] }`. The stash is simply left out of `carried`, so its contents add no
+weight, and declaring it `tier: "banked"` keeps it out of `partitionOnDeath`'s lost half.
+
+For a footprint bag, `fitShapedItem` (`inventory/shapedGrid`) places the first legal spot or names
+why it does not fit — `too-large` with both sizes, `no-space` for a full board, `budget-exceeded` for
+an exhausted search. Stack rules stay in `ItemTraits`: `putItem` fills partial stacks then opens new
+ones up to the max stack, `moveItem` merges with a remainder, and `splitStack(..., limit)` refuses an
+`over-stack` merge instead of breaking the cap.
+
+The rendered side is the engine's: `<InventoryGrid inventoryId="bag" />` (`packages/react`) binds a
+live declared inventory with drag, swap, merge and split through the `inventory.move` /
+`inventory.split` commands, and `<EquipmentSlots items={...} />` paints the worn slots from
+`gear.worn()`. What the grid cannot yet do is drag from one inventory to another (bag to stash), so a
+stash transfer goes through `InventorySet.move` behind a button or command.
+
 ## Coherent authored content
 
 Keep stable ids and canonical facts for characters, factions, places, and world rules in the game's authored data. Record each chapter's prerequisites, consequences, and which facts it may introduce or change. The game's creative pillars, story voice, content palette, and desired player experience come from its author; generated prose, items, art, and assets must serve those constraints. Reuse constrained generation and validation code across games while each game owns its content and visual identity; do not fill catalogs from default genre kits or mass generic content.

package/skills/jgengine-world/SKILL.md

@@ -63,6 +63,14 @@ Route on an editor-baked polygon nav mesh through `createNavRuntime` (`nav/navRu
 
 Move many agents across that mesh with `createNavCrowd` (`nav/navCrowd`): it plans corridors, follows the funnel-smoothed waypoints, keeps them apart with `createRvoCrowd` (`ai/rvo`) reciprocal velocity obstacles, bounds path searches to a per-tick time and count budget, and serializes through `snapshot`/`restore`. Give a crowd converging on one spot a `spread` radius so agents fan out (`ai/crowd`'s stable per-id offset) instead of stacking. Avoidance keeps agents inside the mesh's outer bounds; interior walls remain the game's collision layer.
 
+### Street traffic
+
+Vehicles on roads do not path-find: they follow authored lane spans. `createLaneGraph` (`nav/laneGraph`) resolves those spans — `traffic_lane` paths, or `road` paths from the editor's street bake, split where streets cross — into junctions, crossings with a signal program or first-come right-of-way, and parking spots; `laneGraphFromDocument` reads that straight off the scene document, so editing a road moves its traffic. `createTraffic` (`nav/traffic`) then drives cars on it: IDM car following and braking, one car at a time through each intersection box (only once the exit lane has room, which is what keeps a blocked crossing from wedging the network), signals with phases, lane changes across authored `left`/`right` neighbours, parking that reserves a spot, and `setDemand(count)` for fleet size — the time-of-day curve is the caller's, not the engine's. Cars are posed, not driven: when a player or a chase needs real handling, feed intent into `physics/kinematicVehicle` and let this seam keep the ambient city.
+
+### Heat and police response
+
+A crime only counts when a witness holds the suspect. `createPoliceResponse` (`ai/policeResponse`) reads witness facts from `sensor/perception` memory — `memoryOf` per observer, keeping the sighting's `sourceId` and `sourceTick` — and adds heat on the shared `ai/heatSystem` curve, so there is no second sight path and no second decay. The caller's tier table decides what police do at each heat: patrol, investigate, pursue, roadblock, with a pursuer budget per tier. The search area sits on the suspect's last known position, grows while the trail is cold, and a roadblock tier cordons it with sites `policeRoadsFromLaneGraph` reads off the lane graph (`traffic_roadblock` markers projected onto the lane they block, else the graph's intersections). Breaking sight for `escapeSeconds` is what starts the decay; standing in view keeps the heat. Heat, curve, tiers and search shape are caller policy with defaults, `state()`/`restore()` round-trip mid-chase, and the injected generator is the only source of variety.
+
 ### Fallback-seam diagnostics
 
 Render seams fall back to placeholders when content is unauthored: default green ground (no environment), primitive capsule/box actors (no `entityModels`/`objectModels` mapping), stylized proxy foliage (no scatter `resolveItem`). These placeholders are sometimes intended, so runtime never changes — but a dev-only, opt-in probe (`@jgengine/core/devtools/fallbackSeams`) tells "unauthored/misconfigured" apart from "intended". The shell arms it via `armFallbackSeams(devtoolsEnabled)`; each seam reports at its choice site (`reportFallbackSeam`), and counts surface through the devtools `fallbacks` probe. Disarmed (production) it is a pure, allocation-free no-op.