@mindpeeker/negentropy 0.1.0

package/dist/estimators/pipeline.js

@@ -0,0 +1,30 @@
+import { uniformStream } from '../internal/prng.js';
+import { normPpf } from '../internal/special.js';
+import { zScores } from '../stats/zscores.js';
+/**
+ * Trial sums → z-scores + uniform dither over one lattice cell. The dithered
+ * variable is continuous, and its differential entropy equals the discrete
+ * entropy of the lattice variable (in lattice-spacing log units) — which is
+ * what makes Vasicek meaningful on trial data. Under H0 the result is
+ * approximately N(0, 1 + 1/(12·k/4)) with excess kurtosis −2/k + O(1/k²).
+ */
+export function ditheredTrialZ(series, cal, opts = {}) {
+    const zs = zScores(series, cal);
+    const next = uniformStream(opts.seed);
+    for (let i = 0; i < zs.length; i++)
+        zs[i] = zs[i] + (next() - 0.5) / cal.sd;
+    return zs;
+}
+/**
+ * Bytes → exactly standard normal samples under H0: u = (b + U(0,1))/256 is
+ * uniform when bytes are, and Φ⁻¹(u) is then exactly N(0,1). The exact-null
+ * mode — ideal for calibrating estimators and byte-level (non-trial) analysis.
+ */
+export function probitBytes(bytes, opts = {}) {
+    const next = uniformStream(opts.seed);
+    const out = new Float64Array(bytes.length);
+    for (let i = 0; i < bytes.length; i++)
+        out[i] = normPpf((bytes[i] + next()) / 256);
+    return out;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/estimators/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/estimators/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAa7C;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAmB,EACnB,GAAgB,EAChB,OAAsB,EAAE;IAExB,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC/B,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,EAAE,CAAC,CAAC,CAAC,GAAI,EAAE,CAAC,CAAC,CAAY,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,EAAE,CAAA;IACvF,OAAO,EAAE,CAAA;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB,EAAE,OAAsB,EAAE;IACrE,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAE,KAAK,CAAC,CAAC,CAAY,GAAG,IAAI,EAAE,CAAC,GAAG,GAAG,CAAC,CAAA;IAC9F,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/estimators/vasicek.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Vasicek m-spacings differential entropy estimate (nats):
+ * H = (1/n)Σ ln((n/(2m))·(x₍ᵢ₊ₘ₎ − x₍ᵢ₋ₘ₎)) with boundary clamping, matching
+ * scipy's `differential_entropy(method='vasicek')`. Default window
+ * m = ⌊√n + ½⌋. Negatively biased at small n; scale-equivariant:
+ * H(a·x) = H(x) + ln|a|.
+ *
+ * Lattice-valued data (bytes, trial sums) has ties → zero spacings → −∞;
+ * dither it first (see `ditheredTrialZ`/`probitBytes`).
+ */
+export declare function vasicekEntropy(x: ArrayLike<number>, m?: number): number;
+/**
+ * Negentropy against the maximum-entropy Gaussian of equal (population)
+ * variance: J = ½ln(2πeσ̂²) − Ĥ_vasicek(x). Scale-invariant; can dip slightly
+ * negative from estimator bias — not clamped, by honesty.
+ */
+export declare function negentropyVasicek(x: ArrayLike<number>, m?: number): number;
+//# sourceMappingURL=vasicek.d.ts.map

package/dist/estimators/vasicek.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vasicek.d.ts","sourceRoot":"","sources":["../../src/estimators/vasicek.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CA6BvE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAU1E"}

package/dist/estimators/vasicek.js

@@ -0,0 +1,57 @@
+import { NegentropyError } from '../errors.js';
+import { KahanSum } from '../internal/kahan.js';
+/** ½·ln(2πe) — the differential entropy of a unit-variance Gaussian, in nats. */
+const HALF_LN_2PIE = 1.4189385332046727;
+/**
+ * Vasicek m-spacings differential entropy estimate (nats):
+ * H = (1/n)Σ ln((n/(2m))·(x₍ᵢ₊ₘ₎ − x₍ᵢ₋ₘ₎)) with boundary clamping, matching
+ * scipy's `differential_entropy(method='vasicek')`. Default window
+ * m = ⌊√n + ½⌋. Negatively biased at small n; scale-equivariant:
+ * H(a·x) = H(x) + ln|a|.
+ *
+ * Lattice-valued data (bytes, trial sums) has ties → zero spacings → −∞;
+ * dither it first (see `ditheredTrialZ`/`probitBytes`).
+ */
+export function vasicekEntropy(x, m) {
+    const n = x.length;
+    if (n < 4) {
+        throw new NegentropyError('insufficient_data', `vasicekEntropy needs ≥ 4 samples, got ${n}`);
+    }
+    const window = m ?? Math.floor(Math.sqrt(n) + 0.5);
+    if (!Number.isInteger(window) || window < 1 || window >= n / 2) {
+        throw new NegentropyError('invalid_config', `m-spacings window must be an integer in [1, n/2), got ${window} for n=${n}`);
+    }
+    const sorted = Float64Array.from(x);
+    sorted.sort();
+    const acc = new KahanSum();
+    const scale = n / (2 * window);
+    for (let i = 0; i < n; i++) {
+        const lo = sorted[Math.max(0, i - window)];
+        const hi = sorted[Math.min(n - 1, i + window)];
+        const spacing = hi - lo;
+        if (!(spacing > 0)) {
+            throw new NegentropyError('insufficient_data', 'zero m-spacing (tied samples) — lattice-valued input must be dithered first');
+        }
+        acc.add(Math.log(scale * spacing));
+    }
+    return acc.value / n;
+}
+/**
+ * Negentropy against the maximum-entropy Gaussian of equal (population)
+ * variance: J = ½ln(2πeσ̂²) − Ĥ_vasicek(x). Scale-invariant; can dip slightly
+ * negative from estimator bias — not clamped, by honesty.
+ */
+export function negentropyVasicek(x, m) {
+    const h = vasicekEntropy(x, m);
+    const n = x.length;
+    let sum = 0;
+    for (let i = 0; i < n; i++)
+        sum += x[i];
+    const mean = sum / n;
+    let m2 = 0;
+    for (let i = 0; i < n; i++)
+        m2 += (x[i] - mean) ** 2;
+    const variance = m2 / n;
+    return HALF_LN_2PIE + 0.5 * Math.log(variance) - h;
+}
+//# sourceMappingURL=vasicek.js.map

package/dist/estimators/vasicek.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vasicek.js","sourceRoot":"","sources":["../../src/estimators/vasicek.ts"],"names":[],"mappings":"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"}

package/dist/estimators/windowed.d.ts

@@ -0,0 +1,27 @@
+export type WindowedEstimator = 'kurtosis' | 'logcosh' | 'exp' | 'vasicek';
+export interface WindowedNegentropyOptions {
+    /** Samples per window (≥ 8). */
+    windowSize: number;
+    /** Samples between emissions. Default windowSize (non-overlapping). */
+    hopSize?: number;
+    /** Default 'logcosh'. 'vasicek' needs continuous input — dither lattice data first. */
+    estimator?: WindowedEstimator;
+    signal?: AbortSignal;
+}
+export interface WindowedNegentropyPoint {
+    /** Emission counter, from 0. */
+    index: number;
+    /** Input-sample index at which this window starts. */
+    startSample: number;
+    /** The window's negentropy. NaN for a degenerate (constant) window. */
+    j: number;
+}
+/**
+ * Rolling negentropy over a sample stream — the "when did order appear?"
+ * view. Lazy and pull-based; every emission recomputes the batch estimator
+ * on the current window, so streamed values are EXACTLY the batch values on
+ * the corresponding slices. Accepts numbers or byte chunks (bytes enter as
+ * their numeric values — estimators standardize internally).
+ */
+export declare function windowedNegentropy(input: AsyncIterable<number | Uint8Array> | Iterable<number | Uint8Array>, opts: WindowedNegentropyOptions): AsyncGenerator<WindowedNegentropyPoint>;
+//# sourceMappingURL=windowed.d.ts.map

package/dist/estimators/windowed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windowed.d.ts","sourceRoot":"","sources":["../../src/estimators/windowed.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAA;AAE1E,MAAM,WAAW,yBAAyB;IACxC,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uFAAuF;IACvF,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,CAAC,EAAE,MAAM,CAAA;CACV;AAED;;;;;;GAMG;AACH,wBAAuB,kBAAkB,CACvC,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,UAAU,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,UAAU,CAAC,EACzE,IAAI,EAAE,yBAAyB,GAC9B,cAAc,CAAC,uBAAuB,CAAC,CAwDzC"}

package/dist/estimators/windowed.js

@@ -0,0 +1,66 @@
+import { NegentropyError } from '../errors.js';
+import { negentropyExp, negentropyKurtosis, negentropyLogcosh } from './negentropy.js';
+import { negentropyVasicek } from './vasicek.js';
+/**
+ * Rolling negentropy over a sample stream — the "when did order appear?"
+ * view. Lazy and pull-based; every emission recomputes the batch estimator
+ * on the current window, so streamed values are EXACTLY the batch values on
+ * the corresponding slices. Accepts numbers or byte chunks (bytes enter as
+ * their numeric values — estimators standardize internally).
+ */
+export async function* windowedNegentropy(input, opts) {
+    const { windowSize } = opts;
+    if (!Number.isInteger(windowSize) || windowSize < 8) {
+        throw new NegentropyError('invalid_config', `windowSize must be an integer ≥ 8, got ${windowSize}`);
+    }
+    const hop = opts.hopSize ?? windowSize;
+    if (!Number.isInteger(hop) || hop < 1) {
+        throw new NegentropyError('invalid_config', `hopSize must be a positive integer, got ${hop}`);
+    }
+    const estimator = opts.estimator ?? 'logcosh';
+    const estimate = (window) => {
+        switch (estimator) {
+            case 'kurtosis':
+                return negentropyKurtosis(window).j;
+            case 'logcosh':
+                return negentropyLogcosh(window).j;
+            case 'exp':
+                return negentropyExp(window).j;
+            case 'vasicek':
+                return negentropyVasicek(window);
+        }
+    };
+    const ring = new Float64Array(windowSize);
+    let pushed = 0;
+    let nextEmitAt = windowSize;
+    let index = 0;
+    function* push(value) {
+        ring[pushed % windowSize] = value;
+        pushed++;
+        if (pushed >= nextEmitAt) {
+            // unroll the ring into window order (oldest first)
+            const window = new Float64Array(windowSize);
+            const head = pushed % windowSize;
+            for (let i = 0; i < windowSize; i++)
+                window[i] = ring[(head + i) % windowSize];
+            yield { index: index++, startSample: pushed - windowSize, j: estimate(window) };
+            nextEmitAt += hop;
+        }
+    }
+    if (opts.signal?.aborted) {
+        throw new NegentropyError('aborted', 'windowed negentropy aborted before start');
+    }
+    for await (const item of input) {
+        if (opts.signal?.aborted) {
+            throw new NegentropyError('aborted', 'windowed negentropy aborted');
+        }
+        if (typeof item === 'number') {
+            yield* push(item);
+        }
+        else {
+            for (let i = 0; i < item.length; i++)
+                yield* push(item[i]);
+        }
+    }
+}
+//# sourceMappingURL=windowed.js.map

package/dist/estimators/windowed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windowed.js","sourceRoot":"","sources":["../../src/estimators/windowed.ts"],"names":[],"mappings":"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"}

package/dist/experiment/batch.d.ts

@@ -0,0 +1,15 @@
+import type { TrialSeries } from '../types.js';
+import type { RegisteredExperiment } from './registration.js';
+import type { ExperimentConfig, ExperimentResult } from './types.js';
+/**
+ * The pure analysis core: recorded trial series in, ExperimentResult out.
+ * Live sessions delegate here on stop(), so a re-analysis of the archived
+ * series reproduces the live result exactly.
+ */
+export declare function analyzeTrials(series: readonly TrialSeries[], configOrRegistration: ExperimentConfig | RegisteredExperiment): ExperimentResult;
+/** Convenience wrapper: recorded raw bytes per source → trials → analyzeTrials. */
+export declare function analyzeBytes(recordings: ReadonlyArray<{
+    source: string;
+    bytes: Uint8Array;
+}>, configOrRegistration: ExperimentConfig | RegisteredExperiment): ExperimentResult;
+//# sourceMappingURL=batch.d.ts.map

package/dist/experiment/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/experiment/batch.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAA2B,WAAW,EAAE,MAAM,aAAa,CAAA;AAEvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,KAAK,EAIV,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAgFnB;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,oBAAoB,EAAE,gBAAgB,GAAG,oBAAoB,GAC5D,gBAAgB,CAkIlB;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC,EAChE,oBAAoB,EAAE,gBAAgB,GAAG,oBAAoB,GAC5D,gBAAgB,CAIlB"}

package/dist/experiment/batch.js

@@ -0,0 +1,179 @@
+import { NegentropyError } from '../errors.js';
+import { normPpf } from '../internal/special.js';
+import { calibrate, theoreticalCalibration } from '../stats/calibration.js';
+import { cumulativeDeviation } from '../stats/cumdev.js';
+import { devvar, interSourceCorrelation, netvar } from '../stats/network.js';
+import { P_FLOOR } from '../stats/pvalues.js';
+import { trialsFromBytes } from '../stats/trials.js';
+import { stoufferZ, zScores } from '../stats/zscores.js';
+import { compositeZ } from './composite.js';
+function resolveConfig(config) {
+    if ('hash' in config && 'config' in config) {
+        return { config: config.config, registration: config.hash };
+    }
+    return { config: config };
+}
+/**
+ * Normal-equivalent z of a one-sided p, via normPpf(1−p) = −normPpf(p) —
+ * the lower tail keeps full precision where 1−p would round to exactly 1.
+ */
+function pToZ(p) {
+    return -normPpf(Math.min(Math.max(p, P_FLOOR), 1 - 1e-16));
+}
+function resolveWindow(spec, steps, timestamps) {
+    let start;
+    let end;
+    if (spec.start instanceof Date || spec.end instanceof Date) {
+        if (!timestamps) {
+            throw new NegentropyError('invalid_window', `event ${spec.id} uses Date bounds but the trial data has no timestamps`);
+        }
+        const startMs = spec.start instanceof Date ? spec.start.getTime() : Number.NaN;
+        const endMs = spec.end instanceof Date ? spec.end.getTime() : Number.NaN;
+        if (!(spec.start instanceof Date) || !(spec.end instanceof Date)) {
+            throw new NegentropyError('invalid_window', `event ${spec.id} mixes Date and step-index bounds`);
+        }
+        start = timestamps.findIndex((t) => t >= startMs);
+        if (start === -1)
+            start = steps;
+        end = timestamps.findIndex((t) => t >= endMs);
+        if (end === -1)
+            end = steps;
+    }
+    else {
+        start = spec.start;
+        end = spec.end;
+    }
+    if (!Number.isInteger(start) ||
+        !Number.isInteger(end) ||
+        start < 0 ||
+        end > steps ||
+        start >= end) {
+        throw new NegentropyError('invalid_window', `event ${spec.id}: window [${String(spec.start)}, ${String(spec.end)}) resolves to [${start}, ${end}) outside the ${steps} available steps`);
+    }
+    return { start, end };
+}
+function eventStatistic(statistic, zSlices, sources) {
+    switch (statistic) {
+        case 'netvar':
+            return netvar(zSlices, sources);
+        case 'devvar':
+            return devvar(zSlices, sources);
+        case 'correlation':
+            return interSourceCorrelation(zSlices, sources);
+    }
+}
+/**
+ * The pure analysis core: recorded trial series in, ExperimentResult out.
+ * Live sessions delegate here on stop(), so a re-analysis of the archived
+ * series reproduces the live result exactly.
+ */
+export function analyzeTrials(series, configOrRegistration) {
+    const { config, registration } = resolveConfig(configOrRegistration);
+    if (series.length === 0) {
+        throw new NegentropyError('invalid_config', 'analyzeTrials needs at least one series');
+    }
+    const bitsPerTrial = series[0].bitsPerTrial;
+    for (const s of series) {
+        if (s.bitsPerTrial !== bitsPerTrial) {
+            throw new NegentropyError('invalid_config', `mixed bitsPerTrial: ${s.source} has ${s.bitsPerTrial}, ${series[0].source} has ${bitsPerTrial}`);
+        }
+    }
+    const missing = config.missing ?? 'error';
+    // resolve calibration (possibly burning a leading window off each series)
+    const calibrationSpec = config.calibration ?? 'theoretical';
+    let analysisSeries;
+    let calibrations;
+    if (calibrationSpec === 'theoretical') {
+        analysisSeries = [...series];
+        calibrations = series.map((s) => theoreticalCalibration(s.source, bitsPerTrial));
+    }
+    else if (Array.isArray(calibrationSpec)) {
+        analysisSeries = [...series];
+        calibrations = series.map((s) => {
+            const cal = calibrationSpec.find((c) => c.source === s.source);
+            if (!cal) {
+                throw new NegentropyError('calibration_required', `no calibration provided for ${s.source}`, {
+                    source: s.source,
+                });
+            }
+            return cal;
+        });
+    }
+    else {
+        const burn = calibrationSpec.trials;
+        if (!Number.isInteger(burn) || burn < 2) {
+            throw new NegentropyError('invalid_config', `calibration.trials must be an integer ≥ 2, got ${burn}`);
+        }
+        calibrations = [];
+        analysisSeries = series.map((s) => {
+            if (s.sums.length <= burn) {
+                throw new NegentropyError('insufficient_data', `${s.source} has ${s.sums.length} trials — not enough to burn ${burn} for calibration`, { source: s.source });
+            }
+            calibrations.push(calibrate({ source: s.source, bitsPerTrial, sums: s.sums.slice(0, burn) }, { minTrials: burn }));
+            return {
+                source: s.source,
+                bitsPerTrial,
+                sums: s.sums.slice(burn),
+                timestamps: s.timestamps?.slice(burn),
+            };
+        });
+    }
+    // align lengths
+    const lengths = analysisSeries.map((s) => s.sums.length);
+    const steps = Math.min(...lengths);
+    if (missing === 'error' && new Set(lengths).size > 1) {
+        throw new NegentropyError('invalid_config', `series lengths differ (${lengths.join(', ')}) — align them or use missing: 'skip' to truncate to ${steps}`);
+    }
+    const aligned = analysisSeries.map((s) => s.sums.length === steps
+        ? s
+        : {
+            source: s.source,
+            bitsPerTrial,
+            sums: s.sums.slice(0, steps),
+            timestamps: s.timestamps?.slice(0, steps),
+        });
+    const sources = aligned.map((s) => s.source);
+    const zBySource = aligned.map((s, i) => zScores(s, calibrations[i]));
+    const timeline = aligned[0].timestamps;
+    const events = [];
+    for (const spec of config.events ?? []) {
+        const { start, end } = resolveWindow(spec, steps, timeline);
+        const slices = zBySource.map((zs) => zs.slice(start, end));
+        const stat = eventStatistic(spec.statistic, slices, sources);
+        const windowSteps = end - start;
+        const stouffers = new Float64Array(windowSteps);
+        const column = new Float64Array(slices.length);
+        for (let t = 0; t < windowSteps; t++) {
+            for (let i = 0; i < slices.length; i++)
+                column[i] = slices[i][t];
+            stouffers[t] = stoufferZ(column);
+        }
+        events.push({
+            id: spec.id,
+            ...(spec.label !== undefined && { label: spec.label }),
+            statistic: spec.statistic,
+            value: stat.statistic,
+            df: stat.df,
+            pValue: stat.pValue,
+            z: pToZ(stat.pValue),
+            steps: windowSteps,
+            cumulative: cumulativeDeviation(stouffers),
+            sources,
+        });
+    }
+    const composite = events.length > 0 ? compositeZ(events) : { z: Number.NaN, pValue: Number.NaN, events: 0 };
+    return {
+        events,
+        composite,
+        calibration: calibrations,
+        series: aligned,
+        ...(registration !== undefined && { registration }),
+    };
+}
+/** Convenience wrapper: recorded raw bytes per source → trials → analyzeTrials. */
+export function analyzeBytes(recordings, configOrRegistration) {
+    const { config } = resolveConfig(configOrRegistration);
+    const series = recordings.map((r) => trialsFromBytes(r.bytes, r.source, config.trial));
+    return analyzeTrials(series, configOrRegistration);
+}
+//# sourceMappingURL=batch.js.map

package/dist/experiment/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../src/experiment/batch.ts"],"names":[],"mappings":"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"}

package/dist/experiment/composite.d.ts

@@ -0,0 +1,12 @@
+import type { EventResult, ExperimentComposite } from './types.js';
+/**
+ * Stouffer composite across pre-registered events: Z = Σzₑ/√E, one-sided.
+ * Valid when events are independent (disjoint windows). This — not
+ * per-event significance hunting — is the recommended primary statistic for
+ * a multi-event experiment; for individual-event claims at level α over E
+ * events, Bonferroni α/E applies.
+ */
+export declare function compositeZ(events: readonly EventResult[]): ExperimentComposite;
+/** Bonferroni-corrected significance threshold for individual-event claims. */
+export declare function bonferroni(alpha: number, events: number): number;
+//# sourceMappingURL=composite.d.ts.map

package/dist/experiment/composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/experiment/composite.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAElE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,mBAAmB,CAM9E;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQhE"}

package/dist/experiment/composite.js

@@ -0,0 +1,26 @@
+import { NegentropyError } from '../errors.js';
+import { normSf } from '../internal/special.js';
+import { P_FLOOR } from '../stats/pvalues.js';
+import { stoufferZ } from '../stats/zscores.js';
+/**
+ * Stouffer composite across pre-registered events: Z = Σzₑ/√E, one-sided.
+ * Valid when events are independent (disjoint windows). This — not
+ * per-event significance hunting — is the recommended primary statistic for
+ * a multi-event experiment; for individual-event claims at level α over E
+ * events, Bonferroni α/E applies.
+ */
+export function compositeZ(events) {
+    if (events.length === 0) {
+        throw new NegentropyError('insufficient_data', 'composite needs at least one event');
+    }
+    const z = stoufferZ(events.map((event) => event.z));
+    return { z, pValue: Math.max(normSf(z), P_FLOOR), events: events.length };
+}
+/** Bonferroni-corrected significance threshold for individual-event claims. */
+export function bonferroni(alpha, events) {
+    if (!(alpha > 0 && alpha < 1) || !Number.isInteger(events) || events < 1) {
+        throw new NegentropyError('invalid_config', `bad bonferroni inputs: alpha=${alpha}, events=${events}`);
+    }
+    return alpha / events;
+}
+//# sourceMappingURL=composite.js.map

package/dist/experiment/composite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.js","sourceRoot":"","sources":["../../src/experiment/composite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAG/C;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,MAA8B;IACvD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,oCAAoC,CAAC,CAAA;IACtF,CAAC;IACD,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACnD,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAA;AAC3E,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,MAAc;IACtD,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACzE,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,gCAAgC,KAAK,YAAY,MAAM,EAAE,CAC1D,CAAA;IACH,CAAC;IACD,OAAO,KAAK,GAAG,MAAM,CAAA;AACvB,CAAC"}

package/dist/experiment/registration.d.ts

@@ -0,0 +1,20 @@
+import type { ExperimentConfig } from './types.js';
+/**
+ * Canonical JSON: recursively key-sorted, Dates as ISO strings, no
+ * insignificant whitespace — byte-stable across key insertion orders, so the
+ * hash commits to the CONTENT of a registration.
+ */
+export declare function canonicalJson(value: unknown): string;
+export interface RegisteredExperiment {
+    readonly config: ExperimentConfig;
+    /** Hex SHA-256 of the canonical JSON — cite this alongside results. */
+    readonly hash: string;
+}
+/**
+ * Freeze and hash an experiment configuration BEFORE data ingestion. The
+ * returned config is deeply frozen (mutation throws), and passing the
+ * registration to `analyzeTrials`/`analyzeBytes`/`session` embeds its hash
+ * in the result — the paper trail against garden-of-forking-paths analysis.
+ */
+export declare function registerExperiment(config: ExperimentConfig): Promise<RegisteredExperiment>;
+//# sourceMappingURL=registration.d.ts.map

package/dist/experiment/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../../src/experiment/registration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAyBpD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAYD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAKhG"}

package/dist/experiment/registration.js

@@ -0,0 +1,54 @@
+import { NegentropyError } from '../errors.js';
+/**
+ * Canonical JSON: recursively key-sorted, Dates as ISO strings, no
+ * insignificant whitespace — byte-stable across key insertion orders, so the
+ * hash commits to the CONTENT of a registration.
+ */
+export function canonicalJson(value) {
+    if (value === null)
+        return 'null';
+    if (value instanceof Date)
+        return JSON.stringify(value.toISOString());
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return JSON.stringify(value);
+        case 'number':
+            if (!Number.isFinite(value)) {
+                throw new NegentropyError('invalid_config', `non-finite number in registration: ${value}`);
+            }
+            return JSON.stringify(value);
+        case 'object': {
+            if (Array.isArray(value))
+                return `[${value.map((item) => canonicalJson(item)).join(',')}]`;
+            const entries = Object.entries(value)
+                .filter(([, v]) => v !== undefined)
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+            return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+        }
+        default:
+            throw new NegentropyError('invalid_config', `unserializable value in registration: ${typeof value}`);
+    }
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const key of Object.getOwnPropertyNames(value)) {
+            deepFreeze(value[key]);
+        }
+    }
+    return value;
+}
+/**
+ * Freeze and hash an experiment configuration BEFORE data ingestion. The
+ * returned config is deeply frozen (mutation throws), and passing the
+ * registration to `analyzeTrials`/`analyzeBytes`/`session` embeds its hash
+ * in the result — the paper trail against garden-of-forking-paths analysis.
+ */
+export async function registerExperiment(config) {
+    const canonical = canonicalJson(config);
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical));
+    const hash = [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+    return { config: deepFreeze(structuredClone(config)), hash };
+}
+//# sourceMappingURL=registration.js.map

package/dist/experiment/registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.js","sourceRoot":"","sources":["../../src/experiment/registration.ts"],"names":[],"mappings":"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"}

package/dist/experiment/session.d.ts

@@ -0,0 +1,47 @@
+import type { TrialSource } from '../types.js';
+import type { RegisteredExperiment } from './registration.js';
+import type { ExperimentConfig, ExperimentResult } from './types.js';
+export interface SessionOptions extends ExperimentConfig {
+    sources: readonly TrialSource[];
+    signal?: AbortSignal;
+    /** Max wait per lock-step round before 'timeout' (or a skip, under missing:'skip'). Default 30_000. */
+    stepTimeoutMs?: number;
+    /** Clock override for deterministic tests. */
+    now?: () => number;
+    /** Pre-registered config: overrides the inline trial/calibration/events/missing and embeds its hash. */
+    registration?: RegisteredExperiment;
+}
+export interface SessionTick {
+    step: number;
+    at: number;
+    /** Aligned to `sources`; NaN for a source that missed this round. */
+    zBySource: Float64Array;
+    /** Names of the sources that contributed this round. */
+    present: readonly string[];
+    /** Stouffer Z over the present sources. */
+    stouffer: number;
+    /** Running Σ Z² — live dashboard feed. */
+    netvar: number;
+    /** Running Σ (Z² − 1) — the live cumulative-deviation value. */
+    cumdev: number;
+    /** Events whose window contains this step (index windows) or this instant (Date windows). */
+    activeEvents: readonly string[];
+}
+export interface Session extends AsyncIterable<SessionTick> {
+    /**
+     * End the run and analyze everything recorded so far via the batch core —
+     * a later re-analysis of `result.series` reproduces this result exactly.
+     */
+    stop(): ExperimentResult;
+}
+/**
+ * Live experiment over N sources in lock-step rounds: each tick awaits one
+ * trial from every (still-active) source, so z vectors are step-aligned with
+ * bounded memory — one trial per source in flight. Lazy: no source I/O until
+ * the first tick is pulled. A stalled source stalls the round (that is the
+ * honest behavior for netvar, which needs simultaneity); under
+ * missing:'skip' the round proceeds with whoever answered and a source that
+ * ends is dropped from the roster.
+ */
+export declare function session(opts: SessionOptions): Session;
+//# sourceMappingURL=session.d.ts.map

package/dist/experiment/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/experiment/session.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAsB,WAAW,EAAE,MAAM,aAAa,CAAA;AAElE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,KAAK,EAAa,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE/E,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,uGAAuG;IACvG,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,wGAAwG;IACxG,YAAY,CAAC,EAAE,oBAAoB,CAAA;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,qEAAqE;IACrE,SAAS,EAAE,YAAY,CAAA;IACvB,wDAAwD;IACxD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAA;IAChB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAA;IACd,6FAA6F;IAC7F,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAED,MAAM,WAAW,OAAQ,SAAQ,aAAa,CAAC,WAAW,CAAC;IACzD;;;OAGG;IACH,IAAI,IAAI,gBAAgB,CAAA;CACzB;AAYD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAyQrD"}