Add execplan for ClusteringSession::refresh (11.2.1) by lodyai[bot] · Pull Request #185 · leynos/chutoro

lodyai · 2026-07-22T21:13:28Z

Summary

Adds the execution plan
docs/execplans/11-2-1-implement-clustering-session-refresh.md
for roadmap item 11.2.1 — implement ClusteringSession::refresh.

refresh merges the retained MST backbone, historical edges, and pending
edges; reweights them with the mutual-reachability formula using current core
distances; constructs a fresh EdgeHarvest; runs parallel_kruskal; extracts
labels via extract_labels_from_mst; and publishes an Arc<Vec<usize>> label
snapshot while advancing snapshot_version.

This PR contains only the ExecPlan (Status: DRAFT). Per the execplans
workflow, implementation does not begin until the plan is approved.

How the plan was produced

Wyvern reconnaissance team mapped the batch CPU primitives
(parallel_kruskal, extract_labels_from_mst, EdgeHarvest, MstEdge,
CandidateEdge), the existing session state and core-distance mechanics, and
the repo's test/BDD/Makefile conventions.
$firecrawl confirmed the incremental-MST strategy against the FISHDBC
prior art (Dell'Amico, 2019, arXiv:1910.07283).
A df12 Logisphere community-of-experts review stress-tested the draft and
drove a substantial revision (see the plan's Decision Log and Revision Note).

Key design decisions

Raw-backbone retention. Retain selected MST edges as raw CandidateEdge
(not weighted MstEdge) and reweight from raw each refresh, so weights do not
ratchet upward across refreshes as core distances fall. Refines design
Figure 3; captured in ADR-005 (to be added during implementation).
Hexagonal split. A pure rebuild_mst_labels domain function (merge →
reweight → Kruskal → extract → recover backbone) separated from the impure
HNSW-backed core-distance recompute; the shared mutual_reachability_weight
helper is homed in the lower cpu_pipeline layer.
Contiguous point-id invariant with a CpuMstFailure guard (no new error
variant, no panic).
Graceful degenerate handling (empty and all-noise snapshots) so warm-up
sessions make progress rather than erroring.
Verification: a substantive Verus lemma (raw-retention reweight
faithfulness + merge multiset preservation), a proptest suite including a
multi-refresh differential property, and an optional bounded Kani harness.

Validation

make markdownlint passes for the changed document.

References

Lody session: https://lody.ai/leynos/sessions/eeb05df7-6674-43bc-8a12-879a4a559979

🤖 Generated with Claude Code

Summary by Sourcery

Add the draft ExecPlan for implementing ClusteringSession::refresh and publishing incremental clustering labels.

Enhancements:

Add a draft execution plan for implementing incremental clustering-session refreshes, including label snapshots, MST rebuilding, edge reweighting, and refresh-state semantics.

CI:

Update the testing guidance to use cargo nextest with warnings denied and benchmark targets excluded.

Documentation:

Document the proposed refresh workflow, design constraints, verification obligations, milestones, and acceptance criteria for roadmap item 11.2.1.

sourcery-ai

Sorry @LodyAI[bot], you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

coderabbitai · 2026-07-22T21:13:36Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b0ff2045-fab0-4bdb-89f3-8d14d793202b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch 11-2-1-implement-clustering-session-refresh

Warning

Your free Security trial is over. An organization admin can activate billing to continue.

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

Draft the execution plan for roadmap item 11.2.1: implement `ClusteringSession::refresh`, which merges the retained MST backbone, historical edges, and pending edges, reweights them with mutual reachability using current core distances, runs `parallel_kruskal`, and extracts a published flat-label snapshot. The plan was shaped by a Wyvern reconnaissance pass over the batch CPU pipeline and session state, validated against the FISHDBC prior art, and revised after a df12 Logisphere community-of-experts review. Key design decisions recorded: raw-backbone retention (to avoid cross-refresh weight drift), graceful degenerate handling, a lower-layer mutual-reachability helper, reuse of existing error variants, and the contiguous point-id invariant. Status: DRAFT — awaiting approval before implementation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The repository's `typos`/nixie spelling gate enforces -ize/-ization forms (Oxford-compatible). Replace formalises/optimisation/canonicalised. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Fold in three findings from the user's gap review: - Adopt `googletest`, `pretty_assertions`, and `insta` as dev-dependencies with concrete usage assignments in the new refresh test suites. These are the approved assertion crates from the rust-unit-testing brief and are currently unused anywhere in the workspace; this milestone starts the practice. - Switch the pure rebuild from `EdgeHarvest::from_unsorted` + `parallel_kruskal` to the crate-internal `parallel_kruskal_from_edges` entry point, removing a redundant O(E log E) sort and an intermediate allocation. Recorded as a Decision Log deviation from the roadmap item's literal "construct a fresh EdgeHarvest" wording. - Document that dedup of the overlapping merged buffers happens in `mst::prepare_edge_list`, not `EdgeHarvest`, and add an overlap-tolerance unit test to the pure-function suite. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

AGENTS.md documented `make test` as `cargo test --workspace`, but the Makefile actually runs `cargo nextest run --profile <default|ci> --all-targets --all-features -E 'not kind(bench)'` with warnings denied. Describe the real invocation, including the profile selection and the benchmark exclusion. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The execplans skill now mandates two further living sections and a milestone-plateau structure. Restructure the plan accordingly, preserving every reviewed design decision: - Add `Conformance Basis` with stable upstream identifiers (RM-11.2.1, DES-12.x, DES-FIG3), trace links from requirements through milestones to named acceptance tests, and the three recorded deviations (raw-backbone Figure 3 refinement, `parallel_kruskal_from_edges` wording, degenerate-size behaviour). - Restructure verification into a `Verification Plan` with named obligations OBL-1..OBL-8, explicit axioms AXM-1..AXM-5, per-obligation method, domain, artefact, and evidence, and non-vacuity arguments including two planned seeded-fault mutation checks. - Replace the standalone red-tests milestone with red-green-refactor stages inside each milestone so every milestone ends in a validated plateau (EP-M1..EP-M5), each with a conformance check, recovery path, and an explicit no-compatibility-machinery decision. - Add `Artefacts and notes` as the destination for mutation and proof transcripts. No design or scope decisions changed; the plan still awaits approval. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

codescene-access

No quality gates enabled for this code.

sourcery-ai Bot reviewed Jul 22, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

lodyai Bot force-pushed the 11-2-1-implement-clustering-session-refresh branch from fc8755f to 57ed1e1 Compare August 6, 2026 23:41

This comment was marked as outdated.

Sign in to view

leynos and others added 2 commits August 16, 2026 04:35

Use -ize spelling in 11.2.1 execplan to satisfy typos gate

d7edf4b

The repository's `typos`/nixie spelling gate enforces -ize/-ization forms (Oxford-compatible). Replace formalises/optimisation/canonicalised. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

leynos force-pushed the 11-2-1-implement-clustering-session-refresh branch from 57ed1e1 to d7edf4b Compare August 16, 2026 02:36

This comment was marked as outdated.

Sign in to view

leynos and others added 2 commits August 16, 2026 04:43

This comment was marked as outdated.

Sign in to view

codescene-access Bot approved these changes Aug 23, 2026

View reviewed changes

Navigation Menu

Add execplan for ClusteringSession::refresh (11.2.1) - #185

Add execplan for ClusteringSession::refresh (11.2.1)#185
lodyai[bot] wants to merge 5 commits into
mainfrom
11-2-1-implement-clustering-session-refresh

lodyai Bot commented Jul 22, 2026 •

edited by sourcery-ai Bot

Loading

Uh oh!

sourcery-ai Bot left a comment

Uh oh!

coderabbitai Bot commented Jul 22, 2026 •

edited

Loading

Review skipped

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

codescene-access Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

lodyai Bot commented Jul 22, 2026 • edited by sourcery-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How the plan was produced

Key design decisions

Validation

References

Summary by Sourcery

Uh oh!

sourcery-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

codescene-access Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

lodyai Bot commented Jul 22, 2026 •

edited by sourcery-ai Bot

Loading

coderabbitai Bot commented Jul 22, 2026 •

edited

Loading