demo: add demo_project fixture + scripts/demo.sh walkthrough

[trouze]

Summary

Adds a longer-running, bigger-DAG fixture plus a narrated scripts/demo.sh designed for recording. The existing dbt_dugout fixture is sub-second — the cost overlay there collapses to the 60s min-billing floor, which is great for testing but a flat demo.

The new tests/fixtures/demo_project/ fixture is a synthetic 24-model baseball-analytics DAG scheduled across 4 threads. Shaped so:

• Shared bottleneck — int_game_events (182s) is the slowest model on 3 of the top 5 longest paths. Showcases the analyze Bottleneck column and the shared-node-leverage story.
• Meaningful cost numbers on --warehouse-size L — ~7.5 min wall-clock (min-billing floor doesn't fire), $2.04 run cost, $0.10 headroom (5%), $0.61 idle cost (30%).
• Regenerable — tests/fixtures/generate_demo_fixture.py runs a discrete-event scheduler to produce the JSONs deterministically; change a time or add a node and re-run.

Demo walkthrough

./scripts/demo.sh

Narrated PAUSE between commands (PAUSE=0 to dry-run). Drives: analyze, analyze --show-path, replay, replay --warehouse-size L, contrast with --warehouse-size XL, non-Snowflake path via --credits-per-hour, and --format json | jq.

What the demo shows

Step	Command	Signal
1-3	analyze [--show-path]	int_game_events bottlenecks 3/5 top paths
4	replay	63% thread idleness — DAG is critical-path-bound
5	replay --warehouse-size L	$2.04 run / $1.94 floor / $0.10 headroom / $0.61 idle cost
6	--warehouse-size XL	same run, 2× cost
7	--credits-per-hour 12 --rate-per-credit 1.5	non-Snowflake escape hatch
8	--format json | jq .cost	machine-readable pivot

Tests

tests/test_demo_fixture.py (4 tests) locks the fixture's headline shape so topology changes don't silently break the recorded demo:

• event count (48), thread count (4), wall-clock in 400-600s range
• top path terminates at fct_batter_vs_pitcher and includes int_game_events
• int_game_events is the bottleneck on ≥3 of the top 5 paths
• L-warehouse cost has positive headroom, positive idle cost, waste_fraction > 20%

Full suite: 57 passed (was 53). ruff + mypy --strict clean. act -j test green locally.

Test plan

• uv run pytest — 57/57 pass
• uv run ruff check . clean
• uv run mypy --strict src clean
• act -j test (py3.12) green locally
• scripts/demo.sh PAUSE=0 completes all 8 sections without error
• Record the demo

🤖 Generated with Claude Code