refactor: scheme-agnostic WorldBundle + exposure metadata hook [LTV-Pn.2]

[shaypal5]

Summary

Second sub-PR of the split LTV-Pn (M6). Removes the last core/shared-layer references to the lead-scoring scheme — carried cleanups #2 (apply_exposure coupling) and #3 (core→scheme layering inversion) — so the lifecycle scheme can plug into the same envelope.

WorldBundle → scheme-agnostic (cleanup #3)

WorldBundle's three lead-scoring-typed fields (population / simulation_result / world_graph) are replaced by a single opaque artifacts: Any. Each scheme defines and unwraps its own container; lead-scoring adds LeadScoringArtifacts (schemes/lead_scoring/artifacts.py). core.models no longer imports any lead_scoring type — the inversion introduced in LTV-Pf.1 is gone.

Exposure → scheme hook (cleanup #2)

apply_exposure is now scheme-agnostic:

• writes the generic, spec-only world_spec.json (kept in exposure/metadata.py as write_world_spec_json);
• dispatches scheme-specific hidden truth to a new GenerationScheme.write_metadata(bundle, meta_dir) hook, resolved from bundle.spec.scheme via the registry.

The lead-scoring graph / latent-registry / mechanism-summary writers moved out of exposure/ into LeadScoringScheme.write_metadata. exposure/ no longer references lead_scoring. The protocol gains write_metadata; the lifecycle stub implements it (raises NotImplementedError until Pn.4).

Byte-identity

The full lead-scoring bundle is byte-identical across both exposure modes (research_instructor 21 files, student_public 14), verified against a pre-refactor SHA-256 reference. The metadata writers moved, not changed.

Re-scope

The shared bundle orchestrator (cleanup #1) moves from this PR to LTV-Pn.4. The roadmap's own note says it's best designed with the second scheme's write_bundle in hand — extracting it now against one scheme would guess the hook shape. Roadmap + deferred-cleanups updated (#2, #3 done; #1 → Pn.4).

Tests

• New tests/schemes/test_scheme_metadata_hook.py: artifacts populated by build_world; WorldBundle exposes only {spec, artifacts}; generic world_spec.json writer needs only a WorldSpec; the lead-scoring hook emits the four hidden-truth files; unpopulated-bundle and lifecycle-stub both raise.
• Field-access sites updated in 5 test modules (bundle.X → bundle.artifacts.X).
• Existing exposure suite already exercises the new dispatch end-to-end.
• Full suite 1808 passed / 51 skipped, ruff + mypy clean.

Next: Pn.3 (lifecycle config + regression task model).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Refactors the generation “envelope” to remove lead-scoring coupling by making WorldBundle scheme-agnostic (via an opaque artifacts payload) and by moving hidden-truth metadata writing behind a new GenerationScheme.write_metadata(bundle, meta_dir) hook dispatched from apply_exposure.

Changes:

• Replace WorldBundle’s lead-scoring-typed fields with artifacts: Any, with lead-scoring providing a LeadScoringArtifacts container.
• Make exposure metadata scheme-agnostic by splitting out world_spec.json writing and dispatching scheme-specific hidden truth to GenerationScheme.write_metadata.
• Update tests and roadmap/docs to reflect the new bundle shape and metadata hook behavior.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
leadforge/core/models.py	Replaces scheme-specific bundle fields with artifacts: Any on WorldBundle.
leadforge/schemes/base.py	Adds GenerationScheme.write_metadata protocol hook for hidden-truth emission.
leadforge/schemes/lead_scoring/artifacts.py	Introduces LeadScoringArtifacts as the scheme-owned artifacts container.
leadforge/schemes/lead_scoring/__init__.py	Populates WorldBundle.artifacts and implements write_metadata for lead scoring.
leadforge/schemes/lifecycle/__init__.py	Adds stub write_metadata method (NotImplemented) to satisfy the protocol.
leadforge/exposure/modes.py	Updates apply_exposure to write world_spec.json and dispatch scheme metadata via registry.
leadforge/exposure/metadata.py	Narrows exposure metadata to scheme-agnostic world_spec.json writing only.
tests/api/test_generator.py	Updates expectations to reference bundle.artifacts.*.
tests/test_difficulty_modulation.py	Updates access paths from bundle.simulation_result to bundle.artifacts.simulation_result.
tests/render/test_render.py	Updates bundle construction to use LeadScoringArtifacts.
tests/schemes/test_registry.py	Updates scheme-registry generation assertions to use bundle.artifacts.*.
tests/schemes/test_render_dispatch.py	Updates error-message assertions for unpopulated bundle writes.
tests/schemes/test_scheme_metadata_hook.py	Adds coverage for scheme metadata hook + scheme-agnostic world_spec.json writer.
docs/ltv/roadmap.md	Marks Pn.2 as complete and updates roadmap notes accordingly.
.agent-plan.md	Updates plan/status notes to reflect Pn.2 progress.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

pr-agent-context report:

No unresolved review comments, failing checks, or actionable patch coverage gaps were found on PR #122 in repository https://github.com/leadforge-dev/leadforge. Treat this PR as all clear unless new signals appear.

Run metadata:

Tool ref: v4
Tool version: 4.0.21
Trigger: commit pushed
Workflow run: 27459668962 attempt 1
Comment timestamp: 2026-06-13T06:56:16.698848+00:00
PR head commit: 7216d6d7fcd16c62cbb30b08836ffc25fba8eb42