Skip to content

feat(reachability-lab): fail-closed fragment range holdout (ADR-0032) - #170

Merged
PhysShell merged 2 commits into
mainfrom
claude/holdout-fragment-mode
Jul 29, 2026
Merged

PhysShell merged 2 commits into
mainfrom
claude/holdout-fragment-mode

Conversation

@PhysShell

Copy link
Copy Markdown
Owner

What

The final identity-level ADR-0032 slice: HoldoutTargetFragment — holdout by exact sha256 plus inclusive bar_range overlap. RED→GREEN, in the isolated reachability-lab/ crate. Fragment mode only; song / source-file / NoCorpus / LeakyDiagnostic unchanged.

Contract

  • TargetIdentity gains bar_range: Option<(u32,u32)> and track_index: Option<u32> (per-mode explicit; track_index is provenance only and never narrows exclusion).
  • Execution order: check_binding → source_file_preflight → require source_sha256 → validate target range (InvalidTargetBarRange on first > last) → fragment preflight (malformed range on any target-source manifest chunk → FragmentPreflight) → partition by exact sha256 AND ranges_overlap → refuse if nothing excluded (TargetFragmentAbsent) → compile survivors.
  • Overlap predicate (inclusive, applied only after sha256 equality): either side None = whole-source overlap; [0,3] overlaps [3,5] (endpoint) and [2,5] (partial) and [0,9] (containing); [0,2] does not overlap [3,5]; different source hashes never overlap. No exact-equality shortcut.
  • bar_range: None is a valid whole-source target — never a missing-field error.
  • Independent of song curation: does not run song_holdout_preflight, does not require song_id.

Tests (RED → GREEN, 45 total)

The 17-point matrix: missing target sha256; sha256-less chunk (source preflight); inverted target range; inverted manifest range on the target source; target None excludes all; chunk None overlaps any target range; exact/contained/containing/partial/endpoint-touching excluded; disjoint same-source remains; overlap from another source hash remains; cross-track overlap excluded (track never narrows); no-overlap refuses; target only in a skipped record refuses; song-uncurated corpus succeeds; keeper-only equality across references/rhythms/gesture/skipped; binding refuses first; determinism; plus a direct ranges_overlap predicate table. Existing 28 song/source-file tests unchanged.

Docs folded in (carried debts cleared)

Module / README / Cargo now describe all three modes; the "ADR-0032 first slice" heading is gone; prepare_corpus_for_mode rustdoc + # Errors now cover song, source-file, and fragment refusals; inclusive-range / None-whole-source / track-is-provenance / curation-independence all documented.

Verification

cargo test -p …reachability-lab → 45/45 green; clippy --all-targets (all=deny) + rustfmt + cargo doc clean. Isolated crate → not exercised by workspace CI (ADR-0010 precedent); verified locally under nix.

Out of scope

Measurement / eligibility / projection axes, song_id curation + tooling, production CLI/cockpit wiring, scoring/generation changes, track-index recovery.

🤖 Generated with Claude Code

https://claude.ai/code/session_012T7SRMiXmZe5v1imtrKMPi

PhysShell and others added 2 commits July 29, 2026 08:22
Tests-only; the crate fails to compile until the fragment API lands in GREEN
(TargetIdentity.{bar_range, track_index}, CorpusMode::HoldoutTargetFragment,
HoldoutError::{InvalidTargetBarRange, FragmentPreflight, TargetFragmentAbsent},
FragmentHoldoutRefusal, the ranges_overlap predicate).

HoldoutTargetFragment excludes every same-source chunk whose inclusive range
overlaps or contains the target range — never merely exact matches:
- missing target sha256, and (via source preflight) any sha256-less chunk,
  refuse;
- an inverted target range refuses (InvalidTargetBarRange); an inverted
  manifest range on the target source refuses before filtering
  (FragmentPreflight);
- target bar_range None = whole source, excluding every target-hash chunk; a
  chunk bar_range None overlaps every target range on the same source;
- inclusive exact / contained / containing / partial / endpoint-touching are
  excluded; disjoint same-source ranges remain; overlap from another source
  hash remains;
- overlap across different tracks is excluded (track_index is provenance, not
  an exclusion constraint);
- no overlap, or a target only in a skipped/unloaded record, typed-refuses
  (TargetFragmentAbsent);
- a song-uncurated but fully hash-identified corpus succeeds; material equals
  keeper-only across references, rhythms, gesture, and skipped; full-ChunkMeta
  binding still refuses first; deterministic.
- ranges_overlap predicate table (inclusive, None = whole-source).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012T7SRMiXmZe5v1imtrKMPi
Implement HoldoutTargetFragment:
- TargetIdentity gains bar_range + track_index (per-mode explicit; track is
  provenance only);
- CorpusMode::HoldoutTargetFragment;
- ranges_overlap: inclusive, None on either side = whole-source overlap,
  applied only after exact sha256 equality (never exact-equality shortcut);
- fragment_preflight rejects a malformed range (first > last) on any
  target-source manifest chunk (FragmentHoldoutRefusal::InvalidBarRange);
  bar_range None is valid and never refused;
- order: check_binding -> source_file_preflight -> require source_sha256 ->
  validate target range (InvalidTargetBarRange) -> fragment_preflight ->
  partition by exact sha256 AND range overlap (track never narrows) -> refuse
  if nothing excluded (TargetFragmentAbsent) -> corpus_material;
- fragment mode does NOT run song_holdout_preflight and does NOT require
  song_id.

Docs folded in: module/README/Cargo describe all three modes; the "first
slice" heading is gone; prepare_corpus_for_mode rustdoc + # Errors now cover
song, source-file, and fragment refusals; ranges/None/track/curation
semantics documented.

45/45 tests green; clippy (all=deny, pedantic=warn), rustfmt, and rustdoc
clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012T7SRMiXmZe5v1imtrKMPi
@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown

Warning

Review limit reached

@PhysShell, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 13 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ed48de36-284e-489e-9b1a-b4635d9b6a90

📥 Commits

Reviewing files that changed from the base of the PR and between 2ff8172 and c67e6b6.

📒 Files selected for processing (3)
  • reachability-lab/Cargo.toml
  • reachability-lab/README.md
  • reachability-lab/src/lib.rs

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

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

@PhysShell
PhysShell merged commit 357b5ae into main Jul 29, 2026
15 checks passed
@PhysShell
PhysShell deleted the claude/holdout-fragment-mode branch July 29, 2026 09:20
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.

1 participant