@veryfront/ext-content-mdx 0.1.985

package/esm/src/utils/logger/redact.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Secret / credential redaction for structured log context.
+ *
+ * Defense-in-depth (#1989): the logger, the error-logging path, and the
+ * observability log buffer all accept arbitrary `context`/`data` objects from
+ * callers and serialize them to log sinks. There is no guarantee a caller
+ * never hands us a tokens object, an `Authorization` header bag, or a request
+ * body with a password field. This pass masks values whose *key* looks like a
+ * credential before serialization, so an accidental
+ * `logger.info("...", { authorization: token })` cannot leak the secret.
+ *
+ * Scope is intentionally key-based: we do not attempt to find secrets embedded
+ * in free-form message strings (too lossy). The deny-list errs toward
+ * over-redaction — masking a benign `tokenCount` is acceptable; leaking a real
+ * token is not. The traversal fails *closed*: on a cycle, depth overflow, or a
+ * throwing getter it returns {@link REDACTED} rather than risk emitting an
+ * unredacted object.
+ */
+/** Replacement value substituted for any sensitive field. */
+export declare const REDACTED = "[REDACTED]";
+/**
+ * Whether a context key names a credential and should have its value masked.
+ *
+ * Uses substring matching on a normalized key, so `clientSecret`,
+ * `x-api-key`, and `refresh_token` all match while benign words that merely
+ * *contain* a pattern as a separate token (e.g. `author`) do not — `author`
+ * normalizes to `author`, which contains none of the patterns.
+ */
+export declare function isSensitiveKey(key: string): boolean;
+/**
+ * Returns a redacted deep copy of `context`. Any property whose key is
+ * {@link isSensitiveKey} has its value replaced with {@link REDACTED}; nested
+ * plain objects, class instances, and arrays are traversed. The input is never
+ * mutated, and the pass fails closed (returns {@link REDACTED}) on cycles,
+ * depth overflow, or a throwing getter.
+ */
+export declare function redactSensitive<T>(context: T): T;
+/**
+ * Strip credentials from URL-shaped strings so they can be safely emitted in
+ * free-form text (error messages, stacks, lifted `request_url` fields). Unlike
+ * {@link redactSensitive}, which is key-based, this scrubs secrets embedded in
+ * the *value* itself:
+ *
+ * - URL userinfo: `http://user:pass@host` → `http://user:[REDACTED]@host`
+ * - sensitive query params: `?access_token=abc` → `?access_token=[REDACTED]`
+ *
+ * It is intentionally tolerant: it operates on any string (a DSN, a Mongo URI,
+ * an axios error message containing a URL) via regex rather than requiring a
+ * parseable URL, so malformed or partial URLs in error text are still scrubbed.
+ * Non-URL strings pass through unchanged.
+ */
+export declare function sanitizeUrlCredentials(input: string): string;
+/**
+ * Return the URL form safe to attach to observability span attributes.
+ *
+ * Span attributes bypass the logger's structured redaction pass, so `http.url`
+ * must not include query strings, fragments, or URL userinfo. This intentionally
+ * strips every query parameter instead of selectively redacting credential-like
+ * names because cache keys and callback state can be sensitive even when the
+ * parameter name is not obviously a credential.
+ */
+export declare function sanitizeUrlForSpan(input: string): string;
+/**
+ * Apply {@link sanitizeUrlCredentials} to the `message` and `stack` of a
+ * serialized-error-shaped object, returning a new object. Used by the logger's
+ * JSON and text paths so errors carrying DSNs, Mongo URIs, or
+ * `?access_token=`-bearing URLs do not leak credentials (the serialized error
+ * bypasses the key-based redactor). Returns the input unchanged when falsy.
+ */
+export declare function sanitizeSerializedError<T extends {
+    message?: unknown;
+    stack?: unknown;
+} | undefined>(error: T): T;
+//# sourceMappingURL=redact.d.ts.map

package/esm/src/utils/logger/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../../src/src/utils/logger/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,6DAA6D;AAC7D,eAAO,MAAM,QAAQ,eAAe,CAAC;AA8CrC;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAcnD;AA6ED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAEhD;AA2BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA4B5D;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgBxD;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,CAAC,SAAS;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,EAC5D,KAAK,EAAE,CAAC,GAAG,CAAC,CAMb"}

package/esm/src/utils/logger/redact.js

@@ -0,0 +1,294 @@
+/**
+ * Secret / credential redaction for structured log context.
+ *
+ * Defense-in-depth (#1989): the logger, the error-logging path, and the
+ * observability log buffer all accept arbitrary `context`/`data` objects from
+ * callers and serialize them to log sinks. There is no guarantee a caller
+ * never hands us a tokens object, an `Authorization` header bag, or a request
+ * body with a password field. This pass masks values whose *key* looks like a
+ * credential before serialization, so an accidental
+ * `logger.info("...", { authorization: token })` cannot leak the secret.
+ *
+ * Scope is intentionally key-based: we do not attempt to find secrets embedded
+ * in free-form message strings (too lossy). The deny-list errs toward
+ * over-redaction — masking a benign `tokenCount` is acceptable; leaking a real
+ * token is not. The traversal fails *closed*: on a cycle, depth overflow, or a
+ * throwing getter it returns {@link REDACTED} rather than risk emitting an
+ * unredacted object.
+ */
+import { isRecord } from "./core.js";
+/** Replacement value substituted for any sensitive field. */
+export const REDACTED = "[REDACTED]";
+/**
+ * Normalized substrings that mark a key as sensitive. Matching is done against
+ * a lowercased, non-alphanumeric-stripped form of the key, so `API-Key`,
+ * `api_key`, and `apiKey` all collapse to `apikey` and match.
+ *
+ * Deliberately omitted to avoid false positives that swamp real logs:
+ * - bare `"auth"` (would mask `author`); `authorization`/`authToken` are still
+ *   covered via `authorization`/`token`.
+ * - short tokens like `"dsn"`/`"sas"` (would mask `feedsNamespace`, etc.).
+ */
+const SENSITIVE_KEY_PATTERNS = [
+    "password",
+    "passwd",
+    "pwd",
+    "passphrase",
+    "secret",
+    "clientsecret",
+    "token",
+    "apikey",
+    "accesskey",
+    "privatekey",
+    "credential",
+    "authorization",
+    "cookie",
+    "bearer",
+    "jwt",
+    "connectionstring",
+    "signature",
+    "sessionid",
+    "sid",
+    "otp",
+    "mfa",
+    "pin",
+    "salt",
+    "xsrf",
+    "csrf",
+];
+const SENSITIVE_KEY_CACHE_MAX_SIZE = 512;
+const sensitiveKeyCache = new Map();
+/** Stop traversing past this depth to keep the pass cheap and stack-safe. */
+const MAX_DEPTH = 16;
+/**
+ * Whether a context key names a credential and should have its value masked.
+ *
+ * Uses substring matching on a normalized key, so `clientSecret`,
+ * `x-api-key`, and `refresh_token` all match while benign words that merely
+ * *contain* a pattern as a separate token (e.g. `author`) do not — `author`
+ * normalizes to `author`, which contains none of the patterns.
+ */
+export function isSensitiveKey(key) {
+    const cached = sensitiveKeyCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const sensitive = SENSITIVE_KEY_PATTERNS.some((pattern) => normalized.includes(pattern));
+    if (sensitiveKeyCache.size >= SENSITIVE_KEY_CACHE_MAX_SIZE) {
+        const oldestKey = sensitiveKeyCache.keys().next().value;
+        if (oldestKey !== undefined)
+            sensitiveKeyCache.delete(oldestKey);
+    }
+    sensitiveKeyCache.set(key, sensitive);
+    return sensitive;
+}
+/**
+ * A non-null, non-array object. {@link isRecord} covers class instances too,
+ * whose enumerable fields `JSON.stringify` *would* serialize, so we must
+ * traverse them to catch secrets.
+ */
+function isTraversableRecord(value) {
+    return isRecord(value);
+}
+function hasToJson(value) {
+    return typeof value.toJSON === "function";
+}
+function redactValue(value, depth, seen) {
+    if (Array.isArray(value)) {
+        if (depth >= MAX_DEPTH || seen.has(value))
+            return REDACTED;
+        seen.add(value);
+        try {
+            return value.map((item) => redactValue(item, depth + 1, seen));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    // Objects defining `toJSON` (Date, URL, custom serializers) are serialized
+    // by `JSON.stringify` via the *return value* of `toJSON`, not their own
+    // enumerable keys. A key-based pass over the object's own properties would
+    // therefore miss credentials smuggled through `toJSON`, e.g.
+    // `{ toJSON: () => ({ apiKey: "sk-..." }) }` (CODEX P2). When `toJSON`
+    // returns a non-scalar (an object/array that could carry credential keys),
+    // redact *that* — the thing actually emitted. When it returns a scalar
+    // (Date/URL → ISO string), the original object is left intact, preserving
+    // prior behavior and identity.
+    if (isRecord(value) && hasToJson(value)) {
+        if (depth >= MAX_DEPTH || seen.has(value))
+            return REDACTED;
+        seen.add(value);
+        try {
+            const serialized = value.toJSON();
+            if (isRecord(serialized) || Array.isArray(serialized)) {
+                return redactValue(serialized, depth + 1, seen);
+            }
+            // Scalar result (string/number/…): the object serializes safely as-is.
+            return value;
+        }
+        catch {
+            // A throwing toJSON must never let the raw object (whose own keys we
+            // skipped) through: fail closed.
+            return REDACTED;
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    if (isTraversableRecord(value)) {
+        if (depth >= MAX_DEPTH || seen.has(value))
+            return REDACTED;
+        seen.add(value);
+        try {
+            const out = {};
+            for (const [key, child] of Object.entries(value)) {
+                out[key] = isSensitiveKey(key) ? REDACTED : redactValue(child, depth + 1, seen);
+            }
+            return out;
+        }
+        catch {
+            // A throwing getter (or other access error) must never let an
+            // unredacted object through: fail closed.
+            return REDACTED;
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    // Primitives and scalar-serializing objects (Date, URL, …) are returned
+    // untouched: they are not key/value bags we can safely rewrite.
+    return value;
+}
+/**
+ * Returns a redacted deep copy of `context`. Any property whose key is
+ * {@link isSensitiveKey} has its value replaced with {@link REDACTED}; nested
+ * plain objects, class instances, and arrays are traversed. The input is never
+ * mutated, and the pass fails closed (returns {@link REDACTED}) on cycles,
+ * depth overflow, or a throwing getter.
+ */
+export function redactSensitive(context) {
+    return redactValue(context, 0, new Set());
+}
+/**
+ * Query-string parameter names that commonly carry credentials in URLs.
+ * Matched case-insensitively against the parameter name.
+ */
+const SENSITIVE_URL_PARAMS = [
+    "access_token",
+    "accesstoken",
+    "refresh_token",
+    "api_key",
+    "apikey",
+    "code",
+    "token",
+    "secret",
+    "client_secret",
+    "password",
+    "passwd",
+    "pwd",
+    "state",
+    "sig",
+    "signature",
+    "auth",
+];
+const URL_USERINFO_RE = /(\b[a-z][a-z0-9+.-]*:\/\/)([^/?#@\s]+)@/gi;
+/**
+ * Strip credentials from URL-shaped strings so they can be safely emitted in
+ * free-form text (error messages, stacks, lifted `request_url` fields). Unlike
+ * {@link redactSensitive}, which is key-based, this scrubs secrets embedded in
+ * the *value* itself:
+ *
+ * - URL userinfo: `http://user:pass@host` → `http://user:[REDACTED]@host`
+ * - sensitive query params: `?access_token=abc` → `?access_token=[REDACTED]`
+ *
+ * It is intentionally tolerant: it operates on any string (a DSN, a Mongo URI,
+ * an axios error message containing a URL) via regex rather than requiring a
+ * parseable URL, so malformed or partial URLs in error text are still scrubbed.
+ * Non-URL strings pass through unchanged.
+ */
+export function sanitizeUrlCredentials(input) {
+    if (typeof input !== "string" || input.length === 0)
+        return input;
+    // 1) userinfo: scheme://user:pass@  → mask the password (and any bare creds).
+    let out = input.replace(URL_USERINFO_RE, (_match, scheme, userinfo) => {
+        const colon = userinfo.indexOf(":");
+        if (colon === -1) {
+            // `scheme://token@host` — the whole userinfo is credential-like.
+            return `${scheme}${REDACTED}@`;
+        }
+        const user = userinfo.slice(0, colon);
+        return `${scheme}${user}:${REDACTED}@`;
+    });
+    // 2) sensitive query/fragment params: `key=value` → `key=[REDACTED]`.
+    // Match `?key=`, `&key=`, `;key=` separators and stop at the next delimiter.
+    out = out.replace(/([?&;])([a-z0-9_.\-]+)=([^&#;\s]*)/gi, (match, sep, key, _val) => {
+        const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+        const sensitive = SENSITIVE_URL_PARAMS.some((p) => normalized === p.replace(/[^a-z0-9]/g, ""));
+        return sensitive ? `${sep}${key}=${REDACTED}` : match;
+    });
+    return out;
+}
+function firstUrlDelimiterIndex(input) {
+    const queryIndex = input.indexOf("?");
+    const hashIndex = input.indexOf("#");
+    if (queryIndex === -1)
+        return hashIndex;
+    if (hashIndex === -1)
+        return queryIndex;
+    return Math.min(queryIndex, hashIndex);
+}
+function sanitizeProtocolRelativeUrlForSpan(input) {
+    if (!input.startsWith("//"))
+        return null;
+    try {
+        const url = new URL(`https:${input}`);
+        return `//${url.host}${url.pathname}`;
+    }
+    catch (_) {
+        return null;
+    }
+}
+/**
+ * Return the URL form safe to attach to observability span attributes.
+ *
+ * Span attributes bypass the logger's structured redaction pass, so `http.url`
+ * must not include query strings, fragments, or URL userinfo. This intentionally
+ * strips every query parameter instead of selectively redacting credential-like
+ * names because cache keys and callback state can be sensitive even when the
+ * parameter name is not obviously a credential.
+ */
+export function sanitizeUrlForSpan(input) {
+    if (typeof input !== "string" || input.length === 0)
+        return input;
+    try {
+        const url = new URL(input);
+        if (url.origin !== "null")
+            return `${url.origin}${url.pathname}`;
+    }
+    catch (_) {
+        // Relative or malformed URL-shaped strings are handled by the fallback.
+    }
+    const delimiterIndex = firstUrlDelimiterIndex(input);
+    const withoutQueryOrFragment = delimiterIndex === -1 ? input : input.slice(0, delimiterIndex);
+    const protocolRelativeUrl = sanitizeProtocolRelativeUrlForSpan(withoutQueryOrFragment);
+    if (protocolRelativeUrl)
+        return protocolRelativeUrl;
+    return sanitizeUrlCredentials(withoutQueryOrFragment);
+}
+/**
+ * Apply {@link sanitizeUrlCredentials} to the `message` and `stack` of a
+ * serialized-error-shaped object, returning a new object. Used by the logger's
+ * JSON and text paths so errors carrying DSNs, Mongo URIs, or
+ * `?access_token=`-bearing URLs do not leak credentials (the serialized error
+ * bypasses the key-based redactor). Returns the input unchanged when falsy.
+ */
+export function sanitizeSerializedError(error) {
+    if (!error)
+        return error;
+    const out = { ...error };
+    if (typeof out.message === "string")
+        out.message = sanitizeUrlCredentials(out.message);
+    if (typeof out.stack === "string")
+        out.stack = sanitizeUrlCredentials(out.stack);
+    return out;
+}

package/esm/src/utils/logger/request-context.d.ts

@@ -0,0 +1,27 @@
+/**************************
+ * Request Context Store
+ *
+ * Uses AsyncLocalStorage to propagate request-scoped logger context
+ * throughout the call stack without explicit parameter passing.
+ *
+ * @module utils/logger/request-context
+ **************************/
+import { AsyncLocalStorage } from "node:async_hooks";
+import { type Logger } from "./logger.js";
+/** Context for request. */
+export interface RequestContext {
+    logger: Logger;
+    requestId: string;
+    projectSlug?: string;
+    projectId?: string;
+    domain?: string;
+    userId?: string;
+    conversationId?: string;
+}
+export declare const requestContextStore: AsyncLocalStorage<RequestContext>;
+export declare function getRequestContext(): RequestContext | undefined;
+export declare function getRequestLogger(): Logger | undefined;
+export declare function runWithRequestContext<T>(context: RequestContext, fn: () => T): T;
+/** Run with request context async. */
+export declare function runWithRequestContextAsync<T>(context: RequestContext, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=request-context.d.ts.map

package/esm/src/utils/logger/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../../../src/src/utils/logger/request-context.ts"],"names":[],"mappings":"AAAA;;;;;;;4BAO4B;AAE5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAkC,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1E,2BAA2B;AAC3B,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,mBAAmB,mCAA0C,CAAC;AAE3E,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAErD;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEhF;AAED,sCAAsC;AACtC,wBAAgB,0BAA0B,CAAC,CAAC,EAC1C,OAAO,EAAE,cAAc,EACvB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ"}

package/esm/src/utils/logger/request-context.js

@@ -0,0 +1,28 @@
+/**************************
+ * Request Context Store
+ *
+ * Uses AsyncLocalStorage to propagate request-scoped logger context
+ * throughout the call stack without explicit parameter passing.
+ *
+ * @module utils/logger/request-context
+ **************************/
+import { AsyncLocalStorage } from "node:async_hooks";
+import { __registerRequestContextGetter } from "./logger.js";
+export const requestContextStore = new AsyncLocalStorage();
+export function getRequestContext() {
+    return requestContextStore.getStore();
+}
+export function getRequestLogger() {
+    return getRequestContext()?.logger;
+}
+export function runWithRequestContext(context, fn) {
+    return requestContextStore.run(context, fn);
+}
+/** Run with request context async. */
+export function runWithRequestContextAsync(context, fn) {
+    return requestContextStore.run(context, fn);
+}
+// Register the context getter with the logger module.
+// This allows context-aware loggers to access request context
+// without creating a circular dependency.
+__registerRequestContextGetter(getRequestContext);

package/esm/src/utils/memoize.d.ts

@@ -0,0 +1,19 @@
+/** Implement memo cache. */
+export declare class MemoCache<V> {
+    private cache;
+    get(key: string): V | undefined;
+    set(key: string, value: V): void;
+    has(key: string): boolean;
+    clear(): void;
+    size(): number;
+}
+/** Memoize async. */
+export declare function memoizeAsync<Args extends unknown[], Result>(fn: (...args: Args) => Promise<Result>, keyHasher: (...args: Args) => string): (...args: Args) => Promise<Result>;
+/** Memoize. */
+export declare function memoize<Args extends unknown[], Result>(fn: (...args: Args) => Result, keyHasher: (...args: Args) => string): (...args: Args) => Result;
+/**
+ * FNV-1a hash algorithm for fast cache key generation.
+ * 10-15x faster than JSON.stringify() and uses 70-80% less memory.
+ */
+export declare function simpleHash(...values: unknown[]): string;
+//# sourceMappingURL=memoize.d.ts.map

package/esm/src/utils/memoize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoize.d.ts","sourceRoot":"","sources":["../../../src/src/utils/memoize.ts"],"names":[],"mappings":"AAGA,4BAA4B;AAC5B,qBAAa,SAAS,CAAC,CAAC;IACtB,OAAO,CAAC,KAAK,CAAwB;IAErC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAI/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAIhC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,MAAM;CAGf;AA2CD,qBAAqB;AACrB,wBAAgB,YAAY,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACzD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,EACtC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,GACnC,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAEpC;AAED,eAAe;AACf,wBAAgB,OAAO,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACpD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,EAC7B,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,GACnC,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAE3B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAavD"}

package/esm/src/utils/memoize.js

@@ -0,0 +1,72 @@
+import { FNV1A_PRIME_32 } from "./constants/crypto.js";
+import { HASH_SEED_FNV1A } from "./constants/hash.js";
+/** Implement memo cache. */
+export class MemoCache {
+    cache = new Map();
+    get(key) {
+        return this.cache.get(key);
+    }
+    set(key, value) {
+        this.cache.set(key, value);
+    }
+    has(key) {
+        return this.cache.has(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size;
+    }
+}
+function memoizeWithCache(fn, keyHasher) {
+    const cache = new MemoCache();
+    const inflight = new Map();
+    return (...args) => {
+        const key = keyHasher(...args);
+        if (cache.has(key)) {
+            return cache.get(key);
+        }
+        const existing = inflight.get(key);
+        if (existing)
+            return existing;
+        const result = fn(...args);
+        if (!(result instanceof Promise)) {
+            cache.set(key, result);
+            return result;
+        }
+        const promise = result.then((resolved) => {
+            cache.set(key, resolved);
+            inflight.delete(key);
+            return resolved;
+        }, (error) => {
+            inflight.delete(key);
+            throw error;
+        });
+        inflight.set(key, promise);
+        return promise;
+    };
+}
+/** Memoize async. */
+export function memoizeAsync(fn, keyHasher) {
+    return memoizeWithCache(fn, keyHasher);
+}
+/** Memoize. */
+export function memoize(fn, keyHasher) {
+    return memoizeWithCache(fn, keyHasher);
+}
+/**
+ * FNV-1a hash algorithm for fast cache key generation.
+ * 10-15x faster than JSON.stringify() and uses 70-80% less memory.
+ */
+export function simpleHash(...values) {
+    let hash = HASH_SEED_FNV1A;
+    for (const value of values) {
+        const str = typeof value === "string" ? value : String(value);
+        for (let i = 0; i < str.length; i++) {
+            hash ^= str.charCodeAt(i);
+            hash = Math.imul(hash, FNV1A_PRIME_32);
+        }
+    }
+    return (hash >>> 0).toString(36);
+}

package/esm/src/utils/parallel.d.ts

@@ -0,0 +1,25 @@
+/*******************************
+ * Parallel Execution Utilities
+ *
+ * Provides utilities for parallel execution with concurrency control.
+ * Uses a semaphore to limit the number of concurrent operations.
+ *
+ * @module core/utils/parallel
+ *******************************/
+import { Semaphore } from "../modules/react-loader/ssr-module-loader/concurrency/semaphore.js";
+type ParallelOptions = {
+    concurrency?: number;
+    semaphore?: Semaphore;
+    timeoutMs?: number;
+};
+/** Run parallel map. */
+export declare function parallelMap<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, options?: ParallelOptions): Promise<R[]>;
+export declare function parallelAll<T extends readonly (() => Promise<unknown>)[]>(fns: T, options?: ParallelOptions): Promise<{
+    [K in keyof T]: Awaited<ReturnType<T[K]>>;
+}>;
+export declare function parallelFind<T>(items: T[], predicate: (item: T, index: number) => Promise<boolean>, options?: ParallelOptions): Promise<T | undefined>;
+export declare function parallelFilter<T>(items: T[], predicate: (item: T, index: number) => Promise<boolean>, options?: ParallelOptions): Promise<T[]>;
+export declare function createSemaphore(permits: number): Semaphore;
+export declare function getApiSemaphore(): Semaphore;
+export {};
+//# sourceMappingURL=parallel.d.ts.map

package/esm/src/utils/parallel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../../src/src/utils/parallel.ts"],"names":[],"mappings":"AAAA;;;;;;;iCAOiC;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,oEAAoE,CAAC;AAY/F,KAAK,eAAe,GAAG;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAgBF,wBAAwB;AACxB,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAC9B,KAAK,EAAE,CAAC,EAAE,EACV,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,CAAC,EAAE,CAAC,CA4Bd;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,EACvE,GAAG,EAAE,CAAC,EACN,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,CAMxD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EACvD,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAkCxB;AAED,wBAAgB,cAAc,CAAC,CAAC,EAC9B,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EACvD,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,CAAC,EAAE,CAAC,CAcd;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAE1D;AAED,wBAAgB,eAAe,IAAI,SAAS,CAE3C"}

package/esm/src/utils/parallel.js

@@ -0,0 +1,91 @@
+/*******************************
+ * Parallel Execution Utilities
+ *
+ * Provides utilities for parallel execution with concurrency control.
+ * Uses a semaphore to limit the number of concurrent operations.
+ *
+ * @module core/utils/parallel
+ *******************************/
+import { Semaphore } from "../modules/react-loader/ssr-module-loader/concurrency/semaphore.js";
+import { withSpan } from "../observability/tracing/otlp-setup.js";
+import { TIMEOUT_ERROR } from "../errors/error-registry.js";
+const DEFAULT_CONCURRENCY = 20;
+const ACQUIRE_TIMEOUT_MS = 30_000;
+// No maxQueueSize — parallelMap schedules all items via Promise.all,
+// so a queue cap would reject items in large batches instead of letting
+// them progress under the concurrency limit with timeout-based backpressure.
+const apiSemaphore = new Semaphore(DEFAULT_CONCURRENCY);
+async function acquireOrThrow(semaphore, timeoutMs, label) {
+    const acquired = await semaphore.tryAcquire(timeoutMs);
+    if (acquired)
+        return;
+    throw TIMEOUT_ERROR.create({
+        detail: `${label}: timed out waiting for semaphore after ${timeoutMs}ms (available: ${semaphore.available}, waiting: ${semaphore.waiting})`,
+    });
+}
+/** Run parallel map. */
+export function parallelMap(items, fn, options = {}) {
+    return withSpan("utils.parallelMap", async () => {
+        if (items.length === 0)
+            return [];
+        const semaphore = options.semaphore ?? apiSemaphore;
+        const timeoutMs = options.timeoutMs ?? ACQUIRE_TIMEOUT_MS;
+        const results = new Array(items.length);
+        await Promise.all(items.map(async (item, index) => {
+            await acquireOrThrow(semaphore, timeoutMs, "parallelMap");
+            try {
+                results[index] = await fn(item, index);
+            }
+            finally {
+                semaphore.release();
+            }
+        }));
+        return results;
+    }, {
+        "parallel.itemCount": items.length,
+        "parallel.timeoutMs": options.timeoutMs ?? ACQUIRE_TIMEOUT_MS,
+    });
+}
+export function parallelAll(fns, options = {}) {
+    return parallelMap([...fns], (fn) => fn(), options);
+}
+export function parallelFind(items, predicate, options = {}) {
+    return withSpan("utils.parallelFind", async () => {
+        if (items.length === 0)
+            return undefined;
+        const semaphore = options.semaphore ?? apiSemaphore;
+        const timeoutMs = options.timeoutMs ?? ACQUIRE_TIMEOUT_MS;
+        let found;
+        let foundIndex = Infinity;
+        await Promise.all(items.map(async (item, index) => {
+            if (index >= foundIndex)
+                return;
+            await acquireOrThrow(semaphore, timeoutMs, "parallelFind");
+            try {
+                if (index >= foundIndex)
+                    return;
+                const matches = await predicate(item, index);
+                if (!matches || index >= foundIndex)
+                    return;
+                found = item;
+                foundIndex = index;
+            }
+            finally {
+                semaphore.release();
+            }
+        }));
+        return found;
+    }, { "parallel.itemCount": items.length });
+}
+export function parallelFilter(items, predicate, options = {}) {
+    return withSpan("utils.parallelFilter", async () => {
+        const results = await parallelMap(items, async (item, index) => ({ item, keep: await predicate(item, index) }), options);
+        return results.filter((r) => r.keep).map((r) => r.item);
+    }, { "parallel.itemCount": items.length });
+}
+export function createSemaphore(permits) {
+    return new Semaphore(permits);
+}
+export function getApiSemaphore() {
+    return apiSemaphore;
+}