@superblocksteam/telemetry 2.0.129 → 2.0.130-next.0

package/README.md

@@ -151,17 +151,26 @@ Telemetry attributes describing npm install attempts (`registry_host`,
 `package_name`, `npm.outcome`) ship out of cloud-prem and must be sanitized
 **at the emit boundary** so customer infrastructure hostnames and registry
 tokens never appear in exported traces, metrics, logs, or audit events.
-Every emitter (P6.2 metrics, P6.3 audit events, any future runner) MUST
-pass values through the helpers in
-[`common/sanitize-npm-attributes.ts`](src/common/sanitize-npm-attributes.ts);
-the dashboard/collector layer is not the right place to sanitize.
+Every emitter (the `NpmRegistryEmitter`, P6.3 audit events, any future
+runner) MUST pass values through the helpers in
+[`npm-registry/sanitize.ts`](src/npm-registry/sanitize.ts); the
+dashboard/collector layer is not the right place to sanitize.
+
+The metrics emitter and the four named OTel spans live alongside it in
+[`src/npm-registry/`](src/npm-registry/) (`emitter.ts`, `spans.ts`). The
+emitter defines its own **per-path** short outcome enums
+(`install`/`probe`/`lookup`/`config`, e.g. `auth_failed`) — the long-form
+`NPM_OUTCOMES` below stays as the **audit-event** surface
+(`registry_auth_failed`); the divergence is intentional until an explicit
+audit-schema migration. `registry_host` is bucketed on the metric/span path
+but kept **raw** (guarded by `auditNpmRegistryHost`) on per-org log lines.
 
 | Attribute             | Rule                                                                                                                                                                                                                                 | Helper                                                |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
 | `registry_host`       | Bucket to `public_npm` / `private` / `unknown`. Raw hostnames never ship.                                                                                                                                                            | `bucketNpmRegistryHost`                               |
 | `package_name_bucket` | Metric destinations: bucket to `public` / `private` / `unknown` / `invalid`. Cardinality-safe; never carries the raw name.                                                                                                           | `bucketNpmPackageName` (or `npmAttributesForMetric`)  |
 | `package_name`        | Audit/log destinations only: emit verbatim (lowercased) if it parses as a valid npm name and is not a known-secret value pattern; else `invalid`.                                                                                    | `sanitizeNpmPackageName` (or `npmAttributesForAudit`) |
-| `npm.outcome`         | Closed allowlist of 6 values; unknown coerces to `other`.                                                                                                                                                                            | `normalizeNpmOutcome`                                 |
+| `npm.outcome`         | Audit-surface closed allowlist of 7 values; unknown coerces to `other`. (Metric paths use the shorter per-path enums in `emitter.ts`.)                                                                                               | `normalizeNpmOutcome`                                 |
 | Registry token        | Never an attribute. Bucketing strips it from URLs; `tier2-traces` lists token-shaped attribute NAMES as forbidden and `containsForbiddenPattern` rejects token-shaped VALUES (including `npm_<36+>`) smuggled into the package name. | n/a                                                   |
 
 ### `registry_host`
@@ -238,23 +247,29 @@ argue about the policy.
 
 ### `npm.outcome`
 
-Closed enum, allowlist explicit. The first five values match the
-structured error from APPS-4179 (P1.2) and APPS-4195 (P1.5); `other` is
-the catch-all so dashboards never see free-form strings.
+Closed enum, allowlist explicit. The first values match the structured
+error from APPS-4179 (P1.2) and APPS-4195 (P1.5); `tls_failed` was added in
+APPS-4381; `other` is the catch-all so dashboards never see free-form
+strings.
 
 ```
 success | not_in_registry | registry_unreachable | registry_auth_failed
-       | lockfile_url_mismatch | other
+       | tls_failed | lockfile_url_mismatch | other
 ```
 
-Coercion happens at the emit boundary — never at the dashboard.
+This long-form enum is the **audit-event** surface. The metric emitter
+(APPS-4378) uses shorter per-path enums in
+[`emitter.ts`](src/npm-registry/emitter.ts) — install `auth_failed` /
+`unreachable`, probe `ok` / `invalid_response`, etc. — and normalizes the
+long forms to them. Coercion happens at the emit boundary — never at the
+dashboard.
 
 ### Source-of-truth + acceptance
 
 **Decision (APPS-4190, signed off in #19574):** `package_name` is destination-dependent — bucketed (`package_name_bucket`) for metric destinations, verbatim-lowercased for audit/log destinations. Future P6.2/P6.3 emitters do NOT re-argue this; tighten the helper instead.
 
-- Helper: [`packages/telemetry/src/common/sanitize-npm-attributes.ts`](src/common/sanitize-npm-attributes.ts)
-- Tests: [`sanitize-npm-attributes.test.ts`](src/common/sanitize-npm-attributes.test.ts) — covers each rule + a token-leak regression that asserts no token-bearing input ever appears in output
+- Helper: [`packages/telemetry/src/npm-registry/sanitize.ts`](src/npm-registry/sanitize.ts)
+- Tests: [`sanitize.test.ts`](src/npm-registry/sanitize.test.ts) — covers each rule + a token-leak regression that asserts no token-bearing input ever appears in output
 - Forbidden-attribute backstop: `npm.token` / `npm_token` / `npm.registry_token` / `registry_token` in `FORBIDDEN_TIER_2_SPAN_ATTRIBUTES`
 - Ticket: [APPS-4190](https://linear.app/superblocks/issue/APPS-4190) — referenced from downstream tickets (APPS-4189 metrics, APPS-4191 audit events)
 

package/dist/common/index.d.ts

@@ -14,7 +14,5 @@ export * from "./guardrails.js";
 export * from "./contracts/tier2-traces.js";
 export * from "./log-sanitizer.js";
 export * from "./normalize-metric-path.js";
-export * from "./sanitize-npm-attributes.js";
-export * from "./npm-install-metrics.js";
 export * from "./tier-hints.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC"}

package/dist/common/index.js

@@ -30,7 +30,5 @@ __exportStar(require("./guardrails.js"), exports);
 __exportStar(require("./contracts/tier2-traces.js"), exports);
 __exportStar(require("./log-sanitizer.js"), exports);
 __exportStar(require("./normalize-metric-path.js"), exports);
-__exportStar(require("./sanitize-npm-attributes.js"), exports);
-__exportStar(require("./npm-install-metrics.js"), exports);
 __exportStar(require("./tier-hints.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist/common/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;AAEH,uDAAqC;AACrC,2DAAyC;AACzC,gDAA8B;AAC9B,wDAAsC;AACtC,kDAAgC;AAChC,8DAA4C;AAC5C,qDAAmC;AACnC,6DAA2C;AAC3C,+DAA6C;AAC7C,2DAAyC;AACzC,kDAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;AAEH,uDAAqC;AACrC,2DAAyC;AACzC,gDAA8B;AAC9B,wDAAsC;AACtC,kDAAgC;AAChC,8DAA4C;AAC5C,qDAAmC;AACnC,6DAA2C;AAC3C,kDAAgC"}

package/dist/index.d.ts

@@ -38,6 +38,7 @@
  */
 export * from "./types/index.js";
 export * from "./common/index.js";
+export * from "./npm-registry/index.js";
 export * from "./llmobs/index.js";
 export { REDACTED_PLACEHOLDER } from "./common/index.js";
 export { createSafeLogger, getLoggingPolicy, getMinimumPinoLevelForDeployment, getMinimumPinoLevelFromLoggingPolicy, getTelemetryInstance, initNodeTelemetry, isTelemetryInitialized, LogExportMode, redactForbiddenFields, resetTelemetry, type NodeTelemetryInstance, type LoggingPolicyConfig, type SafeLoggerLike, MetricsClient, type Labels, type CounterHandle, type GaugeHandle, type HistogramHandle, TracedSocket, type TracedSocketConfig, type TracedSocketOptions, } from "./node/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gCAAgC,EAChC,oCAAoC,EACpC,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,aAAa,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,yBAAyB,CAAC;AAGxC,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gCAAgC,EAChC,oCAAoC,EACpC,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,aAAa,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -57,6 +57,8 @@ exports.TracedSocket = exports.MetricsClient = exports.resetTelemetry = exports.
 __exportStar(require("./types/index.js"), exports);
 // Re-export common utilities
 __exportStar(require("./common/index.js"), exports);
+// Re-export npm-registry telemetry (sanitization, metrics emitter, spans)
+__exportStar(require("./npm-registry/index.js"), exports);
 // Re-export LLMObs tiered telemetry
 __exportStar(require("./llmobs/index.js"), exports);
 // Re-export Node.js telemetry functions for convenience

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;;;;;;;;;;;;;;;;AAEH,kBAAkB;AAClB,mDAAiC;AAEjC,6BAA6B;AAC7B,oDAAkC;AAElC,oCAAoC;AACpC,oDAAkC;AAElC,wDAAwD;AACxD,2FAA2F;AAC3F,8CAAyD;AAAhD,gHAAA,oBAAoB,OAAA;AAC7B,4CAsByB;AArBvB,4GAAA,gBAAgB,OAAA;AAChB,4GAAA,gBAAgB,OAAA;AAChB,4HAAA,gCAAgC,OAAA;AAChC,gIAAA,oCAAoC,OAAA;AACpC,gHAAA,oBAAoB,OAAA;AACpB,6GAAA,iBAAiB,OAAA;AACjB,kHAAA,sBAAsB,OAAA;AACtB,yGAAA,aAAa,OAAA;AACb,iHAAA,qBAAqB,OAAA;AACrB,0GAAA,cAAc,OAAA;AAId,yGAAA,aAAa,OAAA;AAKb,wGAAA,YAAY,OAAA;AAKd,wFAAwF;AACxF,kBAAkB;AAClB,yCAAyC;AACzC,yCAAyC;AACzC,wCAAwC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;;;;;;;;;;;;;;;;AAEH,kBAAkB;AAClB,mDAAiC;AAEjC,6BAA6B;AAC7B,oDAAkC;AAElC,0EAA0E;AAC1E,0DAAwC;AAExC,oCAAoC;AACpC,oDAAkC;AAElC,wDAAwD;AACxD,2FAA2F;AAC3F,8CAAyD;AAAhD,gHAAA,oBAAoB,OAAA;AAC7B,4CAsByB;AArBvB,4GAAA,gBAAgB,OAAA;AAChB,4GAAA,gBAAgB,OAAA;AAChB,4HAAA,gCAAgC,OAAA;AAChC,gIAAA,oCAAoC,OAAA;AACpC,gHAAA,oBAAoB,OAAA;AACpB,6GAAA,iBAAiB,OAAA;AACjB,kHAAA,sBAAsB,OAAA;AACtB,yGAAA,aAAa,OAAA;AACb,iHAAA,qBAAqB,OAAA;AACrB,0GAAA,cAAc,OAAA;AAId,yGAAA,aAAa,OAAA;AAKb,wGAAA,YAAY,OAAA;AAKd,wFAAwF;AACxF,kBAAkB;AAClB,yCAAyC;AACzC,yCAAyC;AACzC,wCAAwC"}

package/dist/npm-registry/emitter.d.ts

@@ -0,0 +1,227 @@
+/**
+ * NPM Registry Metrics Emitter (APPS-4378 / APPS-4189)
+ *
+ * One emitter for the whole npm-registry subsystem. It owns every
+ * `superblocks.npm.*` metric and centralizes the sanitize-at-emit-boundary
+ * discipline: no raw registry hostname, package name, or token can escape via
+ * a metric label because every dimension is coerced to a closed enum or a
+ * bounded bucket here, the moment before it reaches an OTel instrument.
+ *
+ * Wiring follows the rest of the npm subsystem: the meter is resolved lazily
+ * from the OTel global (`metrics.getMeter`) and instruments are cached and
+ * re-bound when the global MeterProvider changes (the typical case is a test
+ * installing its own provider for isolation). The emitter is therefore a
+ * zero-config process singleton (`npmRegistryEmitter`) — no DI plumbing
+ * through AiServiceConfig / NpmRegistryClientDeps.
+ *
+ * Metrics (all `superblocks.npm.*`, durations in seconds):
+ *
+ *   - `config.lookup_total`     counter   {result}
+ *   - `config.lookup_duration_seconds` histogram {result} buckets [0.05,0.25,1,3,10,30]
+ *   - `install.outcome_total`   counter   {outcome, configured, registry_host, runner}
+ *   - `install.duration_seconds`histogram {…same…}  buckets [0.5,2,5,15,60,300]
+ *   - `install.status`          gauge     {…same…}  last-seen 1=success/0=else
+ *   - `probe.outcome_total`     counter   {outcome, registry_host}
+ *   - `probe.duration_seconds`  histogram {…same…}  buckets [0.1,0.5,1,3,10,30]
+ *   - `lookup.calls_total`      counter   {outcome, registry_host}
+ *   - `lookup.duration_seconds` histogram {…same…}  buckets [0.05,0.25,1,3,10,30]
+ *   - `killswitch.enabled`      gauge     {}         1 when the feature is suppressed
+ *
+ * Cardinality budget (documented contract — must not regress without a
+ * migration plan; every dashboard / Datadog facet pins on these):
+ *
+ *   - registry_host ≤ 3   (`public_npm | private | unknown`)
+ *   - install.outcome ≤ 7 (`NPM_INSTALL_OUTCOMES`)
+ *   - probe.outcome ≤ 5   (`NPM_PROBE_OUTCOMES`)
+ *   - lookup.outcome ≤ 3  (`NPM_LOOKUP_TOOL_OUTCOMES`)
+ *   - config.result ≤ 4   (`NPM_CONFIG_LOOKUP_RESULTS`)
+ *   - configured ≤ 2, runner ≤ 4 (`NPM_INSTALL_RUNNERS`)
+ *
+ * Worst-case distinct series across every instrument is ≈ 560: the three
+ * install instruments (status gauge + counter + histogram) dominate at
+ * outcome×configured×registry_host×runner = 7×2×3×4 = 168 each → 504, plus
+ * probe 5×3×2=30, config 4×2=8, lookup 3×3×2=18, and the killswitch gauge 1.
+ * APPS-4544 raised the runner count from 3 to 4, which is why this grew from
+ * ≈430 (adding a runner value must increase the count, not decrease it). Still
+ * well under the internal 150K flag and the Datadog billing boundary. Per-pod
+ * `host` is stripped at the collector for the `superblocks.npm.*` family so
+ * series are aggregated by `service.name`.
+ *
+ * Each path has its OWN closed outcome enum + `normalize*` coercer because the
+ * paths legitimately diverge (probe has `ok`/`invalid_response`, install has
+ * `tls_failed`/`lockfile_url_mismatch`, …). `auth_failed` is deliberately a
+ * first-class outcome on install/probe — an expected, fast-failing
+ * customer-config mode — kept separable from infra failures (`unreachable` /
+ * `tls_failed`) so a future alert can page on infra spikes while routing auth
+ * to a dashboard. These short names diverge from the long-form `NPM_OUTCOMES`
+ * in `./sanitize` (which stays as the audit-event surface): the install path
+ * normalizes the long `NpmInstallBlocked.reason` values to the short forms.
+ */
+import { type NpmRegistryBucket } from "./sanitize.js";
+/**
+ * Closed enum of npm install call sites that emit metrics. One value per call
+ * site Superblocks owns; renaming a value breaks every dashboard split on
+ * `runner`, so additions/removals need a migration plan.
+ *
+ *   - `install_all`      — full install from package.json (no specific
+ *                          packages). Covers both `AppShell.runNpmInstall`
+ *                          and `AppShell.runPackageManagerInstall`.
+ *   - `install_specific` — `AppShell.installSpecificPackages` (`npm add`).
+ *   - `prefetch`         — `installTemplateModules` (template `node_modules`
+ *                          prefetch during AiService construction).
+ *   - `auto_upgrade`     — `upgradeCliWithPackageManager` in the CLI SDK
+ *                          (`automatic-upgrades.ts`). Owns the dev-server
+ *                          self-upgrade install; a perimeter block here
+ *                          crash-loops the live-edit pod, so the metric is
+ *                          the only signal that distinguishes that from a
+ *                          working upgrade. APPS-4544.
+ */
+export declare const NPM_INSTALL_RUNNERS: readonly ["auto_upgrade", "install_all", "install_specific", "prefetch"];
+export type NpmInstallRunner = (typeof NPM_INSTALL_RUNNERS)[number];
+/**
+ * `config.lookup_total` result. Derived inside `NpmRegistryClient.getConfig`
+ * (the only place that knows cache hit vs miss): in-TTL non-empty hit → `hit`;
+ * fresh fetch with a configured registry → `miss`; empty / 404 / flag-off →
+ * `not_configured`; `stale` / `unreachable` / any throw → `error`.
+ */
+export declare const NPM_CONFIG_LOOKUP_RESULTS: readonly ["hit", "miss", "not_configured", "error"];
+export type NpmConfigLookupResult = (typeof NPM_CONFIG_LOOKUP_RESULTS)[number];
+/** Unknown config-lookup states are an error condition, not a new series. */
+export declare function normalizeConfigLookupResult(input: string | null | undefined): NpmConfigLookupResult;
+/**
+ * `install.outcome_total` outcome. Short forms; the install path normalizes
+ * the long `NpmInstallBlocked.reason` values (`registry_auth_failed`,
+ * `registry_unreachable`) to these via {@link normalizeInstallOutcome}.
+ */
+export declare const NPM_INSTALL_OUTCOMES: readonly ["success", "auth_failed", "not_in_registry", "unreachable", "tls_failed", "lockfile_url_mismatch", "other"];
+export type NpmInstallOutcome = (typeof NPM_INSTALL_OUTCOMES)[number];
+export declare function normalizeInstallOutcome(input: string | null | undefined): NpmInstallOutcome;
+/** `probe.outcome_total` outcome. Mapped from the server `ProbeResult`. */
+export declare const NPM_PROBE_OUTCOMES: readonly ["ok", "auth_failed", "unreachable", "tls_failed", "invalid_response"];
+export type NpmProbeOutcome = (typeof NPM_PROBE_OUTCOMES)[number];
+/**
+ * Unknown → `unreachable`: the typed call site maps the closed `ProbeReason`
+ * exhaustively, so this floor only fires on a non-typed (JS) caller, where
+ * "we couldn't classify the probe" is safest reported as a connectivity
+ * failure rather than silently dropped or minted as a new series.
+ */
+export declare function normalizeProbeOutcome(input: string | null | undefined): NpmProbeOutcome;
+/** `lookup.calls_total` outcome (the Clark `lookupNpmPackage` tool). */
+export declare const NPM_LOOKUP_TOOL_OUTCOMES: readonly ["in_registry", "not_in_registry", "error"];
+export type NpmLookupToolOutcome = (typeof NPM_LOOKUP_TOOL_OUTCOMES)[number];
+/** Auth / unreachable / fail-closed / throw all collapse to `error` here. */
+export declare function normalizeLookupToolOutcome(input: string | null | undefined): NpmLookupToolOutcome;
+export interface NpmInstallMetricInput {
+    /** Which install call site emitted this event. */
+    runner: NpmInstallRunner;
+    /**
+     * Registry URL or bare hostname (`null`/`undefined` → `unknown`). Always
+     * bucketed via `bucketNpmRegistryHost`, so raw hostnames cannot leak.
+     */
+    registryHost: string | null | undefined;
+    /**
+     * Outcome key. Free-form on input; coerced to {@link NPM_INSTALL_OUTCOMES}
+     * at the emit boundary (long `NpmInstallBlocked.reason` forms are mapped to
+     * their short equivalents; unknown → `other`). Use `"success"` on the happy
+     * path.
+     */
+    outcome: string | null | undefined;
+    /**
+     * Whether the org had a private registry configured for this install
+     * (`result.config.configured`). Lets dashboards separate
+     * configured-but-failed from never-configured.
+     */
+    configured: boolean;
+    /** Elapsed wall-clock time in milliseconds; clamped at 0, emitted as seconds. */
+    durationMs: number;
+}
+export interface NpmProbeMetricInput {
+    registryHost: string | null | undefined;
+    outcome: string | null | undefined;
+    durationMs: number;
+}
+export interface NpmLookupToolMetricInput {
+    registryHost: string | null | undefined;
+    outcome: string | null | undefined;
+    durationMs: number;
+}
+/**
+ * Attribute set shaped for `llmobs.annotate({ tags })`. Returned by
+ * `recordInstall` so the active install span carries the exact values that
+ * went into the metric pipeline.
+ */
+export interface NpmInstallSpanAttributes {
+    "npm.registry_host": NpmRegistryBucket;
+    "npm.outcome": NpmInstallOutcome;
+}
+/**
+ * The npm-registry metrics emitter. Constructed once as the
+ * {@link npmRegistryEmitter} singleton; no `Meter` is injected — instruments
+ * resolve lazily from the OTel global and re-bind on provider change.
+ */
+export declare class NpmRegistryEmitter {
+    /**
+     * Last-seen install status keyed by the attribute tuple. The observable
+     * gauge reads this each collection cycle. Every key component is coerced to
+     * a closed enum / bounded bucket at the emit boundary
+     * (`normalizeInstallOutcome`, `bucketNpmRegistryHost`, the `NpmInstallRunner`
+     * union, a boolean), so the map is **bounded by construction** at
+     * runner(4) × configured(2) × registry_host(3) × outcome(7) = 168 entries —
+     * it cannot grow with traffic, only with deliberate enum changes. Entries
+     * persist until process exit / `_resetForTesting` (a "last-seen for
+     * dashboards" gauge must not drop a combo and lie about the most recent
+     * outcome); no eviction is needed at this bound. The cardinality regression
+     * test pins the resulting series count.
+     */
+    private readonly lastInstallStatus;
+    /** Returns `true` when the kill-switch is asserting (feature suppressed). */
+    private killswitchState;
+    private cachedMeter;
+    private cachedInstruments;
+    /**
+     * Lazy instrument factory. Re-creates instruments and re-registers the
+     * observable-gauge callbacks when the global MeterProvider changes (a stale
+     * instrument bound to a replaced provider silently drops data).
+     */
+    private getInstruments;
+    /**
+     * Emit one `config.lookup_total` + `config.lookup_duration_seconds`
+     * observation. `durationMs` is the time `getConfig` spent resolving — sub-ms
+     * for a cache hit, the network round-trip (+ any JWT-refresh retry) for a
+     * miss — so dashboards can tell fast cache hits from slow cold fetches.
+     */
+    recordConfigLookup(result: string | null | undefined, durationMs: number): void;
+    /**
+     * Emit the install outcome counter + duration histogram + last-seen status
+     * gauge, and return the matching span-attribute pair for `llmobs.annotate`.
+     * Safe to call from a `finally` block.
+     */
+    recordInstall(input: NpmInstallMetricInput): NpmInstallSpanAttributes;
+    /** Emit one `probe.outcome_total` + `probe.duration_seconds` observation. */
+    recordProbe(input: NpmProbeMetricInput): void;
+    /** Emit one `lookup.calls_total` + `lookup.duration_seconds` observation. */
+    recordLookupTool(input: NpmLookupToolMetricInput): void;
+    /**
+     * Register the kill-switch state source. `getCurrentState` returns `true`
+     * when the feature is suppressed (LD flag off). Idempotent — the latest
+     * source wins; the observable gauge reads it on each scrape. Calling this
+     * also ensures the instruments (and thus the gauge callback) are wired.
+     */
+    setKillswitch(getCurrentState: () => boolean): void;
+    /**
+     * Test-only: drop cached instruments, last-seen status, and the kill-switch
+     * source so the next emit re-binds to a freshly-installed test provider.
+     */
+    _resetForTesting(): void;
+}
+/** Process-wide singleton. All npm-registry call sites emit through this. */
+export declare const npmRegistryEmitter: NpmRegistryEmitter;
+/**
+ * Back-compat free function for the install path (APPS-4189 call sites in
+ * `shell.ts` / `template-renderer.ts`). Delegates to the singleton and returns
+ * the span-attribute pair for `llmobs.annotate`.
+ */
+export declare function recordNpmInstall(input: NpmInstallMetricInput): NpmInstallSpanAttributes;
+/** Test-only reset for the singleton (see {@link NpmRegistryEmitter._resetForTesting}). */
+export declare function _resetNpmRegistryEmitterForTesting(): void;
+//# sourceMappingURL=emitter.d.ts.map

package/dist/npm-registry/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/npm-registry/emitter.ts"],"names":[],"mappings":"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"}