Materialize, persist, and diagnose spawn-zone monster packs #80

Camp-site materialization amendment (2026-08-23)

Materialization must preserve the bounded camp footprints and local context
specified by content#241 — preserve camp-spot identity during dynamic spawn
migration while removing
duplicate map-local named definitions. An eligible camp hotspot may increase
the chance of an appropriate named rare/elite, but uses the same global cap,
reservation, cooldown, persistence, and atomic placement lifecycle. Story/key
holders and other static named actors remain explicit and retain their exact
rewards and progression behavior; they do not enter zone accounting.

Cover hotspot selection, full-cap fallback, restart/unload, blocked placement,
and static special-key actor fixtures in persistence and lifecycle tests.

Outcome

Integrate the deterministic population controller with map placement, common
entity creation, monster lifecycle, persistence, observability, and an offline
tuning surface so complete zone-owned packs can run in the headless world.

Scope and invariants

• Consume only validated immutable ABIN/AMAP views from server Implement the compiled content-package loader and immutable catalog #36. Source
  syntax, content-toolkit internals, and filesystem discovery never enter the
  gameplay domain.
• Derive a complete composition from the controller's bounded request, scan
  compiled candidate cells in a purpose-specific deterministic order, and
  apply live occupancy, terrain/surface, multipart, exit/protected-tile,
  proximity/visibility, leash, and reachability checks.
• Preflight and reserve every cell, entity, and threat unit, then create the
  whole pack through common entity/action services or create nothing.
• Tag every spawned member with stable zone/pack/generation ownership. Death,
  despawn, leash/reset, failed insertion, stale callbacks, multipart teardown,
  map unload, content transition, and shutdown release the correct ownership
  exactly once.
• Keep scripted action-graph spawns (Implement generic map/object triggers and authored action graphs #54), summons/pets, static actors,
  quest/gate encounters, and bespoke bosses outside zone accounting unless an
  explicit supported request says otherwise.
• Persist activation epoch, RNG/controller position, refill time/tokens, next
  deadline, cooldowns, and live/reserved pack ownership through Implement SQLite persistence, schema migrations, checkpoints, and backups #39/Persist bounded mutable world state independently of compiled content #11.
  Restart, restore, and map unload/reload cannot provide free rerolls or an
  instant refill burst.
• Expose bounded operator diagnostics with stable zone/pack IDs, effective
  policy, target/alive/reserved cost, role counts, tokens, next evaluation, and
  last typed result. Keep stable IDs out of unbounded metric labels and hidden
  coordinates out of ordinary player output.
• Provide a fake-time offline tuning command/report for population,
  composition, refill, placement rejection, and long-idle distributions.

Acceptance criteria

• A complete bat pack and mixed-role orc pack are selected, placed, and
  created atomically from released/synthetic compiled fixtures.
• No visible/too-close, occupied, blocked, unsupported-surface,
  protected/exit, unreachable, or invalid multipart placement commits.
• A congested zone returns bounded no-placement/backoff results without a
  partial pack, leaked cells/budget, or busy loop.
• Death, despawn, leash/reset, insertion failure, stale generation,
  multipart teardown, unload, content replacement, and shutdown each settle
  member/pack accounting exactly once.
• Persistence failure exposes no partial pack/controller state; restore and
  restart reproduce the same durable lifecycle without reroll or burst.
• Target reduction pauses new materialization but does not delete existing
  actors; target growth remains refill/burst-capped.
• Zone monsters use the same actor, action, combat/AI, death, loot, and
  attribution services as other monsters and cannot bypass their rules.
• Typed metrics/logs/traces/admin snapshots cover request, placement,
  commit, cancellation, cleanup, cap, overload, and persistence outcomes
  without high-cardinality operational labels or hidden-state disclosure.
• Property, replay, fuzz/fault, and scenario tests cover blocked/full maps,
  simultaneous packs, map unload at every phase, persistence/content
  mismatch, stale callbacks, long idle, overload, and shutdown.
• Dense-combat/zone benchmarks establish evaluation, placement, entity,
  persistence, and memory budgets; tools/validate.sh and
  git diff --check pass.

Dependencies

Native sub-issue:

• #81 — Implement transactional offering sites and encounter
  directives

Native child of the controller issue. Also depends on
server#11,
server#37,
server#38,
server#39,
server#41,
server#47,
server#48, and
server#50. Wrapper-connected
proof remains with atrinik#266/#269/#271.