feat: Milestone 7 — simulation engine (state, daily loop, conversion, events)

[shaypal5]

Summary

• simulation/state.py: LeadSimState — per-lead mutable state tracking current stage, dwell days, conversion/churn flags, and the first day reaching sql (used to anchor opportunity timestamps)
• simulation/engine.py: simulate_world(config, population, world_graph) → SimulationResult — 90-day discrete-time loop. Each day per non-terminal lead: churn check (0.4%/day → closed_lost), stage advance via HazardTransition (mql → … → negotiation), final close via ConversionHazard (negotiation → closed_won), then touch/session/sales-activity emission. Post-loop creates opportunities (all sql+ leads), customers, and subscriptions (converted leads).
• converted_within_90_days is event-derived — it is True only when the simulated trajectory reaches closed_won within the 90-day horizon (never directly sampled).
• 45 new tests covering state transitions, FK integrity, determinism, motif-family variation, and conversion-rate ordering (fit-dominant > buying-committee-friction)
• Total: 490 tests passing, ruff clean, mypy clean

Test plan

• LeadSimState unit tests: advance, mark_converted, mark_churned, dwell reset, sql_day recording
• SimulationResult type correctness: all lists contain correct row types
• Determinism: same seed → identical outcome lists
• Lead outcomes: all leads are MQL, converted leads have timestamps and are at closed_won, some leads convert and some don't
• Opportunity / customer / subscription FK integrity and counts match conversion counts
• Touch / session / activity lead FK and ID uniqueness
• All 5 motif families run without error
• Conversion-rate ordering (fit-dominant vs buying-committee-friction at n=300)
• _plan_from_acv tier boundaries

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds the Milestone 7 discrete-time (daily) simulation engine that evolves leads through funnel stages, emits CRM-like events, and materializes downstream entities (opportunities/customers/subscriptions), with a new state model and an accompanying test suite.

Changes:

• Introduces LeadSimState for per-lead mutable simulation state (stage, dwell, conversion/churn flags, sql-day anchoring).
• Implements simulate_world(...) 90-day loop that applies churn + stage/conversion hazards and emits touches/sessions/sales activities, then creates opportunities/customers/subscriptions.
• Adds a comprehensive tests/simulation/test_engine.py covering determinism, FK integrity, motif-family behavior, and tier boundaries.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
leadforge/simulation/engine.py	New simulation engine + post-sim entity creation + helper utilities
leadforge/simulation/state.py	New LeadSimState dataclass used by the engine loop
tests/simulation/test_engine.py	New unit/integration-style tests validating engine/state behavior
.agent-plan.md	Updates milestone status and next-task plan

---

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

[github-actions]

pr-agent-context report:

This run includes unresolved review comments on PR #12.

For each unresolved review comment, recommend one of: resolve as irrelevant, accept and implement
the recommended solution, open a separate issue and resolve as out-of-scope for this PR, accept and
implement a different solution, or resolve as already treated by the code.

After I reply with my decision per item, implement the accepted actions, resolve the corresponding
PR comments, and push all of these changes in a single commit.

# Copilot Comments

## COPILOT-1
Location: leadforge/simulation/engine.py
URL: https://github.com/leadforge-dev/leadforge/pull/12#discussion_r3152275834
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    `date.fromisoformat(lead.lead_created_at)` is executed inside the inner (day × lead) loop, even though `lead_created_at` is constant per lead. For the default scale (e.g., 5k leads × 90 days) this adds avoidable parsing overhead. Consider precomputing `lead_created_date` once per lead before the main loop (or caching it alongside `states`) and then only doing the `timedelta(days=t)` addition per day.

## COPILOT-2
Location: tests/simulation/test_engine.py
URL: https://github.com/leadforge-dev/leadforge/pull/12#discussion_r3152275878
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    `test_different_seeds_differ` asserts different seeds produce different *counts* of touches/sessions, but it’s still possible (by chance) for both counts to match, making the test flaky. Consider asserting a stronger signal (e.g., compare a small slice of serialized rows, or check that at least one of: touch types, timestamps, conversion flags, etc. differs), or increase `n_leads` enough that identical counts become effectively impossible.
    ~~~suggestion
            r1 = _run_sim(seed=1, n_leads=200)
            r2 = _run_sim(seed=2, n_leads=200)
            lead_signature_1 = [
                (
                    row.lead_id,
                    row.converted_within_90_days,
                    row.current_stage,
                    row.conversion_timestamp,
                )
                for row in r1.leads
            ]
            lead_signature_2 = [
                (
                    row.lead_id,
                    row.converted_within_90_days,
                    row.current_stage,
                    row.conversion_timestamp,
                )
                for row in r2.leads
            ]
            assert (
                lead_signature_1 != lead_signature_2
                or len(r1.touches) != len(r2.touches)
                or len(r1.sessions) != len(r2.sessions)
                or len(r1.opportunities) != len(r2.opportunities)
            )
    ~~~

## COPILOT-3
Location: leadforge/simulation/engine.py
URL: https://github.com/leadforge-dev/leadforge/pull/12#discussion_r3152275907
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    `sim_rng` is used for *all* simulation randomness (daily events, stage hazards, and post-loop ACV sampling). This couples unrelated outputs: e.g., changing touch/session logic will shift the RNG state and therefore change ACV/opportunity values, producing large diffs and making components less stream-independent. Consider splitting into multiple `RNGRoot(config.seed).child(...)` substreams (e.g., transitions/churn, events, and post_sim/acv) to keep outputs stable when unrelated parts change (similar to `build_population()` using separate `population_*` streams).
    ~~~suggestion
        transition_rng = root.child("simulation/transitions")
        event_rng = root.child("simulation/events")
        post_sim_rng = root.child("simulation/post_sim")
        acv_rng = post_sim_rng.child("acv")
        sim_rng = event_rng
    ~~~

## COPILOT-4
Location: leadforge/simulation/engine.py:334
URL: https://github.com/leadforge-dev/leadforge/pull/12#discussion_r3152275932
Root author: copilot-pull-request-reviewer

Comment:
    `conv_ts` is computed from `state.conversion_day` but remains typed as `str | None`, and later gets passed into `CustomerRow.customer_start_at` / `SubscriptionRow.subscription_start_at` via `# type: ignore[arg-type]`. Since this block only runs when `state.converted` is true, consider narrowing `conv_ts` to a non-optional `str` (e.g., `assert conv_ts is not None` or a separate `conv_ts_str`) so the ignores can be removed and a future refactor can’t silently introduce `None` values.

## COPILOT-5
Location: leadforge/simulation/engine.py
URL: https://github.com/leadforge-dev/leadforge/pull/12#discussion_r3152275955
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    In the `SubscriptionRow(...)` call, `subscription_status` is mis-indented relative to the other keyword args. While it won’t change semantics inside parentheses, it hurts readability and is easy to miss in reviews; consider aligning it with the other fields (and, if you apply the `conv_ts` narrowing, drop the `# type: ignore[arg-type]` here as well).
    ~~~suggestion
                            subscription_status="active",
    ~~~

## COPILOT-6
Location: leadforge/simulation/state.py:80
URL: https://github.com/leadforge-dev/leadforge/pull/12#discussion_r3152275979
Root author: copilot-pull-request-reviewer

Comment:
    `LeadSimState.sql_day` docstring says it records the first day the lead reached the `sql` stage “(or equivalent deeper stage)”, but `advance_stage()` only sets `sql_day` when `new_stage == "sql"`. Either update the docstring to match the implementation, or broaden the condition to record the first transition into any SQL-or-deeper stage so opportunity timestamps remain correct even if the stage sequence changes later.

Run metadata:

Tool ref: v4
Tool version: 4.0.20
Trigger: commit pushed
Workflow run: 25040688823 attempt 1
Comment timestamp: 2026-04-28T07:50:13.541028+00:00
PR head commit: a1723babd2f66c8863f692a9357aebafce17cf8d