## Context `internal/format/npm` declares the npm-remote observability surface S15 specifies: four `gitlab_artifact_registry_npm_remote_*` metric families (`remote_metrics.go`) and the `npm_remote_proxy` wide event (`remote_observe.go`). Parts of that surface are declared, pinned by tests, and catalogued, but have no production emitter, because the facts they need are not carried by the `internal/remote` seams the npm routes compose. This issue tracks closing what is left. The gaps are filed together because they are one shape: an npm route knows what it wants to record and the seam it went through cannot tell it. ### Where the surface lands S15 Step 15 ships the surface as a three-part stack, and which gaps are reachable at all depends on how much of it has merged: | Part | MR | Carries | | --- | --- | --- | | 1 | merged as `a5ef4d2c` | the four metric families | | 2 | !1879, into `main` | the `npm_remote_proxy` wide event | | 3 | !1880, stacked on !1879 | the emitters on the three read routes | While !1879 and !1880 are open, `remote_observe.go` and `beginRemoteProxyRecord` are not on `main` at all, so no route emits a record and the code gaps 1 and 2 describe is reachable only on those branches. Once both merge, what remains is what each section below names. ## The gaps ### 1. Only the tarball route records a cache verdict Once !1880 merges, `beginRemoteProxyRecord` has one caller per read route (`remote_packument.go`, `remote_disttags.go`, `remote_tarball.go`), so `npm_remote_proxy` records emit for `operation="packument"` and `operation="dist_tags"` as well as `"tarball"`. The wide event is not among the gaps for the metadata routes. The cache verdict does not follow the record. `recordRemoteProxyCache` is called only from `remote_tarball.go`, because the packument and dist-tags routes serve through `remote.Standalone`, whose `ServeResult` carries no value of the npm cache-event domain. `remote.ServeSource` is four values wide (`ServeError`, `ServeFromCache`, `ServeFromCacheDegraded`, `ServeFromUpstream`) and two of them collapse a pair this vocabulary separates: `ServeFromCache` is a fresh hit or a stale hit that revalidated to a `304`, which is `hit_fresh` and `revalidated`; `ServeFromUpstream` is a miss or a stale hit whose conditional fetch returned a `200`, which is `miss` and `hit_stale`. Those routes record no verdict rather than emit one they cannot substantiate. `ServeFromCacheDegraded` is the one source that pins a value on its own, the cache-fallback `hit_stale`. Counting only it is declined deliberately: `npm_remote_cache_events_total`'s four values are documented as summing to a path's read count, so a series firing on the fallback serves alone reads as a hit ratio computed over every read. What has no production emitter once the stack has merged: - `npm_remote_cache_events_total{npm_cache_path="packument"}` and `{npm_cache_path="dist_tags"}` - `npm_remote_upstream_responses_total{npm_operation="packument"}`, because classifying an upstream answer reads a `remote.FetchResult` and only the tarball route receives one - `npm_remote_cache_fill_bytes{npm_cache_artifact="packument"}`, because the fill is `remote.Standalone`'s and it reports neither the commit nor its size to the caller `npm_remote_packument_transform_duration_seconds` is the one family fed from every route it is meant to cover, through `timedRemoteTransform` at `remote_packument.go`'s `serveVariant` and `remote_disttags.go`'s `serve`. Closing this needs `remote.ServeResult` widened to report the cache verdict the serve reached. That is an `internal/remote` change, which the Maven and OCI remote paths also compose, so it is scoped outside a format MR. ### 2. `coalesced` is not carried on the metadata routes `remoteProxyEvent.coalesced` is rendered on every `npm_remote_proxy` record. The seam signal this gap originally asked for already exists on `main`: `remote.FetchResult.Coalesced` (`internal/remote/operations.go`) reports whether a result was served to a `remote.SingleFlight` follower, and `remote.SingleFlight` sets it on the follower path. Once !1880 merges, `remote_tarball.go` passes it to `recordRemoteProxyCoalesced`, so a `tarball` record's `coalesced` is the flight outcome and means what it says. What remains is narrower than a new signal on `remote.FetchResult`. The metadata routes resolve through `remote.Standalone.Serve`, whose `ServeResult` is not a report of a flight, so they call `recordRemoteProxyCoalesced` nowhere and their `coalesced` is `false` whatever happened. On a `packument` or `dist_tags` record, read `false` as "not reported" rather than "did not coalesce". Closing this needs the flight outcome reachable from the `Standalone` serve path. ### 3. Nothing npm-side observes a probe `remoteUpstreamProbe` and `remoteProxyProbe` are declared, pinned in the closed sets, and unreachable, so both `npm_remote_upstream_responses_total{npm_operation="probe"}` and the `npm_remote_proxy` record for `operation="probe"` are silent. The probe is `remote.HealthMonitor.Probe`, which S13 owns; `docs/specs/S15-npm-remote.md` says in its Health monitoring section that S15 contributes nothing to it, while its Observability section puts `probe` on both the npm `npm_operation` domain and the wide event's operation list. That is a contradiction inside the spec, and it needs the spec author rather than an implementation choice. Either the probe emits npm-scoped signals, in which case S15 does contribute to it, or `probe` comes off the two npm domains. Until it is settled the value stays declared, because the spec lists it and removing it would put the code out of step with the document. Nothing about this gap depends on the stack above: it is open on `main` and on both branches alike. ## Why the surface shipped this way The declared-but-unemitted values are pinned in `closedSetValues` (`internal/metrics/cardinality.go`) and covered by positive-hit tests, so the vocabulary is fixed and the audit passes. Emitting a wrong verdict would be worse than emitting none: a `hit_fresh` that was really a revalidation makes the hit ratio a fiction, and the four values are documented as summing to the read count. ## Acceptance - `remote.ServeResult` carries the cache verdict, and the packument and dist-tags routes emit their cache events, upstream responses, and packument cache fills. - The flight outcome is reachable from the `remote.Standalone` serve path, and `coalesced` carries it on the packument and dist-tags records as well as the tarball ones. - The `probe` question is settled with the spec author, and the code and spec agree afterwards. - `docs/dev/observability.md` and `internal/format/npm/metrics.md` drop the "not yet emitted" qualifiers as each gap closes. `metrics.md`'s `### Values with no production emitter` section is the per-series list to keep in step. ## Source Raised in pre-push validation of the S15 Step 15 observability work, which lands the surface with these gaps documented at every site that states them.