@evomap/evolver-core 2.0.0-beta.19 → 2.0.0-beta.22

package/dist/assetstore/unionReadStore.js

@@ -0,0 +1,119 @@
+// Read-union over one writable pool plus any number of read-only ones.
+//
+// Why a provider and not a helper: every evidence consumer already takes an AssetStoreProvider and calls
+// `search`/`list` on it — aggregateLearningHistory, assessGenePublishEvidence, candidateAssembly,
+// probationWouldPromote. Widening what they can see by threading a second store through each of them
+// would fork four call chains and leave the next consumer to remember. Composing at the provider seam
+// instead means they are untouched: whoever builds the store decides how wide the evidence pool is.
+//
+// Writes go to the primary and ONLY the primary. Reads merge, deduplicating by asset_id — records are
+// content-addressed, so the same asset present in two pools is the same asset, and primary wins so a
+// locally-verified record is never shadowed by a foreign copy.
+const DEFAULT_LIMIT = 1000;
+/**
+ * Take from the queues one at a time in source order until `limit` is reached.
+ *
+ * Concatenating instead would let a mature primary fill every slot on its own — at the ~1000-record
+ * limits the real callers pass (candidateAssembly, recall, reviewFilter), a local pool that size returns
+ * ZERO foreign records and the union silently degrades back to the single-store blind spot it exists to
+ * fix. Interleaving also refills: a source that runs out yields its remaining slots to the others, so a
+ * small foreign pool never costs the result its cap.
+ */
+function interleave(queues, limit) {
+    const out = [];
+    for (let cursor = 0; out.length < limit; cursor += 1) {
+        let advanced = false;
+        for (const queue of queues) {
+            const record = queue[cursor];
+            if (record === undefined)
+                continue;
+            advanced = true;
+            out.push(record);
+            if (out.length >= limit)
+                return out;
+        }
+        if (!advanced)
+            return out;
+    }
+    return out;
+}
+export class UnionReadStore {
+    primary;
+    readOnly;
+    // Mirrored as assigned-in-constructor properties rather than plain methods on purpose: the optional
+    // write capabilities are feature-DETECTED by callers (`supportsAtomicConditionalPut`, and
+    // `ingestUnverified`'s `putFrozen` probe). A method declared on the class is always present, so a
+    // union wrapping a primary that lacks the capability would answer "supported" and then throw — the
+    // undeclared-exception failure those probes exist to prevent. Assigning only when the primary has it
+    // keeps the union exactly as capable as the pool it writes to.
+    putConditional;
+    putBundle;
+    putFrozen;
+    putFrozenConditional;
+    // Conditional for the same reason, on the read side: cliContracts.findLogicalAsset and
+    // assetLineage.resolveAsset feature-detect this, and when it is absent fall back to a wide scan that
+    // REPORTS truncation. Answering on behalf of a source that cannot resolve logical ids would strand
+    // those callers on a narrow answer with no truncation signal — a silent "not found" where they would
+    // otherwise have said "lookup is truncated; use an exact asset_id".
+    findByLogicalId;
+    /**
+     * @param primary the writable pool this engine owns; every mutation lands here
+     * @param readOnly additional pools to read, in precedence order after `primary`
+     */
+    constructor(primary, readOnly) {
+        this.primary = primary;
+        this.readOnly = readOnly;
+        if ([primary, ...readOnly].every((source) => source.findByLogicalId)) {
+            this.findByLogicalId = (id, limit = DEFAULT_LIMIT, kind) => this.merged((source) => source.findByLogicalId(id, limit, kind), limit);
+        }
+        const { putBundle, putConditional, putFrozen, putFrozenConditional } = primary;
+        if (putBundle)
+            this.putBundle = (assets) => putBundle.call(primary, assets);
+        if (putConditional)
+            this.putConditional = (asset, options) => putConditional.call(primary, asset, options);
+        if (putFrozen)
+            this.putFrozen = (record) => putFrozen.call(primary, record);
+        if (putFrozenConditional) {
+            this.putFrozenConditional = (record, options) => putFrozenConditional.call(primary, record, options);
+        }
+    }
+    get sources() {
+        return [this.primary, ...this.readOnly];
+    }
+    /**
+     * Merge one read across every source: deduplicate by asset_id with earlier sources winning, then fill
+     * the result by {@link interleave} so every source gets a fair share of the cap.
+     */
+    async merged(read, limit) {
+        const seen = new Set();
+        const queues = [];
+        for (const source of this.sources) {
+            const unique = [];
+            for (const record of await read(source)) {
+                if (seen.has(record.asset_id))
+                    continue;
+                seen.add(record.asset_id);
+                unique.push(record);
+            }
+            queues.push(unique);
+        }
+        return interleave(queues, limit);
+    }
+    async put(asset) {
+        return this.primary.put(asset);
+    }
+    async get(assetId) {
+        for (const source of this.sources) {
+            const found = await source.get(assetId);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    async list(kind, limit = DEFAULT_LIMIT) {
+        return this.merged((source) => source.list(kind, limit), limit);
+    }
+    async search(q) {
+        return this.merged((source) => source.search(q), q.limit ?? DEFAULT_LIMIT);
+    }
+}

package/dist/benchmark/antiGeneBenchmark.d.ts

@@ -70,6 +70,8 @@ export interface AntiGeneBenchmarkOptions {
     minFailureDelta?: number;
     now?: () => number;
     eventsPath?: string;
+    /** Apply the pre-IDF semantic scorer consistently to both A/B arms. */
+    disableSemanticIdf?: boolean;
 }
 export interface AntiGeneBenchmarkDeps {
     store: AssetStoreProvider;

package/dist/benchmark/antiGeneBenchmark.js

@@ -79,7 +79,7 @@ function executeFor(outcome) {
         },
     });
 }
-async function runOneArm(arm, task, source, sourceReview, rootDir, now) {
+async function runOneArm(arm, task, source, sourceReview, rootDir, now, disableSemanticIdf) {
     const armDir = join(rootDir, arm, task.id);
     const store = new LocalJsonlProvider(join(armDir, 'assets'));
     const review = new ReviewLedger(join(armDir, 'assets'), now);
@@ -105,6 +105,7 @@ async function runOneArm(arm, task, source, sourceReview, rootDir, now) {
         execute: executeFor(spec),
         review,
         consumePendingSignals: false,
+        ...(disableSemanticIdf ? { disableSemanticIdf: true } : {}),
     };
     const result = await runEvolutionCycle(engine, store, opts);
     const observed = observedWarningIds(result.decision);
@@ -168,8 +169,8 @@ export async function runAntiGeneBenchmark(suite, deps, options = {}) {
         for (const task of suite.tasks) {
             taskResults.push({
                 taskId: task.id,
-                baseline: await runOneArm('baseline', task, deps.store, sourceReview, rootDir, now),
-                antiGene: await runOneArm('antiGene', task, deps.store, sourceReview, rootDir, now),
+                baseline: await runOneArm('baseline', task, deps.store, sourceReview, rootDir, now, options.disableSemanticIdf === true),
+                antiGene: await runOneArm('antiGene', task, deps.store, sourceReview, rootDir, now, options.disableSemanticIdf === true),
             });
         }
         const report = buildReport(suite, taskResults, minSamples, minFailureDelta);

package/dist/benchmark/antiGeneRollout.d.ts

@@ -75,6 +75,8 @@ export interface AntiGeneRolloutOptions {
     minFailureDelta?: number;
     now?: () => number;
     eventsPath?: string;
+    /** Apply the pre-IDF semantic scorer consistently to both A/B arms. */
+    disableSemanticIdf?: boolean;
 }
 export declare function runAntiGeneRollout(suite: AntiGeneRolloutSuite, deps: AntiGeneRolloutDeps, options?: AntiGeneRolloutOptions): Promise<AntiGeneRolloutReport>;
 export declare function writeAntiGeneRolloutResult(report: AntiGeneRolloutReport, eventsPath: string, now?: () => number): Promise<void>;

package/dist/benchmark/antiGeneRollout.js

@@ -82,7 +82,7 @@ function scoreFromResult(result, status) {
     const score = result.capsule?.outcome?.score;
     return typeof score === 'number' && Number.isFinite(score) ? score : status === 'success' ? 0.9 : 0.2;
 }
-async function runOneArm(arm, task, source, sourceReview, makeExecute, rootDir, now) {
+async function runOneArm(arm, task, source, sourceReview, makeExecute, rootDir, now, disableSemanticIdf) {
     const armDir = join(rootDir, arm, task.id);
     const store = new LocalJsonlProvider(join(armDir, 'assets'));
     const review = new ReviewLedger(join(armDir, 'assets'), now);
@@ -107,6 +107,7 @@ async function runOneArm(arm, task, source, sourceReview, makeExecute, rootDir,
         execute: makeExecute({ arm, task, store, review, armDir }),
         review,
         consumePendingSignals: false,
+        ...(disableSemanticIdf ? { disableSemanticIdf: true } : {}),
     };
     const result = await runEvolutionCycle(engine, store, opts);
     const status = statusFromResult(result);
@@ -183,8 +184,8 @@ export async function runAntiGeneRollout(suite, deps, options = {}) {
         for (const task of suite.tasks) {
             taskResults.push({
                 taskId: task.id,
-                baseline: await runOneArm('baseline', task, deps.store, sourceReview, deps.makeExecute, rootDir, now),
-                antiGene: await runOneArm('antiGene', task, deps.store, sourceReview, deps.makeExecute, rootDir, now),
+                baseline: await runOneArm('baseline', task, deps.store, sourceReview, deps.makeExecute, rootDir, now, options.disableSemanticIdf === true),
+                antiGene: await runOneArm('antiGene', task, deps.store, sourceReview, deps.makeExecute, rootDir, now, options.disableSemanticIdf === true),
             });
         }
         const report = buildReport(suite, taskResults, minSamples, minFailureDelta);

package/dist/benchmark/index.d.ts

@@ -3,4 +3,5 @@ export * from './thesis.js';
 export * from './evolutionThesisSolver.js';
 export * from './antiGeneBenchmark.js';
 export * from './antiGeneRollout.js';
-export * from './triggerShift.js';
+export * from './triggerShift.js';
+export * from './selectionFlatAbstention.js';

package/dist/benchmark/index.js

@@ -3,4 +3,5 @@ export * from './thesis.js';
 export * from './evolutionThesisSolver.js';
 export * from './antiGeneBenchmark.js';
 export * from './antiGeneRollout.js';
-export * from './triggerShift.js';
+export * from './triggerShift.js';
+export * from './selectionFlatAbstention.js';

package/dist/benchmark/selectionFlatAbstention.d.ts

@@ -0,0 +1,152 @@
+import { type GeneDecision, type SelectionInput } from '../algo/geneSelection.js';
+export declare const SELECTION_FLAT_ABSTENTION_BENCHMARK_VERSION = "global-flat-abstention-paired-v1";
+export type SelectionFlatArm = 'current' | 'global-flat-abstain';
+export type SelectionFlatSplit = 'calibration' | 'holdout';
+export type SelectionFlatAction = {
+    kind: 'reuse';
+    geneId: string;
+    assetId?: string;
+} | {
+    kind: 'innovate';
+};
+export interface SelectionFlatComparison {
+    targeted: boolean;
+    targetReason?: 'outside_plateau_flat_positive';
+    currentDecision: GeneDecision;
+    currentAction: SelectionFlatAction;
+    globalFlatAbstainAction: SelectionFlatAction;
+}
+export interface SelectionFlatCohort {
+    id: string;
+    version: string;
+    sourceCommit: string;
+    taskFingerprints: readonly string[];
+    verifier: {
+        id: string;
+        version: string;
+    };
+}
+export type SelectionFlatExpectedRole = 'target' | 'control';
+export interface SelectionFlatExpectation {
+    role: SelectionFlatExpectedRole;
+    currentAction: SelectionFlatAction;
+    globalFlatAbstainAction: SelectionFlatAction;
+}
+export interface SelectionFlatTaskSnapshot<I> {
+    id: string;
+    workspaceSnapshotDigest: string;
+    split: SelectionFlatSplit;
+    stratum: string;
+    /** Verifier input is a private structured-clone-normalized copy (for example, Node Buffer becomes Uint8Array). */
+    payload: I;
+    selection: Omit<SelectionInput, 'selectionGuard'>;
+    expectation: SelectionFlatExpectation;
+}
+export interface SelectionFlatTask<I> extends SelectionFlatTaskSnapshot<I> {
+    taskFingerprint: string;
+}
+export interface SelectionFlatBenchmarkSuite<I> {
+    name: string;
+    cohort: SelectionFlatCohort;
+    tasks: readonly SelectionFlatTask<I>[];
+}
+export interface SelectionFlatVerifierProof {
+    id: string;
+    version: string;
+    proofSha256: string;
+}
+export interface SelectionFlatObjectiveOutcome {
+    passed: boolean;
+    producedValue: boolean;
+    unsafe: boolean;
+    cost: number;
+    verifier: SelectionFlatVerifierProof;
+}
+export interface SelectionFlatVerificationRequest<I> {
+    task: SelectionFlatTask<I>;
+    arm: SelectionFlatArm;
+    action: SelectionFlatAction;
+    isolationKey: string;
+    order: 0 | 1;
+}
+export type SelectionFlatVerifier<I> = (request: SelectionFlatVerificationRequest<I>) => Promise<SelectionFlatObjectiveOutcome> | SelectionFlatObjectiveOutcome;
+export interface SelectionFlatBenchmarkRow {
+    taskFingerprint: string;
+    split: SelectionFlatSplit;
+    stratum: string;
+    armOrder: readonly [SelectionFlatArm, SelectionFlatArm];
+    current: {
+        action: SelectionFlatAction['kind'];
+        outcome: SelectionFlatObjectiveOutcome;
+    };
+    globalFlatAbstain: {
+        action: SelectionFlatAction['kind'];
+        outcome: SelectionFlatObjectiveOutcome;
+    };
+}
+export interface SelectionFlatPairedStats {
+    n: number;
+    currentPasses: number;
+    globalFlatAbstainPasses: number;
+    bothPass: number;
+    bothFail: number;
+    globalOnlyPass: number;
+    currentOnlyPass: number;
+    currentPassRate: number;
+    globalFlatAbstainPassRate: number;
+    pairedRiskDifference: number;
+    ci95Low: number;
+    ci95High: number;
+    mcnemarPValue: number;
+    currentProducedValueRate: number;
+    globalFlatAbstainProducedValueRate: number;
+    currentUnsafeRate: number;
+    globalFlatAbstainUnsafeRate: number;
+    unsafeRateDelta: number;
+    currentAverageCost: number;
+    globalFlatAbstainAverageCost: number;
+    averageCostDelta: number;
+    currentInnovateRate: number;
+    globalFlatAbstainInnovateRate: number;
+}
+export interface SelectionFlatBenchmarkReport {
+    benchmarkVersion: typeof SELECTION_FLAT_ABSTENTION_BENCHMARK_VERSION;
+    statisticalMethods: {
+        mcnemar: 'exact-two-sided-binomial';
+        riskDifferenceCi: 'paired-hoeffding-95';
+    };
+    suite: string;
+    cohort: Omit<SelectionFlatCohort, 'taskFingerprints'> & {
+        registeredTasks: number;
+    };
+    datasetDigest: string;
+    targetTasks: number;
+    controlTasks: number;
+    controlDivergences: 0;
+    rows: SelectionFlatBenchmarkRow[];
+    overall: SelectionFlatPairedStats;
+    calibration: SelectionFlatPairedStats;
+    holdout: SelectionFlatPairedStats;
+    strata: Record<string, SelectionFlatPairedStats>;
+}
+export interface SelectionFlatPassPair {
+    currentPassed: boolean;
+    globalFlatAbstainPassed: boolean;
+}
+/** Compare production with a benchmark-only global flat-positive abstention counterfactual. */
+export declare function compareOutsidePlateauFlatSelection(input: Omit<SelectionInput, 'selectionGuard'>): SelectionFlatComparison;
+/** Compute the digest that the cohort manifest must pre-register for this exact task snapshot. */
+export declare function computeSelectionFlatTaskFingerprint<I>(task: SelectionFlatTaskSnapshot<I>): string;
+/** Exact two-sided McNemar p-value over the discordant pairs. */
+export declare function exactMcNemarTwoSided(globalOnlyPass: number, currentOnlyPass: number): number;
+/** Distribution-free Hoeffding 95% CI for the mean paired success difference (global minus current). */
+export declare function pairedRiskDifference95(pairs: readonly SelectionFlatPassPair[]): {
+    difference: number;
+    ci95Low: number;
+    ci95High: number;
+};
+/**
+ * Run a pre-registered, full-information paired benchmark. Controls are classification checks only and are never
+ * executed. Target tasks run both arms on separately cloned inputs and caller-owned isolated workspaces.
+ */
+export declare function runSelectionFlatAbstentionBenchmark<I>(suite: SelectionFlatBenchmarkSuite<I>, verifier: SelectionFlatVerifier<I>): Promise<SelectionFlatBenchmarkReport>;