@evomap/evolver-core 2.0.0-beta.0

package/dist/algo/evolutionEvent.js

@@ -0,0 +1,24 @@
+import { ulid as makeUlid } from 'ulid';
+import { computeAssetId, SCHEMA_VERSION } from '../wire/index.js';
+/**
+ * EvolutionEvent = 世代记录(outcome 真值在此, 硬化 A4). 单向引 Capsule(capsule_id);
+ * 写入序列: capsule asset_id 先算 → 填 capsule_id → 再算 event asset_id.
+ */
+export function buildEvolutionEvent(input) {
+    const base = {
+        type: 'EvolutionEvent',
+        schema_version: SCHEMA_VERSION,
+        id: makeUlid(),
+        parent: input.parent ?? null,
+        intent: input.intent,
+        signals: [...input.signals],
+        genes_used: [...input.genesUsed],
+        mutation_id: input.mutationId,
+        blast_radius: input.blastRadius,
+        outcome: input.outcome,
+        capsule_id: input.capsuleId,
+        source_type: input.sourceType,
+    };
+    const asset_id = computeAssetId(base);
+    return { ...base, asset_id };
+}

package/dist/algo/exploration.d.ts

@@ -0,0 +1,34 @@
+export type PlateauSeverity = 'suggested' | 'required';
+export interface PlateauState {
+    active: boolean;
+    severity: PlateauSeverity;
+    count: number;
+}
+/** Exploration control fed into selection. Absent → pure deterministic top-score selection. */
+export interface ExplorationInput {
+    /** Force drift on even without a plateau (e.g. an explicit explore policy). */
+    driftEnabled?: boolean;
+    /** Plateau detected upstream; an active plateau forces drift intensity up. */
+    plateau?: PlateauState;
+    /** Total attempts across the candidate pool (drives the maturity decay of the drift offset). */
+    totalAttempts?: number;
+}
+/**
+ * Adaptive drift intensity (ported v1): 1/sqrt(Ne) + an offset that decays from 0.3 → 0.02 as the pool
+ * matures (totalAttempts approaches Ne * 10). Tiny pools (Ne <= 1) get a fixed high 0.7 to force exploration.
+ */
+export declare function computeDriftIntensity(ne: number, totalAttempts?: number): number;
+/** Detect a plateau from recent cycle outcomes: count the trailing run of consecutive non-success. */
+export declare function detectPlateau(recentOutcomes: readonly ('success' | 'failed')[]): PlateauState;
+export interface DriftDecision {
+    driftMode: 'deterministic' | 'drift' | 'plateau_drift';
+    index: number;
+    intensity: number;
+}
+/**
+ * Pick which ranked candidate to take among `eligibleCount` above-floor candidates.
+ * No exploration → deterministic top (index 0). With exploration → compute intensity (an active plateau
+ * forces it to 0.7/1.0); with probability = intensity, pick a random candidate from the top-N (N grows
+ * with intensity). rng() is called at most twice; pass a seeded rng for deterministic tests.
+ */
+export declare function driftSelect(eligibleCount: number, exp: ExplorationInput | undefined, rng: () => number): DriftDecision;

package/dist/algo/exploration.js

@@ -0,0 +1,55 @@
+// Exploration layer (ported from v1 src/gep/selector.js): adaptive drift intensity + plateau override
+// to escape local optima. v2 selection is deterministic by default (always the top score); drift stays
+// OFF unless the caller passes SelectionInput.exploration (typically when a plateau is detected upstream).
+// When active, the strategy occasionally picks from the top-N candidates instead of the single top —
+// random exploration to break a stuck pool. Randomness is injected (ctx.rng) for deterministic tests.
+const MATURITY_ATTEMPTS_PER_GENE = 10;
+const DRIFT_OFFSET_MAX = 0.3;
+const DRIFT_OFFSET_MIN = 0.02;
+const PLATEAU_SUGGEST = 5;
+const PLATEAU_FORCE = 10;
+/**
+ * Adaptive drift intensity (ported v1): 1/sqrt(Ne) + an offset that decays from 0.3 → 0.02 as the pool
+ * matures (totalAttempts approaches Ne * 10). Tiny pools (Ne <= 1) get a fixed high 0.7 to force exploration.
+ */
+export function computeDriftIntensity(ne, totalAttempts = 0) {
+    if (!Number.isFinite(ne) || ne <= 1)
+        return 0.7;
+    const maturityThreshold = ne * MATURITY_ATTEMPTS_PER_GENE;
+    const maturity = maturityThreshold > 0 ? Math.min(1, totalAttempts / maturityThreshold) : 0;
+    const offset = DRIFT_OFFSET_MAX - (DRIFT_OFFSET_MAX - DRIFT_OFFSET_MIN) * maturity;
+    return Math.min(1, 1 / Math.sqrt(ne) + offset);
+}
+/** Detect a plateau from recent cycle outcomes: count the trailing run of consecutive non-success. */
+export function detectPlateau(recentOutcomes) {
+    let count = 0;
+    for (let i = recentOutcomes.length - 1; i >= 0; i--) {
+        if (recentOutcomes[i] === 'success')
+            break;
+        count++;
+    }
+    if (count >= PLATEAU_FORCE)
+        return { active: true, severity: 'required', count };
+    if (count >= PLATEAU_SUGGEST)
+        return { active: true, severity: 'suggested', count };
+    return { active: false, severity: 'suggested', count };
+}
+/**
+ * Pick which ranked candidate to take among `eligibleCount` above-floor candidates.
+ * No exploration → deterministic top (index 0). With exploration → compute intensity (an active plateau
+ * forces it to 0.7/1.0); with probability = intensity, pick a random candidate from the top-N (N grows
+ * with intensity). rng() is called at most twice; pass a seeded rng for deterministic tests.
+ */
+export function driftSelect(eligibleCount, exp, rng) {
+    if (!exp || (!exp.driftEnabled && !exp.plateau?.active) || eligibleCount <= 1) {
+        return { driftMode: 'deterministic', index: 0, intensity: 0 };
+    }
+    let intensity = computeDriftIntensity(eligibleCount, exp.totalAttempts ?? 0);
+    if (exp.plateau?.active)
+        intensity = Math.max(intensity, exp.plateau.severity === 'required' ? 1.0 : 0.7);
+    if (rng() >= intensity)
+        return { driftMode: 'deterministic', index: 0, intensity };
+    const topN = Math.min(eligibleCount, Math.max(2, Math.ceil(eligibleCount * intensity)));
+    const index = Math.min(topN - 1, Math.max(0, Math.floor(rng() * topN)));
+    return { driftMode: exp.plateau?.active ? 'plateau_drift' : 'drift', index, intensity };
+}

package/dist/algo/geneHealth.d.ts

@@ -0,0 +1,24 @@
+import type { GeneLearningView } from '../assetstore/learningHistory.js';
+/** 统一 gene 健康分(算法草案§7 自然选择反馈). 并 learning_history/epigenetic/anti_patterns. */
+export interface GeneHealth {
+    geneId: string;
+    successRate: number;
+    reuseCount: number;
+    antiPatternPenalty: number;
+    score: number;
+}
+export interface GeneHealthWeights {
+    successRate: number;
+    reuse: number;
+    antiPattern: number;
+}
+export declare const HEALTH_WEIGHTS_VERSION = "gh-1";
+export declare const DEFAULT_HEALTH_WEIGHTS: GeneHealthWeights;
+/**
+ * gene 健康分 = w1·successRate + w2·reuse归一 − w3·antiPattern密度.
+ * 输入 = M3-6 聚合视图(不内联 learning_history) + anti_patterns 数 + 复用计数.
+ */
+export declare function geneHealthScore(view: GeneLearningView, opts?: {
+    reuseCount?: number;
+    antiPatternCount?: number;
+}, w?: GeneHealthWeights): GeneHealth;

package/dist/algo/geneHealth.js

@@ -0,0 +1,16 @@
+export const HEALTH_WEIGHTS_VERSION = 'gh-1';
+export const DEFAULT_HEALTH_WEIGHTS = { successRate: 0.6, reuse: 0.3, antiPattern: 0.4 };
+/** reuseCount 归一(对数压缩, 复用越多分越高但边际递减). */
+function reuseScore(count) {
+    return count <= 0 ? 0 : Math.min(1, Math.log10(count + 1) / 2); // 100 次≈封顶
+}
+/**
+ * gene 健康分 = w1·successRate + w2·reuse归一 − w3·antiPattern密度.
+ * 输入 = M3-6 聚合视图(不内联 learning_history) + anti_patterns 数 + 复用计数.
+ */
+export function geneHealthScore(view, opts = {}, w = DEFAULT_HEALTH_WEIGHTS) {
+    const reuseCount = opts.reuseCount ?? view.total;
+    const antiPatternPenalty = Math.min(1, (opts.antiPatternCount ?? 0) / 5); // 5+ anti-pattern 封顶惩罚
+    const score = w.successRate * view.successRate + w.reuse * reuseScore(reuseCount) - w.antiPattern * antiPatternPenalty;
+    return { geneId: view.geneId, successRate: view.successRate, reuseCount, antiPatternPenalty, score };
+}

package/dist/algo/geneIntake.d.ts

@@ -0,0 +1,37 @@
+import { type Gene } from '../wire/index.js';
+/**
+ * True when a gene id is a distilled (skill-derived) gene. Single source of truth for the prefix check — also
+ * consumed by candidate assembly / selection to recognise the broadly-applicable distilled genes that may be
+ * reused as a last-resort fallback when no gene matches the live signals (ported from v1 #97).
+ */
+export declare function isDistilledGeneId(id: string | undefined | null): boolean;
+export interface GeneCandidate {
+    id?: string;
+    category?: string;
+    signals_match?: readonly string[];
+    strategy?: readonly string[];
+    summary?: string;
+    preconditions?: readonly string[];
+    constraints?: {
+        max_files?: number;
+        forbidden_paths?: readonly string[];
+    };
+    validation?: readonly string[];
+    routing_hint?: unknown;
+    tool_policy?: unknown;
+}
+/** Minimal shape of an existing gene needed for dedup. */
+export interface ExistingGeneRef {
+    id?: string;
+    signals_match?: readonly string[];
+}
+export interface GeneIntakeResult {
+    ok: boolean;
+    gene?: Gene;
+    errors: string[];
+}
+/**
+ * Validate + normalize a distilled/proposed gene for pool insertion. On success returns the canonical Gene
+ * (defaults filled, asset_id computed); otherwise the structural / dedup / schema errors.
+ */
+export declare function intakeGene(candidate: GeneCandidate, existing?: readonly ExistingGeneRef[]): GeneIntakeResult;

package/dist/algo/geneIntake.js

@@ -0,0 +1,100 @@
+// Gene intake — the structural part of skill distillation (ported from v1 src/gep/skillDistiller.js).
+// v2's solidify produces Capsules but never Genes, so the reusable gene pool is otherwise static (only
+// seeded/imported). This is the safe INTAKE gate for a distilled/proposed gene before it joins the pool:
+// normalize defaults, validate structure + the gep-sdk schema, recompute asset_id, and reject a gene whose
+// signals fully overlap an existing one (dedup, so the pool does not grow redundant). The gene's CONTENT
+// is generated upstream (the agent runtime / a distillation prompt — generative, out of core scope); this
+// slice is the structural gate. Pairs with capabilityCandidates (which proposes what to distill).
+import { computeAssetId, validateWire, SCHEMA_VERSION, normalizeRoutingHint, normalizeToolPolicy, stripGeneHints, } from '../wire/index.js';
+const VALID_CATEGORIES = ['repair', 'optimize', 'innovate', 'explore'];
+const DEFAULT_FORBIDDEN_PATHS = ['.git', 'node_modules'];
+const DEFAULT_MAX_FILES = 12;
+/** Id prefix every distilled (skill-derived) gene carries. Recognised via {@link isDistilledGeneId}. */
+const DISTILLED_ID_PREFIX = 'gene_distilled_';
+/**
+ * True when a gene id is a distilled (skill-derived) gene. Single source of truth for the prefix check — also
+ * consumed by candidate assembly / selection to recognise the broadly-applicable distilled genes that may be
+ * reused as a last-resort fallback when no gene matches the live signals (ported from v1 #97).
+ */
+export function isDistilledGeneId(id) {
+    return typeof id === 'string' && id.startsWith(DISTILLED_ID_PREFIX);
+}
+function fnv1a(s) {
+    let h = 2166136261;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+const clean = (xs) => (xs ?? []).map((s) => String(s).trim()).filter((s) => s.length > 0);
+/** Returns the id of an existing gene whose signals are a superset of `signals` (i.e. the candidate is redundant), else null. */
+function fullyOverlaps(signals, existing) {
+    const newSet = signals.map((s) => s.toLowerCase());
+    for (const eg of existing) {
+        const egSet = new Set((eg.signals_match ?? []).map((s) => String(s).toLowerCase()));
+        if (egSet.size === 0)
+            continue;
+        if (newSet.every((s) => egSet.has(s)))
+            return eg.id ?? '?';
+    }
+    return null;
+}
+/**
+ * Validate + normalize a distilled/proposed gene for pool insertion. On success returns the canonical Gene
+ * (defaults filled, asset_id computed); otherwise the structural / dedup / schema errors.
+ */
+export function intakeGene(candidate, existing = []) {
+    const errors = [];
+    const signals = clean(candidate.signals_match);
+    const strategy = clean(candidate.strategy);
+    if (signals.length === 0)
+        errors.push('signals_match is empty');
+    if (strategy.length === 0)
+        errors.push('strategy is empty');
+    if (signals.length > 0) {
+        const dup = fullyOverlaps(signals, existing);
+        if (dup)
+            errors.push(`signals_match fully overlaps existing gene: ${dup}`);
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const category = VALID_CATEGORIES.includes(candidate.category) ? candidate.category : 'optimize';
+    const id = candidate.id && candidate.id.startsWith(DISTILLED_ID_PREFIX) ? candidate.id : `${DISTILLED_ID_PREFIX}${fnv1a(signals.join('|'))}`;
+    // v2-delta EvoX hints (v1 PR #93): normalized so a candidate carrying them lands canonical, dropped to
+    // absent when malformed/empty. The router / tool-gate reads absent === "no opinion".
+    const routingHint = normalizeRoutingHint(candidate.routing_hint);
+    const toolPolicy = normalizeToolPolicy(candidate.tool_policy);
+    const gene = {
+        type: 'Gene',
+        schema_version: SCHEMA_VERSION,
+        id,
+        category,
+        signals_match: signals,
+        strategy,
+        constraints: {
+            max_files: candidate.constraints?.max_files ?? DEFAULT_MAX_FILES,
+            forbidden_paths: [...(candidate.constraints?.forbidden_paths ?? DEFAULT_FORBIDDEN_PATHS)],
+        },
+        validation: candidate.validation ? [...candidate.validation] : [],
+        summary: candidate.summary ?? `Strategy for: ${signals.slice(0, 3).join(', ')}`,
+        ...(candidate.preconditions ? { preconditions: [...candidate.preconditions] } : {}),
+        ...(routingHint ? { routing_hint: routingHint } : {}),
+        ...(toolPolicy ? { tool_policy: toolPolicy } : {}),
+        asset_id: '',
+    };
+    // asset_id folds in the hints (intake's own canonical shape — gep-sdk canonicalize hashes every own key).
+    // NB: this is NOT byte-equal to what v1's createGene would hash for the same logical gene — v1 always emits
+    // routing_hint/tool_policy:null plus empty epigenetic_marks/learning_history/anti_patterns/preconditions that
+    // v2 intake omits, so the canonical shapes differ. Self-consistent here; not a cross-impl parity guarantee.
+    gene.asset_id = computeAssetId(gene) ?? '';
+    // Structural gate validates the gep-sdk-known CORE. routing_hint / tool_policy are v2-delta (pending a
+    // gene-schema bump), so strip them before the check — else additionalProperties:false rejects the gene at
+    // intake. The full hinted gene stays schema-invalid until the SDK catches up — surfaced by the advisory
+    // validateWire preview (evolver_gep_build) and enforced by the hub on receipt, NOT by a local egress gate
+    // (the publish/egress path is sanitize-only). Same v2-delta contract Capsule's proof_of_work had pre-1.11.0.
+    const v = validateWire(stripGeneHints(gene));
+    if (!v.ok)
+        return { ok: false, errors: v.errors };
+    return { ok: true, gene, errors: [] };
+}

package/dist/algo/genePromotion.d.ts

@@ -0,0 +1,48 @@
+import type { AssetStoreProvider } from '../assetstore/provider.js';
+import type { ReviewLedger } from '../assetstore/reviewLedger.js';
+export interface AutoPromoteOptions {
+    /** Min real (value-producing) successes — with ZERO failures — before a quarantined draft is auto-approved. */
+    minSuccess?: number;
+    /** Who/why stamp for the audited approval. Defaults to the auto-promoter. */
+    by?: string;
+}
+/** The default proven-success bar. Symmetric to reuse-report's prune threshold (a few clean signals, not one). */
+export declare const DEFAULT_PROMOTE_MIN_SUCCESS = 3;
+/**
+ * The single promote predicate: a quarantined gene auto-promotes iff it has ZERO failures AND at least minSuccess
+ * real (value-producing) successes. Inert (zero-work) successes are excluded by aggregateLearningHistory, so they
+ * never count here. Every surface that judges promote-eligibility (auto-promote, reuse-report --promote, the
+ * review listing) MUST route through this so they cannot diverge — e.g. a gene the review view labels "healthy"
+ * by success-rate but that still has a failure must read as NOT promotable here.
+ */
+export declare function probationWouldPromote(view: {
+    success: number;
+    failed: number;
+}, minSuccess?: number): boolean;
+/** A quarantined gene's evidence so far, measured against the promote threshold. Read-only: this is what the
+ *  daemon's auto-promote tick decides on, surfaced so an operator can SEE the probation pool before flipping
+ *  EVOLVER_GENE_PROBATION on. `wouldPromote` is the exact predicate autoPromoteProbationGenes acts on. */
+export interface ProbationStatus {
+    assetId: string;
+    geneId: string;
+    success: number;
+    failed: number;
+    inert: number;
+    total: number;
+    /** The bar this status was scored against (echoes the option for display). */
+    minSuccess: number;
+    /** True iff this gene would be auto-approved right now (0 failures AND success >= minSuccess). */
+    wouldPromote: boolean;
+}
+/**
+ * Read-only scan of the review ledger: for every QUARANTINED gene, derive its learning evidence and whether it
+ * meets the promote bar right now. The single source of truth for the promote predicate — autoPromoteProbationGenes
+ * acts on exactly this, and reuse-report --promote displays it. Never mutates the ledger.
+ */
+export declare function scanProbationGenes(store: AssetStoreProvider, review: ReviewLedger, opts?: Pick<AutoPromoteOptions, 'minSuccess'>): Promise<ProbationStatus[]>;
+/**
+ * Scan the review ledger for quarantined genes and auto-approve those whose cycle outcomes prove their value
+ * (>= minSuccess real successes AND 0 failures). Returns the asset_ids promoted. Never promotes a gene with any
+ * failure, nor one whose only "successes" were inert. Idempotent: an already-approved/rejected gene is skipped.
+ */
+export declare function autoPromoteProbationGenes(store: AssetStoreProvider, review: ReviewLedger, opts?: AutoPromoteOptions): Promise<string[]>;

package/dist/algo/genePromotion.js

@@ -0,0 +1,53 @@
+import { aggregateLearningHistory } from '../assetstore/learningHistory.js';
+/** The default proven-success bar. Symmetric to reuse-report's prune threshold (a few clean signals, not one). */
+export const DEFAULT_PROMOTE_MIN_SUCCESS = 3;
+/**
+ * The single promote predicate: a quarantined gene auto-promotes iff it has ZERO failures AND at least minSuccess
+ * real (value-producing) successes. Inert (zero-work) successes are excluded by aggregateLearningHistory, so they
+ * never count here. Every surface that judges promote-eligibility (auto-promote, reuse-report --promote, the
+ * review listing) MUST route through this so they cannot diverge — e.g. a gene the review view labels "healthy"
+ * by success-rate but that still has a failure must read as NOT promotable here.
+ */
+export function probationWouldPromote(view, minSuccess = DEFAULT_PROMOTE_MIN_SUCCESS) {
+    return view.failed === 0 && view.success >= minSuccess;
+}
+/**
+ * Read-only scan of the review ledger: for every QUARANTINED gene, derive its learning evidence and whether it
+ * meets the promote bar right now. The single source of truth for the promote predicate — autoPromoteProbationGenes
+ * acts on exactly this, and reuse-report --promote displays it. Never mutates the ledger.
+ */
+export async function scanProbationGenes(store, review, opts = {}) {
+    const minSuccess = opts.minSuccess ?? DEFAULT_PROMOTE_MIN_SUCCESS;
+    const out = [];
+    for (const rec of review.records()) {
+        if (rec.state !== 'quarantined')
+            continue; // only probation drafts; human approve/reject is left alone
+        const gene = await store.get(rec.assetId);
+        if (!gene || gene.type !== 'Gene')
+            continue;
+        const geneId = typeof gene['id'] === 'string' ? String(gene['id']) : rec.assetId;
+        const view = await aggregateLearningHistory(store, geneId);
+        out.push({
+            assetId: rec.assetId, geneId,
+            success: view.success, failed: view.failed, inert: view.inert ?? 0, total: view.total,
+            minSuccess, wouldPromote: probationWouldPromote(view, minSuccess),
+        });
+    }
+    return out;
+}
+/**
+ * Scan the review ledger for quarantined genes and auto-approve those whose cycle outcomes prove their value
+ * (>= minSuccess real successes AND 0 failures). Returns the asset_ids promoted. Never promotes a gene with any
+ * failure, nor one whose only "successes" were inert. Idempotent: an already-approved/rejected gene is skipped.
+ */
+export async function autoPromoteProbationGenes(store, review, opts = {}) {
+    const by = opts.by ?? 'auto-promote';
+    const promoted = [];
+    for (const s of await scanProbationGenes(store, review, opts)) {
+        if (!s.wouldPromote)
+            continue;
+        review.approve(s.assetId, by, `evidence: ${s.success}/${s.total} success, 0 fail (auto-promote #306)`);
+        promoted.push(s.assetId);
+    }
+    return promoted;
+}

package/dist/algo/geneSelection.d.ts

@@ -0,0 +1,128 @@
+import type { Strategy } from '../strategy/strategyPoint.js';
+import { StrategyPoint } from '../strategy/strategyPoint.js';
+import { type GeneHealth } from './geneHealth.js';
+import type { GeneLearningView } from '../assetstore/learningHistory.js';
+import type { AssetRecord } from '../assetstore/provider.js';
+import { type ExplorationInput } from './exploration.js';
+/** 一个候选 gene 的选择期素材. */
+export interface GeneCandidateInput {
+    geneId: string;
+    /**
+     * Content asset_id (sha256:…) of this candidate, when distinct from the logical geneId. Optional. Lets the
+     * cross-runtime reuse map (#268, keyed by reuse-event assetId) match a candidate by EITHER id — local genes
+     * supply it from their record; an injected hub candidate can carry it so it is matched on the same footing.
+     */
+    assetId?: string;
+    signalsMatch: readonly string[];
+    view: GeneLearningView;
+    reuseCount?: number;
+    antiPatternCount?: number;
+    /** Optional gene category/summary for semantic tag expansion (signal-expansion recall, ported from v1). */
+    category?: string;
+    summary?: string;
+    /**
+     * Full hub-fetched Gene payload, when an adapter injects a transient reuse candidate. Selection never reads this;
+     * autoexec uses it to land the asset through the provenance/review gates before the candidate can be executed.
+     */
+    hubAsset?: AssetRecord;
+    /** Epigenetic penalty for the current environment class (subtracted from score; computed upstream, ported from v1). */
+    epigeneticPenalty?: number;
+    /**
+     * Preferred-gene confidence in [0,1] for the current signal fingerprint (added to score; positive cross-cycle
+     * learning, computed upstream from the confidence sidecar, ported from v1). A gene that keeps succeeding under
+     * the same signals is nudged up. This is a SOFT re-ordering factor only: it is applied to the same candidate
+     * set the hard gates already produced, so a high confidence can never resurrect a gene that was excluded.
+     */
+    confidence?: number;
+    /**
+     * Cross-runtime reuse sentiment in [-1, 1] for this gene (#268 phase 1): the net of self-reported reuse
+     * SUCCESSes vs negatives (failed/mismatched/stale/unsafe), computed upstream from reuse-outcome events
+     * (reuseAdjustFromSummary). A SOFT, bounded re-order factor — added with a small weight and clamped — so this
+     * weak, self-reported signal can nudge near-ties (and down-rank a gene foreign agents keep finding unhelpful)
+     * yet can NEVER override the hard gates (trust/review/ban run in assembly, before scoring). Absent → 0 → no
+     * effect, so the factor is dormant until a caller injects the signal (default-off).
+     */
+    reuseAdjust?: number;
+}
+export interface SelectionInput {
+    signals: readonly string[];
+    candidates: readonly GeneCandidateInput[];
+    /** 低于此分则不选(→ 走 innovate 新基因), 默认 0. */
+    floor?: number;
+    /**
+     * Explicit gene requested by GEP / an external runtime. This is a hard selection only within the already
+     * assembled candidate/fallback pools: it cannot resurrect a gene filtered by trust/review/ban upstream, and it is
+     * refused here when the entry is epigenetically suppressed for the current environment. Accepts either logical
+     * geneId or content assetId.
+     */
+    forcedGeneId?: string;
+    /** Exploration control (drift / plateau override). Absent → deterministic top-score selection (ported from v1). */
+    exploration?: ExplorationInput;
+    /**
+     * Distilled-gene fallback pool (ported from v1 #97): broadly-applicable distilled genes that do NOT match the
+     * live signals, supplied by the assembly layer (already trust/review/ban-filtered) so they never compete in the
+     * normal scored set. Used ONLY as a last resort when no candidate clears the floor: instead of falling straight
+     * through to a blind innovate, selection reuses a known distilled strategy. Epigenetically-suppressed entries
+     * (epigeneticPenalty > 0) are skipped — v2's event-log-derived epigeneticPenalty is the analog of v1's asset-mark
+     * hard suppression (a related band, not the identical predicate).
+     */
+    distilledFallback?: readonly GeneCandidateInput[];
+    /**
+     * Non-executable negative memory matched for the current signals. These warnings are carried into the decision
+     * for prompt rendering only; they never enter scoring, fallback, or forced selection.
+     */
+    antiWarnings?: readonly AntiWarning[];
+}
+export interface ScoredCandidate {
+    geneId: string;
+    assetId?: string;
+    score: number;
+    reasons: string[];
+    health?: GeneHealth;
+}
+export interface AntiWarning {
+    antiGeneId: string;
+    assetId?: string;
+    trigger: readonly string[];
+    avoid: readonly string[];
+    summary?: string;
+    severity?: 'low' | 'medium' | 'high';
+    rationale?: string;
+}
+/** 可解释的选择决策(禁黑盒, 军杰§9.4): 带 candidates/scores/reasons/weightsVersion. */
+export interface GeneDecision {
+    selectedGeneId: string | null;
+    /** Content asset_id for the selected candidate when known. Preserves exact forced-by-asset execution semantics. */
+    selectedAssetId?: string;
+    candidates: ScoredCandidate[];
+    /** Advisory-only AntiGene guardrails; never selected, executed, or attributed as used genes. */
+    antiWarnings?: AntiWarning[];
+    weightsVersion: string;
+    strategyName: string;
+}
+/**
+ * Weight of the preferred-gene confidence factor (fourth factor, positive cross-cycle learning). Kept small so
+ * it only re-orders near-ties between already-eligible candidates rather than overriding health / signal match.
+ */
+export declare const CONFIDENCE_WEIGHT = 0.15;
+/**
+ * Weight of the cross-runtime reuse-sentiment factor (#268 phase 1). Deliberately SMALLER than CONFIDENCE_WEIGHT:
+ * a self-reported reuse outcome is weaker evidence than the confidence sidecar (which is built from verified cycle
+ * history), so it only re-orders near-ties. Clamped to a [-1,1] sentiment, so its contribution is bounded to
+ * ±REUSE_WEIGHT and can never dominate health/signal-match.
+ */
+export declare const REUSE_WEIGHT = 0.1;
+/**
+ * Version of the full engine-health weight vector (health 0.6 + signal-match 0.4 − epigenetic penalty
+ * + CONFIDENCE_WEIGHT × confidence + REUSE_WEIGHT × reuse-sentiment). Bumped whenever a factor is added so golden
+ * weight snapshots track the change. Composed from the health-weights version so a change to either layer shows.
+ */
+export declare const SELECTION_WEIGHTS_VERSION = "sel-3(gh-1,conf=0.15,reuse=0.1)";
+/** 实现1: engine 健康分主导(health 0.6 + 信号匹配 0.4). */
+export declare const engineHealthSelection: Strategy<SelectionInput, GeneDecision>;
+/** 实现2: 纯信号匹配采样(忽略 health, 对照基线 — 经验主义要可对比). */
+export declare const signalMatchSelection: Strategy<SelectionInput, GeneDecision>;
+/** 实现3: agent 主导(注入决策回调; engine 只给候选+分, agent 拍板, D26 agent 一等公民). */
+export declare function agentLedSelection(pick: (scored: ScoredCandidate[], input: SelectionInput) => string | null): Strategy<SelectionInput, GeneDecision>;
+/** 选 gene StrategyPoint: 默认 engine-health, 备选 signal-match(+ 可注册 agent-led). */
+export declare function makeGeneSelectionPoint(): StrategyPoint<SelectionInput, GeneDecision>;