@loadstrike/loadstrike-sdk 1.0.30201 → 1.0.31001

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

@@ -0,0 +1,230 @@
+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";
+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;
+    sinkRetryCount?: number;
+    sinkRetryBackoffMs?: number;
+    logger?: IterationObservationDiagnosticLogger;
+}
+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>;
+    private completeWithRetries;
+    buildWarnings(): IterationObservationGeneratorWarning[];
+    private createBatch;
+    private createCompletion;
+    private recordSinkDrop;
+    private recordWarning;
+}
+export declare function validateIterationObservationSettings(settings: IterationObservationSettings): void;
+export {};

package/dist/types/load-engine-v2.d.ts

@@ -0,0 +1,147 @@
+export interface LoadEngineV2Settings {
+    contractVersion: 2;
+    maxInFlight: number;
+    clusterLoadScope: "Global";
+    statisticsReportingIntervalNs: bigint;
+    maxStatusGroupsPerSeries: number;
+}
+export interface LoadEngineV2TrafficMixUnit {
+    laneOrdinal: bigint;
+    globalRank: bigint;
+}
+export declare function buildLoadEngineV2TrafficMixRunId(runId: string, declarationIndex: number, name: string): string;
+export declare function buildLoadEngineV2TrafficMixSeedId(declarationIndex: number, name: string): string;
+export declare function loadEngineV2TrafficMixRank(weights: readonly number[], laneIndex: number, laneOrdinal: bigint): bigint;
+export declare function loadEngineV2TrafficMixLaneUnitCount(globalUnitCount: bigint, weights: readonly number[], laneIndex: number): bigint;
+export declare function loadEngineV2TrafficMixOwnedUnits(globalUnitCount: bigint, weights: readonly number[], laneIndex: number, shardIndex: number, shardCount: number): LoadEngineV2TrafficMixUnit[];
+export type LoadEngineV2ArrivalDecision = "wait" | "start" | "scheduler_late" | "max_in_flight";
+export interface LoadStrikeHistogramV1Sidecar {
+    schemaVersion: "loadstrike.histogram/1";
+    mode: "exact-normalized" | "quantized-v1";
+    count64: string;
+    zeroCount64: string;
+    minimum64: string;
+    maximum64: string;
+    origin64: string;
+    meanOffsetBits: string;
+    m2Bits: string;
+    exactTotal64: string;
+    exactSamples64: string[];
+    buckets: Array<{
+        bucketKey64: string;
+        count64: string;
+    }>;
+}
+export interface LoadEngineV2DistributionRecord {
+    seriesKind: "scenario" | "step" | "scheduler-decision-lag" | "scheduler-start-lag" | "correlation";
+    scenarioIndex64: string;
+    scenarioName: string;
+    identityKeyHex: string;
+    outcome: "ok" | "fail" | "all" | "none";
+    unit: "microseconds" | "bytes" | "count";
+    histogram: LoadStrikeHistogramV1Sidecar;
+    exactTotalDecimalOrEmpty?: string;
+    bands?: Array<{
+        bandId64: string;
+        count64: string;
+    }>;
+}
+export interface LoadEngineV2StatusSummaryRecord {
+    statusIdentityKeyHex: string;
+    display: string;
+    count64: string;
+    aggregatedObservationCount64: string;
+    hasAggregatedIdentities: boolean;
+}
+export interface LoadEngineV2MeasurementOutcomeSummary {
+    outcome: "ok" | "fail";
+    statusObservationCount64: string;
+    statuses: LoadEngineV2StatusSummaryRecord[];
+}
+export interface LoadEngineV2MeasurementSummary {
+    seriesKind: "scenario" | "step";
+    scenarioIndex64: string;
+    scenarioName: string;
+    identityKeyHex: string;
+    display: string;
+    observationCount64: string;
+    successCount64: string;
+    failureCount64: string;
+    aggregatedObservationCount64: string;
+    hasAggregatedIdentities: boolean;
+    outcomes: [LoadEngineV2MeasurementOutcomeSummary, LoadEngineV2MeasurementOutcomeSummary];
+}
+export interface LoadEngineV2HistogramArtifact {
+    distributions: LoadEngineV2DistributionRecord[];
+    measurementSummaries: LoadEngineV2MeasurementSummary[];
+}
+export declare class LoadEngineV2ExecutionBudget {
+    readonly maxInFlight: number;
+    private currentValue;
+    private highWaterValue;
+    constructor(maxInFlight: number);
+    get current(): number;
+    get highWater(): number;
+    tryAcquire(): (() => void) | undefined;
+}
+/**
+ * Canonical bounded streaming histogram used by Load Engine V2.
+ *
+ * The first 2,048 normalized values remain exact. Larger streams are promoted
+ * into the portable quantized-v1 layout, whose 7,296 counters cover every
+ * non-negative signed 64-bit value with a maximum relative error of 1/128.
+ */
+export declare class LoadStrikeHistogramV1 {
+    static readonly exactLimit = 2048;
+    static readonly bucketCount = 7296;
+    private exactSamples;
+    private buckets;
+    private countValue;
+    private minimumValue;
+    private maximumValue;
+    private originValue;
+    private meanOffsetValue;
+    private m2;
+    private exactTotalValue;
+    get count(): bigint;
+    get minimum(): bigint;
+    get maximum(): bigint;
+    get origin(): bigint;
+    get meanOffset(): number;
+    get mean(): number;
+    get populationStandardDeviation(): number;
+    get mode(): "exact-normalized" | "quantized-v1";
+    get maxRelativeError(): number;
+    get retainedValueCount(): number;
+    get exactTotal(): bigint;
+    toSidecar(): LoadStrikeHistogramV1Sidecar;
+    static fromSidecar(sidecar: LoadStrikeHistogramV1Sidecar): LoadStrikeHistogramV1;
+    record(input: bigint): void;
+    clone(): LoadStrikeHistogramV1;
+    merge(other: LoadStrikeHistogramV1): void;
+    percentile(percentile: number): bigint;
+    private updateMoments;
+    private promote;
+    private addBucket;
+    private copyFrom;
+    private static bucketIndex;
+    private static bucketUpperBound;
+    private static bucketKeyFromIndex;
+    private static bucketIndexFromKey;
+}
+/** Serializes the canonical cumulative LoadStrikeHistogramArtifactV1 (`LS-H1`). */
+export declare function serializeLoadEngineV2HistogramArtifact(artifact: LoadEngineV2HistogramArtifact): Buffer;
+/** Strictly parses, validates, and canonical-byte checks an `LS-H1` artifact. */
+export declare function parseLoadEngineV2HistogramArtifact(bytes: Uint8Array): LoadEngineV2HistogramArtifact;
+export declare function createDefaultLoadEngineV2Settings(): LoadEngineV2Settings;
+export declare function fnv1a32(value: string): number;
+export declare function planFixedDeadlines(rate: number, intervalNs: bigint, durationNs: bigint): bigint[];
+export declare function planFixedIterationDeadlines(rate: number, intervalNs: bigint, iterations: number): bigint[];
+export declare function planRampingInjectionDeadlines(rate: number, intervalNs: bigint, durationNs: bigint): bigint[];
+export declare function planRampingConstantDeadlines(copies: number, durationNs: bigint): bigint[];
+export declare function planRandomInjectionDeadlines(minRate: number, maxRate: number, intervalNs: bigint, durationNs: bigint, seed: number): bigint[];
+export declare function xorshift32(input: number): number;
+export declare function loadEngineV2FixedDeadlineNs(ordinal: bigint, rate: number, intervalNs: bigint): bigint;
+export declare function loadEngineV2FixedArrivalCount(rate: number, intervalNs: bigint, durationNs: bigint): bigint;
+export declare function loadEngineV2LatenessToleranceNs(rate: number, intervalNs: bigint): bigint;
+export declare function classifyLoadEngineV2Arrival(nowNs: bigint, deadlineNs: bigint, toleranceNs: bigint, permitAvailable: boolean): LoadEngineV2ArrivalDecision;