Skip to content

feat(mapper): identify the executed graph-PL incidence lists with graphPLReebData and the Reeb quotient (#1006) - #1008

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 #1006

Summary

Second and last unit of #923: the semantic bridge from the executed incidence lists of #1005 to the existing graph-PL Reeb data and the Reeb quotient.

  • TDA/Mapper/GraphPLIncidenceReebData.lean: HeightGraph.reebData reads the executed cell and edge lists of a valid input as FiniteReebData over the computed levels, without renumbering; reebDataIso is an isomorphism of finite data to graphPLReebData (X.graph hX) X.realHeight X.criticalValues, with the laws reebDataIso_hom_v_inl, reebDataIso_hom_v_inr, reebDataIso_hom_e; extractReebDataIso (through graphPLExtractIso) and reebQuotientIso (through graphPLReebQuotientIsoOfIso) follow; isEmpty_realization is the case of no vertex.
  • TDA/Mapper/GraphPLIncidenceReebDataExamples.lean: two parallel edges of the triangle are different elements of the edge type with equal endpoints, and the simple incidence graph forgets one; the crossing cell of crossing and its image in the actual graph; the quotient comparison for the four-cycle; the empty input.
  • Documentation: the executable-extraction subsection of docs/math/mapper.md, the Mapper row of docs/api.md, the CHANGELOG.md entry of this feature.
  • Three non-substantive notes of the final-head review of PR feat(mapper): executable graph-PL incidence extraction with certified component labels (#1005) #1007 are folded in: the docstring of label, LevelVertex named in the math notes, and the cost paragraph of the math notes (statement forms leftEnd/rightEnd, validation cost).

Branch lifecycle

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

Public declarations added / changed

Added in TDA.Mapper.GraphPL.HeightGraph: reebData, reebData_left_coe, reebData_right_coe, reebData_left_eq_leftEnd, reebData_right_eq_rightEnd, reebDataIso, reebDataIso_hom_v_inl, reebDataIso_hom_v_inr, reebDataIso_hom_e, extractReebDataIso, reebQuotientIso, isEmpty_realization; and the fixtures of GraphPLIncidenceReebDataExamples. Changed: the docstring of HeightGraph.label and one sentence of the module docstring of TDA/Mapper/GraphPLIncidence.lean; no statement, definition body or proof of an existing declaration changes.

All listed statements of #1006 are present as stated; no supporting public lemma beyond the contract was added.

Source ↔ Lean correspondence

Library-derived unit; no external source statement. The governing specification is #923 and the contract #1006, whose statements were checked before admission by an independent reviewer that constructed the data and proved every statement in its own scratch files. extractReebDataIso was added to the contract after that review; the final-head review below checked its direction and covering list.

Validation

Evaluated head d2b0d9b54752522c3f8cc903a933d27c53f3e8d8, base ca0fec5a5efcd999820e508159897cb24032aecf.

  • Local scripts/check.sh (full gate) on this head: exit 0, CHECK OK; AXIOM AUDIT OK — 13713 declaration(s), PRIVATE AUDIT — 10536 private theorem root(s), COVERAGE OK — 11024 public theorems, all pinned, Comparator accepted (3m13s). Base: 13686 / 10521 / 11007.
  • git push pre-push gate: passed.
  • Hosted check for this head: success — https://github.com/uda-lab/tda-lib/actions/runs/44667402667/job/136059936334 ; the log reports AXIOM AUDIT OK — 13713 declaration(s), PRIVATE AUDIT — 10536 private theorem root(s), COVERAGE OK — 11024 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.

Remaining sorry / custom-axiom footprint

none

Independent review evidence

  • Read-only final-head review by a reviewer distinct from the implementer, on head d2b0d9b54752522c3f8cc903a933d27c53f3e8d8: pass with non-substantive notes — feat(mapper): identify the executed graph-PL incidence lists with graphPLReebData and the Reeb quotient (#1006) #1008 (comment) . Its notes (N1: one sentence of the math notes reads as the inverse of graphPLExtractIso where the inverse of reebDataIso is meant; N2: placement of the validation-cost sentence; N3, N4: optional) were not acted on, so the reviewed head is the head evaluated above; N1 and N2 are left for a documentation follow-up.
  • Codex automatic review on this head: completed with no findings.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RfoZqCRSgoUin4otWc6fXL

…phPLReebData and the Reeb quotient (#1006)

Read the executed cell and edge lists of a valid HeightGraph as finite Reeb
data over the computed levels, prove them isomorphic to graphPLReebData with
laws for component cells, crossing cells and listed edges, and derive the
comparison with the extracted path-component data and with the Reeb quotient
of the graph-PL height through the existing comparisons. With no vertex the
realization is empty. Fixtures keep two parallel edges apart and instantiate
the quotient comparison for a four-cycle. Fold in three notes of the review
of the first unit.

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:25:14.587155Z d2b0d9b 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: d2b0d9b54752522c3f8cc903a933d27c53f3e8d8 (base develop ca0fec5a5efcd999820e508159897cb24032aecf), against #1006 and #923, under lean-review-routing § Semantic and API quality.

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

Evidence

  1. Contract conformance. I compared all 12 declarations of [Reeb computation] Identify the executed graph-PL incidence lists with graphPLReebData and the Reeb quotient (#923, part 2) #1006 with the source, statement by statement. Every signature matches the contract block word for word, apart from line breaks. reebData, extractReebDataIso and reebQuotientIso also have exactly the stated bodies. In a scratch file I checked the following against the warm head build:
    • X.extractReebDataIso = fun hX => graphPLExtractIso … X.criticalValues X.coversVertexHeights ≪≫ (X.reebDataIso hX).symm and X.reebQuotientIso = fun hX => graphPLReebQuotientIsoOfIso … X.coversVertexHeights (X.reebDataIso hX) both hold by rfl.
    • reebDataIso has the contract type X.reebData hX ≅ graphPLReebData (X.graph hX) X.realHeight X.criticalValues.
    • extractReebDataIso relates X.criticalValues.extract (intervalComponents (plHeight …)) … to X.reebData hX in the stated direction (extract → executed). It is built from the existing graphPLExtractIso and the inverse of reebDataIso, at the same covering list X.criticalValues with X.coversVertexHeights.
    • No hypothesis was added and nothing was weakened. The only extra public surface is the fixture module.
  2. Mathematical correctness.
    • reebData uses the listed cells and listed edge entries as vertex and edge types, and its endpoint maps project the stored cells. Membership comes from leftEnd_mem_cellList / rightEnd_mem_cellList.
    • The vertex map sends inl r to connectedComponentMk ⟨r, _⟩ in the induced level graph and inr y to ⟨s(y.1, y.2), _⟩ as a crossing edge. The edge map sends a listed edge to s(y.1, y.2) as a spanning edge.
    • Injectivity on cells uses label_eq_label_iff_reachable together with the label fixed-point condition. Injectivity on crossing cells and edges excludes the swapped orientation by the strict height order. Surjectivity covers both orientations of a graph edge through le_total.
    • left_comm / right_comm split on whether the lower (or upper) end lies at the level. They use graphPLReebData_left_of_mem / _left_of_forall_ne and the right-hand versions. In the forall_ne case the other end is excluded by p < q ≤ height. The split is correct.
    • reebDataIso is a genuine isomorphism in FiniteReebData: it is built with Hom.inv / comp_inv / inv_comp from the two bijectivity proofs.
    • The three rfl laws are not trivial stand-ins: the forward map is defined explicitly. In scratch I proved that any morphism X.reebData hX ⟶ graphPLReebData … satisfying the three laws agrees with (X.reebDataIso hX).hom on every vertex and edge. So the claim "these laws determine it" is correct.
    • reebQuotientIso is about (ReebQuotient.quotientFunctor ℝ).obj (graphPLOver (X.graph hX) X.realHeight). It only applies graphPLReebQuotientIsoOfIso with X.coversVertexHeights; nothing is assumed.
    • isEmpty_realization uses exists_rep. Vertex cells over Fin 0 are eliminated, and there are no gaps because gapCount = 0. The statement is meaningful, not vacuous.
  3. Faithfulness to [Reeb computation] Extract certified finite graph-PL incidence data #923 ([Reeb computation] Executable graph-PL incidence extraction with certified component labels (#923, part 1) #1005 + [Reeb computation] Identify the executed graph-PL incidence lists with graphPLReebData and the Reeb quotient (#923, part 2) #1006 together).
  4. Hygiene.
    • No sorry, admit, native_decide, axiom, implemented_by or extern in the new files; the fixtures use decide +kernel.
    • The aggregator changes are one import line each.
    • GraphPLIncidence.lean changes only the module docstring and the docstring of label. The new label docstring is correct: label_le with reachability-iff gives least index.
    • Pins: 27 lines appended and 0 lines removed, covering the 12 core and 15 fixture public declarations.
    • #print axioms on the core and fixture declarations gives [propext, Classical.choice, Quot.sound].
  5. Fixtures. They cover the acceptance list of [Reeb computation] Identify the executed graph-PL incidence lists with graphPLReebData and the Reeb quotient (#923, part 2) #1006. I checked them by hand against GraphPLIncidenceExamples:
    • crossing has heights [0, 2, 1] and edge 0 — 1. Its middle level 1 holds .inl 2 and .inr (0, 1). The upper-gap entry is ((0, 1), .inr (0, 1), .inl 1), so its left end is the crossing cell and its right end is the component of vertex 1 at height 2. The docstrings are accurate.
    • In triangle both entries end at .inl 0 / .inl 1, since label 2 = 1 in the horizontal component {1, 2}. The docstrings are accurate.
  6. Documentation. The module docstring, both parts of the math subsection, the docs/api.md row and CHANGELOG.md are accurate. The stale "not included" / "does not compare" sentences from part 1 were removed; I grepped for leftovers and found none.

Findings (all non-substantive)

  • N1 (wording). docs/math/mapper.md: "extractReebDataIso composes graphPLExtractIso with its inverse". This reads as the inverse of graphPLExtractIso. Suggest "with the inverse of reebDataIso".
  • N2 (wording). In the cost paragraph, "Validation costs O(N²) units." comes after "these counts are documented, not proved". As a result it is unclear whether that qualifier also covers this count. Suggest moving the sentence before the qualifier.
  • N3 (optional API). There is no public lemma that characterizes leftEnd / rightEnd by the height case (for example leftEnd_of_height_eq / _of_height_ne); the proofs here use unfold leftEnd leftEndWith. The characteristic content is available through reebData_left_eq_leftEnd, the Hom laws and graphPLReebData_left_of_mem, so this is optional.
  • N4 (note, as contracted). crossing_upper_ends holds definitionally (rfl on the stored entry). diamond_reebQuotientIso is an instantiation with no derived consequence. Both match [Reeb computation] Identify the executed graph-PL incidence lists with graphPLReebData and the Reeb quotient (#923, part 2) #1006's acceptance list and its recorded non-adoptions. crossing_hom_v_inr is the general law applied at a concrete cell.

Checked / not checked

  • Checked: the full diff; scratch elaboration of the contract types and definitional bodies, the determination lemma, axioms and a non-emptiness spot check. Scratch is git-ignored under .agents/scratch/review-1008/.
  • Not run (per instructions): lake build, scripts/check.sh, scripts/bootstrap.sh. For mechanical coverage I rely on the PR's recorded gate. At review time the hosted check for this head was still in_progress (build succeeded); its success remains a merge precondition.
  • Not read: the implementer's 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