@juspay/neurolink 12.12.9 → 12.12.11

package/dist/proxy/proxyAnalysis.js

@@ -1,17 +1,20 @@
 import { createReadStream } from "node:fs";
 import { isDeepStrictEqual } from "node:util";
+import { isProxyAuxiliaryRequest } from "./proxyRequestKind.js";
 import { lstat, readdir, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { ACCOUNT_COOLING_REASONS, PROXY_ACCOUNT_TYPES, PROXY_ACCOUNT_ROUTING_MODES, PROXY_ACCOUNT_ROUTING_REASONS, PROXY_ACCOUNT_ROUTING_STRATEGIES, } from "./routingEvidence.js";
 import { calculateCost, hasPricing, isExactPricingMatch, } from "../utils/pricing.js";
-const LIFECYCLE_FILE_PATTERN = /^proxy-lifecycle-\d{4}-\d{2}-\d{2}\.jsonl$/;
+const LIFECYCLE_FILE_PATTERN = /^proxy-(?:lifecycle|supervisor)-\d{4}-\d{2}-\d{2}\.jsonl$/;
 const REQUEST_FILE_PATTERN = /^proxy-\d{4}-\d{2}-\d{2}\.jsonl$/;
 const ATTEMPT_FILE_PATTERN = /^proxy-attempts-\d{4}-\d{2}-\d{2}\.jsonl$/;
 const DEBUG_FILE_PATTERN = /^proxy-debug-\d{4}-\d{2}-\d{2}\.jsonl$/;
 const ARTIFACT_STAT_CONCURRENCY = 64;
 const LIFECYCLE_EVENTS = new Set([
+    "runtime_sample",
+    "supervisor_event",
     "request_accepted",
     "response_headers",
     "response_first_chunk",
@@ -585,6 +588,7 @@ export async function analyzeProxyLogs(options) {
     let malformedLines = 0;
     let unsupportedLifecycleLines = 0;
     const accepted = new Set();
+    const auxiliaryRequests = new Set();
     const headers = new Set();
     const firstChunks = new Set();
     const terminal = new Set();
@@ -595,18 +599,36 @@ export async function analyzeProxyLogs(options) {
     const firstChunkLatencyByRequest = new Map();
     const terminalLatencyByRequest = new Map();
     const sequences = new Map();
+    const selectedSequenceRanges = new Map();
     const seenLifecycleEvents = new Map();
     let conflictingLifecycleDuplicates = 0;
     const conflictedRequests = new Set();
     const terminalRecords = new Map();
+    const acceptedWorkers = new Map();
+    const admittedWorkerIds = new Set();
+    const conflictedWorkerExits = new Set();
+    const conflictingIdentities = new Set();
+    const runtimeRecords = new Map();
+    const workerExits = new Map();
+    const runtime = {
+        samples: 0,
+        maxEventLoopDelayMs: null,
+        maxRssBytes: null,
+        maxCpuPercentOneCore: null,
+        maxHostLoad1m: null,
+    };
     for (const filePath of lifecycleFiles) {
         linesRead += await readJsonLines(filePath, (record) => {
-            const timestamp = observeTimestamp("lifecycle", record);
+            const operational = record.event === "runtime_sample" ||
+                record.event === "supervisor_event";
+            const operationalTimestamp = Date.parse(String(record.timestamp));
+            const timestamp = operational
+                ? Number.isFinite(operationalTimestamp)
+                    ? operationalTimestamp
+                    : null
+                : observeTimestamp("lifecycle", record);
             const requestId = stringValue(record.requestId);
-            if (timestamp === null ||
-                !requestId ||
-                (!accepted.has(requestId) &&
-                    (timestamp < sinceMs || timestamp > untilMs))) {
+            if (timestamp === null || !requestId) {
                 return;
             }
             const event = stringValue(record.event);
@@ -614,7 +636,10 @@ export async function analyzeProxyLogs(options) {
                 !event ||
                 !LIFECYCLE_EVENTS.has(event) ||
                 !requestId) {
-                unsupportedLifecycleLines += 1;
+                if (accepted.has(requestId) ||
+                    (timestamp >= sinceMs && timestamp <= untilMs)) {
+                    unsupportedLifecycleLines += 1;
+                }
                 return;
             }
             const processId = stringValue(record.processInstanceId);
@@ -623,11 +648,40 @@ export async function analyzeProxyLogs(options) {
                 const values = sequences.get(processId) ?? [];
                 values.push(sequence);
                 sequences.set(processId, values);
+            }
+            const details = record.supervisorEvent && typeof record.supervisorEvent === "object"
+                ? record.supervisorEvent
+                : undefined;
+            const exitedWorkerId = stringValue(details?.workerProcessInstanceId);
+            const relatedExit = event === "supervisor_event" &&
+                details?.type === "worker_exit" &&
+                exitedWorkerId &&
+                admittedWorkerIds.has(exitedWorkerId);
+            // Audit intervening sequences before selecting the request cohort.
+            if (!accepted.has(requestId) &&
+                !relatedExit &&
+                (timestamp < sinceMs || timestamp > untilMs)) {
+                return;
+            }
+            if (processId && sequence !== null && Number.isInteger(sequence)) {
+                const range = selectedSequenceRanges.get(processId);
+                selectedSequenceRanges.set(processId, {
+                    min: Math.min(range?.min ?? sequence, sequence),
+                    max: Math.max(range?.max ?? sequence, sequence),
+                });
                 const identity = `${processId}:${sequence}`;
                 const previous = seenLifecycleEvents.get(identity);
                 if (previous) {
                     if (!isDeepStrictEqual(previous, record)) {
                         conflictingLifecycleDuplicates += 1;
+                        conflictingIdentities.add(identity);
+                        for (const copy of [previous, record]) {
+                            const detail = copy.supervisorEvent;
+                            const workerId = stringValue(detail?.workerProcessInstanceId);
+                            if (workerId) {
+                                conflictedWorkerExits.add(workerId);
+                            }
+                        }
                         conflictedRequests.add(requestId);
                         const previousRequestId = stringValue(previous.requestId);
                         if (previousRequestId) {
@@ -638,9 +692,36 @@ export async function analyzeProxyLogs(options) {
                 }
                 seenLifecycleEvents.set(identity, record);
             }
+            if (event === "runtime_sample") {
+                if (record.runtimeSample &&
+                    typeof record.runtimeSample === "object" &&
+                    processId &&
+                    sequence !== null) {
+                    runtimeRecords.set(`${processId}:${sequence}`, record.runtimeSample);
+                }
+                return;
+            }
+            if (event === "supervisor_event") {
+                if (details?.type === "worker_exit" && exitedWorkerId) {
+                    const exit = { ...details, at: record.timestamp };
+                    const previous = workerExits.get(exitedWorkerId);
+                    if (previous && !isDeepStrictEqual(previous, exit)) {
+                        conflictedWorkerExits.add(exitedWorkerId);
+                    }
+                    workerExits.set(exitedWorkerId, exit);
+                }
+                return;
+            }
+            if (isProxyAuxiliaryRequest(stringValue(record.method) ?? "", stringValue(record.path) ?? "")) {
+                auxiliaryRequests.add(requestId);
+            }
             const elapsed = finiteNumber(record.elapsedMs);
             if (event === "request_accepted") {
                 accepted.add(requestId);
+                if (processId) {
+                    acceptedWorkers.set(requestId, processId);
+                    admittedWorkerIds.add(processId);
+                }
             }
             else if (event === "response_headers") {
                 if (headers.has(requestId)) {
@@ -683,6 +764,25 @@ export async function analyzeProxyLogs(options) {
             malformedLines += 1;
         });
     }
+    for (const [identity, sample] of runtimeRecords) {
+        if (conflictingIdentities.has(identity)) {
+            continue;
+        }
+        runtime.samples += 1;
+        const mapping = {
+            maxEventLoopDelayMs: "eventLoopDelayMaxMs",
+            maxRssBytes: "rssBytes",
+            maxCpuPercentOneCore: "cpuPercentOneCore",
+            maxHostLoad1m: "hostLoad1m",
+        };
+        for (const [key, source] of Object.entries(mapping)) {
+            const value = finiteNumber(sample[source]);
+            if (value !== null && value >= 0) {
+                const target = key;
+                runtime[target] = Math.max(runtime[target] ?? value, value);
+            }
+        }
+    }
     // Contradictory copies are not reliable latency samples. Keep their data
     // quality count, but do not choose one timing arbitrarily.
     const verifiedLatencies = (values) => [...values]
@@ -693,7 +793,12 @@ export async function analyzeProxyLogs(options) {
     const terminalLatency = verifiedLatencies(terminalLatencyByRequest);
     let lifecycleSequenceGaps = 0;
     let lifecycleSequenceDuplicates = 0;
-    for (const values of sequences.values()) {
+    for (const [processId, allValues] of sequences) {
+        const range = selectedSequenceRanges.get(processId);
+        if (!range) {
+            continue;
+        }
+        const values = allValues.filter((value) => value >= range.min && value <= range.max);
         values.sort((a, b) => a - b);
         for (let index = 1; index < values.length; index += 1) {
             const difference = values[index] - values[index - 1];
@@ -918,6 +1023,9 @@ export async function analyzeProxyLogs(options) {
     for (const [requestId, record] of terminalRecords) {
         const final = finalRequests.get(requestId);
         const recorded = stringValue(record.terminalOutcome) ?? "unknown";
+        const auxiliaryTransport = auxiliaryRequests.has(requestId)
+            ? (stringValue(record.transportOutcome) ?? recorded)
+            : null;
         const resolved = final
             ? final.status === 499 || final.errorType === "client_cancelled"
                 ? "client_cancelled"
@@ -927,11 +1035,20 @@ export async function analyzeProxyLogs(options) {
                     : final.status >= 400 || final.errorType
                         ? "handler_error"
                         : "completed"
-            : conflictedRequests.has(requestId) ||
-                recorded === "completed" ||
-                recorded === "bodyless"
-                ? "unknown"
-                : recorded;
+            : auxiliaryTransport && !conflictedRequests.has(requestId)
+                ? auxiliaryTransport === "completed" ||
+                    auxiliaryTransport === "bodyless"
+                    ? finiteNumber(record.responseStatus) === null
+                        ? "unknown"
+                        : Number(record.responseStatus) >= 400
+                            ? "handler_error"
+                            : auxiliaryTransport
+                    : auxiliaryTransport
+                : conflictedRequests.has(requestId) ||
+                    recorded === "completed" ||
+                    recorded === "bodyless"
+                    ? "unknown"
+                    : recorded;
         if (final &&
             recorded !== resolved &&
             !(recorded === "bodyless" && resolved === "completed")) {
@@ -1038,10 +1155,8 @@ export async function analyzeProxyLogs(options) {
             conflictingLifecycleDuplicates,
             duplicateAttempts,
             finalOutcomeConflicts,
-            acceptedWithoutFinal: [...accepted].filter((id) => !finalRequests.has(id))
-                .length,
-            terminalWithoutFinal: [...terminal].filter((id) => !finalRequests.has(id))
-                .length,
+            acceptedWithoutFinal: [...accepted].filter((id) => !finalRequests.has(id) && !auxiliaryRequests.has(id)).length,
+            terminalWithoutFinal: [...terminal].filter((id) => !finalRequests.has(id) && !auxiliaryRequests.has(id)).length,
             streams: Object.fromEntries(Object.entries(observedRanges).map(([stream, range]) => [
                 stream,
                 {
@@ -1066,8 +1181,35 @@ export async function analyzeProxyLogs(options) {
                 absent: absentRoutingDecisions,
             },
         },
+        runtime,
         lifecycle: {
+            unconfirmedAtWorkerExit: [...accepted].flatMap((requestId) => {
+                const workerProcessInstanceId = acceptedWorkers.get(requestId);
+                const exit = workerProcessInstanceId
+                    ? workerExits.get(workerProcessInstanceId)
+                    : undefined;
+                if (!exit ||
+                    !workerProcessInstanceId ||
+                    conflictedWorkerExits.has(workerProcessInstanceId) ||
+                    terminal.has(requestId) ||
+                    conflictedRequests.has(requestId)) {
+                    return [];
+                }
+                return [
+                    {
+                        requestId,
+                        workerProcessInstanceId,
+                        at: String(exit.at),
+                        workerExitCode: finiteNumber(exit.workerExitCode),
+                        workerExitSignal: stringValue(exit.workerExitSignal),
+                        // A provider final cannot prove the client received the entire body.
+                        providerFinalRecorded: finalRequests.has(requestId),
+                    },
+                ];
+            }),
             accepted: accepted.size,
+            auxiliaryRequests: [...accepted].filter((id) => auxiliaryRequests.has(id))
+                .length,
             headers: headers.size,
             firstChunks: firstChunks.size,
             terminal: terminal.size,

package/dist/proxy/proxyLifecycle.d.ts

@@ -1,13 +1,38 @@
+import { chmodSync } from "node:fs";
 import { appendFile } from "node:fs/promises";
 import type { ProxyLifecycleEventInput, ProxyLifecycleLoggerOptions, ProxyLifecycleLoggerSnapshot } from "../types/index.js";
 export declare function hashProxyLifecycleSessionId(sessionId: string | undefined): string | undefined;
+/**
+ * Configure private journal storage while retaining required admission
+ * when initialization fails.
+ */
 export declare function configureProxyLifecycleLogger(options: ProxyLifecycleLoggerOptions): void;
 /** Enqueue fixed-size lifecycle metadata without awaiting filesystem work. */
 export declare function logProxyLifecycleEvent(input: ProxyLifecycleEventInput): void;
+/** Confirm admission before upstream dispatch, without waiting for later traffic.
+ * Disabled logging is explicit; an enabled but unhealthy sink refuses dispatch.
+ * A timeout never retries an ambiguous provider request or the pending append.
+ */
+export declare function persistProxyLifecycleAcceptance(input: Omit<ProxyLifecycleEventInput, "event">, timeoutMs?: number): Promise<void>;
 export declare function flushProxyLifecycleEvents(timeoutMs?: number): Promise<void>;
+/**
+ * Expose journal accounting, process identity, and outstanding writes
+ * without changing them.
+ */
 export declare function getProxyLifecycleLoggerSnapshot(): ProxyLifecycleLoggerSnapshot;
+/**
+ * Reset timers, accounting, and injected I/O after isolated tests have
+ * drained their work.
+ */
 export declare function resetProxyLifecycleLoggerForTests(): void;
 /** Isolated failure injection for lifecycle durability tests. */
 export declare const __proxyLifecycleTestHooks: {
+    /**
+     * Inject directory-hardening failures without altering real filesystem permissions.
+     */
+    setChmodForTests(chmod: typeof chmodSync): void;
+    /**
+     * Inject controlled append outcomes while preserving the production admission and queue paths.
+     */
     setAppendFileForTests(append: typeof appendFile): void;
 };

package/dist/proxy/proxyLifecycle.js

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { performance } from "node:perf_hooks";
 import { withTimeout } from "../utils/async/withTimeout.js";
 import { logger } from "../utils/logger.js";
+import { startProxyRuntimeMetrics } from "./proxyRuntimeMetrics.js";
 const SCHEMA_VERSION = 1;
 const DEFAULT_QUEUE_CAPACITY = 10_000;
 const DEFAULT_BATCH_SIZE = 256;
@@ -14,8 +15,12 @@ const MAX_WRITE_RETRY_DELAY_MS = 1_000;
 const LIFECYCLE_APPEND_TIMEOUT_MS = 2_000;
 const MAX_SHORT_FIELD_LENGTH = 256;
 const SESSION_KEY_FILE = ".proxy-lifecycle-session-key";
+let chmodLifecycleDirectory = chmodSync;
 let loggerEnabled = false;
+let loggerRequired = false;
+let stopRuntimeMetrics;
 let lifecycleLogDir;
+let filePrefix = "proxy-lifecycle";
 let queueCapacity = DEFAULT_QUEUE_CAPACITY;
 let batchSize = DEFAULT_BATCH_SIZE;
 let flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS;
@@ -141,6 +146,10 @@ function scheduleFlush(delayMs = flushIntervalMs) {
     }, delayMs);
     flushTimer.unref?.();
 }
+/**
+ * Append a bounded metadata batch and confirm each admission without
+ * replaying ambiguous writes.
+ */
 async function flushBatch() {
     if (queue.length === 0) {
         return;
@@ -150,7 +159,7 @@ async function flushBatch() {
     try {
         const byPath = new Map();
         for (const item of batch) {
-            const path = join(item.logDir, `proxy-lifecycle-${item.date}.jsonl`);
+            const path = join(item.logDir, `${item.filePrefix ?? "proxy-lifecycle"}-${item.date}.jsonl`);
             const items = byPath.get(path) ?? [];
             items.push(item);
             byPath.set(path, items);
@@ -167,11 +176,13 @@ async function flushBatch() {
             }, LIFECYCLE_APPEND_TIMEOUT_MS);
             timeout.unref?.();
             try {
-                // This best-effort telemetry sink intentionally avoids fsync so request
-                // throughput is not coupled to storage latency. Loss is surfaced by
-                // writeDrops/writeFailures rather than delaying proxy responses.
+                // OS-acknowledged append survives serving-process death. This is not
+                // an fsync/power-loss guarantee. Admission waits on its own record.
                 await appendLifecycleFile(path, lines.join(""), { mode: 0o600 });
                 written += lines.length;
+                for (const item of items) {
+                    item.onPersisted?.(true);
+                }
             }
             catch (error) {
                 writeFailures += 1;
@@ -189,6 +200,9 @@ async function flushBatch() {
                 ]).has(code ?? "");
                 if (!definitelyNotWritten) {
                     unconfirmedWrites += items.length;
+                    for (const item of items) {
+                        item.onPersisted?.(false);
+                    }
                     logger.warn("[proxy] lifecycle metadata append outcome is uncertain", {
                         path,
                         records: items.length,
@@ -211,6 +225,11 @@ async function flushBatch() {
                 if (exhausted > 0) {
                     dropped += exhausted;
                     writeDrops += exhausted;
+                    for (const item of items) {
+                        if (item.writeRetries >= maxWriteRetries) {
+                            item.onPersisted?.(false);
+                        }
+                    }
                 }
                 logger.warn("[proxy] lifecycle metadata write failed", {
                     path,
@@ -234,6 +253,10 @@ async function flushBatch() {
         inFlight = Math.max(0, inFlight - batch.length);
     }
 }
+/**
+ * Serialize batch ownership so timeouts cannot create overlapping append
+ * retries.
+ */
 function startFlush() {
     if (flushInFlight) {
         return flushInFlight;
@@ -257,10 +280,18 @@ function startFlush() {
     });
     return currentFlush;
 }
+/**
+ * Configure private journal storage while retaining required admission
+ * when initialization fails.
+ */
 export function configureProxyLifecycleLogger(options) {
+    stopRuntimeMetrics?.();
+    stopRuntimeMetrics = undefined;
     clearScheduledFlush();
     nextFlushDelayMs = undefined;
     loggerEnabled = false;
+    loggerRequired = options.enabled;
+    filePrefix = options.filePrefix ?? "proxy-lifecycle";
     lifecycleLogDir = undefined;
     queueCapacity = positiveInteger(options.queueCapacity, DEFAULT_QUEUE_CAPACITY);
     batchSize = positiveInteger(options.batchSize, DEFAULT_BATCH_SIZE);
@@ -269,9 +300,21 @@ export function configureProxyLifecycleLogger(options) {
     if (options.enabled && options.logDir) {
         try {
             mkdirSync(options.logDir, { recursive: true, mode: 0o700 });
+            // mkdir mode does not harden an existing directory. Keep admission
+            // required but the sink disabled if its privacy boundary cannot be set.
+            chmodLifecycleDirectory(options.logDir, 0o700);
             sessionHashKey = resolveSessionHashKey(options.logDir);
             lifecycleLogDir = options.logDir;
             loggerEnabled = true;
+            stopRuntimeMetrics = startProxyRuntimeMetrics((runtimeSample) => {
+                logProxyLifecycleEvent({
+                    event: "runtime_sample",
+                    requestId: "-",
+                    method: "-",
+                    path: "-",
+                    runtimeSample,
+                });
+            });
         }
         catch (error) {
             logger.warn("[proxy] lifecycle metadata logging disabled", {
@@ -286,15 +329,24 @@ export function configureProxyLifecycleLogger(options) {
 }
 /** Enqueue fixed-size lifecycle metadata without awaiting filesystem work. */
 export function logProxyLifecycleEvent(input) {
+    enqueueLifecycleEvent(input);
+}
+/**
+ * Enqueue bounded metadata and resolve admission failure immediately when
+ * capacity is unavailable.
+ */
+function enqueueLifecycleEvent(input, onPersisted) {
     if (!loggerEnabled || !lifecycleLogDir) {
+        onPersisted?.(false);
         return;
     }
     try {
         attempted += 1;
         const sequence = nextSequence++;
-        if (queue.length >= queueCapacity) {
+        if (queue.length + inFlight >= queueCapacity) {
             dropped += 1;
             queueDrops += 1;
+            onPersisted?.(false);
             return;
         }
         const timestamp = formatTimestamp(input.timestampMs);
@@ -344,12 +396,23 @@ export function logProxyLifecycleEvent(input) {
             ...(terminalOutcome !== undefined ? { terminalOutcome } : {}),
             ...(errorType !== undefined ? { errorType } : {}),
             ...(errorCode !== undefined ? { errorCode } : {}),
+            ...(input.supervisorEvent
+                ? {
+                    supervisorEvent: {
+                        ...input.supervisorEvent,
+                        reason: clip(input.supervisorEvent.reason),
+                    },
+                }
+                : {}),
+            ...(input.runtimeSample ? { runtimeSample: input.runtimeSample } : {}),
         };
         queue.push({
+            filePrefix,
             logDir: lifecycleLogDir,
             date: String(record.timestamp).slice(0, 10),
             record,
             writeRetries: 0,
+            onPersisted,
         });
         enqueued += 1;
         scheduleFlush();
@@ -357,6 +420,28 @@ export function logProxyLifecycleEvent(input) {
     catch {
         dropped += 1;
         invalidDrops += 1;
+        onPersisted?.(false);
+    }
+}
+/** Confirm admission before upstream dispatch, without waiting for later traffic.
+ * Disabled logging is explicit; an enabled but unhealthy sink refuses dispatch.
+ * A timeout never retries an ambiguous provider request or the pending append.
+ */
+export async function persistProxyLifecycleAcceptance(input, timeoutMs = LIFECYCLE_APPEND_TIMEOUT_MS) {
+    if (!loggerRequired) {
+        return;
+    }
+    const confirmed = new Promise((resolve) => {
+        enqueueLifecycleEvent({ ...input, event: "request_accepted" }, resolve);
+    });
+    // Yield one turn for concurrent admissions to share a bounded batch.
+    clearScheduledFlush();
+    scheduleFlush(0);
+    const persisted = await withTimeout(confirmed, timeoutMs, "Proxy admission metadata append is still pending").catch(() => false);
+    if (!persisted) {
+        throw Object.assign(new Error("Proxy admission metadata could not be confirmed"), {
+            code: "PROXY_TELEMETRY_UNAVAILABLE",
+        });
     }
 }
 export async function flushProxyLifecycleEvents(timeoutMs = 5_000) {
@@ -370,6 +455,10 @@ export async function flushProxyLifecycleEvents(timeoutMs = 5_000) {
         }
     }
 }
+/**
+ * Expose journal accounting, process identity, and outstanding writes
+ * without changing them.
+ */
 export function getProxyLifecycleLoggerSnapshot() {
     return {
         enabled: loggerEnabled,
@@ -392,9 +481,16 @@ export function getProxyLifecycleLoggerSnapshot() {
         flushing: flushInFlight !== undefined,
     };
 }
+/**
+ * Reset timers, accounting, and injected I/O after isolated tests have
+ * drained their work.
+ */
 export function resetProxyLifecycleLoggerForTests() {
+    stopRuntimeMetrics?.();
+    stopRuntimeMetrics = undefined;
     clearScheduledFlush();
     loggerEnabled = false;
+    loggerRequired = false;
     lifecycleLogDir = undefined;
     queueCapacity = DEFAULT_QUEUE_CAPACITY;
     batchSize = DEFAULT_BATCH_SIZE;
@@ -419,9 +515,19 @@ export function resetProxyLifecycleLoggerForTests() {
     flushInFlight = undefined;
     nextFlushDelayMs = undefined;
     appendLifecycleFile = appendFile;
+    chmodLifecycleDirectory = chmodSync;
 }
 /** Isolated failure injection for lifecycle durability tests. */
 export const __proxyLifecycleTestHooks = {
+    /**
+     * Inject directory-hardening failures without altering real filesystem permissions.
+     */
+    setChmodForTests(chmod) {
+        chmodLifecycleDirectory = chmod;
+    },
+    /**
+     * Inject controlled append outcomes while preserving the production admission and queue paths.
+     */
     setAppendFileForTests(append) {
         appendLifecycleFile = append;
     },

package/dist/proxy/proxyRequestKind.d.ts

@@ -0,0 +1,2 @@
+/** These metadata endpoints finish as HTTP responses, without model generation. */
+export declare function isProxyAuxiliaryRequest(method: string, path: string): boolean;

package/dist/proxy/proxyRequestKind.js

@@ -0,0 +1,6 @@
+/** These metadata endpoints finish as HTTP responses, without model generation. */
+export function isProxyAuxiliaryRequest(method, path) {
+    return ((method === "POST" && path === "/v1/messages/count_tokens") ||
+        (method === "GET" &&
+            (path === "/backend-api/codex/models" || path === "/v1/models")));
+}

package/dist/proxy/proxyRuntimeMetrics.d.ts

@@ -0,0 +1,3 @@
+import type { ProxyRuntimeSample } from "../types/index.js";
+/** Samples use actual elapsed time, including delayed timers under host load. */
+export declare function startProxyRuntimeMetrics(emit: (sample: ProxyRuntimeSample) => void): () => void;

package/dist/proxy/proxyRuntimeMetrics.js

@@ -0,0 +1,34 @@
+import { monitorEventLoopDelay, performance } from "node:perf_hooks";
+import { availableParallelism, loadavg } from "node:os";
+/** Samples use actual elapsed time, including delayed timers under host load. */
+export function startProxyRuntimeMetrics(emit) {
+    const histogram = monitorEventLoopDelay({ resolution: 20 });
+    histogram.enable();
+    let previousCpu = process.cpuUsage();
+    let previousTime = performance.now();
+    const timer = setInterval(() => {
+        const now = performance.now();
+        const cpu = process.cpuUsage();
+        const intervalMs = now - previousTime;
+        emit({
+            intervalMs,
+            cpuPercentOneCore: ((cpu.user - previousCpu.user + cpu.system - previousCpu.system) /
+                (intervalMs * 1000)) *
+                100,
+            rssBytes: process.memoryUsage().rss,
+            heapUsedBytes: process.memoryUsage().heapUsed,
+            eventLoopDelayP99Ms: histogram.count ? histogram.percentile(99) / 1e6 : 0,
+            eventLoopDelayMaxMs: histogram.count ? histogram.max / 1e6 : 0,
+            hostLoad1m: loadavg()[0],
+            availableParallelism: availableParallelism(),
+        });
+        previousCpu = cpu;
+        previousTime = now;
+        histogram.reset();
+    }, 10_000);
+    timer.unref();
+    return () => {
+        clearInterval(timer);
+        histogram.disable();
+    };
+}

package/dist/proxy/requestLogger.d.ts

@@ -6,9 +6,15 @@
  * Useful for debugging and auditing proxy traffic.
  */
 import type { ProxyBodyCaptureEntry, RequestAttemptLogEntry, RequestLogEntry, ProxyRequestLoggerSnapshot } from "../types/index.js";
+/**
+ * Expose independent metadata-sink and body-capture counters for incident reconciliation.
+ */
 export declare function getRequestLoggerSnapshot(): ProxyRequestLoggerSnapshot;
 /** Wait, up to a bounded deadline, for admitted request/body writes to settle. */
 export declare function flushRequestLogs(timeoutMs?: number): Promise<void>;
+/**
+ * Initialize private request logs and preserve required lifecycle admission on startup failures.
+ */
 export declare function initRequestLogger(enabled?: boolean, customLogsDir?: string): void;
 export declare function logRequest(entry: RequestLogEntry): Promise<void>;
 /**
@@ -18,19 +24,17 @@ export declare function logRequest(entry: RequestLogEntry): Promise<void>;
  */
 export declare function logRequestAttempt(entry: RequestAttemptLogEntry): Promise<void>;
 export declare function getLogDir(): string | null;
-/** Shared redaction used by offline replay exports and direct comparisons. */
-export declare function redactProxyHeadersForLogging(headers: Record<string, string> | undefined): Record<string, string> | undefined;
 /**
- * Apply the same bounded body redaction used by persisted proxy captures.
- * `value` and `bytes` are omitted only when the input is null or undefined.
- * This performs serialization immediately, so callers must keep it off proxy
- * hot paths unless body processing has already been explicitly requested.
+ * Redact sensitive header values in-place.
  */
+export declare function redactProxyHeadersForLogging(headers: Record<string, string> | undefined): Record<string, string> | undefined;
+/** Return a redacted body representation suitable for persisted request diagnostics. */
 export declare function prepareProxyBodyForLogging(body: unknown): {
     value?: string;
     bytes?: number;
     truncated: boolean;
 };
+/** Capture an owned request body with bounded processing and tracked index/export publication. */
 export declare function logBodyCapture(entry: ProxyBodyCaptureEntry): Promise<void>;
 /**
  * Log the FULL raw request and response for debugging.