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

Rare Creatures, Antagonists, and Camera Cleanup

Status: Implemented; targeted and performance gates pass. Full regression is blocked by the legacy combat-presentability fixture's nondeterministic pair-to-mass reframe assertions.

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.