@evomap/evolver-core 2.0.0-beta.0

package/dist/benchmark/thesis.js

@@ -0,0 +1,150 @@
+function summarize(arm, samples) {
+    const n = samples.length;
+    if (n === 0)
+        return { arm, n: 0, passes: 0, passRate: 0, avgCost: 0, reuseRate: 0 };
+    const passes = samples.filter((s) => s.passed).length;
+    return {
+        arm,
+        n,
+        passes,
+        passRate: passes / n,
+        reuseRate: samples.filter((s) => s.reusedGene).length / n,
+        avgCost: samples.reduce((a, s) => a + s.cost, 0) / n,
+    };
+}
+/** Normal CDF via an Abramowitz-Stegun erf approximation — deterministic, no stats dependency, ample precision
+ *  for a p-value gate (|error| < 1.5e-7). Used for the two-sided p-value of the two-proportion z test. */
+function normalCdf(x) {
+    const t = 1 / (1 + 0.2316419 * Math.abs(x));
+    const d = 0.3989422804014327 * Math.exp((-x * x) / 2);
+    const p = d * t * (0.31938153 + t * (-0.356563782 + t * (1.781477937 + t * (-1.821255978 + t * 1.330274429))));
+    return x >= 0 ? 1 - p : p;
+}
+/** Inverse normal CDF (Acklam's rational approximation) — for the (1 − alpha) CI's critical value, so alpha is
+ *  honoured rather than hard-coding z=1.96. Domain (0,1); deterministic. */
+function normalQuantile(p) {
+    if (p <= 0)
+        return -Infinity;
+    if (p >= 1)
+        return Infinity;
+    const a = [-3.969683028665376e1, 2.209460984245205e2, -2.759285104469687e2, 1.38357751867269e2, -3.066479806614716e1, 2.506628277459239];
+    const b = [-5.447609879822406e1, 1.615858368580409e2, -1.556989798598866e2, 6.680131188771972e1, -1.328068155288572e1];
+    const c = [-7.784894002430293e-3, -3.223964580411365e-1, -2.400758277161838, -2.549732539343734, 4.374664141464968, 2.938163982698783];
+    const d = [7.784695709041462e-3, 3.224671290700398e-1, 2.445134137142996, 3.754408661907416];
+    const pLow = 0.02425;
+    if (p < pLow) {
+        const q = Math.sqrt(-2 * Math.log(p));
+        return (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1);
+    }
+    if (p <= 1 - pLow) {
+        const q = p - 0.5;
+        const r = q * q;
+        return (((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q / (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1);
+    }
+    const q = Math.sqrt(-2 * Math.log(1 - p));
+    return -(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1);
+}
+/** Two-proportion test of (evolver − baseline) pass rates. Significance uses the POOLED-variance z test (the
+ *  standard test of H0: p1 = p2); the reported CI uses the UNPOOLED (Wald) standard error (the standard interval
+ *  for the difference). Zero pooled variance (both arms all-pass or all-fail) → no testable difference. */
+function twoProportionTest(x1, n1, x2, n2, alpha) {
+    const p1 = x1 / n1;
+    const p2 = x2 / n2;
+    const delta = p1 - p2;
+    const pooled = (x1 + x2) / (n1 + n2);
+    const sePooled = Math.sqrt(pooled * (1 - pooled) * (1 / n1 + 1 / n2));
+    const z = sePooled > 0 ? delta / sePooled : 0;
+    const pValue = sePooled > 0 ? 2 * (1 - normalCdf(Math.abs(z))) : 1;
+    const zCrit = normalQuantile(1 - alpha / 2);
+    const seWald = Math.sqrt((p1 * (1 - p1)) / n1 + (p2 * (1 - p2)) / n2);
+    return { z, pValue, significant: pValue <= alpha, ciLow: delta - zCrit * seWald, ciHigh: delta + zCrit * seWald };
+}
+/**
+ * Achieved power + the per-arm sample size needed to call the experiment "powered". Answers what a bare
+ * `no_significant_diff` cannot: was an effect of the minimum interesting size (minDelta) likely to be DETECTED at
+ * this n, or is the null just underpowered? Plans around the OBSERVED baseline rate using the two-proportion
+ * normal approximation; equal-n via the harmonic mean of the two arms (so unequal arms degrade gracefully).
+ */
+function powerAnalysis(baselineRate, minDelta, n1, n2, alpha, targetPower) {
+    const delta = Math.abs(minDelta);
+    if (delta <= 0)
+        return { power: 0, requiredN: Infinity }; // no effect size to power for
+    const p2 = Math.min(1, Math.max(0, baselineRate));
+    const p1 = Math.min(1, Math.max(0, p2 + delta));
+    // EFFECTIVE effect size after clamping to [0,1]: a minDelta lift off a near-ceiling baseline isn't fully
+    // achievable (p1 caps at 1), so the realizable effect is p1 - p2 <= minDelta. Using the raw minDelta here would
+    // overstate power and understate requiredN (Bugbot #286). At the ceiling (p2=1) there is no headroom at all.
+    const effDelta = p1 - p2;
+    if (effDelta <= 0)
+        return { power: 0, requiredN: Infinity };
+    const pbar = (p1 + p2) / 2;
+    const varNull = 2 * pbar * (1 - pbar); // pooled-null variance (numerator uses sqrt of this)
+    const varAlt = p1 * (1 - p1) + p2 * (1 - p2); // alternative variance (the two arms' combined spread)
+    const za = normalQuantile(1 - alpha / 2);
+    const zb = normalQuantile(targetPower);
+    const nEff = n1 > 0 && n2 > 0 ? 2 / (1 / n1 + 1 / n2) : 0;
+    let power = 0;
+    if (nEff > 0) {
+        const seAlt = Math.sqrt(varAlt / nEff);
+        // Perfect separation (both arms at a 0/1 boundary) has zero alt-variance → the effect is detectable with
+        // certainty; otherwise the standard upper-tail power of the two-proportion z test.
+        power = seAlt > 0 ? normalCdf((effDelta - za * Math.sqrt(varNull / nEff)) / seAlt) : 1;
+    }
+    const num = za * Math.sqrt(varNull) + zb * Math.sqrt(varAlt);
+    return { power: Math.min(1, Math.max(0, power)), requiredN: Math.ceil((num * num) / (effDelta * effDelta)) };
+}
+/**
+ * Run both arms over the same task suite and compare. A verdict of evolver_better/worse requires BOTH a practical
+ * delta (|passRateDelta| >= minPassRateDelta) AND statistical significance (two-proportion test p <= alpha);
+ * otherwise no_significant_diff. reuseRate and costDelta are reported, never scored.
+ */
+export async function runThesis(suite, solver, opts = {}) {
+    const minDelta = opts.minPassRateDelta ?? 0.05;
+    const minSamples = opts.minSamples ?? 30;
+    const alpha = opts.alpha ?? 0.05;
+    const targetPower = opts.targetPower ?? 0.8;
+    const baselineSamples = [];
+    const evolverSamples = [];
+    if (opts.interleave) {
+        for (const task of suite.tasks) {
+            baselineSamples.push(await solver(task, 'baseline'));
+            evolverSamples.push(await solver(task, 'evolver'));
+        }
+    }
+    else {
+        for (const task of suite.tasks)
+            baselineSamples.push(await solver(task, 'baseline'));
+        for (const task of suite.tasks)
+            evolverSamples.push(await solver(task, 'evolver'));
+    }
+    const baseline = summarize('baseline', baselineSamples);
+    const evolver = summarize('evolver', evolverSamples);
+    const passRateDelta = evolver.passRate - baseline.passRate;
+    const costDelta = evolver.avgCost - baseline.avgCost;
+    // Power read of the result: with the observed baseline rate and this n, could a minDelta effect have been seen?
+    const { power, requiredN } = powerAnalysis(baseline.passRate, minDelta, baseline.n, evolver.n, alpha, targetPower);
+    // Two-proportion significance test of (evolver − baseline). Guarded against n=0 (only reachable when minSamples
+    // is forced to 0); an empty arm has no testable difference. Otherwise this is the gate that stops a verdict from
+    // riding on sampling noise.
+    const test = baseline.n > 0 && evolver.n > 0
+        ? twoProportionTest(evolver.passes, evolver.n, baseline.passes, baseline.n, alpha)
+        : { z: 0, pValue: 1, significant: false, ciLow: passRateDelta, ciHigh: passRateDelta };
+    // Verdict needs BOTH bars: a practical delta (>= minDelta) AND statistical significance (p <= alpha). A 5pt
+    // delta at n=30 is ~0.4σ — well inside noise — so the practical bar alone could call noise a win; the
+    // significance bar is what makes the headline thesis number defensible.
+    let verdict;
+    if (baseline.n < minSamples || evolver.n < minSamples)
+        verdict = 'insufficient_samples';
+    else if (test.significant && passRateDelta >= minDelta)
+        verdict = 'evolver_better';
+    else if (test.significant && passRateDelta <= -minDelta)
+        verdict = 'evolver_worse';
+    else
+        verdict = 'no_significant_diff';
+    return {
+        suite: suite.name, baseline, evolver, passRateDelta, costDelta,
+        z: test.z, pValue: test.pValue, significant: test.significant, ciLow: test.ciLow, ciHigh: test.ciHigh,
+        power, requiredN,
+        verdict,
+    };
+}

package/dist/bootstrap/envFingerprint.d.ts

@@ -0,0 +1,45 @@
+export interface EnvFingerprint {
+    /** sha256(hostname)[:12] — stable per machine, not reversible. */
+    device: string;
+    node_version: string;
+    platform: string;
+    arch: string;
+    os_release: string;
+    /** EVOLVER_REGION (<=5 chars, lowercased). */
+    region?: string;
+    container: boolean;
+    /**
+     * Underlying LLM model (detectModelName()): explicit EVOLVER_MODEL_NAME, else a host CLI's model env var,
+     * else the literal 'unknown'. Deliberately NOT folded into envFingerprintKey() — a node can swap models
+     * without changing its environment class, so the grouping key stays model-independent; the model travels
+     * as its own field (e.g. so the Hub can index assets by model / feed the by-model leaderboard).
+     */
+    model: string;
+}
+export interface EnvCaptureDeps {
+    platform?: string;
+    arch?: string;
+    nodeVersion?: string;
+    osRelease?: string;
+    hostname?: string;
+    env?: Record<string, string | undefined>;
+    isContainer?: () => boolean;
+}
+/**
+ * Resolve the underlying LLM model name powering this evolver node (ported from v1 PR #174). Until now the
+ * only source was the explicit EVOLVER_MODEL_NAME, so nodes that never set it published assets with no model
+ * at all — the Hub could not tell which model produced a Gene/Capsule, starving the by-model leaderboard and
+ * depriving anti-sybil clustering of a strong signal. We now fall back to the model env vars the common host
+ * CLIs expose. When nothing is discoverable we return the literal 'unknown' rather than null/'' so downstream
+ * aggregation always has a stable, groupable value and can distinguish "ran but model undetectable" from
+ * "field absent (old client)".
+ */
+export declare function detectModelName(env?: Record<string, string | undefined>): string;
+/** Capture the current runtime environment fingerprint. */
+export declare function captureEnvFingerprint(deps?: EnvCaptureDeps): EnvFingerprint;
+/**
+ * Stable "environment class" key for grouping — two nodes with the same key are the same environment class.
+ * Used by epigenetics to bucket a gene's per-environment success/failure (e.g. a gene that only fails on
+ * win32/arm64 is suppressed there, not globally).
+ */
+export declare function envFingerprintKey(fp: EnvFingerprint): string;

package/dist/bootstrap/envFingerprint.js

@@ -0,0 +1,72 @@
+// Environment fingerprint capture (ported from v1 src/gep/envFingerprint.js). Captures the runtime
+// environment (node/platform/arch/os/region/container/model) so an outcome can be attributed to an
+// "environment class" — the prerequisite for epigenetic per-environment gene suppression and for GDI scoring.
+// Privacy: hostname is sha256-truncated, never stored in clear. os/process reads are injectable for tests.
+import { hostname as osHostname, release as osRelease } from 'node:os';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+const sha12 = (s) => createHash('sha256').update(s).digest('hex').slice(0, 12);
+/** Heuristic container detection (Docker / Kubernetes). */
+function detectContainer(env) {
+    if (env['KUBERNETES_SERVICE_HOST'])
+        return true;
+    try {
+        if (existsSync('/.dockerenv'))
+            return true;
+    }
+    catch { /* not on a filesystem with it */ }
+    return false;
+}
+// Env vars that expose the underlying LLM model, in priority order. EVOLVER_MODEL_NAME is the explicit
+// operator override; the rest are what the common host CLIs (Claude Code / Codex / Cursor / generic
+// OpenAI-compatible runners) set. First non-empty wins.
+const MODEL_ENV_VARS = [
+    'EVOLVER_MODEL_NAME',
+    'ANTHROPIC_MODEL',
+    'CLAUDE_MODEL',
+    'CLAUDE_CODE_MODEL',
+    'OPENAI_MODEL',
+    'CODEX_MODEL',
+    'CURSOR_MODEL',
+];
+/**
+ * Resolve the underlying LLM model name powering this evolver node (ported from v1 PR #174). Until now the
+ * only source was the explicit EVOLVER_MODEL_NAME, so nodes that never set it published assets with no model
+ * at all — the Hub could not tell which model produced a Gene/Capsule, starving the by-model leaderboard and
+ * depriving anti-sybil clustering of a strong signal. We now fall back to the model env vars the common host
+ * CLIs expose. When nothing is discoverable we return the literal 'unknown' rather than null/'' so downstream
+ * aggregation always has a stable, groupable value and can distinguish "ran but model undetectable" from
+ * "field absent (old client)".
+ */
+export function detectModelName(env = (typeof process !== 'undefined' ? process.env : {})) {
+    for (const key of MODEL_ENV_VARS) {
+        const v = (env[key] ?? '').trim();
+        if (v)
+            return v.slice(0, 100);
+    }
+    return 'unknown';
+}
+/** Capture the current runtime environment fingerprint. */
+export function captureEnvFingerprint(deps = {}) {
+    const env = deps.env ?? (typeof process !== 'undefined' ? process.env : {});
+    const region = (env['EVOLVER_REGION'] ?? '').trim().toLowerCase().slice(0, 5) || undefined;
+    return {
+        device: sha12(deps.hostname ?? osHostname()),
+        node_version: deps.nodeVersion ?? process.version,
+        platform: deps.platform ?? process.platform,
+        arch: deps.arch ?? process.arch,
+        os_release: deps.osRelease ?? osRelease(),
+        ...(region ? { region } : {}),
+        container: deps.isContainer ? deps.isContainer() : detectContainer(env),
+        model: detectModelName(env),
+    };
+}
+/**
+ * Stable "environment class" key for grouping — two nodes with the same key are the same environment class.
+ * Used by epigenetics to bucket a gene's per-environment success/failure (e.g. a gene that only fails on
+ * win32/arm64 is suppressed there, not globally).
+ */
+export function envFingerprintKey(fp) {
+    const nodeMajor = (fp.node_version || '').replace(/^v/, '').split('.')[0] ?? '';
+    return [fp.platform, fp.arch, `node${nodeMajor}`, fp.region ?? '', fp.device].join('|');
+}

package/dist/bootstrap/index.d.ts

@@ -0,0 +1,2 @@
+export * from './selfEvolve.js';
+export * from './envFingerprint.js';

package/dist/bootstrap/index.js

@@ -0,0 +1,2 @@
+export * from './selfEvolve.js';
+export * from './envFingerprint.js';

package/dist/bootstrap/selfEvolve.d.ts

@@ -0,0 +1,36 @@
+export type RunMode = 'normal' | 'self-evolve';
+/** 自进化预设(seed gene / self-PR 目标 / 硬编码根). 只在 self-evolve 模式加载, 不进默认主流程. */
+export interface EvolvePreset {
+    name: string;
+    seedGenes: readonly string[];
+    selfPrTarget?: {
+        repo: string;
+        branchPrefix: string;
+    };
+    ownedRoots?: readonly string[];
+}
+export interface BootstrapInput {
+    mode: RunMode;
+    preset?: EvolvePreset;
+}
+export interface ResolvedBootstrap {
+    mode: RunMode;
+    isSelfEvolve: boolean;
+    projectAgnostic: boolean;
+    preset: EvolvePreset | null;
+}
+export declare class BootstrapModeError extends Error {
+    constructor(message: string);
+}
+/**
+ * 解析运行模式(M4A-6, 批注#23). 关键不变量:
+ * - **显式**: 模式来自子命令/flag, 不再 isInsideEvolverRepo 自动探测(v1 自举泄漏根因).
+ * - **默认项目无关**: normal 模式拒绝任何 preset/self 目标, 主流程对所有项目一视同仁.
+ * - self-evolve 必须显式带 preset(seed gene / self-PR 目标拆到此).
+ */
+export declare function resolveBootstrap(input: BootstrapInput): ResolvedBootstrap;
+/**
+ * 解析子命令为模式. **不读 cwd / 不探测仓库**(显式优先, 去 v1 隐形约定).
+ * `evolver self-evolve ...` → self-evolve; 其余 → normal.
+ */
+export declare function parseRunMode(argv: readonly string[]): RunMode;

package/dist/bootstrap/selfEvolve.js

@@ -0,0 +1,26 @@
+export class BootstrapModeError extends Error {
+    constructor(message) { super(message); this.name = 'BootstrapModeError'; }
+}
+/**
+ * 解析运行模式(M4A-6, 批注#23). 关键不变量:
+ * - **显式**: 模式来自子命令/flag, 不再 isInsideEvolverRepo 自动探测(v1 自举泄漏根因).
+ * - **默认项目无关**: normal 模式拒绝任何 preset/self 目标, 主流程对所有项目一视同仁.
+ * - self-evolve 必须显式带 preset(seed gene / self-PR 目标拆到此).
+ */
+export function resolveBootstrap(input) {
+    if (input.mode === 'normal') {
+        if (input.preset)
+            throw new BootstrapModeError('normal 模式不得携带 preset(防 EvoMap/self 硬编码泄漏进默认主流程)');
+        return { mode: 'normal', isSelfEvolve: false, projectAgnostic: true, preset: null };
+    }
+    if (!input.preset)
+        throw new BootstrapModeError('self-evolve 模式必须显式提供 preset(seed gene / self-PR 目标)');
+    return { mode: 'self-evolve', isSelfEvolve: true, projectAgnostic: false, preset: input.preset };
+}
+/**
+ * 解析子命令为模式. **不读 cwd / 不探测仓库**(显式优先, 去 v1 隐形约定).
+ * `evolver self-evolve ...` → self-evolve; 其余 → normal.
+ */
+export function parseRunMode(argv) {
+    return argv[0] === 'self-evolve' ? 'self-evolve' : 'normal';
+}

package/dist/cycle/cycleTimeline.d.ts

@@ -0,0 +1,35 @@
+import type { Projector } from '../events/replayer.js';
+import { type CycleStage } from './stateMachine.js';
+import { type CycleFailureClass } from '../algo/cycleFailureClassifier.js';
+export interface CycleRecord {
+    cycleId: string;
+    stage: CycleStage;
+    startedAt: string | null;
+    endedAt: string | null;
+    decisionWhy: string | null;
+    geneId: string | null;
+    mutationId: string | null;
+    capsuleId: string | null;
+    outcome: {
+        status: string;
+        score: number;
+    } | null;
+    failureClass: CycleFailureClass | null;
+    failureSuppressed: boolean;
+    signalCount: number;
+    eventSeqs: number[];
+    illegalTransitions: {
+        from: CycleStage;
+        eventType: string;
+        seq: number;
+    }[];
+}
+export interface CycleTimelineMV {
+    cycles: Record<string, CycleRecord>;
+    order: string[];
+}
+/** cycle timeline MV (军杰§9.3). 每 cycle 一条记录, 状态机校验非法转移. */
+export declare const cycleTimelineProjector: Projector<CycleTimelineMV>;
+export declare function liveCycles(mv: CycleTimelineMV): CycleRecord[];
+export declare function latestCycles(mv: CycleTimelineMV, n?: number): CycleRecord[];
+export declare function historicalCycles(mv: CycleTimelineMV): CycleRecord[];

package/dist/cycle/cycleTimeline.js

@@ -0,0 +1,74 @@
+import { TERMINAL, stageForEventType, canTransition } from './stateMachine.js';
+import { HOST_SUPPRESS_CLASSES } from '../algo/cycleFailureClassifier.js';
+function newRecord(cycleId) {
+    return {
+        cycleId, stage: 'none', startedAt: null, endedAt: null, decisionWhy: null,
+        geneId: null, mutationId: null, capsuleId: null, outcome: null, failureClass: null, failureSuppressed: false,
+        signalCount: 0, eventSeqs: [], illegalTransitions: [],
+    };
+}
+function applyFields(rec, e, to) {
+    const p = (e.payload ?? {});
+    const r = { ...rec, stage: to, eventSeqs: [...rec.eventSeqs, e.seq] };
+    if (to === 'started')
+        r.startedAt = e.ts;
+    if (TERMINAL.has(to))
+        r.endedAt = e.ts;
+    if (to === 'gene_selected') {
+        r.decisionWhy = e.human.why ?? null;
+        r.geneId = p.geneId ?? null;
+    }
+    if (to === 'mutation_built')
+        r.mutationId = p.mutationId ?? null;
+    if (to === 'signals_collected')
+        r.signalCount = p.signalCount ?? rec.signalCount;
+    if (to === 'solidified') {
+        r.capsuleId = p.capsuleId ?? null;
+        r.outcome = p.outcome ?? null;
+    }
+    if (to === 'failed' || to === 'aborted')
+        r.outcome = p.outcome ?? rec.outcome;
+    if (to === 'failed' && typeof p.failure_class === 'string') {
+        const failureClass = p.failure_class;
+        r.failureClass = failureClass;
+        r.failureSuppressed = HOST_SUPPRESS_CLASSES.has(failureClass);
+    }
+    return r;
+}
+/** cycle timeline MV (军杰§9.3). 每 cycle 一条记录, 状态机校验非法转移. */
+export const cycleTimelineProjector = {
+    name: 'cycle_timeline',
+    initial: () => ({ cycles: {}, order: [] }),
+    reduce: (state, e) => {
+        const p = (e.payload ?? {});
+        const cycleId = p.cycleId;
+        if (!cycleId)
+            return state;
+        const exists = cycleId in state.cycles;
+        const rec = state.cycles[cycleId] ?? newRecord(cycleId);
+        const to = stageForEventType(e.type);
+        let next;
+        if (to === null) {
+            next = { ...rec, eventSeqs: [...rec.eventSeqs, e.seq] }; // cycle 内非 stage 事件: 仅记 seq
+        }
+        else if (!canTransition(rec.stage, to)) {
+            next = { ...rec, eventSeqs: [...rec.eventSeqs, e.seq], illegalTransitions: [...rec.illegalTransitions, { from: rec.stage, eventType: e.type, seq: e.seq }] };
+        }
+        else {
+            next = applyFields(rec, e, to);
+        }
+        return {
+            cycles: { ...state.cycles, [cycleId]: next },
+            order: exists ? state.order : [...state.order, cycleId],
+        };
+    },
+};
+export function liveCycles(mv) {
+    return mv.order.map((id) => mv.cycles[id]).filter((c) => !TERMINAL.has(c.stage));
+}
+export function latestCycles(mv, n = 10) {
+    return mv.order.slice(-n).map((id) => mv.cycles[id]);
+}
+export function historicalCycles(mv) {
+    return mv.order.map((id) => mv.cycles[id]);
+}

package/dist/cycle/index.d.ts

@@ -0,0 +1,2 @@
+export * from './stateMachine.js';
+export * from './cycleTimeline.js';

package/dist/cycle/index.js

@@ -0,0 +1,2 @@
+export * from './stateMachine.js';
+export * from './cycleTimeline.js';

package/dist/cycle/stateMachine.d.ts

@@ -0,0 +1,6 @@
+/** cycle 状态机 (军杰§9.3). */
+export type CycleStage = 'none' | 'started' | 'signals_collected' | 'gene_selected' | 'mutation_built' | 'solidified' | 'failed' | 'aborted';
+export declare const TERMINAL: ReadonlySet<CycleStage>;
+/** 事件类型 → 它把 cycle 推进到的 stage (非 stage 事件返回 null). */
+export declare function stageForEventType(type: string): CycleStage | null;
+export declare function canTransition(from: CycleStage, to: CycleStage): boolean;

package/dist/cycle/stateMachine.js

@@ -0,0 +1,25 @@
+export const TERMINAL = new Set(['solidified', 'failed', 'aborted']);
+const ALLOWED = {
+    none: ['started'],
+    started: ['signals_collected', 'gene_selected', 'failed', 'aborted'],
+    signals_collected: ['gene_selected', 'failed', 'aborted'],
+    gene_selected: ['mutation_built', 'solidified', 'failed', 'aborted'],
+    mutation_built: ['solidified', 'failed', 'aborted'],
+    solidified: [], failed: [], aborted: [],
+};
+/** 事件类型 → 它把 cycle 推进到的 stage (非 stage 事件返回 null). */
+export function stageForEventType(type) {
+    switch (type) {
+        case 'cycle.started': return 'started';
+        case 'cycle.signals_collected': return 'signals_collected';
+        case 'decision.gene_selected': return 'gene_selected';
+        case 'mutation.built': return 'mutation_built';
+        case 'cycle.solidified': return 'solidified';
+        case 'cycle.failed': return 'failed';
+        case 'cycle.aborted': return 'aborted';
+        default: return null;
+    }
+}
+export function canTransition(from, to) {
+    return ALLOWED[from].includes(to);
+}

package/dist/daemon/cycleContext.d.ts

@@ -0,0 +1,12 @@
+/** 闸1: cycle-local 状态每轮 reset (D15/军杰附录A). 新 cycle = 新 context, 结束销毁. */
+export declare class CycleContext {
+    readonly cycleId: string;
+    private readonly local;
+    private disposed;
+    constructor(cycleId: string);
+    set<T>(k: string, v: T): void;
+    get<T>(k: string): T | undefined;
+    has(k: string): boolean;
+    dispose(): void;
+    private assertLive;
+}

package/dist/daemon/cycleContext.js

@@ -0,0 +1,13 @@
+/** 闸1: cycle-local 状态每轮 reset (D15/军杰附录A). 新 cycle = 新 context, 结束销毁. */
+export class CycleContext {
+    cycleId;
+    local = new Map();
+    disposed = false;
+    constructor(cycleId) { this.cycleId = cycleId; }
+    set(k, v) { this.assertLive(); this.local.set(k, v); }
+    get(k) { return this.local.get(k); }
+    has(k) { return this.local.has(k); }
+    dispose() { this.local.clear(); this.disposed = true; }
+    assertLive() { if (this.disposed)
+        throw new Error('CycleContext 已销毁: cycle-local 不可跨 cycle'); }
+}

package/dist/daemon/drain.d.ts

@@ -0,0 +1,11 @@
+/** 闸2: drain 升级(禁 hot reload). 停接新 cycle, 排空进行中, 安全退出. */
+export declare class DrainController {
+    private draining;
+    private active;
+    acceptCycle(): boolean;
+    beginCycle(): void;
+    endCycle(): void;
+    drain(pollMs?: number): Promise<void>;
+    get isDraining(): boolean;
+    get activeCount(): number;
+}

package/dist/daemon/drain.js

@@ -0,0 +1,16 @@
+/** 闸2: drain 升级(禁 hot reload). 停接新 cycle, 排空进行中, 安全退出. */
+export class DrainController {
+    draining = false;
+    active = 0;
+    acceptCycle() { return !this.draining; }
+    beginCycle() { if (this.draining)
+        throw new Error('draining: 不接新 cycle'); this.active += 1; }
+    endCycle() { this.active = Math.max(0, this.active - 1); }
+    async drain(pollMs = 5) {
+        this.draining = true;
+        while (this.active > 0)
+            await new Promise((r) => { setTimeout(r, pollMs); });
+    }
+    get isDraining() { return this.draining; }
+    get activeCount() { return this.active; }
+}

package/dist/daemon/guards.d.ts

@@ -0,0 +1,87 @@
+export interface SystemLoad {
+    load1m: number;
+    load5m: number;
+    load15m: number;
+}
+/** Clamp os.loadavg() to at most 2× cores so a misreported sample (Windows zeros, Termux process-counters) can't force a permanent backoff. */
+export declare function clampSystemLoad(loadavg: readonly [number, number, number], cpuCount: number): SystemLoad;
+/** Sensible default load ceiling for N cores (reserve ~10% headroom); floors CPU count so it's never 0. */
+export declare function defaultLoadMax(cpuCount: number): number;
+export interface YieldDecision {
+    yield: boolean;
+    reason: string;
+    ageMs?: number;
+}
+/**
+ * Cooperative `.evolver.lock`: a human (release script, IDE refactor) drops the file to make the daemon yield;
+ * whoever drops it removes it. A lock older than ttlMs is ignored (forgotten lock won't dormant the daemon
+ * forever). A future mtime (clock skew) counts as fresh. Pure — caller supplies presence + mtime.
+ */
+export declare function evaluateUserLock(input: {
+    present: boolean;
+    mtimeMs?: number;
+    now: number;
+    ttlMs: number;
+}): YieldDecision;
+/**
+ * Release-window quiet period: if the last commit is a release bump (chore(release)…), a human is mid-deploy —
+ * yield until the window passes so the daemon doesn't dirty the tree under a publish. windowMs===0 disables.
+ * Pure — caller supplies the last commit subject + unix ts.
+ */
+export declare function evaluateReleaseWindow(input: {
+    lastCommitSubject?: string;
+    lastCommitUnixTs?: number;
+    now: number;
+    windowMs: number;
+}): YieldDecision;
+export interface GuardInput {
+    now: number;
+    lock?: {
+        present: boolean;
+        mtimeMs?: number;
+        ttlMs?: number;
+    };
+    release?: {
+        lastCommitSubject?: string;
+        lastCommitUnixTs?: number;
+        windowMs?: number;
+    };
+    load?: {
+        load1m: number;
+        max?: number;
+        cpuCount?: number;
+    };
+}
+export interface GuardDecision {
+    yield: boolean;
+    reason: string;
+    detail?: Record<string, unknown>;
+}
+/**
+ * Combine the preflight guards in priority order — user lock → release window → system load — and return the
+ * first that says yield. `clear` when none fire. The daemon supplies live readings; this stays pure.
+ */
+export declare function evaluateGuards(input: GuardInput): GuardDecision;
+export interface DormantHypothesis extends Record<string, unknown> {
+    created_at?: string;
+    ttl_ms?: number;
+}
+/**
+ * Persists the daemon's partial state before a backoff so the next cycle resumes the same hypothesis instead of
+ * starting cold. TTL-bounded — a stale dormant state (older than ttlMs) is discarded on read. Atomic write.
+ */
+export declare class DormantHypothesisStore {
+    private readonly path;
+    private readonly opts;
+    constructor(path: string, opts?: {
+        ttlMs?: number;
+        now?: () => number;
+    });
+    private ttl;
+    private now;
+    /** Save partial state before backing off. Never throws. */
+    write(data: Record<string, unknown>): void;
+    /** Recover partial state, or null if absent/expired/corrupt. Expired state is cleared as a side effect. */
+    read(): DormantHypothesis | null;
+    clear(): void;
+}