Home World Overseer

Plan 44 — World Overseer (mechanics instrumentation)

Problem

Ops today: tick perf (/v1/perf), sparse audit JSONL, and manual in-game inspection. There is no structured, per-tick mechanics slice for hired workers, survival, paths, and job-loop anomalies — the kind of “IT overseer” pass the designer runs constantly.

Architecture

RegionSim::collect_overseer_report(tick)
    → WorkerDiag rows + rule engine (crates/sim/src/overseer.rs)
    → published every 5 ticks to OverseerStore (region-worker)
    → GET /v1/overseer (worker admin :7392)
    → GET /api/overseer (content-admin proxy :7385)
    → System → World Overseer UI + agents / flatland-admin (future)

Layers (roadmap)

Layer Status Purpose
L1 Snapshot v1 shipped Per-worker vitals, job step, lodging/jurisdiction, path stress
L2 Rules v1 shipped Declarative anomalies (rest stuck, path failures, survival crisis)
L3 History shipped Ring buffer (300 samples) + overseer_tick_sample audit (1 Hz)
L4 Slices shipped Employer + disk (cx/cy/radius_m); NPCs, wildlife, placed containers in snapshot
L5 CI scenarios planned flatland-admin overseer verify against scenario YAML

v1 anomaly rules

  • worker_rest_step_satisfied — rest step but stamina ≥ 90%
  • worker_rest_travel_while_full — traveling on rest at full stamina
  • worker_rest_far_from_lodging — rest-at-bed step, still needs lodging, stuck waiting or step_stalled > 25m away (not while traveling to bed)
  • worker_step_stalled — step_stalled set
  • worker_path_failures_high — plan/leg failure budget
  • worker_survival_crisis — combined low vitals
  • worker_overburdened_on_rest — overburden during rest step

Add rules in overseer.rs with unit tests; keep messages human-first (display names).

Agent workflow

curl -s http://127.0.0.1:7385/api/overseer | jq '.report.summary, .report.anomalies'
curl -s http://127.0.0.1:7392/v1/overseer | jq '.workers[] | {display_name, job_step_label, state, stamina_ratio, last_error}'

After make dev-restart, poll while reproducing a bug; anomalies should cite worker name + hint.

Not in scope (v1)

  • Player/NPC/wildlife full slices (workers only)
  • Automatic fixes / auto-triage
  • Production persistence (memory-only store)