fix(cache): a sub-second TTL no longer becomes a permanent entry on the Dapr provider

[yilmaztayfun]

What

DaprDistributedCacheService.SetAsync converted the requested expiry to whole seconds with an (int) cast and only wrote the ttlInSeconds metadata when the result was greater than zero. Any expiry below one second rounded to 0, the metadata was dropped, and Dapr stores such an entry with no TTL at all — the caller asked for the shortest possible lifetime and got the longest one.

Both expiry branches now share one computation that rounds up, never falls below the store's one-second granularity, skips the write when the requested lifetime has already elapsed, and clamps very large TTLs instead of overflowing an int.

Why

Reported from vnext runtime 0.0.92 on preprod (2026-09-10). vnext caches a state-function response for 500 ms because that body cannot be validated from the parent row alone. The entry never expired: written 21:39:27, still served 142 seconds later at 21:41:50 with cache_hit=true, carrying a status the workflow instance had already left. The client acted on the stale body and got a 404. Trace ids 5c80e520b1b5c79e4a80d697c980e866, 0dbc92d9a7b2015c6daef80fff232272.

Lowering the caller's TTL to 1 ms changed nothing — 1 ms rounds to 0 exactly like 500 ms does. No configuration value below 1000 ms could express what the caller meant, which is what made this an Aether-level defect rather than a consumer tuning problem. Redis and .NET Core pass the TimeSpan through unchanged, so the bug was invisible in local development and only appeared where a Dapr state store is configured.

Defects fixed

1. Truncation, not rounding — (int)1.9 == 1; a 1.9 s entry expired 47 % early.
2. Sub-second absolute expiry silently lost its TTL — the ttl > 0 guard dropped the metadata. The severe case: no error, no log, no span tag.
3. The absolute and sliding branches disagreed — sub-second sliding wrote the literal ttlInSeconds: 0 instead of dropping it. The single requestedTtl switch makes this structurally impossible to reintroduce.
4. Large TTLs overflowed (not in the original report, found while reading the code) — DateTimeOffset.MaxValue as an absolute expiry produced ≈ 2.5 × 10¹¹ seconds; the unchecked cast sent a garbage ttlInSeconds to the store.
5. Culture-dependent formatting — ttl.ToString() used the current culture; now InvariantCulture.

Reviewer notes

This is a behaviour change for sub-second TTLs: they move from "permanent" to "1 second". That is the point — today those callers hold stale data indefinitely — but it is worth a deliberate look.

The skip path is reachable on a normal code path, and it is silent. DistributedCacheBase.GetOrSetAsync builds the caller's options before awaiting fetchFunc() and calls SetAsync after, so a sub-second absolute expiry paired with a slow fetch now skips the write entirely: the cache never populates and every request pays the full fetch. Under the framework's default Business tracing profile InfrastructureActivitySource.StartDiagnosticActivity returns null, so the new cache.skipped tag is a no-op and nothing reports this. The README warns about it and recommends SlidingExpiration (measured at write time) for short lifetimes, but giving DaprDistributedCacheService an optional ILogger — which RedisDistributedCacheService already takes — is recommended follow-up work.

Entries already written without a TTL are not repaired by this change. They expire only when overwritten. Consumers that depend on the fix (vnext's state-function cache) should flush or key-version their entries when this version rolls out.

The overflow test only fails pre-fix on x64. An out-of-range double→int conversion is unspecified in C#: it wraps on x64 and saturates to int.MaxValue on ARM64. On an Apple Silicon dev machine the test passes even without the clamp. A code comment next to the clamp says so, to stop a future reader "simplifying" the range check away. CI runs x64, where it is a real guard.

Deliberately out of scope

• IDistributedCacheService.MinimumTtl — adds a member to a published interface in BBT.Aether.Core and touches all three providers; its own change, its own design.
• Cross-provider alignment of already-expired writes — the three providers still disagree (Dapr skips, Redis passes a negative TimeSpan to StringSetAsync, .NET Core writes an immediately-expired entry).
• A Redis/Dapr parity integration test — needs a live Redis plus a Dapr sidecar; CI has neither today.

Tests

9 new unit tests in DaprDistributedCacheServiceTests (the class had none). The fixture substitutes DaprClient and captures the metadata dictionary that actually reaches SaveStateAsync, rather than asserting a mock was called.

Requested	Expected
AbsoluteExpiration = now + 500 ms	ttlInSeconds = "1"
AbsoluteExpiration = now + 1.4 s	"2"
AbsoluteExpiration = now + 60 s	"60"
AbsoluteExpiration = now - 5 s	no write
SlidingExpiration = 500 ms	"1"
SlidingExpiration = TimeSpan.Zero	no write
AbsoluteExpiration = DateTimeOffset.MaxValue	"2147483647"
both absolute and sliding set	absolute wins
no options	write happens, no ttlInSeconds key

dotnet build framework/BBT.Aether.slnx → 0 errors, no new warnings.
dotnet test framework/test/BBT.Aether.Infrastructure.Tests → 223/223 passing.

Also in this PR

• framework/docs/distributed-cache/README.md: a per-provider TTL granularity section, the GetOrSetAsync caveat, the upgrade note, the fact that cache.ttl_seconds means "as stored" on Dapr but "as requested, truncated" on Redis, and that sliding expiration does not actually slide on Dapr (RefreshAsync is a no-op). Two examples used AbsoluteExpirationRelativeToNow, a property DistributedCacheEntryOptions does not have — a reader copying either got a compile error. Both fixed.
• framework/docs/superpowers/specs/ and plans/: the design record and implementation plan for this change.

🤖 Generated with Claude Code

Summary by Sourcery

Ensure Dapr cache expiration requests are represented safely at the provider's one-second granularity instead of silently producing permanent or invalid entries.

Bug Fixes:

• Prevent Dapr cache entries with sub-second or fractional lifetimes from becoming permanent or expiring earlier than requested by rounding TTLs up to whole seconds.
• Skip Dapr writes for already-expired absolute expirations and non-positive sliding expirations.
• Clamp excessively large Dapr TTLs to the supported integer range and format TTL metadata invariantly.

Enhancements:

• Unify absolute and sliding expiration handling while preserving absolute-expiration precedence.
• Document provider-specific TTL granularity, Dapr expiration behavior, stale-entry upgrade considerations, and GetOrSetAsync limitations.

Documentation:

• Correct distributed-cache expiration examples and add guidance for Dapr TTL rounding, skipped writes, non-sliding refresh behavior, telemetry differences, and upgrade handling.
• Add design and implementation records for the Dapr cache TTL changes.

Tests:

• Add unit coverage for Dapr TTL rounding, expiration precedence, skipped writes, absent metadata, and large-TTL clamping.

[sourcery-ai]

Reviewer's Guide

The PR fixes Dapr cache expiration by converting absolute and sliding lifetimes through one shared, upward-rounding and overflow-safe path, skipping writes whose requested lifetime has elapsed, and adding targeted provider-level tests plus documentation and design records for the resulting behavior.

Sequence diagram for Dapr cache writes with safe TTL handling

sequenceDiagram
    participant Caller
    participant DaprCache as DaprDistributedCacheService
    participant DaprStore as Dapr state store

    Caller->>DaprCache: SetAsync(key, value, options)
    DaprCache->>DaprCache: Compute requestedTtl
    alt requestedTtl <= TimeSpan.Zero
        DaprCache->>DaprCache: SetTag(cache.skipped, true)
        DaprCache-->>Caller: Return without writing
    else positive requestedTtl
        DaprCache->>DaprCache: ToStoreTtlSeconds(ttl)
        DaprCache->>DaprCache: Round up and clamp to int.MaxValue
        DaprCache->>DaprStore: SaveStateAsync(key, value, ttlInSeconds)
        DaprStore-->>DaprCache: Save completed
        DaprCache-->>Caller: Return
    else no expiration options
        DaprCache->>DaprStore: SaveStateAsync(key, value)
        DaprStore-->>DaprCache: Save completed
        DaprCache-->>Caller: Return
    end

Loading

Flow diagram for Dapr TTL conversion

flowchart TD
    A[Requested cache options] --> B{AbsoluteExpiration set?}
    B -->|Yes| C[absolute - UtcNow]
    B -->|No| D{SlidingExpiration set?}
    D -->|Yes| E[Use sliding duration]
    D -->|No| F[No TTL metadata]
    C --> G{requestedTtl <= zero?}
    E --> G
    G -->|Yes| H[Skip SaveStateAsync]
    G -->|No| I[ToStoreTtlSeconds]
    I --> J[Ceiling to whole seconds]
    J --> K[Minimum 1 second]
    K --> L[Clamp to int.MaxValue]
    L --> M[Write ttlInSeconds with invariant formatting]
    F --> N[SaveStateAsync without TTL]
    M --> O[SaveStateAsync]

Loading

File-Level Changes

Change	Details	Files
Unified Dapr TTL derivation and made stored expiration safe for the provider’s one-second granularity.	Replaced divergent absolute and sliding branches with a shared precedence-preserving computation. Rounds positive TTLs up to whole seconds, including sub-second values. Skips writes for already-expired or non-positive lifetimes, while marking the diagnostic activity when available. Clamps oversized TTLs to int.MaxValue and formats metadata with invariant culture.	framework/src/BBT.Aether.Infrastructure/BBT/Aether/DistributedCache/Dapr/DaprDistributedCacheService.cs
Added regression coverage around the metadata sent to Dapr.	Captures SaveStateAsync metadata with a substituted DaprClient. Verifies sub-second and fractional rounding, exact values, expiration skip behavior, precedence, no-options behavior, and overflow clamping.	framework/test/BBT.Aether.Infrastructure.Tests/BBT/Aether/DistributedCache/Dapr/DaprDistributedCacheServiceTests.cs
Documented provider-specific expiration behavior and operational upgrade implications.	Corrected unsupported AbsoluteExpirationRelativeToNow examples. Explains Dapr’s one-second floor, skipped writes, non-sliding Dapr behavior, and provider-specific telemetry semantics. Notes the GetOrSetAsync slow-fetch caveat and that existing permanent entries require flushing or key versioning.	framework/docs/distributed-cache/README.md
Recorded the design rationale and implementation plan for the fix.	Defines scope, compatibility impact, accepted skipped-write behavior, test strategy, and deliberately deferred follow-up work.	framework/docs/superpowers/specs/2026-09-11-dapr-cache-ttl-granularity-design.md framework/docs/superpowers/plans/2026-09-11-dapr-cache-ttl-granularity.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 836cc2cf-4102-4435-b8be-540b3924f231

---

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

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="framework/docs/distributed-cache/README.md" line_range="117-120" />
<code_context>
+non-positive `SlidingExpiration`), the Dapr provider skips the write rather than storing an entry
+that would never expire. Any previous value under that key is left in place.
+
+An `AbsoluteExpiration` computed before a slow fetch can elapse before the write happens, and the
+write is then skipped — this is exactly what `GetOrSetAsync` does, since it builds `options` before
+awaiting `fetchFunc` and only calls `SetAsync` afterwards. Prefer `SlidingExpiration` for short
+lifetimes: it is measured at write time rather than against a timestamp fixed earlier, so a slow
+fetch cannot make it negative.
+
</code_context>
<issue_to_address>
**nitpick:** The documentation states that `GetOrSetAsync` builds `options` before awaiting `fetchFunc`, but `DistributedCacheBase.GetOrSetAsync` assigns default options only after the fetch completes. This makes the documented explanation inaccurate for calls that omit options, where the default sliding expiration is not created until after the fetch.

**Triggers:** When a reader relies on the documentation to reason about the timing of default expiration options.

**Suggested fix:** Explain that caller-supplied absolute options are created before the `GetOrSetAsync` call, while the method's default sliding options are assigned after `fetchFunc` completes.

```suggestion
A caller-supplied `AbsoluteExpiration` computed before a slow fetch can elapse before the write happens, and the
write is then skipped. Caller-supplied absolute options are created before the `GetOrSetAsync` call, while the method's
default sliding options are assigned only after `fetchFunc` completes. Prefer `SlidingExpiration` for short
lifetimes: it is measured at write time rather than against a timestamp fixed earlier, so a slow
```
</issue_to_address>

Sourcery assessment

Needs a human reviewer. The change alters how cache entries are persisted in Dapr: a miscomputed TTL could keep stale values briefly or skip a write and leave an older value in place. Reverting stops the new behavior, and affected cache entries are bounded and repairable by expiration or clearing the cache.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[sourcery-ai]

nitpick: The documentation states that GetOrSetAsync builds options before awaiting fetchFunc, but DistributedCacheBase.GetOrSetAsync assigns default options only after the fetch completes. This makes the documented explanation inaccurate for calls that omit options, where the default sliding expiration is not created until after the fetch.

Triggers: When a reader relies on the documentation to reason about the timing of default expiration options.

Suggested fix: Explain that caller-supplied absolute options are created before the GetOrSetAsync call, while the method's default sliding options are assigned after fetchFunc completes.

Suggested change

	An `AbsoluteExpiration` computed before a slow fetch can elapse before the write happens, and the
	write is then skipped — this is exactly what `GetOrSetAsync` does, since it builds `options` before
	awaiting `fetchFunc` and only calls `SetAsync` afterwards. Prefer `SlidingExpiration` for short
	lifetimes: it is measured at write time rather than against a timestamp fixed earlier, so a slow
	A caller-supplied `AbsoluteExpiration` computed before a slow fetch can elapse before the write happens, and the
	write is then skipped. Caller-supplied absolute options are created before the `GetOrSetAsync` call, while the method's
	default sliding options are assigned only after `fetchFunc` completes. Prefer `SlidingExpiration` for short
	lifetimes: it is measured at write time rather than against a timestamp fixed earlier, so a slow

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 14 complexity · 0 duplication

Metric	Results
Complexity	14
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[sonarqubecloud]

Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud