@loadstrike/loadstrike-sdk 1.0.30201 → 1.0.30401

package/dist/types/cluster.d.ts

@@ -1,9 +1,14 @@
+import { type EndpointAdapter, type EndpointDefinition } from "./transports.js";
 export interface ClusterScenarioDispatch {
     scenarioNames: string[];
     commandId?: string;
     agentRunToken?: string;
     agentIndex?: number;
     agentCount?: number;
+    segmentLifecycle?: {
+        beforeSegment: (scenarioIndex: number, simulationIndex: number) => Promise<void>;
+        afterSegment: (scenarioIndex: number, simulationIndex: number) => Promise<void>;
+    };
 }
 export interface ClusterNodeResult {
     nodeId: string;
@@ -73,6 +78,13 @@ export interface ClusterNodeStatsPayload {
     nodeInfo?: Record<string, unknown>;
     testInfo?: Record<string, unknown>;
     logFiles?: string[];
+    generatorWarnings?: unknown[];
+    observationDeliveryStats?: Record<string, unknown>;
+    reportingComplete?: boolean;
+    schedulerSegments?: unknown[];
+    schedulerStats?: Record<string, unknown>;
+    histogramSidecars?: unknown[];
+    histogramArtifactBase64?: string;
 }
 export interface ClusterRunResultMessage {
     commandId: string;
@@ -81,6 +93,328 @@ export interface ClusterRunResultMessage {
     errorMessage?: string;
     stats?: ClusterNodeStatsPayload;
 }
+export declare const LOAD_ENGINE_V2_CLUSTER_CAPABILITIES: Readonly<{
+    schedulerVersions: string[];
+    histogramVersions: string[];
+    shardingVersions: string[];
+    resultChunkVersions: string[];
+    iterationObservationSchemas: string[];
+    correlationSetVersions: string[];
+    planHashVersions: string[];
+    callbackExecutionModes: string[];
+    maximumResultChunkBytes: number;
+}>;
+export interface LoadEngineV2Registration {
+    runId: string;
+    sessionId: string;
+    coordinatorNonce: string;
+    agentId: string;
+    targetSubject: string;
+    processInstanceId: string;
+    schedulerVisibleProcessorCount: number;
+    sdkLanguage: string;
+    sdkPackageVersion: string;
+    runtimeVersion: string;
+    registrationSequence64: string;
+    leaseIssuedUtcNs64: string;
+    leaseExpiresUtcNs64: string;
+    schedulerVersions: string[];
+    histogramVersions: string[];
+    shardingVersions: string[];
+    resultChunkVersions: string[];
+    iterationObservationSchemas: string[];
+    correlationSetVersions: string[];
+    planHashVersions: string[];
+    callbackExecutionModes: string[];
+    maximumResultChunkBytes: number;
+    registrationBindingHash: string;
+}
+export interface LoadEngineV2RegistrationInput {
+    runId: string;
+    sessionId: string;
+    coordinatorNonce: string;
+    agentId: string;
+    targetSubject: string;
+    processInstanceId?: string;
+    schedulerVisibleProcessorCount?: number;
+    sdkLanguage?: string;
+    sdkPackageVersion?: string;
+    runtimeVersion?: string;
+    registrationSequence64: string;
+    leaseIssuedUtcNs64: string;
+    leaseExpiresUtcNs64: string;
+    capabilities?: Partial<typeof LOAD_ENGINE_V2_CLUSTER_CAPABILITIES>;
+}
+export declare function createLoadEngineV2Registration(input: LoadEngineV2RegistrationInput): LoadEngineV2Registration;
+export declare function negotiateLoadEngineV2Registrations(runId: string, sessionId: string, coordinatorNonce: string, expectedAgentIds: readonly string[], registrations: readonly LoadEngineV2Registration[], nowUtcNs64: string): LoadEngineV2Registration[];
+export interface LoadEngineV2CoordinatorHello {
+    runId: string;
+    sessionId: string;
+    coordinatorNonce: string;
+    registrationSubject: string;
+    expiresUtcNs64: string;
+    expectedAgentIds: string[];
+    bindingHash: string;
+}
+export declare function buildLoadEngineV2ScopedRegistrationSubject(runId: string, sessionId: string, coordinatorNonce: string): string;
+export declare function buildLoadEngineV2ScopedTargetSubject(runId: string, sessionId: string, coordinatorNonce: string, agentId: string): string;
+export declare function buildLoadEngineV2GlobalInvocationId(runId: string, scenarioIndex: number | bigint, simulationIndex: number | bigint, identityKind: string, primaryOrdinal: string | number | bigint, secondaryOrdinal: string | number | bigint): string;
+export declare function createLoadEngineV2CoordinatorHello(input: Omit<LoadEngineV2CoordinatorHello, "bindingHash" | "expectedAgentIds"> & {
+    expectedAgentIds: string[];
+}): LoadEngineV2CoordinatorHello;
+export declare function validateLoadEngineV2CoordinatorHello(hello: LoadEngineV2CoordinatorHello, expectedSessionId: string, expectedAgentId: string, nowUtcNs64: string): void;
+export interface LoadEngineV2PlanSimulationInput {
+    simulationIndex64: string;
+    kind: string;
+    rate64: string;
+    minRate64: string;
+    maxRate64: string;
+    copies64: string;
+    iterations64: string;
+    intervalNs64: string;
+    durationNs64: string;
+}
+export interface LoadEngineV2PlanScenarioInput {
+    scenarioIndex64: string;
+    scenarioName: string;
+    target: "agent" | "coordinator";
+    callbackExecutionMode?: "async" | "blocking";
+    declaredStepNames?: string[];
+    simulations: LoadEngineV2PlanSimulationInput[];
+}
+export interface LoadEngineV2PlanInput {
+    runId: string;
+    sessionId: string;
+    registrationNonce: string;
+    maxInFlight64: string;
+    reportingIntervalNs64: string;
+    schedulerSeed64?: string;
+    schedulerVisibleProcessorCount64?: string;
+    maxStatisticsStateBytes64?: string;
+    maxDistributionSeries64?: string;
+    maxCorrelationGroups64?: string;
+    maxStatusGroupsPerSeries64?: string;
+    maxPortalRunDistributionBytes64?: string;
+    expectedAgentIds: string[];
+    scenarios: LoadEngineV2PlanScenarioInput[];
+}
+export interface LoadEngineV2PortalSeriesRecord {
+    seriesKeyHex: string;
+    unit: "microseconds" | "bytes";
+    outcome: "ok" | "fail" | "all" | "none";
+}
+export interface LoadEngineV2Plan {
+    bytes: Buffer;
+    hash: string;
+    expectedAgentIds: string[];
+    portalSeries: LoadEngineV2PortalSeriesRecord[];
+}
+export declare function buildLoadEngineV2Plan(input: LoadEngineV2PlanInput): LoadEngineV2Plan;
+/** Canonical LoadStrikeIdentityKeyV1 scenario bytes. */
+export declare function buildLoadEngineV2ScenarioIdentityKey(scenarioIndex64: string): Buffer;
+/** Canonical LoadStrikeIdentityKeyV1 reserved step-other bytes. */
+export declare function buildLoadEngineV2ReservedStepOtherIdentityKey(scenarioIndex64: string): Buffer;
+export declare function buildLoadEngineV2StepIdentityKey(scenarioIndex64: string, stepName: string): {
+    identity: Buffer;
+    display: string;
+};
+/** Resolves a runtime step to its frozen signed identity or the reserved `<other>` bucket. */
+export declare function resolveLoadEngineV2StepIdentityKey(scenarioIndex64: string, stepName: string, declaredStepNames: readonly string[]): {
+    identity: Buffer;
+    display: string;
+    routedToOther: boolean;
+};
+export declare function buildLoadEngineV2SchedulerIdentityKey(kind: "decision" | "start", scenarioIndex64: string, simulationIndex64: string): Buffer;
+export declare function buildLoadEngineV2StatusIdentityKey(status: string, message: string): {
+    identity: Buffer;
+    display: string;
+} | undefined;
+/** Canonical LoadStrikePortalSeriesKeyV1 bytes. */
+export declare function buildLoadEngineV2PortalSeriesKey(identity: Uint8Array, unit: "microseconds" | "bytes", outcome: "ok" | "fail" | "all" | "none"): Buffer;
+export interface LoadEngineV2BarrierAssignmentInput {
+    scenarioIndex64: string;
+    simulationIndex64: string;
+    trafficMixId?: string;
+    trafficMixLaneIndex64?: string;
+    trafficMixPhaseIndex64?: string;
+    agentId: string;
+    shardIndex64: string;
+    shardCount64: string;
+}
+export declare function buildLoadEngineV2BarrierScopeId(planHash: string, scope: {
+    kind: "scenario";
+    scenarioIndex64: string;
+    simulationIndex64: string;
+} | {
+    kind: "traffic-mix";
+    trafficMixId: string;
+    trafficMixPhaseIndex64: string;
+}): string;
+export declare function buildLoadEngineV2AssignmentHash(barrierScopeId: string, assignments: readonly LoadEngineV2BarrierAssignmentInput[]): string;
+export interface LoadEngineV2BarrierAck {
+    phase: string;
+    agentId: string;
+    accepted: boolean;
+    planHash: string;
+    barrierScopeId?: string;
+    assignmentHash: string;
+    barrierEpoch64: string;
+    deadlineUtcNs64: string;
+    acknowledgedUtcNs64: string;
+}
+export interface LoadEngineV2ClockProbeSample {
+    probeIndex: number;
+    coordinatorSendUtcNs64: string;
+    agentReceiveUtcNs64: string;
+    agentSendUtcNs64: string;
+    coordinatorReceiveUtcNs64: string;
+    coordinatorClockResolutionNs64: string;
+    agentClockResolutionNs64: string;
+}
+export interface LoadEngineV2ClockProbeResult extends LoadEngineV2ClockProbeSample {
+    roundTripNs64: string;
+    offsetAgentMinusCoordinatorNs64: string;
+    uncertaintyNs64: string;
+}
+export declare function evaluateLoadEngineV2ClockProbe(sample: LoadEngineV2ClockProbeSample): LoadEngineV2ClockProbeResult;
+export declare function selectLoadEngineV2ClockProbe(samples: readonly LoadEngineV2ClockProbeSample[], latenessToleranceNs64?: string): LoadEngineV2ClockProbeResult;
+export declare function validateLoadEngineV2BarrierAcks(phase: string, expectedAgentIds: readonly string[], acknowledgements: readonly LoadEngineV2BarrierAck[], planHash: string, assignmentHash: string, barrierEpoch64: string, nowUtcNs64: string, barrierScopeId?: string): void;
+export interface LoadEngineV2ResultArtifact {
+    kind: string;
+    artifactId: string;
+    schema: string;
+    applicability: "present" | "empty" | "not-applicable";
+    payload: Buffer;
+}
+export interface LoadEngineV2ResultManifestEntry {
+    kind: string;
+    artifactId: string;
+    schema: string;
+    applicability: "present" | "empty" | "not-applicable";
+    uncompressedLength64: string;
+    chunkCount: number;
+    artifactSha256: string;
+}
+export interface LoadEngineV2ResultManifest {
+    runId: string;
+    sessionId: string;
+    resultOwnerId: string;
+    snapshotSequence64: string;
+    planHash: string;
+    isFinal: boolean;
+    correlationDetailPartCount: number;
+    entries: LoadEngineV2ResultManifestEntry[];
+    bytes: Buffer;
+    hash: string;
+}
+export interface LoadEngineV2CanonicalResultChunk {
+    runId: string;
+    sessionId: string;
+    resultOwnerId: string;
+    snapshotSequence64: string;
+    manifestSha256: string;
+    kind: string;
+    artifactId: string;
+    schema: string;
+    artifactSha256: string;
+    chunkIndex: number;
+    chunkCount: number;
+    uncompressedTotalLength64: string;
+    payload: Buffer;
+    chunkSha256: string;
+    bytes: Buffer;
+}
+export interface LoadEngineV2ResultCommit {
+    runId: string;
+    sessionId: string;
+    resultOwnerId: string;
+    snapshotSequence64: string;
+    planHash: string;
+    manifestLength: number;
+    manifestSha256: string;
+    entryCount: number;
+    totalNonDetailBytes64: string;
+    totalDetailBytes64: string;
+    bytes: Buffer;
+}
+export interface LoadEngineV2ResultSnapshot {
+    manifest: LoadEngineV2ResultManifest;
+    chunks: LoadEngineV2CanonicalResultChunk[];
+    commit: LoadEngineV2ResultCommit;
+}
+export declare function loadEngineV2PresentArtifact(kind: string, artifactId: string, schema: string, payload: Uint8Array): LoadEngineV2ResultArtifact;
+export declare function loadEngineV2EmptyArtifact(kind: string, artifactId: string, schema: string): LoadEngineV2ResultArtifact;
+export declare function loadEngineV2NotApplicableArtifact(kind: string, artifactId: string): LoadEngineV2ResultArtifact;
+export declare function createLoadEngineV2ResultSnapshot(runId: string, sessionId: string, resultOwnerId: string, snapshotSequence64: string, planHash: string, isFinal: boolean, chunkBytes: number, artifacts: readonly LoadEngineV2ResultArtifact[]): LoadEngineV2ResultSnapshot;
+export declare function decodeLoadEngineV2ResultManifest(bytesValue: Uint8Array): LoadEngineV2ResultManifest;
+export declare function decodeLoadEngineV2ResultChunk(bytesValue: Uint8Array, maximumChunkBytes: number): LoadEngineV2CanonicalResultChunk;
+export declare function decodeLoadEngineV2ResultCommit(bytesValue: Uint8Array): LoadEngineV2ResultCommit;
+export declare class LoadEngineV2ResultSnapshotReceiver {
+    private readonly runId;
+    private readonly sessionId;
+    private readonly resultOwnerId;
+    private readonly planHash;
+    private readonly chunkBytes;
+    private readonly maximumResultBytes;
+    private lastSequence;
+    private lastManifestHash;
+    private lastCommitBytes;
+    private lastArtifacts;
+    private pending?;
+    private ownerLost;
+    constructor(runId: string, sessionId: string, resultOwnerId: string, planHash: string, chunkBytes: number, maximumResultBytes: number);
+    begin(manifest: LoadEngineV2ResultManifest): void;
+    add(chunk: LoadEngineV2CanonicalResultChunk): void;
+    get hasCompleteSnapshot(): boolean;
+    commitSnapshot(commit: LoadEngineV2ResultCommit): Map<string, Buffer>;
+    sealOwnerLost(): void;
+}
+export interface LoadEngineV2ResultChunk {
+    commandId: string;
+    agentId: string;
+    chunkIndex: number;
+    chunkCount: number;
+    totalLength64: string;
+    payloadSha256: string;
+    chunkSha256: string;
+    dataBase64: string;
+}
+export declare function createLoadEngineV2ResultChunks(result: ClusterRunResultMessage | Record<string, unknown>, chunkBytes?: number): LoadEngineV2ResultChunk[];
+export declare class LoadEngineV2ResultChunkAccumulator {
+    private readonly maximumResultBytes;
+    private manifest;
+    private readonly chunks;
+    private complete;
+    constructor(maximumResultBytes?: number);
+    add(message: LoadEngineV2ResultChunk): ClusterRunResultMessage | Record<string, unknown> | undefined;
+}
+export interface LoadEngineV2OwnerLossInput {
+    missingAgentIds: string[];
+    assignments: Array<{
+        agentId: string;
+        shardIndex64: string;
+        shardCount64: string;
+        scenarios: Array<{
+            scenarioName: string;
+            scenarioIndex64: string;
+            simulations: Array<{
+                simulationIndex64: string;
+                kind: string;
+                plannedIterations64: string;
+            }>;
+        }>;
+    }>;
+}
+export declare function buildLoadEngineV2OwnerLoss(input: LoadEngineV2OwnerLossInput): {
+    reportingComplete: false;
+    applicationFailureCount64: "0";
+    generatorWarnings: Array<{
+        code: string;
+        agentId: string;
+        count64: string;
+    }>;
+    schedulerSegments: Array<Record<string, unknown>>;
+};
 export interface DistributedClusterCoordinatorOptions {
     clusterId: string;
     sessionId: string;
@@ -90,6 +424,15 @@ export interface DistributedClusterCoordinatorOptions {
     agentGroup?: string;
     commandTimeoutMs?: number;
     nats?: Record<string, unknown>;
+    expectedAgentIds?: string[];
+    loadEngineContractVersion?: 1 | 2;
+    barrierLeadTimeMs?: number;
+    adapterFactory?: ClusterEndpointAdapterFactory;
+    /** @internal Clock adapter resolution used by exact protocol harnesses. */
+    v2ClockResolutionNs64?: string;
+}
+export interface ClusterEndpointAdapterFactory {
+    create(definition: EndpointDefinition): EndpointAdapter;
 }
 export interface DistributedClusterDispatchResult {
     nodeResults: ClusterNodeResult[];
@@ -100,6 +443,7 @@ export interface DistributedClusterDispatchResult {
     missingNodes: number;
     runSubject: string;
     replySubject: string;
+    ownerLoss?: ReturnType<typeof buildLoadEngineV2OwnerLoss>;
 }
 export declare class DistributedClusterCoordinator {
     private readonly options;
@@ -109,8 +453,11 @@ export declare class DistributedClusterCoordinator {
      */
     constructor(options: DistributedClusterCoordinatorOptions);
     dispatch(assignments: string[][], buildAgentRunToken?: (command: ClusterRunCommandMessage) => Promise<string>): Promise<DistributedClusterDispatchResult>;
+    /** Runs the native V2 capability, targeted-command, barrier, and chunk-result protocol. */
+    dispatchV2(assignments: string[][], planInput: LoadEngineV2PlanInput, buildAgentRunToken?: (command: ClusterRunCommandMessage) => Promise<string>): Promise<DistributedClusterDispatchResult>;
     private buildRunSubject;
     private buildReplySubject;
+    private createAdapter;
     private natsEndpoint;
 }
 export interface DistributedClusterAgentOptions {
@@ -119,10 +466,28 @@ export interface DistributedClusterAgentOptions {
     agentId: string;
     agentGroup?: string;
     nats?: Record<string, unknown>;
+    loadEngineContractVersion?: 1 | 2;
+    adapterFactory?: ClusterEndpointAdapterFactory;
+    /** @internal Validates received signed descriptors against immutable local declarations. */
+    validateV2Plan?: (planInput: LoadEngineV2PlanInput) => void;
+    /** @internal Exact conformance harness capability override. */
+    v2Capabilities?: Partial<typeof LOAD_ENGINE_V2_CLUSTER_CAPABILITIES>;
+    /** @internal Clock adapter resolution used by exact protocol harnesses. */
+    v2ClockResolutionNs64?: string;
 }
 export declare class DistributedClusterAgent {
     private readonly options;
     private commandConsumer;
+    private v2HelloConsumer;
+    private v2CommandConsumer;
+    private v2RegistrationProducer;
+    private v2LastRegistrationMs;
+    private v2Hello;
+    private v2CurrentRegistration;
+    private v2RegistrationSequence;
+    private v2RenewalTimer;
+    private v2RenewalError;
+    private v2Prepared;
     /**
      * Exposes the public constructor operation.
      * Use this when the surrounding wrapper type makes this operation the clearest way to express your intent.
@@ -130,9 +495,22 @@ export declare class DistributedClusterAgent {
     constructor(options: DistributedClusterAgentOptions);
     dispose(): Promise<void>;
     pollAndExecuteOnce(execute: (dispatch: ClusterScenarioDispatch) => Promise<ClusterNodeResult> | ClusterNodeResult): Promise<boolean>;
+    /** Polls one targeted V2 message. A callback can run only after a matching commit. */
+    pollAndExecuteV2Once(execute: (dispatch: ClusterScenarioDispatch) => Promise<ClusterNodeResult> | ClusterNodeResult): Promise<boolean>;
+    private publishV2CanonicalResult;
+    private publishV2ClockProbe;
+    private acceptV2Prepare;
+    private acceptV2Commit;
+    private ensureV2Registration;
+    private ensureV2CommandConsumer;
+    private publishV2Registration;
+    private matchesV2Scope;
+    private publishV2Ack;
+    private endpoint;
+    private createAdapter;
 }
 declare function parseRunCommand(value: Record<string, unknown>): ClusterRunCommandMessage;
-declare function parseRunResult(value: Record<string, unknown>): ClusterRunResultMessage;
+declare function parseRunResult(value: Record<string, unknown>, requireHistogramArtifact?: boolean): ClusterRunResultMessage;
 declare function convertRunResult(result: ClusterRunResultMessage): ClusterNodeResult;
 declare function sanitizeToken(value: string): string;
 declare function buildWeightedCycle(weights: number[]): number[];

package/dist/types/index.d.ts

@@ -3,7 +3,9 @@ export { LoadStrikeAutopilot, LoadStrikeAutopilotResult } from "./autopilot.js";
 export type { LoadStrikeAutopilotEndpoint, LoadStrikeAutopilotEndpointBinding, LoadStrikeAutopilotLoadSimulationSuggestion, LoadStrikeAutopilotMessageSample, LoadStrikeAutopilotOptions, LoadStrikeAutopilotPlan, LoadStrikeAutopilotPreviewReport, LoadStrikeAutopilotReadinessFailure, LoadStrikeAutopilotRedaction, LoadStrikeAutopilotRequest, LoadStrikeAutopilotResultShape, LoadStrikeAutopilotScenarioPlan, LoadStrikeAutopilotSecretBinding, LoadStrikeAutopilotThresholdSuggestion, LoadStrikeAutopilotTrackingSelectorSuggestion } from "./autopilot-contracts.js";
 export { LoadStrikeAutopilotReadiness } from "./autopilot-contracts.js";
 export { CrossPlatformScenarioConfigurator, ScenarioTrackingExtensions, LoadStrikeContext, LoadStrikeAccessibility, LoadStrikeAccessibilityAdapters, LoadStrikeAccessibilityBaseline, LoadStrikeAccessibilityCiGate, LoadStrikeAccessibilityScanner, LoadStrikeBrowserWebVitals, LoadStrikeBrowserWebVitalsCollector, LoadStrikePluginData, LoadStrikePluginDataTable, LoadStrikeNodeType, LoadStrikeReportFormat, LoadStrikeResponse, LoadStrikeLogLevel, LoadStrikeScenarioOperation, LoadStrikeOperationType, LoadStrikeRunner, LoadStrikeScenario, LoadStrikeScenarioShare, LoadStrikeSimulation, LoadStrikeTrafficMix, CrossPlatformTrackingConfiguration, LoadStrikeMetric, LoadStrikeCounter, LoadStrikeGauge, LoadStrikeStep, LoadStrikeThreshold } from "./runtime.js";
-export type { ILoadStrikeReportingSink, ILoadStrikeWorkerPlugin, LoadStrikeRunResult, LoadStrikeReportingSink, LoadStrikeRuntimePolicy, LoadStrikeRunnerOptions, LoadStrikeRunContext as LoadStrikeRuntimeContext, LoadStrikeRunContext, LoadStrikeAccessibilityOptions, LoadStrikeAccessibilityBaselineOutcome, LoadStrikeAccessibilityCiGateOutcome, LoadStrikeAccessibilityViolation, LoadStrikeKeyboardFocusResult, LoadStrikeAccessibilityResult, LoadStrikeAccessibilityCheckContext, LoadStrikeBrowserWebVitalsOptions, LoadStrikeBrowserWebVitalsResult, LoadStrikeBrowserWebVitalsContext, LoadStrikeBaseContext, LoadStrikeCounterStats, LoadStrikeDataTransferStats, LoadStrikeGaugeStats, LoadStrikeLogger, LoadStrikeLoadSimulationStats, LoadStrikeMeasurementStats, LoadStrikeMetricStats, LoadStrikeNodeInfo, LoadStrikeMetricValue, LoadStrikeRandom, LoadStrikeReply, LoadStrikeLatencyCount, LoadStrikeLatencyStats, LoadStrikeLoadSimulation, LoadStrikeScenarioInfo, LoadStrikeScenarioInitContext, LoadStrikeScenarioPartition, LoadStrikeScenarioStartInfo, LoadStrikeScenarioContext, LoadStrikeScenarioStats, LoadStrikeTestInfo, LoadStrikeScenarioRuntime, LoadStrikeSessionStartInfo, LoadStrikeSinkSession, LoadStrikeSinkError, LoadStrikeStatusCodeStats, LoadStrikeThresholdResult, LoadStrikeThresholdPredicateContext, LoadStrikeStepReply, LoadStrikeStepStats, LoadStrikeStepRuntime, LoadStrikeThresholdOptions, LoadStrikeRequestStats, LoadStrikeWorkerPlugin } from "./runtime.js";
+export type { ILoadStrikeReportingSink, ILoadStrikeWorkerPlugin, LoadStrikeRunResult, LoadStrikeGeneratorWarning, LoadStrikeSchedulerSegmentStats, LoadStrikeSchedulerStats, LoadStrikeReportingSink, LoadStrikeRuntimePolicy, LoadStrikeRunnerOptions, LoadStrikeRunContext as LoadStrikeRuntimeContext, LoadStrikeRunContext, LoadStrikeAccessibilityOptions, LoadStrikeAccessibilityBaselineOutcome, LoadStrikeAccessibilityCiGateOutcome, LoadStrikeAccessibilityViolation, LoadStrikeKeyboardFocusResult, LoadStrikeAccessibilityResult, LoadStrikeAccessibilityCheckContext, LoadStrikeBrowserWebVitalsOptions, LoadStrikeBrowserWebVitalsResult, LoadStrikeBrowserWebVitalsContext, LoadStrikeBaseContext, LoadStrikeCounterStats, LoadStrikeDataTransferStats, LoadStrikeGaugeStats, LoadStrikeLogger, LoadStrikeLoadSimulationStats, LoadStrikeMeasurementStats, LoadStrikeMetricStats, LoadStrikeNodeInfo, LoadStrikeMetricValue, LoadStrikeRandom, LoadStrikeReply, LoadStrikeLatencyCount, LoadStrikeLatencyStats, LoadStrikeLoadSimulation, LoadStrikeScenarioInfo, LoadStrikeScenarioInitContext, LoadStrikeScenarioPartition, LoadStrikeScenarioStartInfo, LoadStrikeScenarioContext, LoadStrikeScenarioStats, LoadStrikeTestInfo, LoadStrikeScenarioRuntime, LoadStrikeSessionStartInfo, LoadStrikeSinkSession, LoadStrikeSinkError, LoadStrikeStatusCodeStats, LoadStrikeThresholdResult, LoadStrikeThresholdPredicateContext, LoadStrikeStepReply, LoadStrikeStepStats, LoadStrikeStepRuntime, LoadStrikeThresholdOptions, LoadStrikeRequestStats, LoadStrikeWorkerPlugin } from "./runtime.js";
+export { DEFAULT_ITERATION_OBSERVATION_SETTINGS, ITERATION_OBSERVATION_BATCH_SCHEMA_VERSION, ITERATION_OBSERVATION_SCHEMA_VERSION, ITERATION_OBSERVATION_STREAM_COMPLETION_SCHEMA_VERSION, createIterationObservation, createIterationStepObservation, deriveIterationBatchId, deriveIterationId, deriveObservationId, serializeIterationObservationBatchGzipJson } from "./iteration-observations.js";
+export type { CreateIterationObservationInput, CreateIterationStepObservationInput, IterationObservationSettings, LoadStrikeIterationObservationBatchV1, LoadStrikeIterationObservationStreamCompletionV1, LoadStrikeIterationObservationV1, LoadStrikeIterationStepObservationV1, LoadStrikeObservationDeliveryStats } from "./iteration-observations.js";
 export { CorrelationStoreConfiguration, CrossPlatformTrackingRuntime, InMemoryCorrelationStore, RedisCorrelationStoreOptions, RedisCorrelationStore, TrackingPayloadBuilder, TrackingFieldSelector } from "./correlation.js";
 export type { CorrelationEntry, DestinationConsumeResult, GatheredRow, CorrelationStoreKind, CorrelationRuntimeOptions, CorrelationRuntimePlugin, CorrelationRuntimeStats, CorrelationStore, SourceProduceResult, TrackingFieldLocation, TrackingPayload } from "./correlation.js";
 export { LOADSTRIKE_TRACE_ID_HEADER, LOADSTRIKE_TRACE_ID_TRACKING_FIELD, TrafficEndpointDefinition, HttpEndpointDefinition, KafkaEndpointDefinition, KafkaSaslOptions, RabbitMqEndpointDefinition, NatsEndpointDefinition, RedisStreamsEndpointDefinition, AzureEventHubsEndpointDefinition, SqsEndpointDefinition, DelegateStreamEndpointDefinition, PushDiffusionEndpointDefinition, GrpcEndpointDefinition, GrpcMethodTypes, GrpcNativeClientOptions, GrpcStatusMapper, ProtocolMetricSnapshot, WebSocketEndpointDefinition, WebSocketExpectedMessage, WebSocketMessageSpec, WebSocketNativeClientOptions, WebSocketReconnectPolicy, HttpOAuth2ClientCredentialsOptions, HttpAuthOptions } from "./transports.js";

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

@@ -0,0 +1,225 @@
+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";
+export interface LoadStrikeIterationStepObservationV1 {
+    stepName: string;
+    sortIndex: number;
+    startedUtcNs: string;
+    completedUtcNs: string;
+    observedLatencyUs64: string;
+    reportedLatencyUs64: string;
+    isSuccess: boolean;
+    statusCode: string;
+    sizeBytes64: string;
+}
+export interface LoadStrikeIterationObservationV1 {
+    schemaVersion: typeof ITERATION_OBSERVATION_SCHEMA_VERSION;
+    observationId: string;
+    runId: string;
+    sessionId: string;
+    resultOwnerId: string;
+    processGroup: number;
+    scenarioName: string;
+    scenarioIndex: number;
+    simulationIndex: number;
+    simulationKind: string;
+    phase: "warmup" | "bombing";
+    globalOrdinal64: string;
+    globalSecondaryOrdinal64: string;
+    shardIndex: number;
+    shardCount: number;
+    iterationId: string;
+    attemptIndex: number;
+    isFinalAttempt: boolean;
+    startedUtcNs: string;
+    completedUtcNs: string;
+    observedLatencyUs64: string;
+    reportedLatencyUs64: string;
+    isSuccess: boolean;
+    statusCode: string;
+    sizeBytes64: string;
+    steps: LoadStrikeIterationStepObservationV1[];
+}
+export interface LoadStrikeIterationObservationBatchV1 {
+    schemaVersion: typeof ITERATION_OBSERVATION_BATCH_SCHEMA_VERSION;
+    batchId: string;
+    runId: string;
+    sessionId: string;
+    resultOwnerId: string;
+    processGroup: number;
+    batchSequence64: string;
+    createdUtcNs: string;
+    firstObservationUtcNs: string;
+    lastObservationUtcNs: string;
+    observations: LoadStrikeIterationObservationV1[];
+    capturedCount64: string;
+    droppedBeforeBatch64: string;
+    compression: "gzip-json";
+}
+export interface LoadStrikeIterationObservationStreamCompletionV1 {
+    schemaVersion: typeof ITERATION_OBSERVATION_STREAM_COMPLETION_SCHEMA_VERSION;
+    runId: string;
+    sessionId: string;
+    resultOwnerId: string;
+    /** Additive in schema v1. Readers must treat an absent value as "1". */
+    expectedResultOwnerCount64?: string;
+    processGroup: number;
+    lastBatchSequence64: string;
+    capturedCount64: string;
+    deliveredCount64: string;
+    droppedBufferCount64: string;
+    droppedSinkCount64: string;
+    reportingComplete: boolean;
+    completedUtcNs: string;
+}
+export interface LoadStrikeObservationDeliveryStats {
+    lastBatchSequence64: string;
+    capturedCount64: string;
+    deliveredCount64: string;
+    droppedBufferCount64: string;
+    droppedSinkCount64: string;
+    readonly LastBatchSequence64?: string;
+    readonly CapturedCount64?: string;
+    readonly DeliveredCount64?: string;
+    readonly DroppedBufferCount64?: string;
+    readonly DroppedSinkCount64?: string;
+}
+export interface IterationObservationDeliveryResult extends LoadStrikeObservationDeliveryStats {
+    reportingComplete: boolean;
+}
+export interface IterationObservationGeneratorWarning {
+    code: string;
+    sinkName?: string;
+    scenarioName: string;
+    scenarioIndex: number;
+    simulationIndex: number;
+    simulationKind: string;
+    count64: string;
+    message: string;
+    firstObservedUtcNs: string;
+    lastObservedUtcNs: string;
+}
+export interface IterationObservationSettings {
+    flushIntervalMs: number;
+    maxBufferBytes: number;
+    maxObservationsPerBatch: number;
+    maxBatchBytes: number;
+    sinkQueueDepth: number;
+    sinkParallelism: number;
+    drainTimeoutMs: number;
+}
+export declare const DEFAULT_ITERATION_OBSERVATION_SETTINGS: Readonly<IterationObservationSettings>;
+export interface IterationObservationClock {
+    nowUtcNs(): bigint;
+    setInterval(callback: () => void, intervalMs: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+export interface IterationObservationSinkTarget {
+    name: string;
+    iterationObservationPortalSink?: boolean;
+    iterationObservationShapeLimited?: boolean;
+    saveIterationBatch?: (batch: LoadStrikeIterationObservationBatchV1) => Promise<void> | void;
+    completeIterationObservationStream?: (completion: LoadStrikeIterationObservationStreamCompletionV1) => Promise<void> | void;
+}
+export interface CreateIterationStepObservationInput {
+    stepName: string;
+    sortIndex: number;
+    startedUtcNs: string | bigint | number;
+    completedUtcNs: string | bigint | number;
+    observedLatencyUs64: string | bigint | number;
+    reportedLatencyUs64: string | bigint | number;
+    isSuccess: boolean;
+    statusCode: string;
+    sizeBytes64: string | bigint | number;
+}
+export interface CreateIterationObservationInput {
+    runId: string;
+    sessionId: string;
+    resultOwnerId: string;
+    processGroup: number;
+    scenarioName: string;
+    scenarioIndex: number;
+    simulationIndex: number;
+    simulationKind: string;
+    phase: "warmup" | "bombing";
+    globalOrdinal64: string | bigint | number;
+    globalSecondaryOrdinal64?: string | bigint | number;
+    iterationId?: string;
+    shardIndex: number;
+    shardCount: number;
+    attemptIndex: number;
+    isFinalAttempt: boolean;
+    startedUtcNs: string | bigint | number;
+    completedUtcNs: string | bigint | number;
+    observedLatencyUs64: string | bigint | number;
+    reportedLatencyUs64: string | bigint | number;
+    isSuccess: boolean;
+    statusCode: string;
+    sizeBytes64: string | bigint | number;
+    steps: LoadStrikeIterationStepObservationV1[];
+}
+interface BufferedObservation {
+    observation: LoadStrikeIterationObservationV1;
+    jsonBytes: number;
+}
+export declare function utcNowNs(): bigint;
+export declare function deriveIterationId(runId: string, resultOwnerId: string, scenarioName: string, simulationIndex: number, globalOrdinal64: string | bigint | number): string;
+export declare function deriveObservationId(iterationId: string, attemptIndex: number): string;
+export declare function deriveIterationBatchId(runId: string, resultOwnerId: string, batchSequence64: string | bigint | number): string;
+export declare function createIterationStepObservation(input: CreateIterationStepObservationInput): LoadStrikeIterationStepObservationV1;
+export declare function createIterationObservation(input: CreateIterationObservationInput): LoadStrikeIterationObservationV1;
+export declare function serializeIterationObservationBatchGzipJson(value: unknown): Buffer;
+export declare class ProcessIterationObservationBuffer {
+    private readonly streams;
+    private readonly streamLimits;
+    private totalBytes;
+    get byteLength(): number;
+    register(streamKey: symbol, maxBufferBytes: number): void;
+    offer(streamKey: symbol, observation: LoadStrikeIterationObservationV1, maxBufferBytes: number, encodedBytes?: number): boolean;
+    drain(streamKey: symbol): BufferedObservation[];
+    release(streamKey: symbol): void;
+    unregister(streamKey: symbol): void;
+    private effectiveLimit;
+}
+export interface IterationObservationReporterOptions {
+    runId: string;
+    sessionId: string;
+    resultOwnerId: string;
+    expectedResultOwnerCount64?: string | bigint | number;
+    processGroup: number;
+    sinks: IterationObservationSinkTarget[];
+    settings?: Partial<IterationObservationSettings>;
+    buffer?: ProcessIterationObservationBuffer;
+    clock?: IterationObservationClock;
+    skipValidation?: boolean;
+}
+export declare class IterationObservationReporter {
+    private readonly options;
+    private readonly streamKey;
+    private readonly settings;
+    private readonly buffer;
+    private readonly clock;
+    private readonly dispatchers;
+    private readonly warnings;
+    private readonly timer;
+    private readonly batchEnvelopeBytes;
+    private sequence;
+    private captured;
+    private droppedBuffer;
+    private unsupportedSinkCount;
+    private sealed;
+    private finalResult;
+    private readonly expectedResultOwnerCount64;
+    constructor(options: IterationObservationReporterOptions);
+    get enabled(): boolean;
+    capture(observation: LoadStrikeIterationObservationV1): boolean;
+    flushNow(): void;
+    sealAndDrain(): Promise<IterationObservationDeliveryResult>;
+    buildWarnings(): IterationObservationGeneratorWarning[];
+    private createBatch;
+    private createCompletion;
+    private recordSinkDrop;
+    private recordWarning;
+}
+export declare function validateIterationObservationSettings(settings: IterationObservationSettings): void;
+export {};