ADR-117: Add source-anchored canonical minimum cut implementation#287
Merged
ADR-117: Add source-anchored canonical minimum cut implementation#287
Conversation
Introduces source-anchored canonical min-cut based on Kenneth-Mordoch 2026, with lexicographic tie-breaking (λ, first_separable_vertex, |S|, π(S)) for unique reproducible cuts. Three-tier plan: exact engine now, O(m log²n) fast path, then dynamic maintenance via sparsifiers. Integrates with RVF witness hashing for cut receipts. https://claude.ai/code/session_01UrVLJpxq8itzVxycy5sjNw
…-cut Full Tier 1 implementation of the Kenneth-Mordoch 2026 canonical min-cut algorithm with lexicographic tie-breaking (λ, first_separable_vertex, |S|, π(S)). Core implementation (source_anchored/mod.rs): - AdjSnapshot for deterministic computation on FixedWeight (32.32) - Stoer-Wagner global min-cut on fixed-point weights - Dinic's max-flow for exact s-t cuts - SHA-256 (FIPS 180-4, self-contained, no_std compatible) - SourceAnchoredMinCut stateful wrapper with cache invalidation - CanonicalMinCutResult repr(C) struct for FFI WASM bindings (wasm/canonical.rs): - Thread-safe Mutex-guarded global state (no static mut) - 8 extern "C" functions: init, add_edge, compute, get_result, get_hash, get_side, get_cut_edges, free, hashes_equal - Constant-time hash comparison for timing side-channel prevention - Null pointer validation on all FFI entry points - Graph size limit (10,000 vertices) to prevent OOM Tests (40 total): - 33 source_anchored tests: SHA-256 NIST vectors, determinism (100+1000 iterations), symmetric graphs (K4, K5, cycles, ladders, barbells), custom source/priorities, disconnected rejection, FFI conversion - 7 WASM tests: init/compute lifecycle, null safety, hash comparison, self-loop rejection, size limit enforcement Benchmarks (canonical_bench.rs): - Random connected graphs (10-100 vertices) - Cycle and complete graph families - Hash stability measurement Security hardening: - No static mut (Mutex for thread safety) - Integer-exact FixedWeight arithmetic (no floats in comparisons) - Checked capacity perturbation bounds - Source-side orientation invariant enforced - NIST-validated SHA-256 for witness hashes ADR-117 updated to production-quality spec with explicit vertex-splitting requirement for capacity perturbation, WASM FFI documentation, and Phase 1 completion status. https://claude.ai/code/session_01UrVLJpxq8itzVxycy5sjNw
- Enable `canonical` feature on ruvector-mincut dependency - Add `partition_canonical_full()` to KnowledgeGraph using source-anchored canonical min-cut for deterministic, hashable partitions - Add `canonical` query parameter to `/v1/partition` endpoint - Add `cut_hash` (hex SHA-256) and `first_separable_vertex` fields to PartitionResult and PartitionResultCompact types - Backward compatible: canonical fields are skip_serializing_if None, only populated when `?canonical=true` is passed https://claude.ai/code/session_01UrVLJpxq8itzVxycy5sjNw
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements ADR-117: Pseudo-Deterministic Canonical Minimum Cut, adding a new source-anchored canonical minimum cut API to
ruvector-mincut. This provides a unique, deterministic canonical cut suitable for RVF witness generation, proof-gated mutations, and structural identity tracking across the RuVector stack.Key Changes
New canonical module (
crates/ruvector-mincut/src/canonical/source_anchored/):SourceAnchoredCutstruct: represents the canonical cut with lambda value, first separable vertex, side vertices, and SHA-256 hashSourceAnchoredConfig: configuration for source vertex, vertex ordering, and per-vertex prioritiescanonical_mincut(): main entry point computing the canonical cut via Stoer-Wagner + s-t cut probingSourceAnchoredMinCut: stateful wrapper for dynamic graph mutations with epoch trackingWASM FFI bindings (
crates/ruvector-mincut/src/wasm/canonical.rs):canonical_init(),canonical_add_edge(),canonical_compute()for graph constructioncanonical_get_result(),canonical_get_hash(),canonical_get_side(),canonical_get_cut_edges()for result retrievalMutexfor testing compatibilitycanonical_hashes_equal()Integration with MCP brain server:
partition_canonical_full()method inKnowledgeGraphfor deterministic clusteringcanonicalquery parameter in partition endpointcut_hashfield inPartitionResultfor witness compatibilityDocumentation:
Benchmarks (
crates/ruvector-mincut/benches/canonical_bench.rs):Algorithm Details
The canonical cut is uniquely determined by the lexicographic tuple:
Where:
The implementation uses capacity perturbation to enforce lexicographic ordering during max-flow computation, ensuring the chosen side minimizes cardinality and priority sum among all minimum s-t cuts.
Notable Implementation Details
FixedWeightas 32.32 fixed-point) and stable SHA-256 hashing for receipt generationcanonicalfeature flag inCargo.tomlhttps://claude.ai/code/session_01UrVLJpxq8itzVxycy5sjNw