@loadstrike/loadstrike-sdk 1.0.30201 → 1.0.30401

package/dist/esm/load-engine-v2.js

@@ -0,0 +1,942 @@
+import { createHash } from "node:crypto";
+export function buildLoadEngineV2TrafficMixRunId(runId, declarationIndex, name) {
+    if (!runId || Buffer.byteLength(runId, "utf8") > 128) {
+        throw new Error("Load Engine V2 traffic-mix run ID is invalid.");
+    }
+    return buildLoadEngineV2TrafficMixId("LS-TM1\n", runId, declarationIndex, name);
+}
+export function buildLoadEngineV2TrafficMixSeedId(declarationIndex, name) {
+    return buildLoadEngineV2TrafficMixId("LS-TMS1\n", undefined, declarationIndex, name);
+}
+export function loadEngineV2TrafficMixRank(weights, laneIndex, laneOrdinal) {
+    validateLoadEngineV2TrafficMix(weights, laneIndex, laneOrdinal);
+    const denominator = BigInt(weights[laneIndex]);
+    const midpointNumerator = 2n * laneOrdinal + 1n;
+    let rank = 0n;
+    for (let otherLane = 0; otherLane < weights.length; otherLane += 1) {
+        const product = midpointNumerator * BigInt(weights[otherLane]);
+        const quotient = (product - 1n) / denominator;
+        const before = (quotient + 1n) / 2n;
+        const tie = otherLane < laneIndex
+            && product % denominator === 0n
+            && (product / denominator) % 2n !== 0n
+            ? 1n
+            : 0n;
+        rank += before + tie;
+    }
+    if (rank > 9223372036854775807n) {
+        throw new RangeError("Load Engine V2 traffic-mix rank exceeds signed 64-bit storage.");
+    }
+    return rank;
+}
+export function loadEngineV2TrafficMixLaneUnitCount(globalUnitCount, weights, laneIndex) {
+    if (globalUnitCount < 0n || globalUnitCount > 9223372036854775807n) {
+        throw new RangeError("Load Engine V2 traffic-mix global unit count is invalid.");
+    }
+    validateLoadEngineV2TrafficMix(weights, laneIndex, 0n);
+    let low = 0n;
+    let high = globalUnitCount;
+    while (low < high) {
+        const middle = low + ((high - low) >> 1n);
+        if (loadEngineV2TrafficMixRank(weights, laneIndex, middle) < globalUnitCount) {
+            low = middle + 1n;
+        }
+        else {
+            high = middle;
+        }
+    }
+    return low;
+}
+export function loadEngineV2TrafficMixOwnedUnits(globalUnitCount, weights, laneIndex, shardIndex, shardCount) {
+    if (!Number.isSafeInteger(shardCount) || shardCount <= 0
+        || !Number.isSafeInteger(shardIndex) || shardIndex < 0 || shardIndex >= shardCount) {
+        throw new RangeError("Load Engine V2 traffic-mix shard request is invalid.");
+    }
+    const laneCount = loadEngineV2TrafficMixLaneUnitCount(globalUnitCount, weights, laneIndex);
+    const result = [];
+    for (let laneOrdinal = BigInt(shardIndex); laneOrdinal < laneCount; laneOrdinal += BigInt(shardCount)) {
+        result.push({
+            laneOrdinal,
+            globalRank: loadEngineV2TrafficMixRank(weights, laneIndex, laneOrdinal)
+        });
+    }
+    return result;
+}
+function buildLoadEngineV2TrafficMixId(magic, runId, declarationIndex, name) {
+    if (!Number.isSafeInteger(declarationIndex) || declarationIndex < 0) {
+        throw new RangeError("Load Engine V2 traffic-mix declaration index is invalid.");
+    }
+    if (!name.trim()) {
+        throw new Error("Load Engine V2 traffic-mix name is required.");
+    }
+    const values = [...(runId === undefined ? [] : [runId]), declarationIndex.toString(), name];
+    const fields = values.map((value) => {
+        const bytes = Buffer.from(value, "utf8");
+        const framed = Buffer.allocUnsafe(4 + bytes.length);
+        framed.writeUInt32BE(bytes.length, 0);
+        bytes.copy(framed, 4);
+        return framed;
+    });
+    return createHash("sha256").update(Buffer.concat([Buffer.from(magic, "ascii"), ...fields])).digest("hex");
+}
+function validateLoadEngineV2TrafficMix(weights, laneIndex, laneOrdinal) {
+    if (!Array.isArray(weights) || weights.length === 0
+        || weights.some((weight) => !Number.isSafeInteger(weight) || weight <= 0)) {
+        throw new Error("Load Engine V2 traffic-mix weights must be positive integers.");
+    }
+    if (!Number.isSafeInteger(laneIndex) || laneIndex < 0 || laneIndex >= weights.length) {
+        throw new RangeError("Load Engine V2 traffic-mix lane index is invalid.");
+    }
+    if (laneOrdinal < 0n || laneOrdinal > 9223372036854775807n) {
+        throw new RangeError("Load Engine V2 traffic-mix lane ordinal is invalid.");
+    }
+}
+export class LoadEngineV2ExecutionBudget {
+    constructor(maxInFlight) {
+        this.maxInFlight = maxInFlight;
+        this.currentValue = 0;
+        this.highWaterValue = 0;
+        if (!Number.isSafeInteger(maxInFlight) || maxInFlight < 1 || maxInFlight > 1000000) {
+            throw new RangeError("maxInFlight must be an integer from 1 through 1000000.");
+        }
+    }
+    get current() {
+        return this.currentValue;
+    }
+    get highWater() {
+        return this.highWaterValue;
+    }
+    tryAcquire() {
+        if (this.currentValue >= this.maxInFlight) {
+            return undefined;
+        }
+        this.currentValue += 1;
+        this.highWaterValue = Math.max(this.highWaterValue, this.currentValue);
+        let released = false;
+        return () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            this.currentValue -= 1;
+        };
+    }
+}
+/**
+ * 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 class LoadStrikeHistogramV1 {
+    constructor() {
+        this.exactSamples = [];
+        this.countValue = 0n;
+        this.minimumValue = 0n;
+        this.maximumValue = 0n;
+        this.originValue = 0n;
+        this.meanOffsetValue = 0;
+        this.m2 = 0;
+        this.exactTotalValue = 0n;
+    }
+    get count() { return this.countValue; }
+    get minimum() { return this.countValue === 0n ? 0n : this.minimumValue; }
+    get maximum() { return this.countValue === 0n ? 0n : this.maximumValue; }
+    get origin() { return this.countValue === 0n ? 0n : this.originValue; }
+    get meanOffset() { return this.countValue === 0n ? 0 : this.meanOffsetValue; }
+    get mean() { return this.countValue === 0n ? 0 : Number(this.originValue) + this.meanOffsetValue; }
+    get populationStandardDeviation() {
+        return this.countValue <= 1n ? 0 : Math.sqrt(this.m2 / Number(this.countValue));
+    }
+    get mode() {
+        return this.exactSamples ? "exact-normalized" : "quantized-v1";
+    }
+    get maxRelativeError() { return this.exactSamples ? 0 : 0.0078125; }
+    get retainedValueCount() {
+        return this.exactSamples?.length ?? this.buckets.reduce((total, value) => total + (value === 0n ? 0 : 1), 0);
+    }
+    get exactTotal() { return this.exactTotalValue; }
+    toSidecar() {
+        const exactSamples = this.exactSamples
+            ? [...this.exactSamples].sort(compareBigInt).map((value) => value.toString())
+            : [];
+        const buckets = [];
+        let zeroCount = 0n;
+        if (this.exactSamples) {
+            zeroCount = this.exactSamples.reduce((count, value) => count + (value === 0n ? 1n : 0n), 0n);
+        }
+        else {
+            zeroCount = this.buckets[0];
+            for (let index = 1; index < LoadStrikeHistogramV1.bucketCount; index += 1) {
+                const count = this.buckets[index];
+                if (count === 0n)
+                    continue;
+                buckets.push({
+                    bucketKey64: LoadStrikeHistogramV1.bucketKeyFromIndex(index).toString(),
+                    count64: count.toString()
+                });
+            }
+        }
+        return {
+            schemaVersion: "loadstrike.histogram/1",
+            mode: this.mode,
+            count64: this.countValue.toString(),
+            zeroCount64: zeroCount.toString(),
+            minimum64: this.minimum.toString(),
+            maximum64: this.maximum.toString(),
+            origin64: this.origin.toString(),
+            meanOffsetBits: binary64Bits(this.meanOffsetValue),
+            m2Bits: binary64Bits(this.m2),
+            exactTotal64: this.exactTotalValue.toString(),
+            exactSamples64: exactSamples,
+            buckets
+        };
+    }
+    static fromSidecar(sidecar) {
+        if (!sidecar || sidecar.schemaVersion !== "loadstrike.histogram/1") {
+            throw new Error("Histogram sidecar schema is unsupported.");
+        }
+        const count = parseCanonicalNonNegativeBigInt(sidecar.count64, "histogram count");
+        const zeroCount = parseCanonicalNonNegativeBigInt(sidecar.zeroCount64, "histogram zero count");
+        const minimum = parseCanonicalNonNegativeBigInt(sidecar.minimum64, "histogram minimum");
+        const maximum = parseCanonicalNonNegativeBigInt(sidecar.maximum64, "histogram maximum");
+        const origin = parseCanonicalNonNegativeBigInt(sidecar.origin64, "histogram origin");
+        const exactTotal = parseCanonicalNonNegativeBigInt(sidecar.exactTotal64, "histogram exact total");
+        if (count > 9223372036854775807n || minimum > maximum || zeroCount > count) {
+            throw new Error("Histogram sidecar counters do not reconcile.");
+        }
+        if (count === 0n && (minimum !== 0n || maximum !== 0n || origin !== 0n || exactTotal !== 0n)) {
+            throw new Error("Empty histogram sidecar state is invalid.");
+        }
+        if (count > 0n && (origin < minimum || origin > maximum)) {
+            throw new Error("Histogram sidecar origin is outside its range.");
+        }
+        const meanOffset = binary64FromBits(sidecar.meanOffsetBits, "histogram mean offset");
+        const m2 = binary64FromBits(sidecar.m2Bits, "histogram M2");
+        if (Object.is(m2, -0) || m2 < 0)
+            throw new Error("Histogram sidecar M2 must be non-negative.");
+        const restored = new LoadStrikeHistogramV1();
+        restored.countValue = count;
+        restored.minimumValue = minimum;
+        restored.maximumValue = maximum;
+        restored.originValue = origin;
+        restored.meanOffsetValue = meanOffset;
+        restored.m2 = m2;
+        restored.exactTotalValue = exactTotal;
+        if (sidecar.mode === "exact-normalized") {
+            if (sidecar.buckets.length !== 0 || sidecar.exactSamples64.length > LoadStrikeHistogramV1.exactLimit) {
+                throw new Error("Exact histogram sidecar shape is invalid.");
+            }
+            const samples = sidecar.exactSamples64.map((value) => parseCanonicalNonNegativeBigInt(value, "histogram exact sample"));
+            if (BigInt(samples.length) !== count || !isSortedBigInt(samples)
+                || samples.filter((value) => value === 0n).length !== Number(zeroCount)
+                || samples.some((value) => value < minimum || value > maximum)) {
+                throw new Error("Exact histogram sidecar samples do not reconcile.");
+            }
+            restored.exactSamples = samples;
+            restored.buckets = undefined;
+            return restored;
+        }
+        if (sidecar.mode !== "quantized-v1" || sidecar.exactSamples64.length !== 0) {
+            throw new Error("Histogram sidecar mode is invalid.");
+        }
+        restored.exactSamples = undefined;
+        restored.buckets = Array.from({ length: LoadStrikeHistogramV1.bucketCount }, () => 0n);
+        restored.buckets[0] = zeroCount;
+        let previousKey = -1n;
+        let total = zeroCount;
+        for (const row of sidecar.buckets) {
+            const key = parseCanonicalNonNegativeBigInt(row.bucketKey64, "histogram bucket key");
+            const bucketCount = parseCanonicalNonNegativeBigInt(row.count64, "histogram bucket count");
+            if (key <= previousKey || bucketCount <= 0n) {
+                throw new Error("Histogram sidecar buckets must be sorted, unique, and positive.");
+            }
+            restored.buckets[LoadStrikeHistogramV1.bucketIndexFromKey(key)] = bucketCount;
+            previousKey = key;
+            total += bucketCount;
+        }
+        if (total !== count)
+            throw new Error("Histogram sidecar bucket counts do not reconcile.");
+        return restored;
+    }
+    record(input) {
+        if (input > 9223372036854775807n) {
+            throw new RangeError("Histogram values must fit in a non-negative signed 64-bit integer.");
+        }
+        const value = input < 0n ? 0n : input;
+        this.updateMoments(value);
+        if (this.exactSamples && this.exactSamples.length < LoadStrikeHistogramV1.exactLimit) {
+            this.exactSamples.push(value);
+            return;
+        }
+        if (this.exactSamples)
+            this.promote();
+        this.addBucket(value, 1n);
+    }
+    clone() {
+        const clone = new LoadStrikeHistogramV1();
+        clone.copyFrom(this);
+        return clone;
+    }
+    merge(other) {
+        if (other.countValue === 0n)
+            return;
+        if (this.countValue === 0n) {
+            this.copyFrom(other);
+            return;
+        }
+        const leftCount = this.countValue;
+        const rightCount = other.countValue;
+        const combinedCount = leftCount + rightCount;
+        if (combinedCount > 9223372036854775807n) {
+            throw new RangeError("Merged histogram count exceeds signed 64-bit storage.");
+        }
+        const delta = Number(other.originValue - this.originValue) + other.meanOffsetValue - this.meanOffsetValue;
+        const mergedM2 = this.m2 + other.m2
+            + delta * delta * Number(leftCount) * Number(rightCount) / Number(combinedCount);
+        if (!Number.isFinite(mergedM2) || mergedM2 < 0) {
+            throw new Error("Histogram merge produced invalid variance state.");
+        }
+        this.meanOffsetValue += delta * Number(rightCount) / Number(combinedCount);
+        this.m2 = mergedM2 === 0 ? 0 : mergedM2;
+        this.countValue = combinedCount;
+        this.minimumValue = this.minimumValue < other.minimumValue ? this.minimumValue : other.minimumValue;
+        this.maximumValue = this.maximumValue > other.maximumValue ? this.maximumValue : other.maximumValue;
+        this.exactTotalValue += other.exactTotalValue;
+        if (this.exactSamples && other.exactSamples && combinedCount <= BigInt(LoadStrikeHistogramV1.exactLimit)) {
+            this.exactSamples.push(...other.exactSamples);
+            return;
+        }
+        if (this.exactSamples)
+            this.promote();
+        if (other.exactSamples) {
+            for (const sample of other.exactSamples)
+                this.addBucket(sample, 1n);
+        }
+        else {
+            for (let index = 0; index < LoadStrikeHistogramV1.bucketCount; index += 1) {
+                if (other.buckets[index] !== 0n)
+                    this.buckets[index] += other.buckets[index];
+            }
+        }
+    }
+    percentile(percentile) {
+        if (!Number.isFinite(percentile) || percentile < 0 || percentile > 1) {
+            throw new RangeError("percentile must be from 0 through 1.");
+        }
+        if (this.countValue === 0n)
+            return 0n;
+        if (percentile === 0)
+            return this.minimumValue;
+        if (percentile === 1)
+            return this.maximumValue;
+        const scale = 1000000000000n;
+        const numerator = BigInt(Math.ceil(percentile * Number(scale)));
+        const rank = maximumBigInt(1n, divideCeiling(this.countValue * numerator, scale));
+        if (this.exactSamples) {
+            const ordered = [...this.exactSamples].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+            return ordered[Number(rank - 1n)];
+        }
+        let cumulative = 0n;
+        for (let index = 0; index < LoadStrikeHistogramV1.bucketCount; index += 1) {
+            cumulative += this.buckets[index];
+            if (cumulative >= rank) {
+                const upper = LoadStrikeHistogramV1.bucketUpperBound(index);
+                return upper < this.maximumValue ? upper : this.maximumValue;
+            }
+        }
+        throw new Error("Histogram counts do not reconcile.");
+    }
+    updateMoments(value) {
+        if (this.countValue === 0n) {
+            this.countValue = 1n;
+            this.minimumValue = value;
+            this.maximumValue = value;
+            this.originValue = value;
+            this.exactTotalValue = value;
+            return;
+        }
+        const nextCount = this.countValue + 1n;
+        if (nextCount > 9223372036854775807n)
+            throw new RangeError("Histogram count exceeds signed 64-bit storage.");
+        const offset = Number(value - this.originValue);
+        const delta = offset - this.meanOffsetValue;
+        this.meanOffsetValue += delta / Number(nextCount);
+        const updatedM2 = this.m2 + delta * (offset - this.meanOffsetValue);
+        if (!Number.isFinite(updatedM2) || updatedM2 < 0)
+            throw new Error("Histogram update produced invalid variance state.");
+        this.m2 = updatedM2 === 0 ? 0 : updatedM2;
+        this.countValue = nextCount;
+        if (value < this.minimumValue)
+            this.minimumValue = value;
+        if (value > this.maximumValue)
+            this.maximumValue = value;
+        this.exactTotalValue += value;
+    }
+    promote() {
+        this.buckets = Array.from({ length: LoadStrikeHistogramV1.bucketCount }, () => 0n);
+        for (const sample of this.exactSamples)
+            this.addBucket(sample, 1n);
+        this.exactSamples = undefined;
+    }
+    addBucket(value, count) {
+        this.buckets[LoadStrikeHistogramV1.bucketIndex(value)] += count;
+    }
+    copyFrom(other) {
+        this.countValue = other.countValue;
+        this.minimumValue = other.minimumValue;
+        this.maximumValue = other.maximumValue;
+        this.originValue = other.originValue;
+        this.meanOffsetValue = other.meanOffsetValue;
+        this.m2 = other.m2;
+        this.exactTotalValue = other.exactTotalValue;
+        this.exactSamples = other.exactSamples ? [...other.exactSamples] : undefined;
+        this.buckets = other.buckets ? [...other.buckets] : undefined;
+    }
+    static bucketIndex(value) {
+        if (value === 0n)
+            return 0;
+        const exponent = value.toString(2).length - 1;
+        const shift = Math.max(exponent - 7, 0);
+        const mantissa = Number(value >> BigInt(shift));
+        return shift === 0 ? mantissa : 256 + (shift - 1) * 128 + (mantissa - 128);
+    }
+    static bucketUpperBound(index) {
+        if (index === 0)
+            return 0n;
+        if (index <= 255)
+            return BigInt(index);
+        const shift = 1 + Math.floor((index - 256) / 128);
+        const mantissa = 128 + (index - 256) % 128;
+        return (BigInt(mantissa) << BigInt(shift)) + (1n << BigInt(shift)) - 1n;
+    }
+    static bucketKeyFromIndex(index) {
+        if (index <= 0 || index >= LoadStrikeHistogramV1.bucketCount) {
+            throw new RangeError("Histogram bucket index is invalid.");
+        }
+        if (index <= 255)
+            return BigInt(index);
+        const shift = 1 + Math.floor((index - 256) / 128);
+        const mantissa = 128 + (index - 256) % 128;
+        return BigInt((shift << 8) | mantissa);
+    }
+    static bucketIndexFromKey(key) {
+        if (key > BigInt(Number.MAX_SAFE_INTEGER))
+            throw new Error("Histogram bucket key is invalid.");
+        const numeric = Number(key);
+        const shift = numeric >> 8;
+        const mantissa = numeric & 255;
+        if (shift === 0 && mantissa >= 1 && mantissa <= 255)
+            return mantissa;
+        if (shift < 1 || shift > 55 || mantissa < 128 || mantissa > 255) {
+            throw new Error("Histogram bucket key is invalid.");
+        }
+        return 256 + (shift - 1) * 128 + (mantissa - 128);
+    }
+}
+LoadStrikeHistogramV1.exactLimit = 2048;
+LoadStrikeHistogramV1.bucketCount = 7296;
+/** Serializes the canonical cumulative LoadStrikeHistogramArtifactV1 (`LS-H1`). */
+export function serializeLoadEngineV2HistogramArtifact(artifact) {
+    const distributions = [...artifact.distributions].sort(compareV2DistributionRecords);
+    const summaries = [...artifact.measurementSummaries].sort(compareV2MeasurementSummaries);
+    if (distributions.length > 100000 || summaries.length > 100000) {
+        throw new Error("Load Engine V2 histogram artifact record count exceeds the supported bound.");
+    }
+    if (distributions.length !== summaries.length * 6
+        && (distributions.length < summaries.length * 6
+            || (distributions.length - summaries.length * 6) % 2 !== 0)) {
+        throw new Error("Load Engine V2 histogram artifact distribution/summary counts do not reconcile.");
+    }
+    const fields = [Buffer.from("LS-H1\n", "ascii")];
+    const write = (value) => { fields.push(frameV2Text(value)); };
+    write("1");
+    write("1");
+    write(distributions.length.toString());
+    distributions.forEach((record) => fields.push(serializeV2DistributionRecord(record)));
+    write(summaries.length.toString());
+    summaries.forEach((summary) => fields.push(frameV2Bytes(serializeV2MeasurementSummary(summary))));
+    const encoded = Buffer.concat(fields);
+    if (encoded.length > 67108864) {
+        throw new Error("Load Engine V2 histogram artifact exceeds the signed non-detail artifact bound.");
+    }
+    return encoded;
+}
+/** Strictly parses, validates, and canonical-byte checks an `LS-H1` artifact. */
+export function parseLoadEngineV2HistogramArtifact(bytes) {
+    const input = Buffer.from(bytes);
+    if (input.length > 67108864 || !input.subarray(0, 6).equals(Buffer.from("LS-H1\n", "ascii"))) {
+        throw new Error("Load Engine V2 histogram artifact magic or byte bound is invalid.");
+    }
+    const cursor = new V2ArtifactCursor(input, 6);
+    if (cursor.text() !== "1" || cursor.text() !== "1") {
+        throw new Error("Load Engine V2 histogram artifact version is unsupported.");
+    }
+    const distributionCount = cursor.count("distribution record count", 100000);
+    const distributions = [];
+    for (let index = 0; index < distributionCount; index += 1) {
+        distributions.push(parseV2DistributionRecord(cursor));
+    }
+    const summaryCount = cursor.count("measurement summary count", 100000);
+    const measurementSummaries = [];
+    for (let index = 0; index < summaryCount; index += 1) {
+        const nested = new V2ArtifactCursor(cursor.bytes(), 0);
+        measurementSummaries.push(parseV2MeasurementSummary(nested));
+        nested.requireEnd();
+    }
+    cursor.requireEnd();
+    const artifact = { distributions, measurementSummaries };
+    if (!serializeLoadEngineV2HistogramArtifact(artifact).equals(input)) {
+        throw new Error("Load Engine V2 histogram artifact is not in canonical byte order.");
+    }
+    return artifact;
+}
+function serializeV2DistributionRecord(record) {
+    validateV2SeriesKind(record.seriesKind);
+    parseCanonicalNonNegativeBigInt(record.scenarioIndex64, "distribution scenario index");
+    validateV2BoundedText(record.scenarioName, "distribution scenario name", 1024);
+    validateV2Hex(record.identityKeyHex, "distribution identity key");
+    if (!["ok", "fail", "all", "none"].includes(record.outcome)
+        || !["microseconds", "bytes", "count"].includes(record.unit)) {
+        throw new Error("Load Engine V2 distribution outcome or unit is invalid.");
+    }
+    const histogram = LoadStrikeHistogramV1.fromSidecar(record.histogram).toSidecar();
+    const exactTotal = record.exactTotalDecimalOrEmpty ?? histogram.exactTotal64;
+    if (exactTotal !== "")
+        parseCanonicalNonNegativeBigInt(exactTotal, "distribution exact total");
+    const bands = [...(record.bands ?? [])].sort((left, right) => compareCanonicalV2Integers(left.bandId64, right.bandId64));
+    if (bands.length > 64 || new Set(bands.map((value) => value.bandId64)).size !== bands.length) {
+        throw new Error("Load Engine V2 distribution band records are invalid.");
+    }
+    bands.forEach((band) => {
+        parseCanonicalNonNegativeBigInt(band.bandId64, "distribution band ID");
+        parseCanonicalNonNegativeBigInt(band.count64, "distribution band count");
+    });
+    const fields = [];
+    const write = (value) => { fields.push(frameV2Text(value)); };
+    ["distribution", record.seriesKind, record.scenarioIndex64, record.scenarioName,
+        record.identityKeyHex, record.outcome, record.unit, histogram.mode,
+        histogram.mode === "exact-normalized" ? "0" : "0.0078125",
+        histogram.count64, histogram.zeroCount64, histogram.minimum64, histogram.maximum64,
+        histogram.origin64, histogram.meanOffsetBits, histogram.m2Bits, exactTotal,
+        bands.length.toString()].forEach(write);
+    bands.forEach((band) => { write(band.bandId64); write(band.count64); });
+    write(histogram.exactSamples64.length.toString());
+    histogram.exactSamples64.forEach(write);
+    write(histogram.buckets.length.toString());
+    histogram.buckets.forEach((bucket) => { write(bucket.bucketKey64); write(bucket.count64); });
+    return Buffer.concat(fields);
+}
+function parseV2DistributionRecord(cursor) {
+    if (cursor.text() !== "distribution")
+        throw new Error("Load Engine V2 distribution kind is invalid.");
+    const seriesKind = cursor.text();
+    const scenarioIndex64 = cursor.text();
+    const scenarioName = cursor.text();
+    const identityKeyHex = cursor.text();
+    const outcome = cursor.text();
+    const unit = cursor.text();
+    const mode = cursor.text();
+    const maxRelativeError = cursor.text();
+    const count64 = cursor.text();
+    const zeroCount64 = cursor.text();
+    const minimum64 = cursor.text();
+    const maximum64 = cursor.text();
+    const origin64 = cursor.text();
+    const meanOffsetBits = cursor.text();
+    const m2Bits = cursor.text();
+    const exactTotal64 = cursor.text();
+    const bandCount = cursor.count("distribution band count", 64);
+    const bands = Array.from({ length: bandCount }, () => ({ bandId64: cursor.text(), count64: cursor.text() }));
+    const exactSampleCount = cursor.count("histogram exact sample count", LoadStrikeHistogramV1.exactLimit);
+    const exactSamples64 = Array.from({ length: exactSampleCount }, () => cursor.text());
+    const bucketCount = cursor.count("histogram bucket count", LoadStrikeHistogramV1.bucketCount);
+    const buckets = Array.from({ length: bucketCount }, () => ({
+        bucketKey64: cursor.text(), count64: cursor.text()
+    }));
+    if ((mode === "exact-normalized" ? "0" : "0.0078125") !== maxRelativeError) {
+        throw new Error("Load Engine V2 distribution relative-error field is invalid.");
+    }
+    return {
+        seriesKind, scenarioIndex64, scenarioName, identityKeyHex, outcome, unit,
+        histogram: {
+            schemaVersion: "loadstrike.histogram/1", mode, count64, zeroCount64,
+            minimum64, maximum64, origin64, meanOffsetBits, m2Bits, exactTotal64,
+            exactSamples64, buckets
+        },
+        exactTotalDecimalOrEmpty: exactTotal64,
+        bands
+    };
+}
+function serializeV2MeasurementSummary(summary) {
+    if (summary.seriesKind !== "scenario" && summary.seriesKind !== "step") {
+        throw new Error("Load Engine V2 measurement summary kind is invalid.");
+    }
+    parseCanonicalNonNegativeBigInt(summary.scenarioIndex64, "summary scenario index");
+    validateV2BoundedText(summary.scenarioName, "summary scenario name", 1024);
+    validateV2Hex(summary.identityKeyHex, "summary identity key");
+    const observation = parseCanonicalNonNegativeBigInt(summary.observationCount64, "summary observation count");
+    const success = parseCanonicalNonNegativeBigInt(summary.successCount64, "summary success count");
+    const failure = parseCanonicalNonNegativeBigInt(summary.failureCount64, "summary failure count");
+    const aggregated = parseCanonicalNonNegativeBigInt(summary.aggregatedObservationCount64, "summary aggregated observation count");
+    if (observation !== success + failure || aggregated > observation
+        || summary.hasAggregatedIdentities !== (aggregated > 0n)
+        || summary.outcomes.length !== 2 || summary.outcomes[0].outcome !== "ok"
+        || summary.outcomes[1].outcome !== "fail") {
+        throw new Error("Load Engine V2 measurement summary counts do not reconcile.");
+    }
+    const fields = [Buffer.from("LS-MS1\n", "ascii")];
+    const write = (value) => { fields.push(frameV2Text(value)); };
+    ["1", summary.seriesKind, summary.scenarioIndex64, summary.scenarioName,
+        summary.identityKeyHex, summary.display, summary.observationCount64,
+        summary.successCount64, summary.failureCount64, summary.aggregatedObservationCount64,
+        summary.hasAggregatedIdentities ? "1" : "0"].forEach(write);
+    summary.outcomes.forEach((body) => {
+        const statuses = [...body.statuses].sort((left, right) => Buffer.compare(Buffer.from(left.statusIdentityKeyHex, "hex"), Buffer.from(right.statusIdentityKeyHex, "hex")));
+        const statusObservation = parseCanonicalNonNegativeBigInt(body.statusObservationCount64, "status observation count");
+        const sum = statuses.reduce((total, row) => total + parseCanonicalNonNegativeBigInt(row.count64, "status count"), 0n);
+        if (sum !== statusObservation)
+            throw new Error("Load Engine V2 status counts do not reconcile.");
+        write(body.outcome);
+        write(body.statusObservationCount64);
+        write(statuses.length.toString());
+        statuses.forEach((status) => {
+            validateV2Hex(status.statusIdentityKeyHex, "status identity key");
+            const statusCount = parseCanonicalNonNegativeBigInt(status.count64, "status count");
+            const statusAggregated = parseCanonicalNonNegativeBigInt(status.aggregatedObservationCount64, "status aggregated count");
+            if (statusAggregated > statusCount
+                || status.hasAggregatedIdentities !== (statusAggregated > 0n)) {
+                throw new Error("Load Engine V2 status aggregation does not reconcile.");
+            }
+            [status.statusIdentityKeyHex, status.display, status.count64,
+                status.aggregatedObservationCount64, status.hasAggregatedIdentities ? "1" : "0"].forEach(write);
+        });
+    });
+    return Buffer.concat(fields);
+}
+function parseV2MeasurementSummary(cursor) {
+    if (!cursor.raw(7).equals(Buffer.from("LS-MS1\n", "ascii")) || cursor.text() !== "1") {
+        throw new Error("Load Engine V2 measurement summary magic or version is invalid.");
+    }
+    const seriesKind = cursor.text();
+    const scenarioIndex64 = cursor.text();
+    const scenarioName = cursor.text();
+    const identityKeyHex = cursor.text();
+    const display = cursor.text();
+    const observationCount64 = cursor.text();
+    const successCount64 = cursor.text();
+    const failureCount64 = cursor.text();
+    const aggregatedObservationCount64 = cursor.text();
+    const hasAggregatedIdentities = cursor.bit();
+    const outcomes = ["ok", "fail"].map((expectedOutcome) => {
+        const outcome = cursor.text();
+        if (outcome !== expectedOutcome)
+            throw new Error("Load Engine V2 summary outcome order is invalid.");
+        const statusObservationCount64 = cursor.text();
+        const statusCount = cursor.count("summary status count", 10000);
+        const statuses = Array.from({ length: statusCount }, () => ({
+            statusIdentityKeyHex: cursor.text(), display: cursor.text(), count64: cursor.text(),
+            aggregatedObservationCount64: cursor.text(), hasAggregatedIdentities: cursor.bit()
+        }));
+        return { outcome, statusObservationCount64, statuses };
+    });
+    return {
+        seriesKind, scenarioIndex64, scenarioName, identityKeyHex, display,
+        observationCount64, successCount64, failureCount64, aggregatedObservationCount64,
+        hasAggregatedIdentities, outcomes
+    };
+}
+class V2ArtifactCursor {
+    constructor(input, offset) {
+        this.input = input;
+        this.offset = offset;
+    }
+    raw(length) {
+        if (!Number.isSafeInteger(length) || length < 0 || this.offset + length > this.input.length) {
+            throw new Error("Load Engine V2 artifact is truncated.");
+        }
+        const value = this.input.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return value;
+    }
+    bytes() {
+        const header = this.raw(4);
+        const length = header.readUInt32BE(0);
+        return this.raw(length);
+    }
+    text() {
+        const bytes = this.bytes();
+        const value = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        requireValidUnicodeScalars(value);
+        return value;
+    }
+    count(field, maximum) {
+        const value = parseCanonicalNonNegativeBigInt(this.text(), field);
+        if (value > BigInt(maximum))
+            throw new Error(`${field} exceeds the supported bound.`);
+        return Number(value);
+    }
+    bit() {
+        const value = this.text();
+        if (value !== "0" && value !== "1")
+            throw new Error("Load Engine V2 artifact bit is invalid.");
+        return value === "1";
+    }
+    requireEnd() {
+        if (this.offset !== this.input.length)
+            throw new Error("Load Engine V2 artifact has trailing bytes.");
+    }
+}
+function compareV2DistributionRecords(left, right) {
+    return compareUtf8V2(left.seriesKind, right.seriesKind)
+        || compareCanonicalV2Integers(left.scenarioIndex64, right.scenarioIndex64)
+        || Buffer.compare(Buffer.from(left.identityKeyHex, "hex"), Buffer.from(right.identityKeyHex, "hex"))
+        || compareUtf8V2(left.outcome, right.outcome)
+        || compareUtf8V2(left.unit, right.unit);
+}
+function compareV2MeasurementSummaries(left, right) {
+    return compareUtf8V2(left.seriesKind, right.seriesKind)
+        || compareCanonicalV2Integers(left.scenarioIndex64, right.scenarioIndex64)
+        || Buffer.compare(Buffer.from(left.identityKeyHex, "hex"), Buffer.from(right.identityKeyHex, "hex"));
+}
+function compareUtf8V2(left, right) {
+    requireValidUnicodeScalars(left);
+    requireValidUnicodeScalars(right);
+    return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
+function compareCanonicalV2Integers(left, right) {
+    const a = parseCanonicalNonNegativeBigInt(left, "canonical integer");
+    const b = parseCanonicalNonNegativeBigInt(right, "canonical integer");
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function validateV2SeriesKind(value) {
+    if (!["scenario", "step", "scheduler-decision-lag", "scheduler-start-lag", "correlation"]
+        .includes(value))
+        throw new Error("Load Engine V2 distribution series kind is invalid.");
+}
+function validateV2Hex(value, field) {
+    if (!/^(?:[0-9a-f]{2})+$/.test(value))
+        throw new Error(`${field} must be non-empty lowercase hexadecimal.`);
+}
+function validateV2BoundedText(value, field, maximumBytes) {
+    requireValidUnicodeScalars(value);
+    if (Buffer.byteLength(value, "utf8") > maximumBytes)
+        throw new Error(`${field} exceeds its UTF-8 bound.`);
+}
+function frameV2Text(value) {
+    requireValidUnicodeScalars(value);
+    return frameV2Bytes(Buffer.from(value, "utf8"));
+}
+function frameV2Bytes(value) {
+    const output = Buffer.allocUnsafe(4 + value.length);
+    output.writeUInt32BE(value.length, 0);
+    value.copy(output, 4);
+    return output;
+}
+function compareBigInt(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isSortedBigInt(values) {
+    return values.every((value, index) => index === 0 || values[index - 1] <= value);
+}
+function parseCanonicalNonNegativeBigInt(value, field) {
+    if (!/^(0|[1-9][0-9]*)$/.test(value))
+        throw new Error(`${field} must be a canonical decimal string.`);
+    const parsed = BigInt(value);
+    if (parsed > 9223372036854775807n)
+        throw new Error(`${field} exceeds signed 64-bit storage.`);
+    return parsed;
+}
+function binary64Bits(value) {
+    if (!Number.isFinite(value))
+        throw new Error("Histogram binary64 state must be finite.");
+    const bytes = Buffer.allocUnsafe(8);
+    bytes.writeDoubleBE(value, 0);
+    return bytes.toString("hex");
+}
+function binary64FromBits(value, field) {
+    if (!/^[0-9a-f]{16}$/.test(value)) {
+        throw new Error(`${field} bits must be 16 lowercase hexadecimal characters.`);
+    }
+    const parsed = Buffer.from(value, "hex").readDoubleBE(0);
+    if (!Number.isFinite(parsed))
+        throw new Error(`${field} must be finite.`);
+    return parsed;
+}
+export function createDefaultLoadEngineV2Settings() {
+    return {
+        contractVersion: 2,
+        maxInFlight: 10000,
+        clusterLoadScope: "Global",
+        statisticsReportingIntervalNs: 1000000000n,
+        maxStatusGroupsPerSeries: 64
+    };
+}
+export function fnv1a32(value) {
+    requireValidUnicodeScalars(value);
+    let hash = 0x811c9dc5;
+    for (const valueByte of new TextEncoder().encode(value)) {
+        hash ^= valueByte;
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}
+export function planFixedDeadlines(rate, intervalNs, durationNs) {
+    validateFixedInputs(rate, intervalNs);
+    if (durationNs <= 0n) {
+        throw new RangeError("durationNs must be positive.");
+    }
+    const count = divideCeiling(durationNs * BigInt(rate), intervalNs);
+    if (count > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new RangeError("The planned ordinal count is too large to materialize.");
+    }
+    return Array.from({ length: Number(count) }, (_, ordinal) => deadline(BigInt(ordinal), intervalNs, rate));
+}
+export function planFixedIterationDeadlines(rate, intervalNs, iterations) {
+    validateFixedInputs(rate, intervalNs);
+    requirePositiveSafeInteger(iterations, "iterations");
+    return Array.from({ length: iterations }, (_, ordinal) => deadline(BigInt(ordinal), intervalNs, rate));
+}
+export function planRampingInjectionDeadlines(rate, intervalNs, durationNs) {
+    validateFixedInputs(rate, intervalNs);
+    validateDuration(durationNs);
+    const count = divideCeiling(BigInt(rate) * durationNs, 2n * intervalNs);
+    if (count > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new RangeError("The planned ordinal count is too large to materialize.");
+    }
+    return Array.from({ length: Number(count) }, (_, ordinal) => integerSquareRoot(2n * BigInt(ordinal) * intervalNs * durationNs / BigInt(rate)));
+}
+export function planRampingConstantDeadlines(copies, durationNs) {
+    requirePositiveSafeInteger(copies, "copies");
+    validateDuration(durationNs);
+    return Array.from({ length: copies }, (_, slot) => BigInt(slot) * durationNs / BigInt(copies));
+}
+export function planRandomInjectionDeadlines(minRate, maxRate, intervalNs, durationNs, seed) {
+    if (!Number.isSafeInteger(minRate) || minRate < 0 || !Number.isSafeInteger(maxRate) || maxRate < minRate) {
+        throw new RangeError("random injection rates must be non-negative integers with minRate <= maxRate.");
+    }
+    requirePositiveSafeInteger(maxRate, "maxRate");
+    if (intervalNs <= 0n) {
+        throw new RangeError("intervalNs must be positive.");
+    }
+    validateDuration(durationNs);
+    let state = (seed >>> 0) || 0x6d2b79f5;
+    const result = [];
+    for (let windowStart = 0n; windowStart < durationNs; windowStart += intervalNs) {
+        state = xorshift32(state);
+        const selectedRate = minRate + state % (maxRate - minRate + 1);
+        for (let ordinal = 0; ordinal < selectedRate; ordinal += 1) {
+            const planned = windowStart + BigInt(ordinal) * intervalNs / BigInt(selectedRate);
+            if (planned < durationNs) {
+                result.push(planned);
+            }
+        }
+    }
+    return result;
+}
+export function xorshift32(input) {
+    let state = (input >>> 0) || 0x6d2b79f5;
+    state = (state ^ (state << 13)) >>> 0;
+    state = (state ^ (state >>> 17)) >>> 0;
+    state = (state ^ (state << 5)) >>> 0;
+    return state >>> 0;
+}
+export function loadEngineV2FixedDeadlineNs(ordinal, rate, intervalNs) {
+    validateFixedInputs(rate, intervalNs);
+    if (ordinal < 0n) {
+        throw new RangeError("ordinal cannot be negative.");
+    }
+    return deadline(ordinal, intervalNs, rate);
+}
+export function loadEngineV2FixedArrivalCount(rate, intervalNs, durationNs) {
+    validateFixedInputs(rate, intervalNs);
+    if (durationNs <= 0n) {
+        throw new RangeError("durationNs must be positive.");
+    }
+    const count = divideCeiling(durationNs * BigInt(rate), intervalNs);
+    if (count > 9223372036854775807n) {
+        throw new RangeError("The planned arrival count exceeds signed 64-bit storage.");
+    }
+    return count;
+}
+export function loadEngineV2LatenessToleranceNs(rate, intervalNs) {
+    validateFixedInputs(rate, intervalNs);
+    const quantum = maximumBigInt(1n, intervalNs / BigInt(rate));
+    return minimumBigInt(100000000n, maximumBigInt(2000000n, quantum * 4n));
+}
+export function classifyLoadEngineV2Arrival(nowNs, deadlineNs, toleranceNs, permitAvailable) {
+    if (nowNs < deadlineNs) {
+        return "wait";
+    }
+    if (toleranceNs < 0n) {
+        throw new RangeError("toleranceNs cannot be negative.");
+    }
+    if (nowNs - deadlineNs > toleranceNs) {
+        return "scheduler_late";
+    }
+    return permitAvailable ? "start" : "max_in_flight";
+}
+function deadline(ordinal, intervalNs, rate) {
+    const value = ordinal * intervalNs / BigInt(rate);
+    if (value > 9223372036854775807n) {
+        throw new RangeError("The canonical deadline exceeds signed 64-bit nanoseconds.");
+    }
+    return value;
+}
+function validateFixedInputs(rate, intervalNs) {
+    requirePositiveSafeInteger(rate, "rate");
+    if (intervalNs <= 0n || intervalNs > 9223372036854775807n) {
+        throw new RangeError("intervalNs must be a positive signed 64-bit value.");
+    }
+}
+function validateDuration(durationNs) {
+    if (durationNs <= 0n || durationNs > 9223372036854775807n) {
+        throw new RangeError("durationNs must be a positive signed 64-bit value.");
+    }
+}
+function integerSquareRoot(value) {
+    if (value < 0n) {
+        throw new RangeError("value cannot be negative.");
+    }
+    if (value < 2n) {
+        return value;
+    }
+    let estimate = 1n << BigInt((value.toString(2).length + 1) >> 1);
+    for (;;) {
+        const next = (estimate + value / estimate) >> 1n;
+        if (next >= estimate) {
+            return estimate;
+        }
+        estimate = next;
+    }
+}
+function requirePositiveSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value > 2147483647) {
+        throw new RangeError(`${name} must be an integer from 1 through 2147483647.`);
+    }
+}
+function requireValidUnicodeScalars(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff)) {
+                throw new TypeError("value contains an unpaired UTF-16 surrogate.");
+            }
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            throw new TypeError("value contains an unpaired UTF-16 surrogate.");
+        }
+    }
+}
+function divideCeiling(dividend, divisor) {
+    return (dividend + divisor - 1n) / divisor;
+}
+function minimumBigInt(left, right) {
+    return left < right ? left : right;
+}
+function maximumBigInt(left, right) {
+    return left > right ? left : right;
+}