Skip to content

feat(persistence): executable rank-erosion test for F₂ grid representations (#1001) - #1002

Merged
t-uda merged 2 commits into
developfrom
ccr-eb669e62-a5kqoa
Nov 20, 2026
Merged

t-uda merged 2 commits into
developfrom
ccr-eb669e62-a5kqoa

Conversation

@t-uda

@t-uda t-uda commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Closes #1001

Summary

Third and last unit of #925 (finite-grid rank-erosion tests): the executable test with its certificate, proved correct for the actual Kan extensions.

  • New TDA/Persistence/F2GridErosion.lean (namespace TDA.Persistence):
    • RatGrid.pointList (explicit enumeration of grid grades), RatGrid.erosionBreakpoints (rational breakpoints, deduplicated), RatGrid.radius, RatGrid.lower / upper, with grid_erosionBreakpoints (the real image of the rational breakpoint grid is the breakpoint grid of the real grids) and realGrade_lower / realGrade_upper.
    • F2GridRep.ErosionFailure, erosionFailureAt, erosionFailure?, ErosionResult, runErosion.
    • Correctness: erosionFailure?_eq_none_iff (no failure ↔ RankErosion of the actual Kan extensions, for valid input and 0 ≤ e), runErosion_eq_invalid_iff, runErosion_eq_pass_iff, runErosion_eq_fail.
  • New TDA/Persistence/F2GridErosionExamples.lean, routed through TDA/Persistence/Examples.lean.
  • docs/api.md, docs/math/rank-erosion.md, CHANGELOG.md, pins; four documentation notes from the review of feat(persistence): executable F₂ grid representations and their Kan-extension ranks (#999) #1000.

Branch lifecycle

Ordinary develop topic: based on develop fa2a89275280ee905b2bdb30b734c14d2d53c21c, target develop, squash merge. Target scope: computation lane under #227 / #865 Package C (#925, part 3); release version undecided. Propagation: N/A.

Public declarations added / changed

Added in TDA.Persistence.RatGrid: pointList, mem_pointList, erosionBreakpoints, radius, coe_radius, grid_erosionBreakpoints, lower, upper, realGrade_lower, realGrade_upper.

Added in TDA.Persistence.F2GridRep: ErosionFailure, erosionFailureAt, erosionFailure?, ErosionResult, runErosion, erosionFailureAt_eq_none_iff, erosionFailureAt_eq_some, erosionFailure?_eq_none_iff_forall, erosionFailure?_eq_some, rankAt_lower_upper, erosionFailure?_eq_none_iff, runErosion_eq_invalid_iff, runErosion_eq_pass_iff, runErosion_eq_fail.

Added in TDA.Persistence.F2GridErosionExamples: zero, ray, shifted, noCoordinatesTwo, flat and 31 theorems about executed tests and their transfers.

Changed: docstrings only, in F2GridRep.lean (RatGrid) and F2GridRepExamples.lean (module docstring, plane_rank_between). No existing statement or definition changes.

Source ↔ Lean correspondence

Library-derived contract (#1001); no paper statement is formalised. The signatures are those of the contract in #1001. Every rank in the correctness theorems is a rank of the actual Kan extension R.grid.lan.obj (R.toModule hR) and the predicate is the existing weak-pair RankErosion; no caller-supplied rank or certificate enters a statement.

Against #925: invalid input is distinguished (invalid); a failure reports the direction, a comparable pair of breakpoint grades and the two exact ranks; success is equivalent to the full predicate for valid input. Not provided, as #925 itself excludes: the strict bound ε < dE ≤ dI, distance minimisation, other fields, Gaussian elimination, an input generator.

Validation

Evaluated head db48853ad0605a5c297f88d9d7e7fec8af8873b6, base fa2a89275280ee905b2bdb30b734c14d2d53c21c.

  • Hosted check: success — run 44657463710 / job 136027131793 on this head: AXIOM AUDIT OK — 13593 declaration(s), PRIVATE AUDIT — 10503 private theorem root(s), COVERAGE OK — 10954 public theorems, all pinned, Comparator "Lean default kernel accepts the solution", CHECK OK. The docs job was skipped (manual dispatch only).
  • Local scripts/check.sh (full gate) on this head: exit 0, CHECK OK, the same three counts, Comparator accepted (1m41s, warm build).
  • Against the base's counts (13548 / 10503 / 10909): +45 audited declarations and +45 public theorems are the 45 appended pins (14 library theorems, 31 example theorems); no private theorem.
  • git push pre-push gate: passed.
  • The examples module, all of whose executed fixtures are decide +kernel, builds in about 10 s.
  • Not run: scripts/test-guards.sh, doc generation. No TauCeti search was made (not a dependency).

Remaining sorry / custom-axiom footprint

none

Independent review evidence

🤖 Generated with Claude Code

https://claude.ai/code/session_01RfoZqCRSgoUin4otWc6fXL

…ations (#1001)

Add the rational breakpoint grid and F2GridRep.runErosion, which validates two
representations and a rational radius and returns invalid, pass, or a failed
inequality with its direction, grades and ranks. The three outcomes are proved
correct for RankErosion of the actual Kan extensions through the finite
criterion. Fold in the documentation notes from the review of #1000.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RfoZqCRSgoUin4otWc6fXL
…icate (#1001)

Deduplicate the rational breakpoint lists, state in runErosion_eq_fail that the
reported grades are breakpoint grades, and add fixtures for a failing
two-parameter comparison, a passing one between different modules and an empty
value list. State the breakpoint count in the documentation.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RfoZqCRSgoUin4otWc6fXL
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-20T02:00:11.619529Z db48853 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

t-uda commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

Reviewed-by: claude-opus read-only reviewer (session distinct from the implementer)

Head reviewed: db48853ad0605a5c297f88d9d7e7fec8af8873b6 (base develop fa2a89275280ee905b2bdb30b734c14d2d53c21c), governed by #1001, last unit of #925.
Compiled: one scratch file .agents/scratch/Review1002.lean (deleted afterwards), elaborated with scripts/lean.sh lake env lean. It imported TDA.Persistence.F2GridErosionExamples and ran #print axioms on runErosion, erosionFailure?, erosionFailureAt, erosionBreakpoints, pointList and rankAt. It ran compiled #evals that list every failing comparable pair, not only the first one, for interval/zero at 1/4, ray 0/ray 1 at 1/2 and plane/flat at 1/2. It also ran runErosion on plane/flat and flat/plane at 1 and 1/2, emptyGrid/zero at 1, and interval/zero and shifted/interval at 49/100. No tracked file was edited, and no build or gate was run.
Comparison mode: digest-based. Compared against the #1001 contract, #925's requirements and the existing library definitions (RankErosion, CoordinateGrid.erosionBreakpoints, rankErosion_lan_iff_of_subset, F2GridRep.rankAt_eq(_of_eq)). There is no primary paper source.
Verdict: pass. No substantive findings; four non-substantive ones.

Findings

  1. NON-SUBSTANTIVE: some documentation is stale. docs/math/rank-erosion.md lines 216–224 still say "Executable tests additionally need effective grades, coefficients and a matrix-rank correctness bridge. These are proposed extensions, not declarations supplied by this note." The same note now supplies such a test for F₂ (§ "A certified finite test"). Suggest limiting the sentence to fields other than F₂ and to persistent-homology consumers. Smaller stale text of the same kind:
    • docs/README.md:73 ("proposed … finite-test extensions").
    • The earlier Unreleased CHANGELOG entry (CHANGELOG.md:56, "no erosion test is included"), which reads as contradicting the new entry right below it. Suggest "that module includes no erosion test".
      The docs/api.md sentence (lines 1185–1187) was updated consistently.
  2. NON-SUBSTANTIVE: results cannot be printed. ErosionResult and ErosionFailure derive only DecidableEq, so #eval runErosion R S e fails with "Could not synthesize a ToExpr, Repr, or ToString instance" (checked). The API is still usable through decide +kernel and pattern matching, and the contract fixes the derivations. Adding deriving Repr is a harmless follow-up.
  3. NON-SUBSTANTIVE: the emptyGrid_zero docstring is imprecise (F2GridErosionExamples.lean:170). "An empty coordinate set leaves no grade to test in that coordinate of the first grid" is inaccurate. The value list is empty, so the first grid has no grade and its Kan extension is zero. The breakpoint grid itself is not empty: it is {0, ±1}, taken from zero.
  4. NON-SUBSTANTIVE: wording.
    • The module docstring says "a failure at radius 1/2 in either direction". This is the same violation with the arguments swapped; no single comparison fails both ways, and RankErosion is symmetric under the swap. That matches the contract's "swap the two representations", but saying "in either argument order" would be clearer.
    • Two lines in rank-erosion.md (165 and 232) are longer than the file's usual wrap. Cosmetic.

Observation (not a finding): #print axioms lists Classical.choice for runErosion, erosionFailure?, erosionFailureAt and erosionBreakpoints; the pre-existing rankAt lists it too. It sits only in proof positions: decide +kernel reduces every fixture, and compiled #eval runs. So the executable path does not get stuck on choice. pointList depends on propext only.

Risks 1–6

  1. Contract fidelity: holds.
    • Every name, definition body and theorem type matches the contract verbatim, with docstrings added (F2GridErosion.lean 34–36, 61–63, 66, 68, 71–73, 96, 99, 101–109, 120–132, 135–146, 149–164, 168–330). The only extra is a local open RatGrid.
    • pointList uses [Fin.elim0]. erosionBreakpoints uses .dedup over the same six-part concatenation.
    • runErosion_eq_fail matches conjunct by conjunct: validity, 0 ≤ e, hpq, breakpoint membership of source and target, narrowRank < wideRank, the two direction implications with the same extensions, and ¬ RankErosion.
    • No extra hypotheses, nothing specialised.
  2. Meaning: holds.
    • (a) Direction. firstWide = true is taken exactly when S.rankAt p q < R.rankAt (lower e p) (upper e q), that is, R's wide rank exceeds S's narrow rank. This violates RankErosion's first conjunct with M = R's extension and N = S's (RankErosion.lean:100–104). runErosion_eq_fail lines 299–308 assign wideRank and narrowRank to the right extension in each direction.
    • (b) erosionFailure?_eq_none_iff states, for valid input, that the absence of a failure is equivalent to the existing weak-pair RankErosion (radius e he) of R.grid.lan.obj (R.toModule hR) and S.grid.lan.obj (S.toModule hS). radius casts to (e : ℝ) (coe_radius is rfl).
    • (c) Exhaustive and exclusive. The three constructors are distinct. invalid holds iff the input is invalid. pass holds iff the input is valid and the predicate holds. fail w implies the input is valid and the predicate fails. So for valid input, failure of the predicate forces fail. Together this is [Multi PH computation] Certify finite-grid rank-erosion tests #925's completeness statement.
    • (d) A fail with narrowRank ≥ wideRank, or at a non-comparable pair, is excluded by runErosion_eq_fail (it gives narrowRank < wideRank and hpq). A pass despite a violated real pair is excluded by runErosion_eq_pass_iff: RankErosion quantifies over all real pairs a ≤ b.
    • (e) grid_erosionBreakpoints is a genuine equality of CoordinateGrids, proved by funext/ext with List.mem_dedup; dedup does not change membership.
  3. Faithfulness to [Multi PH computation] Certify finite-grid rank-erosion tests #925: discharged. See the judgement below.
  4. Examples: all correct. Each was checked by hand and, for the cases listed above, by #eval.
    • interval/zero at 1/4. The breakpoints are [1, 0, 5/4, 3/4, 1/4, −1/4]. The only failing pair is (1/4, 1/4) in direction true, with ranks 1 and 0. A failure needs p ≥ 1/4 and q < 3/4.
    • Sampling only original values misses it. interval_zero_original_values_pass covers every comparable pair from the union {0, 1} of both grids' values, and quarter_not_grid_value shows that 1/4 is in neither list. Together they faithfully state that sampling original values misses the failure.
    • interval/zero at 1/2 passes. A failure would need 1/2 ≤ p ≤ q < 1/2. The true threshold is 1/2, and the predicate is weak, so passing at 1/2 is correct; at 49/100 the test fails, as it should.
    • interval/zero at radius 0 fails on the diagonal at (0, 0) with ranks 1 and 0. The swapped run records false with ranks 1 and 0.
    • Rays.
      • At radius 1 they pass by hand: wide rank 1 forces p ≥ 1 or p ≥ 2, where the narrow rank is 1.
      • At 1/2 the failing pairs are (1/2, 1), (1/2, 3/2) and (1/2, 1/2), all true (all three listed by the #eval). The first in enumeration order is (1/2, 1), as reported. The swapped run gives false.
    • interval/messy at radius 0 passes: they are the same module.
    • shifted/interval. At 1/2 they pass: a failure would need p ≥ −3/2 and q < −3/2. At 1/4 they fail at (−7/4, −7/4), a negative shifted breakpoint, with ranks 1 and 0.
    • noCoordinates. Against itself it passes, since the identity rank is 3 on both sides. Against noCoordinatesTwo it fails with ranks 3 and 2, direction true.
    • plane against itself passes at 0 and 1/2: the rank of a composite is at most the rank of each factor.
    • plane/flat at 0 fails at the origin with ranks 2 and 1.
    • plane/flat at 1 passes; checked by hand. A wide map of plane would need its source floor at the origin (0 ≤ p − 1 < 1) and its target floor at the origin (q + 1 < 1), which is impossible for p ≤ q. So every wide rank of plane is at most 1, and it is nonzero only when p ≥ (1, 1), where flat's narrow rank is 1. Conversely, flat's wide rank is 1 only when p ≥ (1, 1), where plane's narrow map is the identity at (1, 1), rank 1. So the two-dimensional fiber never meets a wide map, and the pass is correct. The test also passes at 1/2.
    • emptyGrid/zero: both extensions are zero, so the pass is correct.
    • Invalid cases: both are genuine (the composition failure and e = −1).
    • Transfer theorems. The three are genuine consequences: interval_zero_not_rankErosion takes the last conjunct of runErosion_eq_fail, and the other two take runErosion_eq_pass_iff.
    • No vacuous or mislabelled fixture.
  5. Semantic and API quality: holds, apart from findings 1–4.
    • The module docstring, docs/api.md, rank-erosion.md and the CHANGELOG all say a failure refutes the predicate at radius e and is not a distance lower bound. They state the F₂ restriction, the cost and the absence of minimisation.
    • The four notes from the feat(persistence): executable F₂ grid representations and their Kan-extension ranks (#999) #1000 review are folded in:
      • "exactly when" became "when", with the necessity converse marked as not formalised.
      • The RatGrid dot-notation sentence was added.
      • The plane_rank_between docstring was rewritten. Checked against the floors: [1/2, 0] has floor (0, 0), [1/2, 3] has floor (0, 1), and the map between them is the all-ones 1×2 matrix, of rank 1.
      • The zero-dimensional fiber at interval's value 1 is now named.
    • The CHANGELOG anchor #a-certified-finite-test exists (rank-erosion.md:162).
    • Reuse is concrete: rankErosion_lan_iff_of_subset, rankAt_eq_of_eq, realGrade_le_iff and ratPoint.
    • The certificate is usable: Bool direction plus the two grades and the two ranks. The hypotheses are natural: validity and 0 ≤ e, existentially packed in the pass/fail statements.
  6. Bookkeeping: holds.
    • Pins: 14 public theorems in F2GridErosion.lean plus 31 in F2GridErosionExamples.lean give 45, matching the 45 appended pins exactly. Each new pin occurs once in the file; there is no mismatch, and no existing pin line was changed.
    • The aggregator diffs add only import lines: the library module in TDA/Persistence.lean, the examples in TDA/Persistence/Examples.lean.
    • No Lean line in the four touched Lean files exceeds 100 characters (counted as characters).
    • No scratch artefact or chronology in tracked files. The -- … (Issue #1001) pin header follows the existing convention.

#925 discharge judgement

Taken together, #997, #999 and this PR fully discharge #925's mathematical and implementation requirements:

  • Inputs. Two F₂ representations, possibly on different rational grids, and a rational ε ≥ 0.
  • Validation. Identity and composition are validated by finite decidable computation ([Multi PH computation] Executable F₂ matrix representations on rational grids and their Kan-extension ranks (#925, part 2) #999 Valid); dimensions are intrinsic to the matrix types.
  • Invalid input is distinguishable from failure (invalid, runErosion_eq_invalid_iff).
  • No caller-supplied ranks or certificates.
  • Finite criterion. It is discharged in an equivalent proved form instead of explicit cell representatives. [Multi PH computation] Finite test-grid criterion for rank erosion of grid Kan extensions (#925, part 1) #997's real criterion works with floors on any finite grid that contains the breakpoints. grid_erosionBreakpoints with erosionFailure?_eq_none_iff(_forall) turns it into finitely many comparable rational grade pairs. Floors, missing lower points and upper tails are handled by rankAt, rankAt_eq and the criterion.
  • Executable certificate and completeness. Covered by the three runErosion theorems; ranks come from the certified F2Matrix.rank.
  • Fixtures cover every required case:
    • original values are insufficient;
    • both directions;
    • diagonal at ε = 0;
    • negative cuts;
    • different grids;
    • zero fibers;
    • n = 0;
    • two parameters, passing and failing;
    • an empty list;
    • invalid input.
  • Kernel-checked consumers of the full predicate: three, one failing and two passing.
  • Cost statements: P² pairs, ranks exponential in fiber dimension, grades exponential in n, no cubic or polynomial bound.
  • Non-claims are stated: no strict ε < dE ≤ dI, no minimisation, no Gaussian elimination, F₂ only, no input generator.

What remains is process only: a successful hosted check on this head, an exact-head regular review, and reconciliation and closure on #925 by the owner or orchestrator.

Checks not performed

  • No lake build, scripts/check.sh, axiom audit, coverage or Comparator rerun (relied on the reported gate evidence for this head).
  • Hosted CI check not observed.
  • No proof-internal audit beyond reading.
  • No #eval of badComposition, negative_radius, noCoordinates or the plane-against-itself fixtures (checked by hand and by the reported decide +kernel gate).

Generated by Claude Code

@t-uda
t-uda merged commit 1b6c2d9 into develop Nov 20, 2026
4 checks passed
t-uda added a commit that referenced this pull request Nov 20, 2026
…1003) (#1004)

Fold the non-substantive notes from the final-head reviews of #996 and #1002 into the rank-erosion documentation, the changelog, the executed-example docstrings and the cloud setup guide; ErosionFailure and ErosionResult also derive Repr. No statement, proof or pin changes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RfoZqCRSgoUin4otWc6fXL
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants