[lan17]

Problem

A confirmed shadow mismatch reports how old the cache frame is, but that does not identify when the source changed. Applications that already have a meaningful source timestamp need a way to report its age. Requested in a maintainer session; no issue exists.

Change

Design proposal only; implementation has not started. This is Portable behavior + Public API work. The record is design/2026-10-25-shadow-source-update-age.md, with all decisions Open.

Propose one optional synchronous timestamp extractor alongside existing boolean comparators in TypeScript, Go, Rust and Python. On a terminal confirmed mismatch, emit (verdictTimeMs - sourceUpdatedAtMs) / 1000 as dialcache.shadow.source_update_age (Datadog) and dialcache_shadow_source_update_age_histogram (Prometheus). Missing, invalid, future or failing extraction omits the new sample and preserves existing diagnostics. The metric describes age since the reported update; it cannot generally establish the first missed change.

This extends the existing operation, diagnostics and formal model. It adds no storage, wire changes, extra I/O or rollout setting. It is independent of #242; if that PR lands first, reconcile the overlapping diagnostic paths on rebase.

Open questions

1. D1 — API: Accept one optional timestamp extractor with existing boolean comparators unchanged, including the Go/Rust source compatibility costs below?
2. D2 — Semantics: Accept age since the reported source update in seconds, only after terminal confirmed mismatch, with unavailable/invalid timestamps omitted and diagnostic failures isolated?
3. D3 — Scope: Accept all four ports and built-in adapters, extending existing shadow conformance and documentation in this PR?

Recommended answer: yes to all three. The record remains Proposed until the maintainer confirms each decision; the repository design gate requires acceptance before implementation.

Validation

Head: 742e9bc9badfca1e27f83932dea97ec515604a9b

• git diff --check origin/main...HEAD at 742e9bc: passed.
• Design-record checks before 4045326: template sections, exactly three Open decisions, referenced source paths and public links, public-only context, and design-only scope passed. 742e9bc adds only this PR's backlink; that diff was checked separately.
• Read-only review checked callback placement, metric semantics and public API compatibility across ports.
• PR title run 40237304898 at 742e9bc: passed.
• CI run 40237306792 at 742e9bc: pending.
• Documentation run 40237306760 at 742e9bc: pending.
• Formal smoke run 40237306763 at 742e9bc: queued.

Not run locally: native/package tests, documentation build, integration/wire tests. Replay, Mutations and Full have not been dispatched. This commit only proposes the design; implementation and its required validation lanes follow acceptance. The PR stays draft.

Follow-ups

None outside this PR. Implementation is gated by D1–D3 above.

BREAKING CHANGE: The proposed implementation adds an optional field to Rust Operation<T> and Go Operation[T]; Rust exhaustive struct literals and Go unkeyed literals need updates. New Rust Event and MetricKind variants also require downstream exhaustive matches to add an arm. Constructors/builders and keyed Go literals remain usable. This draft currently contains only the design record.

— Levicus 🤖

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.73%. Comparing base (b4e4fba) to head (742e9bc).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #246   +/-   ##
=======================================
  Coverage   93.73%   93.73%           
=======================================
  Files          78       78           
  Lines       11357    11357           
  Branches      656      656           
=======================================
  Hits        10645    10645           
  Misses        642      642           
  Partials       70       70           

Flag	Coverage Δ
go	91.12% <ø> (ø)
python	92.08% <ø> (ø)
rust	94.29% <ø> (ø)
typescript	96.56% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.