Phase 9 plan — adventure-bundled monsters

[mmacy]

The plan for phase 9: an Adventure document carries its own MonsterTemplates, resolved everywhere the engine resolves template ids — the consumer-demonstrated need phase 6 pinned as the reopening condition ("post-1.0 if a consumer ever demonstrates the need"), demonstrated now by osr-forge's phase 7 (custom monster emission). Document-carried data, not a runtime registration API: the phase 6 boundary stands.

Notable decisions

• The seam is a session-held union, not a threading project. Every engine site that resolves a template id already has the session in scope, so the design is GameSession.effective_monsters (built once in __init__) plus four one-line redirects; the fifth load_monsters() site — validation in GameSession.new — keeps passing the base catalog by contract.
• validate_adventure keeps its exact signature and unions internally, honoring the consumer contract osr-forge's merged phase 7 plan pins: its existing call is correct unchanged.
• Collisions are errors, never overrides (shadowing orc would silently re-stat every reference); the _effective_monsters helper returns a first-occurrence-wins dedup union plus the colliding-id list, so both callers stay total and each turns collisions into its own typed ContentValidationError — checked before construction because MonsterCatalog's own validator raises a bare ValueError, the wrong failure shape.
• Inline wandering-table monster_ids join validation, closing a pre-existing deferred play-time ValueError surface (Changed bullet pinned — previously-accepted dangling ids now fail the gate up front).
• No SCHEMA_VERSION bump, no golden regeneration, no __all__ edit — the field is additive and defaulted, no golden embeds a serialized Adventure, and the property/helper are invisible to test_public_surface.py. Released as 1.2.0, semver-minor under the phase 8 discipline.

Review provenance

Rubber-ducked per AGENTS.md; first pass NEEDS REVISION, second pass SOLID. The blocking finding: the validation failure path was decision-incomplete — when the union fails, which catalog do the remaining checks use? Fixed by making the helper total (dedup union + collision list), pinning that remaining checks resolve the union so a colliding adventure's report names exactly the root cause with no spurious unknown-monster echo, and pinning the tests that assert it. Non-blocking findings addressed: the redirect count corrected (four, not five — the validation site is kept by contract), the id-domain docstring sweep added, the helper's definition moved to the validation work item, the versioned-docs evaluation now cites the 1.1.0 precedent and rebuts the AGENTS.md gloss instead of reading past it, the wandering-tightening Changed bullet pinned, the property renamed effective_monsters (leaving room for effective_equipment siblings, no helper shadowing), and the adaptations-register silence recorded as deliberate. Sign-off cosmetic notes folded in.

https://claude.ai/code/session_01EVrxXFxYBEGYjTF6wqnGP2