closed-loop-default-detection 0.2.0__tar.gz → 0.4.0__tar.gz

{closed_loop_default_detection-0.2.0 → closed_loop_default_detection-0.4.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: closed-loop-default-detection
-Version: 0.2.0
+Version: 0.4.0
 Summary: Closed loop that measures selective-labels default detection on synthetic SMB lending cohorts and finds the PD model's operating frontier.
-Author-email: Hossain Pazooki <hossain@pazooki.com>
+Author: Hossain Pazooki
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/hossainpazooki/closed-loop-default-detection
 Project-URL: Repository, https://github.com/hossainpazooki/closed-loop-default-detection
@@ -26,6 +26,7 @@ Requires-Dist: matplotlib>=3.8
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7; extra == "docs"
 Requires-Dist: furo; extra == "docs"
@@ -48,105 +49,14 @@ hides labels the way real approval policies do, and grades every correction agai
 - **Deterministic** — byte-identical per seed, scikit-learn-only, no services or GPUs.
 - **Pluggable** — correction levers (IPW, retrain, exploration, reject inference) are classes;
   add yours by subclassing `Corrector`.
-- **Honest by construction** — every number below recomputes from committed CSVs; limits are
-  reported, not smoothed over.
-
-## The result it produces
-
-The loop escalates selection severity until correction fails and reports the **operating
-frontier** — the last severity at which declined-cohort calibration still holds (target
-ECE ≤ 0.10). From the committed runs (`artifacts/loop_frontier*.csv`, seed 42):
-
-| Selection severity | 0.0 | 0.2 | 0.4 | 0.6 |
-|---|---|---|---|---|
-| Naive declined ECE (flat world) | 0.021 | 0.045 | 0.108 | 0.161 |
-| **IPW-corrected** (flat world) | 0.020 | 0.038 | **0.086 ✓** | **0.154 ✗** |
-| **IPW-corrected** (SCM world) | 0.036 | 0.038 | **0.097 ✓** | **0.244 ✗** |
-
-On **this seed** both worlds land the frontier at severity 0.4, and the counterfactual
-deliverable breaks at the same boundary: across 25 seeds, g-computation cuts
-strong-propagation counterfactual MAE from 0.099 to 0.086 (−13.5%, positive on 24/25 seeds,
-Wilcoxon p = 1.5e-7) *inside* the frontier — and collapses to a negligible +0.0017 at full
-severity, where **no deployable advantage is claimed**. One cause explains both: selection
-through an **unobserved confounder**, which backdoor adjustment and IPW cannot fix. That
-single measured limit — not an unverifiable score — is the deliverable.
-
-### The frontier is a distribution, not a point (v2)
-
-A frontier quoted from one seed is a figure published without an error bar. `v0.2.0` runs the
-loop across the full 25-seed set (`artifacts/frontier_sweep.csv`) — and **seed 42 turns out to
-sit at the optimistic end**:
-
-| World | min | median | max | seeds at 0.4 | seeds at 0.2 |
-|---|---|---|---|---|---|
-| flat | 0.2 | **0.4** | 0.4 | 15/25 | 10/25 |
-| SCM | 0.2 | **0.2** | 0.4 | 11/25 | 14/25 |
-
-In the SCM world the *majority of seeds fail one step earlier than the headline*: the median
-frontier is **0.2**, and seed 42's 0.4 is a minority outcome (11/25). The honest statement is
-that the operating frontier is **0.2–0.4 depending on the draw**, not a clean 0.4 — the
-single-seed table above is a valid instance of it, not its center. Nothing about the
-mechanism changes (the unobserved confounder still explains the failure); what changes is how
-precisely the boundary can be quoted.
-
-*Caveat on the sweep:* loop seed `s` consumes generator seeds `s..s+7`, and the 25-seed set has
-gaps smaller than 8, so some runs share feature draws. No two runs duplicate a cohort, but the
-25 rows are not fully independent — the set is kept for comparability with the counterfactual
-sweep that uses it.
-
-Reproduce the headline from committed evidence: `python scripts/paired_significance.py`.
-The full independent assessment (methodology, all numbers, what didn't hold) is the
-accompanying article, [`docs/assessment.md`](docs/assessment.md) — a **dated snapshot**, written
-against the single-seed frontier and not retro-fitted with the distribution above.
-
-## Pricing the frontier (v2)
-
-Calibration says *whether* the model is wrong on the declines; it does not say **what being
-wrong costs**. v2 adds an expected-maximum-profit (EMP) reporting axis — computed from the
-same in-process scores the loop already measures, and **never** a loop-control input (ECE
-still decides pass/fail and the frontier). Two variants run side by side:
-
-| Variant | Parameters | What it answers |
-|---|---|---|
-| `empc` — literature EMPC | Verbraken et al. (2014) prior: `p0=0.55, p1=0.10, ROI=0.2644` | benchmark-comparable: what the standard measure says |
-| `emp_h` — harness-derived | this harness's own economics + **planted** default timing | what the loan structure actually pays |
-
-**The two disagree — and the disagreement is the finding.** In the SCM world they move in
-opposite directions as selection severity rises (from `artifacts/loop_frontier_scm.csv`,
-declined subpopulation, seed 42):
-
-| Selection severity | 0.0 | 0.2 | 0.4 | 0.6 |
-|---|---|---|---|---|
-| Literature `empc` (naive) | 0.0217 | 0.0331 | 0.0416 | **0.0420 ↑** |
-| Harness `emp_h` (naive) | 0.0387 | 0.0297 | 0.0139 | **0.0024 ↓** |
-
-The convenience prior **misprices this loan structure**: it assumes `ROI = 0.2644` where a
-60-day daily-ACH loan actually returns `0.0875` (3% origination fee + 5.75% term interest) —
-a **3.0× overstatement** — and puts **55% of defaults at full recovery where the harness plants
-1.2%** (prior mean λ = 0.275 vs harness 0.419). Priced honestly, the profit on the declined
-pool collapses to near-zero at the frontier; priced by the literature prior, it appears to
-*grow*. Same model, same scores, opposite conclusion.
-
-**Reading caveats — the boundary of what this measures:**
-
-- **Raw EMP moves with world hardness.** A riskier declined pool changes EMP even for a
-  perfect model, so a cross-severity EMP delta is *not* pure model signal. Read the two
-  variants against each other at fixed severity, not the trend in isolation.
-- **`emp_h` rests on unfitted timing.** `days_to_default` is planted but independent of
-  features and risk given default — spec-shaped, never validated against real recovery data.
-  So `emp_h` is a **verified experiment, not a verified result**: the arithmetic is exact, the
-  timing distribution is an assumption.
-- **Post-term defaults are imputed.** ~22.5% of planted defaults land at day 90, past the
-  60-day term, and the generator does not model their payment history; they are priced at the
-  cohort's mean in-term loss fraction (a stated convention, not measured truth).
-- **`emp_h` is SCM-only.** The flat generator plants no timing, so its `emp_h` columns are
-  empty by design; only `empc` is reported there.
-
-Exploration now carries a price tag too. From `artifacts/exploration_frontier.csv` (SCM,
-seed 42, 10% budget, severity 0.6): the lever buys **157 labels for $439,578** — about
-**$2,800 per label**, of which 56 are realized defaults. That is the cost of *identification*,
-in dollars a lender can see, on the only lever that buys it rather than reweighting what is
-already identified.
+- **Honest by construction** — every results figure registered in the doc-number gate
+  recomputes from a committed CSV in CI, and every artifact is pinned by content hash; the
+  results and their limits are in [docs/results.md](docs/results.md).
+
+> **What this is — and is not.** CLDD is a *validation harness* graded against planted
+> synthetic ground truth; it is **not a credit-modeling toolkit**. The correction levers it
+> ships (IPW, retrain, exploration, reject inference) exist to be *measured against a known
+> answer* — nothing in this repo is validated for making decisions on real borrower data.
 
 ## Install
 
@@ -248,17 +158,18 @@ python scripts/paired_significance.py         # recompute the headline stat from
 
 ## Validation
 
-`pytest` — 149 tests, all synthetic, no real data needed. CI runs a pinned-repro job (exact
-pins), a cross-version/OS compat matrix, and a strict docs build. Six float-sensitive tests
-reproduce only under the pins in `requirements-dev.txt`; the optional marginal-fidelity gate
-compares the SCM against a **private** real dataset via `CLDD_DATA_DIR` and is the only thing
-that needs it. Details, reproducibility, and troubleshooting:
-[docs/validation.md](docs/validation.md).
+`pytest`, all synthetic, no real data needed. CI runs a pinned-repro job (exact pins), a
+cross-version/OS compat matrix, and a strict docs build; a doc-number gate recomputes every
+registered figure in the docs from a committed artifact. A few float-sensitive tests reproduce
+only under the pins in `requirements-dev.txt`; the optional marginal-fidelity gate compares
+the SCM against a **private** real dataset via `CLDD_DATA_DIR` and is the only thing that
+needs it. Details, reproducibility, and troubleshooting: [docs/validation.md](docs/validation.md).
 
 ## Documentation
 
 | Where | What |
 |---|---|
+| [docs/results.md](docs/results.md) | **every measured result** — the frontier and its distribution, the v4 intervention, the two pre-registered experiments, the two pricing layers |
 | [docs/quickstart.md](docs/quickstart.md) | run the loop, the counterfactual eval, the fidelity report |
 | [docs/how-it-works.md](docs/how-it-works.md) | loop mechanics, diagnostics, feedback simulation, repo map |
 | [docs/configuration.md](docs/configuration.md) | every knob (`config.py`) and the one env var |
@@ -270,12 +181,8 @@ Build locally: `pip install -e ".[docs]" && sphinx-build -b html -W docs docs/_b
 
 ## Status
 
-`0.2.0` **alpha** on [PyPI](https://pypi.org/project/closed-loop-default-detection/),
-changelog in [CHANGELOG.md](CHANGELOG.md).
-
-Shipped in 0.1.0: the loop, both synthetic worlds, all correction levers, the fidelity gate,
-the sklearn estimator, CI on three gates. Added in 0.2.0: `cldd.emp` (both EMP variants),
-priced exploration, the EMP-optimal cutoff, and the 25-seed frontier sweep.
+**Alpha**, on [PyPI](https://pypi.org/project/closed-loop-default-detection/); version
+history in [CHANGELOG.md](CHANGELOG.md).
 
 CLDD began as a validation harness for the Intuit TechWeek SMB Underwriting Challenge; it is
 not a submission and does not alter challenge files.
@@ -290,7 +197,7 @@ Metadata in [`CITATION.cff`](CITATION.cff) (GitHub's "Cite this repository" read
   title   = {{closed-loop-default-detection}: measuring selective-labels default
              detection and the PD model's operating frontier},
   year    = {2026},
-  version = {0.2.0},
+  version = {0.4.0},
   license = {MIT},
   url     = {https://github.com/hossainpazooki/closed-loop-default-detection}
 }

{closed_loop_default_detection-0.2.0 → closed_loop_default_detection-0.4.0}/README.md

@@ -14,105 +14,14 @@ hides labels the way real approval policies do, and grades every correction agai
 - **Deterministic** — byte-identical per seed, scikit-learn-only, no services or GPUs.
 - **Pluggable** — correction levers (IPW, retrain, exploration, reject inference) are classes;
   add yours by subclassing `Corrector`.
-- **Honest by construction** — every number below recomputes from committed CSVs; limits are
-  reported, not smoothed over.
-
-## The result it produces
-
-The loop escalates selection severity until correction fails and reports the **operating
-frontier** — the last severity at which declined-cohort calibration still holds (target
-ECE ≤ 0.10). From the committed runs (`artifacts/loop_frontier*.csv`, seed 42):
-
-| Selection severity | 0.0 | 0.2 | 0.4 | 0.6 |
-|---|---|---|---|---|
-| Naive declined ECE (flat world) | 0.021 | 0.045 | 0.108 | 0.161 |
-| **IPW-corrected** (flat world) | 0.020 | 0.038 | **0.086 ✓** | **0.154 ✗** |
-| **IPW-corrected** (SCM world) | 0.036 | 0.038 | **0.097 ✓** | **0.244 ✗** |
-
-On **this seed** both worlds land the frontier at severity 0.4, and the counterfactual
-deliverable breaks at the same boundary: across 25 seeds, g-computation cuts
-strong-propagation counterfactual MAE from 0.099 to 0.086 (−13.5%, positive on 24/25 seeds,
-Wilcoxon p = 1.5e-7) *inside* the frontier — and collapses to a negligible +0.0017 at full
-severity, where **no deployable advantage is claimed**. One cause explains both: selection
-through an **unobserved confounder**, which backdoor adjustment and IPW cannot fix. That
-single measured limit — not an unverifiable score — is the deliverable.
-
-### The frontier is a distribution, not a point (v2)
-
-A frontier quoted from one seed is a figure published without an error bar. `v0.2.0` runs the
-loop across the full 25-seed set (`artifacts/frontier_sweep.csv`) — and **seed 42 turns out to
-sit at the optimistic end**:
-
-| World | min | median | max | seeds at 0.4 | seeds at 0.2 |
-|---|---|---|---|---|---|
-| flat | 0.2 | **0.4** | 0.4 | 15/25 | 10/25 |
-| SCM | 0.2 | **0.2** | 0.4 | 11/25 | 14/25 |
-
-In the SCM world the *majority of seeds fail one step earlier than the headline*: the median
-frontier is **0.2**, and seed 42's 0.4 is a minority outcome (11/25). The honest statement is
-that the operating frontier is **0.2–0.4 depending on the draw**, not a clean 0.4 — the
-single-seed table above is a valid instance of it, not its center. Nothing about the
-mechanism changes (the unobserved confounder still explains the failure); what changes is how
-precisely the boundary can be quoted.
-
-*Caveat on the sweep:* loop seed `s` consumes generator seeds `s..s+7`, and the 25-seed set has
-gaps smaller than 8, so some runs share feature draws. No two runs duplicate a cohort, but the
-25 rows are not fully independent — the set is kept for comparability with the counterfactual
-sweep that uses it.
-
-Reproduce the headline from committed evidence: `python scripts/paired_significance.py`.
-The full independent assessment (methodology, all numbers, what didn't hold) is the
-accompanying article, [`docs/assessment.md`](docs/assessment.md) — a **dated snapshot**, written
-against the single-seed frontier and not retro-fitted with the distribution above.
-
-## Pricing the frontier (v2)
-
-Calibration says *whether* the model is wrong on the declines; it does not say **what being
-wrong costs**. v2 adds an expected-maximum-profit (EMP) reporting axis — computed from the
-same in-process scores the loop already measures, and **never** a loop-control input (ECE
-still decides pass/fail and the frontier). Two variants run side by side:
-
-| Variant | Parameters | What it answers |
-|---|---|---|
-| `empc` — literature EMPC | Verbraken et al. (2014) prior: `p0=0.55, p1=0.10, ROI=0.2644` | benchmark-comparable: what the standard measure says |
-| `emp_h` — harness-derived | this harness's own economics + **planted** default timing | what the loan structure actually pays |
-
-**The two disagree — and the disagreement is the finding.** In the SCM world they move in
-opposite directions as selection severity rises (from `artifacts/loop_frontier_scm.csv`,
-declined subpopulation, seed 42):
-
-| Selection severity | 0.0 | 0.2 | 0.4 | 0.6 |
-|---|---|---|---|---|
-| Literature `empc` (naive) | 0.0217 | 0.0331 | 0.0416 | **0.0420 ↑** |
-| Harness `emp_h` (naive) | 0.0387 | 0.0297 | 0.0139 | **0.0024 ↓** |
-
-The convenience prior **misprices this loan structure**: it assumes `ROI = 0.2644` where a
-60-day daily-ACH loan actually returns `0.0875` (3% origination fee + 5.75% term interest) —
-a **3.0× overstatement** — and puts **55% of defaults at full recovery where the harness plants
-1.2%** (prior mean λ = 0.275 vs harness 0.419). Priced honestly, the profit on the declined
-pool collapses to near-zero at the frontier; priced by the literature prior, it appears to
-*grow*. Same model, same scores, opposite conclusion.
-
-**Reading caveats — the boundary of what this measures:**
-
-- **Raw EMP moves with world hardness.** A riskier declined pool changes EMP even for a
-  perfect model, so a cross-severity EMP delta is *not* pure model signal. Read the two
-  variants against each other at fixed severity, not the trend in isolation.
-- **`emp_h` rests on unfitted timing.** `days_to_default` is planted but independent of
-  features and risk given default — spec-shaped, never validated against real recovery data.
-  So `emp_h` is a **verified experiment, not a verified result**: the arithmetic is exact, the
-  timing distribution is an assumption.
-- **Post-term defaults are imputed.** ~22.5% of planted defaults land at day 90, past the
-  60-day term, and the generator does not model their payment history; they are priced at the
-  cohort's mean in-term loss fraction (a stated convention, not measured truth).
-- **`emp_h` is SCM-only.** The flat generator plants no timing, so its `emp_h` columns are
-  empty by design; only `empc` is reported there.
-
-Exploration now carries a price tag too. From `artifacts/exploration_frontier.csv` (SCM,
-seed 42, 10% budget, severity 0.6): the lever buys **157 labels for $439,578** — about
-**$2,800 per label**, of which 56 are realized defaults. That is the cost of *identification*,
-in dollars a lender can see, on the only lever that buys it rather than reweighting what is
-already identified.
+- **Honest by construction** — every results figure registered in the doc-number gate
+  recomputes from a committed CSV in CI, and every artifact is pinned by content hash; the
+  results and their limits are in [docs/results.md](docs/results.md).
+
+> **What this is — and is not.** CLDD is a *validation harness* graded against planted
+> synthetic ground truth; it is **not a credit-modeling toolkit**. The correction levers it
+> ships (IPW, retrain, exploration, reject inference) exist to be *measured against a known
+> answer* — nothing in this repo is validated for making decisions on real borrower data.
 
 ## Install
 
@@ -214,17 +123,18 @@ python scripts/paired_significance.py         # recompute the headline stat from
 
 ## Validation
 
-`pytest` — 149 tests, all synthetic, no real data needed. CI runs a pinned-repro job (exact
-pins), a cross-version/OS compat matrix, and a strict docs build. Six float-sensitive tests
-reproduce only under the pins in `requirements-dev.txt`; the optional marginal-fidelity gate
-compares the SCM against a **private** real dataset via `CLDD_DATA_DIR` and is the only thing
-that needs it. Details, reproducibility, and troubleshooting:
-[docs/validation.md](docs/validation.md).
+`pytest`, all synthetic, no real data needed. CI runs a pinned-repro job (exact pins), a
+cross-version/OS compat matrix, and a strict docs build; a doc-number gate recomputes every
+registered figure in the docs from a committed artifact. A few float-sensitive tests reproduce
+only under the pins in `requirements-dev.txt`; the optional marginal-fidelity gate compares
+the SCM against a **private** real dataset via `CLDD_DATA_DIR` and is the only thing that
+needs it. Details, reproducibility, and troubleshooting: [docs/validation.md](docs/validation.md).
 
 ## Documentation
 
 | Where | What |
 |---|---|
+| [docs/results.md](docs/results.md) | **every measured result** — the frontier and its distribution, the v4 intervention, the two pre-registered experiments, the two pricing layers |
 | [docs/quickstart.md](docs/quickstart.md) | run the loop, the counterfactual eval, the fidelity report |
 | [docs/how-it-works.md](docs/how-it-works.md) | loop mechanics, diagnostics, feedback simulation, repo map |
 | [docs/configuration.md](docs/configuration.md) | every knob (`config.py`) and the one env var |
@@ -236,12 +146,8 @@ Build locally: `pip install -e ".[docs]" && sphinx-build -b html -W docs docs/_b
 
 ## Status
 
-`0.2.0` **alpha** on [PyPI](https://pypi.org/project/closed-loop-default-detection/),
-changelog in [CHANGELOG.md](CHANGELOG.md).
-
-Shipped in 0.1.0: the loop, both synthetic worlds, all correction levers, the fidelity gate,
-the sklearn estimator, CI on three gates. Added in 0.2.0: `cldd.emp` (both EMP variants),
-priced exploration, the EMP-optimal cutoff, and the 25-seed frontier sweep.
+**Alpha**, on [PyPI](https://pypi.org/project/closed-loop-default-detection/); version
+history in [CHANGELOG.md](CHANGELOG.md).
 
 CLDD began as a validation harness for the Intuit TechWeek SMB Underwriting Challenge; it is
 not a submission and does not alter challenge files.
@@ -256,7 +162,7 @@ Metadata in [`CITATION.cff`](CITATION.cff) (GitHub's "Cite this repository" read
   title   = {{closed-loop-default-detection}: measuring selective-labels default
              detection and the PD model's operating frontier},
   year    = {2026},
-  version = {0.2.0},
+  version = {0.4.0},
   license = {MIT},
   url     = {https://github.com/hossainpazooki/closed-loop-default-detection}
 }

{closed_loop_default_detection-0.2.0 → closed_loop_default_detection-0.4.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "closed-loop-default-detection"
-version = "0.2.0"
+version = "0.4.0"
 description = "Closed loop that measures selective-labels default detection on synthetic SMB lending cohorts and finds the PD model's operating frontier."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 license-files = ["LICENSE"]
-authors = [{ name = "Hossain Pazooki", email = "hossain@pazooki.com" }]
+authors = [{ name = "Hossain Pazooki" }]
 keywords = [
     "selective-labels",
     "probability-of-default",
@@ -45,7 +45,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0", "pytest-cov>=5"]
+dev = ["pytest>=8.0", "pytest-cov>=5", "build>=1"]
 docs = ["sphinx>=7", "furo", "myst-parser>=2"]
 
 [project.urls]
@@ -70,7 +70,7 @@ markers = [
 # Coverage is opt-in (run `pytest --cov=cldd`); it is not wired into addopts so a
 # plain `pytest` stays lightweight. The private-data fidelity path (cldd/fidelity.py)
 # is only exercised when the real dataset is present, so its data-loading branch is
-# expected to be uncovered on public CI by design — see README.
+# expected to be uncovered on public CI by design — see docs/validation.md.
 [tool.coverage.run]
 source = ["cldd"]
 branch = true

{closed_loop_default_detection-0.2.0 → closed_loop_default_detection-0.4.0}/src/cldd/__init__.py

@@ -11,7 +11,7 @@ from importlib.metadata import PackageNotFoundError, version as _pkg_version
 try:  # pyproject `version` is the single source of truth (read from installed metadata)
     __version__ = _pkg_version("closed-loop-default-detection")
 except PackageNotFoundError:  # running from a source tree with no install
-    __version__ = "0.2.0"
+    __version__ = "0.4.0"
 
 from .correctors import (
     CorrectionOutcome,
@@ -57,6 +57,7 @@ from .scm import (
     dag_children,
     dag_parents,
 )
+from .selection import SegmentedSelection, knockout_rates
 from .synthetic import SyntheticBorrowerGenerator
 
 __all__ = [
@@ -105,4 +106,6 @@ __all__ = [
     "GComputationEstimator",
     "run_counterfactual_eval",
     "generate_queries",
+    "SegmentedSelection",
+    "knockout_rates",
 ]

{closed_loop_default_detection-0.2.0 → closed_loop_default_detection-0.4.0}/src/cldd/counterfactual.py

@@ -632,6 +632,7 @@ def run_counterfactual_eval(
     n_query_applicants: int = 300,
     seed: int = config.RANDOM_SEED,
     generator: StructuralBorrowerGenerator | None = None,
+    unobserved_strength: float | None = None,
 ) -> CounterfactualResult:
     """Build a cohort, generate Deliverable-C-style queries, grade the estimators.
 
@@ -644,13 +645,27 @@ def run_counterfactual_eval(
     Both deployable estimators are fit on the APPROVED rows only (selective-labels
     regime), so their conditionals are distorted by selection — exactly the
     confound g-computation's backdoor adjustment is meant to repair.
+
+    ``unobserved_strength`` (v4 surface knob) is forwarded to the internal
+    ``StructuralBorrowerGenerator`` construction only when ``generator`` is None;
+    the effective value is echoed in ``meta``. ``None`` (the default) is
+    byte-identical to the pre-knob path.
     """
+    if generator is not None and unobserved_strength is not None:
+        raise ValueError(
+            "unobserved_strength is forwarded to the internal generator "
+            "construction only; pass it OR a pre-built generator, not both "
+            "(silently ignoring it would let a driver drift from the eval)"
+        )
     if generator is None:
-        generator = StructuralBorrowerGenerator(
+        gen_kwargs: dict = dict(
             n_applicants=n_applicants,
             selection_severity=selection_severity,
             seed=seed,
         )
+        if unobserved_strength is not None:
+            gen_kwargs["unobserved_strength"] = unobserved_strength
+        generator = StructuralBorrowerGenerator(**gen_kwargs)
     cohort = generator.generate_cohort()
     state = cohort["scm_state"]
     features = cohort["features"]
@@ -763,5 +778,6 @@ def run_counterfactual_eval(
             "n_applicants": n_applicants,
             "seed": seed,
             "approval_rate": float(approved.mean()),
+            "unobserved_strength": float(generator.unobserved_strength),
         },
     )

{closed_loop_default_detection-0.2.0 → closed_loop_default_detection-0.4.0}/src/cldd/emp.py

@@ -1,7 +1,7 @@
 """Expected-maximum-profit (EMP) reporting layer — the v2 measurement axis.
 
 Prices the frontier the loop already measures; **never** a loop-control input
-(spec: ``docs/superpowers/specs/2026-07-13-cldd-v2-emp-design.md``). Two
+(spec: ``2026-07-13-cldd-v2-emp-design.md``). Two
 variants, side by side:
 
 * :func:`empc_literature` — the Verbraken/Bravo/Weber/Baesens EMPC closed form
@@ -18,7 +18,7 @@ of mean per-loan exposure** (exposure = ``requested_amount``), so the two
 columns are directly comparable. Both consume ``scores`` as a ranking only and
 are invariant to strictly monotone transforms.
 
-Reading caveats (documented in README + CSV column notes):
+Reading caveats (documented in docs/results.md + CSV column notes):
 
 * Planted default timing is **marginally spec-shaped but conditionally
   cosmetic** — independent of features/risk given default status — so harness
@@ -49,6 +49,7 @@ __all__ = [
     "emp_harness",
     "loss_fractions",
     "realized_profits",
+    "realized_book_profit",
 ]
 
 
@@ -304,6 +305,52 @@ def realized_profits(
     return profit
 
 
+def realized_book_profit(
+    y_true: np.ndarray,
+    default_day: np.ndarray | None,
+    requested_amount: np.ndarray,
+    funded: np.ndarray,
+    economics: LoanEconomics | None = None,
+) -> float | None:
+    """Realized book P&L of the funded rows, normalized by full-cohort exposure.
+
+    Reuses :func:`realized_profits` priced over the FULL cohort, then sums the
+    funded rows -- so day-90 rows take the decision-5 mean-body imputation with
+    the mean computed from the *cohort's* body defaulters (lambda = 1 fallback
+    when the cohort body is empty, see :func:`loss_fractions`). The basis is a
+    planted cohort property, invariant to who funds: pricing on the funded
+    slice's own body mean made book P&L non-additive across slices and broke
+    the H4 arithmetic identity at the pilot gate (spec Rev 2.1 amendment,
+    2026-07-19). Returns ``None`` when timing columns are absent (flat cohorts,
+    ``default_day is None``), mirroring :func:`emp_harness`. **SCM-only, like
+    everything in v3.**
+
+    Units: total realized profit of funded rows / (n_applicants * mean
+    ``requested_amount`` over the FULL cohort, not funded-only) -- profit per
+    applicant as a fraction of cohort mean exposure (v2 decision 6 extended);
+    the full-cohort denominator keeps arms with different funded counts
+    comparable and paired differences well-defined.
+
+    Pure numpy, zero RNG, deterministic.
+    """
+    if default_day is None:
+        return None
+
+    y_true = np.asarray(y_true, dtype=float)
+    default_day = np.asarray(default_day, dtype=float)
+    requested_amount = np.asarray(requested_amount, dtype=float)
+    funded = np.asarray(funded, dtype=bool)
+    n = y_true.shape[0]
+
+    mean_a = float(np.mean(requested_amount)) if n > 0 else 0.0
+    denom = n * mean_a
+    if denom == 0.0:
+        return float("nan")
+
+    profits = realized_profits(y_true, default_day, requested_amount, economics)
+    return float(np.sum(profits[funded])) / denom
+
+
 def emp_harness(
     y_true: np.ndarray,
     scores: np.ndarray,