@superblocksteam/telemetry 2.0.129 → 2.0.130-next.0

package/dist/npm-registry/spans.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * NPM Registry Spans (APPS-4378)
+ *
+ * OTel-native `startActiveSpan` helpers for the four named npm-registry spans.
+ * Using the global tracer (`trace.getTracer`) means LLMObs interop is
+ * automatic: a span started inside an `@llmobs.decorate`'d context becomes a
+ * child of that task span (shared global tracer provider); outside any LLMObs
+ * context (server verify, CLI bootstrap) it is a root span.
+ *
+ * `org_id` rides on spans (per-trace context), never on a metric label. Raw
+ * registry hostnames are bucketed via {@link bucketNpmRegistryHost} before
+ * they reach a span attribute, matching the metric path — the one exception
+ * is the structured-log path, which keeps the raw host (see
+ * {@link auditNpmRegistryHost} in ./sanitize).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NPM_REGISTRY_SPAN_ATTR = exports.NPM_REGISTRY_SPAN = void 0;
+exports.withNpmRegistrySpan = withNpmRegistrySpan;
+exports.npmPackageUnpackedSizeBytes = npmPackageUnpackedSizeBytes;
+const api_1 = require("@opentelemetry/api");
+/** Instrumentation scope for every npm-registry span. */
+const TRACER_NAME = "superblocks.npm-registry";
+/** The four named spans (APPS-4378). */
+exports.NPM_REGISTRY_SPAN = {
+    VERIFY: "npm_registry.verify",
+    LOOKUP_PACKAGE: "npm_registry.lookup_package",
+    PREPARE_FOR_PRIVATE_REGISTRY: "npm_registry.prepare_for_private_registry",
+    SYNC_HOME_NPMRC: "npm_registry.sync_home_npmrc",
+};
+/**
+ * Canonical span-attribute keys, shared across the four spans so the
+ * dimension names never drift between call sites.
+ */
+exports.NPM_REGISTRY_SPAN_ATTR = {
+    ORG_ID: "org_id",
+    /** Bucketed (`public_npm | private | unknown`) — never the raw host. */
+    REGISTRY_HOST: "registry_host",
+    OUTCOME: "outcome",
+    DURATION_MS: "duration_ms",
+    /** Richer `NpmRegistryFetchResult.source` for drill-down. */
+    SOURCE: "source",
+    REGISTRY_CONFIGURED: "registry_configured",
+    /** Tri-valued: `true | false | "unknown"`. */
+    ALLOW_INSTALL_SCRIPTS: "allow_install_scripts",
+    PACKAGE_NAME_BUCKET: "package_name_bucket",
+    /** Span-attribute ONLY — raw byte counts are unbounded, never a metric label. */
+    PACKAGE_UNPACKED_SIZE_BYTES: "package_unpacked_size_bytes",
+};
+/**
+ * Start an active npm-registry span over the global tracer, run `fn`, and
+ * end the span in `finally`. On throw, the error is recorded
+ * (`span.recordException`) and the span status set to ERROR before the throw
+ * propagates. `fn` receives the span so it can attach final attributes
+ * (outcome / duration) once the operation resolves.
+ */
+async function withNpmRegistrySpan(spanName, initialAttributes, fn) {
+    const tracer = api_1.trace.getTracer(TRACER_NAME);
+    return tracer.startActiveSpan(spanName, async (span) => {
+        if (Object.keys(initialAttributes).length > 0) {
+            span.setAttributes(initialAttributes);
+        }
+        try {
+            return await fn(span);
+        }
+        catch (err) {
+            // `recordException` accepts Error | string; narrow rather than cast.
+            span.recordException(err instanceof Error ? err : String(err));
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Coerce a registry-reported `dist.unpackedSize` to a span-safe value: a
+ * finite, non-negative number, else `undefined`. A hostile or buggy registry
+ * cannot smuggle a non-numeric byte count onto the span through this guard.
+ *
+ * Callers MUST omit the attribute when this returns `undefined` rather than
+ * calling `setAttribute(key, undefined)` (some OTel exporters mishandle
+ * undefined values). The lookup call site guards with `if (size !== undefined)`.
+ */
+function npmPackageUnpackedSizeBytes(raw) {
+    return typeof raw === "number" && Number.isFinite(raw) && raw >= 0
+        ? raw
+        : undefined;
+}
+//# sourceMappingURL=spans.js.map

package/dist/npm-registry/spans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.js","sourceRoot":"","sources":["../../src/npm-registry/spans.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AA+CH,kDAqBC;AAWD,kEAIC;AAjFD,4CAK4B;AAE5B,yDAAyD;AACzD,MAAM,WAAW,GAAG,0BAA0B,CAAC;AAE/C,wCAAwC;AAC3B,QAAA,iBAAiB,GAAG;IAC/B,MAAM,EAAE,qBAAqB;IAC7B,cAAc,EAAE,6BAA6B;IAC7C,4BAA4B,EAAE,2CAA2C;IACzE,eAAe,EAAE,8BAA8B;CACvC,CAAC;AAEX;;;GAGG;AACU,QAAA,sBAAsB,GAAG;IACpC,MAAM,EAAE,QAAQ;IAChB,wEAAwE;IACxE,aAAa,EAAE,eAAe;IAC9B,OAAO,EAAE,SAAS;IAClB,WAAW,EAAE,aAAa;IAC1B,6DAA6D;IAC7D,MAAM,EAAE,QAAQ;IAChB,mBAAmB,EAAE,qBAAqB;IAC1C,8CAA8C;IAC9C,qBAAqB,EAAE,uBAAuB;IAC9C,mBAAmB,EAAE,qBAAqB;IAC1C,iFAAiF;IACjF,2BAA2B,EAAE,6BAA6B;CAClD,CAAC;AAEX;;;;;;GAMG;AACI,KAAK,UAAU,mBAAmB,CACvC,QAAgB,EAChB,iBAA6B,EAC7B,EAA8B;IAE9B,MAAM,MAAM,GAAG,WAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC5C,OAAO,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACrD,IAAI,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,qEAAqE;YACrE,IAAI,CAAC,eAAe,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAC/D,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,oBAAc,CAAC,KAAK,EAAE,CAAC,CAAC;YAC/C,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,2BAA2B,CAAC,GAAY;IACtD,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAChE,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}

package/dist-esm/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-esm/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-esm/common/index.js

@@ -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.js.map

package/dist-esm/common/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","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.js","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-esm/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-esm/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-esm/index.js

@@ -40,6 +40,8 @@
 export * from "./types/index.js";
 // Re-export common utilities
 export * from "./common/index.js";
+// Re-export npm-registry telemetry (sanitization, metrics emitter, spans)
+export * from "./npm-registry/index.js";
 // Re-export LLMObs tiered telemetry
 export * from "./llmobs/index.js";
 // Re-export Node.js telemetry functions for convenience

package/dist-esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,kBAAkB;AAClB,cAAc,kBAAkB,CAAC;AAEjC,6BAA6B;AAC7B,cAAc,mBAAmB,CAAC;AAElC,oCAAoC;AACpC,cAAc,mBAAmB,CAAC;AAElC,wDAAwD;AACxD,2FAA2F;AAC3F,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,EAId,aAAa,EAKb,YAAY,GAGb,MAAM,iBAAiB,CAAC;AAEzB,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,cAAc,kBAAkB,CAAC;AAEjC,6BAA6B;AAC7B,cAAc,mBAAmB,CAAC;AAElC,0EAA0E;AAC1E,cAAc,yBAAyB,CAAC;AAExC,oCAAoC;AACpC,cAAc,mBAAmB,CAAC;AAElC,wDAAwD;AACxD,2FAA2F;AAC3F,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,EAId,aAAa,EAKb,YAAY,GAGb,MAAM,iBAAiB,CAAC;AAEzB,wFAAwF;AACxF,kBAAkB;AAClB,yCAAyC;AACzC,yCAAyC;AACzC,wCAAwC"}

package/dist-esm/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-esm/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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"}