Skip to content

refactor(provideroptimizer): score latency and sync lag through one normalizer (MAG-4244) - #607

Merged
AnnaR-prog merged 2 commits into
mainfrom
refactor/MAG-4244-normalize-inverted
Nov 3, 2026
Merged

AnnaR-prog merged 2 commits into
mainfrom
refactor/MAG-4244-normalize-inverted

Conversation

@avitenzer

Copy link
Copy Markdown
Contributor

Jira ticket: MAG-4244

The second of MAG-4244's section 7 duplicates: normalizeLatency and normalizeSync in provider selection. Every score is bit-identical to main's, and every branch allocates exactly what main does.

What was duplicated

The two functions were the same 90 lines twice: the adaptive P10-P90 scale with its bounds validation and clamping, then the fixed-maximum fallback. They differ in three inputs and in the words their log lines use.

The change

The algorithm lives once, in normalizeInverted(value, adaptive, bounds, n). The per-dimension part is an invertedNormalization value:

latency sync lag
falls back to score.WorstLatencyScore, 30 s score.WorstSyncScore, 1200 s
log tag [LatencyNormalization] [SyncNormalization]
attribute keys raw_latency, clamped_latency, max_latency raw_sync_lag, clamped_sync_lag, max_sync_lag

Each normalize* method is now a one-line call that keeps its own doc, including the per-dimension range-utilisation figures.

Why the log text is held as whole literals

This runs once per provider per selection, and Go evaluates log arguments even with trace logging off. So building a key like "raw_" + name per call, or boxing the worst value into the log's interface{} per call, would allocate on every selection. That is the cost MAG-4244 exists to remove, so this change must not add any.

The log text is therefore whole literals, and the worst value is boxed into its attribute once, at package initialisation. Measured rather than argued: boxing it per call takes the fixed branch from 5 allocations to 6.

Proof that nothing changed

The existing tests only ever reached the fixed branch. They build the selector from DefaultUpstreamSelectorConfig(), which leaves adaptive off, and compare within 0.01. Nothing exercised the adaptive range, its bounds validation or its clamping, which is the larger half of what this merges.

normalize_inverted_test.go pins every branch for both dimensions with exact equality, written and passing against main before the merge:

  • the fixed scale, probed at half each dimension's own worst value, which is exactly 0.5 only with the right constant;
  • adaptive requiring both the flag and the getter;
  • the clamped P10-P90 range;
  • ten kinds of unusable bounds (NaN, infinities, zero, negative, equal, inverted) falling back to the fixed scale.

A differential check against a frozen copy of main's functions, run as evidence and not committed:

Check Result
scores compared: 2 dimensions × 18 bounds configurations × values incl. NaN, ±Inf, float64 extremes and a dense sweep 128,088, all bit-identical
allocations per call, fixed branch main 5, new 5
allocations per call, perfect score main 3, new 3
allocations per call, adaptive branch main 9, new 9
allocations per call, invalid bounds main 68, new 68

Mutation testing. Of twelve mutants of the new code, the committed tests kill all nine that can change a score, including each dimension scaled by the other's worst value. The other three survive and must: dropping either input clamp, or scoring zero on the fixed scale rather than as perfect, gives a bit-identical score on all 128,088 cases. Each is redundant with a later step, the defensive [0, 1] clamp or the formula that is exactly 1 at zero, and changes only which trace line is logged.

Two findings, deliberately left for a follow-up

This PR is a pure merge, so it changes neither. Both are in MAG-4244's spirit.

  1. The trace logs allocate with tracing off. The table above is main's cost too: 3 to 9 allocations per provider per selection, spent building log arguments that a disabled trace level throws away. Guarding the three trace calls with utils.IsDebugEnabled() should remove most of them; this file already guards one log that way, and trace sits below debug, so debug off implies trace off.
  2. Two guards in the algorithm only label trace lines. The input clamps duplicate the output clamp for the score, and the zero short-circuit duplicates the formula at zero, which is what the three surviving mutants show. They are harmless, and they feed the was_clamped_* and "Perfect" log fields, so I left them.

Verification

From a detached worktree of the commit.

go build -buildvcs=false ./...                          clean
go vet ./protocol/provideroptimizer/                    clean
go test -race ./protocol/provideroptimizer/             ok
golangci-lint run ./protocol/provideroptimizer/...  (fresh cache)   0 issues

🤖 Generated with Claude Code

…ormalizer (MAG-4244)

normalizeLatency and normalizeSync were the same 90 lines twice: the
adaptive P10-P90 scale with its bounds validation and clamping, then the
fixed-maximum fallback. They differ in three inputs and in the words
their log lines use. The audit's dupl run flagged them (MAG-4244
section 7).

The algorithm now lives once, in normalizeInverted(value, adaptive,
bounds, n). The per-dimension part is an invertedNormalization value,
latencyNormalization and syncNormalization: the worst value each falls
back to (score.WorstLatencyScore, score.WorstSyncScore) and its log text.
Each normalize* method is a one-line call that keeps its own doc,
including the per-dimension range-utilisation figures. Every log line,
attribute key and score is unchanged.

The log text is held as whole literals, not assembled from a dimension
name, and the worst value is boxed into its log attribute once, at
package initialisation. This runs once per provider per selection, and Go
evaluates log arguments even with trace logging off, so assembling a key
or boxing the worst value per call would allocate on every selection.
Measured: boxing it per call takes the fixed branch from 5 allocations to
6. As written, every branch allocates exactly what main does.

The existing tests only ever reached the fixed branch: they build the
selector from DefaultUpstreamSelectorConfig, which leaves adaptive off,
and compare within 0.01. Nothing exercised the adaptive range, its bounds
validation or its clamping, which is the larger half of what this merges.
normalize_inverted_test.go pins every branch for both dimensions with
exact equality, before the merge: the fixed scale at half each
dimension's OWN worst value (exactly 0.5 only with the right constant);
adaptive requiring both the flag and the getter; the clamped P10-P90
range; and ten kinds of unusable bounds falling back to the fixed scale.

Evidence, not committed (the scratch files held a frozen copy of main's
functions): over 128,088 combinations of dimension, 18 bounds
configurations and values including NaN, both infinities and the float64
extremes, every score is bit-identical to main's. Allocations per call
are identical on all four branches.

Of twelve mutants of the new code, the committed tests kill all nine that
can change a score. The other three survive and must: dropping either
input clamp, or treating zero as a fixed-scale value rather than a
perfect score, gives a bit-identical score on all 128,088 cases. Each is
redundant with a later step (the defensive [0, 1] clamp; the formula,
which is exactly 1 at zero) and changes only which trace line is logged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Took 2 minutes
@avitenzer
avitenzer requested a review from a team as a code owner October 29, 2026 11:57

@AnnaR-prog AnnaR-prog left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 31a1a2f. I tested it merged with current main d765031.

The change is correct.

  • I ran my own differential test against a copy of main's normalizeLatency and normalizeSync, comparing with math.Float64bits: 2,521,134 scores, 0 differences. The inputs included 0, -0, NaN, ±Inf, ±MaxFloat64, subnormals and the values next to 30 and 1200, across adaptive off, on without a getter, a getter while off, and 18 bound pairs (valid, equal, inverted, zero, negative, NaN, ±Inf).
  • testing.AllocsPerRun gives the same counts on main and here for the fixed, perfect, adaptive and invalid-bounds branches (5/3/9/68 per call), as the description says.
  • The log messages and keys are the same literals per dimension as before, and the shared maxAttr is read-only.
  • The new tests also pass against main's upstream_selector.go. go test ./protocol/provideroptimizer/... passes on the merged tree, and lint reports nothing new.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

@AnnaR-prog AnnaR-prog left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at df398b0: main b85bf5c plus this PR. go build ./... and the full protocol/provideroptimizer suite pass on this exact tree.

@AnnaR-prog
AnnaR-prog merged commit 2b9df42 into main Nov 3, 2026
@AnnaR-prog
AnnaR-prog deleted the refactor/MAG-4244-normalize-inverted branch November 3, 2026 15:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants