perf(overlap): filter active stems before pair comparisons

[seonghobae]

Performance and correctness slice

detect_register_overlap now filters active pitched stems per register band before pair comparison, preserving real FFT-derived register occupancy while reducing pair work from all pitched stems to the active subset for each band.

Protected base: develop@acdbea6344fe1231c39535b575f4de35e4c607c9.
Exact current head: 05533f29f299bf8077d3df61b6ee404d9a956985.
Draft remains required.

Exactly four files differ from protected develop:

• services/analysis-engine/src/bandscope_analysis/roles/overlap.py
• services/analysis-engine/tests/test_register_overlap.py
• services/analysis-engine/tests/test_register_overlap_threshold_contract.py
• CHANGELOG.md

No dependency, root-lock, .trivyignore, workflow, database, network/filesystem authority, model, or IPC change remains on this head. Canonical dependency-security ownership stays in #783; audio job resource admission stays in #781/#866 rather than this feature analyzer.

Exact-head drift repair and TDD contract

Earlier valid work established active-stem filtering and fixed equal-severity ordering so ties retain alphabetical pair order followed by declared BANDS order instead of lexical band names.

A later branch head a559d65eafe1d0e94a5564ca7590d34be3a2427b drifted outside that boundary: it carried silent feature-local sample/stem caps, .jules changes, a CVE-2026-16633 Trivy ignore, and npm/PDF.js lock churn owned elsewhere. Successor #870 repaired that exact drift and added one further valid correctness boundary: Boolean, non-finite, or out-of-range threshold configuration fails closed instead of allowing threshold coercion or fabricated overlap evidence; silent stems remain non-evidence even at nonpositive edge thresholds.

Rather than keep a competing owner, the canonical #801 branch was fast-forwarded non-destructively to #870 exact head 05533f29f299bf8077d3df61b6ee404d9a956985. #870 was then closed as a proven duplicate because #801 and #870 now pointed to the same exact commit/tree.

Current behavior includes:

• active-stem filtering per band before pair comparison;
• no feature-local audio-sample or stem-count ceiling;
• invalid threshold (bool, non-finite, outside 0.0..1.0) => fail-closed empty result;
• zero-energy stems never become overlap evidence merely because threshold is zero/negative;
• equal-severity results preserve historical pair + BANDS ordering;
• no shared dependency/security suppression or lockfile repair in this branch.

Focused #870 verification on this exact tree reported 22 passing overlap/threshold tests. That predecessor execution is diagnostic evidence only; fresh #801 exact-head repository workflows/reviews must be used for merge classification.

Gate state

A fresh exact-head repository workflow cycle is required for 05533f29f299bf8077d3df61b6ee404d9a956985; queued/in-progress/predecessor evidence is not success. Any failure must be inspected at exact job/annotation/log level before another edit or rerun.

Do not merge until #783 reaches protected develop and security gates are regenerated cleanly; #861's Python branch-coverage baseline is integrated/revalidated; the central .github#939 → #1020 prerequisite chain reaches protected central main and exact-current-head central review/coverage is regenerated; zero actionable threads remain; a qualifying independent non-author last-push approval exists; and live branch protection permits merge without bypass.

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[coderabbitai]

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: CHILL

Plan: Pro Plus

Run ID: e98944b3-a4a4-4db0-817c-1d0bae4fe048

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

---

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.}

[opencode-agent]

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head a922c371769767f4ebce10d63502485cac63caa3.

• Head SHA: a922c371769767f4ebce10d63502485cac63caa3

• Workflow run: 31327369360

• Workflow attempt: 1

Coverage evidence

Coverage evidence job did not run or did not publish coverage evidence.

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (7 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (7 files)"]
  R1 --> V1["required checks"]

Loading

[opencode-agent]

OpenCode Review Overview

• Head SHA: 93dd0f234e6d44e32141940fa1577320575b44d0
• Workflow run: 31632354273
• Workflow attempt: 1
• Gate result: REQUEST_CHANGES (approval step)

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head 93dd0f234e6d44e32141940fa1577320575b44d0.

• Head SHA: 93dd0f234e6d44e32141940fa1577320575b44d0

• Workflow run: 31632354273

• Workflow attempt: 1

Coverage evidence

Coverage evidence job did not run or did not publish coverage evidence.

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (6 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (6 files)"]
  R1 --> V1["required checks"]

Loading

[opencode-agent]

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head 93dd0f234e6d44e32141940fa1577320575b44d0.

• Head SHA: 93dd0f234e6d44e32141940fa1577320575b44d0

• Workflow run: 31632354273

• Workflow attempt: 1

Coverage evidence

Coverage evidence job did not run or did not publish coverage evidence.

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (6 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (6 files)"]
  R1 --> V1["required checks"]

Loading

[seonghobae]

@opencode-agent address

Operate only if the live head is exactly 93dd0f234e6d44e32141940fa1577320575b44d0; otherwise stop without writing and report the new head. Rebuild this as a bounded register-overlap performance PR.

Restore .jules/bolt.md, apps/desktop/package.json, package.json, package-lock.json, and the generated fix_pdfjs.cjs exactly to protected develop (or delete the generated helper if it does not exist there). PR #783 exclusively owns the JavaScript dependency/PDF.js/Undici baseline. Do not make this DSP optimization depend on that security diff.

Preserve observable semantics while reorganizing candidate selection. Add test-first coverage in services/analysis-engine/tests/test_register_overlap.py using an independent scalar pair×band oracle over deterministic profile fixtures so the optimized band-first path must exactly preserve: threshold equality/inclusion, all qualifying bands, alphabetical stem-pair ordering, descending severity, deterministic equal-severity tie behavior, unpitched exclusion, malformed/silent fail-safe behavior, and no duplicate records. Include a sparse many-stem fixture demonstrating that only threshold-active stems enter pair generation; do not gate CI on wall-clock timing. If the implementation intentionally changes tie ordering beyond the documented pre-change stable order, either remove that unrelated behavior change or document and test a product reason for it.

The final base-to-head scope should be services/analysis-engine/src/bandscope_analysis/roles/overlap.py, services/analysis-engine/tests/test_register_overlap.py, and one concise Unreleased CHANGELOG.md performance entry. Keep this Python path explicitly behavior-equivalent and do not weaken the repository's Rust/native numerical-parity direction; if register-overlap remains a production numerical hotspot without a Rust kernel, record that as follow-up rather than claiming this PR establishes full native/GPU parity.

Run focused/full analysis-engine tests at 100% owned production statement/branch coverage, public API docstrings 100%, Ruff check/format, mypy, compileall, applicable native/Rust parity gates, and repository quickcheck. Then request fresh exact-current-head CI/security/SAST/SBOM/central coverage/review. Existing OpenCode CHANGES_REQUESTED and any polluted-head checks remain non-transferable; after #783 lands, update onto the current protected base and revalidate.

Dismissed as stale review evidence: this request was anchored to predecessor head a922c37. Current exact head b317318 has successful coverage-evidence and opencode-review checks. This dismissal does not provide or replace independent approval.

[seonghobae]

@opencode-agent Review the exact current head only. Do not update branches, enable auto-merge, or merge.

[cursor]

Stale comment

Review (head a559d65e)

The active-stem filter is sound: same overlap set as the old pair-major loop, and the sort key restores alphabetical-pair then BANDS tie order. Do not merge this head.

The PR body still describes isolated head 7a3f566 (three files, feature-local guards removed, .jules / Trivy / npm extras absent). Current head is an eight-file Bolt revert that puts those extras back and adds silent product-breaking caps.

Blockers

1. Silent 10M-sample cap in band_energy_profile zeros any stem longer than ~3.8 minutes at 44.1 kHz. Separation already admits 15 minutes at TARGET_SR = 44100. A valid full-song rehearsal then gets no density warnings and no user-facing error. This is the #781 failure mode.
2. Silent 10-pitched-stem abort returns [] with only a log line. Current htdemucs is 4 stems / 3 pitched, so this is latent, but the public API and tests lock the silence. #781 and this PR's own 7a3f566 / 11221cfc work already assigned admission to canonical audio_resource_policy.
3. Scope creep vs #783. .jules/*, .trivyignore CVE-2026-16633, and pdfjs/nanoid/undici lock churn do not belong in an overlap optimization. The ignore cites 6.1.200 while the same head bumps to 6.2.108 (the patch). That is not a documented false-positive exception.
4. Threshold clamp fabricates warnings. b55e21c6 failed closed on bool / non-finite / out-of-range and required share > 0.0. This head clamps negatives to 0.0, so silent stems satisfy 0.0 >= 0.0.
5. Dropped contract. Unreleased CHANGELOG, test_equal_severity_keeps_declared_band_order, and test_register_overlap_threshold_contract.py are gone. The new tests encode the silent caps as required behavior.

Next action

Use #870 (05533f29) instead of this head. It restores the isolated 171f0ab0 slice: active-stem filter, BANDS tie order, fail-closed thresholds, policy-owned admission regressions, CHANGELOG. No Trivy ignore and no npm edits. Local overlap tests: 22 passed.

Keep #801 Draft, or close it as superseded by #870. Leave resource admission on #781 / #866 and the npm/PDF.js baseline on #783.

  

_{Sent by Cursor Automation: fix all}

[cursor]

Review (head 05533f29)

Previous blockers on a559d65e are gone. This head is the isolated four-file slice: active-stem filter, BANDS tie order, fail-closed thresholds, policy-owned admission regressions, Unreleased CHANGELOG. No sample/stem caps, no .trivyignore, no npm/PDF.js churn.

detect_register_overlap now matches the claimed contract. Silent stems stay non-evidence at threshold 0.0 because occupancy still requires share > 0.0. Boolean / non-finite / out-of-range thresholds return [].

Do not merge this draft.

Remaining merge gates (not code defects on this head)

1. Keep Draft until exact-head required checks finish. Queued/in-progress runs are not success.
2. #783 still owns the npm/PDF.js/Nanoid/Undici baseline. Do not land this overlap slice ahead of that security regeneration.
3. #861 branch-coverage and the central .github#939 → #1020 chain remain external prerequisites named in the PR body.
4. Independent non-author last-push approval is still required by live protection. This comment is current-head inspection, not that approval.

Product gap (next loop, not this PR)

detect_register_overlap is still unused in production. RoleExtractor._build_roles keeps fabricating Density warning / Melodic overlap strings, so a buyer never sees FFT-derived section warnings. Wiring belongs in a successor, not this bounded perf slice.

Leave resource admission on #781 / #866.

  

_{Sent by Cursor Automation: Fix Issues}

[seonghobae]

Superseded by canonical role-overlap PR #873 with the complete #801 history preserved. Fresh exact-state verification shows #801 still at 05533f29f299bf8077d3df61b6ee404d9a956985 and #873 at 9f1e166da9acf043b7f4b8b6df84b5e1a2417706. compare(05533f29…, 9f1e166d…) reports ahead_by=6, behind_by=0, with merge-base exactly 05533f29…; therefore every #801 commit is an ancestor of #873. #873 adds the buyer-visible section/role wiring and fail-closed evidence semantics on top of the preserved active-stem filtering/threshold/order contract. No #801 check/review evidence transfers to #873.