Theme B: Sampling

# learning/code/ex-13-random-sample/random_sample.py
"""Worked Example 13: A Random Sample."""  # => co-07: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => hygiene: postpones annotation evaluation, interpreter-version-agnostic
 
import random  # => co-07: draws the random samples this example estimates from
import statistics  # => co-02: averages many independent random-sample estimates
 
POPULATION_SIZE = 2000  # => co-07: the full pool of real cases a random sample is drawn FROM
TRUE_PASS_RATE = 0.85  # => co-02: the population's real, unobservable pass rate
SAMPLE_SIZE = 60  # => co-07: cases drawn per sample
REPEATS = 300  # => co-02: independent samples, to check the estimator's own long-run behavior
 
 
def build_population(true_rate: float, size: int, *, seed: int) -> list[bool]:  # => co-07: a FIXED, finite population of pass/fail outcomes
    """Build a finite population of size `size` cases, each True (pass) with probability true_rate."""  # => co-07: documents build_population's contract -- no runtime output, just sets its __doc__
    rng = random.Random(seed)  # => co-07: one fixed generator -- the population itself does not change across samples
    return [rng.random() < true_rate for _ in range(size)]  # => co-07: one Bernoulli draw per case in the population
 
 
if __name__ == "__main__":  # => co-07: entry point -- runs only when this file executes directly, not on import
    population = build_population(TRUE_PASS_RATE, POPULATION_SIZE, seed=1)  # => co-07: the FIXED population every sample below draws from
    actual_population_rate = sum(population) / POPULATION_SIZE  # => co-07: the population's own realized rate (close to, not exactly, TRUE_PASS_RATE)
    print(f"Population size: {POPULATION_SIZE} | actual population pass rate: {actual_population_rate:.4f}")  # => co-07
 
    one_sample = random.Random(10).sample(population, SAMPLE_SIZE)  # => co-07: ONE random sample, drawn without replacement
    one_estimate = sum(one_sample) / SAMPLE_SIZE  # => co-02: this sample's own pass-rate estimate
    print(f"One random sample (n={SAMPLE_SIZE}) estimate: {one_estimate:.4f}")  # => co-02: what a single team would observe
 
    estimates = [sum(random.Random(100 + i).sample(population, SAMPLE_SIZE)) / SAMPLE_SIZE for i in range(REPEATS)]  # => co-02: many INDEPENDENT random samples
    average_estimate = statistics.mean(estimates)  # => co-02: the estimator's long-run average across repeats
    print(f"Average estimate across {REPEATS} independent random samples: {average_estimate:.4f}")  # => co-02
    gap = abs(average_estimate - actual_population_rate)  # => co-02: how close the long-run average lands to the population's own true rate
    print(f"Gap to the population's actual rate: {gap:.4f}")  # => co-02
    assert gap < 0.01, "the average of many independent random-sample estimates must land close to the population's actual rate"  # => co-07
    print("MATCH: random sampling is unbiased -- no systematic pull toward any particular subset of the population")  # => co-07
    # => co-07: this is the sampling strategy every other strategy in this theme is compared against -- unbiased, but ex-17 shows it can still MISS rare structure

Population size: 2000 | actual population pass rate: 0.8465
One random sample (n=60) estimate: 0.8167
Average estimate across 300 independent random samples: 0.8469
Gap to the population's actual rate: 0.0004
MATCH: random sampling is unbiased -- no systematic pull toward any particular subset of the population

# learning/code/ex-14-convenience-sample-bias/convenience_sample_bias.py
"""Worked Example 14: Convenience Sample Bias."""  # => co-07: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => hygiene: postpones annotation evaluation, interpreter-version-agnostic
 
import random  # => co-07: builds the population and draws both the random and the convenience sample
 
POPULATION_SIZE = 2000  # => co-07: the full pool of real cases
TRUE_PASS_RATE = 0.85  # => co-07: the population's real, unobservable pass rate
RANDOM_SAMPLE_SIZE = 60  # => co-07: an honest random sample's size, for direct comparison
 
 
if __name__ == "__main__":  # => co-07: entry point -- runs only when this file executes directly, not on import
    rng = random.Random(3)  # => co-07: builds the fixed population this whole example draws from
    population = [rng.random() < TRUE_PASS_RATE for _ in range(POPULATION_SIZE)]  # => co-07: one Bernoulli draw per case
    actual_rate = sum(population) / POPULATION_SIZE  # => co-07: the population's own realized pass rate
    print(f"Population's actual pass rate: {actual_rate:.4f}")  # => co-07: the ground truth this example compares both samples against
 
    random_sample = random.Random(50).sample(population, RANDOM_SAMPLE_SIZE)  # => co-07: an honest, unbiased random sample
    random_estimate = sum(random_sample) / RANDOM_SAMPLE_SIZE  # => co-07: its resulting estimate
    print(f"Random sample (n={RANDOM_SAMPLE_SIZE}) estimate: {random_estimate:.4f}")  # => co-07
 
    fail_indices = [i for i, passed in enumerate(population) if not passed]  # => co-07: "the failures someone happened to notice" pool -- ALL of them, over-represented
    pass_indices = [i for i, passed in enumerate(population) if passed]  # => co-07: passes get noticed only incidentally, almost never on purpose
    noticed_failures = random.Random(51).sample(fail_indices, min(40, len(fail_indices)))  # => co-07: a support team collects failures they happened to see
    noticed_passes = random.Random(51).sample(pass_indices, 5)  # => co-07: a handful of passes noticed only by accident
    convenience_indices = noticed_failures + noticed_passes  # => co-07: the whole "convenience sample" -- NOT drawn at random from the population
    convenience_estimate = sum(population[i] for i in convenience_indices) / len(convenience_indices)  # => co-07: this sample's resulting estimate
    print(f"Convenience sample (n={len(convenience_indices)}, 'cases someone noticed') estimate: {convenience_estimate:.4f}")  # => co-07
 
    random_error = abs(random_estimate - actual_rate)  # => co-07: how far the honest random sample's estimate is from the truth
    convenience_error = abs(convenience_estimate - actual_rate)  # => co-07: how far the convenience sample's estimate is from the truth
    print(f"Random sample error: {random_error:.4f} | Convenience sample error: {convenience_error:.4f}")  # => co-07
    assert convenience_error > 5 * random_error, "the convenience sample's error must be dramatically larger than the random sample's"  # => co-07: the bias claim itself
    print("MATCH: a convenience sample of failures someone happened to notice estimates almost nothing about the true rate")  # => co-07
    # => co-07: this is why 'we collected the bugs users reported' is not a sampling strategy -- it is a strategy for finding bugs, not for estimating a rate

Population's actual pass rate: 0.8470
Random sample (n=60) estimate: 0.7833
Convenience sample (n=45, 'cases someone noticed') estimate: 0.1111
Random sample error: 0.0637 | Convenience sample error: 0.7359
MATCH: a convenience sample of failures someone happened to notice estimates almost nothing about the true rate

# learning/code/ex-15-stratified-sample/stratified_sample.py
"""Worked Example 15: A Stratified Sample."""  # => co-08: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => hygiene: postpones annotation evaluation, interpreter-version-agnostic
 
import random  # => co-07: builds each stratum's population and draws both sampling strategies
from collections import Counter  # => co-07: tallies per-stratum representation in the random sample
 
STRATA_SIZES = {"formatting": 1400, "factual": 500, "tone": 100}  # => co-08: population counts per failure-mode stratum -- very unequal sizes
STRATA_PASS_RATE = {"formatting": 0.90, "factual": 0.75, "tone": 0.60}  # => co-08: each stratum has its own true pass rate
STRATIFIED_N_PER_STRATUM = 20  # => co-08: fixed count drawn from EACH stratum, regardless of the stratum's own population size
 
 
def build_stratum(pass_rate: float, size: int, *, seed: int) -> list[bool]:  # => co-08: one failure-mode stratum's own population
    """Build a stratum population of size `size`, each True (pass) with probability pass_rate."""  # => co-08: documents build_stratum's contract -- no runtime output, just sets its __doc__
    rng = random.Random(seed)  # => co-08: one fixed generator per stratum
    return [rng.random() < pass_rate for _ in range(size)]  # => co-08: one Bernoulli draw per case in this stratum
 
 
if __name__ == "__main__":  # => co-08: entry point -- runs only when this file executes directly, not on import
    population_by_stratum = {s: build_stratum(STRATA_PASS_RATE[s], n, seed=4) for s, n in STRATA_SIZES.items()}  # => co-08: three separate, fixed strata populations
    pooled = [(s, c) for s, cases in population_by_stratum.items() for c in cases]  # => co-07: the SAME population, viewed as one pooled list -- what plain random sampling would draw from
    for s, cases in population_by_stratum.items():  # => co-08: prints each stratum's own size and true rate up front
        print(f"{s:<12} population={len(cases):>5}  true_rate={sum(cases) / len(cases):.4f}")  # => co-08
 
    random_sample = random.Random(60).sample(pooled, 60)  # => co-07: an honest, proportional random sample of the SAME total size as the stratified one below
    random_counts = Counter(s for s, _ in random_sample)  # => co-07: how many of each stratum a plain random sample happened to include
    print(f"Random sample (n=60) per-stratum coverage: {dict(random_counts)}")  # => co-07: the tiny "tone" stratum barely appears
    assert random_counts["tone"] < STRATIFIED_N_PER_STRATUM, "a proportional random sample must under-represent the small 'tone' stratum relative to a stratified draw"  # => co-08
 
    stratified_counts = {}  # => co-08: one deliberate sample size per stratum
    for s, cases in population_by_stratum.items():  # => co-08: draws EXACTLY STRATIFIED_N_PER_STRATUM from every stratum, regardless of its own size
        sample = random.Random(70).sample(cases, STRATIFIED_N_PER_STRATUM)  # => co-08: the deliberate, guaranteed-coverage draw
        stratified_counts[s] = len(sample)  # => co-08: records this stratum's own guaranteed count
    print(f"Stratified sample per-stratum coverage: {stratified_counts}")  # => co-08: every stratum, equally represented
    assert all(count == STRATIFIED_N_PER_STRATUM for count in stratified_counts.values()), "every stratum must be equally represented under stratified sampling"  # => co-08
    print("MATCH: stratified sampling guarantees every stratum's coverage; random sampling leaves it to chance")  # => co-08
    # => co-07,co-08: random and stratified sampling literally estimate DIFFERENT things when strata are unequal -- ex-16 shows how to combine stratified counts back into one honest population estimate

formatting   population= 1400  true_rate=0.8993
factual      population=  500  true_rate=0.6960
tone         population=  100  true_rate=0.6200
Random sample (n=60) per-stratum coverage: {'formatting': 44, 'factual': 14, 'tone': 2}
Stratified sample per-stratum coverage: {'formatting': 20, 'factual': 20, 'tone': 20}
MATCH: stratified sampling guarantees every stratum's coverage; random sampling leaves it to chance

# learning/code/ex-16-reweight-a-stratified-estimate/reweight_stratified.py
"""Worked Example 16: Reweight a Stratified Estimate."""  # => co-08: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => hygiene: postpones annotation evaluation, interpreter-version-agnostic
 
import random  # => co-08: builds each stratum's population and draws the stratified sample
 
STRATA_SIZES = {"formatting": 1400, "factual": 500, "tone": 100}  # => co-08: population counts per stratum -- the SAME fixture as ex-15
STRATA_PASS_RATE = {"formatting": 0.90, "factual": 0.75, "tone": 0.60}  # => co-08: each stratum's own true pass rate
POPULATION_TOTAL = sum(STRATA_SIZES.values())  # => co-08: the full population size across all strata
N_PER_STRATUM = 20  # => co-08: fixed draw per stratum -- OVERSAMPLES "tone", which is only 5% of the population but 33% of this sample
 
 
def build_stratum(pass_rate: float, size: int, *, seed: int) -> list[bool]:  # => co-08: one failure-mode stratum's own population
    """Build a stratum population of size `size`, each True (pass) with probability pass_rate."""  # => co-08: documents build_stratum's contract -- no runtime output, just sets its __doc__
    rng = random.Random(seed)  # => co-08: one fixed generator per stratum
    return [rng.random() < pass_rate for _ in range(size)]  # => co-08: one Bernoulli draw per case in this stratum
 
 
if __name__ == "__main__":  # => co-08: entry point -- runs only when this file executes directly, not on import
    population_by_stratum = {s: build_stratum(STRATA_PASS_RATE[s], n, seed=4) for s, n in STRATA_SIZES.items()}  # => co-08: the SAME three strata populations ex-15 built
    true_overall_rate = sum(sum(cases) for cases in population_by_stratum.values()) / POPULATION_TOTAL  # => co-08: the population's own TRUE overall pass rate, weighted by real stratum sizes
    print(f"True overall population pass rate: {true_overall_rate:.4f}")  # => co-08: the ground truth every estimate below is compared against
 
    stratum_samples = {s: random.Random(70 + i).sample(cases, N_PER_STRATUM) for i, (s, cases) in enumerate(population_by_stratum.items())}  # => co-08: one equal-sized sample per stratum
    stratum_means = {s: sum(sample) / len(sample) for s, sample in stratum_samples.items()}  # => co-08: each stratum's own sample-based pass-rate estimate
    print(f"Per-stratum sample means: { {s: round(m, 4) for s, m in stratum_means.items()} }")  # => co-08
 
    naive_pooled_estimate = sum(sum(sample) for sample in stratum_samples.values()) / sum(len(sample) for sample in stratum_samples.values())  # => co-08: WRONG -- treats every stratum as equally common
    print(f"Naive (unweighted) pooled estimate: {naive_pooled_estimate:.4f}")  # => co-08: biased toward the over-sampled "tone" stratum's lower rate
 
    reweighted_estimate = sum(stratum_means[s] * (STRATA_SIZES[s] / POPULATION_TOTAL) for s in STRATA_SIZES)  # => co-08: weight each stratum's mean by its REAL population share
    print(f"Reweighted (population-share-weighted) estimate: {reweighted_estimate:.4f}")  # => co-08: recovers the population structure the sample itself distorted
 
    naive_error = abs(naive_pooled_estimate - true_overall_rate)  # => co-08: how far the naive pooled estimate misses the truth
    reweighted_error = abs(reweighted_estimate - true_overall_rate)  # => co-08: how far the reweighted estimate misses the truth
    print(f"Naive error: {naive_error:.4f} | Reweighted error: {reweighted_error:.4f}")  # => co-08
    assert reweighted_error < naive_error, "reweighting by population share must reduce the error versus the naive unweighted pool"  # => co-08: the reweighting claim itself
    print("MATCH: reweighting by each stratum's TRUE population share recovers a far more honest overall estimate")  # => co-08
    # => co-08: oversampling a rare stratum for statistical power is fine -- but pooling it back WITHOUT reweighting silently distorts the overall number

True overall population pass rate: 0.8345
Per-stratum sample means: {'formatting': 0.8, 'factual': 0.8, 'tone': 0.6}
Naive (unweighted) pooled estimate: 0.7333
Reweighted (population-share-weighted) estimate: 0.7900
Naive error: 0.1012 | Reweighted error: 0.0445
MATCH: reweighting by each stratum's TRUE population share recovers a far more honest overall estimate

# learning/code/ex-17-rare-mode-invisible/rare_mode_invisible.py
"""Worked Example 17: A Rare Mode Is Invisible at This Sample Size."""  # => co-08: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => hygiene: postpones annotation evaluation, interpreter-version-agnostic
 
import random  # => co-08: builds the population and draws both the random and the stratified sample
 
POPULATION_SIZE = 5000  # => co-08: a realistic-sized pool of logged cases
RARE_PREVALENCE = 0.01  # => co-08: the rare failure mode's TRUE prevalence -- 1 in 100 cases
RANDOM_SAMPLE_SIZE = 50  # => co-08: a typical small eval-set size
 
 
if __name__ == "__main__":  # => co-08: entry point -- runs only when this file executes directly, not on import
    rng = random.Random(5)  # => co-08: builds the fixed population every sample below draws from
    population = [rng.random() < RARE_PREVALENCE for _ in range(POPULATION_SIZE)]  # => co-08: True = this case exhibits the rare failure mode
    actual_count = sum(population)  # => co-08: how many rare-mode cases genuinely exist in the population
    print(f"Population: {POPULATION_SIZE} cases, {actual_count} exhibit the rare mode ({actual_count / POPULATION_SIZE:.4f})")  # => co-08
 
    random_sample_idx = random.Random(80).sample(range(POPULATION_SIZE), RANDOM_SAMPLE_SIZE)  # => co-08: an honest random draw, the OBVIOUS strategy
    rare_found_random = sum(population[i] for i in random_sample_idx)  # => co-08: how many rare-mode cases this random sample happened to include
    print(f"Rare-mode cases found in a random {RANDOM_SAMPLE_SIZE}-case sample: {rare_found_random}")  # => co-08: almost always zero
    assert rare_found_random == 0, "a random sample at this size must miss the rare mode entirely, for this example's own fixed seed"  # => co-08
 
    theoretical_miss_probability = (1 - RARE_PREVALENCE) ** RANDOM_SAMPLE_SIZE  # => co-08: P(every one of 50 draws misses a 1%-prevalence case)
    print(f"Theoretical probability a random {RANDOM_SAMPLE_SIZE}-case sample misses it entirely: {theoretical_miss_probability:.4f}")  # => co-08
    assert theoretical_miss_probability > 0.5, "missing a 1%-prevalence mode in 50 random draws must be MORE likely than not"  # => co-08: names the structural risk, not just this one draw
 
    rare_indices = [i for i, is_rare in enumerate(population) if is_rare]  # => co-08: the rare-mode stratum, identified deliberately
    common_indices = [i for i, is_rare in enumerate(population) if not is_rare]  # => co-08: everything else
    stratified_sample_idx = random.Random(90).sample(rare_indices, 10) + random.Random(91).sample(common_indices, 40)  # => co-08: DELIBERATELY draw 10 from the rare stratum
    rare_found_stratified = sum(population[i] for i in stratified_sample_idx)  # => co-08: how many rare-mode cases the stratified draw includes
    print(f"Rare-mode cases found in a stratified {len(stratified_sample_idx)}-case sample (10 from the rare stratum on purpose): {rare_found_stratified}")  # => co-08
    assert rare_found_stratified == 10, "a stratified sample drawing 10 from the rare stratum on purpose must find all 10"  # => co-08
    print("MATCH: random sampling structurally cannot be trusted to find a rare mode; deliberate stratification can")  # => co-08
    # => co-08: 'we didn't see it in the eval set' is not evidence a rare failure mode is gone -- it may just mean the sampling strategy could not have found it

Population: 5000 cases, 44 exhibit the rare mode (0.0088)
Rare-mode cases found in a random 50-case sample: 0
Theoretical probability a random 50-case sample misses it entirely: 0.6050
Rare-mode cases found in a stratified 50-case sample (10 from the rare stratum on purpose): 10
MATCH: random sampling structurally cannot be trusted to find a rare mode; deliberate stratification can

# learning/code/ex-18-sampling-frame-mismatch/sampling_frame_mismatch.py
"""Worked Example 18: A Sampling Frame Mismatch."""  # => co-07: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => hygiene: postpones annotation evaluation, interpreter-version-agnostic
 
import random  # => co-07: builds the simulated traffic log and draws the frame-based sample
 
N_TRAFFIC = 3000  # => co-07: total real requests a system actually received
TIMEOUT_RATE = 0.08  # => co-07: fraction of real requests that time out -- these NEVER complete, and never write a log line
PASS_RATE_AMONG_COMPLETED = 0.85  # => co-07: among requests that DO complete, the fraction judged a good answer
FRAME_SAMPLE_SIZE = 80  # => co-07: cases drawn from the (incomplete) sampling frame
 
 
if __name__ == "__main__":  # => co-07: entry point -- runs only when this file executes directly, not on import
    rng = random.Random(6)  # => co-07: builds the fixed simulated traffic this whole example draws from
    all_traffic: list[tuple[str, bool]] = []  # => co-07: every REAL request, whether or not it ever reaches the completion log
    for _ in range(N_TRAFFIC):  # => co-07: simulate the full real traffic stream, timeouts included
        if rng.random() < TIMEOUT_RATE:  # => co-07: this request times out -- the user got no answer at all
            all_traffic.append(("timeout", False))  # => co-07: counts as a failed interaction from the user's point of view, but writes NO log line
        else:  # => co-07: this request completes and gets scored normally
            passed = rng.random() < PASS_RATE_AMONG_COMPLETED  # => co-07: whether the completed answer was judged good
            all_traffic.append(("completed", passed))  # => co-07: this request DOES appear in the completion log
 
    true_rate_all_traffic = sum(1 for _, passed in all_traffic if passed) / len(all_traffic)  # => co-07: the honest question -- "does a real user get a good answer" -- timeouts count as failures
    print(f"True pass rate over ALL real traffic (timeouts count as failures): {true_rate_all_traffic:.4f}")  # => co-07
 
    log_frame = [passed for kind, passed in all_traffic if kind == "completed"]  # => co-07: the SAMPLING FRAME -- what the completion log actually contains
    print(f"Completion-log frame size: {len(log_frame)} of {N_TRAFFIC} total requests ({len(log_frame) / N_TRAFFIC:.1%})")  # => co-07: the frame is SMALLER than the real population, by construction
 
    frame_sample = random.Random(95).sample(log_frame, FRAME_SAMPLE_SIZE)  # => co-07: an HONEST random sample -- but drawn from the wrong frame
    frame_estimate = sum(frame_sample) / FRAME_SAMPLE_SIZE  # => co-07: this sample's resulting estimate
    print(f"Estimate from sampling the completion log: {frame_estimate:.4f}")  # => co-07: looks like a normal, well-sampled number
 
    gap = frame_estimate - true_rate_all_traffic  # => co-07: the systematic gap this mismatch introduces -- NOT sampling error, a different question entirely
    print(f"Gap between the frame estimate and the true all-traffic rate: {gap:.4f}")  # => co-07
    assert gap > 0.05, "sampling only the completion log must overstate the true all-traffic pass rate by a material margin"  # => co-07: the mismatch claim itself
    print("MATCH: a perfectly honest random sample of the WRONG frame still answers the WRONG question")  # => co-07
    # => co-07: 'we sampled at random' is necessary but not sufficient -- the sampling frame itself must match the population the decision is actually about

True pass rate over ALL real traffic (timeouts count as failures): 0.7807
Completion-log frame size: 2734 of 3000 total requests (91.1%)
Estimate from sampling the completion log: 0.8500
Gap between the frame estimate and the true all-traffic rate: 0.0693
MATCH: a perfectly honest random sample of the WRONG frame still answers the WRONG question

# learning/code/ex-20-sample-size-plan-for-an-eval-set/sampling_plan.py
"""Worked Example 20: A Sample-Size Plan for a Real Eval Set."""  # => co-24: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => hygiene: postpones annotation evaluation, interpreter-version-agnostic
 
import math  # => co-06: ceil -- a sample size must be a whole number of cases
from dataclasses import dataclass, field  # => co-24: a typed, structurally-required sampling-plan record
 
from statsmodels.stats.proportion import samplesize_confint_proportion  # => co-06: the pinned library's own sample-size solver
 
 
@dataclass(frozen=True)  # => co-24: frozen -- a written plan is a commitment made BEFORE collecting data, not something later code can quietly edit
class SamplingPlan:  # => co-24: the four fields a real sampling plan must state, per this theme's own discipline
    target_effect: str  # => co-06: what the plan is trying to be able to detect or estimate
    target_precision: float  # => co-06: the interval half-width the plan is designed to achieve
    strata: tuple[str, ...] = field(default_factory=tuple)  # => co-08: named strata this plan deliberately oversamples, if any
    required_n: int = 0  # => co-06: the resulting sample size -- computed, not guessed
 
 
def build_plan(*, anticipated_rate: float, target_precision: float, target_effect: str, strata: tuple[str, ...]) -> SamplingPlan:  # => co-24: the ONE function that produces a real plan
    """Solve for the required n and package it with the plan's stated effect, precision, and strata."""  # => co-24: documents build_plan's contract -- no runtime output, just sets its __doc__
    raw_n = samplesize_confint_proportion(proportion=anticipated_rate, half_length=target_precision, alpha=0.05, method="normal")  # => co-06: the SAME solver ex-08 used, now inside a reusable plan builder
    required_n = math.ceil(raw_n)  # => co-06: round UP -- a fractional case cannot be collected
    return SamplingPlan(target_effect=target_effect, target_precision=target_precision, strata=strata, required_n=required_n)  # => co-24: returns this computed value to the caller -- every field populated
 
 
if __name__ == "__main__":  # => co-24: entry point -- runs only when this file executes directly, not on import
    plan = build_plan(  # => co-24: a plan for a real, concrete eval-set decision
        anticipated_rate=0.82,  # => co-06: a pilot run's own observed rate, used to anticipate the target eval's rate
        target_precision=0.06,  # => co-06: "I need the interval within +/-6 points to make this ship decision"
        target_effect="baseline-vs-candidate pass-rate comparison for the eval-set decision",  # => co-06: states WHAT the plan is trying to support
        strata=("rare-failure-mode-A", "rare-failure-mode-B"),  # => co-08: two rare failure modes this plan will deliberately oversample, per ex-15/ex-17
    )  # => co-24: closes the build_plan call
    print(f"Target effect: {plan.target_effect}")  # => co-06: states the effect explicitly, first
    print(f"Target precision (half-width): {plan.target_precision}")  # => co-06: states the precision explicitly
    print(f"Deliberately oversampled strata: {plan.strata}")  # => co-08: states the strata explicitly
    print(f"Required n: {plan.required_n}")  # => co-06: the resulting number -- computed, not chosen by feel
 
    assert plan.target_effect != "", "a sampling plan must state its target effect"  # => co-24: the four required-fields check, one assertion per field
    assert plan.target_precision > 0, "a sampling plan must state a positive target precision"  # => co-24
    assert len(plan.strata) > 0, "this plan must name its deliberately oversampled strata"  # => co-24
    assert plan.required_n > 0, "a sampling plan must state a computed, justified n"  # => co-24
    print("MATCH: this plan states target effect, precision, strata, and n -- BEFORE a single case is drawn")  # => co-24
    # => co-06,co-08,co-24: this is the written artifact the capstone's own sampling-plan.md step produces for a real shipping decision

Target effect: baseline-vs-candidate pass-rate comparison for the eval-set decision
Target precision (half-width): 0.06
Deliberately oversampled strata: ('rare-failure-mode-A', 'rare-failure-mode-B')
Required n: 158
MATCH: this plan states target effect, precision, strata, and n -- BEFORE a single case is drawn