@socketsecurity/lib 6.0.8 → 6.0.10

package/dist/logger/symbols-builder.js

@@ -26,18 +26,17 @@ src_external__socketregistry_is_unicode_supported = require_runtime.__toESM(src_
 */
 function buildLoggerSymbols(theme) {
 	const supported = (0, src_external__socketregistry_is_unicode_supported.default)();
-	const colors = require_logger_colors.getYoctocolors();
 	/* c8 ignore start - ASCII-fallback symbol arms only fire on
 	terminals without unicode support; tests run on unicode TTYs. */
 	return {
 		__proto__: null,
-		fail: require_logger_colors.applyColor(supported ? "✖" : "×", theme.colors.error, colors),
-		info: require_logger_colors.applyColor(supported ? "ℹ" : "i", theme.colors.info, colors),
-		progress: require_logger_colors.applyColor(supported ? "∴" : ":.", theme.colors.step, colors),
-		skip: require_logger_colors.applyColor(supported ? "↻" : "@", theme.colors.step, colors),
-		step: require_logger_colors.applyColor(supported ? "→" : ">", theme.colors.step, colors),
-		success: require_logger_colors.applyColor(supported ? "✔" : "√", theme.colors.success, colors),
-		warn: require_logger_colors.applyColor(supported ? "⚠" : "‼", theme.colors.warning, colors)
+		fail: require_logger_colors.applyColor(supported ? "✖" : "×", theme.colors.error),
+		info: require_logger_colors.applyColor(supported ? "ℹ" : "i", theme.colors.info),
+		progress: require_logger_colors.applyColor(supported ? "∴" : ":.", theme.colors.step),
+		skip: require_logger_colors.applyColor(supported ? "↻" : "@", theme.colors.step),
+		step: require_logger_colors.applyColor(supported ? "→" : ">", theme.colors.step),
+		success: require_logger_colors.applyColor(supported ? "✔" : "√", theme.colors.success),
+		warn: require_logger_colors.applyColor(supported ? "⚠" : "‼", theme.colors.warning)
 	};
 	/* c8 ignore stop */
 }

package/dist/logger/symbols.js

@@ -39,14 +39,14 @@ function createLogSymbols() {
 		const stepColor = theme.colors.step;
 		/* c8 ignore start - ASCII-fallback symbol arms only fire on
 		terminals without unicode support; tests run on unicode TTYs. */
-		target["fail"] = require_logger_colors.applyColor(supported ? "✖" : "×", errorColor, colors);
-		target["info"] = require_logger_colors.applyColor(supported ? "ℹ" : "i", infoColor, colors);
-		target["progress"] = require_logger_colors.applyColor(supported ? "∴" : ":.", stepColor, colors);
-		target["reason"] = colors.dim(require_logger_colors.applyColor(supported ? "∴" : ":.", warningColor, colors));
-		target["skip"] = require_logger_colors.applyColor(supported ? "↻" : "@", stepColor, colors);
-		target["step"] = require_logger_colors.applyColor(supported ? "→" : ">", stepColor, colors);
-		target["success"] = require_logger_colors.applyColor(supported ? "✔" : "√", successColor, colors);
-		target["warn"] = require_logger_colors.applyColor(supported ? "⚠" : "‼", warningColor, colors);
+		target["fail"] = require_logger_colors.applyColor(supported ? "✖" : "×", errorColor);
+		target["info"] = require_logger_colors.applyColor(supported ? "ℹ" : "i", infoColor);
+		target["progress"] = require_logger_colors.applyColor(supported ? "∴" : ":.", stepColor);
+		target["reason"] = colors.dim(require_logger_colors.applyColor(supported ? "∴" : ":.", warningColor));
+		target["skip"] = require_logger_colors.applyColor(supported ? "↻" : "@", stepColor);
+		target["step"] = require_logger_colors.applyColor(supported ? "→" : ">", stepColor);
+		target["success"] = require_logger_colors.applyColor(supported ? "✔" : "√", successColor);
+		target["warn"] = require_logger_colors.applyColor(supported ? "⚠" : "‼", warningColor);
 		/* c8 ignore stop */
 	};
 	const init = () => {

package/dist/native-messaging/install.js

@@ -9,11 +9,11 @@ const require_env_windows = require('../env/windows.js');
 const require_constants_node = require('../constants/node.js');
 const require_env_node_version_managers = require('../env/node-version-managers.js');
 let node_fs = require("node:fs");
+let node_url = require("node:url");
 let node_process = require("node:process");
 node_process = require_runtime.__toESM(node_process);
 let node_path = require("node:path");
 node_path = require_runtime.__toESM(node_path);
-let node_url = require("node:url");
 let _socketsecurity_lib_stable_process_spawn_child = require("@socketsecurity/lib-stable/process/spawn/child");
 
 //#region src/native-messaging/install.ts

package/dist/native-messaging/rate-limit.d.ts

@@ -14,7 +14,7 @@
  *   That's exactly what we want: an attacker who can force Chrome to relaunch
  *   has bigger problems than rate-limiting. Shape patterned after pilcrow's
  *   `ratelimit/limit.go` — minimal, in-memory, LRU-evicts at `maxKeys`. The
- *   fleet's `socket-lib` already has a TTL-cache module but it's overkill for
+ *   Socket's `socket-lib` already has a TTL-cache module but it's overkill for
  *   this one use case; a 50-line bucket is easier to audit.
  */
 export interface TokenBucketOptions {
@@ -45,6 +45,9 @@ export interface BucketEntry {
     older: BucketEntry | undefined;
     key: string;
 }
+/**
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
 export declare class TokenBucketLimiter {
     #private;
     constructor(options: TokenBucketOptions);

package/dist/native-messaging/rate-limit.js

@@ -20,9 +20,12 @@ const require_primordials_error = require('../primordials/error.js');
 *   That's exactly what we want: an attacker who can force Chrome to relaunch
 *   has bigger problems than rate-limiting. Shape patterned after pilcrow's
 *   `ratelimit/limit.go` — minimal, in-memory, LRU-evicts at `maxKeys`. The
-*   fleet's `socket-lib` already has a TTL-cache module but it's overkill for
+*   Socket's `socket-lib` already has a TTL-cache module but it's overkill for
 *   this one use case; a 50-line bucket is easier to audit.
 */
+/**
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
 var TokenBucketLimiter = class {
 	#capacity;
 	#refillIntervalMs;

package/dist/node/events.d.ts

@@ -3,4 +3,7 @@
  *   rationale shared across all `node/*.ts` lazy-loaders.
  */
 import type * as NodeEvents from 'node:events';
+/**
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
 export declare function getNodeEvents(): typeof NodeEvents;

package/dist/node/events.js

@@ -5,6 +5,9 @@ const require_constants_runtime = require('../constants/runtime.js');
 
 //#region src/node/events.ts
 let events;
+/**
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
 function getNodeEvents() {
 	if (!require_constants_runtime.IS_NODE) return;
 	return events ??= /*@__PURE__*/ require("events");

package/dist/node/fs.d.ts

@@ -12,7 +12,7 @@
  *   load-time snapshot. Two surfaces: `getNodeFs()` returns the module object
  *   with LATE method lookup (spy-able — the test seam); the `fs<Method>` consts
  *   (`fsExistsSync`, `fsReadFileSync`, …) are method references FROZEN at load
- *   (tamper-proof against a method swap, not spy-able), for the fleet's hot fs
+ *   (tamper-proof against a method swap, not spy-able), for Socket's hot fs
  *   calls. Both stay browser-safe behind IS_NODE + `/*@__PURE__*\/`.
  */
 import type * as NodeFs from 'node:fs';

package/dist/node/module.d.ts

@@ -1,7 +1,78 @@
 /**
- * @file Lazy-loader for `node:module`. See `node/fs.ts` for the design
- *   rationale shared across all `node/*.ts` lazy-loaders.
+ * @file Accessors for `node:module` that work across runtimes. Ambient
+ *   `require` is bound in CommonJS but unbound in ESM and inside
+ *   ahead-of-time-compiled package modules (e.g. Perry), where reading it
+ *   throws. And Perry's `require('module')` value omits `isBuiltin`. So instead
+ *   of the ambient `require('module')` lazy-loader, `isBuiltin`/`createRequire`
+ *   are imported as named values from the bare `module` specifier — which
+ *   resolves on Node and Perry, and which browser bundlers can stub via
+ *   resolve.fallback (a `node:` prefix would throw UnhandledSchemeError
+ *   there).
+ *   `require` is DIRECTORY-SPECIFIC: `createRequire(base)` resolves relative
+ *   specifiers (`./x`, `../y`) from `base`'s directory. For builtins and bare
+ *   packages that's irrelevant (they resolve the same anywhere), so the cached
+ *   `getRequire` / `requireBuiltin` bind to THIS file. A RELATIVE specifier
+ *   must resolve from the CALLER's directory, so use `requireFrom` with the
+ *   caller's `import.meta.url` — binding such a load to this file would resolve
+ *   it against `src/node/` instead. Bundled, every module collapses to one base
+ *   and either works; unbundled (e.g. AOT-compiled from source), each module
+ *   sits at its own nested path and the base matters.
  */
 import type * as NodeModule from 'node:module';
+/**
+ * Bind a working `require`. Ambient `require` exists in CommonJS; in ESM and
+ * ahead-of-time-compiled package modules it is unbound (reading it throws or
+ * yields undefined), so fall back to `createRequire`. Returns undefined off
+ * Node and in browsers, where neither is available.
+ *
+ * `fromUrl` sets the resolution base — pass a caller's `import.meta.url` to
+ * resolve that caller's RELATIVE specifiers. When omitted, the base is this
+ * file, which is correct only for builtins / bare packages (dir-independent).
+ * With `fromUrl` the ambient `require` is skipped: it is bound to THIS file, so
+ * it would resolve a relative specifier from the wrong directory.
+ */
+export declare function bindRequire(fromUrl?: string | undefined): ((id: string) => unknown) | undefined;
+/**
+ * Returns `node:module` (or undefined off Node), loaded through the bound
+ * `require`. Cached across calls.
+ */
 export declare function getNodeModule(): typeof NodeModule;
+/**
+ * Returns a working `require` bound to THIS file, binding one on first call
+ * (see bindRequire). Cached across calls; undefined off Node / in browsers.
+ *
+ * For builtins and bare packages only — the resolution base is this file, so a
+ * relative specifier would resolve from `src/node/`. Use `requireFrom` for
+ * relative loads.
+ */
+export declare function getRequire(): ((id: string) => unknown) | undefined;
+/**
+ * Is `name` a Node built-in module? Resolved from the statically-imported
+ * `isBuiltin`, so it works on Node and on ahead-of-time-compiled binaries
+ * (Perry), where ambient `require('module')` would lack `isBuiltin`. Returns
+ * false in browsers, where the bare `module` import is stubbed away.
+ *
+ * Single source of truth for "is this a Node builtin?" probes across socket-lib
+ * (used by the smol-binding loaders to gate their `node:smol-*` loads).
+ */
 export declare function isNodeBuiltin(name: string): boolean;
+/**
+ * Load a built-in module by *computed* specifier through the bound `require`
+ * (see getRequire). The specifier is a parameter — never a literal at the call
+ * site — so browser bundlers neither walk nor bundle it. Returns undefined
+ * where no `require` can be bound.
+ *
+ * Builtins / bare packages only (dir-independent); for a relative specifier use
+ * `requireFrom`. Used by `getNodeModule` for `node:module`, and by the
+ * smol-binding loaders for the optional `node:smol-*` native bindings (gated
+ * behind `isNodeBuiltin`, true only on socket-btm's smol Node binary).
+ */
+export declare function requireBuiltin(specifier: string): unknown;
+/**
+ * Load a module by specifier from a CALLER-supplied base (its
+ * `import.meta.url`). Use this for RELATIVE specifiers (`./x`, `../y`), whose
+ * resolution depends on the caller's directory — `requireBuiltin` binds to this
+ * file and would resolve them from `src/node/`. Not cached: the binding is
+ * per-caller. Returns undefined where no `require` can be bound.
+ */
+export declare function requireFrom(fromUrl: string, specifier: string): unknown;

package/dist/node/module.js

@@ -2,30 +2,115 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_constants_runtime = require('../constants/runtime.js');
+let module$1 = require("module");
 
 //#region src/node/module.ts
+/**
+* @file Accessors for `node:module` that work across runtimes. Ambient
+*   `require` is bound in CommonJS but unbound in ESM and inside
+*   ahead-of-time-compiled package modules (e.g. Perry), where reading it
+*   throws. And Perry's `require('module')` value omits `isBuiltin`. So instead
+*   of the ambient `require('module')` lazy-loader, `isBuiltin`/`createRequire`
+*   are imported as named values from the bare `module` specifier — which
+*   resolves on Node and Perry, and which browser bundlers can stub via
+*   resolve.fallback (a `node:` prefix would throw UnhandledSchemeError
+*   there).
+*   `require` is DIRECTORY-SPECIFIC: `createRequire(base)` resolves relative
+*   specifiers (`./x`, `../y`) from `base`'s directory. For builtins and bare
+*   packages that's irrelevant (they resolve the same anywhere), so the cached
+*   `getRequire` / `requireBuiltin` bind to THIS file. A RELATIVE specifier
+*   must resolve from the CALLER's directory, so use `requireFrom` with the
+*   caller's `import.meta.url` — binding such a load to this file would resolve
+*   it against `src/node/` instead. Bundled, every module collapses to one base
+*   and either works; unbundled (e.g. AOT-compiled from source), each module
+*   sits at its own nested path and the base matters.
+*/
 let cachedModule;
-function getNodeModule() {
+let cachedRequire;
+/**
+* Bind a working `require`. Ambient `require` exists in CommonJS; in ESM and
+* ahead-of-time-compiled package modules it is unbound (reading it throws or
+* yields undefined), so fall back to `createRequire`. Returns undefined off
+* Node and in browsers, where neither is available.
+*
+* `fromUrl` sets the resolution base — pass a caller's `import.meta.url` to
+* resolve that caller's RELATIVE specifiers. When omitted, the base is this
+* file, which is correct only for builtins / bare packages (dir-independent).
+* With `fromUrl` the ambient `require` is skipped: it is bound to THIS file, so
+* it would resolve a relative specifier from the wrong directory.
+*/
+function bindRequire(fromUrl) {
 	if (!require_constants_runtime.IS_NODE) return;
-	return cachedModule ??= /*@__PURE__*/ require("module");
+	if (!fromUrl && typeof require === "function") return require;
+	if (typeof module$1.createRequire === "function") try {
+		return (0, module$1.createRequire)(fromUrl ?? require("url").pathToFileURL(__filename).href);
+	} catch {
+		return;
+	}
+}
+/**
+* Returns `node:module` (or undefined off Node), loaded through the bound
+* `require`. Cached across calls.
+*/
+function getNodeModule() {
+	return cachedModule ??= requireBuiltin("module");
 }
 /**
-* Lazy + cached reference to `node:module`'s `isBuiltin(name)`. First call
-* resolves the binding; subsequent calls dispatch through the cached function
-* reference. Safe to detach — `isBuiltin` is `this`-free.
+* Returns a working `require` bound to THIS file, binding one on first call
+* (see bindRequire). Cached across calls; undefined off Node / in browsers.
 *
-* Returns `false` in browser / non-CJS environments where `require` is
-* undefined — no `node:` modules are built-in there.
+* For builtins and bare packages only — the resolution base is this file, so a
+* relative specifier would resolve from `src/node/`. Use `requireFrom` for
+* relative loads.
+*/
+function getRequire() {
+	if (cachedRequire === void 0) cachedRequire = bindRequire();
+	return cachedRequire;
+}
+/**
+* Is `name` a Node built-in module? Resolved from the statically-imported
+* `isBuiltin`, so it works on Node and on ahead-of-time-compiled binaries
+* (Perry), where ambient `require('module')` would lack `isBuiltin`. Returns
+* false in browsers, where the bare `module` import is stubbed away.
 *
 * Single source of truth for "is this a Node builtin?" probes across socket-lib
-* (used by the smol-binding loaders to gate `require('node:smol-*')`).
+* (used by the smol-binding loaders to gate their `node:smol-*` loads).
 */
-let cachedIsBuiltin;
 function isNodeBuiltin(name) {
-	if (!require_constants_runtime.IS_NODE) return false;
-	return (cachedIsBuiltin ??= getNodeModule().isBuiltin)(name);
+	if (!require_constants_runtime.IS_NODE || typeof module$1.isBuiltin !== "function") return false;
+	return (0, module$1.isBuiltin)(name);
+}
+/**
+* Load a built-in module by *computed* specifier through the bound `require`
+* (see getRequire). The specifier is a parameter — never a literal at the call
+* site — so browser bundlers neither walk nor bundle it. Returns undefined
+* where no `require` can be bound.
+*
+* Builtins / bare packages only (dir-independent); for a relative specifier use
+* `requireFrom`. Used by `getNodeModule` for `node:module`, and by the
+* smol-binding loaders for the optional `node:smol-*` native bindings (gated
+* behind `isNodeBuiltin`, true only on socket-btm's smol Node binary).
+*/
+function requireBuiltin(specifier) {
+	const req = getRequire();
+	if (req) return req(specifier);
+}
+/**
+* Load a module by specifier from a CALLER-supplied base (its
+* `import.meta.url`). Use this for RELATIVE specifiers (`./x`, `../y`), whose
+* resolution depends on the caller's directory — `requireBuiltin` binds to this
+* file and would resolve them from `src/node/`. Not cached: the binding is
+* per-caller. Returns undefined where no `require` can be bound.
+*/
+function requireFrom(fromUrl, specifier) {
+	const req = bindRequire(fromUrl);
+	if (req) return req(specifier);
 }
 
 //#endregion
+exports.bindRequire = bindRequire;
 exports.getNodeModule = getNodeModule;
-exports.isNodeBuiltin = isNodeBuiltin;
+exports.getRequire = getRequire;
+exports.isNodeBuiltin = isNodeBuiltin;
+exports.requireBuiltin = requireBuiltin;
+exports.requireFrom = requireFrom;

package/dist/node/timers-promises.d.ts

@@ -3,4 +3,7 @@
  *   rationale shared across all `node/*.ts` lazy-loaders.
  */
 import type * as NodeTimersPromises from 'node:timers/promises';
+/**
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
 export declare function getNodeTimersPromises(): typeof NodeTimersPromises;

package/dist/node/timers-promises.js

@@ -5,6 +5,9 @@ const require_constants_runtime = require('../constants/runtime.js');
 
 //#region src/node/timers-promises.ts
 let timersPromises;
+/**
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
 function getNodeTimersPromises() {
 	if (!require_constants_runtime.IS_NODE) return;
 	return timersPromises ??= /*@__PURE__*/ require("timers/promises");

package/dist/node/url.d.ts

@@ -3,4 +3,7 @@
  *   shared across all `node/*.ts` lazy-loaders.
  */
 import type * as NodeUrl from 'node:url';
+/**
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
 export declare function getNodeUrl(): typeof NodeUrl;

package/dist/node/url.js

@@ -5,6 +5,9 @@ const require_constants_runtime = require('../constants/runtime.js');
 
 //#region src/node/url.ts
 let cachedUrl;
+/**
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
 function getNodeUrl() {
 	if (!require_constants_runtime.IS_NODE) return;
 	return cachedUrl ??= /*@__PURE__*/ require("url");

package/dist/npm/meta-cache.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @file Cached packument fetch — `getPackumentSlim` wires the pure slicer
+ *   (`./meta-slice`) to an injectable HTTP adapter and the repo's
+ *   `createTtlCache` (memo + cacache persistence + in-flight dedupe via
+ *   `getOrFetch`). Every `getPackumentSlim`-backed cache is actually three
+ *   `TtlCache` instances sharing one cacache directory (`getCachePeers`): the
+ *   primary cache (the object callers hold), a persisted long-TTL last
+ *   known-good store (`-stale` prefix, `STALE_TTL_MS`), and a short-TTL
+ *   storm-control marker (`-storm` prefix, `STALE_SERVE_TTL_MS`). Three
+ *   failure-handling policies layer on top:
+ *
+ *   - **`force`** bypasses a cached entry EXCEPT when it was written within the
+ *     last 30 seconds, so a burst of forced refreshes coalesces into one
+ *     upstream fetch instead of hammering the registry. A forced refresh NEVER
+ *     removes the existing entry before fetching — on failure, whatever was
+ *     cached before the call is untouched, and serve-stale-on-error (below)
+ *     still has the persisted last-known-good value to fall back on.
+ *   - **Negative caching** is narrow and short: only a definitive HTTP 404
+ *     (package/version genuinely absent) is cached, for `NEGATIVE_TTL_MS`, and
+ *     only when the persisted stale store holds no known-good data for that
+ *     key. A transient error (network failure, 5xx) is NEVER negative-cached,
+ *     and a still-fresh negative entry is discarded rather than trusted the
+ *     moment known-good data exists in the persisted stale store — a retry
+ *     always outranks a cached "not found" over real data.
+ *   - **Serve-stale-on-error**: every successful fetch also persists the
+ *     `PackumentMetaSlim` to the stale store, independent of the primary
+ *     entry's own TTL — `STALE_TTL_MS` (7 days) comfortably outlives it, so the
+ *     value survives both the primary entry's expiry and a process restart. If
+ *     a later refresh fails for ANY reason — including a fresh 404 — the
+ *     persisted value is served instead of propagating the error, and the
+ *     storm-control marker is (re)written so a burst of callers within
+ *     `STALE_SERVE_TTL_MS` is served without re-hitting a registry that just
+ *     failed. ETag revalidation requires a header-capable HTTP adapter; the
+ *     current `NpmMetaHttpAdapter` is header-less by design so test doubles and
+ *     `httpJson` stay interchangeable with the rest of the npm client surface —
+ *     see `NpmMetaHttpAdapter`.
+ */
+import type { GetPackumentSlimOptions, NpmMetaHttpAdapter, PackumentMetaSlim, PackumentVariant } from './meta-types';
+import type { TtlCache, TtlCacheOptions } from '../cache/ttl/types';
+/**
+ * A cached, successfully-fetched packument.
+ */
+export interface CachedPackumentHit {
+    cachedAt: number;
+    kind: 'hit';
+    meta: PackumentMetaSlim;
+}
+/**
+ * A cached definitive-404 result — narrow and short-lived (`NEGATIVE_TTL_MS`);
+ * see the file-level doc for when this is written.
+ */
+export interface CachedPackumentMiss {
+    cachedAt: number;
+    kind: 'miss';
+    status: number;
+}
+/**
+ * The value shape stored per cache key — either a successful fetch or a
+ * short-lived negative (404) result.
+ */
+export type CachedPackumentEntry = CachedPackumentHit | CachedPackumentMiss;
+/**
+ * Thrown by `getPackumentSlim` (and the `getVersions` / `getLatestVersion`
+ * exact-version / dist-tag lookups) when a specific package, version, or tag
+ * is definitively absent. Carries `status` so `extractHttpStatus` reports it
+ * the same way as a real `HttpResponseError`.
+ */
+export declare class PackumentNotFoundError extends Error {
+    packageName: string;
+    status: number;
+    constructor(packageName: string, status: number, message?: string | undefined);
+}
+/**
+ * Build the cache key for one (registry, name, variant) tuple. Normalizes
+ * `registry` first (`normalizeRegistryUrl`) so two spellings of the same
+ * registry collapse to one key.
+ */
+export declare function buildMetaCacheKey(registry: string, name: string, variant: PackumentVariant): string;
+/**
+ * Deep-clone a `PackumentMetaSlim` via a JSON round-trip — plain
+ * JSON-roundtrippable data (strings, numbers, booleans, records), so this is
+ * 3-5x faster than `structuredClone` and avoids the HTML structured-clone
+ * algorithm entirely. Used at every public read boundary so no two callers
+ * ever hold a reference to the same cached object.
+ */
+export declare function cloneMeta(meta: PackumentMetaSlim): PackumentMetaSlim;
+/**
+ * Companion long-TTL (persisted stale) and short-TTL (storm-control) caches
+ * that back one primary `TtlCache` instance — see the file-level doc.
+ */
+export interface NpmMetaCachePeers {
+    stale: TtlCache;
+    storm: TtlCache;
+}
+/**
+ * Create a dedicated npm-meta cache instance — same `prefix` /
+ * default-`ttl` as the module singleton, overridable per-call. Use this (vs.
+ * the default singleton) for test isolation or a non-default TTL. Also
+ * creates and registers this instance's persisted-stale + storm-control
+ * companions (`registerCachePeers`).
+ */
+export declare function createNpmMetaCache(options?: TtlCacheOptions | undefined): TtlCache;
+/**
+ * The uncached fetch attempt for one packument, run through the negative-cache
+ * decision: on success, persists the result to `staleCache` and returns a
+ * `hit`; on a definitive 404 with no persisted stale data, returns a `miss`
+ * (a normal, non-throwing outcome the caller decides how to cache); any other
+ * failure (transient error, or a 404 when stale data DOES exist) rethrows so
+ * the caller's serve-stale-on-error path can take over.
+ */
+export declare function fetchAndCacheEntry(name: string, key: string, fetchOptions: ResolvedPackumentFetchOptions, staleCache: TtlCache): Promise<CachedPackumentEntry>;
+/**
+ * `GetPackumentSlimOptions` with every field the fetch path needs resolved to
+ * a concrete value (defaults applied) — the shape `fetchPackumentSlim` and
+ * `getPackumentSlim`'s cache-key logic operate on internally.
+ */
+export interface ResolvedPackumentFetchOptions {
+    http: NpmMetaHttpAdapter;
+    registry: string;
+    retries: number;
+    timeout?: number | undefined;
+    variant: PackumentVariant;
+}
+/**
+ * The uncached fetch — GET the packument with the variant's `Accept` header
+ * and slice it. Split out so `getPackumentSlim`'s cache-key / force logic
+ * stays readable. Throws (never negative-caches itself — that decision is
+ * `getPackumentSlim`'s, which has the context to know whether stale data
+ * already exists for this key).
+ */
+export declare function fetchPackumentSlim(name: string, resolved: ResolvedPackumentFetchOptions): Promise<PackumentMetaSlim>;
+/**
+ * Resolve the persisted-stale + storm-control companions for a primary cache
+ * instance, creating them lazily (under the default prefix) for a `TtlCache`
+ * that wasn't created via `createNpmMetaCache`.
+ */
+export declare function getCachePeers(cache: TtlCache): NpmMetaCachePeers;
+/**
+ * The module-level default cache instance, created lazily on first use.
+ */
+export declare function getDefaultMetaCache(): TtlCache;
+/**
+ * Fetch a package's packument, slice it down to `PackumentMetaSlim`, and
+ * cache the result. Concurrent calls for the same (registry, name, variant)
+ * dedupe to a single upstream request via the cache's `getOrFetch`. See the
+ * file-level doc for the `force` / negative-cache / serve-stale-on-error
+ * policies.
+ *
+ * @throws {PackumentNotFoundError} When the registry returns a definitive 404
+ *   and no previously-good data exists for this key to serve instead.
+ */
+export declare function getPackumentSlim(name: string, options?: GetPackumentSlimOptions | undefined): Promise<PackumentMetaSlim>;
+/**
+ * Look up the persisted last known-good value for `key`, if any — backed by
+ * `STALE_TTL_MS` (7 days), independent of the primary cache's own TTL, and
+ * readable from a fresh process. Returns a fresh clone so no two callers ever
+ * share a reference to the same cached object.
+ */
+export declare function getStaleMeta(cache: TtlCache, key: string): Promise<PackumentMetaSlim | undefined>;
+/**
+ * Normalize a registry base URL so two spellings of the same registry
+ * collapse to one cache key and one request URL: lowercase the scheme+host,
+ * and ensure exactly one trailing slash. Falls back to the input unchanged
+ * when it isn't a parseable absolute URL.
+ */
+export declare function normalizeRegistryUrl(registry: string): string;
+/**
+ * Create and register the persisted-stale + storm-control companion caches
+ * for `cache` under `prefix`.
+ */
+export declare function registerCachePeers(cache: TtlCache, prefix: string): NpmMetaCachePeers;
+/**
+ * Persist `meta` as the last known-good value for `key`, independent of the
+ * primary entry's own TTL/expiry.
+ */
+export declare function rememberStaleMeta(cache: TtlCache, key: string, meta: PackumentMetaSlim): Promise<void>;
+/**
+ * Serve-stale-on-error: look up the persisted last known-good value and, when
+ * found, (re)write the storm-control marker so a burst of callers within
+ * `STALE_SERVE_TTL_MS` is served without re-hitting a registry that just
+ * failed.
+ */
+export declare function serveStaleOnFailure(staleCache: TtlCache, stormCache: TtlCache, key: string): Promise<PackumentMetaSlim | undefined>;