Fix overhead deltas filtering and flags (#454)

[willwashburn]

Summary

• makes burn overhead deltas honor project filtering and relative or ISO --since cutoffs in both all-session and session-specific modes
• rejects unsupported or duplicate flags instead of silently ignoring them, while preserving valid trim flag placement
• changes ContextDeltaOpts::since from Option<Duration> to Option<String>; the release train should account for this Rust SDK source break
• matches literal and canonical project path spellings so existing ledgers remain queryable across symlink-resolved paths

Validation

• cargo fmt --all -- --check
• cargo test --workspace
• cargo clippy --workspace --all-targets

Fixes #454

🤖 Generated with Claude Code.

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 42 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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c9b63001-e932-46d4-b52c-88af52b52424

📥 Commits

Reviewing files that changed from the base of the PR and between 1a107e2 and 726199f.

📒 Files selected for processing (4)

• CHANGELOG.md
• crates/relayburn-sdk/src/analyze/context_delta.rs
• crates/relayburn-sdk/src/query_verbs/flow.rs
• crates/relayburn-sdk/src/query_verbs/tests.rs

📝 Walkthrough

Walkthrough

The CLI now handles overhead filters at subcommand scope and rejects unsupported or duplicate flags. The SDK accepts relative or ISO since values, filters project and session context deltas, preserves unknown timestamps, and reports overflow errors.

Changes

Context-delta filtering and overhead CLI

Layer / File(s)	Summary
Overhead flag contracts and dispatch crates/relayburn-cli/src/cli.rs, crates/relayburn-cli/src/commands/overhead.rs, crates/relayburn-cli/tests/smoke.rs	Subcommands define supported filters. Dispatch merges scoped values, rejects conflicts and unsupported --kind, resolves project paths, and forwards string-based --since values.
Session delta cutoff contract crates/relayburn-sdk/src/analyze.rs, crates/relayburn-sdk/src/analyze/context_delta.rs, crates/relayburn-sdk/src/analyze/context_delta_tests.rs	ContextDeltaOpts::since now accepts strings. Session delta calculation receives a cutoff and retains eligible unknown-timestamp inferences.
Project and timestamp query filtering crates/relayburn-sdk/src/query_verbs/flow.rs, crates/relayburn-sdk/src/query_verbs/mod.rs, crates/relayburn-sdk/src/query_verbs/tests.rs	Context-delta queries support project paths, session filtering, relative ranges, ISO timestamps, and overflow validation.
Release notes CHANGELOG.md	The changelog documents the updated SDK and CLI behavior.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant ContextDeltaQuery
  participant NormalizeSince
  participant SessionDiscovery
  participant DeltasForSessionSince
  CLI->>ContextDeltaQuery: pass project and since filters
  ContextDeltaQuery->>NormalizeSince: normalize relative or ISO since
  ContextDeltaQuery->>SessionDiscovery: select eligible sessions
  SessionDiscovery-->>ContextDeltaQuery: return matching turns and inferences
  ContextDeltaQuery->>DeltasForSessionSince: calculate deltas with cutoff
  DeltasForSessionSince-->>CLI: return filtered context deltas

Loading

Poem

I’m a rabbit with flags in my paws,
Filtering deltas by timestamps and paths.
No duplicate carrots, no --kind surprise,
ISO dates hop through the query with ease.
Overflow is stopped before it can grow.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: fixing filtering and flag handling for overhead deltas.
Description check	✅ Passed	The description directly explains the filtering, flag validation, SDK changes, path handling, and validation for this changeset.
Linked Issues check	✅ Passed	The changes address issue #454 by fixing supported flags, since validation, relative and ISO cutoffs, project handling, session consistency, and regression coverage.
Out of Scope Changes check	✅ Passed	The changes remain within issue #454 scope, including related CLI, SDK, tests, and changelog updates.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ 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 issue-454-overhead-deltas-flags

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1a107e28f1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

🧹 Nitpick comments (1)

CHANGELOG.md (1)

8-8: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

State the --kind behavior directly.

Replace the removed-behavior wording with the user-visible result: unsupported --kind is rejected with an error. This is clearer and more impact-focused.

Proposed wording

-- `burn overhead deltas` now honors `--project`, accepts relative or ISO `--since` values with explicit errors for invalid input, and no longer advertises or silently ignores the unsupported `--kind` flag.
+- `burn overhead deltas` now honors `--project`, accepts relative or ISO `--since` values with explicit errors for invalid input, and rejects the unsupported `--kind` flag.

🤖 Prompt for 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.

In `@CHANGELOG.md` at line 8, Update the changelog entry for “burn overhead
deltas” to state directly that the unsupported --kind flag is rejected with an
error, replacing wording about no longer advertising or silently ignoring it
while preserving the other documented behavior.

Source: Coding guidelines

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

Nitpick comments:
In `@CHANGELOG.md`:
- Line 8: Update the changelog entry for “burn overhead deltas” to state
directly that the unsupported --kind flag is rejected with an error, replacing
wording about no longer advertising or silently ignoring it while preserving the
other documented behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bcaf7a2a-0858-4d00-8315-2ac0850d2c98

📥 Commits

Reviewing files that changed from the base of the PR and between 962b2b7 and 1a107e2.

📒 Files selected for processing (10)

• CHANGELOG.md
• crates/relayburn-cli/src/cli.rs
• crates/relayburn-cli/src/commands/overhead.rs
• crates/relayburn-cli/tests/smoke.rs
• crates/relayburn-sdk/src/analyze.rs
• crates/relayburn-sdk/src/analyze/context_delta.rs
• crates/relayburn-sdk/src/analyze/context_delta_tests.rs
• crates/relayburn-sdk/src/query_verbs/flow.rs
• crates/relayburn-sdk/src/query_verbs/mod.rs
• crates/relayburn-sdk/src/query_verbs/tests.rs

[cubic-dev-ai]

All reported issues were addressed across 10 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[willwashburn]

Addressed both automated review findings in f98b5a9: context-delta project paths now expand to the Git-derived project key in the SDK (covered by a nested-repository/different-checkout regression), and the changelog now states directly that unsupported --kind is rejected. Full workspace tests, formatting, and clippy pass.

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>