@loadstrike/loadstrike-sdk 1.0.30401 → 1.0.31601

package/dist/esm/sink-retry-policy.js

@@ -0,0 +1,44 @@
+export const DEFAULT_SINK_RETRY_COUNT = 3;
+export const DEFAULT_SINK_RETRY_BACKOFF_MS = 250;
+export const MAXIMUM_SINK_RETRY_COUNT = 100;
+export const MAXIMUM_TIMER_DELAY_MS = 2147483647;
+export function normalizeSinkRetryCount(value) {
+    const resolved = value === undefined ? DEFAULT_SINK_RETRY_COUNT : value;
+    if (!Number.isFinite(resolved) || resolved <= 0) {
+        return 0;
+    }
+    return Math.min(Math.trunc(resolved), MAXIMUM_SINK_RETRY_COUNT);
+}
+export function normalizeSinkRetryBackoffMs(value) {
+    const resolved = value === undefined ? DEFAULT_SINK_RETRY_BACKOFF_MS : value;
+    if (!Number.isFinite(resolved) || resolved <= 0) {
+        return 0;
+    }
+    return Math.min(Math.trunc(resolved), MAXIMUM_TIMER_DELAY_MS);
+}
+export function sinkRetryDelayMs(baseDelayMs, retryNumber) {
+    if (baseDelayMs <= 0) {
+        return 0;
+    }
+    let delayMs = Math.min(Math.trunc(baseDelayMs), MAXIMUM_TIMER_DELAY_MS);
+    const doublings = Math.max(Math.trunc(retryNumber) - 1, 0);
+    for (let index = 0; index < doublings; index += 1) {
+        if (delayMs >= Math.ceil(MAXIMUM_TIMER_DELAY_MS / 2)) {
+            return MAXIMUM_TIMER_DELAY_MS;
+        }
+        delayMs *= 2;
+    }
+    return delayMs;
+}
+export async function waitForSinkRetryDelay(delayMs) {
+    if (delayMs <= 0) {
+        await cooperativeSinkRetryYield();
+        return;
+    }
+    await new Promise((resolve) => {
+        setTimeout(resolve, Math.min(delayMs, MAXIMUM_TIMER_DELAY_MS));
+    });
+}
+export async function cooperativeSinkRetryYield() {
+    await new Promise((resolve) => setImmediate(resolve));
+}

package/dist/esm/sinks.js

@@ -6,7 +6,26 @@ import { createSocket } from "node:dgram";
 import { gzip } from "node:zlib";
 import { Pool } from "pg";
 import { serializeIterationObservationBatchGzipJson } from "./iteration-observations.js";
+import { redactIterationObservationSecrets } from "./iteration-observation-diagnostics.js";
 const PORTAL_RUN_TOKEN_PROVIDER = Symbol.for("loadstrike.internal.portal-run-token-provider");
+const MAXIMUM_HTTP_RESPONSE_BODY_BYTES = 256 * 1024;
+const MAXIMUM_HTTP_METADATA_CHARACTERS = 256;
+const HTTP_METADATA_TRUNCATION_SUFFIX = " [truncated]";
+class ReportingSinkHttpError extends Error {
+    constructor(sinkName, status, statusText, requestId) {
+        const normalizedStatus = Number.isFinite(status) ? Math.max(Math.trunc(status), 0) : 0;
+        const normalizedStatusText = normalizeHttpMetadata(statusText);
+        const normalizedRequestId = normalizeHttpMetadata(requestId);
+        super(`${sinkName} write failed with HTTP status ${normalizedStatus}`
+            + (normalizedStatusText ? ` ${normalizedStatusText}` : "")
+            + (normalizedRequestId ? ` (requestId=${normalizedRequestId})` : "")
+            + ".");
+        this.name = "ReportingSinkHttpError";
+        this.status = normalizedStatus;
+        this.statusText = normalizedStatusText;
+        this.requestId = normalizedRequestId;
+    }
+}
 function gzipJsonAsync(value) {
     const json = Buffer.from(JSON.stringify(value), "utf8");
     return new Promise((resolve, reject) => {
@@ -2202,6 +2221,7 @@ function removeSdkPercentileFields(event) {
 }
 function createIterationObservationEvents(session, batch) {
     const events = [];
+    const occurredUtc = dateFromUtcNanoseconds(batch.createdUtcNs);
     for (const observation of batch.observations) {
         const tags = {
             run_id: batch.runId,
@@ -2214,7 +2234,7 @@ function createIterationObservationEvents(session, batch) {
         events.push({
             runId: batch.runId,
             eventType: "iteration.observation",
-            occurredUtc: new Date(),
+            occurredUtc,
             sessionId: batch.sessionId,
             testSuite: session.testSuite,
             testName: session.testName,
@@ -2249,7 +2269,7 @@ function createIterationObservationEvents(session, batch) {
             events.push({
                 runId: batch.runId,
                 eventType: "iteration.step",
-                occurredUtc: new Date(),
+                occurredUtc,
                 sessionId: batch.sessionId,
                 testSuite: session.testSuite,
                 testName: session.testName,
@@ -2280,10 +2300,11 @@ function createIterationObservationEvents(session, batch) {
     return events;
 }
 function createIterationCompletionEvents(session, completion) {
+    const occurredUtc = dateFromUtcNanoseconds(completion.completedUtcNs);
     return [{
             runId: completion.runId,
             eventType: "observation.stream.completed",
-            occurredUtc: new Date(),
+            occurredUtc,
             sessionId: completion.sessionId,
             testSuite: session.testSuite,
             testName: session.testName,
@@ -2342,6 +2363,22 @@ function portalEventId(event, index) {
     });
     return `lsr_${createHash("sha256").update(material).digest("hex").slice(0, 40)}`;
 }
+function dateFromUtcNanoseconds(value) {
+    try {
+        const nanoseconds = BigInt(value);
+        if (nanoseconds < 0n) {
+            return new Date(0);
+        }
+        const milliseconds = nanoseconds / 1000000n;
+        const numeric = Number(milliseconds);
+        return Number.isFinite(numeric) && numeric <= 8640000000000000
+            ? new Date(numeric)
+            : new Date(0);
+    }
+    catch {
+        return new Date(0);
+    }
+}
 function addMeasurementFields(fields, prefix, measurement) {
     const request = measurement?.request ?? { count: 0, percent: 0, rps: 0 };
     const latency = measurement?.latency ?? {
@@ -3533,22 +3570,85 @@ async function postWithTimeout(fetchImpl, url, init, timeoutMs, sinkName) {
     const timer = setTimeout(() => controller.abort(), Math.max(timeoutMs, 1));
     try {
         const response = await fetchImpl(url, { ...init, signal: controller.signal });
-        const body = await readResponseBodyText(response);
         if (!response.ok) {
-            throw new Error(`${sinkName} write failed with status ${response.status}: ${body}`);
+            throw new ReportingSinkHttpError(sinkName, response.status, readHttpResponseStatusText(response), readHttpResponseRequestId(response));
         }
-        return body;
+        return await readResponseBodyText(response);
     }
     finally {
         clearTimeout(timer);
     }
 }
 async function readResponseBodyText(response) {
-    const candidate = response;
-    if (typeof candidate.text !== "function") {
+    const body = response.body;
+    if (body && typeof body.getReader === "function") {
+        const reader = body.getReader();
+        const chunks = [];
+        let bytes = 0;
+        try {
+            while (true) {
+                const next = await reader.read();
+                if (next.done)
+                    break;
+                if (!next.value)
+                    continue;
+                if (bytes + next.value.byteLength > MAXIMUM_HTTP_RESPONSE_BODY_BYTES) {
+                    await reader.cancel();
+                    throw new Error("Reporting sink response exceeded the bounded response limit.");
+                }
+                chunks.push(next.value);
+                bytes += next.value.byteLength;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
+    }
+    return "";
+}
+function readHttpResponseStatusText(response) {
+    try {
+        return normalizeHttpMetadata(response.statusText);
+    }
+    catch {
+        return "";
+    }
+}
+function readHttpResponseRequestId(response) {
+    for (const name of [
+        "x-request-id",
+        "x-correlation-id",
+        "request-id",
+        "traceparent"
+    ]) {
+        try {
+            const value = response.headers?.get(name);
+            if (value) {
+                return normalizeHttpMetadata(value);
+            }
+        }
+        catch {
+            return "";
+        }
+    }
+    return "";
+}
+function normalizeHttpMetadata(value) {
+    let text;
+    try {
+        const source = String(value ?? "");
+        text = source.length <= MAXIMUM_HTTP_METADATA_CHARACTERS
+            ? source
+            : source.slice(0, MAXIMUM_HTTP_METADATA_CHARACTERS - HTTP_METADATA_TRUNCATION_SUFFIX.length) + HTTP_METADATA_TRUNCATION_SUFFIX;
+    }
+    catch {
         return "";
     }
-    return String(await candidate.text());
+    return redactIterationObservationSecrets(Buffer.from(text, "utf8").toString("utf8")
+        .replace(/[\u0000-\u001F\u007F-\u009F]/gu, " ")
+        .replace(/\s{2,}/gu, " ")
+        .trim());
 }
 function validatePortalIngestResponse(responseBody) {
     const text = String(responseBody ?? "").trim();
@@ -3601,6 +3701,8 @@ export const __loadstrikeTestExports = {
     cloneScenarioStats,
     cloneSessionStartInfo,
     createFinalStatsEvents,
+    createIterationCompletionEvents,
+    createIterationObservationEvents,
     createRealtimeStatsEvents,
     createRunResultEvents,
     createReportingEvent,
@@ -3617,6 +3719,7 @@ export const __loadstrikeTestExports = {
     normalizeStringMap,
     optionNumber,
     optionString,
+    portalEventPayload,
     pickBooleanValue,
     pickRecordValue,
     postWithTimeout,

package/dist/esm/transports.js

@@ -596,14 +596,10 @@ class WebSocketEndpointDefinitionModel extends TrafficEndpointDefinitionModel {
             parsed = new URL(url);
         }
         catch {
-            // Diagnostic text only; no connection is opened here.
-            // nosemgrep: vulnerability-tools.semgrep-rules.javascript.lang.security.detect-insecure-websocket
-            throw new Error("Url must be an absolute ws:// or wss:// URI.");
+            throw new Error("Url must be an absolute WebSocket URI using the ws or wss scheme.");
         }
         if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
-            // Diagnostic text only; no connection is opened here.
-            // nosemgrep: vulnerability-tools.semgrep-rules.javascript.lang.security.detect-insecure-websocket
-            throw new Error("Url must be an absolute ws:// or wss:// URI.");
+            throw new Error("Url must be an absolute WebSocket URI using the ws or wss scheme.");
         }
         if (this.ConnectTimeoutSeconds <= 0) {
             throw new RangeError("ConnectTimeout must be greater than zero.");
@@ -3132,14 +3128,10 @@ function validateWebSocketEndpoint(endpoint, mode) {
         parsed = new URL(url);
     }
     catch {
-        // Diagnostic text only; no connection is opened here.
-        // nosemgrep: vulnerability-tools.semgrep-rules.javascript.lang.security.detect-insecure-websocket
-        throw new Error("Url must be an absolute ws:// or wss:// URI.");
+        throw new Error("Url must be an absolute WebSocket URI using the ws or wss scheme.");
     }
     if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
-        // Diagnostic text only; no connection is opened here.
-        // nosemgrep: vulnerability-tools.semgrep-rules.javascript.lang.security.detect-insecure-websocket
-        throw new Error("Url must be an absolute ws:// or wss:// URI.");
+        throw new Error("Url must be an absolute WebSocket URI using the ws or wss scheme.");
     }
     const connectMs = optionNumber(options, "ConnectTimeoutMs", "connectTimeoutMs");
     const connectSeconds = optionNumber(options, "ConnectTimeoutSeconds", "connectTimeoutSeconds", "ConnectTimeout", "connectTimeout");
@@ -3569,7 +3561,13 @@ function extractJsonPath(value, arrayPath) {
     if (!normalized) {
         return value;
     }
-    const tokens = normalized.replace(/\[(\d+)\]/g, ".$1").split(".").filter((x) => x.length > 0);
+    let tokens;
+    try {
+        tokens = safeJsonPathSegments(normalized.replace(/\[(\d+)\]/g, ".$1"));
+    }
+    catch {
+        return null;
+    }
     for (const token of tokens) {
         if (current == null) {
             return null;
@@ -3579,13 +3577,17 @@ function extractJsonPath(value, arrayPath) {
             if (!Number.isInteger(index) || index < 0 || index >= current.length) {
                 return null;
             }
-            current = current[index];
+            current = current.at(index);
             continue;
         }
-        if (!isRecord(current) || !(token in current)) {
+        if (!isRecord(current)) {
             return null;
         }
-        current = current[token];
+        const descriptor = Object.getOwnPropertyDescriptor(current, token);
+        if (!descriptor || !("value" in descriptor)) {
+            return null;
+        }
+        current = descriptor.value;
     }
     return current;
 }
@@ -3602,7 +3604,7 @@ function parseMaybeJson(value) {
     }
 }
 function headersToRecord(value) {
-    const headers = {};
+    const headers = Object.create(null);
     value.forEach((headerValue, key) => {
         headers[key] = headerValue;
     });
@@ -3956,11 +3958,22 @@ function extractTrackingValue(payload, selector) {
             return null;
         }
         let current = body;
-        for (const segment of selector.slice("json:".length).trim().replace(/^\$\./, "").split(".").filter(Boolean)) {
+        const path = selector.slice("json:".length).trim().replace(/^\$\./, "");
+        let segments;
+        try {
+            segments = safeJsonPathSegments(path);
+        }
+        catch {
+            return null;
+        }
+        for (const segment of segments) {
             if (!isRecord(current)) {
                 return null;
             }
-            current = current[segment];
+            if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+                return null;
+            }
+            current = readOwnJsonProperty(current, segment);
         }
         return current == null ? null : String(current);
     }
@@ -3991,23 +4004,61 @@ function injectTrackingValue(payload, selector, value) {
 }
 function setJsonBodyValue(body, path, value) {
     const target = parseBodyObject(body) ?? {};
-    const clone = cloneBody(target);
-    const segments = path.split(".").filter(Boolean);
+    const clone = cloneJsonRecord(target);
+    const segments = safeJsonPathSegments(path);
     if (!segments.length) {
         return clone;
     }
     let current = clone;
     for (let i = 0; i < segments.length - 1; i += 1) {
         const segment = segments[i];
-        const next = current[segment];
+        let next = readOwnJsonProperty(current, segment);
         if (!isRecord(next)) {
-            current[segment] = {};
+            next = {};
+            defineJsonProperty(current, segment, next);
         }
-        current = current[segment];
+        current = next;
     }
-    current[segments[segments.length - 1]] = value;
+    defineJsonProperty(current, segments[segments.length - 1], value);
     return clone;
 }
+const FORBIDDEN_JSON_PATH_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+function safeJsonPathSegments(path) {
+    const segments = path.split(".").filter(Boolean);
+    const forbidden = segments.find((segment) => FORBIDDEN_JSON_PATH_SEGMENTS.has(segment));
+    if (forbidden) {
+        throw new Error(`Tracking selector contains forbidden JSON path segment '${forbidden}'.`);
+    }
+    return segments;
+}
+function defineJsonProperty(target, key, value) {
+    Object.defineProperty(target, key, {
+        configurable: true,
+        enumerable: true,
+        value,
+        writable: true
+    });
+}
+function readOwnJsonProperty(target, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(target, key);
+    return descriptor && "value" in descriptor ? descriptor.value : undefined;
+}
+function cloneJsonRecord(source) {
+    const target = {};
+    for (const [key, value] of Object.entries(source)) {
+        defineJsonProperty(target, key, cloneJsonValue(value));
+    }
+    return target;
+}
+function cloneJsonValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => cloneJsonValue(entry));
+    }
+    if (isRecord(value)) {
+        return cloneJsonRecord(value);
+    }
+    return value;
+}
 function parseBodyObject(body) {
     if (body instanceof Uint8Array) {
         return parseBodyObject(new TextDecoder().decode(body));
@@ -4616,8 +4667,10 @@ export const __loadstrikeTestExports = {
     createNatsHeaders,
     createRedisStreamPayload,
     deserializeBrokerPayloadBody,
+    extractJsonPath,
     extractTrackingValue,
     fromKafkaHeaders,
+    headersToRecord,
     headerValue,
     attachDotNetTrackingPayloadAliases,
     attachPayloadHelpers,

package/dist/types/iteration-observation-diagnostics.d.ts

@@ -0,0 +1,21 @@
+export interface IterationObservationDiagnosticLogger {
+    debug(message: string): void | PromiseLike<void>;
+    warn(message: string): void | PromiseLike<void>;
+    error(message: string): void | PromiseLike<void>;
+}
+export interface IterationObservationDiagnosticContext {
+    sinkName: string;
+    operation: "observation-batch" | "observation-stream-completion" | "reporting-sink-action";
+    phase?: string;
+    runId: string;
+    resultOwnerId: string;
+    batchId?: string;
+    batchSequence64?: string;
+    observationCount: number;
+    attempt: number;
+    maximumAttempts: number;
+    nextDelayMs?: number;
+}
+export declare function logIterationObservationFailure(logger: IterationObservationDiagnosticLogger | undefined, level: "warn" | "error", context: IterationObservationDiagnosticContext, error: unknown): void;
+export declare function logIterationObservationRecovery(logger: IterationObservationDiagnosticLogger | undefined, context: IterationObservationDiagnosticContext): void;
+export declare function redactIterationObservationSecrets(value: string): string;

package/dist/types/iteration-observations.d.ts

@@ -1,3 +1,4 @@
+import { type IterationObservationDiagnosticLogger } from "./iteration-observation-diagnostics.js";
 export declare const ITERATION_OBSERVATION_SCHEMA_VERSION = "loadstrike.iteration-observation/1";
 export declare const ITERATION_OBSERVATION_BATCH_SCHEMA_VERSION = "loadstrike.iteration-batch/1";
 export declare const ITERATION_OBSERVATION_STREAM_COMPLETION_SCHEMA_VERSION = "loadstrike.iteration-stream-completion/1";
@@ -192,6 +193,9 @@ export interface IterationObservationReporterOptions {
     buffer?: ProcessIterationObservationBuffer;
     clock?: IterationObservationClock;
     skipValidation?: boolean;
+    sinkRetryCount?: number;
+    sinkRetryBackoffMs?: number;
+    logger?: IterationObservationDiagnosticLogger;
 }
 export declare class IterationObservationReporter {
     private readonly options;
@@ -215,6 +219,7 @@ export declare class IterationObservationReporter {
     capture(observation: LoadStrikeIterationObservationV1): boolean;
     flushNow(): void;
     sealAndDrain(): Promise<IterationObservationDeliveryResult>;
+    private completeWithRetries;
     buildWarnings(): IterationObservationGeneratorWarning[];
     private createBatch;
     private createCompletion;

package/dist/types/local-report-input.d.ts

@@ -0,0 +1,6 @@
+import type { ReportHistoryProjection } from "./report-history.js";
+export interface LocalReportInput {
+    history: ReportHistoryProjection;
+}
+export declare function emptyLocalReportInput(): LocalReportInput;
+export declare function distributedLocalReportInput(): LocalReportInput;

package/dist/types/report-history.d.ts

@@ -0,0 +1,124 @@
+export declare const REPORT_HISTORY_MAX_POINTS = 2048;
+export declare const REPORT_HISTORY_MAX_SCALAR_VALUES = 262144;
+export type ReportHistoryReasonCategory = "capture_failure" | "budget_pressure" | "distributed_temporal_aggregation_unavailable";
+export interface ReportHistoryMeasurement {
+    count: number;
+    bytes: number;
+    approximate?: boolean;
+    percent50Ms?: number;
+    percent75Ms?: number;
+    percent95Ms?: number;
+    percent99Ms?: number;
+}
+export interface ReportHistoryScenario {
+    scenarioName: string;
+    sortIndex?: number;
+    all?: ReportHistoryMeasurement;
+    ok?: ReportHistoryMeasurement;
+    failed?: ReportHistoryMeasurement;
+}
+export interface ReportHistoryPoint {
+    elapsedSeconds: number;
+    terminal: boolean;
+    scenarios: ReportHistoryScenario[];
+}
+export interface AvailableReportHistoryProjection {
+    status: "available";
+    points: ReportHistoryPoint[];
+}
+export interface UnavailableReportHistoryProjection {
+    status: "unavailable";
+    reasonCategory: ReportHistoryReasonCategory;
+    points: [];
+}
+export type ReportHistoryProjection = AvailableReportHistoryProjection | UnavailableReportHistoryProjection;
+export interface ReportHistoryRateSeries {
+    scenarioName: string;
+    values: Array<number | null>;
+}
+export interface ReportHistoryCollectorOptions {
+    scenarioCount: number;
+    maxPoints?: number;
+    nowNs?: () => bigint;
+    onCaptureError?: (error: unknown) => void;
+}
+/**
+ * Bounded report-only cumulative telemetry. This type is intentionally not
+ * exported from the package entry point and never participates in public run,
+ * sink, observation, or cluster payloads.
+ */
+export declare class ReportHistoryCollector {
+    readonly pointLimit: number;
+    private readonly nowNs;
+    private readonly onCaptureError?;
+    private points;
+    private startNs;
+    private terminalCaptured;
+    private reasonCategory;
+    constructor(options: ReportHistoryCollectorOptions);
+    get available(): boolean;
+    start(startNs?: bigint): void;
+    capture(snapshotFactory: () => readonly ReportHistoryScenario[]): boolean;
+    finalize(snapshotFactory: () => readonly ReportHistoryScenario[]): boolean;
+    disable(reasonCategory: ReportHistoryReasonCategory): void;
+    toProjection(): ReportHistoryProjection;
+    private captureSafely;
+    private compact;
+}
+export interface ReportHistoryWorkerOptions {
+    collector: ReportHistoryCollector;
+    cadenceSeconds: number;
+    snapshotFactory: () => readonly ReportHistoryScenario[];
+    nowNs?: () => bigint;
+    onFailure?: (category: ReportHistoryReasonCategory, exceptionClasses: string) => void;
+}
+interface ReportHistoryLifecycleWorker {
+    start(): void;
+    stopAndFinalize(): void;
+    stopWithoutFinalizing(): void;
+}
+/**
+ * Coordinates one private history worker across every local scenario. The
+ * first measured phase establishes the history clock, and the last scenario
+ * leaving execution records the terminal point before scenario cleanup.
+ */
+export declare class ReportHistoryLifecycleCoordinator {
+    private readonly worker;
+    private readonly scenarioCount;
+    private readonly terminalBoundary;
+    private releaseTerminalBoundary;
+    private measuredLoadStarted;
+    private endedScenarios;
+    private completed;
+    private terminalBoundaryReleased;
+    constructor(worker: ReportHistoryLifecycleWorker & {
+        scenarioCount?: number;
+    });
+    scenarioBombingStarted(): void;
+    scenarioExecutionEnded(): Promise<void>;
+    stopWithoutFinalizing(): void;
+    private releaseBoundary;
+}
+/**
+ * Owns the report timer. Every cadence calculation, timeout callback, snapshot,
+ * and projection is exception-bounded so report history can never fail a run.
+ */
+export declare class ReportHistoryWorker {
+    private readonly options;
+    private readonly nowNs;
+    private timer;
+    private cadenceNs;
+    private nextDeadlineNs;
+    private running;
+    constructor(options: ReportHistoryWorkerOptions);
+    get started(): boolean;
+    start(): void;
+    stopAndFinalize(): void;
+    stopWithoutFinalizing(): void;
+    private scheduleNext;
+    private onTimer;
+    private fail;
+}
+export declare function sanitizedExceptionClassChain(error: unknown): string;
+export declare function deriveScenarioRates(points: readonly ReportHistoryPoint[]): ReportHistoryRateSeries[];
+export {};

package/dist/types/reporting-svg.d.ts

@@ -0,0 +1,2 @@
+export declare const REPORT_SVG_CSS: string;
+export declare const REPORT_SVG_SCRIPT: string;

package/dist/types/reporting.d.ts

@@ -1,3 +1,4 @@
+import { type LocalReportInput } from "./local-report-input.js";
 type ReportRecord = Record<string, any>;
 type ReportTab = [string, string, string];
 declare function buildUngroupedCorrelationChartPayload(rows: ReportRecord[]): ReportRecord;
@@ -14,7 +15,7 @@ declare function buildDotnetMetricHtml(nodeStats: ReportRecord): string;
 declare function buildDotnetGroupedCorrelationSummaryHtml(rows: ReportRecord[], groupedChartKey: string): string;
 declare function buildDotnetUngroupedCorrelationSummaryHtml(rows: ReportRecord[], groupedChartKey: string): string;
 declare function buildDotnetPluginHints(plugin: ReportRecord): string;
-declare function buildDotnetHtmlTabs(nodeStats: ReportRecord): ReportTab[];
+declare function buildDotnetHtmlTabs(nodeStats: ReportRecord, localReportInput?: LocalReportInput): ReportTab[];
 /**
  * Exposes the build dotnet txt report operation. Use this when interacting with the SDK through this surface.
  */
@@ -28,9 +29,11 @@ export declare function buildDotnetCsvReport(nodeStats: ReportRecord): string;
  */
 export declare function buildDotnetMarkdownReport(nodeStats: ReportRecord): string;
 /**
- * Exposes the build dotnet html report operation. Use this when interacting with the SDK through this surface.
+ * Builds the portable single-file HTML report. The optional second argument is
+ * an internal report-only carrier used by the native runner and is never added
+ * to public result, sink, observation, or cluster payloads.
  */
-export declare function buildDotnetHtmlReport(nodeStats: ReportRecord): string;
+export declare function buildDotnetHtmlReport(nodeStats: ReportRecord, localReportInput?: LocalReportInput): string;
 export declare const __loadstrikeTestExports: {
     buildDotnetFailedResponseContent: typeof buildDotnetFailedResponseContent;
     buildDotnetFailedResponseHtml: typeof buildDotnetFailedResponseHtml;