@saihm/shm 0.0.0-stage → 0.38.1

package/dist/tiers/index.d.ts

@@ -0,0 +1,2 @@
+export { TIER_RANK, validateTierPolicy, tierOf, planTiers, renderTierPlan, type Tier, type TierPolicy, type TierSignals, type TierDecision, type TierState, type PagingAction, type TierPlan, } from "./membership.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tiers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tiers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,MAAM,EACN,SAAS,EACT,cAAc,EACd,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,QAAQ,GACd,MAAM,iBAAiB,CAAC"}

package/dist/tiers/index.js

@@ -0,0 +1,2 @@
+export { TIER_RANK, validateTierPolicy, tierOf, planTiers, renderTierPlan, } from "./membership.js";
+//# sourceMappingURL=index.js.map

package/dist/tiers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tiers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,MAAM,EACN,SAAS,EACT,cAAc,GAQf,MAAM,iBAAiB,CAAC"}

package/dist/tiers/membership.d.ts

@@ -0,0 +1,48 @@
+export type Tier = "hot" | "warm" | "cold";
+export declare const TIER_RANK: Readonly<Record<Tier, number>>;
+export interface TierPolicy {
+    readonly hotMinAccesses: number;
+    readonly hotWindowHours: number;
+    readonly warmWindowHours: number;
+}
+export interface TierSignals {
+    readonly cellId: string;
+    readonly ingestEpoch?: number;
+    readonly salient: boolean;
+    readonly accesses?: {
+        readonly count: number;
+        readonly lastEpoch?: number;
+    };
+}
+export interface TierDecision {
+    readonly cellId: string;
+    readonly tier: Tier;
+    readonly reason: string;
+}
+export interface TierState {
+    readonly hot: ReadonlySet<string>;
+    readonly warm: ReadonlySet<string>;
+}
+export interface PagingAction {
+    readonly cellId: string;
+    readonly from: Tier;
+    readonly to: Tier;
+    readonly reason: string;
+}
+export interface TierPlan {
+    readonly nowEpoch: number;
+    readonly policy: TierPolicy;
+    readonly accessesObserved: boolean;
+    readonly decisions: readonly TierDecision[];
+    readonly byTier: Readonly<Record<Tier, number>>;
+    readonly current: Readonly<Record<Tier, number>>;
+    readonly promotions: readonly PagingAction[];
+    readonly evictions: readonly PagingAction[];
+    readonly unchanged: number;
+    readonly notes: readonly string[];
+}
+export declare function validateTierPolicy(p: TierPolicy): void;
+export declare function tierOf(s: TierSignals, policy: TierPolicy, nowEpoch: number): TierDecision;
+export declare function planTiers(signals: readonly TierSignals[], state: TierState, policy: TierPolicy, nowEpoch: number, accessesObserved: boolean): TierPlan;
+export declare function renderTierPlan(p: TierPlan): string;
+//# sourceMappingURL=membership.d.ts.map

package/dist/tiers/membership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"membership.d.ts","sourceRoot":"","sources":["../../src/tiers/membership.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,IAAI,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3C,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgC,CAAC;AAEtF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAID,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAItD;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAoBzF;AAID,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,GAAG,QAAQ,CA4BtJ;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAalD"}

package/dist/tiers/membership.js

@@ -0,0 +1,85 @@
+export const TIER_RANK = { cold: 0, warm: 1, hot: 2 };
+const finiteNonNeg = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0;
+export function validateTierPolicy(p) {
+    if (!Number.isInteger(p.hotMinAccesses) || p.hotMinAccesses < 0)
+        throw new Error(`tier policy: hotMinAccesses must be a non-negative integer (got ${String(p.hotMinAccesses)})`);
+    if (!finiteNonNeg(p.hotWindowHours))
+        throw new Error(`tier policy: hotWindowHours must be finite and non-negative (got ${String(p.hotWindowHours)})`);
+    if (!finiteNonNeg(p.warmWindowHours))
+        throw new Error(`tier policy: warmWindowHours must be finite and non-negative (got ${String(p.warmWindowHours)})`);
+}
+export function tierOf(s, policy, nowEpoch) {
+    validateTierPolicy(policy);
+    const acc = s.accesses;
+    const sinceAccess = acc?.lastEpoch !== undefined ? nowEpoch - acc.lastEpoch : undefined;
+    const sinceIngest = s.ingestEpoch !== undefined ? nowEpoch - s.ingestEpoch : undefined;
+    if (acc !== undefined && sinceAccess !== undefined && acc.count >= policy.hotMinAccesses && sinceAccess <= policy.hotWindowHours) {
+        return { cellId: s.cellId, tier: "hot", reason: `accessed ${acc.count}× — last ${sinceAccess}h ago (≤ ${policy.hotWindowHours}h)` };
+    }
+    if (s.salient)
+        return { cellId: s.cellId, tier: "warm", reason: "salient: the namespace policy keeps it resident (never cold)" };
+    if (sinceAccess !== undefined && sinceAccess <= policy.warmWindowHours) {
+        return { cellId: s.cellId, tier: "warm", reason: `last accessed ${sinceAccess}h ago (≤ ${policy.warmWindowHours}h)` };
+    }
+    if (sinceIngest !== undefined && sinceIngest <= policy.warmWindowHours) {
+        return { cellId: s.cellId, tier: "warm", reason: `ingested ${sinceIngest}h ago (≤ ${policy.warmWindowHours}h)` };
+    }
+    if (sinceIngest === undefined && sinceAccess === undefined) {
+        return { cellId: s.cellId, tier: "cold", reason: acc === undefined ? "unstamped; access unobserved" : "unstamped; never accessed" };
+    }
+    const latest = Math.min(...[sinceIngest, sinceAccess].filter((x) => x !== undefined));
+    return { cellId: s.cellId, tier: "cold", reason: `last activity ${latest}h ago (> ${policy.warmWindowHours}h)` };
+}
+const currentTierOf = (id, state) => (state.hot.has(id) ? "hot" : state.warm.has(id) ? "warm" : "cold");
+export function planTiers(signals, state, policy, nowEpoch, accessesObserved) {
+    validateTierPolicy(policy);
+    if (!Number.isFinite(nowEpoch))
+        throw new Error(`tier plan: nowEpoch must be finite (got ${String(nowEpoch)})`);
+    if (!accessesObserved) {
+        const carrying = signals.filter((s) => s.accesses !== undefined).length;
+        if (carrying > 0)
+            throw new Error(`tier plan: accessesObserved=false but ${carrying} signal(s) carry accesses — omit accesses when the instrument was absent, or pass accessesObserved=true`);
+    }
+    const decisions = [];
+    const promotions = [];
+    const evictions = [];
+    let unchanged = 0;
+    const byTier = { hot: 0, warm: 0, cold: 0 };
+    const current = { hot: 0, warm: 0, cold: 0 };
+    for (const s of signals) {
+        const d = tierOf(s, policy, nowEpoch);
+        decisions.push(d);
+        byTier[d.tier]++;
+        const from = currentTierOf(s.cellId, state);
+        current[from]++;
+        if (TIER_RANK[d.tier] > TIER_RANK[from])
+            promotions.push({ cellId: s.cellId, from, to: d.tier, reason: d.reason });
+        else if (TIER_RANK[d.tier] < TIER_RANK[from])
+            evictions.push({ cellId: s.cellId, from, to: d.tier, reason: d.reason });
+        else
+            unchanged++;
+    }
+    const notes = [];
+    if (!accessesObserved)
+        notes.push("access frequency unobserved (no compliance trail): no cell can qualify as hot on access; warm follows salience and ingest only");
+    const unstamped = signals.filter((s) => s.ingestEpoch === undefined).length;
+    if (unstamped > 0)
+        notes.push(`${unstamped} cell(s) carry no ingest epoch: recency cannot keep them warm`);
+    return { nowEpoch, policy, accessesObserved, decisions, byTier, current, promotions, evictions, unchanged, notes };
+}
+export function renderTierPlan(p) {
+    const lines = [];
+    lines.push(`TIERS @${p.nowEpoch}h — target hot ${p.byTier.hot} · warm ${p.byTier.warm} · cold ${p.byTier.cold} (current hot ${p.current.hot} · warm ${p.current.warm} · cold ${p.current.cold}) · ${p.promotions.length} promotion(s) · ${p.evictions.length} eviction(s) · ${p.unchanged} unchanged · accesses ${p.accessesObserved ? "observed" : "UNOBSERVED"}`);
+    lines.push(`  policy: hot ≥ ${p.policy.hotMinAccesses} access(es) within ${p.policy.hotWindowHours}h · warm within ${p.policy.warmWindowHours}h`);
+    for (const a of p.promotions)
+        lines.push(`  ↑ ${a.cellId}  ${a.from} → ${a.to}  ${a.reason}`);
+    for (const a of p.evictions)
+        lines.push(`  ↓ ${a.cellId}  ${a.from} → ${a.to}  ${a.reason}`);
+    if (p.notes.length > 0) {
+        lines.push("  notes:");
+        for (const n of p.notes)
+            lines.push(`    ${n}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=membership.js.map

package/dist/tiers/membership.js.map

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

package/dist/tuning/holdout.d.ts

@@ -0,0 +1,54 @@
+export interface HoldoutOptions {
+    readonly seed?: number;
+    readonly heldOutFraction?: number;
+    readonly groupOf?: (caseId: string) => string;
+    readonly stratumOf?: (caseId: string) => string;
+}
+export interface StratumBalance {
+    readonly discovery: number;
+    readonly heldOut: number;
+}
+export interface Holdout<T> {
+    readonly discovery: readonly T[];
+    readonly heldOut: readonly T[];
+    readonly groups: {
+        readonly discovery: number;
+        readonly heldOut: number;
+        readonly straddling: number;
+    };
+    readonly strata: ReadonlyMap<string, StratumBalance>;
+    readonly degenerate: boolean;
+    readonly warnings: readonly string[];
+    readonly disclosure: string;
+}
+export declare function splitHoldout<T>(cases: readonly T[], idOf: (c: T) => string, opts?: HoldoutOptions): Holdout<T>;
+export interface StratumDeviation {
+    readonly stratum: string;
+    readonly population: number;
+    readonly sampled: number;
+    readonly populationShare: number;
+    readonly sampledShare: number;
+    readonly expected: number;
+    readonly z: number | null;
+}
+export interface SampleBias {
+    readonly n: number;
+    readonly population: number;
+    readonly strata: readonly StratumDeviation[];
+    readonly biased: boolean;
+    readonly measurable: boolean;
+    readonly warnings: readonly string[];
+    readonly disclosure: string;
+}
+export declare function sampleBias<T>(sample: readonly T[], population: readonly T[], stratumOf: (c: T) => string, opts?: {
+    readonly zTolerance?: number;
+}): SampleBias;
+export interface SampleResult<T> {
+    readonly cases: readonly T[];
+    readonly bias: SampleBias;
+    readonly disclosure: string;
+}
+export declare function stratifiedSample<T>(population: readonly T[], n: number, stratumOf: (c: T) => string, opts?: {
+    readonly seed?: number;
+}): SampleResult<T>;
+//# sourceMappingURL=holdout.d.ts.map

package/dist/tuning/holdout.d.ts.map

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

package/dist/tuning/holdout.js

@@ -0,0 +1,231 @@
+function rng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+const DEFAULT_SEED = 20260902;
+export function splitHoldout(cases, idOf, opts = {}) {
+    const seed = opts.seed ?? DEFAULT_SEED;
+    const frac = opts.heldOutFraction ?? 0.5;
+    if (!Number.isFinite(frac) || frac <= 0 || frac >= 1) {
+        throw new RangeError(`heldOutFraction must be strictly between 0 and 1, got ${String(opts.heldOutFraction)}`);
+    }
+    const groupOf = opts.groupOf ?? ((id) => id);
+    const stratumOf = opts.stratumOf;
+    const byGroup = new Map();
+    for (const c of cases) {
+        const g = groupOf(idOf(c));
+        let bucket = byGroup.get(g);
+        if (!bucket)
+            byGroup.set(g, (bucket = []));
+        bucket.push(c);
+    }
+    const groupIds = [...byGroup.keys()].sort();
+    const rand = rng(seed);
+    for (let i = groupIds.length - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        [groupIds[i], groupIds[j]] = [groupIds[j], groupIds[i]];
+    }
+    const dominant = (members) => {
+        if (!stratumOf)
+            return "";
+        const counts = new Map();
+        for (const m of members) {
+            const s = stratumOf(idOf(m));
+            counts.set(s, (counts.get(s) ?? 0) + 1);
+        }
+        return [...counts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))[0][0];
+    };
+    const discovery = [];
+    const heldOut = [];
+    let dGroups = 0;
+    let hGroups = 0;
+    const dStrat = new Map();
+    const hStrat = new Map();
+    for (const gid of groupIds) {
+        const members = byGroup.get(gid);
+        const s = dominant(members);
+        const dSeen = dStrat.get(s) ?? 0;
+        const hSeen = hStrat.get(s) ?? 0;
+        const total = dSeen + hSeen;
+        const toHeldOut = total === 0 ? frac >= 0.5 : hSeen < frac * total;
+        if (toHeldOut) {
+            heldOut.push(...members);
+            hGroups++;
+            hStrat.set(s, hSeen + members.length);
+        }
+        else {
+            discovery.push(...members);
+            dGroups++;
+            dStrat.set(s, dSeen + members.length);
+        }
+    }
+    const dIds = new Set(discovery.map((c) => groupOf(idOf(c))));
+    const hIds = new Set(heldOut.map((c) => groupOf(idOf(c))));
+    let straddling = 0;
+    for (const g of dIds)
+        if (hIds.has(g))
+            straddling++;
+    if (straddling > 0) {
+        throw new Error(`splitHoldout: ${straddling} group(s) straddle both sides, so the held-out half is not held ` +
+            `out. This is a bug in the splitter, not a condition a caller can accept.`);
+    }
+    if (discovery.length + heldOut.length !== cases.length) {
+        throw new Error(`splitHoldout: ${discovery.length} + ${heldOut.length} != ${cases.length} cases; the split ` +
+            `lost or duplicated cases.`);
+    }
+    const strata = new Map();
+    if (stratumOf) {
+        for (const c of discovery) {
+            const s = stratumOf(idOf(c));
+            const cur = strata.get(s) ?? { discovery: 0, heldOut: 0 };
+            strata.set(s, { discovery: cur.discovery + 1, heldOut: cur.heldOut });
+        }
+        for (const c of heldOut) {
+            const s = stratumOf(idOf(c));
+            const cur = strata.get(s) ?? { discovery: 0, heldOut: 0 };
+            strata.set(s, { discovery: cur.discovery, heldOut: cur.heldOut + 1 });
+        }
+    }
+    const warnings = [];
+    if (heldOut.length === 0)
+        warnings.push("held-out side is EMPTY — nothing can be reported from it");
+    if (discovery.length === 0)
+        warnings.push("discovery side is EMPTY — nothing can be tuned on it");
+    if (byGroup.size < 2)
+        warnings.push(`only ${byGroup.size} group(s) — a group-atomic split cannot divide them`);
+    for (const [s, b] of strata) {
+        if (b.discovery === 0 || b.heldOut === 0) {
+            warnings.push(`stratum "${s}" appears on ONE side only (${b.discovery}/${b.heldOut}) — a per-stratum difference there is an artefact of the split`);
+        }
+    }
+    const grouped = opts.groupOf ? `grouped by caller-supplied key` : `UNGROUPED (each case its own group — no leakage protection)`;
+    const disclosure = `holdout: seed=${seed} frac=${frac} · ${discovery.length} discovery / ${heldOut.length} held-out cases ` +
+        `· ${dGroups}/${hGroups} groups · ${grouped}` +
+        (stratumOf ? ` · stratified best-effort on ${strata.size} strata` : ``);
+    return {
+        discovery,
+        heldOut,
+        groups: { discovery: dGroups, heldOut: hGroups, straddling },
+        strata,
+        degenerate: warnings.length > 0,
+        warnings,
+        disclosure,
+    };
+}
+const MIN_COUNT_FOR_Z = 5;
+const DEFAULT_Z_TOLERANCE = 3;
+export function sampleBias(sample, population, stratumOf, opts = {}) {
+    const tol = opts.zTolerance ?? DEFAULT_Z_TOLERANCE;
+    if (!Number.isFinite(tol) || tol <= 0) {
+        throw new RangeError(`zTolerance must be a positive finite number, got ${String(opts.zTolerance)}`);
+    }
+    const N = population.length;
+    const n = sample.length;
+    const popCount = new Map();
+    for (const c of population)
+        popCount.set(stratumOf(c), (popCount.get(stratumOf(c)) ?? 0) + 1);
+    const sampCount = new Map();
+    for (const c of sample)
+        sampCount.set(stratumOf(c), (sampCount.get(stratumOf(c)) ?? 0) + 1);
+    const warnings = [];
+    for (const s of sampCount.keys()) {
+        if (!popCount.has(s))
+            warnings.push(`stratum "${s}" is in the sample but NOT in the population — the sample is not a subset of what it is being judged against`);
+    }
+    const strata = [...popCount.keys()].sort().map((s) => {
+        const pop = popCount.get(s);
+        const samp = sampCount.get(s) ?? 0;
+        const p = N === 0 ? 0 : pop / N;
+        const expected = p * n;
+        const sd = Math.sqrt((p * (1 - p)) / Math.max(1, n));
+        const judgeable = Math.max(expected, samp) >= MIN_COUNT_FOR_Z && sd > 0 && n > 0;
+        return {
+            stratum: s,
+            population: pop,
+            sampled: samp,
+            populationShare: p,
+            sampledShare: n === 0 ? 0 : samp / n,
+            expected,
+            z: judgeable ? ((n === 0 ? 0 : samp / n) - p) / sd : null,
+        };
+    });
+    const measurable = popCount.size > 1 && n > 0 && N > 0;
+    const offenders = strata.filter((d) => d.z !== null && Math.abs(d.z) > tol);
+    const biased = measurable && offenders.length > 0;
+    if (!measurable) {
+        warnings.push(popCount.size <= 1
+            ? `only ${popCount.size} distinct stratum — this check CANNOT FAIL here and its verdict is vacuous`
+            : `empty sample or population — nothing to judge`);
+    }
+    for (const d of offenders) {
+        warnings.push(`stratum "${d.stratum}": ${d.sampled}/${n} sampled (${(100 * d.sampledShare).toFixed(1)}%) vs ` +
+            `${d.population}/${N} in population (${(100 * d.populationShare).toFixed(1)}%), expected ~${d.expected.toFixed(1)} — z=${d.z.toFixed(2)}`);
+    }
+    const unjudged = strata.filter((d) => d.z === null);
+    if (unjudged.length > 0) {
+        warnings.push(`${unjudged.length} stratum/strata too rare to judge at n=${n} (expected AND observed both < ${MIN_COUNT_FOR_Z}): ${unjudged.map((d) => d.stratum).join(", ")}`);
+    }
+    const verdict = !measurable ? "VACUOUS" : biased ? "BIASED" : "no deviation beyond tolerance";
+    const disclosure = `sample: n=${n} of ${N} · ${popCount.size} strata · |z|>${tol} ⇒ biased · ${verdict}` +
+        (offenders.length > 0 ? ` (${offenders.length} offending: ${offenders.map((d) => d.stratum).join(", ")})` : ``);
+    return { n, population: N, strata, biased, measurable, warnings, disclosure };
+}
+export function stratifiedSample(population, n, stratumOf, opts = {}) {
+    if (!Number.isInteger(n) || n <= 0)
+        throw new RangeError(`sample size must be a positive integer, got ${String(n)}`);
+    const seed = opts.seed ?? DEFAULT_SEED;
+    if (n >= population.length) {
+        const all = [...population];
+        return {
+            cases: all,
+            bias: sampleBias(all, population, stratumOf),
+            disclosure: `sample: FULL POPULATION (${all.length}) — no sampling performed`,
+        };
+    }
+    const byStratum = new Map();
+    for (const c of population) {
+        const s = stratumOf(c);
+        let b = byStratum.get(s);
+        if (!b)
+            byStratum.set(s, (b = []));
+        b.push(c);
+    }
+    const keys = [...byStratum.keys()].sort();
+    const quota = new Map();
+    const remainder = [];
+    let assigned = 0;
+    for (const s of keys) {
+        const exact = (byStratum.get(s).length / population.length) * n;
+        const base = Math.floor(exact);
+        quota.set(s, base);
+        assigned += base;
+        remainder.push({ s, frac: exact - base });
+    }
+    remainder.sort((a, b) => b.frac - a.frac || (a.s < b.s ? -1 : 1));
+    for (let i = 0; assigned < n; i++, assigned++) {
+        const s = remainder[i % remainder.length].s;
+        quota.set(s, quota.get(s) + 1);
+    }
+    const rand = rng(seed);
+    const cases = [];
+    for (const s of keys) {
+        const members = [...byStratum.get(s)];
+        for (let i = members.length - 1; i > 0; i--) {
+            const j = Math.floor(rand() * (i + 1));
+            [members[i], members[j]] = [members[j], members[i]];
+        }
+        cases.push(...members.slice(0, Math.min(quota.get(s), members.length)));
+    }
+    const bias = sampleBias(cases, population, stratumOf);
+    return {
+        cases,
+        bias,
+        disclosure: `sample: stratified n=${cases.length} of ${population.length} · seed=${seed} · ${keys.length} strata · ${bias.biased ? "STILL BIASED (see warnings)" : "mix tracks population"}`,
+    };
+}
+//# sourceMappingURL=holdout.js.map

package/dist/tuning/holdout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"holdout.js","sourceRoot":"","sources":["../../src/tuning/holdout.ts"],"names":[],"mappings":"AAAA,SAAS,GAAG,CAAC,IAAY;IACvB,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC;IACnB,OAAO,GAAG,EAAE;QACV,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACzC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,UAAU,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC;AAwBD,MAAM,YAAY,GAAG,QAAQ,CAAC;AAE9B,MAAM,UAAU,YAAY,CAC1B,KAAmB,EACnB,IAAsB,EACtB,OAAuB,EAAE;IAEzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,YAAY,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,eAAe,IAAI,GAAG,CAAC;IACzC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,UAAU,CAAC,yDAAyD,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;IAChH,CAAC;IACD,MAAM,OAAO,GAA+B,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAEjC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAe,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC;QAC3C,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAE,EAAE,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,OAAqB,EAAU,EAAE;QACjD,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7B,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC;IAC5F,CAAC,CAAC;IAEF,MAAM,SAAS,GAAQ,EAAE,CAAC;IAC1B,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;QAClC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;QAC5B,MAAM,SAAS,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;QACnE,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;YACzB,OAAO,EAAE,CAAC;YACV,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,SAAS,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;YAC3B,OAAO,EAAE,CAAC;YACV,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,UAAU,EAAE,CAAC;IACpD,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,iBAAiB,UAAU,kEAAkE;YAC3F,0EAA0E,CAC7E,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,iBAAiB,SAAS,CAAC,MAAM,MAAM,OAAO,CAAC,MAAM,OAAO,KAAK,CAAC,MAAM,oBAAoB;YAC1F,2BAA2B,CAC9B,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0B,CAAC;IACjD,IAAI,SAAS,EAAE,CAAC;QACd,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YAC1D,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACxE,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YAC1D,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;IACpG,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAC;IAClG,IAAI,OAAO,CAAC,IAAI,GAAG,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,OAAO,CAAC,IAAI,qDAAqD,CAAC,CAAC;IAC/G,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,CAAC,CAAC,SAAS,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YACzC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,+BAA+B,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,OAAO,gEAAgE,CAAC,CAAC;QACtJ,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC,CAAC,6DAA6D,CAAC;IAChI,MAAM,UAAU,GACd,iBAAiB,IAAI,SAAS,IAAI,MAAM,SAAS,CAAC,MAAM,gBAAgB,OAAO,CAAC,MAAM,kBAAkB;QACxG,KAAK,OAAO,IAAI,OAAO,aAAa,OAAO,EAAE;QAC7C,CAAC,SAAS,CAAC,CAAC,CAAC,gCAAgC,MAAM,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAE1E,OAAO;QACL,SAAS;QACT,OAAO;QACP,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE;QAC5D,MAAM;QACN,UAAU,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC;QAC/B,QAAQ;QACR,UAAU;KACX,CAAC;AACJ,CAAC;AAED,MAAM,eAAe,GAAG,CAAC,CAAC;AAC1B,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAsB9B,MAAM,UAAU,UAAU,CACxB,MAAoB,EACpB,UAAwB,EACxB,SAA2B,EAC3B,OAAyC,EAAE;IAE3C,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,mBAAmB,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,UAAU,CAAC,oDAAoD,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACtG,CAAC;IACD,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;IAC5B,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;IACxB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,UAAU;QAAE,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9F,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAE5F,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;QACjC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,8GAA8G,CAAC,CAAC;IACnK,CAAC;IAED,MAAM,MAAM,GAAuB,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACvE,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QAChC,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACrD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,eAAe,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjF,OAAO;YACL,OAAO,EAAE,CAAC;YACV,UAAU,EAAE,GAAG;YACf,OAAO,EAAE,IAAI;YACb,eAAe,EAAE,CAAC;YAClB,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;YACpC,QAAQ;YACR,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI;SAC1D,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;IAC5E,MAAM,MAAM,GAAG,UAAU,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IAElD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,QAAQ,CAAC,IAAI,CACX,QAAQ,CAAC,IAAI,IAAI,CAAC;YAChB,CAAC,CAAC,QAAQ,QAAQ,CAAC,IAAI,4EAA4E;YACnG,CAAC,CAAC,+CAA+C,CACpD,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CACX,YAAY,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ;YAC7F,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,mBAAmB,CAAC,GAAG,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAC7I,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IACpD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,0CAA0C,CAAC,kCAAkC,eAAe,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjL,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,+BAA+B,CAAC;IAC9F,MAAM,UAAU,GACd,aAAa,CAAC,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,iBAAiB,GAAG,eAAe,OAAO,EAAE;QACrF,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,MAAM,eAAe,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAElH,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAChF,CAAC;AAQD,MAAM,UAAU,gBAAgB,CAC9B,UAAwB,EACxB,CAAS,EACT,SAA2B,EAC3B,OAAmC,EAAE;IAErC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,+CAA+C,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrH,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,YAAY,CAAC;IAEvC,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;QAC5B,OAAO;YACL,KAAK,EAAE,GAAG;YACV,IAAI,EAAE,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,CAAC;YAC5C,UAAU,EAAE,4BAA4B,GAAG,CAAC,MAAM,2BAA2B;SAC9E,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,GAAG,EAAe,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC,CAAC;YAAE,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACnC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACZ,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAE1C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,MAAM,SAAS,GAAkC,EAAE,CAAC;IACpD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACnB,QAAQ,IAAI,IAAI,CAAC;QACjB,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,QAAQ,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,CAAC;QAC9C,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,CAAE,CAAC,CAAC,CAAC;QAC7C,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,KAAK,GAAQ,EAAE,CAAC;IACtB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACvC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAE,EAAE,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC;QACxD,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAE,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IACtD,OAAO;QACL,KAAK;QACL,IAAI;QACJ,UAAU,EAAE,wBAAwB,KAAK,CAAC,MAAM,OAAO,UAAU,CAAC,MAAM,WAAW,IAAI,MAAM,IAAI,CAAC,MAAM,aAAa,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,uBAAuB,EAAE;KAC7L,CAAC;AACJ,CAAC"}

package/dist/tuning/index.d.ts

@@ -0,0 +1,7 @@
+export { sampleBias, splitHoldout, stratifiedSample } from "./holdout.js";
+export type { Holdout, HoldoutOptions, SampleBias, SampleResult, StratumBalance, StratumDeviation, } from "./holdout.js";
+export { pairedCompare } from "./paired.js";
+export type { PairedComparison } from "./paired.js";
+export { composeLeverStack, DEFAULT_RERANK_BODY_WINDOW } from "./lever_stack.js";
+export type { BodyWindowSource, LeverStack, LeverStackDeps } from "./lever_stack.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tuning/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tuning/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC1E,YAAY,EACV,OAAO,EACP,cAAc,EACd,UAAU,EACV,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACjF,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/tuning/index.js

@@ -0,0 +1,4 @@
+export { sampleBias, splitHoldout, stratifiedSample } from "./holdout.js";
+export { pairedCompare } from "./paired.js";
+export { composeLeverStack, DEFAULT_RERANK_BODY_WINDOW } from "./lever_stack.js";
+//# sourceMappingURL=index.js.map

package/dist/tuning/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tuning/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAS1E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/tuning/lever_stack.d.ts

@@ -0,0 +1,27 @@
+import type { RankRetriever } from "../answer/answer_layer.js";
+import { RerankingRankRetriever } from "../rerank/reranking_select.js";
+import type { Reranker } from "../rerank/types.js";
+import { ThreadLifecycleRankRetriever, type StampLookup } from "../retrieval/thread_lifecycle.js";
+import type { LeverProfile } from "../profile/lever_profile.js";
+export declare const DEFAULT_RERANK_BODY_WINDOW = 256;
+export interface BodyWindowSource {
+    fetchByIds(ids: readonly string[]): Promise<readonly {
+        cellId: string;
+        plaintext: string;
+    }[]>;
+}
+export interface LeverStackDeps {
+    readonly base: RankRetriever;
+    readonly labelOf: (cellId: string) => string | undefined;
+    readonly bodies?: BodyWindowSource;
+    readonly reranker?: Reranker;
+    readonly stampOf?: StampLookup;
+    readonly onRerankFallback?: (err: unknown) => void;
+}
+export interface LeverStack {
+    readonly retriever: RankRetriever;
+    readonly rerankRetriever: RerankingRankRetriever | undefined;
+    readonly threadRetriever: ThreadLifecycleRankRetriever | undefined;
+}
+export declare function composeLeverStack(deps: LeverStackDeps, profile: LeverProfile): LeverStack;
+//# sourceMappingURL=lever_stack.d.ts.map

package/dist/tuning/lever_stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lever_stack.d.ts","sourceRoot":"","sources":["../../src/tuning/lever_stack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,sBAAsB,EAAuB,MAAM,+BAA+B,CAAC;AAC5F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,4BAA4B,EAG5B,KAAK,WAAW,EACjB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;CAC/F;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,eAAe,EAAE,4BAA4B,GAAG,SAAS,CAAC;CACpE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,GAAG,UAAU,CAmEzF"}

package/dist/tuning/lever_stack.js

@@ -0,0 +1,76 @@
+import { PseudoRelevanceExpander } from "../retrieval/query_expansion.js";
+import { RerankingRankRetriever } from "../rerank/reranking_select.js";
+import { ThreadLifecycleRankRetriever, assertThreadPoolWithinRerank, } from "../retrieval/thread_lifecycle.js";
+import { SessionClosedError } from "../retrieval/session_closed.js";
+export const DEFAULT_RERANK_BODY_WINDOW = 256;
+export function composeLeverStack(deps, profile) {
+    let retriever = deps.base;
+    if (profile.queryExpansion) {
+        const qe = {};
+        if (profile.queryExpansionN !== undefined)
+            qe.prfN = profile.queryExpansionN;
+        if (profile.queryExpansionM !== undefined)
+            qe.prfM = profile.queryExpansionM;
+        retriever = new PseudoRelevanceExpander(retriever, deps.labelOf, qe);
+    }
+    let rerankRetriever;
+    if (deps.reranker) {
+        const rr = {};
+        if (profile.rerankK !== undefined)
+            rr.rerankK = profile.rerankK;
+        if (deps.onRerankFallback !== undefined)
+            rr.onFallback = deps.onRerankFallback;
+        if (profile.rerankOnBody && !deps.bodies) {
+            throw new Error(`composeLeverStack: rerankOnBody is on but no bodies source was supplied. Degrading to label ` +
+                `rerank here would silently serve a DIFFERENT lever than the one asked for — the same ` +
+                `silent-no-op this module refuses for threadLifecycle. (A body FETCH that fails at query ` +
+                `time still degrades to label rerank on purpose; that is resilience, this is a config error.)`);
+        }
+        if (profile.rerankOnBody && deps.bodies) {
+            const win = Number.isFinite(profile.rerankBodyWindowChars) && profile.rerankBodyWindowChars >= 1
+                ? Math.floor(profile.rerankBodyWindowChars)
+                : DEFAULT_RERANK_BODY_WINDOW;
+            const bodies = deps.bodies;
+            rr.textOf = async (ids) => {
+                const m = new Map();
+                try {
+                    for (const b of await bodies.fetchByIds(ids))
+                        m.set(b.cellId, b.plaintext.slice(0, win));
+                }
+                catch (err) {
+                    if (err instanceof SessionClosedError)
+                        throw err;
+                }
+                return m;
+            };
+        }
+        rerankRetriever = new RerankingRankRetriever(retriever, deps.reranker, deps.labelOf, rr);
+        retriever = rerankRetriever;
+    }
+    let threadRetriever;
+    if (profile.threadLifecycle) {
+        if (!deps.stampOf) {
+            throw new Error(`composeLeverStack: threadLifecycle is on but no stampOf was supplied. Without a stamp source ` +
+                `every cell is unstamped, so the lever would be a silent no-op rather than an error.`);
+        }
+        assertThreadPoolWithinRerank({
+            rerankK: profile.rerankK,
+            threadPoolK: profile.threadPoolK,
+            hasReranker: deps.reranker !== undefined,
+            allowWider: profile.allowThreadPoolWiderThanRerank,
+        });
+        const tc = {};
+        if (profile.threadPoolK !== undefined)
+            tc.poolK = profile.threadPoolK;
+        if (profile.threadMaxGroup !== undefined)
+            tc.maxThreadGroup = profile.threadMaxGroup;
+        if (profile.threadJoin !== undefined)
+            tc.join = profile.threadJoin;
+        if (profile.threadDemote !== undefined)
+            tc.demote = profile.threadDemote;
+        threadRetriever = new ThreadLifecycleRankRetriever(retriever, deps.stampOf, tc);
+        retriever = threadRetriever;
+    }
+    return { retriever, rerankRetriever, threadRetriever };
+}
+//# sourceMappingURL=lever_stack.js.map

package/dist/tuning/lever_stack.js.map

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