Skip to content

feat(mapper): executable graph-PL incidence extraction with certified component labels (#1005) - #1007

Merged
t-uda merged 1 commit into
developfrom
ccr-eb669e62-a5kqoa
Nov 20, 2026
Merged

t-uda merged 1 commit into
developfrom
ccr-eb669e62-a5kqoa

Conversation

@t-uda

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

Copy link
Copy Markdown
Contributor

Closes #1005

Summary

First of two units of #923: the executable half of graph-PL incidence extraction.

  • TDA/Mapper/GraphPLIncidence.lean: HeightGraph N (Boolean adjacency on Fin N, rational vertex heights) with decidable Valid; the sorted distinct levels and the covering list criticalValues; component labels by N rounds of minimum-label propagation along horizontal edges, with label_eq_label_iff_reachable (label equality is reachability in the actual graph induced on {v | realHeight v = c}) and the bijection componentEquiv with SimpleGraph.ConnectedComponent; the executed lists cellList, edgeList, incidence, and incidence?, which rejects invalid adjacency.
  • TDA/Mapper/GraphPLIncidenceExamples.lean: the complete executed value for no vertex, one vertex, two isolated vertices, a horizontal edge, two unjoined vertices of one height, a crossing edge, a four-cycle, a triangle with two parallel entries, a level component needing more than one propagation round (with its label equality transferred to the actual induced graph), and two invalid inputs.
  • Documentation: a subsection of docs/math/mapper.md, the Mapper row of docs/api.md, a CHANGELOG.md line.

Not included (the second unit, #1006): FiniteReebData of the lists, the isomorphism with graphPLReebData, the Reeb quotient comparison.

Branch lifecycle

Ordinary develop topic: based on develop 0a49f5b12ed09191b70054120ee9b4355c6503cb, target develop, squash merge. Target scope: Reeb computation under #923/#227; release version undecided. Propagation: N/A.

Public declarations added / changed

Added, all in TDA.Mapper.GraphPL: HeightGraph with HeightGraph.Cell, Incidence, Valid, instDecidableValid, graph, instDecidableRelGraphAdj, graph_adj, realHeight, realHeight_eq_iff, levels, levels_pairwise, mem_levels, levels_ne_nil, levels_of_eq_zero, gapCount, length_levels, level, level_strictMono, level_mem_levels, exists_level_eq, range_level, criticalValues, criticalValues_value, coversVertexHeights, horizontal, relax, labels, label, label_le, height_label, label_label, label_eq_label_iff_reachable, componentEquiv, componentEquiv_apply, componentEquiv_symm_mk, vertexPairs, cellsWith, leftEndWith, rightEndWith, edgesWith, cellList, leftEnd, rightEnd, edgeList, incidence, incidence?, incidence_levels, incidence_cells, incidence_edges, incidence?_eq_some_iff, incidence?_eq_none_iff, levels_getElem?, incidence_cells_getElem?, incidence_edges_getElem?, mem_cellList_inl, mem_cellList_inr, nodup_cellList, mem_edgeList, nodup_edgeList, leftEnd_mem_cellList, rightEnd_mem_cellList; and the fixtures of GraphPLIncidenceExamples. No existing declaration changes.

Relative to the contract in #1005, two supporting lemmas are added: level_mem_levels and exists_level_eq. No listed statement is changed.

Source ↔ Lean correspondence

Library-derived unit; no external source statement. The governing specification is #923 and the contract #1005, whose statements were checked before admission by an independent reviewer that proved them in its own scratch files. The three index lemmas levels_getElem?, incidence_cells_getElem? and incidence_edges_getElem? were added to the contract after that review; the final-head review below checked them and the two supporting lemmas.

Validation

Evaluated head fba3bc694420f867c24a86d8a685b01490160752, base 0a49f5b12ed09191b70054120ee9b4355c6503cb.

  • Local scripts/check.sh (full gate) on this head: exit 0, CHECK OK; AXIOM AUDIT OK — 13686 declaration(s), PRIVATE AUDIT — 10521 private theorem root(s), COVERAGE OK — 11007 public theorems, all pinned, Comparator accepted (1m47s). Base: 13593 / 10503 / 10954.
  • git push pre-push gate: passed.
  • Hosted check for this head: success — https://github.com/uda-lab/tda-lib/actions/runs/44664602300/job/136050739470 ; the log reports AXIOM AUDIT OK — 13686 declaration(s), PRIVATE AUDIT — 10521 private theorem root(s), COVERAGE OK — 11007 public theorems, all pinned, Lean default kernel accepts the solution, CHECK OK, the same counts as the local run.
  • Not run: scripts/test-guards.sh, doc generation, a timing of compiled incidence on large inputs (the cost paragraph is a documented count, not a measurement of this head).

Remaining sorry / custom-axiom footprint

none

Independent review evidence

🤖 Generated with Claude Code

https://claude.ai/code/session_01RfoZqCRSgoUin4otWc6fXL

… component labels (#1005)

Add HeightGraph (Boolean adjacency on Fin N with rational heights), its
decidable validity, the sorted distinct levels as a covering critical-value
list, component labels by minimum-label propagation with the theorem that label
equality is reachability in the actual induced level graph, and the executed
cell and edge lists with their membership and no-repetition statements.
Fixtures state the complete executed value for nine graphs and two invalid
inputs.

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-20T03:00:50.413894Z fba3bc6 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)

Reviewed head: fba3bc694420f867c24a86d8a685b01490160752 (base develop 0a49f5b12ed09191b70054120ee9b4355c6503cb), governing contract #1005 (part 1 of #923).

Verdict: pass with non-substantive notes. No substantive finding.

Findings

  1. Contract conformance (no finding). I compared every declaration in [Reeb computation] Executable graph-PL incidence extraction with certified component labels (#923, part 1) #1005 with the source one by one. I also elaborated each listed theorem statement, copied verbatim from the contract, as an example closed by the library declaration in a scratch file against the warm head build. All elaborate. There is no extra hypothesis and no weakening. levels, relax, labels, cellsWith, leftEndWith/rightEndWith, edgesWith and incidence match the contract bodies. The only scratch error was mine: my componentEquiv example lacked noncomputable.

  2. Statements outside the pre-admission review (no finding).

    • levels_getElem? is correctly indexed: level i is levels.get (i.cast _).
    • incidence_cells_getElem? maps level index i to cellList (level i).
    • incidence_edges_getElem? maps gap e to edgeList (level e.castSucc) (level e.succ): lower level first, upper level second, matching zip levels levels.tail.
    • level_mem_levels and exists_level_eq are true and are the two directions behind range_level and coversVertexHeights.
    • These lemmas are not vacuous. Scratch check: crossing.gapCount = 2, crossing.level 1 = 1, crossing.level 2 = 2.
  3. Mathematical correctness (no finding).

    • The Within k invariant of iterate_relax shows that after k rounds the label of v is reached within k horizontal steps and is at most every vertex within k steps.
    • within_of_reachable uses IsPath.length_lt (a path has fewer than N edges), so N rounds suffice, including N = 0 and N = 1.
    • label_eq_label_iff_reachable goes through a private horizontal graph and transfers both ways to the actual (graph hX).induce {v | realHeight v = c}. No caller-supplied relation enters the statement.
    • componentEquiv is built by ConnectedComponent.lift, and both inverse laws are proved, not assumed.
    • Cells and spanning edges are filtered over ordered pairs with strict height y.1 < c < height y.2, or with height y.1 ≤ p < q ≤ height y.2 for a gap. So each undirected edge appears once as (lower, upper), and horizontal edges never appear.
    • Parallel entries are kept because the entries are indexed by the edge itself.
    • incidence? only tests Valid; nothing is symmetrised or repaired.
    • No proof is trivially true for the wrong reason. The rfl proofs (incidence_cells, incidence_edges, componentEquiv_apply/_symm_mk, levels_of_eq_zero) are genuine definitional unfoldings.
  4. Hygiene (no finding).

    • No sorry, admit, native_decide, axiom, implemented_by or extern in either new module.
    • The TDA/Mapper.lean and TDA/Mapper/Examples.lean changes are one import line each.
    • The scripts/print_axioms/Mapper.lean diff has 93 added lines and 0 removed lines, appended at the end. Every public declaration of both modules is pinned, including level_mem_levels, exists_level_eq and the examples' edgeAdj.
    • Scratch #print axioms shows only propext, Classical.choice, Quot.sound.
  5. Fixtures (no finding). I recomputed every fixture value by hand and they agree, including the vertexPairs lexicographic order (vee: (2,0),(2,1)) and bent's one-round vector [0,1,0,3]. The acceptance list of [Reeb computation] Executable graph-PL incidence extraction with certified component labels (#923, part 1) #1005 is covered:

    Required case Fixture
    N = 0 empty
    single vertex single
    disconnected apart
    horizontal edge flat
    repeated heights with a joining edge flat, triangle
    repeated heights without a joining edge vee
    isolated vertex crossing (vertex 2), apart
    crossing edge crossing
    cycle diamond
    parallel entries with a checked statement triangle_edgeList, triangle_parallel
    invalid asymmetric / loop oneWay, loop
    more than one round bent: least index 0 is not adjacent to 1; bent_one_round shows one round is insufficient
    consumer on the actual induced graph bent_reachable instantiates label_eq_label_iff_reachable

    My own extra fixtures under #eval/decide +kernel also agree:

    • a five-vertex level path 1-2-3-4-0 needs more than 3 rounds and gets all labels 0 after N rounds;
    • a mixed graph with a horizontal edge at a middle level and a crossing edge gives the expected cells and edges;
    • compiled #eval of incidence runs, including on invalid input.
  6. Documentation (no substantive finding).

    • The module docstring, docs/math/mapper.md § Executable incidence extraction, the docs/api.md Mapper row and CHANGELOG.md describe what is proved.
    • They state explicitly that FiniteReebData, the identification with graphPLReebData and the Reeb quotient comparison are not included. There is no overclaim.
    • The anchor #executable-incidence-extraction resolves to the new ### heading, which is unique. Declaration names in the docs exist.
    • The cost paragraph is honest. It says the counts are "documented, not proved", restricts the bound to incidence/incidence? and says the statement forms recompute labels. It also gives the honest Classical.choice explanation (bound proofs of vector indexing), consistent with the contract.
  7. Non-substantive notes (optional).

    • (a) The docstring of label ("the least index in its level component") and the matching module-doc bullet are exact only for valid input. For asymmetric adjacency, "component" is not defined and the label is the least index reached by directed horizontal chains. A qualifier such as "for valid input" would be more precise.
    • (b) docs/math/mapper.md says {v | realHeight v = c} is "the vertex set of the level components above". The module docstring names LevelVertex in TDA.Mapper.GraphPLReebData; naming it here as well would remove the ambiguity of "above".
    • (c) The cost paragraph in docs/math/mapper.md lists label, cellList, edgeList as recomputing, while the module docstring also lists leftEnd/rightEnd. It also omits the O(N²) validation cost stated in the contract. These are minor omissions, not false.
    • (d) API surface: edgeAdj in the examples namespace is a public helper. That is acceptable, since it is pinned and namespaced to the examples. I found no reuse candidate in mathlib for executable level-component labelling; mathlib's ConnectedComponent is the semantic target and is used.

Checked / not checked

  • Checked: the full diff of all 8 files; statement-by-statement contract comparison (elaborated); proofs read for vacuity; hand recomputation of all fixtures plus reviewer fixtures; append-only pins; forbidden-token grep; anchors; PR body declaration list.
  • Not checked:
    • I did not run lake build, scripts/check.sh or doc generation, and I did not time compiled incidence on large inputs. I rely on the implementer's reported local gate and on the admission reviewer's cubic-growth measurement.
    • Hosted check for this head was still in_progress when I looked (build succeeded). Merge still requires it to succeed.
    • I did not read the implementer's scratch drafts.

Generated by Claude Code

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