worldbox-observer-mod/docs/event-catalog-discovery.md

Event catalog discovery

Live gap map of AssetManager libraries, mutation hooks, and IdleSpectator event-catalog coverage. Expansion of event-catalog.json should cite this ledger, not guessed id lists.

Audit date: 2026-07-17. WorldBox harness refresh: mutation_discovery, domain_event_audit, activity_happiness_audit, activity_status_audit, world_log_audit, disaster_war_audit, activity_taxonomy_audit (all PASS). Artifacts: IdleSpectator/.harness/ (especially mutation_*.tsv, domain_event_audit.tsv). Machine worksheet: event-catalog-discovery.tsv.

Verdict

Id inventory is complete for every EventCatalog domain. Authored 1:1 libraries match live counts with zero missing/orphan ids. Live+dial libraries are fully seeded. mutation_gaps.tsv is empty (gaps=0).

The feeling of “lots of events/tips we are not tracking” is mostly tip quality and Layer A noise, not missing catalog rows:

1. Library Labels still interpolate raw {id} (culture gains xenophobic, forges armor_leather).
2. Large ambient-A surfaces (items, genes, phenotypes, subspecies traits, meta traits, world laws) own the camera with generic templates.
3. Building complete / wonder finish still has no Layer A wire (destroy/consume only).
4. Meta-trait domains are live-seeded and TSV-audited but not fail-gated by domain_event_audit.

Tips here means watch tip / orange reason Labels from interest feeds, not dossier chip hover tooltips.

How to read priorities

Priority	Meaning
P0	Missing wire or authored sync that drops a real lifecycle beat
P1	Tip/prose quality for already-seeded high-visibility classes
P2	New surfaces or Signal tuning after P0/P1
P3	Intentional Layer B / covered-by another feed

Authored 1:1 domains

Live audits: missingAuthored=0 / orphan=0 for all closed libraries.

Domain	Live	Authored	Catalog mode	Camera policy (approx)	Priority
happiness	67	67	authored	Signal 49 / Aggregate 13 / Ambient 5	P3 sync done
status	58	58	authored	CreatesInterest 42; B FX 16	P3 sync done
worldLog	41	41	authored	CreatesInterest 40 (auto_tester B)	P3 sync done
plots	28	28	authored	all A	P3 sync done
eras	11	11	authored	all A	P3 sync done
books	12	12	authored	all A	P3 sync done
traits	116	116	authored	all A	P3 sync done
disasters	17	17	authored	via WorldLog pairs	P3 sync done
warTypes	5	5	authored	dials	P3 sync done
relationship	n/a	11	authored discrete	all A	P3 sync done

Happiness Ambient (stay B): got_poked, got_caught, paid_tax, just_ate, just_pooped. Status B: recovery_*, egg gain, spell_silence/boost, on_guard, just_ate, afterglow, slowness, cough, shield, dodge, dash, flicked.

Live + dial domains

Seeded via LiveLibraryInterest.EnsureSeeded + JSON libraries.* dials. authored=1 in domain_event_audit.tsv means live-seeded entry exists, not a per-id JSON prose row.

Domain	Live	Camera A	Dial label template	Notes	Priority
decisions	127	12	{a} decides to {action}	12 camera ids have action phrases; 2 JSON overlays are non-camera (try_new_plot, warrior_train_with_dummy)	P1 only if new interesting decisions appear
spells	12	12	{a} casts {id}	7 signalIds @86; 5 ambient A @44	P1 display names; P2 signal set
powers	339	23	God power: {id}	ambient CI=false; spectacle predicate	P1 display names
items	111	111	{a} forges {id}	ambient A; “forges” weak for armor/non-craft	P1 tip quality
genes	47	47	{a} gains gene {id}	ambient A	P1 names; P2 demote ambient spam
phenotypes	52	52	{a} shows {id}	ambient A	P1 names; P2 demote ambient spam
world_laws	49	49	Law changed: {id}	ambient A	P1 names
subspecies_traits	204	204	{a} evolves {id}	ambient A	P1 names; P2 Signal heuristics
biomes	29	0	Biome shifts: {id}	ambient CI=false	P3 stay B
culture_traits	78	78	{a} culture gains {id}	~14 dramatic @74; rest ambient @34	P1 names; hygiene gate
religion_traits	40	40	{a} faith gains {id}	dramatic heuristic	P1 names; hygiene gate
clan_traits	29	29	{a} clan gains {id}	dramatic heuristic	P1 names; hygiene gate
language_traits	26	26	{a} tongue gains {id}	dramatic heuristic	P1 names; hygiene gate

Decision camera set (all have authored action phrases): try_to_steal_money, kill_unruly_clan_members, banish_unruly_clan_members, find_lover, king_change_kingdom_{language,culture,religion}, leader_change_city_{language,culture,religion}, warrior_try_join_army_group, warrior_army_follow_leader.

Spell signalIds (strength 86): summon_lightning, summon_tornado, cast_curse, cast_fire, cast_blood_rain, summon_meteor, teleport. Ambient-A spells @44: cast_silence, cast_grass_seeds, spawn_vegetation, spawn_skeleton, cast_shield, cast_cure.

Patch-only / no catalog rows

Surface	Live / notes	Wire status	Priority
buildings	618	consume A; ambient destroy demoted B; no complete/wonder A	P0 complete/wonder
boats	patch	trade/unload A; load B	P3
combat	policy in EventCatalog.Combat	scanner + fight feeds	P3
architecture / city_build_orders	53 / 3	covered_by_building_activity	P3
kingdoms_traits	5	covered_by_trait_meta_feeds	P3
items_modifiers	59	covered_by_item_feed	P3
combat_action_library	11	covered_by_spell_combat_feeds	P2 only if distinct beats
loyalty / opinion / knowledge / communication / story	29/24/11/10/1	covered_by_worldlog_happiness	P3
citizen_job / professions / personalities	13/5/5	Activity/dossier labels	P3
tasks_actor	217	Activity taxonomy (unmappedTasks=0)	P3
actor_library	322	SpeciesDiscovery / voice (taxonomy PASS)	P3
plot_category_library	9	categories only	P3

WorldLog already covers end beats that inventory once flagged as open wire work: alliance_dissolved, kingdom_destroyed, kingdom_shattered, kingdom_fractured, city_destroyed. Manager removeObject is intentionally not event-worthy in MutationDiscoveryHarness because those WorldLog rows exist.

Mutation discovery

Metric	Value
managers	57
managerMethods	189
actorMethods	256
beh	93
libraries	39
libraryAssets	2893
gaps	0

World.era_manager / World.earthquake_manager report null on this build (unwired PollState, not gap rows). Age change remains wired via WorldAgeManager.startNextAge. Ongoing era/earthquake poll is still optional fill (P2), not a missing id catalog row.

Unwired ManagerEnd / Beh rows exist in TSVs but are filtered out of mutation_gaps by design (Beh → activity path; removeObject → WorldLog).

Tip quality gap (main expansion lever)

EventReason / discrete MakeLabel replace {id} with the raw asset id. Status/trait Activity and dossier paths already use locale/getTranslatedName helpers (LiveEnsemble.StatusDisplayName, trait display names). Library event Labels do not.

Examples of weak watch tips today:

• {a} culture gains xenophobic instead of a localized culture-trait name
• {a} forges armor_leather (wrong verb + raw id)
• {a} gains gene warfare_3
• God power: atomic_bomb (readable but not localized)

Recommended class fix: resolve {id} through live asset display names inside Label builders for library domains (same pattern as status), not thousands of JSON rows.

Audit hygiene

DomainEventHarness diffs culture/religion/clan/language traits into domain_event_audit.tsv but omits those diffs from Passed. If meta traits are first-class EventCatalog domains (they are), the pass condition should include them.

Expansion waves

Wave 0 - done by this audit

Authored 1:1 sync and live seed inventory: no missing ids.

Wave 1 (first implementation PR) - tip quality + building complete

Status (2026-07-17): implemented in mod 0.28.14.

1. LibraryAssetNames + EventReason.Library resolve live display names (localized when available, else humanized).
2. Item verb is gains by default; forges only for forge/smith/anvil ids. Catalog template {a} gains {id}.
3. Building.completeConstruction wires Layer A for Building_Civ (temple/statue spectacle strength bump).
4. domain_event_audit fail-gates culture/religion/clan/language trait diffs; library_asset_labels_ok dumps .harness/library-asset-labels.tsv.

Wave 2 - Signal / ambient A tuning

Status (2026-07-17): implemented in mod 0.28.16.

1. ambientCreatesInterest=false for spell/item/gene/phenotype/worldLaw/subspecies/meta trait dials (Signal predicates / signalIds own Layer A).
2. Spells: IsSpectacleSpell keeps summon/meteor/tornado/lightning/teleport/curse/blood/fire as A; silence/shield/cure/grass/vegetation/skeleton stay B.
3. World laws: dramatic class includes hunger/rebellion/disaster/angry (plus war/death/plague).
4. Phenotypes: all B (no Signal predicate).
5. Items: Signal for mythril/adamantine (+ named relic tokens); leather/iron ambient B.
6. JSON loader now ingests culture/religion/clan/language trait dials; default ambient CI is false.
7. Gate: library_ambient_policy_ok (nested in domain_event_audit).

Era change was already wired (WorldAgeManager.update → startNextAge). Earthquake ongoing hold: implemented (Earthquake.startQuake → EarthquakeActive sticky) in 0.28.17.

Wave 3 - new surfaces only if playtests demand

Status (2026-07-17): triaged closed - no new EventCatalog domains.

Surface	Live	Decision
combat_action_library (11)	melee/range/spell/dodge/…	Covered by combat scanner + tryToCastSpell → spell catalog
story / knowledge / communication / loyalty / opinion	small libs	Covered by WorldLog / happiness civic paths
personalities / professions	5 / 5	Activity/dossier labels only
architecture / city_build_orders	build helpers	Building complete / consume path

Do not mass-author powers/items/buildings into JSON.

First implementation PR recommendation

Title focus: Improve library event tip labels and wire building completion.

Scope:

• Display-name resolution for library Labels (class fix)
• Item label template improvement
• Building complete / wonder Layer A path + harness gate
• domain_event_audit pass includes culture/religion/clan/language trait diffs
• Refresh this doc + world-event-inventory.md counts

Out of scope for that PR: mass JSON rows; scoring-model changes; dossier chip tooltips.

Refresh commands

./scripts/worldbox-ctl.sh status
./scripts/harness-run.sh --no-launch mutation_discovery
./scripts/harness-run.sh --no-launch domain_event_audit
./scripts/harness-run.sh --no-launch activity_happiness_audit
./scripts/harness-run.sh --no-launch activity_status_audit
./scripts/harness-run.sh --no-launch world_log_audit
./scripts/harness-run.sh --no-launch disaster_war_audit
./scripts/harness-run.sh --no-launch activity_taxonomy_audit