@loadstrike/loadstrike-sdk 1.0.31001 → 1.0.31601

package/dist/esm/runtime.js

@@ -7,6 +7,8 @@ import { DistributedClusterAgent, DistributedClusterCoordinator, buildLoadEngine
 import { CorrelationStoreConfiguration, CrossPlatformTrackingRuntime, RedisCorrelationStore, RedisCorrelationStoreOptions, TrackingFieldSelector } from "./correlation.js";
 import { EndpointAdapterFactory, LOADSTRIKE_TRACE_ID_TRACKING_FIELD } from "./transports.js";
 import { buildDotnetCsvReport, buildDotnetHtmlReport, buildDotnetMarkdownReport, buildDotnetTxtReport } from "./reporting.js";
+import { ReportHistoryCollector, ReportHistoryLifecycleCoordinator, ReportHistoryWorker, sanitizedExceptionClassChain } from "./report-history.js";
+import { distributedLocalReportInput, emptyLocalReportInput } from "./local-report-input.js";
 import { PortalReportingSink, cloneReportingSinkForRun } from "./sinks.js";
 import { LoadEngineV2ExecutionBudget, buildLoadEngineV2TrafficMixSeedId, LoadStrikeHistogramV1, parseLoadEngineV2HistogramArtifact, serializeLoadEngineV2HistogramArtifact, classifyLoadEngineV2Arrival, loadEngineV2FixedArrivalCount, loadEngineV2FixedDeadlineNs, loadEngineV2LatenessToleranceNs, loadEngineV2TrafficMixLaneUnitCount, loadEngineV2TrafficMixOwnedUnits, planRampingInjectionDeadlines, planRampingConstantDeadlines, planRandomInjectionDeadlines, fnv1a32 } from "./load-engine-v2.js";
 import { DEFAULT_ITERATION_OBSERVATION_SETTINGS, IterationObservationReporter, createIterationObservation, createIterationStepObservation, utcNowNs, validateIterationObservationSettings } from "./iteration-observations.js";
@@ -283,6 +285,28 @@ class MeasurementAccumulator {
             moreOrEq1200: left.moreOrEq1200 + right.moreOrEq1200
         }, allRequestCount, durationMs);
     }
+    /**
+     * Projects only the cumulative fields used by the private HTML-report
+     * history. Legacy distributions deliberately omit latency so this cadence
+     * path never scans their retained per-request arrays.
+     */
+    buildReportHistoryMeasurement() {
+        return projectNativeReportHistoryMeasurement(this.count, this.allBytes, this.useHistogram ? this.latencyHistogram : undefined);
+    }
+    /**
+     * Combines only bounded native latency state plus exact counters. It does
+     * not materialize status rows or any public measurement DTO.
+     */
+    buildCombinedReportHistoryMeasurement(other) {
+        const count = this.count + other.count;
+        const bytes = this.allBytes + other.allBytes;
+        if (!this.useHistogram || !other.useHistogram) {
+            return projectNativeReportHistoryMeasurement(count, bytes);
+        }
+        const latency = this.latencyHistogram.clone();
+        latency.merge(other.latencyHistogram);
+        return projectNativeReportHistoryMeasurement(count, bytes, latency);
+    }
     histogramSnapshot() {
         return {
             count: this.count,
@@ -296,6 +320,24 @@ class MeasurementAccumulator {
         };
     }
 }
+function projectNativeReportHistoryMeasurement(count, bytes, latency) {
+    const measurement = {
+        count,
+        bytes,
+        approximate: latency?.maxRelativeError !== undefined
+            && latency.maxRelativeError > 0
+    };
+    if (!latency || latency.count === 0n) {
+        return measurement;
+    }
+    return {
+        ...measurement,
+        percent50Ms: Number(latency.percentile(0.5)) / 1000,
+        percent75Ms: Number(latency.percentile(0.75)) / 1000,
+        percent95Ms: Number(latency.percentile(0.95)) / 1000,
+        percent99Ms: Number(latency.percentile(0.99)) / 1000
+    };
+}
 function buildHistogramMeasurement(snapshot, allRequestCount, durationMs) {
     const count = snapshot.count;
     const totalDurationMs = Math.max(durationMs, 0);
@@ -634,6 +676,21 @@ class ScenarioStatsAccumulator {
         step.record(reply, observedLatencyMs);
         return step.sortIndex;
     }
+    /**
+     * Captures the bounded, private history view without building scenario
+     * steps, status rows, plugins, aliases, or any other public result shape.
+     */
+    buildReportHistorySnapshot() {
+        const ok = this.ok.buildReportHistoryMeasurement();
+        const failed = this.fail.buildReportHistoryMeasurement();
+        return {
+            scenarioName: this.scenarioName,
+            sortIndex: this.sortIndex,
+            all: this.ok.buildCombinedReportHistoryMeasurement(this.fail),
+            ...(ok.count > 0 ? { ok } : {}),
+            ...(failed.count > 0 ? { failed } : {})
+        };
+    }
     /**
      * Builds the configured payload or helper object.
      * Use this when all builder inputs are ready to be materialized.
@@ -3481,6 +3538,58 @@ export class LoadStrikeRunner {
         licenseSession = await licenseClient.acquireLicenseLease(licensePayload);
         const loggerSetup = createLoggerSetup(this.options.loggerConfig, this.options.minimumLogLevel, this.options, testInfo, nodeInfo);
         const runLogger = loggerSetup.logger;
+        const htmlReportHistoryRequested = (this.options.reportsEnabled ?? true)
+            && normalizeReportFormats(this.options.reportFormats ?? ["html", "txt", "csv", "md"]).includes("html");
+        const distributedReportHistory = isDistributedReportHistoryExecution(clusterMode, this.options);
+        let localReportInput = htmlReportHistoryRequested
+            && distributedReportHistory
+            ? distributedLocalReportInput()
+            : emptyLocalReportInput();
+        let reportHistoryCollector;
+        let reportHistoryLifecycle;
+        if (htmlReportHistoryRequested && !distributedReportHistory) {
+            const warnReportHistoryFailure = (category, error) => {
+                const exceptionClasses = error === undefined
+                    ? ""
+                    : `; exception_classes=${sanitizedExceptionClassChain(error)}`;
+                try {
+                    runLogger.warn(`LoadStrike report history unavailable: ${category}${exceptionClasses}.`);
+                }
+                catch {
+                    // Report-only diagnostics are best-effort.
+                }
+            };
+            reportHistoryCollector = new ReportHistoryCollector({
+                scenarioCount: selectedScenarios.length,
+                onCaptureError: (error) => warnReportHistoryFailure("capture_failure", error)
+            });
+            if (!reportHistoryCollector.available) {
+                warnReportHistoryFailure("budget_pressure");
+            }
+            const snapshotFactory = () => Array.from(scenarioAccumulators.values())
+                .map((value) => value.buildReportHistorySnapshot())
+                .sort((left, right) => (left.sortIndex ?? 0) - (right.sortIndex ?? 0)
+                || left.scenarioName.localeCompare(right.scenarioName));
+            const reportHistoryWorker = new ReportHistoryWorker({
+                collector: reportHistoryCollector,
+                cadenceSeconds: resolvedReportHistoryCadenceSeconds(this.options.reportingIntervalSeconds ?? 5),
+                snapshotFactory,
+                onFailure: (category, exceptionClasses) => {
+                    try {
+                        runLogger.warn(`LoadStrike report history unavailable: ${category}; exception_classes=${exceptionClasses}.`);
+                    }
+                    catch {
+                        // Report-only diagnostics are best-effort.
+                    }
+                }
+            });
+            reportHistoryLifecycle = new ReportHistoryLifecycleCoordinator({
+                scenarioCount: selectedScenarios.length,
+                start: () => reportHistoryWorker.start(),
+                stopAndFinalize: () => reportHistoryWorker.stopAndFinalize(),
+                stopWithoutFinalizing: () => reportHistoryWorker.stopWithoutFinalizing()
+            });
+        }
         const scenarioStartInfos = selectedScenarios.map((scenario, index) => {
             const startInfo = {
                 scenarioName: scenario.name,
@@ -3590,7 +3699,7 @@ export class LoadStrikeRunner {
                 realtimeInFlight = false;
             }
         };
-        const reportingIntervalMs = Math.max(Math.trunc((this.options.reportingIntervalSeconds ?? 5) * 1000), 1);
+        const reportingIntervalMs = boundedReportingIntervalMs(this.options.reportingIntervalSeconds ?? 5);
         const triggerRealtimeSnapshot = () => {
             if (realtimeCurrent) {
                 return;
@@ -3677,6 +3786,7 @@ export class LoadStrikeRunner {
                     iterationObservationRunId,
                     iterationObservationResultOwnerId,
                     iterationObservationProcessGroup,
+                    reportHistoryLifecycle,
                     executeScenarioInvocation: (targetScenario, context, operation) => this.executeScenarioInvocation(targetScenario, context, operation),
                     invokeBeforeScenario: (runtimePolicies, scenarioName) => this.invokeBeforeScenario(runtimePolicies, scenarioName, policyErrors, runtimePolicyErrorMode),
                     invokeAfterScenario: (runtimePolicies, scenarioName, stats) => this.invokeAfterScenario(runtimePolicies, scenarioName, stats, policyErrors, runtimePolicyErrorMode),
@@ -3764,9 +3874,14 @@ export class LoadStrikeRunner {
                 ...iterationObservationReporter.buildWarnings()
             ];
             result.pluginsData = mergePluginData(result.pluginsData, await this.collectPluginData(plugins, attachRunResultAliases(result), pluginLifecycleErrors));
+            if (reportHistoryCollector) {
+                localReportInput = {
+                    history: reportHistoryCollector.toProjection()
+                };
+            }
             const finalizedResult = attachRunResultAliases(result);
             finalizedResult.logFiles = mergeStringArrays(finalizedResult.logFiles, loggerSetup.logFiles);
-            finalizedResult.reportFiles = this.writeReports(finalizedResult);
+            finalizedResult.reportFiles = this.writeReports(finalizedResult, localReportInput);
             finalizedResult.disabledSinks = sinkStates.filter((x) => x.disabled).map((x) => x.name);
             await this.emitRunResult(sinkStates, finalizedResult, sinkRetryCount, sinkRetryBackoffMs, sinkErrors, testInfo.sessionId, runLogger);
             await this.stopSinks(sinkStates, sinkRetryCount, sinkRetryBackoffMs, sinkErrors, testInfo.sessionId, runLogger);
@@ -3777,6 +3892,7 @@ export class LoadStrikeRunner {
             return finalizedResult;
         }
         finally {
+            reportHistoryLifecycle?.stopWithoutFinalizing();
             await stopRealtimeReporting();
             if (!iterationObservationsFinalized) {
                 await iterationObservationReporter.sealAndDrain().catch(() => { });
@@ -4254,7 +4370,7 @@ export class LoadStrikeRunner {
             message: String(error ?? "runtime policy callback failed")
         });
     }
-    writeReports(result) {
+    writeReports(result, localReportInput = emptyLocalReportInput()) {
         const reportsEnabled = this.options.reportsEnabled ?? true;
         if (!reportsEnabled) {
             return [];
@@ -4279,7 +4395,7 @@ export class LoadStrikeRunner {
                 writeFileSync(path, buildDotnetMarkdownReport(nodeStats), "utf8");
             }
             else if (format === "html") {
-                writeFileSync(path, buildDotnetHtmlReport(nodeStats), "utf8");
+                writeFileSync(path, buildDotnetHtmlReport(nodeStats, localReportInput), "utf8");
             }
             written.push(path);
         }
@@ -4312,6 +4428,19 @@ function hasPluginRows(value) {
     }
     return value.tables.some((table) => Array.isArray(table.rows) && table.rows.length > 0);
 }
+function boundedReportingIntervalMs(seconds) {
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        return 1;
+    }
+    const milliseconds = seconds * 1000;
+    if (!Number.isFinite(milliseconds) || milliseconds >= 2147483647) {
+        return 2147483647;
+    }
+    return Math.max(Math.trunc(milliseconds), 1);
+}
+function resolvedReportHistoryCadenceSeconds(seconds) {
+    return boundedReportingIntervalMs(seconds) / 1000;
+}
 async function executeV2FixedArrivals(args) {
     const { rate, intervalNs, totalArrivals, budget, cancellationToken, shouldStopNow, nextInstanceInfo, runBombingInvocation, logger, scenarioName, deadlineOffsetsNs, tolerancesNs, ownedOrdinals, shardIndex = 0, shardCount = 1, telemetry, segment } = args;
     const segmentStartNs = process.hrtime.bigint();
@@ -4448,7 +4577,15 @@ function maxBigInt(left, right) {
     return left > right ? left : right;
 }
 async function executeScenarioRuntime(args) {
-    const { scenario, scenarioIndex, scenarioCount, options, logger, nodeInfo, testInfo, policies, restartIterationMaxAttempts, allRegisteredMetrics, scenarioRuntimes, stepRuntimes, scenarioAccumulators, scenarioDurationsMs, stopTestState, testAbortController, loadEngineV2Budget, loadEngineV2Telemetry, iterationObservationReporter, iterationObservationRunId = testInfo.sessionId, iterationObservationResultOwnerId = "", iterationObservationProcessGroup = 0, executeScenarioInvocation, invokeBeforeScenario, invokeAfterScenario, invokeBeforeStep, invokeAfterStep } = args;
+    const { scenario, scenarioIndex, scenarioCount, options, logger, nodeInfo, testInfo, policies, restartIterationMaxAttempts, allRegisteredMetrics, scenarioRuntimes, stepRuntimes, scenarioAccumulators, scenarioDurationsMs, stopTestState, testAbortController, loadEngineV2Budget, loadEngineV2Telemetry, iterationObservationReporter, iterationObservationRunId = testInfo.sessionId, iterationObservationResultOwnerId = "", iterationObservationProcessGroup = 0, reportHistoryLifecycle, executeScenarioInvocation, invokeBeforeScenario, invokeAfterScenario, invokeBeforeStep, invokeAfterStep } = args;
+    let reportHistoryExecutionEnded = false;
+    const endReportHistoryExecution = async () => {
+        if (reportHistoryExecutionEnded) {
+            return;
+        }
+        reportHistoryExecutionEnded = true;
+        await reportHistoryLifecycle?.scenarioExecutionEnded();
+    };
     const scenarioStartedMs = Date.now();
     const scenarioContextData = {};
     const registeredMetrics = [];
@@ -5269,6 +5406,7 @@ async function executeScenarioRuntime(args) {
         })));
         await invokeBeforeScenario(policies, scenario.name);
         await runWarmUpAsync();
+        reportHistoryLifecycle?.scenarioBombingStarted();
         accumulator.setCurrentOperation("Bombing");
         const simulations = scenario.getSimulations();
         if (!simulations.length) {
@@ -5302,6 +5440,7 @@ async function executeScenarioRuntime(args) {
             }
         }
         accumulator.setCurrentOperation(stopScenario || stopTestState.value ? "Stop" : "Complete");
+        await endReportHistoryExecution();
         await invokeAfterScenario(policies, scenario.name, runtime);
     }
     catch (error) {
@@ -5318,6 +5457,7 @@ async function executeScenarioRuntime(args) {
         }
     }
     finally {
+        await endReportHistoryExecution();
         scenarioDurationsMs.set(scenario.name, Math.max(Date.now() - scenarioStartedMs, 0));
         try {
             await scenario.invokeClean({
@@ -7251,6 +7391,11 @@ function resolveClusterExecutionMode(options) {
     }
     return "single";
 }
+function isDistributedReportHistoryExecution(clusterMode, options) {
+    return clusterMode !== "single"
+        || options.loadEngineV2SegmentLifecycleOverride !== undefined
+        || Math.max(Math.trunc(options.clusterShardCount ?? 1), 1) > 1;
+}
 function buildEmptyNodeStats(args) {
     return attachNodeStatsAliases({
         startedUtc: args.startedUtc,
@@ -11082,6 +11227,7 @@ function buildGroupedCorrelationRows(rows) {
             LatencyMinMs: latencySamples.length ? formatOptionalLatency(latencySamples[0]) : "",
             LatencyMeanMs: latencySamples.length ? formatOptionalLatency(latencySamples.reduce((sum, value) => sum + value, 0) / latencySamples.length) : "",
             LatencyP50Ms: latencySamples.length ? formatOptionalLatency(percentile(latencySamples, 0.5)) : "",
+            LatencyP75Ms: latencySamples.length ? formatOptionalLatency(percentile(latencySamples, 0.75)) : "",
             LatencyP80Ms: latencySamples.length ? formatOptionalLatency(percentile(latencySamples, 0.8)) : "",
             LatencyP85Ms: latencySamples.length ? formatOptionalLatency(percentile(latencySamples, 0.85)) : "",
             LatencyP90Ms: latencySamples.length ? formatOptionalLatency(percentile(latencySamples, 0.9)) : "",
@@ -11294,6 +11440,8 @@ export const __loadstrikeTestExports = {
     buildThresholdCheckExpression,
     buildTrackingLeaseKey,
     buildTrackingRunNamespace,
+    boundedReportingIntervalMs,
+    resolvedReportHistoryCadenceSeconds,
     clusterNodeResultToNodeStats,
     combineAbortSignals,
     computeScenarioRequestCount,
@@ -11313,6 +11461,7 @@ export const __loadstrikeTestExports = {
     formatUtcReportTimestamp,
     hasPluginRows,
     inferRuntimeLegacyHttpResponseSource,
+    isDistributedReportHistoryExecution,
     isComparisonFailed,
     loadJsonObject,
     logLevelOrder,

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;

package/dist/types/runtime.d.ts

@@ -1,6 +1,7 @@
 import { type ClusterNodeResult, type LoadEngineV2PlanInput } from "./cluster.js";
 import { RedisCorrelationStore, RedisCorrelationStoreOptions, TrackingFieldSelector, type TrackingPayload } from "./correlation.js";
 import { type EndpointAdapter, type EndpointDefinition } from "./transports.js";
+import { type ReportHistoryMeasurement, type ReportHistoryScenario } from "./report-history.js";
 import { LoadEngineV2ExecutionBudget, type LoadEngineV2DistributionRecord, type LoadStrikeHistogramV1Sidecar } from "./load-engine-v2.js";
 import { type LoadStrikeIterationObservationBatchV1, type LoadStrikeIterationObservationStreamCompletionV1, type LoadStrikeIterationStepObservationV1, type LoadStrikeObservationDeliveryStats } from "./iteration-observations.js";
 declare const LOAD_ENGINE_V2_SCHEDULER_DISTRIBUTIONS: unique symbol;
@@ -570,6 +571,17 @@ declare class MeasurementAccumulator {
      */
     build(allRequestCount: number, durationMs: number): LoadStrikeMeasurementStats;
     buildCombined(other: MeasurementAccumulator, allRequestCount: number, durationMs: number): LoadStrikeMeasurementStats;
+    /**
+     * Projects only the cumulative fields used by the private HTML-report
+     * history. Legacy distributions deliberately omit latency so this cadence
+     * path never scans their retained per-request arrays.
+     */
+    buildReportHistoryMeasurement(): ReportHistoryMeasurement;
+    /**
+     * Combines only bounded native latency state plus exact counters. It does
+     * not materialize status rows or any public measurement DTO.
+     */
+    buildCombinedReportHistoryMeasurement(other: MeasurementAccumulator): ReportHistoryMeasurement;
     private histogramSnapshot;
 }
 declare class StepStatsAccumulator {
@@ -627,6 +639,11 @@ declare class ScenarioStatsAccumulator {
      * Use this when the surrounding wrapper type makes this operation the clearest way to express your intent.
      */
     recordStep(stepName: string, reply: LoadStrikeStepReply, observedLatencyMs: number, sortIndex?: number): number;
+    /**
+     * Captures the bounded, private history view without building scenario
+     * steps, status rows, plugins, aliases, or any other public result shape.
+     */
+    buildReportHistorySnapshot(): ReportHistoryScenario;
     /**
      * Builds the configured payload or helper object.
      * Use this when all builder inputs are ready to be materialized.
@@ -2384,6 +2401,8 @@ export declare class LoadStrikeRunner {
     private collectPluginData;
 }
 declare function hasPluginRows(value: LoadStrikePluginData): boolean;
+declare function boundedReportingIntervalMs(seconds: number): number;
+declare function resolvedReportHistoryCadenceSeconds(seconds: number): number;
 declare function combineAbortSignals(...signals: AbortSignal[]): AbortSignal;
 declare function delayWithAbort(durationMs: number, signal: AbortSignal): Promise<void>;
 declare function createRuntimeRandom(): LoadStrikeRandom;
@@ -2434,6 +2453,7 @@ declare function normalizeThresholdScope(value: string): "scenario" | "step" | "
 declare function buildThresholdCheckExpression(scope: "scenario" | "step" | "metric", stepName: string, field: string): string;
 declare function detailedToNodeStats(result: LoadStrikeRunResult, metricStats?: LoadStrikeMetricStats): LoadStrikeNodeStats;
 declare function resolveClusterExecutionMode(options: LoadStrikeRunnerOptions): "single" | "local-coordinator" | "nats-coordinator" | "nats-agent";
+declare function isDistributedReportHistoryExecution(clusterMode: ReturnType<typeof resolveClusterExecutionMode>, options: Pick<LoadStrikeRunnerOptions, "clusterShardCount" | "loadEngineV2SegmentLifecycleOverride">): boolean;
 declare function buildEmptyNodeStats(args: {
     startedUtc: string;
     completedUtc: string;
@@ -2644,6 +2664,8 @@ export declare const __loadstrikeTestExports: {
     buildThresholdCheckExpression: typeof buildThresholdCheckExpression;
     buildTrackingLeaseKey: typeof buildTrackingLeaseKey;
     buildTrackingRunNamespace: typeof buildTrackingRunNamespace;
+    boundedReportingIntervalMs: typeof boundedReportingIntervalMs;
+    resolvedReportHistoryCadenceSeconds: typeof resolvedReportHistoryCadenceSeconds;
     clusterNodeResultToNodeStats: typeof clusterNodeResultToNodeStats;
     combineAbortSignals: typeof combineAbortSignals;
     computeScenarioRequestCount: typeof computeScenarioRequestCount;
@@ -2663,6 +2685,7 @@ export declare const __loadstrikeTestExports: {
     formatUtcReportTimestamp: typeof formatUtcReportTimestamp;
     hasPluginRows: typeof hasPluginRows;
     inferRuntimeLegacyHttpResponseSource: typeof inferRuntimeLegacyHttpResponseSource;
+    isDistributedReportHistoryExecution: typeof isDistributedReportHistoryExecution;
     isComparisonFailed: typeof isComparisonFailed;
     loadJsonObject: typeof loadJsonObject;
     logLevelOrder: typeof logLevelOrder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadstrike/loadstrike-sdk",
-  "version": "1.0.31001",
+  "version": "1.0.31601",
   "description": "TypeScript and JavaScript SDK for in-process load execution, traffic correlation, and reporting.",
   "keywords": [
     "load-testing",