Unify the temporal kv GetLatest interface — eliminate accreted duck-typed metered-getter variants

[mh0lt]

Problem

The temporal kv read path has accreted several near-duplicate ways to do the same GetLatest, because each incremental need is added as an optional duck-typed interface + type-switch rather than by changing the kv interface itself. Changing the interface ripples to a large number of call sites, so it's repeatedly deferred as "too big for this PR" — and the variants accumulate.

Current state (db/state/execctx/domain_shared.go, getLatestMetered):

• plain tx.GetLatest(domain, k) — no metering, no txN
• MeteredGetter.MeteredGetLatest(…, metrics, start) → (v, step, ok, err) — adds read metering + maxStep
• MeteredGetterWithTxN.MeteredGetLatestWithTxN(…) → (v, step, txN, ok, err) — adds the read's txN (needed to tag BranchCache entries with their unwind watermark)

The SD getter type-switches over tx.AggTx() to pick the richest available variant. MeteredGetterWithTxN differs from MeteredGetter only by the extra txN return value.

Proposal

Make the temporal GetLatest API consistent: a single GetLatest that returns the txN and is metered, with metrics threaded via ctx (so the signature doesn't grow a metrics parameter). Remove the MeteredGetter / MeteredGetterWithTxN duck-typed interfaces and the type-switches that select between them.

Related — another take on the same problem

The lock-free, channel-fed KV-read metrics collector (#21663) threads metrics through via ctx rather than an interface parameter. That is effectively another take on this same underlying issue (adding read-path capabilities without an interface-param explosion). The unified GetLatest should adopt that ctx-carried pattern instead of passing metrics *changeset.DomainMetrics explicitly.

Scope / why it keeps getting deferred

Changing the kv temporal interface touches many call sites, so it gets punted from feature PRs. This needs its own dedicated PR.

Surfaced in review of #21380.

[mh0lt]

Why this interface change matters beyond tidiness — it enables a (txNum, epoch) DB unwind model

Returning the value's txNum (instead of the file step) and letting the tx decide whether to surface a value (via ctx-carried read state) isn't just cosmetic — it's the seam that lets the DB layer later adopt the same (txNum, epoch) model the state/branch/code caches now use, without changing this interface again.

Future model (separate, follow-on step — not this PR):

• DB reads return (txNum, epoch) instead of step.
• The tx decides whether to return a value based on its current unwind (floor, epoch) — a value from a superseded epoch above the floor is simply not surfaced.
• Unwind becomes an epoch bump + floor lower — no bulk DB truncation/rewrite of the domain tables.

Trade-off:

• Cost: some additional storage per unwind (old-epoch values linger until pruned).
• Benefit: almost certainly cheaper than maintaining complete changesets for unwind — and it avoids having to write them at all.

This PR only does the interface change (add context.Context, return txNum not step, collapse the duck-typed metered variants). It deliberately keeps today's unwind mechanism; it just stops the interface from being the thing that blocks the DB-side model later.

[mh0lt]

Stating the core design principle explicitly (and why it matters more now)

Taking an explicit position — recognising it may be contested on the team:

Leaking step into the application layer is a problem. step is a db-layer concept (the collation/file granularity, step = txNum / stepSize). The application layer — execution, RPC, staged sync, SharedDomains and above — is txNum-based; it only ever wants "the value as of this txNum." Surfacing step to it means application code has to reason about, and convert, a foreign unit it has no control over and no real use for, which confuses the code and couples the application to the freezing scheme.

This is materially worse now that stepSize is variable. Step↔txNum is no longer a constant shift: every conversion needs the current stepSize, so each one in application code becomes a function call to fetch it plus a data dependency on it. Keeping the application in txNum removes that call and that dependency outright — the single step↔txNum conversion happens inside the aggregator/domain, where stepSize already lives.

That is the motivation for this unification, beyond removing the duck-typed variants:

• TemporalGetter.GetLatest(ctx, name, k) (v, txNum, err) — txNum in, txNum out.
• step never appears above the aggregator/domain.
• the unwind bound + metrics ride in ctx (changeset.ReadContext), converted to a step only inside the domain.

Recorded as a codebase principle in db/agents.md ("Layering principle: txNum is the application unit; step is a db implementation detail").

[VBulikov]

yperbasis added Imp2 as Importance