Skip to content

feat: publish the fidelity tiers against both denominators they are read against - #166

Merged
skyoo2003 merged 1 commit into
mainfrom
feat/phase-5-fidelity-offset
Sep 13, 2026
Merged

skyoo2003 merged 1 commit into
mainfrom
feat/phase-5-fidelity-offset

Conversation

@skyoo2003

Copy link
Copy Markdown
Owner

Summary

Registering the 226 services the demand study found nobody building enlarged a denominator and nothing else, but the coverage page reported it as depth — hand-verified read 23.6% where it had read 36.2% without one operation becoming less faithful. The per-operation table now publishes both denominators, and every page that restates the share is gated against the binary.

Related Issue

Refs #166

Changes

Published figures

  • docs/coverage.md splits the per-operation table into Serving target (the depth promise: every registered service except the 226) and All registered (the long tail added back, with the 6,794 operations that exist so an SDK call cannot leave for a billable account).
  • Both hand-verified shares are published — 36.2% and 23.6% — with the denominator named where each is read. docs/fidelity-manifest.md gains the same note.

Derivation

  • The serving-target set is derived from docs/demand.md (registry minus exactly the rows with support < 2) rather than pinned, so 205 does not gain a fourth home.
  • The share is carried as integer tenths of a percent, so the gate and the updater compare the digits the page shows rather than two floats agreeing to a precision no reader can see. Rounded half up.

Gates (five → nine)

Test Gates
TestPublishedOperationTiersMatchTheManifest the operation tiers, in both denominators
TestPublishedFidelityShareMatchesTheManifest the hand-verified share of each
TestPublishedLongTailProseMatchesTheManifest the long-tail figures the prose states in words
TestFidelityManifestQuotesTheSameShare that the manifest page states the same share
TestPublishedTargetTableMatchesTheBinary (extended) that the table's 205 is the denominator the tier table divides by

Weekly sync

  • figureEdit carries a render function instead of a separated bool — the page shows three renderings now (plain, thousands-separated, one decimal place) and the cell decides which.
  • The updater owns six new spans across two pages, including docs/fidelity-manifest.md as a fourth target, and is idempotent on the committed pages.

Files Changed

File Type
cmd/devcloud/coverage_test.go Modified — two new gates, the denominator assertion, shareTenths, demandSupport
cmd/devcloud/figures_update_test.go Modified — render functions, formatTenths, six new edits, three new round-trip cases
docs/coverage.md Modified — two-denominator table, the paragraph explaining it, gate list
docs/fidelity-manifest.md Modified — a tier share needs its denominator named
changes/unreleased/Changed-20260913-184045.yaml Added

Test Plan

Every new gate was proved to bite before it was trusted — the figure was mangled in the tracked page, the gate was run, and the page restored:

Guarantee RED evidence GREEN
The published 205 is the tier table's actual denominator target row → 206: promises depth on 206 … counted over 205 restored, PASS
The prose 6,794 matches the columns' difference → 6,795: states 6795 … columns differ by 6794 restored, PASS
fidelity-manifest.md agrees with coverage.md → 36.3%: states 36.3% … publishes 36.2% restored, PASS
The updater owns the six new spans round-trip cases 8–10 failed before the figureEdits existed PASS
shareTenths rounds half up, not truncates TestShareRendersTheFigureThePageShows — 1/8 → 12.5, 0/0 → 0.0 PASS
go test ./...                     119 packages ok
go vet ./cmd/devcloud/            clean
golangci-lint run ./cmd/devcloud/ 0 issues
gofmt -l cmd/devcloud/            clean
DEVCLOUD_UPDATE_DOCS=1 go test -run TestUpdatePublishedFigures
                                  PASS, working tree unchanged (idempotent)

Checklist

  • Self-reviewed the code
  • Added/updated tests
  • Lint/format passes (golangci-lint run)
  • Updated documentation (if applicable)
  • Added a Changie changelog fragment for user-facing changes

…ead against

Registering the 226 services the demand study found nobody building enlarged a
denominator and nothing else. The page reported it as depth: hand-verified read
23.6% where it had read 36.2%, without one operation becoming less faithful, and
the only way to "offset" that number is roughly 2,450 hand-written operations
nobody asked for.

The per-operation table now publishes two columns. The serving target is the
depth promise — every registered service except those 226 — and all registered
adds the long tail back, with the 6,794 operations that exist so an SDK call
cannot leave for a billable account. Both shares are stated, both are gated, and
the denominator is named wherever the share is read.

The serving-target set is derived from docs/demand.md rather than pinned: the
registry minus exactly the rows with support < 2. A fourth place for 205 to live
is the defect this page exists to prevent. The share is carried as integer tenths
of a percent so the gate and the updater compare the digits the page shows, not
two floats that agree to a precision no reader can see.

Review follow-ups, each with a failing test first:

  - The tier table's serving-target column was counted over a set whose size
    nothing compared to the 205 the target table publishes. AWS shipping a
    service the study never sampled grows that set to 206 — deliberately — while
    the page goes on promising depth on 205 and every gate stays green.
  - The paragraph under that table restates the same arithmetic in words, and
    prose is where a number goes to stop being maintained. Both figures are now
    gated and rewritten by the weekly sync; the second statement of 6,794 was
    reworded so exactly one span owns it.
  - docs/fidelity-manifest.md restates the share and nothing read it back, which
    is the shape of the drift that left "148 registered / 117 serving" on both
    front pages for three milestones. It is the sync's fourth page now.
  - Both readers of docs/demand.md folded an unparseable support cell into their
    `continue`, which read as though a malformed row were routine. demandRow
    requires digits, so that branch was unreachable and the real hazard is a row
    that goes missing entirely — which the denominator gate above now catches.
    One parse, used twice, so the two cannot split the table differently.
@github-actions github-actions Bot added documentation Improvements or additions to documentation tests Test code and test infrastructure labels Sep 13, 2026
@skyoo2003
skyoo2003 merged commit 0b554c5 into main Sep 13, 2026
10 checks passed
@skyoo2003
skyoo2003 deleted the feat/phase-5-fidelity-offset branch September 13, 2026 12:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation tests Test code and test infrastructure

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant