pedigree-graph 0.6.0__tar.gz

pedigree_graph-0.6.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # setuptools-scm derives the version from the tag history
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install the build frontend
+        run: python -m pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Verify the built version matches the tag
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          built="$(ls dist/pedigree_graph-*.tar.gz | sed -E 's|.*/pedigree_graph-(.+)\.tar\.gz$|\1|')"
+          if [ "$tag" != "$built" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} implies version ${tag}, but setuptools-scm built ${built}"
+            exit 1
+          fi
+          echo "Built version ${built} matches tag ${GITHUB_REF_NAME}"
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pedigree-graph
+    permissions:
+      id-token: write # trusted publishing (OIDC) — no API token stored
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pedigree_graph-0.6.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Virtual envs
+env/
+venv/
+.venv/
+
+# Testing / coverage
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+coverage.xml
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Numba cache
+__pycache__/
+
+# Setuptools-scm
+_version.py

pedigree_graph-0.6.0/CHANGELOG.md

@@ -0,0 +1,157 @@
+# Changelog
+
+This file tracks public-API changes per release.  For per-commit
+history, see `git log`.  Historical release notes prior to v0.5.0
+live on the corresponding GitHub release pages.
+
+## v0.6.0
+
+- **First release published to PyPI.**  `pip install pedigree-graph` now
+  works, retiring the `git+https://...@vX.Y.Z` install form that consumers
+  had to carry because the project was unavailable on the index.
+  Distributions are built and uploaded by a tag-triggered GitHub Actions
+  workflow using PyPI trusted publishing (OIDC), so no API token is
+  stored in the repository or in CI secrets.  Downstream packages pinning
+  a git URL can move to a version range such as
+  `pedigree-graph>=0.6,<0.7`; the bound is worth keeping tight because
+  `PAIR_KINSHIP` and `extract_pairs` are consumed directly by simace,
+  fitace, and pedsum.
+- **Packaging metadata completed for the index listing.**  `readme`,
+  `license` (SPDX `MIT`), `license-files`, `authors`, `classifiers`, and
+  `[project.urls]` are now declared, so the PyPI page renders the README
+  and links back to the repository and this changelog.  The build backend
+  floor moved from `setuptools>=64` to `setuptools>=77`, which is where
+  PEP 639 SPDX license support lands.
+- **`py.typed` marker added.**  The package now advertises inline type
+  information under PEP 561, so type checkers read its annotations when
+  it is installed as a wheel rather than as an editable source checkout.
+  Runtime code is unchanged.
+
+## v0.5.4
+
+- **Self-kinship diagonal fixed for inbred individuals when rows are not
+  in generation-monotonic order.**  The matrix-DP kinship kernel assumed
+  every relative discovered during a row's merge walk had a smaller row
+  index, but `from_arrays` only requires topological order (parents
+  before children).  When a relative at an earlier generation had a
+  higher row index, the diagonal append broke the row's sorted order and
+  the binary search reading `phi(mother, father)` silently returned 0 —
+  so the self-kinship diagonal read `(1+0)/2` instead of `(1+F)/2`, and
+  the GRM diagonal consumed downstream was wrong for inbred individuals.
+  Off-diagonals and the pairwise `compute_pair_kinship` path were
+  unaffected, as was any pedigree loaded in generation order (the common
+  case, which now hits a zero-overhead fast path).
+
+- **Pair-set subtraction and id validation no longer go through
+  `np.unique`/`np.isin`.**  Three internal hot spots were rewritten with
+  sort/searchsorted or diff-based equivalents, verified output-identical
+  on real data and under differential fuzzing (5,000 randomized trials
+  per site, including empties, duplicates, and ids near the int64
+  pair-key bound):
+  - `PedigreeGraph._subtract_pairs` now sorts the remove keys and
+    binary-searches candidates instead of `np.isin` (~6.9x on a 300k-N
+    pedigree; halves `sibling_pairs()` wall time).  Same pattern —
+    and rationale — as `extract_from_sparse` already used.
+  - The duplicate-id check in `_validate_id_column` counts equal
+    adjacent elements after a sort instead of `len(np.unique)` (~37x).
+  - `pairs_from_groups` detects group boundaries by diffing its
+    already-sorted key array instead of re-running `np.unique` on it.
+
+  Returned pairs, counts, orderings, and error messages are unchanged —
+  this change is performance-only.
+
+## v0.5.3
+
+- **`count_pairs_streaming` warns when a cousin/collateral residual
+  underflows.**  The scalar engine derives `H1C`, `1C1R`, `1C2R`, and
+  `H1C1R` by inclusion–exclusion — subtracting closer-relationship
+  contributions with fixed coefficients that are exact only on non-inbred,
+  single-mating pedigrees.  On inbred or structurally complex real
+  pedigrees those corrections can over-count, driving the raw residual
+  negative; it was then silently clamped to `0`, indistinguishable from a
+  true absence (e.g. millions of `1C` but `H1C == 0`).  The clamp now logs a
+  `WARNING` naming the code and the underflow magnitude and points to the
+  matrix engine (`extract_pairs`) for an exact count.  Returned counts are
+  unchanged — only the diagnostic is new.
+
+## v0.5.2
+
+- **`count_pairs_streaming()` releases its transient matrices on exit.**
+  The scalar streaming counter builds the adjacency powers `_A`…`_A5` and
+  now drops them via `_release_pair_matrices()` before returning, exactly
+  as `extract_pairs()` already did.  Previously they stayed resident for
+  the graph's lifetime, inflating peak memory of any later inbreeding / Ne
+  / lineage work on the same graph (~400–520 MiB on a 1M-row pedigree).
+  The counts remain cached and the matrices rebuild lazily via
+  `_ensure_parent_csr()` if pair work runs again, so callers that reached
+  into the private `_release_pair_matrices()` after a streaming call (e.g.
+  pedsum `summarize`) can drop that workaround.  Fixes #4.
+
+## v0.5.0
+
+- **Registry-aligned `max_degree` semantics.**  `extract_pairs`,
+  `count_pairs`, and `count_pairs_streaming` now include exactly the
+  relationship categories whose `REL_REGISTRY[code].degree` is less
+  than or equal to the cutoff.  `max_degree=0` is MZ-only,
+  `max_degree=2` stops before 1st cousins, and `max_degree=3`
+  includes 1st cousins plus the other degree-3 categories.  The public
+  defaults changed from `2` to `3` to preserve the old default behavior
+  of including 1st cousins.
+
+- **`PedigreeGraph.compute_n_ancestors()`** — new cached method.
+  Returns the per-individual count of *distinct* strict ancestors
+  (`int32`, length `n`).  Backed by a sparse boolean transitive
+  closure of the parent graph; memory scales with the total closure
+  size.  Suitable for pedigrees up to ~1M rows on commodity hardware;
+  deeper / wider pedigrees may need a future retirement-style DP
+  variant.
+
+- **`PedigreeGraph.compute_n_descendants()`** — new cached method.
+  Returns the per-individual descendant *path count* (`int32`, length
+  `n`).  In non-inbred pedigrees this equals the unique-descendant
+  count; in inbred pedigrees it over-counts a descendant reachable via
+  multiple ancestor paths.  Matches the convention used historically
+  by `pedsum` (`compute_descendants`) and by the matrix engine's GP /
+  Av / 1C pair counts.  Raises `OverflowError` if any per-individual
+  path count exceeds `int32` max (the kernel accumulates in `int64`
+  and the cast happens after a bounds check, so deeply inbred
+  pedigrees cannot silently wrap).
+
+- **`PedigreeGraph.from_arrays(...)`** — accepts a new optional `sex`
+  kwarg (`np.ndarray | None`).  When omitted, behaviour is unchanged
+  (sex defaults to zeros).  Existing callers do not need updates.
+
+- **Defensive warning for the `sex`-default foot-gun.**
+  ``ne_sex_ratio`` and ``ne_variance_family_size`` now emit a
+  ``RuntimeWarning`` when ``pg.sex`` is uniformly 0 or 1 — almost
+  always a sign that the caller forgot to pass ``sex=`` to
+  ``from_arrays`` and is consuming silently-degenerate (single-sex)
+  Ne results.  The estimator return values are unchanged (``ne=None``);
+  the warning is the new diagnostic.  Kinship-only callers
+  (relationship-pair extraction, GRMs, PA-FGRS) are not affected
+  because they don't invoke the sex-aware estimators.
+
+- New private kernel module `pedigree_graph/_lineage_kernel.py` houses
+  the descendant (numba-JIT) and ancestor (scipy sparse) primitives.
+
+- **`PedigreeGraph.count_pairs_streaming(max_degree=2, scope="full")`**
+  — new method.  Memory-bounded relationship pair counts via pure
+  scalar arithmetic; no pair-key arrays are ever materialized.  Peak
+  memory is O(N) regardless of pedigree density.  Returns all 23
+  codes from `REL_REGISTRY`.  Bit-identical to `count_pairs` for
+  the 10 simple codes (`MZ`, `MO`, `FO`, `FS`, `MHS`, `PHS`, `GP`,
+  `GGP`, `GGGP`, `G3GP`); approximate (~1% on deep low-inbreeding
+  pedigrees) for the 13 cousin / collateral codes (`Av`, `1C`,
+  `H1C`, `HAv`, `GAv`, `GGAv`, `G3Av`, `HGAv`, `HGGAv`, `1C1R`,
+  `H1C1R`, `1C2R`, `2C`).  The scalar path is **full-graph only**:
+  `scope='subsample'` raises `NotImplementedError` on graphs built
+  via `from_subsample` (use `count_pairs` for subsample-restricted
+  counts).  See `LIMITATIONS.md` for the full precision contract.
+  Benchmark: 5 seconds on a 783K-row stallion-heavy livestock
+  pedigree where both matrix and BFS engines OOM at 30 GB.
+
+- **`max_degree` validation** — `extract_pairs`, `count_pairs`, and
+  `count_pairs_streaming` now reject `max_degree` outside `[0, 5]`
+  with `ValueError`.  Degree 0 is accepted (cheap codes MZ / MO /
+  FO / FS are computed regardless; the cap controls the expensive
+  matrix products at degree 2 and above).

pedigree_graph-0.6.0/CONTEXT.md

@@ -0,0 +1,67 @@
+# pedigree-graph
+
+Sparse-matrix pedigree relationship extraction and kinship computation. A
+pedigree is a parent→child DAG of individuals; this context is the vocabulary
+for the relationships between individuals and the two coordinate systems used
+to name them.
+
+## Language
+
+### Coordinate spaces
+
+**Graph-space**:
+An individual's row index within the full pedigree the graph was built over.
+_Avoid_: full index, absolute index, internal index
+
+**Caller-space**:
+An individual's row index within the subsample the caller supplied, which may
+order or omit individuals differently from the full pedigree.
+_Avoid_: subsample index, df index, external index
+
+### Relationships
+
+**Relationship pair**:
+An unordered pair of individuals sharing a relationship category. Some pair
+arrays preserve relationship orientation (for example descendant→ancestor for
+lineal relationships); pair-key encodings canonicalize as `(lo, hi)` with
+`lo < hi`.
+_Avoid_: edge, link, tuple; assuming every pair array is already canonical
+
+**Relationship category**:
+A class of relationship identified by a short code (e.g. `FS`, `MHS`, `1C`),
+defined by `(up, down, n_ancestors)` — meioses up to the common ancestor(s),
+meioses back down, and whether the connecting ancestor is a single individual
+(half / lineal) or a mated pair (full).
+_Avoid_: relationship type (when the code is meant), kind
+
+**Degree**:
+The kinship distance of a relationship category — `0` for MZ twins, `1` for
+parent-offspring and full sibs, and so on. A degree cutoff includes relationship
+categories whose degree is less than or equal to the cutoff.
+
+**Nominal kinship**:
+The kinship coefficient implied by a relationship category's `(up, down,
+n_ancestors)` formula, assuming a single relationship path and no inbreeding
+or co-coalescence.
+_Avoid_: exact kinship
+
+**Exact pairwise kinship**:
+The kinship coefficient for a particular pair of individuals after summing all
+pedigree paths, including inbreeding, MZ co-coalescence, and duplicate
+relationship paths such as double cousins.
+_Avoid_: nominal kinship
+
+## Relationships
+
+- A **relationship pair** holds two individuals and belongs to one **relationship category**; canonical ordering is a storage/encoding choice, not part of the relationship itself.
+- Every individual index is expressed in either **graph-space** or **caller-space**; the same individual generally has a different index in each.
+- A pair returned to a caller is in **caller-space**; the kinship matrix is indexed in **graph-space**. Converting between the two is required whenever both meet.
+
+## Example dialogue
+
+> **Reviewer:** "`extract_pairs` gave me pair `(1, 0)` for the MZ twins — why is its kinship `0.0`?"
+> **Author:** "Those indices are **caller-space** — you reversed the subsample. The kinship matrix is **graph-space**, so indexing it with caller indices reads the wrong cell. The pair has to be mapped back to graph-space first."
+
+## Flagged ambiguities
+
+- "index" alone is ambiguous between **graph-space** and **caller-space** — always qualify which space, since the same individual differs between them and conflating them caused a kinship-lookup bug (PGQ-001).

pedigree_graph-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Waples
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pedigree_graph-0.6.0/LIMITATIONS.md

@@ -0,0 +1,183 @@
+# Limitations
+
+Current scaling and correctness limitations of the relationship-pair
+engines.  Read before reaching for `extract_pairs` / `count_pairs` on
+pair-dense pedigrees.
+
+## Pair counting is O(answer size) for the matrix and BFS engines
+
+The matrix and BFS engines both materialise every pair as an
+``(idx1, idx2)`` array before counting it:
+
+- ``extract_pairs()`` returns ``dict[code, (np.ndarray, np.ndarray)]``.
+- ``count_pairs()`` is a thin facade — it runs ``extract_pairs()`` and
+  returns ``{code: len(idx_array)}``.
+
+Memory is therefore proportional to the total relationship-pair count,
+**not** the pedigree size.
+
+### Worst case: prolific-stallion livestock pedigrees
+
+Stallion-driven half-sib density is the engine's hard wall.  On a real
+horse-breed pedigree (783K individuals, one all-time-great stallion
+siring 2,500 horses, top-sire grand-offspring set ~50K):
+
+- Paternal half-sib pair count = ~156 M
+- ``_half_sib_matrix`` materialisation = ~312 M nonzeros (~3 GB) just
+  for the symmetric MHS+PHS matrix
+- Per-grandparent grandchild bucket for ``_cousin_pairs`` enumeration
+  reaches ``C(50K, 2) ≈ 1.25 B`` candidate pairs through one stallion
+  grandparent (~10 GB of int64 keys)
+- ``_A2 @ _A3.T`` for 1C1R / H1C1R has row nnz ~2,500 (one stallion's
+  great-grandchildren spread); chunk sizes blow up at default
+  ``chunk_rows``
+
+Both engines OOM on this pedigree well before producing a count, even
+on 30 GB hosts.  Matrix OOMs in ``A_f @ A_f.T`` (PHS sparse product);
+BFS OOMs in the numba cousin enumeration kernel.
+
+### Operational workarounds
+
+1. ``pedsum --no-pairs`` skips the pair-counting stage entirely.  The
+   horse pedigree completes in ~30s with 1 GB peak RSS this way,
+   producing every other section (size structure, family, mating,
+   lineage, founder contribution, inbreeding, effective size) but
+   returning stub values for the 23 relationship counts (``pairs: {}``
+   and ``relationship_summary.computed: false``).
+
+2. ``PedigreeGraph.count_pairs_streaming()`` — pure-scalar per-anchor
+   arithmetic, O(N) memory, exact on 10 simple codes, approximate
+   within ~1% on 13 cousin / collateral codes for deep low-inbreeding
+   pedigrees.  See the precision contract below.
+
+## ``count_pairs_streaming`` precision contract
+
+The scalar path is **full-graph only** — ``scope='subsample'`` raises
+``NotImplementedError`` on graphs constructed via ``from_subsample``.
+Use ``count_pairs`` for subsample-restricted counts.
+
+- **Exact** on 10 codes (bit-identical to ``count_pairs`` on every
+  input):
+  ``MZ``, ``MO``, ``FO``, ``FS``, ``MHS``, ``PHS``,
+  ``GP``, ``GGP``, ``GGGP``, ``G3GP``.
+
+- **Approximate** on 13 cousin / collateral codes:
+  ``Av``, ``1C``, ``H1C``, ``HAv``, ``GAv``, ``GGAv``, ``G3Av``,
+  ``HGAv``, ``HGGAv``, ``1C1R``, ``H1C1R``, ``1C2R``, ``2C``.
+
+  Scalar formulas assume each individual has the full complement of
+  known grandparents at the relevant depth, so constants like
+  ``4*FS`` in the ``H1C`` correction over-subtract on shallow
+  pedigrees; ``H1C`` may clamp to ``0`` on depth ≤ 3.  Twin parents
+  and sib-mating offspring also push the formulas off bit-identity
+  because the inclusion-exclusion terms assume neither pattern.
+
+  On the synthetic ``small_pedigree`` fixture (3000 rows, depth 3,
+  ~0.5% sib-mating, 10 twin pairs): ``Av`` off by 3, ``HAv`` off by
+  11, ``1C`` off by 30, ``H1C`` clamped to 0.  On deep livestock
+  pedigrees (depth ≥ 5, low inbreeding) the formulas are accurate to
+  better than 1%.
+
+The horse-pedigree benchmark (N=783K, mean F=0.007) completes in
+~5 seconds with peak RSS ~730 MB.
+
+## Cousin-code matrix/BFS divergence on inbred input
+
+Independent of scaling, the ``matrix`` and ``bfs`` engines give
+**different counts** on inbred pedigrees for the four
+cousin-multiplicity codes: ``1C1R``, ``H1C1R``, ``1C2R``, ``2C``.
+
+- **Matrix engine** uses path multiplicity: ``M.data >= 2`` (full) or
+  ``M.data == 1`` (half) thresholds on ``_A2 @ _A3.T`` / ``_A2 @ _A4.T``
+  / ``_A3 @ _A3.T``.  A pair sharing an ancestor via two distinct
+  paths is counted twice in the matrix entry; the threshold
+  classifies based on this multiplicity.
+- **BFS engine** uses distinct-shared-ancestor semantics: a pair
+  sharing N distinct ancestors at the relevant depth is counted once
+  regardless of paths.
+
+The divergence is documented in
+``tests/test_experimental.py:171`` (the ``inbred_with_cousins_pedigree``
+fixture) and asserted in ``test_inbred_with_cousins_cousin_codes_diverge``.
+
+``extract_pairs(scope="full")`` returns matrix-engine values by
+default.  Callers needing BFS-distinct semantics on inbred input must
+use ``pedigree_graph.experimental.count_pairs_bfs`` and accept the
+matrix-vs-BFS difference for those four codes.
+
+## ``int8`` overflow risk in BFS ``P_k`` boolean matmul
+
+The BFS engine (`pedigree_graph.experimental.count_pairs_bfs`) uses
+``np.int8`` for ``P_k.data`` during the boolean matmul stages.
+Theoretically vulnerable to silent path-count overflow under extreme
+consanguinity: more than 127 distinct paths to a single ``(i, X)`` pair
+before the ``M.data[:] = 1`` clamp will wrap.
+
+Empirically not seen on any tested pedigree. Switch to ``int32`` if it
+ever bites — the change is a one-line dtype swap at the matmul site;
+memory cost is 4× on the intermediate matrices.
+
+## ``compute_n_ancestors`` memory scales with ``sum_i n_ancestors[i]``
+
+``PedigreeGraph.compute_n_ancestors`` is a sparse boolean transitive
+closure of the parent graph (``_lineage_kernel._compute_n_ancestors``).
+Memory scales with ``sum_i n_ancestors[i]``, so very deep / very wide
+pedigrees can hit RAM limits:
+
+- N=100K, G=10, random mating → 2.2 s, peak RSS ~0.5 GB.
+- N=10M with saturated ancestry → extrapolates beyond commodity hardware.
+
+A retirement-style DP (analogous to the F kernel's row-retirement
+optimisation in ``_kinship_kernel``) would bound peak memory to the
+live frontier rather than the cumulative ancestor set. Deferred until
+a user hits the wall.
+
+## Half-founders and missing parents
+
+Both engines accept half-founders (one parent known, one missing).
+The sibling group-by filters to known parents only:
+
+- ``FS`` requires BOTH parents known on both individuals.
+- ``MHS`` only considers individuals with mother known.
+- ``PHS`` only considers individuals with father known.
+
+This matches the standard convention but can surprise callers who
+expect half-founders to contribute to half-sib counts on the
+"missing" side.  They don't.
+
+## Subsample-restricted counts are O(full pair count)
+
+``PedigreeGraph.from_subsample(...)`` builds a graph that returns
+subsample-filtered pair arrays from ``extract_pairs``, but the
+underlying enumeration runs over the FULL pedigree first (raw counts
+saved, then sample mask applied).  Memory is bounded by full-pedigree
+pair counts, not the subsample.
+
+For a 10% subsample of a stallion-heavy pedigree, this is still
+OOM-prone because the full-pedigree intermediate doesn't shrink.
+
+## What this file does NOT cover
+
+- Lineal-code counting limitations (none significant — ``_A^k.nnz`` is
+  O(N · depth) and tractable to N=10M+).
+- F (inbreeding coefficient) scaling — covered by
+  ``pedigree_graph._kinship_kernel`` and its own row-retirement
+  optimisation work.
+- Effective size estimator scaling — covered by
+  ``pedigree_graph._effective_size`` and the ``skip_ne_coancestry``
+  knob.
+- BFS engine internal limitations — see the ``int8`` overflow section
+  above for the path-count overflow case, and GitHub issues
+  [#2 (numba kernel parallelisation)](https://github.com/rwaples/pedigree-graph/issues/2)
+  and [#3 (10M+ scaling test)](https://github.com/rwaples/pedigree-graph/issues/3)
+  for open performance / scalability questions.
+
+## Last updated
+
+2026-05-20 — ``int8`` overflow risk and ``compute_n_ancestors``
+scalability sections added; BFS internal follow-ups re-homed from
+retired ``external/pedsum/STATUS.md`` to GitHub issues #2 and #3.
+
+2026-05-19 — ``count_pairs_streaming`` precision contract
+reconciled; ``Av`` documented as approximate; stale
+"count-only-experiment-didn't-ship" narrative removed.