perf(exec): serial disposition for maximum_spanning_tree (#580)

[DecisionNerd]

Implements #580: serial disposition for maximum_spanning_tree.

Closes #580

  

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Note

Add serial disposition for analyze(by=MaximumSpanningTree) with test coverage

• Adds serial_kruskal_descending_union_find as the fixed disposition for GraphForge::analyze with MaximumSpanningTree, with no parallel crossover regardless of compute_threads.
• Adds a run_analyze_maximum_spanning_tree test helper that exercises the analyze call, checks determinism across two invocations, and records WorkloadEvidence with the new disposition.
• Extends the M4 entry matrix contract and CI validation script to require the analyze-maximum-spanning-tree workload and validate it against structural gates.
• Documents the serial-only policy in execution-resource-policy.md.

^{Macroscope summarized ceb8dc4.}

Summary by CodeRabbit

• Tests

  • Added coverage for maximum-spanning-tree analysis using deterministic, cost-weighted graph data.
  • Added repeatability checks for results, output fingerprints, ordering, row counts, and bounded output.
  • Included the workload in short and large execution matrices with validation of serial processing behavior.

• Documentation

  • Documented why spanning-forest analysis uses serial processing to preserve consistent edge-selection results.

[coderabbitai]

Walkthrough

Added deterministic maximum-spanning-tree analysis coverage to the M4 baseline and entry matrix. The workload compares repeated results, fingerprints output, records timing and RSS, and documents serial union-find execution.

Changes

Maximum-spanning-tree M4 coverage

Layer / File(s)	Summary
Maximum-spanning-tree workload evidence crates/graphforge-api/tests/m4_entry_baseline.rs, crates/graphforge-exec/src/algorithm_analyze_minimum_spanning_forest.rs	The baseline runs GraphForge::analyze twice, compares results, fingerprints output, records timing and RSS, and reports serial Kruskal/union-find metadata.
M4 matrix contract integration tests/contracts/m4-entry-matrix.json, scripts/ci/m4-entry-matrix.py	The entry matrix defines maximum-spanning-tree execution and structural gates. CI validation now requires the workload ID.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• perf(exec): polish scale/performance for analyze(by="minimum_spanning_tree") #582 — Covers the same deterministic serial maximum-spanning-tree workload and contract requirements.

Possibly related PRs

• CurateLabs/graphforge#485 — Introduced the M4 entry-baseline harness and contract extended by this change.
• CurateLabs/graphforge#645 — Documents and validates serial execution for order-dependent analysis algorithms.

Suggested labels: ci-cd

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description states the issue and summarizes the implementation, but it omits most required template sections, testing details, checklist items, and reviewer notes.	Complete the required description sections, including change type, testing commands and coverage, checklist confirmations, performance impact, breaking changes, and reviewer notes.
Linked Issues check	❓ Inconclusive	The changes support the serial disposition, deterministic workload evidence, and CSR/Arrow CI gates, but cancellation, limits, structured errors, documentation, and CI results are not fully verifiable.	Provide evidence for cancellation, limits, structured errors, exact-head CI, and the excluded execution-resource policy documentation.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	All reviewed changes directly support the linked issue by documenting, testing, and enforcing the maximum spanning tree serial disposition.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly identifies the main change: a serial execution disposition for maximum spanning tree analysis.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/580-serial-maximum-spanning-tree-disposition-c6a4

---

_{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 `@crates/graphforge-api/tests/m4_entry_baseline.rs`:
- Around line 606-620: Replace the hard-coded execution fields in the baseline’s
structural evidence with values observed from the GraphForge::analyze algorithm
path. Instrument or expose assertions for the actual thread policy, CSR
projection, and bounded Arrow sink behavior, and populate threads_path,
csr_native_projection, and bounded_arrow_sink from those observations rather
than constants.
- Around line 593-603: Add a fixture-specific correctness assertion in the
maximum_spanning_tree test before constructing WorkloadEvidence, validating the
expected selected edge endpoints and weights (or comparing against the approved
fixture fingerprint). Keep the existing assert_logical_batch_equal check to
preserve determinism coverage.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 6fc9c8ef-17fb-46db-b3f7-7388c025273b

📥 Commits

Reviewing files that changed from the base of the PR and between 26fb547 and 4ead674.

⛔ Files ignored due to path filters (1)

• docs/development/execution-resource-policy.md is excluded by !**/*.md, !**/docs/**

📒 Files selected for processing (4)

• crates/graphforge-api/tests/m4_entry_baseline.rs
• crates/graphforge-exec/src/algorithm_analyze_minimum_spanning_forest.rs
• scripts/ci/m4-entry-matrix.py
• tests/contracts/m4-entry-matrix.json