@loadstrike/loadstrike-sdk 1.0.30401 → 1.0.31601

package/README.md

@@ -68,12 +68,18 @@ Non-correlated V2 scenarios can run through the local-development cluster or a r
 
 HTML reports include a Generator Delivery tab whenever scheduler delivery data, raw observation delivery statistics, generator or reporting warnings, or incomplete reporting are available. Results without reporting-completeness status show N/A rather than reporting loss. Application failures remain separate from generator and reporting warnings.
 
+HTML charts are responsive SVG graphics embedded in the offline report. They provide exact-value pointer, touch, and keyboard tooltips; outcome legends; zoom, pan, and reset; an accessible expanded view; chart-title search; and compact, comfortable, or spacious grids. Successful and failed latency stay separate, while All appears only when the run has a genuine combined distribution. When temporal history is available, cumulative requests, achieved request rate, bytes, and per-scenario latency include the final partial reporting interval. Correlation charts retain scenario, destination, status, GatherBy selector/value, and all available percentile points without averaging groups.
+
 ## Raw Iteration Reporting
 
 Observation-capable reporting sinks receive one compact record for every scenario attempt, including retry attempts and nested steps. Retries share a logical iteration ID while retaining distinct attempt indexes and final-attempt markers. Warm-up and bombing traffic, simulation and shard identity, UTC nanosecond timestamps, observed and reported latency, outcome, status code, and response size are included; reply messages, payloads, bodies, and headers are not.
 
+If a fail-mode runtime policy callback fails after an attempt begins, the stream receives one final failed observation with status `runtime_policy_error` before the run terminates. The observation does not include the callback error text.
+
 Portal reporting sends compressed batches, while the JSONL and generic webhook sinks preserve the canonical observation records. Custom sinks can opt in with `saveIterationBatch` or `SaveIterationBatch` while keeping all existing aggregate lifecycle callbacks unchanged. Batches flush every five seconds; the defaults and the portal-compatible common shape are 50,000 observations or 8 MiB before compression. Runs without a portal sink may select the documented larger limits. Capture and sink queues are memory bounded; buffer pressure, a single record that cannot fit a batch, and sink pressure drop only the affected reporting observations with explicit warnings instead of changing application failures. Metric-only destinations disclose their reduced observation shape. The final observation flush and optional stream-completion callback finish before `saveRunResult` or `SaveRunResult`.
 
+Every reporting-sink callback—including initialization, start, realtime statistics and metrics, final statistics and metrics, raw batches, completion markers, stop, and dispose—is attempted once and then retried up to three times by default, after 250 ms, 500 ms, and 1 second. Set `sinkRetryCount` and `sinkRetryBackoffMs`, or the matching Pascal-case configuration keys, to select a bounded policy of zero through 100 retries. A recovered callback adds no final sink error or delivery-failed warning. Only an exhausted raw-observation delivery counts as sink observation loss; other exhausted callbacks are reported against that sink without failing the workload. Custom sinks have at-least-once delivery semantics and should deduplicate replay by stable batch or observation identity. Stop and dispose remain best-effort cleanup, and an exhausted stop callback does not prevent dispose. Sanitized nested error details stay in the local run log rather than generator warnings, portable results, portal payloads, or HTML reports.
+
 Portal trend p50, p75, p95, and p99 values are calculated cumulatively from every final bombing-phase outcome received for that scenario and run. Separate successful and failed distributions remain available for diagnosis; SDK-calculated percentile fields are not sent as the authoritative portal or observation-capable sink result.
 
 Use runner configuration fields such as `iterationObservationFlushIntervalSeconds`, `maxIterationObservationBufferBytes`, `maxIterationObservationsPerBatch`, `maxIterationObservationBatchBytes`, `iterationObservationSinkQueueDepth`, `iterationObservationSinkParallelism`, and `iterationObservationDrainTimeoutSeconds` when the defaults need to be adjusted within their documented bounds.

package/dist/cjs/iteration-observation-diagnostics.js

@@ -0,0 +1,513 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logIterationObservationFailure = logIterationObservationFailure;
+exports.logIterationObservationRecovery = logIterationObservationRecovery;
+exports.redactIterationObservationSecrets = redactIterationObservationSecrets;
+const MAXIMUM_DIAGNOSTIC_BYTES = 16 * 1024;
+const MAXIMUM_SOURCE_CHARACTERS = 8 * 1024;
+const MAXIMUM_CAUSAL_DEPTH = 8;
+const MAXIMUM_CAUSAL_NODES = 32;
+const SOURCE_TRUNCATION_SUFFIX = " [truncated]";
+const SENSITIVE_FIELD_NAME_SOURCE = "(?:authorization|proxy(?:[_-]|\\s+)?authorization|body|payload"
+    + "|request(?:[_-]|\\s+)?(?:body|payload)"
+    + "|response(?:[_-]|\\s+)?(?:body|payload)"
+    + "|observation(?:[_-]|\\s+)?(?:body|payload)"
+    + "|runner(?:[_-]|\\s+)?key"
+    + "|api(?:[_-]|\\s+)?(?:key|token)"
+    + "|x(?:[_-]|\\s+)?api(?:[_-]|\\s+)?(?:key|token)"
+    + "|run(?:[_-]|\\s+)?token|access(?:[_-]|\\s+)?token"
+    + "|refresh(?:[_-]|\\s+)?token|id(?:[_-]|\\s+)?token"
+    + "|token|password|passwd|pwd|client(?:[_-]|\\s+)?secret"
+    + "|connection(?:[_-]|\\s+)?string|secret)";
+const SENSITIVE_FIELD_NAME_PATTERN = new RegExp(`^${SENSITIVE_FIELD_NAME_SOURCE}$`, "iu");
+const SENSITIVE_FIELD_PATTERN = new RegExp(`(^|[\\s{(,;=.]|\\[\\s*)(["']?)(${SENSITIVE_FIELD_NAME_SOURCE})\\2((?:\\s*\\[\\s*\\d+\\s*\\])*)(\\s*\\])?\\s*[:=]\\s*`, "giu");
+const NEXT_SENSITIVE_FIELD_PATTERN = new RegExp(`\\s+(?=(?:(?:[a-z_$][\\w$.-]*\\s*)?\\[\\s*)?["']?${SENSITIVE_FIELD_NAME_SOURCE}["']?(?:\\s*\\[\\s*\\d+\\s*\\])*\\s*\\]?\\s*[:=])`, "giu");
+const XML_ELEMENT_TAG_PATTERN = /<\s*(\/?)\s*([a-z_][\w.:-]*)(?:\s[^<>]*?)?\s*(\/?)>/giu;
+const DIAGNOSTIC_FIELD_BOUNDARY_PATTERN = /\s+(?=(?:stack|code|errno|syscall|status|statuscode|statustext)\s*[:=])/giu;
+const CAUSAL_BOUNDARY_PATTERN = /\s+\|\s+/gu;
+const SOURCE_TRUNCATION_BOUNDARY_PATTERN = /\s+\[truncated\](?=\s|$)/giu;
+const STANDALONE_CREDENTIAL_BOUNDARY_PATTERN = /\s+(?=(?:bearer|basic)\s+(?:["']|\[REDACTED\]|[a-z0-9._~+/=-]+))/giu;
+const STANDALONE_CREDENTIAL_PREFIX_PATTERN = /\b(bearer|basic)\s+/giu;
+function logIterationObservationFailure(logger, level, context, error) {
+    const event = formatIterationObservationDiagnostic("observation sink callback failed", context, error);
+    safeLog(logger, level, event);
+}
+function logIterationObservationRecovery(logger, context) {
+    const event = formatIterationObservationDiagnostic("observation sink callback recovered", context);
+    safeLog(logger, "debug", event);
+}
+function formatIterationObservationDiagnostic(event, context, error) {
+    const fields = [
+        `event=${event}`,
+        `sink=${safeText(context.sinkName)}`,
+        `operation=${context.operation}`,
+        ...(context.phase ? [`phase=${safeText(context.phase)}`] : []),
+        `runId=${safeText(context.runId)}`,
+        `resultOwnerId=${safeText(context.resultOwnerId)}`,
+        ...(context.batchId ? [`batchId=${safeText(context.batchId)}`] : []),
+        ...(context.batchSequence64
+            ? [`batchSequence64=${safeText(context.batchSequence64)}`]
+            : []),
+        `observationCount=${safeInteger(context.observationCount)}`,
+        `attempt=${safeInteger(context.attempt)}/${safeInteger(context.maximumAttempts)}`,
+        ...(context.nextDelayMs === undefined
+            ? []
+            : [`nextDelayMs=${safeInteger(context.nextDelayMs)}`])
+    ];
+    if (error !== undefined) {
+        fields.push(`errorChain=${formatErrorChain(error)}`);
+    }
+    return truncateUtf8(redactIterationObservationSecrets(normalizeText(fields.join(" "))), MAXIMUM_DIAGNOSTIC_BYTES);
+}
+function formatErrorChain(error) {
+    const lines = [];
+    const seen = new Set();
+    const state = { nodes: 0, nodeLimitWritten: false };
+    visitError(error, "error", 0, seen, state, lines);
+    return lines.join(" | ");
+}
+function visitError(value, path, depth, seen, state, lines) {
+    if (depth >= MAXIMUM_CAUSAL_DEPTH) {
+        lines.push(`${path}: [truncated at causal depth ${MAXIMUM_CAUSAL_DEPTH}]`);
+        return;
+    }
+    if (state.nodes >= MAXIMUM_CAUSAL_NODES) {
+        if (!state.nodeLimitWritten) {
+            state.nodeLimitWritten = true;
+            lines.push(`[truncated after ${MAXIMUM_CAUSAL_NODES} causal nodes]`);
+        }
+        return;
+    }
+    state.nodes += 1;
+    if ((typeof value !== "object" && typeof value !== "function") || value === null) {
+        lines.push(`${path}: ${primitiveType(value)} message=${safeText(value)}`);
+        return;
+    }
+    if (seen.has(value)) {
+        lines.push(`${path}: [cycle]`);
+        return;
+    }
+    seen.add(value);
+    const name = safePropertyText(value, "name") || objectType(value);
+    const message = safePropertyText(value, "message");
+    const details = [`${path}: ${name}`];
+    if (message) {
+        details.push(`message=${message}`);
+    }
+    for (const key of ["code", "errno", "syscall", "status", "statusCode", "statusText"]) {
+        const resolved = safePropertyText(value, key);
+        if (resolved) {
+            details.push(`${key}=${resolved}`);
+        }
+    }
+    const stack = safePropertyText(value, "stack", 4096);
+    if (stack) {
+        details.push(`stack=${stack}`);
+    }
+    lines.push(details.join(" "));
+    const cause = safeProperty(value, "cause");
+    if (cause.available && cause.value !== undefined && cause.value !== null) {
+        visitError(cause.value, `${path}.cause`, depth + 1, seen, state, lines);
+    }
+    else if (!cause.available) {
+        lines.push(`${path}.cause: [unavailable]`);
+    }
+    const aggregate = safeProperty(value, "errors");
+    if (!aggregate.available) {
+        lines.push(`${path}.errors: [unavailable]`);
+        return;
+    }
+    const members = safeArrayMembers(aggregate.value);
+    for (let index = 0; index < members.length; index += 1) {
+        visitError(members[index], `${path}.errors[${index}]`, depth + 1, seen, state, lines);
+    }
+}
+function safeArrayMembers(value) {
+    try {
+        if (!Array.isArray(value)) {
+            return [];
+        }
+        const length = Math.min(value.length, MAXIMUM_CAUSAL_NODES);
+        const result = [];
+        for (let index = 0; index < length; index += 1) {
+            try {
+                result.push(value[index]);
+            }
+            catch {
+                result.push("[unavailable aggregate member]");
+            }
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}
+function safeProperty(value, key) {
+    try {
+        return { available: true, value: Reflect.get(value, key) };
+    }
+    catch {
+        return { available: false, value: undefined };
+    }
+}
+function safePropertyText(value, key, maximumCharacters = MAXIMUM_SOURCE_CHARACTERS) {
+    const property = safeProperty(value, key);
+    return property.available ? safeText(property.value, maximumCharacters) : "";
+}
+function objectType(value) {
+    try {
+        const tag = Object.prototype.toString.call(value);
+        const match = /^\[object ([^\]]+)\]$/u.exec(tag);
+        return match?.[1] || "Object";
+    }
+    catch {
+        return "Object";
+    }
+}
+function primitiveType(value) {
+    return value === null ? "null" : typeof value;
+}
+function safeText(value, maximumCharacters = MAXIMUM_SOURCE_CHARACTERS) {
+    let source;
+    try {
+        source = typeof value === "string" ? value : String(value ?? "");
+    }
+    catch {
+        source = "[unavailable]";
+    }
+    return normalizeText(boundSourceCharacters(source, maximumCharacters));
+}
+function normalizeText(value) {
+    const validUtf8 = Buffer.from(value, "utf8").toString("utf8");
+    return validUtf8
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/gu, " ")
+        .replace(/[\r\n\t]+/gu, " ")
+        .replace(/\s{2,}/gu, " ")
+        .trim();
+}
+function redactIterationObservationSecrets(value) {
+    let output = boundSourceCharacters(value, MAXIMUM_SOURCE_CHARACTERS * 2);
+    output = redactSensitiveXmlElements(output);
+    output = redactBoundedSensitiveFields(output);
+    output = redactStandaloneCredentials(output);
+    output = output.replace(/([?&](?:authorization|runner[_-]?key|api[_-]?(?:key|token)|x[_-]?api[_-]?(?:key|token)|run[_-]?token|access[_-]?token|refresh[_-]?token|id[_-]?token|security[_-]?token|token|password|passwd|pwd|client[_-]?secret|connection[_-]?string|account[_-]?key|key|secret|signature|sig|credential|code|x-(?:amz|goog)-(?:credential|signature|security-token))=)[^&#\s]*/giu, "$1[REDACTED]");
+    output = output.replace(/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/giu, "$1[REDACTED]@");
+    output = output.replace(/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@]+(?=\s+\[truncated\](?:\s|$))/giu, "$1[REDACTED]");
+    return output;
+}
+function redactStandaloneCredentials(value) {
+    let output = "";
+    let cursor = 0;
+    STANDALONE_CREDENTIAL_PREFIX_PATTERN.lastIndex = 0;
+    for (let match = STANDALONE_CREDENTIAL_PREFIX_PATTERN.exec(value); match; match = STANDALONE_CREDENTIAL_PREFIX_PATTERN.exec(value)) {
+        if (match.index < cursor) {
+            continue;
+        }
+        const valueStart = STANDALONE_CREDENTIAL_PREFIX_PATTERN.lastIndex;
+        const valueEnd = standaloneCredentialValueEnd(value, valueStart);
+        output += value.slice(cursor, match.index);
+        output += `${match[1]} [REDACTED]`;
+        cursor = Math.max(valueEnd, valueStart);
+        STANDALONE_CREDENTIAL_PREFIX_PATTERN.lastIndex = cursor;
+    }
+    output += value.slice(cursor);
+    return output;
+}
+function standaloneCredentialValueEnd(source, valueStart) {
+    if (valueStart >= source.length) {
+        return source.length;
+    }
+    const hardBoundary = earliestPatternIndex(source, valueStart, CAUSAL_BOUNDARY_PATTERN, DIAGNOSTIC_FIELD_BOUNDARY_PATTERN, SOURCE_TRUNCATION_BOUNDARY_PATTERN);
+    const quote = source[valueStart];
+    if (quote === "\"" || quote === "'") {
+        const quotedEnd = quotedValueEnd(source, valueStart);
+        if (quotedEnd !== null
+            && (hardBoundary === null || quotedEnd <= hardBoundary)) {
+            if (isStandaloneCredentialBoundary(source, quotedEnd)) {
+                return quotedEnd;
+            }
+            return standaloneCredentialScalarEnd(source, quotedEnd, hardBoundary);
+        }
+        return hardBoundary ?? source.length;
+    }
+    return standaloneCredentialScalarEnd(source, valueStart, hardBoundary);
+}
+function standaloneCredentialScalarEnd(source, valueStart, hardBoundary) {
+    const scalarBoundary = earliestCharacterIndex(source, valueStart, " \t\r\n,;|");
+    return minimumIndex(hardBoundary, scalarBoundary) ?? source.length;
+}
+function isStandaloneCredentialBoundary(source, index) {
+    return index >= source.length || /^[\s,;|]/u.test(source.slice(index));
+}
+function boundSourceCharacters(value, maximumCharacters) {
+    const limit = Math.max(Math.trunc(maximumCharacters), 0);
+    if (value.length <= limit) {
+        return value;
+    }
+    if (limit <= SOURCE_TRUNCATION_SUFFIX.length) {
+        return SOURCE_TRUNCATION_SUFFIX.slice(0, limit);
+    }
+    return `${value.slice(0, limit - SOURCE_TRUNCATION_SUFFIX.length)}${SOURCE_TRUNCATION_SUFFIX}`;
+}
+function redactBoundedSensitiveFields(value) {
+    let output = "";
+    let cursor = 0;
+    SENSITIVE_FIELD_PATTERN.lastIndex = 0;
+    for (let match = SENSITIVE_FIELD_PATTERN.exec(value); match; match = SENSITIVE_FIELD_PATTERN.exec(value)) {
+        if (match.index < cursor) {
+            continue;
+        }
+        const prefix = match[1] ?? "";
+        const key = match[3] ?? "";
+        const indexSuffix = match[4] ?? "";
+        const bracketSuffix = match[5] ?? "";
+        const valueStart = SENSITIVE_FIELD_PATTERN.lastIndex;
+        const valueEnd = sensitiveFieldValueEnd(value, valueStart, key);
+        output += value.slice(cursor, match.index);
+        output += `${prefix}${key}${indexSuffix}${bracketSuffix}=[REDACTED]`;
+        cursor = Math.max(valueEnd, valueStart);
+        SENSITIVE_FIELD_PATTERN.lastIndex = cursor;
+    }
+    output += value.slice(cursor);
+    return output;
+}
+function redactSensitiveXmlElements(value) {
+    let output = "";
+    let cursor = 0;
+    let sensitiveElementName = null;
+    let sensitiveElementDepth = 0;
+    XML_ELEMENT_TAG_PATTERN.lastIndex = 0;
+    for (let match = XML_ELEMENT_TAG_PATTERN.exec(value); match; match = XML_ELEMENT_TAG_PATTERN.exec(value)) {
+        const isClosingTag = match[1] === "/";
+        const elementName = (match[2] ?? "").toLowerCase();
+        const isSelfClosingTag = match[3] === "/";
+        if (sensitiveElementName === null) {
+            if (isClosingTag
+                || isSelfClosingTag
+                || !isSensitiveXmlElementName(elementName)) {
+                continue;
+            }
+            output += value.slice(cursor, XML_ELEMENT_TAG_PATTERN.lastIndex);
+            output += "[REDACTED]";
+            cursor = XML_ELEMENT_TAG_PATTERN.lastIndex;
+            sensitiveElementName = elementName;
+            sensitiveElementDepth = 1;
+            continue;
+        }
+        if (elementName !== sensitiveElementName) {
+            continue;
+        }
+        if (!isClosingTag && !isSelfClosingTag) {
+            sensitiveElementDepth += 1;
+            continue;
+        }
+        if (!isClosingTag) {
+            continue;
+        }
+        sensitiveElementDepth -= 1;
+        if (sensitiveElementDepth === 0) {
+            output += match[0];
+            cursor = XML_ELEMENT_TAG_PATTERN.lastIndex;
+            sensitiveElementName = null;
+        }
+    }
+    if (sensitiveElementName === null) {
+        output += value.slice(cursor);
+    }
+    return output;
+}
+function isSensitiveXmlElementName(elementName) {
+    const namespaceSeparator = elementName.lastIndexOf(":");
+    const localName = namespaceSeparator < 0
+        ? elementName
+        : elementName.slice(namespaceSeparator + 1);
+    return SENSITIVE_FIELD_NAME_PATTERN.test(localName);
+}
+function sensitiveFieldValueEnd(source, valueStart, key) {
+    if (valueStart >= source.length) {
+        return source.length;
+    }
+    const normalizedKey = key.replace(/[_\s-]/gu, "").toLowerCase();
+    const hardBoundary = earliestPatternIndex(source, valueStart, CAUSAL_BOUNDARY_PATTERN, DIAGNOSTIC_FIELD_BOUNDARY_PATTERN);
+    if (normalizedKey === "authorization"
+        || normalizedKey === "proxyauthorization") {
+        return hardBoundary ?? source.length;
+    }
+    const markerEnd = redactionMarkerPrefixEnd(source, valueStart);
+    let boundarySearchStart = markerEnd ?? valueStart;
+    if (markerEnd === null) {
+        const quotedEnd = quotedValueEnd(source, valueStart);
+        if (quotedEnd !== null) {
+            if (isRecognizedSensitiveValueBoundary(source, quotedEnd)) {
+                return quotedEnd;
+            }
+            boundarySearchStart = quotedEnd;
+        }
+        else {
+            const structuredEnd = structuredValueEnd(source, valueStart);
+            if (structuredEnd !== null) {
+                if (isRecognizedSensitiveValueBoundary(source, structuredEnd)) {
+                    return structuredEnd;
+                }
+                boundarySearchStart = structuredEnd;
+            }
+        }
+    }
+    if (normalizedKey === "connectionstring") {
+        return hardBoundary ?? source.length;
+    }
+    const nextFieldBoundary = earliestPatternIndex(source, boundarySearchStart, NEXT_SENSITIVE_FIELD_PATTERN, STANDALONE_CREDENTIAL_BOUNDARY_PATTERN);
+    const fieldBoundary = minimumIndex(hardBoundary, nextFieldBoundary);
+    if (normalizedKey === "body"
+        || normalizedKey === "payload"
+        || normalizedKey.endsWith("body")
+        || normalizedKey.endsWith("payload")) {
+        return fieldBoundary ?? source.length;
+    }
+    const scalarBoundary = earliestCharacterIndex(source, boundarySearchStart, ";,&}]");
+    return minimumIndex(fieldBoundary, scalarBoundary) ?? source.length;
+}
+function redactionMarkerPrefixEnd(source, valueStart) {
+    const marker = /^(?:\[REDACTED\])+/iu.exec(source.slice(valueStart));
+    return marker ? valueStart + marker[0].length : null;
+}
+function isRecognizedSensitiveValueBoundary(source, index) {
+    if (index >= source.length) {
+        return true;
+    }
+    if (/^[;,&}\]]/u.test(source.slice(index))) {
+        return true;
+    }
+    return earliestPatternIndex(source, index, CAUSAL_BOUNDARY_PATTERN, DIAGNOSTIC_FIELD_BOUNDARY_PATTERN, NEXT_SENSITIVE_FIELD_PATTERN, STANDALONE_CREDENTIAL_BOUNDARY_PATTERN) === index;
+}
+function quotedValueEnd(source, valueStart) {
+    const quote = source[valueStart];
+    if (quote !== "\"" && quote !== "'") {
+        return null;
+    }
+    let escaped = false;
+    for (let index = valueStart + 1; index < source.length; index += 1) {
+        const token = source[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (token === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (token === quote) {
+            return index + 1;
+        }
+    }
+    return null;
+}
+function structuredValueEnd(source, valueStart) {
+    const opening = source[valueStart];
+    if (opening !== "{" && opening !== "[") {
+        return null;
+    }
+    const stack = [opening];
+    let quote = "";
+    let escaped = false;
+    for (let index = valueStart + 1; index < source.length; index += 1) {
+        const token = source[index];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (token === "\\") {
+                escaped = true;
+            }
+            else if (token === quote) {
+                quote = "";
+            }
+            continue;
+        }
+        if (token === "\"" || token === "'") {
+            quote = token;
+            continue;
+        }
+        if (token === "{" || token === "[") {
+            stack.push(token);
+            continue;
+        }
+        if (token === "}" || token === "]") {
+            const expected = token === "}" ? "{" : "[";
+            if (stack.at(-1) !== expected) {
+                return null;
+            }
+            stack.pop();
+            if (!stack.length) {
+                return index + 1;
+            }
+        }
+    }
+    return null;
+}
+function earliestPatternIndex(source, start, ...patterns) {
+    let earliest = null;
+    for (const pattern of patterns) {
+        pattern.lastIndex = start;
+        const match = pattern.exec(source);
+        if (match && (earliest === null || match.index < earliest)) {
+            earliest = match.index;
+        }
+    }
+    return earliest;
+}
+function earliestCharacterIndex(source, start, characters) {
+    let earliest = null;
+    for (const character of characters) {
+        const index = source.indexOf(character, start);
+        if (index >= 0 && (earliest === null || index < earliest)) {
+            earliest = index;
+        }
+    }
+    return earliest;
+}
+function minimumIndex(left, right) {
+    if (left === null)
+        return right;
+    if (right === null)
+        return left;
+    return Math.min(left, right);
+}
+function safeInteger(value) {
+    return Number.isFinite(value) ? String(Math.max(Math.trunc(value), 0)) : "0";
+}
+function truncateUtf8(value, maximumBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maximumBytes) {
+        return value;
+    }
+    const suffix = " [truncated]";
+    const limit = Math.max(maximumBytes - Buffer.byteLength(suffix, "utf8"), 0);
+    let output = "";
+    let bytes = 0;
+    for (const token of value) {
+        const tokenBytes = Buffer.byteLength(token, "utf8");
+        if (bytes + tokenBytes > limit) {
+            break;
+        }
+        output += token;
+        bytes += tokenBytes;
+    }
+    return `${output}${suffix}`;
+}
+function safeLog(logger, level, message) {
+    if (!logger)
+        return;
+    try {
+        const method = logger[level];
+        if (typeof method === "function") {
+            const result = method.call(logger, message);
+            if (result && typeof result.then === "function") {
+                void Promise.resolve(result).catch(() => { });
+            }
+        }
+    }
+    catch {
+        // Operational diagnostics must never change retry or run behavior.
+    }
+}