@evomap/evolver-core 2.0.0-beta.0

package/dist/algo/capabilityCandidates.js

@@ -0,0 +1,131 @@
+// Capability candidate extraction (ported from v1 src/gep/candidates.js). Mines NEW capability proposals
+// from agent behavior — repeated tool calls, active opportunity signals, and clusters of failed evolutions —
+// to feed the innovation step. Candidates are ADVISORY (the agent runtime decides whether to act, exactly
+// as in v1); this is the self-growth path v2 otherwise lacks (v2 only scores EXISTING genes). Pure +
+// deterministic: callers pass already-extracted tool-call names / signals / failed capsules; no time/io here.
+import { expandSignals } from '../signals/expand.js';
+const TOOL_CALL_MIN = 3;
+const FAILURE_CLUSTER_MIN = 2;
+const TITLE_MAX = 120;
+const EVIDENCE_MAX = 240;
+/** Predefined signal → candidate-title map (ported v1): defensive + opportunity signals. */
+const SIGNAL_CANDIDATES = [
+    { signal: 'log_error', title: 'Repair recurring runtime errors' },
+    { signal: 'protocol_drift', title: 'Prevent protocol drift and enforce auditable outputs' },
+    { signal: 'windows_shell_incompatible', title: 'Avoid platform-specific shell assumptions (Windows compatibility)' },
+    { signal: 'session_logs_missing', title: 'Harden session log detection and fallback behavior' },
+    { signal: 'user_feature_request', title: 'Implement user-requested feature' },
+    { signal: 'user_improvement_suggestion', title: 'Apply user improvement suggestion' },
+    { signal: 'perf_bottleneck', title: 'Resolve performance bottleneck' },
+    { signal: 'capability_gap', title: 'Fill capability gap' },
+    { signal: 'stable_success_plateau', title: 'Explore new strategies during stability plateau' },
+    { signal: 'external_opportunity', title: 'Evaluate external A2A asset for local adoption' },
+];
+/** Highest → lowest priority problem class used to pick a failure cluster's grouping key (ported v1). */
+const PROBLEM_PRIORITY = ['problem:performance', 'problem:protocol', 'problem:reliability', 'problem:stagnation', 'problem:capability'];
+/** FNV-1a 32-bit stable hash (ported v1 hash.js) — deterministic candidate ids. */
+function stableHash(input) {
+    let h = 2166136261;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+const clip = (s, n) => (s.length > n ? s.slice(0, n) : s);
+/** Build the fixed five-question shape (ported v1): only title/params/evidence vary per candidate. */
+function buildShape(title, signals, evidence) {
+    const params = `Signals: ${signals.join(', ')}`.trim();
+    return {
+        title: clip(title, TITLE_MAX),
+        input: 'Recent session transcript + memory snippets + user instructions',
+        output: 'A safe, auditable evolution patch guided by GEP assets',
+        invariants: 'Protocol order, small reversible patches, validation, append-only events',
+        params: params || 'Signals: (none)',
+        failure_points: 'Missing signals, over-broad changes, skipped validation, missing knowledge solidification',
+        evidence: clip(evidence, EVIDENCE_MAX),
+    };
+}
+function candidate(source, id, title, signals, evidence, tags) {
+    return { type: 'CapabilityCandidate', id: `cand_${id}`, title, source, signals, tags, shape: buildShape(title, signals, evidence) };
+}
+function failureTitle(tags) {
+    if (tags.includes('problem:performance'))
+        return 'Resolve recurring performance regressions';
+    if (tags.includes('problem:protocol'))
+        return 'Prevent recurring protocol and validation regressions';
+    if (tags.includes('problem:reliability'))
+        return 'Repair recurring reliability failures';
+    if (tags.includes('problem:stagnation'))
+        return 'Break repeated stagnation loops with a new strategy';
+    if (tags.includes('area:orchestration'))
+        return 'Stabilize task and orchestration behavior';
+    return 'Learn from recurring failed evolution paths';
+}
+/**
+ * Mine capability candidates from three sources (ported v1): repeated tool calls (>=3), active opportunity
+ * signals, and clusters of failed capsules (>=2 in the same dominant-problem group). Deduped by stable id.
+ */
+export function extractCapabilityCandidates(inp) {
+    const signals = (inp.signals ?? []).map((s) => String(s));
+    const signalTags = expandSignals(signals);
+    const out = [];
+    // A. Tool-call mining: a tool used >= TOOL_CALL_MIN times suggests a reusable capability.
+    const freq = new Map();
+    for (const t of inp.toolCalls ?? [])
+        freq.set(t, (freq.get(t) ?? 0) + 1);
+    for (const [tool, count] of freq) {
+        if (count < TOOL_CALL_MIN)
+            continue;
+        const title = `Repeated tool usage: ${tool}`;
+        out.push(candidate('transcript', stableHash(title), title, signals, `Observed ${count} occurrences of tool call ${tool}.`, signalTags));
+    }
+    // B. Signal-mapped candidates: predefined defensive/opportunity signals.
+    for (const sc of SIGNAL_CANDIDATES) {
+        if (!signals.some((s) => s === sc.signal || s.startsWith(sc.signal + ':')))
+            continue;
+        out.push(candidate('signals', stableHash(sc.signal), sc.title, signals, `Signal ${sc.signal} active.`, signalTags));
+    }
+    // C. Failure clustering: group failed capsules by dominant problem class.
+    const groups = new Map();
+    for (const fc of inp.failedCapsules ?? []) {
+        if (fc.outcome?.status === 'success')
+            continue;
+        const reason = String(fc.failure_reason ?? '').trim();
+        const failureTags = expandSignals([...(fc.trigger ?? []), ...signals], reason).filter((t) => /^(problem|risk|area|action):/.test(t));
+        if (failureTags.length === 0)
+            continue;
+        let dominant = null;
+        for (const p of PROBLEM_PRIORITY)
+            if (failureTags.includes(p)) {
+                dominant = p;
+                break;
+            }
+        const grouping = dominant ? [dominant] : failureTags.filter((t) => t.startsWith('area:') || t.startsWith('risk:')).slice(0, 1);
+        const key = grouping.join('|');
+        if (!key)
+            continue;
+        const g = groups.get(key) ?? { count: 0, tags: failureTags, reasons: [] };
+        g.count += 1;
+        if (reason)
+            g.reasons.push(reason);
+        groups.set(key, g);
+    }
+    for (const [key, g] of groups) {
+        if (g.count < FAILURE_CLUSTER_MIN)
+            continue;
+        const title = failureTitle(g.tags);
+        const evidence = `${g.count} recurring failures${g.reasons.length ? ` (${g.reasons.slice(0, 2).join('; ')})` : ''}`;
+        out.push(candidate('failed_capsules', stableHash('failed:' + key), title, signals, evidence, g.tags));
+    }
+    // Dedup by stable id (first occurrence wins).
+    const seen = new Set();
+    const deduped = [];
+    for (const c of out) {
+        if (seen.has(c.id))
+            continue;
+        seen.add(c.id);
+        deduped.push(c);
+    }
+    return deduped;
+}

package/dist/algo/confidence.d.ts

@@ -0,0 +1,106 @@
+/** A single per-(fingerprint, gene) outcome observation derived from the event log. */
+export interface ConfidenceObservation {
+    signalFingerprint: string;
+    geneId: string;
+    /**
+     * `inert` (port of v1 #195 `stable_no_error`): the cycle hit no error AND produced no measurable value
+     * (no ProofOfWork output) — i.e. nothing happened. Counting that as a `success` lets a gene that only ever
+     * does nothing climb confidence → ~1.0 and dominate `--loop` selection forever (diversity collapse). An
+     * inert observation therefore builds NO positive evidence: it does not touch success/fail counts and so does
+     * not raise baseConfidence; it is tallied apart (inertCount) and is what `inertBannedGeneIds` uses to ban a
+     * gene stuck doing nothing on a signal.
+     */
+    status: 'success' | 'failed' | 'inert';
+    /** Epoch millis of the outcome (from the event ts). Used for half-life decay. */
+    at: number;
+}
+/** A derived confidence edge: how reliably `geneId` resolved problems under `signalFingerprint`. */
+export interface ConfidenceEdge {
+    signalFingerprint: string;
+    geneId: string;
+    successCount: number;
+    failCount: number;
+    /**
+     * Inert (zero-work) observations on this edge (#195). Tallied apart from success/fail so they neither raise
+     * baseConfidence nor count toward attempts — an all-inert edge stays at the neutral 0.5 prior, never ~1.0.
+     */
+    inertCount: number;
+    /** Epoch millis of the most recent observation on this edge (newest wins). */
+    lastAt: number;
+    /** Laplace-smoothed, undecayed expected success rate in [0,1]. Decay is applied at query time against `now`. */
+    baseConfidence: number;
+}
+/** All derived edges, keyed by `confidenceEdgeKey(signalFingerprint, geneId)`. */
+export type ConfidenceEdges = ReadonlyMap<string, ConfidenceEdge>;
+/** Default half-life for confidence decay (days). Aligned with v1 edgeExpectedSuccess half_life_days=30. */
+export declare const CONFIDENCE_HALF_LIFE_DAYS = 30;
+/**
+ * Composite map key for an edge: `<fingerprint>::<geneId>`. The fingerprint is fixed-length hex (no `:`), so
+ * `::` is an unambiguous separator. Exported so callers/tests look edges up the same way they are stored,
+ * instead of hand-building the key string.
+ */
+export declare function confidenceEdgeKey(signalFingerprint: string, geneId: string): string;
+/**
+ * Stable signal fingerprint (port of v1 computeSignalKey): normalize → de-duplicate → sort → digest.
+ * Deterministic and order-independent, so the same signal SET always yields the same fingerprint.
+ * An empty set maps to a fixed sentinel digest so "no signals" is still a well-defined edge key.
+ */
+export declare function signalFingerprint(signals: readonly string[]): string;
+/**
+ * Half-life decay weight in (0,1] (port of v1 decayWeight): 0.5^(ageDays / halfLife).
+ * Age is measured from the edge's lastAt to `now`. Future/zero/negative age → no decay (weight 1).
+ */
+export declare function decayWeight(lastAt: number, now: number, halfLifeDays?: number): number;
+/**
+ * Derive confidence edges from a flat list of per-(fingerprint, gene) outcome observations.
+ * Pure and deterministic: the same observations (in any order — we track the max `at` for lastAt) always
+ * produce the same edges. This is the replay primitive — feed it the observations re-extracted from
+ * root_events and you get byte-identical edges back.
+ */
+export declare function deriveConfidenceEdges(observations: readonly ConfidenceObservation[]): ConfidenceEdges;
+/**
+ * Query the confidence of `geneId` under `signalFingerprint` at time `now`, in [0,1].
+ * = baseConfidence (Laplace-smoothed success rate) × half-life decay weight.
+ * Returns 0 when there is no edge (no history) so a never-tried gene gets no positive nudge —
+ * absence of evidence is not evidence of success — and 0 for a purely-inert edge (only zero-work cycles),
+ * so a do-nothing gene gets the same zero nudge as a never-tried one (#195).
+ */
+export declare function confidenceFor(edges: ConfidenceEdges, signalFingerprint: string, geneId: string, now: number, halfLifeDays?: number): number;
+/**
+ * Consecutive inert (zero-work) outcomes on a (fingerprint, gene) edge after which a gene with NO real success
+ * on that signal is banned, so `--loop` selection explores instead of re-running a do-nothing gene (#195).
+ * Port of v1 `GENE_INERT_BAN_STREAK` (env `EVOLVER_GENE_INERT_BAN_STREAK`, default 8); kept an inline const to
+ * match v2's algo-tunable convention (BAN_THRESHOLD / MIN_ENV_ATTEMPTS), not env-driven.
+ */
+export declare const GENE_INERT_BAN_STREAK = 8;
+/**
+ * Observation window (in raw events) over which the inert ban is derived — deliberately MUCH wider than the
+ * small recency window used for confidence SCORING. A banned gene runs as `ad-hoc` and accrues no new
+ * observation for itself, so its trailing inert run must be recomputed from a history wide enough that
+ * intervening innovate/ad-hoc cycles cannot evict it — and cannot evict an earlier real success that exempts
+ * the gene (`successCount > 0`). With a small window the run/exemption age out purely from unrelated cycles, so
+ * the ban flaps: the do-nothing gene resurfaces and the productive gene gets falsely banned (#195 regression).
+ * ~14000 events ≈ 2000 cycles, mirroring v1's multi-hundred-cycle memory-graph read horizon: far past any
+ * realistic flap window, yet still bounded (a long-idle gene's stale success eventually ages out, matching v1).
+ * `EventStore.tail()` reads the entire log regardless of window size, so a larger window costs no extra I/O.
+ */
+export declare const INERT_BAN_OBSERVATION_WINDOW = 14000;
+/**
+ * Trailing consecutive-inert run per (fingerprint, gene), keyed by `confidenceEdgeKey`. Unlike
+ * `deriveConfidenceEdges` (a pure function of the observation SET), this is deliberately order-DEPENDENT: it
+ * counts inert outcomes from the most recent backward and ANY real success/failure resets the run to 0 — so a
+ * gene that ever does real work is never punished for older idle cycles. Input MUST be chronological
+ * (oldest→newest, i.e. the order `ingestor.tail` yields); the trailing run is the value left after the final
+ * observation per edge.
+ */
+export declare function trailingInertByEdge(observations: readonly ConfidenceObservation[]): Map<string, number>;
+/**
+ * Gene ids to ban for the CURRENT signal fingerprint because they are stuck producing inert (zero-work)
+ * cycles (#195). A gene is banned iff, on this fingerprint's edge, its trailing inert run ≥ `streak` AND it has
+ * ZERO real success on this signal (double guard: the consecutive run is reset by any real outcome, and a gene
+ * that ever truly succeeded here keeps successCount > 0). Banning a sole-matching inert gene lets selection
+ * fall through to mutation (selected:null → fresh gene), restoring diversity — the failure-streak ban never
+ * fires on these because nothing "fails". Per-signal, mirroring v1's per-signal-key ban: a gene idle on THIS
+ * signal can still be tried on others.
+ */
+export declare function inertBannedGeneIds(edges: ConfidenceEdges, observations: readonly ConfidenceObservation[], fingerprint: string, streak?: number): Set<string>;

package/dist/algo/confidence.js

@@ -0,0 +1,196 @@
+// Preferred-gene confidence edges (positive cross-cycle learning, ported from v1 src/gep/memoryGraph.js,
+// adapted to v2's derive-from-events model). The negative side (ban / epigenetic penalty) is already ported;
+// this is the missing POSITIVE half: a gene that keeps succeeding under a given signal fingerprint should be
+// nudged UP in ranking for that fingerprint — without ever resurrecting a gene that a hard gate excluded.
+//
+// Sidecar principle (same as epigenetics.ts): edges are DERIVED from the append-only root_events log at
+// selection time. We never mutate an asset, never add an asset field, never persist a separate store — so
+// asset_id stays stable and the edges can be replayed byte-for-byte from the events alone.
+//
+// Edge key: (signalFingerprint, geneId). Edge value: { successCount, failCount, inertCount, lastAt, confidence },
+// where confidence is a Laplace-smoothed, half-life-decayed expected success rate in [0, 1] (port of v1
+// edgeExpectedSuccess). The fingerprint is a stable, deterministic digest of the signal set (port of v1
+// computeSignalKey): sorted, de-duplicated, normalized — so the same signals always map to the same edge.
+//
+// This file also carries the negative #195 half of the same scoring data: an `inert` (zero-work) outcome
+// builds no confidence (tallied apart as inertCount), and `inertBannedGeneIds` bans a gene stuck producing only
+// inert cycles on a signal — so a sole-matching do-nothing gene can no longer dominate `--loop` selection.
+//
+// Purity: no Date.now(), no Math.random(). Time enters only through event timestamps and an injected `now`.
+import { createHash } from 'node:crypto';
+/** Default half-life for confidence decay (days). Aligned with v1 edgeExpectedSuccess half_life_days=30. */
+export const CONFIDENCE_HALF_LIFE_DAYS = 30;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Composite map key for an edge: `<fingerprint>::<geneId>`. The fingerprint is fixed-length hex (no `:`), so
+ * `::` is an unambiguous separator. Exported so callers/tests look edges up the same way they are stored,
+ * instead of hand-building the key string.
+ */
+export function confidenceEdgeKey(signalFingerprint, geneId) {
+    return `${signalFingerprint}::${geneId}`;
+}
+/**
+ * Stable signal fingerprint (port of v1 computeSignalKey): normalize → de-duplicate → sort → digest.
+ * Deterministic and order-independent, so the same signal SET always yields the same fingerprint.
+ * An empty set maps to a fixed sentinel digest so "no signals" is still a well-defined edge key.
+ */
+export function signalFingerprint(signals) {
+    const norm = (Array.isArray(signals) ? signals : [])
+        .map((s) => String(s ?? '').trim())
+        .filter((s) => s.length > 0);
+    const uniqSorted = Array.from(new Set(norm)).sort();
+    const canonical = uniqSorted.length > 0 ? uniqSorted.join('|') : '(none)';
+    // Short, collision-resistant, deterministic. 16 hex chars (64 bits) is ample for an edge key.
+    return createHash('sha256').update(canonical, 'utf8').digest('hex').slice(0, 16);
+}
+/**
+ * Laplace-smoothed expected success rate (port of v1 edgeExpectedSuccess, smoothing only — decay is separate).
+ * p = (success + 1) / (success + fail + 2). With zero evidence this is 0.5 (a neutral prior), not 0 or 1.
+ */
+function laplaceSuccessRate(success, fail) {
+    const total = success + fail;
+    return (success + 1) / (total + 2);
+}
+/**
+ * Half-life decay weight in (0,1] (port of v1 decayWeight): 0.5^(ageDays / halfLife).
+ * Age is measured from the edge's lastAt to `now`. Future/zero/negative age → no decay (weight 1).
+ */
+export function decayWeight(lastAt, now, halfLifeDays = CONFIDENCE_HALF_LIFE_DAYS) {
+    if (!Number.isFinite(halfLifeDays) || halfLifeDays <= 0)
+        return 1;
+    if (!Number.isFinite(lastAt) || !Number.isFinite(now))
+        return 1;
+    const ageDays = (now - lastAt) / MS_PER_DAY;
+    if (!Number.isFinite(ageDays) || ageDays <= 0)
+        return 1;
+    return Math.pow(0.5, ageDays / halfLifeDays);
+}
+/**
+ * Derive confidence edges from a flat list of per-(fingerprint, gene) outcome observations.
+ * Pure and deterministic: the same observations (in any order — we track the max `at` for lastAt) always
+ * produce the same edges. This is the replay primitive — feed it the observations re-extracted from
+ * root_events and you get byte-identical edges back.
+ */
+export function deriveConfidenceEdges(observations) {
+    const map = new Map();
+    for (const o of observations) {
+        if (!o || !o.geneId || !o.signalFingerprint)
+            continue;
+        if (o.status !== 'success' && o.status !== 'failed' && o.status !== 'inert')
+            continue;
+        const k = confidenceEdgeKey(o.signalFingerprint, o.geneId);
+        const cur = map.get(k) ?? {
+            signalFingerprint: o.signalFingerprint,
+            geneId: o.geneId,
+            successCount: 0,
+            failCount: 0,
+            inertCount: 0,
+            lastAt: 0,
+            baseConfidence: 0,
+        };
+        // #195: inert (zero-work) outcomes are tallied apart — they must NOT raise success/fail counts, so they
+        // build no positive confidence. They still advance lastAt (the gene WAS exercised; freshness is real).
+        if (o.status === 'success')
+            cur.successCount += 1;
+        else if (o.status === 'failed')
+            cur.failCount += 1;
+        else
+            cur.inertCount += 1;
+        const at = Number.isFinite(o.at) ? o.at : 0;
+        if (at > cur.lastAt)
+            cur.lastAt = at;
+        map.set(k, cur);
+    }
+    // Finalize baseConfidence once counts are known. Inert outcomes are excluded from the smoothing inputs, so an
+    // all-inert edge has success=0/fail=0 → the neutral 0.5 prior (no climb toward 1.0). Order-independent: the
+    // result is a pure function of the observation SET (counts + max `at`), never their sequence.
+    for (const edge of map.values()) {
+        edge.baseConfidence = laplaceSuccessRate(edge.successCount, edge.failCount);
+    }
+    return map;
+}
+/**
+ * Query the confidence of `geneId` under `signalFingerprint` at time `now`, in [0,1].
+ * = baseConfidence (Laplace-smoothed success rate) × half-life decay weight.
+ * Returns 0 when there is no edge (no history) so a never-tried gene gets no positive nudge —
+ * absence of evidence is not evidence of success — and 0 for a purely-inert edge (only zero-work cycles),
+ * so a do-nothing gene gets the same zero nudge as a never-tried one (#195).
+ */
+export function confidenceFor(edges, signalFingerprint, geneId, now, halfLifeDays = CONFIDENCE_HALF_LIFE_DAYS) {
+    const edge = edges.get(confidenceEdgeKey(signalFingerprint, geneId));
+    if (!edge)
+        return 0;
+    // #195: a purely-inert edge (only zero-work cycles — no real success or failure) carries no positive evidence,
+    // so it must give the SAME zero nudge as a never-tried gene, not the neutral-prior 0.5 (which would leak a
+    // +CONFIDENCE_WEIGHT×0.5 boost and let a do-nothing gene out-rank an equal-health fresh candidate before the
+    // inert ban trips). Mirrors v1's hasPositiveEvidence (success>0) gate. A fail-only edge keeps its small Laplace
+    // nudge unchanged — that is pre-existing v2 behavior, out of #195's scope.
+    if (edge.successCount === 0 && edge.failCount === 0)
+        return 0;
+    const w = decayWeight(edge.lastAt, now, halfLifeDays);
+    const c = edge.baseConfidence * w;
+    return c < 0 ? 0 : c > 1 ? 1 : c;
+}
+/**
+ * Consecutive inert (zero-work) outcomes on a (fingerprint, gene) edge after which a gene with NO real success
+ * on that signal is banned, so `--loop` selection explores instead of re-running a do-nothing gene (#195).
+ * Port of v1 `GENE_INERT_BAN_STREAK` (env `EVOLVER_GENE_INERT_BAN_STREAK`, default 8); kept an inline const to
+ * match v2's algo-tunable convention (BAN_THRESHOLD / MIN_ENV_ATTEMPTS), not env-driven.
+ */
+export const GENE_INERT_BAN_STREAK = 8;
+/**
+ * Observation window (in raw events) over which the inert ban is derived — deliberately MUCH wider than the
+ * small recency window used for confidence SCORING. A banned gene runs as `ad-hoc` and accrues no new
+ * observation for itself, so its trailing inert run must be recomputed from a history wide enough that
+ * intervening innovate/ad-hoc cycles cannot evict it — and cannot evict an earlier real success that exempts
+ * the gene (`successCount > 0`). With a small window the run/exemption age out purely from unrelated cycles, so
+ * the ban flaps: the do-nothing gene resurfaces and the productive gene gets falsely banned (#195 regression).
+ * ~14000 events ≈ 2000 cycles, mirroring v1's multi-hundred-cycle memory-graph read horizon: far past any
+ * realistic flap window, yet still bounded (a long-idle gene's stale success eventually ages out, matching v1).
+ * `EventStore.tail()` reads the entire log regardless of window size, so a larger window costs no extra I/O.
+ */
+export const INERT_BAN_OBSERVATION_WINDOW = 14_000;
+/**
+ * Trailing consecutive-inert run per (fingerprint, gene), keyed by `confidenceEdgeKey`. Unlike
+ * `deriveConfidenceEdges` (a pure function of the observation SET), this is deliberately order-DEPENDENT: it
+ * counts inert outcomes from the most recent backward and ANY real success/failure resets the run to 0 — so a
+ * gene that ever does real work is never punished for older idle cycles. Input MUST be chronological
+ * (oldest→newest, i.e. the order `ingestor.tail` yields); the trailing run is the value left after the final
+ * observation per edge.
+ */
+export function trailingInertByEdge(observations) {
+    const run = new Map();
+    for (const o of observations) {
+        if (!o || !o.geneId || !o.signalFingerprint)
+            continue;
+        const k = confidenceEdgeKey(o.signalFingerprint, o.geneId);
+        if (o.status === 'inert')
+            run.set(k, (run.get(k) ?? 0) + 1);
+        else if (o.status === 'success' || o.status === 'failed')
+            run.set(k, 0); // any real outcome breaks the run
+    }
+    return run;
+}
+/**
+ * Gene ids to ban for the CURRENT signal fingerprint because they are stuck producing inert (zero-work)
+ * cycles (#195). A gene is banned iff, on this fingerprint's edge, its trailing inert run ≥ `streak` AND it has
+ * ZERO real success on this signal (double guard: the consecutive run is reset by any real outcome, and a gene
+ * that ever truly succeeded here keeps successCount > 0). Banning a sole-matching inert gene lets selection
+ * fall through to mutation (selected:null → fresh gene), restoring diversity — the failure-streak ban never
+ * fires on these because nothing "fails". Per-signal, mirroring v1's per-signal-key ban: a gene idle on THIS
+ * signal can still be tried on others.
+ */
+export function inertBannedGeneIds(edges, observations, fingerprint, streak = GENE_INERT_BAN_STREAK) {
+    const trailing = trailingInertByEdge(observations);
+    const banned = new Set();
+    for (const edge of edges.values()) {
+        if (edge.signalFingerprint !== fingerprint)
+            continue;
+        if (edge.successCount > 0)
+            continue; // ever did real work here → never banned for idle cycles
+        const k = confidenceEdgeKey(fingerprint, edge.geneId);
+        if ((trailing.get(k) ?? 0) >= streak)
+            banned.add(edge.geneId);
+    }
+    return banned;
+}

package/dist/algo/cycleEngine.d.ts

@@ -0,0 +1,143 @@
+import type { Ingestor } from '../events/ingest.js';
+import type { ProblemPattern } from '../schema/problem.js';
+import type { GepCategory, Mutation, Capsule, EvolutionEvent } from '../wire/index.js';
+import type { AssetStoreProvider } from '../assetstore/provider.js';
+import type { StrategyPoint } from '../strategy/strategyPoint.js';
+import { type CycleStage } from '../cycle/stateMachine.js';
+import { type GeneDecision, type SelectionInput, type GeneCandidateInput, type AntiWarning } from './geneSelection.js';
+import { type EnvFingerprint } from '../bootstrap/envFingerprint.js';
+import type { PersonalityStore } from '../personality/store.js';
+import { type ResolutionStatus } from './solidify.js';
+import type { ProofOfWork } from '../schema/proofOfWork.js';
+import { type ClassifyRecentEvent } from './cycleFailureClassifier.js';
+export interface TriggerEval {
+    trigger: boolean;
+    reasons: string[];
+    valueScore: number;
+}
+export interface ExecutionResult {
+    outcome: {
+        status: 'success' | 'failed';
+        score: number;
+        reason?: string;
+    };
+    proofOfWork?: ProofOfWork;
+    strongEvidence?: boolean;
+    /**
+     * The agent run's transcript (stdout, plus stderr when present), attached by the execution layer on a FAILED
+     * outcome. It is the host-side context classifyCycleFailure needs to reach the host_no_transcript /
+     * host_provider_error buckets on the PRODUCTION path (#279): an empty transcript means the host gave evolver
+     * nothing to evolve from; a provider-error string (429 / quota / context-length) means the host's LLM call
+     * failed, not the gene. Consumed only for failure triage and NEVER persisted to event payloads (the engine
+     * writes only the derived failure_class), so it adds no root_events bloat and leaks no transcript content.
+     */
+    sessionLog?: string;
+}
+export interface SolidifyPermitContext {
+    cycleId: string;
+    geneId: string;
+    signals: readonly string[];
+    mutation: Mutation;
+    decision: GeneDecision;
+    outcome: ExecutionResult['outcome'];
+    proofOfWork?: ProofOfWork;
+    strongEvidence?: boolean;
+}
+export type SolidifyPermitDecision = {
+    ok: true;
+    reason?: string;
+} | {
+    ok: false;
+    reason: string;
+    detail?: string;
+};
+export type SolidifyPermitGate = (ctx: SolidifyPermitContext) => Promise<SolidifyPermitDecision> | SolidifyPermitDecision;
+export interface CycleEngineDeps {
+    ingestor: Ingestor;
+    selection: StrategyPoint<SelectionInput, GeneDecision>;
+    store: AssetStoreProvider;
+    now: () => number;
+    /** Injected randomness for exploration drift (deterministic tests). Defaults to Math.random inside selection. */
+    rng?: () => number;
+    /** Injected environment fingerprint (deterministic tests). Defaults to capturing the real runtime env. */
+    envFingerprint?: () => EnvFingerprint;
+    /** 触发评估(常注入 TriggerEngine.evaluate 的包装; 缺省=直接触发). */
+    trigger?: (p: ProblemPattern, now: number) => Promise<TriggerEval> | TriggerEval;
+    /** 可进化人格(可选). 注入后, 每轮:
+     *   - 轮首: (平台期?先 applyForcePivot→personality.pivoted) → applySelectForRun 自然选择+触发变异
+     *     (personality.mutated), 落盘, 选出的状态喂 personality.selected + 人格风险闸(personality.risk_gated),
+     *     并被 exec bridge 读回注入 prompt(用途①).
+     *   - 轮尾(拿到 outcome 后): applyStatsUpdate 把本轮 outcome/score 回写到当轮所用人格桶
+     *     (personality.stats_updated); v1 语义: 只动 stats/history, 不挪 current.
+     *  缺省 ⇒ 完全不改现有行为(逐字向后兼容). 人格只调"风格/风险", 不改"选哪个 gene / 做什么"——
+     *  与 valueModel/gene 选择共存而非互斥. */
+    personality?: PersonalityStore;
+}
+export interface CycleInput {
+    cycleId: string;
+    problem: ProblemPattern;
+    signals: readonly string[];
+    category: GepCategory;
+    /** Optional explicit strategy preset name; when set, it wins over history-derived meta-signal auto-detection. */
+    strategyName?: string;
+    candidates: readonly GeneCandidateInput[];
+    selectionFloor?: number;
+    /**
+     * Explicit GEP/runtime-selected gene. Forwarded after candidate assembly and local hard filters, so it cannot
+     * bypass trust/review/ban; selection still rejects an env-suppressed candidate.
+     */
+    forcedGeneId?: string;
+    target: string;
+    expectedEffect: string;
+    summary: string;
+    confidence: number;
+    execute: (mutation: Mutation, decision: GeneDecision) => Promise<ExecutionResult> | ExecutionResult;
+    /** Optional adapter/runtime permit gate. Runs after execute succeeds and before solidify writes assets. */
+    solidifyPermit?: SolidifyPermitGate;
+    /**
+     * Distilled-gene fallback pool (ported from v1 #97): broadly-applicable distilled genes that do NOT match the
+     * live signals, assembled (trust/review/ban-filtered) upstream. Forwarded to selection, which uses one only as a
+     * last resort when no candidate clears the floor — reusing a known distilled strategy instead of a blind innovate.
+     */
+    distilledFallback?: readonly GeneCandidateInput[];
+    /** Advisory-only AntiGene warnings matched upstream for this cycle's base signals. */
+    antiWarnings?: readonly AntiWarning[];
+    /**
+     * Optional triage context for the cycle.failed event (PORT v1 #279 issue-reporter half). When the caller can
+     * supply a session transcript or a list of recent failed cycles, classifyCycleFailure runs and the resulting
+     * `failure_class` is written onto cycle.failed payloads. Inert handling (V2 #216) is untouched — this is purely
+     * additive metadata. When absent, host transcript classification stays off; V2-local no-blast classification may
+     * still run from the current failed gene + capsule blast radius.
+     *
+     * This is the EXTERNAL/test injection path. The PRODUCTION host transcript no longer comes through here: the
+     * execution layer (claudeBridge) attaches the agent transcript to ExecutionResult.sessionLog on a failed
+     * outcome, and the failed-write site feeds THAT into classifyCycleFailure (#279 wiring). So host_no_transcript /
+     * host_provider_error now fire on the real autonomous path. failureContext remains for callers that supply a
+     * transcript or recentFailedEvents out-of-band (and for tests). local_gene_no_blast runs in production from the
+     * current gene + capsule blast radius and needs neither.
+     */
+    failureContext?: {
+        sessionLog?: string;
+        recentFailedEvents?: readonly ClassifyRecentEvent[];
+    };
+}
+export interface CycleResult {
+    cycleId: string;
+    triggered: boolean;
+    finalStage: CycleStage;
+    decision?: GeneDecision;
+    mutation?: Mutation;
+    capsule?: Capsule;
+    event?: EvolutionEvent;
+    resolutionStatus?: ResolutionStatus;
+    reasons: string[];
+}
+/**
+ * cycle engine(M4A-1d): signals → trigger → 选 gene → mutation → 执行 → solidify → Capsule + EvolutionEvent.
+ * 每阶段 emit root_events 并校验状态机迁移; 写入序列守硬化 A4(capsule asset_id 先 → 填 capsule_id → event asset_id).
+ */
+export declare class CycleEngine {
+    private readonly deps;
+    constructor(deps: CycleEngineDeps);
+    runCycle(input: CycleInput): Promise<CycleResult>;
+}