@@ -10,5 +10,6 @@
 ## Verification Hosts
 - Keep local Windows Python processes below 1 GiB. Use narrow checks and rely on `D:\SystemState\PythonMemoryGuard\python-memory-guard.ps1`.
 - Run Docker-heavy verification, jobs likely to exceed 1 GiB, and macOS diagnostics through SSH alias `deproject-mac`; the Mac checkout is `/Users/julia/agentflow-docker-check`.
+- The sharded Windows suite pins `OPENBLAS_NUM_THREADS=1` and `OMP_NUM_THREADS=1` in every child process; unpinned, OpenBLAS alone accounts for ~550 MiB of the 1 GiB budget. Measurements and the production caveat: `docs/operations/windows-verification.md`.
 - Non-secret Mac context belongs in `AGENT_STATE.md`, `docs/SESSION_HANDOFF.md`, and `docs/operations/local-verification-matrix.md`.
 - Never print, commit, or copy SSH keys, passwords, tokens, recovery codes, or other secrets into project files, logs, PRs, or chat.
@@ -226,6 +226,7 @@ python -m pytest tests/unit tests/integration tests/sdk -q
 # broad Windows no-Docker suite (audit F-07): sequential per-process shards
 # with a per-shard peak-memory budget under the host's 1 GiB process guard.
 # Do not run the monolithic pytest command above for this purpose on Windows.
+# What that budget is spent on: docs/operations/windows-verification.md
 python scripts/run_windows_unit_shards.py tests/unit
 
 # benchmark and regression gate
 
@@ -44,6 +44,7 @@ are inputs to later work, not general-purpose procedures.
 | [API DuckDB persistence and recovery design](api-duckdb-persistence-recovery-design.md) | Current preservation/recovery authorization-boundary owner | Status is `CAPABILITY_REHEARSAL_REQUIRED`; it is not an approved operator runbook |
 | [CI-soak Compose foundation](ci-soak-compose-foundation.md) | Topology and historical implementation reference | Its runtime-status sequence is superseded; resume from the current CI-soak runbook above |
 | [OpenSSF security posture](openssf-security-posture.md) | Scope and interpretation of free supply-chain posture signals | Neither Scorecard nor self-certification is a penetration test or attestation |
+| [Windows verification memory](windows-verification.md) | What the sharded Windows suite's per-process budget is spent on, measured | Describes the test host; pinning the same variables in the API image is an owner decision that page does not take |
 
 ## Consumed and dated records
 
 
@@ -0,0 +1,110 @@
+# Windows verification memory
+
+The Windows verification host kills any Python process that passes 1 GiB, which
+is why `tests/unit` runs as sequential shards instead of one pytest command
+(audit F-07). This page owns what that budget is actually spent on. It exists
+because the budget was raised against the wrong cause, and the next person to
+touch it should start from the measurement rather than from the shard size.
+
+**Audience:** maintainers running or tuning the Windows no-Docker verification suite
+
+**Prerequisites:** a local checkout with the project virtualenv installed; the numbers below were measured on the supported 18-core Windows host on 2026-09-07, except where a line attributes them otherwise, with duckdb 1.5.4, numpy 2.3.5, pandas 3.0.3 and pyarrow 24.0.0
+
+## Where the memory goes
+
+Nearly all of it is one flat, per-process cost, paid the first time anything in
+the process imports numpy:
+
+| Measured with `scripts/run_windows_unit_shards.py <file>` | Peak |
+| --- | --- |
+| `import numpy` | 655.6 MiB |
+| `import numpy`, with `OPENBLAS_NUM_THREADS=1` | 109.5 MiB |
+| `import numpy, pandas, pyarrow`, with the thread variables pinned | 141.0 MiB |
+| `INSERT INTO t VALUES ('r', 't', 200)` on a DuckDB file | 86.0 MiB |
+| the same insert as `VALUES (?, ?, ?)` with bound parameters | 703.1 MiB |
+
+Two mechanisms combine:
+
+- **OpenBLAS commits per-core scratch buffers when it loads.** On this host that
+  is roughly 30 MiB times 18 cores, and it is charged to the process whether or
+  not any array arithmetic ever happens. Pinning the pools to a single thread
+  removes it.
+- **DuckDB reaches numpy on its own.** Passing parameters to `execute()` makes
+  the Python client import pandas and pyarrow — and therefore numpy — to convert
+  the bound values. The same statement written with literals never loads them.
+  Parameter binding is the correct way to write these queries, so this is a cost
+  to bound, not to avoid.
+
+That second point is why the heavy modules looked like a random assortment:
+every test that writes to a DuckDB store paid it, and nothing else did. Bisecting
+one 797 MiB test in `tests/unit/test_analytics_middleware.py` reached
+`ensure_analytics_table` at 91.6 MiB and the single session insert after it at
+810.8 MiB, which is the whole finding in one line.
+
+## Why a smaller `--shard-size` never helped
+
+The cost is per process and flat, so it does not divide. An earlier pass on the
+same host (2026-08-21) recorded a 14-file shard at 830 MiB next to a 147-test
+shard at 94 MiB; splitting either one changes nothing, because each resulting
+process still imports numpy once. Those numbers were read as "individual heavy
+test modules" and the budget was raised instead, which is how the suite arrived
+at a 969.8 MiB worst shard against a 1024 MiB guard — 5.3% of headroom.
+
+## What the runner does now
+
+`scripts/run_windows_unit_shards.py` forces `OPENBLAS_NUM_THREADS=1` and
+`OMP_NUM_THREADS=1` into every child process it starts, for collection as well
+as for each shard. The variables are forced rather than defaulted: an
+`OMP_NUM_THREADS=8` left over in an operator's shell would otherwise put the
+whole cost back without any visible sign.
+
+Neither `src/` nor the unit suite computes with numpy — it is loaded only as
+DuckDB's conversion helper — so single-threaded BLAS has nothing to slow down.
+Per-module peaks with the pinning in place:
+
+| Module | Before | After |
+| --- | --- | --- |
+| `tests/unit/test_analytics_middleware.py` | 805.6 MiB | 192.1 MiB |
+| `tests/unit/test_versioning.py` | 826.7 MiB | 312.3 MiB |
+| `tests/unit/test_usage_db_connection_reuse.py` | 696.0 MiB | 150.6 MiB |
+
+`tests/unit/test_windows_shard_thread_pinning.py` holds the pinning in place and
+fails if a change drops it.
+
+Across the whole suite — 3790 tests in 14 shards — the peaks now run 120.7 to
+400.4 MiB, against 733 to 969.8 MiB before. The budget is back to being a
+ratchet: `DEFAULT_MEMORY_BUDGET_MIB` is 600 MiB, half again the worst shard and
+well under the 1024 MiB guard, so a regression trips the runner rather than the
+host.
+
+## The API image does not pay this
+
+The cost is an artefact of the development environment, not of the product. No
+file under `src/` imports numpy or pandas — the only match there is the Flink
+jobs' requirements lock, a separate runtime — no test imports them either, and
+`requirements-docker.lock`, which `Dockerfile.api` installs with
+`--require-hashes`, contains neither. DuckDB only reaches for them when they
+are already installed, which in this repository means a developer checkout.
+
+Re-running the same `INSERT OR REPLACE ... VALUES (?, ?, ?)` with numpy and
+pandas made unimportable, which is the shape of the API image, gives the answer
+directly: the row is written and the process peaks at 87.6 MiB, the same as the
+literal insert. So there is nothing to pin in the container, and nothing to
+carry over from the numbers above when sizing the API.
+
+`tests/unit/test_windows_shard_thread_pinning.py` fails if numpy or pandas
+enters that lock, because the paragraph above would then need re-measuring
+rather than re-reading.
+
+## Re-measuring
+
+To attribute a shard that exceeds its budget, measure its files one at a time —
+the runner prints a peak for whatever target it is given:
+
+```bash
+python scripts/run_windows_unit_shards.py tests/unit/test_versioning.py
+```
+
+Compare a suspect line's cost by isolating it the same way, down to a single
+node ID. When a peak moves, check whether the process gained an import before
+concluding that a test got heavier.
@@ -9,9 +9,11 @@
   every file to exactly one shard (asserted — no silent gaps);
 - runs each shard sequentially in a fresh Python process, so no single
   process accumulates the whole suite's allocations;
-- records peak private memory per shard (Windows: ``PeakPagefileUsage`` via
-  ctypes; POSIX: best effort) and fails if a shard exceeds the budget
-  (default 900 MiB — headroom under the 1024 MiB guard);
+- pins each shard's BLAS thread pools to one thread (``SHARD_ENV``), which is
+  where this suite's memory actually went before audit FB-17;
+- records peak private memory per shard (Windows: ``PeakProcessMemoryUsed``
+  via ctypes; POSIX: best effort) and fails if a shard exceeds the budget
+  (``DEFAULT_MEMORY_BUDGET_MIB`` below — headroom under the 1024 MiB guard);
 - cross-checks each shard's executed-test count against its collected
   node-ID count, so a shard that silently drops tests fails the run.
 
@@ -21,25 +23,59 @@
 Usage:
     python scripts/run_windows_unit_shards.py                # tests/unit
     python scripts/run_windows_unit_shards.py tests/unit tests/sdk
-    python scripts/run_windows_unit_shards.py --shard-size 250 --memory-budget-mib 900
+    python scripts/run_windows_unit_shards.py --shard-size 250 --memory-budget-mib 800
+    python scripts/run_windows_unit_shards.py tests/unit/test_versioning.py  # one module's peak
 """
 
 from __future__ import annotations
 
 import argparse
+import os
 import re
 import subprocess
 import sys
 from collections import Counter
 from pathlib import Path
 
 DEFAULT_SHARD_SIZE = 300
-# Measured on the supported Windows host (2026-08-21): per-shard peaks are
-# dominated by individual heavy test modules, not shard size — a 14-file
-# shard peaked at 830 MiB while its 147-test neighbour peaked at 94 MiB, and
-# the hottest shard reached 944 MiB. Splitting shards further cannot reduce a
-# single module's peak, so the budget sits just under the 1024 MiB guard.
-DEFAULT_MEMORY_BUDGET_MIB = 1000
+
+# Audit FB-17. Peaks were never about how many tests a shard held: a 14-file
+# shard peaked at 830 MiB next to a 147-test shard at 94 MiB, so the earlier
+# reading — "individual heavy test modules" — was measured but misattributed.
+# Bisecting one 797 MiB test down to its imports found a flat, per-process
+# cost that every shard paid once, on the supported Windows host (18 cores,
+# numpy 2.3.5 / pandas 3.0.3 / pyarrow 24.0.0 / duckdb 1.5.4, 2026-09-07):
+#
+#   import numpy                                    655.6 MiB
+#   import numpy, with OPENBLAS_NUM_THREADS=1       109.5 MiB
+#   numpy + pandas + pyarrow, both vars set         141.0 MiB
+#
+# OpenBLAS commits per-thread scratch buffers at load, one set per core, so
+# the arithmetic is ~30 MiB x 18 cores. No file under src/ or tests imports
+# numpy, so nothing here loses arithmetic by pinning; duckdb reaches it on
+# its own: passing
+# parameters to `execute()` imports pandas/pyarrow (and so numpy) to convert
+# them, which is why every module that writes to a DuckDB store looked heavy
+# while the same INSERT with literals stayed at 86 MiB.
+#
+# This is a development-environment cost only: duckdb imports pandas/numpy
+# when they happen to be installed, and requirements-docker.lock ships
+# neither. With both made unimportable — the shape of the API image — the
+# same INSERT writes its row and peaks at 87.6 MiB. See
+# docs/operations/windows-verification.md.
+SHARD_ENV = {"OPENBLAS_NUM_THREADS": "1", "OMP_NUM_THREADS": "1"}
+
+# With SHARD_ENV applied the full suite (3790 tests, 14 shards, 2026-09-07)
+# peaks at 400.4 MiB, down from 969.8 MiB. This budget is therefore a ratchet
+# against regressions again, not a near-miss of the 1024 MiB guard. Raise it
+# only with a measurement that says why.
+DEFAULT_MEMORY_BUDGET_MIB = 600
+
+BUDGET_FAILURE_HINT = (
+    "attribute it with `python scripts/run_windows_unit_shards.py <file>` per file "
+    "before changing this number — a smaller --shard-size cannot lower a per-process "
+    "import cost, and SHARD_ENV is what keeps that cost small"
+)
 
 # "== 12 passed, 3 skipped, 1 xfailed in 4.56s ==" -> {"passed": 12, ...}
 _SUMMARY_RE = re.compile(r"(\d+) (passed|failed|error(?:s)?|skipped|xfailed|xpassed|warnings?)")
@@ -52,6 +88,7 @@ def collect_node_ids(targets: list[str]) -> list[str]:
         capture_output=True,
         text=True,
         check=False,
+        env=shard_environment(),
     )
     if completed.returncode not in (0, 5):
         sys.stderr.write(completed.stdout + completed.stderr)
@@ -168,13 +205,24 @@ class JobObjectExtendedLimitInformation(ctypes.Structure):
         return peak
 
 
+def shard_environment() -> dict[str, str]:
+    """The parent environment with SHARD_ENV forced on top.
+
+    Forced, not defaulted: an ``OMP_NUM_THREADS=8`` left in an operator's
+    shell would otherwise put back the ~550 MiB the pinning exists to avoid,
+    and it would do it silently.
+    """
+    return {**os.environ, **SHARD_ENV}
+
+
 def run_shard(files: list[str]) -> tuple[int, str, float | None]:
     job = _WindowsJob() if sys.platform == "win32" else None
     process = subprocess.Popen(  # noqa: S603
         [sys.executable, "-m", "pytest", "-q", *files],
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,
         text=True,
+        env=shard_environment(),
     )
     assigned = job.assign(process) if job is not None else False
     output, _ = process.communicate()
@@ -217,7 +265,7 @@ def main(argv: list[str] | None = None) -> int:
         if peak_mib is not None and peak_mib > args.memory_budget_mib:
             failures.append(
                 f"shard {index} peaked at {peak_mib:.1f} MiB "
-                f"(budget {args.memory_budget_mib:.0f} MiB); split it further"
+                f"(budget {args.memory_budget_mib:.0f} MiB); {BUDGET_FAILURE_HINT}"
             )
 
     print(f"total executed: {executed_total}/{len(node_ids)}")
 
@@ -32,6 +32,7 @@
     "docs/operations/api-duckdb-persistence-recovery-design.md",
     "docs/operations/ci-soak-compose-foundation.md",
     "docs/operations/openssf-security-posture.md",
+    "docs/operations/windows-verification.md",
 }
 
 CONSUMED_OR_DATED_RECORDS = {
 
@@ -0,0 +1,127 @@
+"""Audit FB-17: the shard runner must pin BLAS threads in every child process.
+
+Unpinned, OpenBLAS commits one set of scratch buffers per core at import
+(measured: 655.6 MiB for `import numpy` on an 18-core host, 109.5 MiB with
+OPENBLAS_NUM_THREADS=1). That flat cost is what pushed shards to within 5% of
+the host's 1 GiB per-process guard, so losing the pinning would quietly undo
+the headroom rather than fail loudly.
+"""
+
+import re
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from scripts import run_windows_unit_shards as runner
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def test_shard_env_pins_both_thread_pools_to_one():
+    assert runner.SHARD_ENV == {"OPENBLAS_NUM_THREADS": "1", "OMP_NUM_THREADS": "1"}
+
+
+def test_shard_environment_overrides_an_inherited_thread_count(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("OMP_NUM_THREADS", "8")
+    monkeypatch.setenv("OPENBLAS_NUM_THREADS", "18")
+
+    environment = runner.shard_environment()
+
+    assert environment["OMP_NUM_THREADS"] == "1"
+    assert environment["OPENBLAS_NUM_THREADS"] == "1"
+
+
+def test_shard_environment_keeps_the_rest_of_the_parent_environment(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    monkeypatch.setenv("AGENTFLOW_MARKER", "kept")
+
+    assert runner.shard_environment()["AGENTFLOW_MARKER"] == "kept"
+
+
+def test_run_shard_passes_the_pinned_environment_to_pytest(monkeypatch: pytest.MonkeyPatch):
+    captured: dict = {}
+
+    class _FakeProcess:
+        returncode = 0
+
+        def communicate(self):
+            return "1 passed in 0.01s", ""
+
+    class _NoJob:
+        """Stand in for the Job Object: a fake Popen has no handle to assign."""
+
+        def assign(self, process):
+            return False
+
+    def _fake_popen(argv, **kwargs):
+        captured["argv"] = argv
+        captured["env"] = kwargs.get("env")
+        return _FakeProcess()
+
+    monkeypatch.setattr(subprocess, "Popen", _fake_popen)
+    monkeypatch.setattr(runner, "_WindowsJob", _NoJob)
+
+    returncode, output, _ = runner.run_shard(["tests/unit/test_example.py"])
+
+    assert returncode == 0
+    assert "passed" in output
+    assert captured["env"] is not None, "run_shard inherited the environment instead of pinning it"
+    for name, value in runner.SHARD_ENV.items():
+        assert captured["env"][name] == value
+
+
+def test_collect_node_ids_pins_the_environment_too(monkeypatch: pytest.MonkeyPatch):
+    captured: dict = {}
+
+    def _fake_run(argv, **kwargs):
+        captured["env"] = kwargs.get("env")
+        return subprocess.CompletedProcess(argv, 0, "tests/unit/test_example.py::test_one\n", "")
+
+    monkeypatch.setattr(subprocess, "run", _fake_run)
+
+    runner.collect_node_ids(["tests/unit"])
+
+    assert captured["env"] is not None
+    for name, value in runner.SHARD_ENV.items():
+        assert captured["env"][name] == value
+
+
+def test_docstring_quotes_no_budget_that_disagrees_with_the_constant():
+    """A stale "default 900 MiB" in the docstring outlived two budget changes."""
+    quoted = {int(match) for match in re.findall(r"(\d+) MiB", runner.__doc__ or "")}
+
+    assert quoted <= {1024, int(runner.DEFAULT_MEMORY_BUDGET_MIB)}, (
+        f"docstring quotes {sorted(quoted)} MiB; the budget is "
+        f"{runner.DEFAULT_MEMORY_BUDGET_MIB:.0f} MiB and 1024 is the host guard"
+    )
+
+
+def test_the_api_image_still_ships_neither_numpy_nor_pandas():
+    """The runbook's "the API image does not pay this" rests on this lock.
+
+    DuckDB imports pandas (and so numpy, and so OpenBLAS) only when they are
+    installed, so the measured 87.6 MiB for a parameterized insert in the image
+    holds exactly as long as this stays true.
+    """
+    lock = (ROOT / "requirements-docker.lock").read_text(encoding="utf-8")
+    requirements = {
+        line.split("==", 1)[0].strip().lower()
+        for line in lock.splitlines()
+        if "==" in line and not line.lstrip().startswith(("#", "--"))
+    }
+
+    intruders = requirements & {"numpy", "pandas"}
+    assert not intruders, (
+        f"{sorted(intruders)} entered requirements-docker.lock; re-measure before "
+        "trusting docs/operations/windows-verification.md on the API image"
+    )
+
+
+def test_budget_failure_hint_does_not_advise_splitting_shards():
+    hint = runner.BUDGET_FAILURE_HINT
+
+    assert "split it further" not in hint
+    assert "run_windows_unit_shards.py <file>" in hint
+    assert "SHARD_ENV" in hint
Original file line number	Diff line number	Diff line change
`@@ -32,6 +32,7 @@`
`32`	`32`	`"docs/operations/api-duckdb-persistence-recovery-design.md",`
`33`	`33`	`"docs/operations/ci-soak-compose-foundation.md",`
`34`	`34`	`"docs/operations/openssf-security-posture.md",`
	`35`	`+ "docs/operations/windows-verification.md",`
`35`	`36`	`}`
`36`	`37`
`37`	`38`	`CONSUMED_OR_DATED_RECORDS = {`