Relax the dependency graph in Nassau's compute_through_stem

[JoeyBF]

Implements the relaxation flagged by the long-standing comment in nassau.rs: computing (s, t) only needs (s, t-1) and (s-1, t-1), not (s-1, t) and (s, t-1). The comment noted that "having the dimensions of the modules change halfway through the computation is annoying to do correctly" — this handles that.

What

• compute_through_stem now uses the relaxed wavefront (s, t) <- (s, t-1), (s-1, t-1) for s >= 2, keeping many t-diagonals (n = t - s fixed) in flight at once. Rows s = 0, 1 stay strict — they're cheap, and step0/step1 read their targets through full matrices.
• step_resolution_with_subalgebra reads its target C_{s-1} using only generators of degree < t (and C_{s-2} of degree < t-1). By minimality the differentials we lift land in the radical, so the degree-t generators — which (s-1, t) may be adding concurrently — contribute neither to the kernel we quotient by nor to those differentials. The read is thus race-free against those append-only writes, with no locking. New helpers: a generator-degree bound on signature_mask, plus restricted_dimension and restricted_partial_matrix.
• Differentials are stored in the restricted (radical) basis, and the quasi-inverse save files always take the existing "incomplete information" (Magic::Fix) path, which the secondary machinery already handles.
• ModuleHomomorphism::apply_to_basis_element now allows a result buffer shorter than the full target dimension (a prefix of the target basis); the matching truncated differential means act never writes past it. This is the only change outside nassau.rs.

Notes

The relaxed graph shortens the critical path to (S, T) from ~S + T to ~T: a whole internal-degree column can compute in parallel once the previous one is committed. Nassau can afford this because each bidegree already computes the kernel it consumes locally (it reduces the incoming differential d_{s-1}), so relaxing shares nothing across bidegrees and duplicates no work.

Remark: the classical resolution (resolution.rs)

The same relaxation is mathematically valid for MuResolution — ker(d_{s-1})_t is a column-(t-1) object there too (see the existing get_kernel comment) — but it is not a free win. The classical algorithm reduces the outgoing differential at each bidegree and gets ker(d_{s-1})_t as the byproduct of the single row reduction it does at (s-1, t) to place that row's generators, handing it forward through the kernel cache. That reuse is exactly the (s-1, t) -> (s, t) edge. Relaxing means decoupling "find kernel" (column-(t-1)) from "place generators" (which needs (s-2, t)) and scheduling/caching the kernel independently — the get_kernel stem-edge path is already a special case of this. Done carefully it costs no extra reductions, only holding the reduced matrix live a little longer (memory) plus the scheduling refactor; done naively (cache only the Subspace, recompute the matrix) it doubles the expensive reductions. Left out of this PR since p=2 workloads use Nassau in practice, but noted here for the record.

Test plan

All with --features concurrent (the parallel path; maybe_rayon runs sequentially otherwise):

• cargo test -p ext --lib nassau:: — test_restart_stem, plus a new test_stem_concurrent_secondary (save-backed d2 cross-check against the standard resolution, exercising the Magic::Fix quasi-inverse path)
• cargo test -p ext --test milnor_vs_nassau — existing compare, plus a new wide compare_stem cross-check against the standard resolution (S_2, C2 to n=40/s=30; Joker to n=30/s=20), run 12× at RAYON_NUM_THREADS=16 for determinism
• full cargo test -p ext — green except the pre-existing save_load_resolution::test_tempdir_lock (unrelated: it relies on read-only directory bits that root bypasses)
• builds and tests pass in both the default and concurrent feature configurations

🤖 Generated with Claude Code

https://claude.ai/code/session_01MCUtWj6P6suSZqvATCdg6d

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added support for calculating partial basis-action results and matrices using caller-defined target dimensions.
  • Added dimension queries that account only for generators below a specified degree, improving consistency during ongoing computations.
  • Added bounded generator-degree filtering to Nassau resolution calculations.

• Bug Fixes

  • Improved Nassau computation scheduling and preservation of restricted calculation behavior.

• Tests

  • Added cross-checks comparing Nassau and standard resolutions across multiple degrees and boundary cases.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 7690b9de-6886-4e72-8b5d-c82a42eea843

📥 Commits

Reviewing files that changed from the base of the PR and between 80d614f and 43dc7e9.

📒 Files selected for processing (3)

• ext/crates/algebra/src/module/free_module.rs
• ext/crates/algebra/src/module/homomorphism/free_module_homomorphism.rs
• ext/src/nassau.rs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds bounded free-module dimension and homomorphism operations, applies them throughout Nassau resolution construction, relaxes concurrent stem scheduling, and adds comparisons against standard-resolution results.

Changes

Bounded basis and matrix contracts

Layer / File(s)	Summary
Bounded basis and matrix contracts ext/crates/algebra/src/module/free_module.rs, ext/crates/algebra/src/module/homomorphism/free_module_homomorphism.rs	Adds bounded generator-dimension queries, restricted basis-element application, and partial matrices with caller-provided target dimensions. Tests cover strict generator bounds and computed offsets.

Restricted resolution computation

Layer / File(s)	Summary
Restricted resolution step and persistence ext/src/nassau.rs	Adds bounded signature masks and matrices. Nassau steps use frozen target dimensions for differentials, correction terms, and quasi-inverse persistence. Saved quasi-inverses use Magic::Fix.

Concurrent stem scheduling

Layer / File(s)	Summary
Relaxed concurrent stem scheduling ext/src/nassau.rs	Updates readiness, wavefront seeding, and successor spawning for same-row and diagonal dependencies.

Resolution validation

Layer / File(s)	Summary
Resolution equivalence validation ext/tests/milnor_vs_nassau.rs, ext/src/nassau.rs	Adds parameterized stem comparisons and a save-backed concurrent-stem test that compares Nassau and standard-resolution results.

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: ⚪ Minimal · up to 43dc7

This change enables more concurrent Nassau stem computation while using bounded resolution data; current validation compares its results with the standard resolution, and no merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant compute_through_stem
  participant step_resolution_with_subalgebra
  participant signature_matrix
  participant get_partial_matrix_restricted
  participant resolution_state
  compute_through_stem->>resolution_state: identify ready stem position
  compute_through_stem->>step_resolution_with_subalgebra: compute Nassau step
  step_resolution_with_subalgebra->>signature_matrix: build bounded target matrix
  step_resolution_with_subalgebra->>get_partial_matrix_restricted: build restricted differential
  get_partial_matrix_restricted-->>step_resolution_with_subalgebra: return fixed-dimension matrix
  step_resolution_with_subalgebra-->>resolution_state: save step and quasi-inverse

Loading

Poem

A rabbit bounds the basis bright
Restricted columns fit just right
Nassau hops through stems in rows
Fixed inverses guide the flows
Two resolutions meet and compare
Carrot-tested charts align with care

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.73% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: relaxing the dependency graph in Nassau's compute_through_stem.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ext/crates/algebra/src/module/homomorphism/free_module_homomorphism.rs`:
- Around line 65-71: Enforce the truncated result bound in the homomorphism
action method containing the result-length assertion: ensure both
output_on_generator and target.act write only within result’s provided prefix,
using a bounded action API or a dedicated restricted method that validates the
invariant. Keep the generic full-dimension behavior unchanged and prevent
shorter buffers from causing out-of-bounds writes.

In `@ext/src/nassau.rs`:
- Around line 1052-1055: Update the row-1 readiness branch in the progress check
so the stem-boundary case `(1, max_n + 1)` does not bypass row 0. Compute the
required one-bidegree row-0 dependency halo before this check, then retain
strict readiness validation against the corresponding row-0 progress rather than
treating `t > max_n` as automatically satisfied.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6b01d781-3d1c-4c33-ab32-35cc51bf1ca3

📥 Commits

Reviewing files that changed from the base of the PR and between 4867b30 and 727a2c2.

📒 Files selected for processing (3)

• ext/crates/algebra/src/module/homomorphism/free_module_homomorphism.rs
• ext/src/nassau.rs
• ext/tests/milnor_vs_nassau.rs

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

ext/src/utils.rs (1)

598-662: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider a small unit test for thread-local independence.

This subtle invariant — a stolen job's PARALLEL_DEPTH is scoped to its worker thread, not global — has no direct test in this file; it's presently exercised only indirectly through Nassau's concurrent scheduling. A focused test (e.g. spawn two std::threads, hold a ParallelGuard on one, assert is_in_parallel() is false on the other) would cheaply pin down this behavior against future regressions (e.g. accidentally reverting to a shared counter).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ext/src/utils.rs` around lines 598 - 662, Add a focused unit test alongside
ParallelGuard and is_in_parallel that spawns two OS threads, holds a
ParallelGuard on one thread, and verifies is_in_parallel() remains false on the
other thread while the guard is active. Ensure the test synchronizes the threads
so the assertion specifically validates thread-local independence.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@ext/src/utils.rs`:
- Around line 598-662: Add a focused unit test alongside ParallelGuard and
is_in_parallel that spawns two OS threads, holds a ParallelGuard on one thread,
and verifies is_in_parallel() remains false on the other thread while the guard
is active. Ensure the test synchronizes the threads so the assertion
specifically validates thread-local independence.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 679a693a-61e7-4998-a8ba-af03976cc2b8

📥 Commits

Reviewing files that changed from the base of the PR and between 5beaf22 and 80d614f.

📒 Files selected for processing (2)

• ext/src/nassau.rs
• ext/src/utils.rs