@superblocksteam/telemetry 2.0.129 → 2.0.130-next.0

package/dist/npm-registry/emitter.js

@@ -0,0 +1,402 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.npmRegistryEmitter = exports.NpmRegistryEmitter = exports.NPM_LOOKUP_TOOL_OUTCOMES = exports.NPM_PROBE_OUTCOMES = exports.NPM_INSTALL_OUTCOMES = exports.NPM_CONFIG_LOOKUP_RESULTS = exports.NPM_INSTALL_RUNNERS = void 0;
+exports.normalizeConfigLookupResult = normalizeConfigLookupResult;
+exports.normalizeInstallOutcome = normalizeInstallOutcome;
+exports.normalizeProbeOutcome = normalizeProbeOutcome;
+exports.normalizeLookupToolOutcome = normalizeLookupToolOutcome;
+exports.recordNpmInstall = recordNpmInstall;
+exports._resetNpmRegistryEmitterForTesting = _resetNpmRegistryEmitterForTesting;
+const api_1 = require("@opentelemetry/api");
+const sanitize_js_1 = require("./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.
+ */
+exports.NPM_INSTALL_RUNNERS = [
+    "auto_upgrade",
+    "install_all",
+    "install_specific",
+    "prefetch",
+];
+const METER_NAME = "@superblocksteam/telemetry/npm-registry";
+const METRIC_CONFIG_LOOKUP = "superblocks.npm.config.lookup_total";
+const METRIC_CONFIG_DURATION = "superblocks.npm.config.lookup_duration_seconds";
+const METRIC_INSTALL_OUTCOME = "superblocks.npm.install.outcome_total";
+const METRIC_INSTALL_DURATION = "superblocks.npm.install.duration_seconds";
+const METRIC_INSTALL_STATUS = "superblocks.npm.install.status";
+const METRIC_PROBE_OUTCOME = "superblocks.npm.probe.outcome_total";
+const METRIC_PROBE_DURATION = "superblocks.npm.probe.duration_seconds";
+const METRIC_LOOKUP_CALLS = "superblocks.npm.lookup.calls_total";
+const METRIC_LOOKUP_DURATION = "superblocks.npm.lookup.duration_seconds";
+const METRIC_KILLSWITCH = "superblocks.npm.killswitch.enabled";
+/**
+ * Explicit histogram boundaries (seconds). Coarse on purpose: latency
+ * histograms here exist to detect regressions / alert on pathological cases,
+ * not for fine percentile work, so 6 finite buckets beat OTel's default 12.
+ * The SDK appends an implicit `(last, +∞)` overflow bucket, so values past the
+ * top boundary are still counted — the arrays stay finite (no `Infinity`).
+ */
+const INSTALL_DURATION_BUCKETS = [0.5, 2, 5, 15, 60, 300];
+const PROBE_DURATION_BUCKETS = [0.1, 0.5, 1, 3, 10, 30];
+const LOOKUP_DURATION_BUCKETS = [0.05, 0.25, 1, 3, 10, 30];
+// Config lookups span sub-ms cache hits to multi-second cold fetches (network
+// round-trip + possible JWT-refresh retry), so reuse the lookup-tool scale.
+const CONFIG_DURATION_BUCKETS = [0.05, 0.25, 1, 3, 10, 30];
+// ---------------------------------------------------------------------------
+// Per-path closed outcome enums + emit-boundary coercers.
+// ---------------------------------------------------------------------------
+/**
+ * `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`.
+ */
+exports.NPM_CONFIG_LOOKUP_RESULTS = [
+    "hit",
+    "miss",
+    "not_configured",
+    "error",
+];
+/** Unknown config-lookup states are an error condition, not a new series. */
+function normalizeConfigLookupResult(input) {
+    return (exports.NPM_CONFIG_LOOKUP_RESULTS.find((result) => result === input) ?? "error");
+}
+/**
+ * `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}.
+ */
+exports.NPM_INSTALL_OUTCOMES = [
+    "success",
+    "auth_failed",
+    "not_in_registry",
+    "unreachable",
+    "tls_failed",
+    "lockfile_url_mismatch",
+    "other",
+];
+/**
+ * Long-form `NpmInstallBlocked.reason` → short install-metric outcome.
+ * `NPM_INSTALL_OUTCOMES` above is the canonical list for the metric; a blocked
+ * reason that is neither already a short outcome nor aliased here folds to
+ * `other` on the metric (the precise reason still rides on the log/audit
+ * surface via `NPM_OUTCOMES` in ./sanitize). Add an entry here when a new
+ * `NpmInstallBlocked.reason` should get its own metric facet rather than
+ * collapsing to `other`.
+ */
+const INSTALL_OUTCOME_ALIASES = new Map([
+    ["registry_auth_failed", "auth_failed"],
+    ["registry_unreachable", "unreachable"],
+]);
+function normalizeInstallOutcome(input) {
+    if (input == null)
+        return "other";
+    return (exports.NPM_INSTALL_OUTCOMES.find((outcome) => outcome === input) ??
+        INSTALL_OUTCOME_ALIASES.get(input) ??
+        "other");
+}
+/** `probe.outcome_total` outcome. Mapped from the server `ProbeResult`. */
+exports.NPM_PROBE_OUTCOMES = [
+    "ok",
+    "auth_failed",
+    "unreachable",
+    "tls_failed",
+    "invalid_response",
+];
+/**
+ * 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.
+ */
+function normalizeProbeOutcome(input) {
+    return (exports.NPM_PROBE_OUTCOMES.find((outcome) => outcome === input) ?? "unreachable");
+}
+/** `lookup.calls_total` outcome (the Clark `lookupNpmPackage` tool). */
+exports.NPM_LOOKUP_TOOL_OUTCOMES = [
+    "in_registry",
+    "not_in_registry",
+    "error",
+];
+/** Auth / unreachable / fail-closed / throw all collapse to `error` here. */
+function normalizeLookupToolOutcome(input) {
+    return (exports.NPM_LOOKUP_TOOL_OUTCOMES.find((outcome) => outcome === input) ?? "error");
+}
+const SECONDS_PER_MS = 1 / 1000;
+const toSeconds = (durationMs) => Math.max(0, durationMs) * SECONDS_PER_MS;
+/**
+ * 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.
+ */
+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.
+     */
+    lastInstallStatus = new Map();
+    /** Returns `true` when the kill-switch is asserting (feature suppressed). */
+    killswitchState;
+    cachedMeter;
+    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).
+     */
+    getInstruments() {
+        const meter = api_1.metrics.getMeter(METER_NAME);
+        if (meter === this.cachedMeter && this.cachedInstruments) {
+            return this.cachedInstruments;
+        }
+        this.cachedMeter = meter;
+        this.cachedInstruments = {
+            configCounter: meter.createCounter(METRIC_CONFIG_LOOKUP, {
+                description: "Count of NpmRegistryClient.getConfig outcomes (cache hit/miss, not-configured, error).",
+                unit: "{lookup}",
+            }),
+            configHistogram: meter.createHistogram(METRIC_CONFIG_DURATION, {
+                description: "Duration of NpmRegistryClient.getConfig resolutions (cache hits are sub-ms; misses include the network fetch).",
+                unit: "s",
+                advice: { explicitBucketBoundaries: CONFIG_DURATION_BUCKETS },
+            }),
+            installCounter: meter.createCounter(METRIC_INSTALL_OUTCOME, {
+                description: "Count of npm install outcomes from Superblocks-owned paths.",
+                unit: "{install}",
+            }),
+            installHistogram: meter.createHistogram(METRIC_INSTALL_DURATION, {
+                description: "Duration of npm install invocations.",
+                unit: "s",
+                advice: { explicitBucketBoundaries: INSTALL_DURATION_BUCKETS },
+            }),
+            probeCounter: meter.createCounter(METRIC_PROBE_OUTCOME, {
+                description: "Count of org npm-registry verify-probe outcomes.",
+                unit: "{probe}",
+            }),
+            probeHistogram: meter.createHistogram(METRIC_PROBE_DURATION, {
+                description: "Duration of org npm-registry verify probes.",
+                unit: "s",
+                advice: { explicitBucketBoundaries: PROBE_DURATION_BUCKETS },
+            }),
+            lookupCounter: meter.createCounter(METRIC_LOOKUP_CALLS, {
+                description: "Count of Clark lookupNpmPackage tool outcomes.",
+                unit: "{call}",
+            }),
+            lookupHistogram: meter.createHistogram(METRIC_LOOKUP_DURATION, {
+                description: "Duration of Clark lookupNpmPackage tool calls.",
+                unit: "s",
+                advice: { explicitBucketBoundaries: LOOKUP_DURATION_BUCKETS },
+            }),
+        };
+        const statusGauge = meter.createObservableGauge(METRIC_INSTALL_STATUS, {
+            description: "Last-seen npm install status (1 = success, 0 = anything else) per runner+configured+registry+outcome. For at-a-glance dashboards.",
+        });
+        statusGauge.addCallback((result) => {
+            // Observable callbacks run on the metric export thread; an uncaught
+            // throw here aborts the whole collection cycle and drops every metric.
+            // Never let one escape.
+            try {
+                for (const { value, attrs } of this.lastInstallStatus.values()) {
+                    result.observe(value, attrs);
+                }
+            }
+            catch {
+                // Swallow: a metrics callback must not crash collection.
+            }
+        });
+        const killswitchGauge = meter.createObservableGauge(METRIC_KILLSWITCH, {
+            description: "1 when the npm-registry feature is suppressed (LD flag off / kill-switch active), 0 otherwise. One series per process.",
+        });
+        killswitchGauge.addCallback((result) => {
+            // Same export-thread safety as the status gauge: if the kill-switch
+            // state source throws (e.g. a flag client is momentarily unavailable),
+            // don't take down the whole npm-registry metric stream with it.
+            try {
+                if (this.killswitchState) {
+                    result.observe(this.killswitchState() ? 1 : 0);
+                }
+            }
+            catch {
+                // Swallow: a metrics callback must not crash collection.
+            }
+        });
+        return this.cachedInstruments;
+    }
+    /**
+     * 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, durationMs) {
+        const attrs = {
+            result: normalizeConfigLookupResult(result),
+        };
+        const { configCounter, configHistogram } = this.getInstruments();
+        configCounter.add(1, attrs);
+        configHistogram.record(toSeconds(durationMs), attrs);
+    }
+    /**
+     * 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) {
+        const { installCounter, installHistogram } = this.getInstruments();
+        const registry_host = (0, sanitize_js_1.bucketNpmRegistryHost)(input.registryHost);
+        const outcome = normalizeInstallOutcome(input.outcome);
+        const attrs = {
+            runner: input.runner,
+            outcome,
+            configured: input.configured,
+            registry_host,
+        };
+        installCounter.add(1, attrs);
+        installHistogram.record(toSeconds(input.durationMs), attrs);
+        const key = `${attrs.runner}|${attrs.configured}|${attrs.registry_host}|${attrs.outcome}`;
+        this.lastInstallStatus.set(key, {
+            value: outcome === "success" ? 1 : 0,
+            attrs,
+        });
+        return { "npm.registry_host": registry_host, "npm.outcome": outcome };
+    }
+    /** Emit one `probe.outcome_total` + `probe.duration_seconds` observation. */
+    recordProbe(input) {
+        const { probeCounter, probeHistogram } = this.getInstruments();
+        const attrs = {
+            outcome: normalizeProbeOutcome(input.outcome),
+            registry_host: (0, sanitize_js_1.bucketNpmRegistryHost)(input.registryHost),
+        };
+        probeCounter.add(1, attrs);
+        probeHistogram.record(toSeconds(input.durationMs), attrs);
+    }
+    /** Emit one `lookup.calls_total` + `lookup.duration_seconds` observation. */
+    recordLookupTool(input) {
+        const { lookupCounter, lookupHistogram } = this.getInstruments();
+        const attrs = {
+            outcome: normalizeLookupToolOutcome(input.outcome),
+            registry_host: (0, sanitize_js_1.bucketNpmRegistryHost)(input.registryHost),
+        };
+        lookupCounter.add(1, attrs);
+        lookupHistogram.record(toSeconds(input.durationMs), attrs);
+    }
+    /**
+     * 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) {
+        this.killswitchState = getCurrentState;
+        this.getInstruments();
+    }
+    /**
+     * 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() {
+        this.cachedMeter = undefined;
+        this.cachedInstruments = undefined;
+        this.lastInstallStatus.clear();
+        this.killswitchState = undefined;
+    }
+}
+exports.NpmRegistryEmitter = NpmRegistryEmitter;
+/** Process-wide singleton. All npm-registry call sites emit through this. */
+exports.npmRegistryEmitter = new 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`.
+ */
+function recordNpmInstall(input) {
+    return exports.npmRegistryEmitter.recordInstall(input);
+}
+/** Test-only reset for the singleton (see {@link NpmRegistryEmitter._resetForTesting}). */
+function _resetNpmRegistryEmitterForTesting() {
+    exports.npmRegistryEmitter._resetForTesting();
+}
+//# sourceMappingURL=emitter.js.map

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

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

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

@@ -0,0 +1,12 @@
+/**
+ * NPM Registry Telemetry
+ *
+ * Sanitization helpers, the unified metrics emitter, and the named OTel spans
+ * for the npm-registry subsystem (config fetch, install, verify probe, the
+ * Clark lookup tool, CLI npmrc sync). Re-exported from the package root, so
+ * callers import from `@superblocksteam/telemetry` rather than this subpath.
+ */
+export * from "./sanitize.js";
+export * from "./emitter.js";
+export * from "./spans.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/npm-registry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/npm-registry/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * NPM Registry Telemetry
+ *
+ * Sanitization helpers, the unified metrics emitter, and the named OTel spans
+ * for the npm-registry subsystem (config fetch, install, verify probe, the
+ * Clark lookup tool, CLI npmrc sync). Re-exported from the package root, so
+ * callers import from `@superblocksteam/telemetry` rather than this subpath.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./sanitize.js"), exports);
+__exportStar(require("./emitter.js"), exports);
+__exportStar(require("./spans.js"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/npm-registry/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;AAEH,gDAA8B;AAC9B,+CAA6B;AAC7B,6CAA2B"}

package/dist/{common/sanitize-npm-attributes.d.ts → npm-registry/sanitize.d.ts}

@@ -43,6 +43,24 @@ export type NpmRegistryBucket = (typeof NPM_REGISTRY_BUCKETS)[number];
  * the false-negative of suppressing private-registry behavior in telemetry.
  */
 export declare function bucketNpmRegistryHost(input: string | null | undefined): NpmRegistryBucket;
+/**
+ * Audit/log-destination form of `registry_host`. Unlike the metric/span
+ * path (which buckets to `public_npm | private | unknown` so a raw customer
+ * hostname never reaches a shared, cross-tenant destination), logs are
+ * per-org and retained internally, so on-call needs the **raw** hostname for
+ * forensic value ("which registry did org X actually hit?"). This helper is
+ * the log-boundary guard: it returns the host verbatim EXCEPT when it
+ *
+ *   - matches a known-secret value shape (`containsForbiddenPattern`) — a
+ *     developer-error backstop against a token smuggled in via a host arg, or
+ *   - contains an ASCII C0 control character or DEL — a log-injection /
+ *     line-spoofing payload,
+ *
+ * in which case it returns `"invalid"`. null/blank → `"unknown"`. The value
+ * is trimmed but otherwise unchanged (not lowercased): the host is the
+ * forensic signal and case is preserved as attempted.
+ */
+export declare function auditNpmRegistryHost(input: string | null | undefined): string;
 /**
  * Audit/log-destination form of the `package_name` attribute. Returns the
  * lowercased input verbatim when it parses as an npm name AND does not
@@ -153,4 +171,4 @@ export declare function npmAttributesForAudit(input: NpmAttributesInput): NpmAud
  * for triage; the host identity is what we must drop.
  */
 export declare function redactNpmRegistryHostsFromText(input: string): string;
-//# sourceMappingURL=sanitize-npm-attributes.d.ts.map
+//# sourceMappingURL=sanitize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/npm-registry/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,eAAO,MAAM,oBAAoB,+CAIvB,CAAC;AACX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAKtE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,iBAAiB,CAkBnB;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAS7E;AAeD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,CAWR;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,sDAK3B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,cAAc,EAAE,iBAAiB,GAChC,oBAAoB,CAetB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,yIAQf,CAAC;AACX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAIvD,iEAAiE;AACjE,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,UAAU,CAGZ;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,iBAAiB,CAAC;IACjC,mBAAmB,EAAE,oBAAoB,CAAC;IAC1C,OAAO,EAAE,UAAU,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,iBAAiB,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,UAAU,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,GACxB,mBAAmB,CAUrB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,kBAAkB,GACxB,kBAAkB,CAMpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA0BpE"}

package/dist/{common/sanitize-npm-attributes.js → npm-registry/sanitize.js}

@@ -30,13 +30,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NPM_OUTCOMES = exports.NPM_PACKAGE_NAME_BUCKETS = exports.NPM_REGISTRY_BUCKETS = void 0;
 exports.bucketNpmRegistryHost = bucketNpmRegistryHost;
+exports.auditNpmRegistryHost = auditNpmRegistryHost;
 exports.sanitizeNpmPackageName = sanitizeNpmPackageName;
 exports.bucketNpmPackageName = bucketNpmPackageName;
 exports.normalizeNpmOutcome = normalizeNpmOutcome;
 exports.npmAttributesForMetric = npmAttributesForMetric;
 exports.npmAttributesForAudit = npmAttributesForAudit;
 exports.redactNpmRegistryHostsFromText = redactNpmRegistryHostsFromText;
-const tier2_traces_js_1 = require("./contracts/tier2-traces.js");
+const tier2_traces_js_1 = require("../common/contracts/tier2-traces.js");
 exports.NPM_REGISTRY_BUCKETS = [
     "public_npm",
     "private",
@@ -80,6 +81,53 @@ function bucketNpmRegistryHost(input) {
         return "unknown";
     return PUBLIC_NPM_HOSTS.has(host) ? "public_npm" : "private";
 }
+/**
+ * Control characters (ASCII C0 range + DEL) that must never reach a log
+ * line: a newline/carriage-return lets a hostile value forge a second log
+ * record, and other C0 bytes corrupt structured-log parsers.
+ */
+function hasControlChar(value) {
+    // ASCII C0 controls (0x00-0x1F) + DEL (0x7F). A regex literal holding these
+    // raw bytes is invisible in source and trips no-control-regex, so we scan
+    // code points instead.
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * Audit/log-destination form of `registry_host`. Unlike the metric/span
+ * path (which buckets to `public_npm | private | unknown` so a raw customer
+ * hostname never reaches a shared, cross-tenant destination), logs are
+ * per-org and retained internally, so on-call needs the **raw** hostname for
+ * forensic value ("which registry did org X actually hit?"). This helper is
+ * the log-boundary guard: it returns the host verbatim EXCEPT when it
+ *
+ *   - matches a known-secret value shape (`containsForbiddenPattern`) — a
+ *     developer-error backstop against a token smuggled in via a host arg, or
+ *   - contains an ASCII C0 control character or DEL — a log-injection /
+ *     line-spoofing payload,
+ *
+ * in which case it returns `"invalid"`. null/blank → `"unknown"`. The value
+ * is trimmed but otherwise unchanged (not lowercased): the host is the
+ * forensic signal and case is preserved as attempted.
+ */
+function auditNpmRegistryHost(input) {
+    if (input == null)
+        return "unknown";
+    const trimmed = input.trim();
+    if (trimmed === "")
+        return "unknown";
+    // Secret-shape check runs on the trimmed (case-preserved) value: AKIA/JWT
+    // patterns are case-sensitive and must be caught before they reach a log.
+    if ((0, tier2_traces_js_1.containsForbiddenPattern)(trimmed))
+        return "invalid";
+    if (hasControlChar(trimmed))
+        return "invalid";
+    return trimmed;
+}
 /** npm package name spec (lowercased): optional `@scope/` prefix + name body. */
 const VALID_PACKAGE_NAME_RE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 /**
@@ -265,4 +313,4 @@ function redactNpmRegistryHostsFromText(input) {
     out = out.replace(/\bconnect\s+(E[A-Z]+)\s+([0-9a-fA-F.:]+)(?::\d+)?/g, (_m, code) => `connect ${code} <host>`);
     return out;
 }
-//# sourceMappingURL=sanitize-npm-attributes.js.map
+//# sourceMappingURL=sanitize.js.map

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

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

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

@@ -0,0 +1,61 @@
+/**
+ * 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).
+ */
+import { type Attributes, type Span } from "@opentelemetry/api";
+/** The four named spans (APPS-4378). */
+export declare const NPM_REGISTRY_SPAN: {
+    readonly VERIFY: "npm_registry.verify";
+    readonly LOOKUP_PACKAGE: "npm_registry.lookup_package";
+    readonly PREPARE_FOR_PRIVATE_REGISTRY: "npm_registry.prepare_for_private_registry";
+    readonly 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.
+ */
+export declare const NPM_REGISTRY_SPAN_ATTR: {
+    readonly ORG_ID: "org_id";
+    /** Bucketed (`public_npm | private | unknown`) — never the raw host. */
+    readonly REGISTRY_HOST: "registry_host";
+    readonly OUTCOME: "outcome";
+    readonly DURATION_MS: "duration_ms";
+    /** Richer `NpmRegistryFetchResult.source` for drill-down. */
+    readonly SOURCE: "source";
+    readonly REGISTRY_CONFIGURED: "registry_configured";
+    /** Tri-valued: `true | false | "unknown"`. */
+    readonly ALLOW_INSTALL_SCRIPTS: "allow_install_scripts";
+    readonly PACKAGE_NAME_BUCKET: "package_name_bucket";
+    /** Span-attribute ONLY — raw byte counts are unbounded, never a metric label. */
+    readonly 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.
+ */
+export declare function withNpmRegistrySpan<T>(spanName: string, initialAttributes: Attributes, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * 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)`.
+ */
+export declare function npmPackageUnpackedSizeBytes(raw: unknown): number | undefined;
+//# sourceMappingURL=spans.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spans.d.ts","sourceRoot":"","sources":["../../src/npm-registry/spans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,IAAI,EAGV,MAAM,oBAAoB,CAAC;AAK5B,wCAAwC;AACxC,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;IAEjC,wEAAwE;;;;IAIxE,6DAA6D;;;IAG7D,8CAA8C;;;IAG9C,iFAAiF;;CAEzE,CAAC;AAEX;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,UAAU,EAC7B,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI5E"}