worldbox-observer-mod/docs/rare-creature-antagonist-plan.md

Rare Creatures, Antagonists, and Camera Cleanup

Status: Complete. Implementation, deterministic regression, scheduler health, and two organic soak windows pass.

Goal

Let rare supernatural creatures and evidence-backed recurring antagonists compete for one of the five MC slots without allowing species identity, incidental combat, or routine background events to destabilize the ensemble. Keep admission explainable in the dossier/logs and bounded on mature worlds.

Phase 1 — Admission diagnostics

• Record visible-slot admission reason, rarity population/tier, and effective score.
• Record antagonist evidence, challenger score, weakest replaceable MC score, and rejection/replacement reason.
• Include the compact visible-roster explanation in soak_probe.
• Include rejected challenger explanations in soak_probe.
• Rate-limit diagnostics so observation cannot create log/GC hitches.

Exit: a soak log explains why each visible MC entered and why a notable challenger did not.

Phase 2 — Rare-creature admission

• Add one authoritative special-creature classifier for dragons, druids, necromancers, evil mages, and verified equivalent supernatural actor assets.
• Combine a modest special-creature prior with a dynamic population tier: singleton, rare, uncommon/common.
• Make special/rare creatures admission candidates, but never guaranteed occupants.
• Feed the bounded bonus into challenger priority and roster standing.
• Resolve population once per existing amortized scan/cache cycle, never once per scored actor.
• Expose RareCreature and SpecialCreature admission reasons.

Exit: a lone dragon or mage enters the challenger pool; a common population receives little or no rarity benefit and cannot displace a developed MC on identity alone.

Phase 3 — Recurring-antagonist lane

• Reuse bounded durable-rival evidence keyed by antagonist id and anchor MC id.
• Accept typed hostile encounters, harm to MC cast/city/faction, repeated opposition, major destruction, and confirmed kills; reject incidental proximity and a single weak fight.
• Make threshold-crossing antagonists admission candidates and emerging-story challengers.
• Combine antagonist and rarity bonuses with the normal replacement margin.
• Remove dead/stale edges through the existing bounded life-memory pruning.
• Expose RecurringAntagonist admission reason and exact anchor/evidence.

Exit: O'Blight-like repeated opposition can earn a slot, while one incidental attacker cannot.

Phase 4 — Exceptional-background policy

• Replace the broad strong-typed-consequence gate with explicit exceptional outcomes.
• Reject unrelated routine birth, hatch, adulthood, sleep, food, reproduction, movement, and ordinary settlement activity.
• Allow direct MC relevance, first/last special species, major lineage change, disaster survival/loss, and major political/destructive consequences.
• Log the exact exception rule for every approved background cut.

Exit: routine unrelated background cuts approach zero without hiding important disaster victims or world-changing events.

Phase 5 — Relationship/thread accuracy and dossier UI

• Require an exact typed story edge for McThreadContext; do not infer it from broad city, kingdom, cluster, or stale thread proximity.
• Support family, partner, friend, and recurring-opponent evidence; exact event participants cover typed attacker/victim/rescuer events.
• Show friendly and hostile connection labels in the dossier, including the anchor MC.
• Fall back to exceptional background when no exact MC relationship exists.

Exit: every related non-MC cut has an accurate, visible explanation.

Phase 6 — Texture pacing

• Track recent low-information texture categories per MC.
• Cool down repeated sleep, laughter, play, caffeine, wandering, and generic lover-search cuts.
• Prefer unresolved developments, relationships, rivalries, and consequences through the existing story scheduler and variety score.
• Retain occasional quiet re-entry after the category cooldown.

Exit: quiet life remains visible without crowding out story development.

Phase 7 — Deterministic coverage

• Singleton dragon enters through the real admission path.
• A larger dragon population receives a smaller bonus.
• Rare identity alone does not evict a developed MC.
• Repeated conflict creates an antagonist challenger.
• One kill/fight cycle does not create an antagonist.
• Harm to MC cast creates stronger evidence.
• Combined rarity/antagonist bonuses respect their cap.
• Routine unrelated hatch is rejected; an explicit singleton-special exception is accepted.
• Friendly/hostile dossier labels name the correct anchor.
• Broad or stale faction correlation fails thread attribution.
• The five-character roster stays stable across repeated scans.

Phase 8 — Performance and organic soak gate

• Run the full deterministic regression suite without the legacy combat fixture failure.
• Run scheduler health with hitch_probe and an active organic soak audit.
• Compare maximum frame, director, discovery, caption, and scheduler slices with the pre-change baseline.
• Confirm population work is scan-cached and antagonist work is event-driven/bounded.
• Confirm routine unrelated background share approaches zero, significant antagonists can earn slots, and roster churn remains controlled.

Exit: editorial acceptance criteria pass with no material performance regression.

Phase 9 — Long-soak stability tuning

• Remove ordinary-species singleton identity as a standalone admission gate.
• Retain strong singleton standing only for curated special creatures; ordinary singleton metadata remains available to the dossier but receives only a small standing tie-breaker.
• Protect established MCs with an additional replacement margin after meaningful chapters or minimum tenure.
• Require undeveloped ordinary challengers to clear an additional replacement margin.
• Apply per-character texture-family cooldowns even when the event is not classified as a FixedDwell moment beat.
• Extend lover-search to a fifteen-minute per-character cooldown.
• Prevent undeveloped ordinary challengers from displacing established MCs regardless of raw standing; require a chapter, sufficient story heat, or meaningful scheduler potential.
• Stop a fifth consecutive ordinary combat cut while allowing kills, resolutions, consequences, and world-critical combat through.
• Confirm reduced roster churn, no repeated lover-search cuts, and a maximum ordinary combat run of four in the next long organic soak.

Evidence prompting this phase: the first post-feature long soak successfully promoted evil mage Roum into a sustained MC story, but produced 26 distinct direct-MC subjects, four repeated lover-search cuts for Bim Llurr, and a seven-cut combat run. The first stability soak reduced the normalized churn rate by roughly 37% and capped combat runs at four, but still showed three lover-search cuts for Yaaahaona and 13 direct MCs in the developed-world portion.

Final deterministic probes confirm the fifteen-minute lover gate and ordinary-challenger evidence gate. A mature-save instrumented run settled from one 28.5 ms load/warm-up frame to 17.6 ms and then 16.7 ms windows; scheduler cost was 0.24 ms with 268 developments and 597 character states.

Completion evidence — 2026-07-25

• saga_rare_antagonist_acceptance passed all five assertions. Population standing scaled from 8 for a singleton to 2.6 at population five and 2 when common. Combined special/antagonist standing capped at 12, admission priority capped at 225, identity-only displacement of a developed incumbent was rejected, and developed-special/recurring-antagonist lanes remained eligible.
• Exact MC-cast harm produced rival evidence with strength 95 and the exact MC anchor. Friendly and hostile dossier labels named that same anchor; a city/kingdom-only correlation remained DiscoveryOnly with no anchor.
• Three consecutive live world scans retained the same ordered five-member fingerprint. The legacy combat-summary probe passed three independent runs, and camera presentability passed five independent runs after accepting a valid duel-to-collective escalation while preserving the principal pair.
• The isolated release regression passed 21/21 scenarios. Scheduler health passed at 0.71 ms with 18/128 candidates.
• Two uninterrupted five-minute organic windows passed the log audit. Across 45 cuts there were zero focus/name errors, placeholder tips, identity-filter leaks, unpresentable cuts, object-fall cuts, or fighting/sleeping mismatches. Combat share was 24.1% then 0%; the maximum combat run was 3; no character received a repeated lover-search cut.
• The established-roster window retained three of five members while the world lost four living actors; the two replacement slots were filled by stronger role-backed candidates and did not flip across repeated scans. Normal director slices were about 2–9 ms, scans stayed at or below 2.4 ms, scheduler slices at or below 0.71 ms, discovery at or below 2.5 ms, and caption work at or below 7.1 ms. One 28.4 ms director cutover outlier occurred. Whole-frame stalls of 401.2 ms and 162.3 ms contained only roughly 2–4 ms of attributed mod work and therefore were not caused by roster/scheduler scanning.