Tooling: search open-PR overlap by changed file path in find_overlap (no new kappa)

research/overlap-path-index/README.md

@@ -0,0 +1,115 @@
+# overlap-path-index: search open-PR overlap by changed file path
+
+**Verifier engineering; no new kappa, no certificate or selected-record change.**
+This package documents and verifies one change to the live coordination tool
+`scripts/find_overlap.py`: it now caches each open PR's changed-file list and
+answers "which open PRs touch this path?", the request left in
+[the workflow feedback thread](https://github.com/CrocSwap/integer-mult-bounds/discussions/1200#discussioncomment-18909265).
+
+## Scope and evidence
+
+Original card: `replay-runtime` (verifier-engineering), scope **refined** to the
+card's allowed "source-bound cache boundary" variation; see
+[TASK.json](TASK.json) for the scope-change reason. Source commits, Git blobs
+and SHA256 pins are in [SOURCES.json](SOURCES.json); the catalogue and selected
+record are pinned as historical provenance.
+
+**What changed.** `find_overlap.py` gains a third snapshot source, `pr_files`,
+fetched only when `--path` is used, plus `fetch_pr_files` and `path_report`.
+Body term search, its match order and its report fields are unchanged. With
+both axes given, `matches` is the intersection (a record must hit at least one
+term and one path) while `path_matches` stays the superset of all path hits, so
+a path hit can never disappear silently. Patterns are `fnmatch` patterns or
+literal substrings of the repository-relative path. A PR whose changed-file
+list is unavailable (for example
+[CrocSwap/integer-mult-bounds#376](https://github.com/CrocSwap/integer-mult-bounds/pull/376)
+at the measured snapshot) is recorded
+with empty paths and `truncated: true`, and PRs beyond GitHub's 100-file
+listing are flagged `truncated: true` in the output; neither is silently
+trusted. Diff contents remain unsearched, and the report's `path_limits` says so.
+
+**Measured behavior** (Windows 11, CPython 3.13.15, this host):
+
+| Check | Before | After |
+|---|---:|---:|
+| Body-only overlap query (offline cache) | 0.48 s | 0.48 s (no `pr_files` fetch at all) |
+| Full changed-file index build | impossible (no path data) | 87.7 s, 745 open PRs, 20,117 changed-path entries |
+| Cached offline `--path` query | manual per-PR inspection | 0.48 s |
+
+The index fetch pages 10 PRs at a time with up to four attempts per page:
+25x100-node pages exceed GitHub's ~10 s gateway limit and returned HTTP 502 on
+this host (measured: failing calls died at 10.5-10.7 s), while 10x100 pages
+completed in 0.8-4.4 s. A failed refresh keeps the previous snapshot and warns;
+it never reports "no overlap" from missing data without a warning.
+
+**Live answers to the request's example questions** at the measured snapshot:
+`docs/research/current-status.md` is touched by exactly one open PR,
+[CrocSwap/integer-mult-bounds#1232](https://github.com/CrocSwap/integer-mult-bounds/pull/1232);
+`research/lean-external-review` is touched by
+[CrocSwap/integer-mult-bounds#1365](https://github.com/CrocSwap/integer-mult-bounds/pull/1365)
+and
+[CrocSwap/integer-mult-bounds#1494](https://github.com/CrocSwap/integer-mult-bounds/pull/1494),
+the stacked level-model phases of
+[CrocSwap/integer-mult-bounds#442](https://github.com/CrocSwap/integer-mult-bounds/pull/442).
+
+## Reproduce
+
+From the repository root (no network needed):
+
+```sh
+python3 scripts/research_package.py --package research/overlap-path-index --check-only
+python3 scripts/research_package.py --package research/overlap-path-index
+```
+
+Expected: `PASS_OVERLAP_PATH_INDEX`, then registered-package success. The
+verifier checks the two pinned live inputs, runs the 11 Overlap unit tests and
+seven hermetic CLI controls (positive, substring, glob, rejection,
+term-and-path, mutation, missing-index) against a fixture snapshot cache placed
+outside the repository. A live index build additionally needs authenticated
+`gh`; `--path` queries within the cache lifetime cost nothing extra.
+
+## Limitations
+
+Tooling only. No mathematical claim, kappa, supplier, certificate, replay
+coverage or selected-frontier change. Path matching is a changed-file
+inventory, not diff-content search; closed PRs remain represented only through
+local READMEs, TASK metadata and the PR ledger. The full index build costs
+about 88 s and is paid only by `--path` queries at refresh time; GitHub's
+~10 s gateway limit caps the page size. Whether the two live input files change
+later is not this package's call: they are pinned, so a future edit of either
+needs an explicit source-pin migration (same convention as other tooling
+packages here). The pre-existing Windows CRLF failures in `PackageTests`
+(fixed in [CrocSwap/integer-mult-bounds#1298](https://github.com/CrocSwap/integer-mult-bounds/pull/1298))
+are unrelated and untouched. No independent human review or hosted-CI success
+is claimed.
+
+## Open next questions
+
+Structured in [TASK.json](TASK.json):
+
+1. **Closed-PR path coverage.** Can the index cover closed/merged PRs via the
+   ledger's `COVERAGE.json.gz` inventories? Matters because closed work holds
+   most duplicates. First step: a reader for
+   `research/pr-reconciliation100-20261013/COVERAGE.json.gz`. Blocked by the
+   need for an explicit freshness/coverage label so batch snapshots cannot
+   overstate coverage.
+2. **Cheaper refresh.** Should body-only searches carry the index, and can the
+   87.7 s build be cut? First step: per-page caching keyed by PR head sha.
+   Blocked by GraphQL offering no ETags for this connection; the time cost must
+   be shown worth paying first.
+3. **True stacking.** "What stacks on PR N" is approximated by shared paths;
+   base/head chains would be exact. First step: record each open PR's base ref
+   in `pr_files` rows. Blocked by stacked PRs here mostly targeting `main` and
+   naming their parent only in prose.
+
+## Credit and provenance
+
+The overlap helper, its snapshot design and its coverage contract are Douglas
+Colkitt's (with OpenAI Codex assistance, Apache-2.0, retained unchanged except
+as described). The changed-file request is Mister-Meeseeks's
+[discussion 1200](https://github.com/CrocSwap/integer-mult-bounds/discussions/1200#discussioncomment-18909265)
+item 2. The onboarding UTF-8/Windows fixes in
+[CrocSwap/integer-mult-bounds#1298](https://github.com/CrocSwap/integer-mult-bounds/pull/1298)
+(rtyu193-rgb) affect the same script and are complementary; this change does not
+include them. Prepared by Aaron Wang / navinor, with help from opencode.
+Apache-2.0.

research/overlap-path-index/SOURCES.json

@@ -0,0 +1,30 @@
+{
+  "schema_version": 1,
+  "base_commit": "04aecc3d2d818df020b628a41082c79951202628",
+  "files": [
+    {
+      "path": "certificates/selected-result.json",
+      "usage": "provenance",
+      "git_blob": "ae6a99f28aa468649eb66a361e764d769363bf11",
+      "sha256": "10b9e340fd8e354a37a0c4813c90e5de1dd42044b5f6aca4a3fc5a42b685fa32"
+    },
+    {
+      "path": "docs/research/agent-task-catalog.json",
+      "usage": "provenance",
+      "git_blob": "c05fafaa25ba95b2d5af86b1800427198e3d20eb",
+      "sha256": "89b5928bc92c81e2647b6d702a7ad85a6795b8f44e2eb267b2ff3145d8f2b2ce"
+    },
+    {
+      "path": "scripts/find_overlap.py",
+      "usage": "input",
+      "git_blob": "2668844310ea52bb4fe3c4561dd4ee16fcdd20cc",
+      "sha256": "ce77860b18ea5a58ee527a1055e0ba7c650b2da2167a6aaeaaf83af099689b4f"
+    },
+    {
+      "path": "tests/test_research_onboarding.py",
+      "usage": "input",
+      "git_blob": "8d5dfdee97a59153ddc155d2590a35131aea6076",
+      "sha256": "b0f23e38a5d6fa2079712df1f564a23b9bab0b997bc90f09f48965aa4802cc2e"
+    }
+  ]
+}

research/overlap-path-index/TASK.json

@@ -0,0 +1,73 @@
+{
+  "schema_version": 1,
+  "task_id": "replay-runtime",
+  "priority_revision": 2,
+  "base_commit": "04aecc3d2d818df020b628a41082c79951202628",
+  "original_card": {
+    "id": "replay-runtime",
+    "question": "Can one measured replay bottleneck be sped up without dropping coverage?",
+    "starting_points": [
+      "scripts/run_isolated_tests.py",
+      "scripts/verify_replay_coverage.py",
+      "certificates/selected-result.json"
+    ],
+    "methods": [
+      "Profile one isolated replay and optimize the measured bottleneck.",
+      "Design source-bound reuse with explicit dependency invalidation and negative controls."
+    ],
+    "acceptance_gate": "Report before/after wall time on the same fixture, retained checks and invalidation behavior.",
+    "first_step": {
+      "command": [
+        "python3",
+        "-B",
+        "scripts/research_baseline.py"
+      ],
+      "expected": "PASS_RESEARCH_BASELINE_BINDINGS_ONLY",
+      "inspect": "Read the selected reproduction command and choose a single replay stage for profiling.",
+      "scope": "Positive control / source-bound orientation only; this is not a new construction or full cold replay."
+    },
+    "first_experiment": "Measure one unchanged fixture, preserve check coverage, and test one optimization with invalidation controls.",
+    "bottleneck_link": "Faster trustworthy replays increase review throughput and let mechanism candidates be checked sooner.",
+    "allowed_variations": [
+      "Profile one stage or design one source-bound cache boundary."
+    ],
+    "scope_change_triggers": [
+      "Skipping coverage or comparing different fixtures to claim speedup."
+    ],
+    "overlap_terms": [
+      "replay runtime",
+      "cache invalidation",
+      "isolated tests"
+    ]
+  },
+  "scope_status": "refined",
+  "actual_scope": "Cache each open PR's changed-file list inside find_overlap.py's existing source-bound snapshot and search it by path (--path), implementing the request in discussion 1200 (comment 18909265), with body term search unchanged and stale/partial indexes reported rather than trusted.",
+  "scope_change_reason": "The card's measured check chosen is the overlap helper's own remote refresh, the coordination check discussion 1200 names as expensive and unable to see code paths; this is the card's allowed variation 'design one source-bound cache boundary'. The card's other starting points (isolated-test replays) were left alone because open work already covers nearby replay optimizations (CrocSwap/integer-mult-bounds#1461, CrocSwap/integer-mult-bounds#1584, CrocSwap/integer-mult-bounds#1101).",
+  "bottleneck_link": "Overlap checks are the coordination bottleneck every agent pays before claiming novelty; today they cannot see changed code paths at all, so agents inspect PRs one by one and miss concurrent duplicates (the exact failure discussion 1166 coordination rules warn about). One cached offline path query replaces that manual inspection.",
+  "budget_minutes": 60,
+  "stop_rule": "Ship the index and its controls if a cached offline path query answers both discussion 1200 example questions; stop if GitHub cannot serve the file lists within its gateway limits at any page size tested (25 PRs/page 502s at ~10 s, 10 PRs/page works).",
+  "outcome": "completed",
+  "evidence": "scripts/find_overlap.py gained fetch_pr_files/path_report and --path; 5 new fixture tests plus 6 pre-existing Overlap tests pass (11 total); the package verifier runs 7 hermetic CLI controls. Measured on Windows 11, CPython 3.13: full index build 745 open PRs / 20117 changed-path entries in 87.7 s, cached offline path query 0.48 s, body searches pay nothing extra (pr_files is fetched only for --path queries). Live answers: docs/research/current-status.md is touched by CrocSwap/integer-mult-bounds#1232 only; research/lean-external-review is touched by CrocSwap/integer-mult-bounds#1365 and CrocSwap/integer-mult-bounds#1494, the stacked CrocSwap/integer-mult-bounds#442 level-model work. 112 PRs (of 745) exceed GitHub's 100-file listing and are flagged truncated; https://github.com/CrocSwap/integer-mult-bounds/pull/376 reports no file list and is recorded empty+flagged.",
+  "author": "Aaron Wang / navinor, with help from opencode",
+  "ai_assistance": "Substantial assistance from opencode (agent tooling): design, implementation, tests, measurements and writing. No other AI tools used.",
+  "open_questions": [
+    {
+      "question": "Can the same path index cover closed/merged PRs, whose changed files are now reachable only through the local ledger's COVERAGE inventories?",
+      "why_it_matters": "Closed work is where most duplicates already live; today find_overlap searches closed PRs only through local READMEs and the ledger.",
+      "first_step": "Prototype a reader for research/pr-reconciliation100-20261013/COVERAGE.json.gz changed-file inventories and merge it into path_report with an explicit closed-PR coverage label.",
+      "blocked_by": "Ledger inventories are batch snapshots; they need a freshness/coverage statement before they can appear in the same report without overstating coverage."
+    },
+    {
+      "question": "Should body-only searches also carry the changed-file index, and can its 87.7 s refresh be made cheap enough for that?",
+      "why_it_matters": "A combined body+path score would rank path-touching records higher in ordinary overlap reports.",
+      "first_step": "Measure the fetch with conditional requests (ETag/If-None-Match on the pulls listing) and per-page caching keyed by PR head sha.",
+      "blocked_by": "GraphQL does not expose ETags for this connection; the time cost is the price of ~74 pages, so cost accounting must show the win first."
+    },
+    {
+      "question": "What stacks on a given PR beyond shared files (base-branch chains)?",
+      "why_it_matters": "The discussion 1200 question about what stacks on https://github.com/CrocSwap/integer-mult-bounds/pull/540 is only approximated by shared-path hits; true stacking is a head/base relationship.",
+      "first_step": "Record each open PR's base ref in the pr_files rows and flag PRs whose base names another open PR's head branch.",
+      "blocked_by": "Most stacked PRs here target main and reference their parent only in prose, so the signal would be incomplete and must be labeled as such."
+    }
+  ]
+}

research/overlap-path-index/VERIFY.json

@@ -0,0 +1,21 @@
+{
+  "schema_version": 1,
+  "status": "ready",
+  "python": "3.12",
+  "requirements": [],
+  "inputs": [
+    "scripts/find_overlap.py",
+    "tests/test_research_onboarding.py"
+  ],
+  "commands": [
+    {
+      "argv": [
+        "{python}",
+        "-B",
+        "{package}/verify.py"
+      ],
+      "timeout_seconds": 300,
+      "checks": "Identity (SOURCES.json pins for both live inputs), the 11 Overlap unit tests against the pinned tool, and 7 hermetic CLI controls on a fixture snapshot cache: positive path hit, substring and fnmatch patterns, rejection (untouched path), term/path intersection with the superset property, a mutated-fixture control that must lose the hit, and a missing-index control that must warn instead of reporting no overlap. No network access."
+    }
+  ]
+}