[mrgrain]

The npm replica's _changes feed occasionally makes change entries visible behind positions the follower has already read past (npm calls this normal feed behavior), and the registry occasionally serves packuments older than the revision the feed announced. Both cases silently dropped package versions until the affected package published again. In a recent incident, five consecutive construct-hub-probe versions were missed over about 15 hours.

The follower therefore no longer tracks a single high-water mark:

• It writes a receipt for every change entry it receives, and every run re-scans a trailing window of the feed, processing any entry it has no receipt for. Late-inserted entries are picked up on the next run. Rolling checkpoints map times to feed positions and derive the window's starting point. Interim checkpoints are recorded as a scan progresses, so interrupted scans resume where they stopped; a daily deep scan covers the full state retention, so insertion delays beyond the regular window are still observed.
• When the registry serves a packument behind the announced revision (a laggy packument), the versions it did serve are processed immediately. The follower records the announced revision and re-checks it every run until it appears or ages out after 24 hours. A give-up is logged with the package name and emits a metric that drives a low-severity alarm, since at that point a version announced by the feed genuinely never materialized.
• All state lives in one scannable, newline-delimited S3 object (receipts, checkpoints, laggy packuments; roughly 3 MB raw / a few hundred KB gzipped at 24h retention).

Observability: LateChangeCount and LateChangeLag measure the feed's late insertions (the lag data is what tunes the scan window), and LaggyPackuments / LaggyPackumentsRecovered / LaggyPackumentGiveUps track the registry lagging the feed. They feed a new Feed Reliability dashboard widget and two low-severity alarms, both with runbook entries. The PR also adds docs/npm-sync-protocol.md, documenting with citations what the feed does and does not guarantee, and updates the backfill instructions in the application overview for the new state model.

Replaces #1933.

Internal reference: V2376798198

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None