@evomap/evolver-core 2.0.0-beta.1 → 2.0.0-beta.3

package/dist/assetstore/reviewLedger.js

@@ -8,8 +8,12 @@
 //
 // Default (no record) = approved/eligible: the only writer of quarantine records is `--distill`; cycle-self-
 // produced and v1-migrated genes are never quarantined, so the explore→prove loop is untouched for them.
-import { appendFileSync, existsSync, readFileSync, mkdirSync, statSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { appendUtf8Durable, assertAssetStoreDirectory, ensureAssetStoreDirectory, readUtf8Regular, regularFileFingerprint, withAssetStoreLock, } from './assetStoreStorage.js';
+import { assertTrustSidecarHealthy, parseReviewRecord, parseSidecarJsonl, } from './assetSidecarRecords.js';
+function immutableRecord(record) {
+    return Object.freeze({ ...record });
+}
 /**
  * Append-only JSONL sidecar at <baseDir>/review.jsonl. Default for an asset with NO record = approved (eligible):
  * only auto-distilled drafts are quarantined here; everything else is eligible by default.
@@ -22,11 +26,14 @@ import { join, dirname } from 'node:path';
 export class ReviewLedger {
     now;
     path;
+    lockPath;
     index = new Map();
-    sig = ''; // `${mtimeMs}:${size}` of review.jsonl at the last index build; '' = never loaded / file absent
+    fileState = null;
     constructor(baseDir, now = Date.now) {
         this.now = now;
+        ensureAssetStoreDirectory(baseDir);
         this.path = join(baseDir, 'review.jsonl');
+        this.lockPath = join(baseDir, '.assetstore.lock');
     }
     static isHuman(s) { return s === 'approved' || s === 'rejected'; }
     /** Which record wins for an asset_id: a human decision beats a quarantine; otherwise the later one wins. */
@@ -37,43 +44,50 @@ export class ReviewLedger {
             return r; // human decision always wins (and later human beats earlier)
         return ReviewLedger.isHuman(existing.state) ? existing : r; // a quarantine replaces only a prior quarantine
     }
-    // Reload-aware (not load-once): the resident `autoexec` daemon holds ONE ReviewLedger, yet an operator runs
-    // `evolver review --approve` in a SEPARATE process. Re-read review.jsonl whenever its mtime+size changed, so a
-    // live approval lifts a quarantined gene without restarting the daemon. The file is small and queried at most
-    // once per cycle, so a statSync per query is cheap. (mtime alone can collide within one ms → pair it with size.)
-    load() {
-        if (!existsSync(this.path)) {
-            this.index.clear();
-            this.sig = '';
-            return;
-        }
-        const st = statSync(this.path);
-        const sig = `${st.mtimeMs}:${st.size}`;
-        if (sig === this.sig)
-            return; // unchanged since last read → cached index is current
-        this.index.clear();
-        for (const line of readFileSync(this.path, 'utf8').split('\n')) {
-            if (!line.trim())
-                continue;
-            try {
-                const r = JSON.parse(line);
-                if (r.assetId)
-                    this.index.set(r.assetId, ReviewLedger.keep(this.index.get(r.assetId), r));
+    rebuildIndex(state) {
+        const next = new Map();
+        const raw = state === 'missing' ? null : readUtf8Regular(this.path);
+        if (raw !== null) {
+            const parsed = parseSidecarJsonl(raw, parseReviewRecord);
+            assertTrustSidecarHealthy('review', parsed);
+            for (const record of parsed.records) {
+                const frozen = immutableRecord(record);
+                next.set(record.assetId, ReviewLedger.keep(next.get(record.assetId), frozen));
             }
-            catch { /* skip corrupt line */ }
         }
-        this.sig = sig;
+        this.index.clear();
+        for (const [assetId, record] of next)
+            this.index.set(assetId, record);
+        this.fileState = state;
+    }
+    refreshUnderLock() {
+        const state = regularFileFingerprint(this.path);
+        if (state !== this.fileState)
+            this.rebuildIndex(state);
+    }
+    withFreshRead(read) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            return read(this.index);
+        });
+    }
+    appendUnderLock(full) {
+        appendUtf8Durable(this.path, `${JSON.stringify(full)}\n`);
+        const frozen = immutableRecord(full);
+        this.index.set(full.assetId, ReviewLedger.keep(this.index.get(full.assetId), frozen));
+        this.fileState = regularFileFingerprint(this.path);
+        return this.index.get(full.assetId);
     }
     /** Record a review-state for an asset_id (append-only; the JSONL history is the audit trail). */
     mark(rec) {
-        this.load();
         const full = { ...rec, at: rec.at ?? new Date(this.now()).toISOString() };
-        mkdirSync(dirname(this.path), { recursive: true });
-        appendFileSync(this.path, `${JSON.stringify(full)}\n`);
-        this.index.set(full.assetId, ReviewLedger.keep(this.index.get(full.assetId), full));
-        const st = statSync(this.path); // single stat: two separate calls could straddle a concurrent same-ms append
-        this.sig = `${st.mtimeMs}:${st.size}`; // our own write is already indexed; don't force a re-read
-        return full;
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            this.appendUnderLock(full);
+            return immutableRecord(full);
+        });
     }
     /** Quarantine an auto-distilled draft: its strategy must not enter a real run until reviewed. */
     quarantine(assetId, reason = 'auto-distilled — review before use') {
@@ -87,9 +101,19 @@ export class ReviewLedger {
      * approval is inert. Returns the surviving record (the existing decision, or the new quarantine).
      */
     quarantineIfAbsent(assetId, reason = 'auto-distilled — review before use') {
-        this.load();
-        const existing = this.index.get(assetId);
-        return existing ?? this.quarantine(assetId, reason);
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const existing = this.index.get(assetId);
+            if (existing)
+                return existing;
+            return this.appendUnderLock({
+                assetId,
+                state: 'quarantined',
+                reason,
+                at: new Date(this.now()).toISOString(),
+            });
+        });
     }
     /** Explicit, audited approval (who/why) — flips a draft to eligible. */
     approve(assetId, by, reason) {
@@ -100,8 +124,7 @@ export class ReviewLedger {
         return this.mark({ assetId, state: 'rejected', by, reason });
     }
     get(assetId) {
-        this.load();
-        return this.index.get(assetId) ?? null;
+        return this.withFreshRead((index) => index.get(assetId) ?? null);
     }
     /**
      * Every recorded review decision (resolved, reload-aware). The authoritative source of which assets are
@@ -109,13 +132,25 @@ export class ReviewLedger {
      * asset list, so a draft awaiting approval is never missed behind a store-list cutoff.
      */
     records() {
-        this.load();
-        return [...this.index.values()];
+        return [...this.snapshot().values()];
+    }
+    /** One linearizable review snapshot for bounded batch readers. */
+    snapshot() {
+        return this.withFreshRead((index) => new Map(index));
     }
     /** No record → approved (default eligible); a record → approved only when its state is 'approved'. */
     isApproved(assetId) {
-        this.load();
-        const r = this.index.get(assetId);
-        return r ? r.state === 'approved' : true;
+        return this.withFreshRead((index) => {
+            const r = index.get(assetId);
+            return r ? r.state === 'approved' : true;
+        });
+    }
+    /**
+     * True only when a human approval record exists. Safety-sensitive consumers such as AntiGene warning
+     * injection must fail closed when review state is absent; unlike cycle/migrate-authored Genes, an unreviewed
+     * negative-memory asset must never inherit the ledger's backward-compatible "no record = eligible" default.
+     */
+    isExplicitlyApproved(assetId) {
+        return this.withFreshRead((index) => index.get(assetId)?.state === 'approved');
     }
 }

package/dist/assetstore/seedGenes.d.ts

@@ -0,0 +1,3 @@
+import { type Gene } from '../wire/index.js';
+export declare const BUNDLED_HARNESS_SEED_GENES: readonly Gene[];
+export declare function bundledHarnessSeedGenesJsonl(): string;

package/dist/assetstore/seedGenes.js

@@ -0,0 +1,134 @@
+import { computeAssetId, SCHEMA_VERSION } from '../wire/index.js';
+const HARNESS_SEED_GENE_DRAFTS = [
+    {
+        id: 'gene_seed_publish_feishu_doc',
+        category: 'innovate',
+        signals_match: [
+            'publish_markdown_to_feishu',
+            'create_feishu_doc',
+            'export_report_to_feishu',
+            'publish_results_to_lark_doc',
+            'feishu_doc',
+            'lark_doc',
+        ],
+        preconditions: [
+            'lark-cli is installed and available on PATH.',
+            'lark-cli auth status reports a ready user or bot identity.',
+        ],
+        strategy: [
+            'Run lark-cli doctor and require an ok result before publishing.',
+            'Use the Docs v2 API and avoid deprecated Docs v1 flags.',
+            'Write long Markdown content to a temporary file and pass it as an @file input.',
+            'Create or update the document with the intended user or bot identity, then return the document URL.',
+            'Never overwrite local lark-cli credential files while preparing the document.',
+        ],
+        constraints: { max_files: 2, forbidden_paths: ['.git', 'node_modules', '~/.lark-cli/config.json'] },
+        validation: ['node --version'],
+        summary: 'Publish Markdown content as a Feishu/Lark document through the official CLI, using file-backed content and Docs v2.',
+    },
+    {
+        id: 'gene_seed_conventional_git_commit',
+        category: 'optimize',
+        signals_match: [
+            'git_commit',
+            'create_commit',
+            'commit_changes',
+            'conventional_commit',
+            'stage_and_commit',
+            'write_commit_message',
+        ],
+        preconditions: ['A git repository has staged or unstaged changes that should become one logical commit.'],
+        strategy: [
+            'Inspect git status plus the staged or unstaged diff before choosing a commit shape.',
+            'Pick a Conventional Commits type and optional scope from the actual changed files.',
+            'Stage only the intended logical files and never stage credentials or unrelated changes.',
+            'Write a present-tense imperative subject under 72 characters, with body or footer when needed.',
+            'Do not amend, force-push, hard-reset, or bypass hooks without explicit operator approval.',
+        ],
+        constraints: { max_files: 50, forbidden_paths: ['.git', 'node_modules'] },
+        validation: ['node --version'],
+        summary: 'Create a focused Conventional Commits-style git commit from the real diff while avoiding secrets and unrelated changes.',
+    },
+    {
+        id: 'gene_seed_poll_bugbot_review',
+        category: 'optimize',
+        signals_match: [
+            'poll_bugbot',
+            'bugbot_review',
+            'wait_for_ci_review',
+            'pr_review_gate',
+            'cursor_bugbot',
+            'pr_opened',
+        ],
+        preconditions: ['An open GitHub PR exists and Cursor Bugbot is expected to review it.'],
+        strategy: [
+            'Poll the Cursor Bugbot check by name until it reaches a terminal conclusion or the operator timeout is reached.',
+            'Treat SUCCESS as mergeable only when required checks are green and there are no unresolved Bugbot comments.',
+            'Treat NEUTRAL as not passed; fetch and summarize Cursor Bugbot inline comments for the operator.',
+            'On FAILURE or ACTION_REQUIRED, surface the findings and do not merge automatically.',
+            'Only squash-merge when the operator explicitly asked for merge and the review gate is clean.',
+        ],
+        constraints: { max_files: 1, forbidden_paths: ['.git', 'node_modules'] },
+        validation: ['node --version'],
+        summary: 'Wait for Cursor Bugbot on a GitHub PR and gate merge decisions on the actual check conclusion and comments.',
+    },
+    {
+        id: 'gene_seed_gateway_timeout_recovery',
+        category: 'repair',
+        signals_match: [
+            'gateway_timeout',
+            'upstream_timeout',
+            'http_524',
+            'http_504',
+            'request_timed_out',
+            'retry_on_timeout',
+        ],
+        preconditions: ['A tool call, fetch, subagent request, or long command returned a gateway-class timeout.'],
+        strategy: [
+            'Treat gateway timeout as transient or size-driven until one bounded recovery attempt proves otherwise.',
+            'Retry the exact same operation once, then stop retrying the monolithic call.',
+            'If the retry also times out, split the work by file, directory, endpoint, record, section, or time window.',
+            'Run independent slices in parallel when safe and merge the results.',
+            'Apply the same decomposition recursively only to the slice that still times out.',
+        ],
+        constraints: { max_files: 1, forbidden_paths: ['.git', 'node_modules'] },
+        validation: ['node --version'],
+        summary: 'Recover from gateway or upstream timeouts by retrying once, then decomposing the work instead of looping the same large call.',
+    },
+    {
+        id: 'gene_seed_github_webhook_listener',
+        category: 'innovate',
+        signals_match: [
+            'github_webhook_listener',
+            'bugbot_webhook',
+            'passive_pr_notifications',
+            'notify_when_bugbot_finishes',
+            'webhook_tunnel',
+            'github_pr_inbox',
+        ],
+        preconditions: ['A developer machine can run a local listener and an outbound tunnel for GitHub webhook delivery.'],
+        strategy: [
+            'Use an HMAC-validated local listener for GitHub webhook payloads and deduplicate delivery ids.',
+            'Expose the listener through an outbound-only tunnel rather than an inbound public port.',
+            'Write vetted notifications into a local inbox with restrictive permissions; never execute webhook payloads.',
+            'On session start, re-fetch PR state through GitHub before surfacing any inbox item.',
+            'Rotate webhook secrets periodically and immediately after suspected exposure.',
+        ],
+        constraints: { max_files: 20, forbidden_paths: ['.git', 'node_modules'] },
+        validation: ['node --version'],
+        summary: 'Deploy a local HMAC-validated GitHub webhook listener that turns PR and Bugbot events into safe operator notifications.',
+    },
+];
+function materializeSeedGene(draft) {
+    const gene = {
+        type: 'Gene',
+        schema_version: SCHEMA_VERSION,
+        ...draft,
+        asset_id: '',
+    };
+    return { ...gene, asset_id: computeAssetId(gene) ?? '' };
+}
+export const BUNDLED_HARNESS_SEED_GENES = Object.freeze(HARNESS_SEED_GENE_DRAFTS.map((gene) => Object.freeze(materializeSeedGene(gene))));
+export function bundledHarnessSeedGenesJsonl() {
+    return `${BUNDLED_HARNESS_SEED_GENES.map((gene) => JSON.stringify(gene)).join('\n')}\n`;
+}

package/dist/benchmark/antiGeneBenchmark.d.ts

@@ -2,6 +2,7 @@ import type { AssetStoreProvider } from '../assetstore/provider.js';
 import { ReviewLedger } from '../assetstore/reviewLedger.js';
 import type { ReportEvent } from '../events/reports.js';
 import type { GepCategory } from '../wire/index.js';
+import { type AntiGeneOverblockSummary } from './antiGeneImpact.js';
 export type AntiGeneBenchmarkArm = 'baseline' | 'antiGene';
 export type AntiGeneBenchmarkVerdict = 'anti_gene_better' | 'no_clear_improvement' | 'anti_gene_worse' | 'insufficient_samples';
 export interface AntiGeneBenchmarkOutcomeSpec {
@@ -58,6 +59,7 @@ export interface AntiGeneBenchmarkReport {
     antiGene: AntiGeneBenchmarkArmMetrics;
     missingExpectedWarnings: number;
     overblocked: number;
+    overblockedAntiGenes: AntiGeneOverblockSummary[];
     failureDelta: number;
     verdict: AntiGeneBenchmarkVerdict;
     taskResults: AntiGeneBenchmarkTaskResult[];

package/dist/benchmark/antiGeneBenchmark.js

@@ -8,6 +8,7 @@ import { LineTooLargeError } from '../events/eventStore.js';
 import { CycleEngine } from '../algo/cycleEngine.js';
 import { runEvolutionCycle } from '../algo/orchestrator.js';
 import { makeGeneSelectionPoint } from '../algo/geneSelection.js';
+import { parseOverblockedAntiGenes, summarizeOverblockedAntiGenes } from './antiGeneImpact.js';
 const ALL_ASSETS_LIMIT = Number.MAX_SAFE_INTEGER;
 const ASSET_KINDS = ['Gene', 'Capsule', 'EvolutionEvent', 'AntiGene'];
 function buildProblem(task, now) {
@@ -148,6 +149,7 @@ function buildReport(suite, taskResults, minSamples, minFailureDelta) {
         antiGene,
         missingExpectedWarnings: taskResults.reduce((sum, r) => sum + r.antiGene.missingExpectedWarnings.length, 0),
         overblocked: antiGene.overblocked,
+        overblockedAntiGenes: summarizeOverblockedAntiGenes(taskResults),
         failureDelta: baseline.failureRate - antiGene.failureRate,
         taskResults,
     };
@@ -225,13 +227,21 @@ function isReportPayload(value) {
         && typeof value.tasks === 'number'
         && typeof value.verdict === 'string';
 }
+function normalizeReportPayload(value) {
+    const parsed = parseOverblockedAntiGenes(value.overblockedAntiGenes);
+    const truncated = typeof value.taskResultsTruncated === 'number' && value.taskResultsTruncated > 0;
+    return {
+        ...value,
+        overblockedAntiGenes: parsed ?? (truncated ? [] : summarizeOverblockedAntiGenes(value.taskResults ?? [])),
+    };
+}
 export function antiGeneBenchmarkReportsFromEvents(events) {
     const out = [];
     for (const event of events) {
         if (event.type !== 'anti_gene.benchmark_result')
             continue;
         if (isReportPayload(event.payload))
-            out.push(event.payload);
+            out.push(normalizeReportPayload(event.payload));
     }
     return out;
 }

package/dist/benchmark/antiGeneImpact.d.ts

@@ -0,0 +1,16 @@
+export interface AntiGeneOverblockSummary {
+    antiGeneId: string;
+    count: number;
+    taskIds: string[];
+}
+interface AntiGeneImpactRunResult {
+    overblocked: boolean;
+    observedAntiWarnings: readonly string[];
+}
+interface AntiGeneImpactTaskResult {
+    taskId: string;
+    antiGene: AntiGeneImpactRunResult;
+}
+export declare function summarizeOverblockedAntiGenes(taskResults: readonly AntiGeneImpactTaskResult[]): AntiGeneOverblockSummary[];
+export declare function parseOverblockedAntiGenes(value: unknown): AntiGeneOverblockSummary[] | null;
+export {};

package/dist/benchmark/antiGeneImpact.js

@@ -0,0 +1,34 @@
+export function summarizeOverblockedAntiGenes(taskResults) {
+    const byId = new Map();
+    for (const task of taskResults) {
+        if (!task.antiGene.overblocked)
+            continue;
+        for (const antiGeneId of new Set(task.antiGene.observedAntiWarnings)) {
+            const row = byId.get(antiGeneId) ?? { count: 0, taskIds: new Set() };
+            row.count += 1;
+            row.taskIds.add(task.taskId);
+            byId.set(antiGeneId, row);
+        }
+    }
+    return [...byId.entries()]
+        .map(([antiGeneId, row]) => ({ antiGeneId, count: row.count, taskIds: [...row.taskIds].sort() }))
+        .sort((a, b) => b.count - a.count || a.antiGeneId.localeCompare(b.antiGeneId));
+}
+export function parseOverblockedAntiGenes(value) {
+    if (!Array.isArray(value))
+        return null;
+    const out = [];
+    for (const item of value) {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return null;
+        const row = item;
+        if (typeof row['antiGeneId'] !== 'string')
+            return null;
+        if (typeof row['count'] !== 'number' || !Number.isFinite(row['count']))
+            return null;
+        if (!Array.isArray(row['taskIds']) || !row['taskIds'].every((taskId) => typeof taskId === 'string'))
+            return null;
+        out.push({ antiGeneId: row['antiGeneId'], count: row['count'], taskIds: [...row['taskIds']] });
+    }
+    return out;
+}

package/dist/benchmark/antiGeneRollout.d.ts

@@ -3,6 +3,7 @@ import { ReviewLedger } from '../assetstore/reviewLedger.js';
 import type { ReportEvent } from '../events/reports.js';
 import { type CycleInput } from '../algo/cycleEngine.js';
 import type { GepCategory } from '../wire/index.js';
+import { type AntiGeneOverblockSummary } from './antiGeneImpact.js';
 export type AntiGeneRolloutArm = 'baseline' | 'antiGene';
 export type AntiGeneRolloutVerdict = 'anti_gene_better' | 'no_clear_improvement' | 'anti_gene_worse' | 'insufficient_samples';
 export interface AntiGeneRolloutTask {
@@ -50,6 +51,7 @@ export interface AntiGeneRolloutReport {
     antiGene: AntiGeneRolloutArmMetrics;
     missingExpectedWarnings: number;
     overblocked: number;
+    overblockedAntiGenes: AntiGeneOverblockSummary[];
     failureDelta: number;
     verdict: AntiGeneRolloutVerdict;
     taskResults: AntiGeneRolloutTaskResult[];

package/dist/benchmark/antiGeneRollout.js

@@ -8,6 +8,7 @@ import { LineTooLargeError } from '../events/eventStore.js';
 import { CycleEngine } from '../algo/cycleEngine.js';
 import { runEvolutionCycle } from '../algo/orchestrator.js';
 import { makeGeneSelectionPoint } from '../algo/geneSelection.js';
+import { parseOverblockedAntiGenes, summarizeOverblockedAntiGenes } from './antiGeneImpact.js';
 const ALL_ASSETS_LIMIT = Number.MAX_SAFE_INTEGER;
 const ASSET_KINDS = ['Gene', 'Capsule', 'EvolutionEvent', 'AntiGene'];
 function buildProblem(task, now) {
@@ -163,6 +164,7 @@ function buildReport(suite, rawTaskResults, minSamples, minFailureDelta) {
         antiGene,
         missingExpectedWarnings: taskResults.reduce((sum, r) => sum + r.antiGene.missingExpectedWarnings.length, 0),
         overblocked: antiGene.overblocked,
+        overblockedAntiGenes: summarizeOverblockedAntiGenes(taskResults),
         failureDelta: baseline.failureRate - antiGene.failureRate,
         taskResults,
     };
@@ -240,13 +242,23 @@ function isReportPayload(value) {
         && typeof value.tasks === 'number'
         && typeof value.verdict === 'string';
 }
+function normalizeReportPayload(value) {
+    const parsed = parseOverblockedAntiGenes(value.overblockedAntiGenes);
+    const taskResults = normalizeTaskResults(value.taskResults ?? []);
+    const truncated = typeof value.taskResultsTruncated === 'number' && value.taskResultsTruncated > 0;
+    return {
+        ...value,
+        taskResults,
+        overblockedAntiGenes: parsed ?? (truncated ? [] : summarizeOverblockedAntiGenes(taskResults)),
+    };
+}
 export function antiGeneRolloutReportsFromEvents(events) {
     const out = [];
     for (const event of events) {
         if (event.type !== 'anti_gene.rollout_result')
             continue;
         if (isReportPayload(event.payload))
-            out.push(event.payload);
+            out.push(normalizeReportPayload(event.payload));
     }
     return out;
 }

package/dist/benchmark/index.d.ts

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

package/dist/benchmark/index.js

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

package/dist/benchmark/triggerShift.d.ts

@@ -0,0 +1,62 @@
+export declare const TRIGGER_SHIFT_METHOD_VERSION = "trigger-shift-v1";
+/** @experimental Shift dimension for a semantically paired replay task. */
+export type TriggerShiftAxis = 'wrapper_trigger' | 'temporal_context' | 'instruction_phrasing';
+/** @experimental One replay prompt variant in a trigger-shift pair. */
+export interface TriggerShiftTask {
+    id: string;
+    prompt: string;
+    wrapperTrigger?: string;
+    temporalContext?: string;
+    instructionPhrasing?: string;
+}
+/** @experimental Same objective, paired across one trigger/context shift axis. */
+export interface TriggerShiftPair {
+    id: string;
+    objectiveId: string;
+    axis: TriggerShiftAxis;
+    expectedDecision: string;
+    train: TriggerShiftTask;
+    shifted: TriggerShiftTask;
+}
+/** @experimental Policy output normalized for replay scoring. */
+export interface TriggerShiftDecision {
+    label: string;
+    confidence?: number;
+}
+/** @experimental Replay-only policy seam; callers own any model/tool execution. */
+export interface TriggerShiftPolicy {
+    id: string;
+    predict(task: TriggerShiftTask): TriggerShiftDecision;
+}
+/** @experimental One paired replay result with train/shifted rewards and gap. */
+export interface TriggerShiftPairResult {
+    pairId: string;
+    objectiveId: string;
+    axis: TriggerShiftAxis;
+    trainTaskId: string;
+    shiftedTaskId: string;
+    expectedDecision: string;
+    trainDecision: string;
+    shiftedDecision: string;
+    trainReward: number;
+    shiftedReward: number;
+    gap: number;
+}
+/** @experimental Aggregate replay report; diagnostic only, not a selector input. */
+export interface TriggerShiftReport {
+    methodVersion: string;
+    policyId: string;
+    pairs: number;
+    meanTrainReward: number;
+    meanShiftedReward: number;
+    meanGap: number;
+    maxGap: number;
+    rows: TriggerShiftPairResult[];
+}
+/**
+ * @experimental Offline trigger-shift replay evaluator. It returns inert report
+ * rows only: no trigger fires, no store writes, and no live selection updates.
+ */
+export declare function evaluateTriggerShift(policy: TriggerShiftPolicy, pairs: readonly TriggerShiftPair[]): TriggerShiftReport;
+/** @experimental Tiny public calibration/demo suite; not a live threshold. */
+export declare function smallTriggerShiftSuite(): TriggerShiftPair[];