@loadstrike/loadstrike-sdk 1.0.30001 → 1.0.30401

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;