@evomap/evolver-core 2.0.0-beta.9 → 2.0.0

package/dist/algo/geneSelection.d.ts

@@ -6,6 +6,7 @@ import type { AssetRecord } from '../assetstore/provider.js';
 import { type ExplorationInput } from './exploration.js';
 import type { GenerationSource } from '../wire/index.js';
 import type { MemoryGraphGeneEvidence } from './memoryGraph.js';
+import { UCB1_REWARD_POLICY_VERSION, UCB1_SELECTION_POLICY_VERSION, type SelectionPolicy, type Ucb1Choice, type Ucb1FallbackReason } from './ucb1.js';
 /** 一个候选 gene 的选择期素材. */
 export interface GeneCandidateInput {
     geneId: string;
@@ -52,12 +53,23 @@ export interface GeneCandidateInput {
      * fallback only for old candidates that do not carry this field.
      */
     generationSource?: GenerationSource;
+    /**
+     * Assembly-owned UCB1 eligibility. Only trusted approved/legacy-local candidates may set true. Injected callers
+     * must not self-assert this bit; candidateAssembly overwrites Hub candidates to false.
+     */
+    explorationEligible?: boolean;
 }
 export interface SelectionInput {
     signals: readonly string[];
     candidates: readonly GeneCandidateInput[];
+    /** Trust-filtered library corpus captured before relevance admission. Omit for direct strategy callers. */
+    semanticCorpus?: readonly GeneCandidateInput[];
+    /** Emergency rollback: restore the pre-IDF semantic scorer and skip profile construction. */
+    disableSemanticIdf?: boolean;
     /** 低于此分则不选(→ 走 innovate 新基因), 默认 0. */
     floor?: number;
+    /** Relevance guard rollout. Omit for legacy selector behavior in direct/core callers. */
+    selectionGuard?: SelectionGuardMode;
     /**
      * 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
@@ -70,8 +82,9 @@ export interface SelectionInput {
     /**
      * 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
+     * normal scored set. Used ONLY after normal selection has no reusable positive choice (the legacy non-positive
+     * pool or an enforced no-match guard): instead of falling 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).
      */
@@ -87,7 +100,8 @@ export interface SelectionInput {
 export interface ScoredCandidate {
     geneId: string;
     assetId?: string;
-    score: number;
+    score: number; /** Internal expanded match in [0,1]; omitted from root-event candidate payloads. */
+    matchScore?: number;
     reasons: string[];
     health?: GeneHealth;
 }
@@ -114,6 +128,36 @@ export interface GeneDecision {
     selectedReason?: string;
     /** Bounded structured outcome evidence for prompt enrichment. */
     memoryEvidence?: MemoryGraphGeneEvidence[];
+    /** Deterministic identity of the bounded IDF profile used for this decision. */
+    semanticProfileVersion?: string;
+    /** Number of trusted semantic documents represented by the profile. */
+    semanticDocumentCount?: number;
+    /** Compact policy trace; omitted for the default engine-health behavior. */
+    selectionPolicy?: SelectionPolicyTrace;
+    /** Versioned relevance guard trace; omitted only for explicit legacy rollback. */
+    selectionGuard?: SelectionGuardTrace;
+}
+export interface SelectionPolicyTrace {
+    requested: Exclude<SelectionPolicy, 'engine-health'>;
+    effective: 'engine-health' | 'ucb1';
+    selectionPolicyVersion: typeof UCB1_SELECTION_POLICY_VERSION;
+    rewardPolicyVersion: typeof UCB1_REWARD_POLICY_VERSION;
+    arm?: Ucb1Choice;
+    shadowArmId?: string;
+    shadowDisagrees?: boolean;
+    fallbackReason?: Ucb1FallbackReason;
+}
+export type SelectionGuardMode = 'legacy' | 'shadow' | 'enforce';
+export declare const SELECTION_GUARD_VERSION = "relevance-guard-v1";
+export type SelectionGuardReason = 'no_match' | 'plateau_flat_match';
+export type SelectionGuardStatus = 'allowed' | 'shadow' | 'forced' | 'ucb1' | 'fallback' | 'innovate';
+export interface SelectionGuardTrace {
+    mode: Exclude<SelectionGuardMode, 'legacy'>;
+    version: typeof SELECTION_GUARD_VERSION;
+    status: SelectionGuardStatus;
+    reason?: SelectionGuardReason;
+    maxMatch?: number;
+    matchSpread?: number;
 }
 /**
  * Weight of the preferred-gene confidence factor (fourth factor, positive cross-cycle learning). Kept small so
@@ -129,12 +173,25 @@ export declare const CONFIDENCE_WEIGHT = 0.15;
 export declare const REUSE_WEIGHT = 0.1;
 /** Weight of scoped local MemoryGraph outcome evidence. */
 export declare const MEMORY_GRAPH_WEIGHT = 0.12;
+/** Bounded weight for a canonical task-domain signal match (#628). */
+export declare const TASK_DOMAIN_WEIGHT = 0.08;
+/** signals_match is weak domain evidence; its maximum score contribution is 0.08 * 0.5 = 0.04. */
+export declare const TASK_DOMAIN_SIGNAL_EVIDENCE = 0.5;
 /**
  * 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-4(gh-1,conf=0.15,memory=0.12,reuse=0.1)";
+export declare const LEGACY_SELECTION_WEIGHTS_VERSION = "sel-5-domain(gh-2,conf=0.15,memory=0.12,reuse=0.1,domain=0.08)";
+export declare const SELECTION_WEIGHTS_VERSION = "sel-6-idf-domain(gh-2,conf=0.15,memory=0.12,reuse=0.1,domain=0.08)";
+interface SelectionGuardAssessment {
+    wouldAbstain: boolean;
+    reason?: SelectionGuardReason;
+    maxMatch?: number;
+    matchSpread?: number;
+}
+/** Refs #626: identify selections whose relevance is absent or cannot discriminate during a plateau. */
+export declare function assessSelectionGuard(scored: readonly ScoredCandidate[], plateauActive: boolean): SelectionGuardAssessment;
 /** 实现1: engine 健康分主导(health 0.6 + 信号匹配 0.4). */
 export declare const engineHealthSelection: Strategy<SelectionInput, GeneDecision>;
 /** 实现2: 纯信号匹配采样(忽略 health, 对照基线 — 经验主义要可对比). */
@@ -142,4 +199,5 @@ 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>;
+export declare function makeGeneSelectionPoint(): StrategyPoint<SelectionInput, GeneDecision>;
+export {};

package/dist/algo/geneSelection.js

@@ -1,11 +1,15 @@
 import { StrategyPoint } from '../strategy/strategyPoint.js';
 import { geneHealthScore, HEALTH_WEIGHTS_VERSION } from './geneHealth.js';
-import { tagOverlapScore, bagCosine } from '../signals/expand.js';
-import { driftSelect } from './exploration.js';
+import { bagCosine, buildSemanticIdfProfile, geneTags, idfBagCosine, idfTagOverlapScore, tagOverlapScore, } from '../signals/expand.js';
+import { driftSelect, explorationWindowSize } from './exploration.js';
 import { isDistilledGeneId } from './geneIntake.js';
+import { chooseUcb1Arm, ucb1StatsForCandidate, UCB1_REWARD_POLICY_VERSION, UCB1_SELECTION_POLICY_VERSION, } from './ucb1.js';
+import { resolveTaskDomainSignals, withoutTaskDomainSignals, } from '../signals/taskDomain.js';
+export const SELECTION_GUARD_VERSION = 'relevance-guard-v1';
 function decisionWithWarnings(input, decision) {
     const selected = decision.selectedGeneId
-        ? decision.candidates.find((candidate) => candidate.geneId === decision.selectedGeneId || candidate.assetId === decision.selectedAssetId)
+        ? decision.candidates.find((candidate) => (candidate.geneId === decision.selectedGeneId
+            || (decision.selectedAssetId !== undefined && candidate.assetId === decision.selectedAssetId)))
         : undefined;
     const enriched = {
         ...decision,
@@ -17,11 +21,13 @@ function decisionWithWarnings(input, decision) {
         : enriched;
 }
 function signalMatchScore(signals, match) {
-    if (signals.length === 0 || match.length === 0)
+    const genericSignals = withoutTaskDomainSignals(signals);
+    const genericMatch = withoutTaskDomainSignals(match);
+    if (genericSignals.length === 0 || genericMatch.length === 0)
         return 0;
-    const set = new Set(signals);
-    const hit = match.filter((m) => set.has(m)).length;
-    return hit / match.length; // 覆盖率
+    const set = new Set(genericSignals);
+    const hit = genericMatch.filter((m) => set.has(m)).length;
+    return hit / genericMatch.length; // 覆盖率
 }
 // Weight of the bag-of-words cosine path when it fills the recall gap left by literal + tag overlap.
 const SEMANTIC_WEIGHT = 0.5;
@@ -39,12 +45,79 @@ export const CONFIDENCE_WEIGHT = 0.15;
 export const REUSE_WEIGHT = 0.1;
 /** Weight of scoped local MemoryGraph outcome evidence. */
 export const MEMORY_GRAPH_WEIGHT = 0.12;
+/** Bounded weight for a canonical task-domain signal match (#628). */
+export const TASK_DOMAIN_WEIGHT = 0.08;
+/** signals_match is weak domain evidence; its maximum score contribution is 0.08 * 0.5 = 0.04. */
+export const TASK_DOMAIN_SIGNAL_EVIDENCE = 0.5;
+const SELECTION_GUARD_MATCH_EPS = 1e-6;
 /**
  * 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 const SELECTION_WEIGHTS_VERSION = `sel-4(${HEALTH_WEIGHTS_VERSION},conf=${CONFIDENCE_WEIGHT},memory=${MEMORY_GRAPH_WEIGHT},reuse=${REUSE_WEIGHT})`;
+export const LEGACY_SELECTION_WEIGHTS_VERSION = `sel-5-domain(${HEALTH_WEIGHTS_VERSION},conf=${CONFIDENCE_WEIGHT},memory=${MEMORY_GRAPH_WEIGHT},reuse=${REUSE_WEIGHT},domain=${TASK_DOMAIN_WEIGHT})`;
+export const SELECTION_WEIGHTS_VERSION = `sel-6-idf-domain(${HEALTH_WEIGHTS_VERSION},conf=${CONFIDENCE_WEIGHT},memory=${MEMORY_GRAPH_WEIGHT},reuse=${REUSE_WEIGHT},domain=${TASK_DOMAIN_WEIGHT})`;
+const SEMANTIC_CORPUS_LIMIT = 1_000;
+const SEMANTIC_SIGNAL_LIMIT = 16;
+const SEMANTIC_SIGNAL_CHARS = 96;
+const SEMANTIC_GENE_ID_CHARS = 128;
+const SEMANTIC_CATEGORY_CHARS = 96;
+const SEMANTIC_SUMMARY_CHARS = 1_024;
+const SEMANTIC_IDENTITY_CHARS = 256;
+function legacyCandidateSemanticText(candidate) {
+    return [
+        ...withoutTaskDomainSignals(candidate.signalsMatch),
+        candidate.category ?? '',
+        candidate.summary ?? '',
+    ].join(' ');
+}
+function boundedSignals(signals) {
+    const out = [];
+    const genericSignals = withoutTaskDomainSignals(signals);
+    const limit = Math.min(genericSignals.length, SEMANTIC_SIGNAL_LIMIT);
+    for (let index = 0; index < limit; index += 1) {
+        const signal = genericSignals[index];
+        if (typeof signal === 'string')
+            out.push(signal.slice(0, SEMANTIC_SIGNAL_CHARS));
+    }
+    return out;
+}
+function semanticCandidateProjection(candidate) {
+    const signalsMatch = boundedSignals(candidate.signalsMatch);
+    const geneId = candidate.geneId.slice(0, SEMANTIC_GENE_ID_CHARS);
+    const category = candidate.category?.slice(0, SEMANTIC_CATEGORY_CHARS);
+    const summary = candidate.summary?.slice(0, SEMANTIC_SUMMARY_CHARS);
+    return {
+        tagInput: {
+            signalsMatch,
+            geneId,
+            ...(category ? { category } : {}),
+            ...(summary ? { summary } : {}),
+        },
+        text: [...signalsMatch, category ?? '', summary ?? ''].join(' '),
+        hasContent: signalsMatch.some((signal) => signal.trim().length > 0)
+            || Boolean(category?.trim())
+            || Boolean(summary?.trim()),
+    };
+}
+function buildSelectionSemanticProfile(corpus) {
+    const documents = [];
+    const identities = new Set();
+    for (const candidate of corpus) {
+        if (documents.length >= SEMANTIC_CORPUS_LIMIT)
+            break;
+        const identityValue = candidate.assetId ?? candidate.geneId;
+        const identity = `${candidate.assetId ? 'asset' : 'gene'}:${identityValue.slice(0, SEMANTIC_IDENTITY_CHARS)}`;
+        if (identities.has(identity))
+            continue;
+        identities.add(identity);
+        const projection = semanticCandidateProjection(candidate);
+        if (!projection.hasContent)
+            continue;
+        documents.push({ tags: geneTags(projection.tagInput), text: projection.text });
+    }
+    return buildSemanticIdfProfile(documents);
+}
 /**
  * Match score with semantic signal expansion (ported from v1): literal coverage first, then fill the
  * recall gap with semantic tag overlap, then with bag-of-words cosine similarity. A perfect literal match
@@ -52,22 +125,40 @@ export const SELECTION_WEIGHTS_VERSION = `sel-4(${HEALTH_WEIGHTS_VERSION},conf=$
  * for 'repair'), and cosine catches lexical similarity the curated tags miss (e.g. a 'timeout_slow' signal
  * vs a gene summarized "fix the slow timeout"). Each layer only fills the gap the previous one left.
  */
-function expandedMatchScore(signals, c) {
+function expandedMatchScore(signals, c, semanticProfile) {
     const literal = signalMatchScore(signals, c.signalsMatch);
     if (literal >= 1)
         return { score: 1, literal, tag: 0, cos: 0 };
-    const tag = tagOverlapScore(signals, { signalsMatch: c.signalsMatch, geneId: c.geneId, category: c.category, summary: c.summary });
+    const projection = semanticProfile ? semanticCandidateProjection(c) : undefined;
+    const semanticSignals = semanticProfile ? boundedSignals(signals) : withoutTaskDomainSignals(signals);
+    const tag = semanticProfile
+        ? idfTagOverlapScore(semanticSignals, projection.tagInput, semanticProfile)
+        : tagOverlapScore(semanticSignals, {
+            signalsMatch: withoutTaskDomainSignals(c.signalsMatch),
+            geneId: c.geneId,
+            category: c.category,
+            summary: c.summary,
+        });
     const base = Math.min(1, literal + (1 - literal) * tag);
     if (base >= 1)
         return { score: 1, literal, tag, cos: 0 };
-    const geneText = [...c.signalsMatch, c.category ?? '', c.summary ?? ''].join(' ');
-    const cos = bagCosine(signals.join(' '), geneText);
+    const cos = semanticProfile
+        ? idfBagCosine(semanticSignals.join(' '), projection.text, semanticProfile)
+        : bagCosine(semanticSignals.join(' '), legacyCandidateSemanticText(c));
     return { score: Math.min(1, base + (1 - base) * cos * SEMANTIC_WEIGHT), literal, tag, cos };
 }
-/** Score one candidate under the engine-health weight vector (health 0.6 + 信号匹配 0.4 − epigenetic + confidence). */
-function scoreCandidate(signals, c) {
+function taskDomainEvidence(queryDomain, candidateSignals) {
+    if (queryDomain.status !== 'resolved')
+        return 0;
+    const candidateDomain = resolveTaskDomainSignals(candidateSignals);
+    return candidateDomain.status === 'resolved' && candidateDomain.slug === queryDomain.slug
+        ? TASK_DOMAIN_SIGNAL_EVIDENCE
+        : 0;
+}
+/** Score one candidate under the engine-health weight vector, including bounded task-domain evidence. */
+function scoreCandidate(signals, c, semanticProfile, queryDomain) {
     const health = geneHealthScore(c.view, { reuseCount: c.reuseCount, antiPatternCount: c.antiPatternCount });
-    const m = expandedMatchScore(signals, c);
+    const m = expandedMatchScore(signals, c, semanticProfile);
     const epi = c.epigeneticPenalty ?? 0;
     // Confidence is the fourth (positive) factor: a [0,1] preferred-gene edge for this signal fingerprint.
     // Clamped defensively so an upstream bug cannot turn the soft nudge into a dominant term.
@@ -76,7 +167,10 @@ function scoreCandidate(signals, c) {
     // into a dominant (or unbounded) term. Absent → 0 → no effect (default-off until a caller injects it).
     const reuse = Math.max(-1, Math.min(1, c.reuseAdjust ?? 0));
     const memory = Math.max(-1, Math.min(1, c.memoryBoost ?? 0));
-    const score = 0.6 * health.score + 0.4 * m.score - epi + CONFIDENCE_WEIGHT * conf + MEMORY_GRAPH_WEIGHT * memory + REUSE_WEIGHT * reuse;
+    const domainEvidence = taskDomainEvidence(queryDomain, c.signalsMatch);
+    const domainContribution = TASK_DOMAIN_WEIGHT * domainEvidence;
+    const score = 0.6 * health.score + 0.4 * m.score - epi + CONFIDENCE_WEIGHT * conf
+        + MEMORY_GRAPH_WEIGHT * memory + REUSE_WEIGHT * reuse + domainContribution;
     const breakdown = m.tag > 0 || m.cos > 0 ? `(literal=${m.literal.toFixed(2)}+tag=${m.tag.toFixed(2)}+cos=${m.cos.toFixed(2)})` : '';
     const reasons = [`health=${health.score.toFixed(3)}(succ=${health.successRate.toFixed(2)},reuse=${health.reuseCount})`, `信号匹配=${m.score.toFixed(2)}${breakdown}`];
     if (epi > 0)
@@ -87,7 +181,9 @@ function scoreCandidate(signals, c) {
         reasons.push(`scoped memory-graph outcome ${memory >= 0 ? '+' : ''}${(MEMORY_GRAPH_WEIGHT * memory).toFixed(3)} (boost=${memory.toFixed(2)})`);
     if (reuse !== 0)
         reasons.push(`cross-runtime reuse ${reuse >= 0 ? '+' : ''}${(REUSE_WEIGHT * reuse).toFixed(3)} (sentiment=${reuse.toFixed(2)})`);
-    return { geneId: c.geneId, ...(c.assetId ? { assetId: c.assetId } : {}), score, health, reasons };
+    if (domainContribution > 0)
+        reasons.push(`task_domain match +${domainContribution.toFixed(3)} (evidence=${domainEvidence.toFixed(2)})`);
+    return { geneId: c.geneId, ...(c.assetId ? { assetId: c.assetId } : {}), score, matchScore: m.score, health, reasons };
 }
 function matchesForcedGeneId(c, forcedGeneId) {
     return c.geneId === forcedGeneId || c.assetId === forcedGeneId;
@@ -101,6 +197,23 @@ function matchesScoredIdentity(a, b) {
 function withoutCandidateIdentity(scored, c) {
     return scored.filter((s) => !matchesCandidateIdentity(s, c));
 }
+function candidateForScore(input, scored) {
+    // Eligibility is attached to one assembled candidate, not to every logical alias of the same content.
+    // Match the exact scored row so an untrusted alias cannot borrow a trusted candidate's UCB1 admission bit.
+    return input.candidates.find((candidate) => (candidate.geneId === scored.geneId && candidate.assetId === scored.assetId));
+}
+function compactMetric(value) {
+    return Math.round(value * 1_000_000) / 1_000_000;
+}
+function compactChoice(choice) {
+    return {
+        ...choice,
+        armId: choice.armId.slice(0, 160),
+        meanReward: compactMetric(choice.meanReward),
+        ...(choice.bonus !== null ? { bonus: compactMetric(choice.bonus) } : { bonus: null }),
+        ...(choice.index !== null ? { index: compactMetric(choice.index) } : { index: null }),
+    };
+}
 function isReusableGenerationSource(source) {
     return source === 'distilled' || source === 'evolved';
 }
@@ -146,20 +259,150 @@ function forcedSelection(input, scored, scoreForcedFallback, floor) {
         forcedFallback.reasons.push(`forced gene selected despite floor ${floor}`);
     return { selectedGeneId: fallback.geneId, ...(fallback.assetId ? { selectedAssetId: fallback.assetId } : {}), scoredForChoice: scoredCandidatesOnly };
 }
+/** Refs #626: identify selections whose relevance is absent or cannot discriminate during a plateau. */
+export function assessSelectionGuard(scored, plateauActive) {
+    if (scored.length === 0) {
+        return { wouldAbstain: true, reason: 'no_match', maxMatch: 0, matchSpread: 0 };
+    }
+    const matches = scored.map((candidate) => candidate.matchScore ?? 0);
+    const maxMatch = Math.max(...matches);
+    const minMatch = Math.min(...matches);
+    const matchSpread = maxMatch - minMatch;
+    const metrics = {
+        maxMatch: compactMetric(maxMatch),
+        matchSpread: compactMetric(matchSpread),
+    };
+    if (maxMatch <= SELECTION_GUARD_MATCH_EPS) {
+        return { wouldAbstain: true, reason: 'no_match', ...metrics };
+    }
+    if (plateauActive && scored.length > 1 && matchSpread <= SELECTION_GUARD_MATCH_EPS) {
+        return { wouldAbstain: true, reason: 'plateau_flat_match', ...metrics };
+    }
+    return { wouldAbstain: false, ...metrics };
+}
 /** 实现1: engine 健康分主导(health 0.6 + 信号匹配 0.4). */
 export const engineHealthSelection = {
     name: 'engine-health',
     version: '1',
     run(input, ctx) {
-        const scored = input.candidates.map((c) => scoreCandidate(input.signals, c)).sort((a, b) => b.score - a.score);
+        const semanticProfile = input.disableSemanticIdf || input.semanticCorpus === undefined
+            ? undefined
+            : buildSelectionSemanticProfile(input.semanticCorpus);
+        const weightsVersion = semanticProfile ? SELECTION_WEIGHTS_VERSION : LEGACY_SELECTION_WEIGHTS_VERSION;
+        const semanticMetadata = semanticProfile
+            ? {
+                semanticProfileVersion: semanticProfile.version,
+                semanticDocumentCount: semanticProfile.documentCount,
+            }
+            : {};
+        const queryDomain = resolveTaskDomainSignals(input.signals);
+        const scoreForSelection = (candidate) => (scoreCandidate(input.signals, candidate, semanticProfile, queryDomain));
+        const scored = input.candidates.map(scoreForSelection).sort((a, b) => b.score - a.score);
         const floor = input.floor ?? 0;
-        const forced = forcedSelection(input, scored, (c) => scoreCandidate(input.signals, c), floor);
+        const forced = forcedSelection(input, scored, scoreForSelection, floor);
         const eligible = forced.scoredForChoice.filter((s) => s.score > floor);
-        // Deterministic top by default; exploration drift picks from the top-N to escape local optima.
-        const drift = driftSelect(eligible.length, input.exploration, ctx?.rng ?? Math.random);
-        const chosen = eligible[drift.index] ?? eligible[0];
+        const guardMode = input.selectionGuard ?? 'legacy';
+        const plateauActive = input.exploration?.plateau?.active === true;
+        let guardAssessment = assessSelectionGuard(eligible, plateauActive);
+        if (eligible.length === 0) {
+            const fullAssessment = assessSelectionGuard(forced.scoredForChoice, plateauActive);
+            if (fullAssessment.reason !== 'no_match') {
+                guardAssessment = {
+                    wouldAbstain: false,
+                    ...(fullAssessment.maxMatch !== undefined ? { maxMatch: fullAssessment.maxMatch } : {}),
+                    ...(fullAssessment.matchSpread !== undefined ? { matchSpread: fullAssessment.matchSpread } : {}),
+                };
+            }
+        }
+        const policyEligible = guardMode === 'enforce' && guardAssessment.reason === 'no_match'
+            ? []
+            : eligible;
+        // Deterministic top by default. Plateau exploration either preserves legacy random drift or, when explicitly
+        // requested, evaluates UCB1 over the same adaptive top-N window. Forced selection always wins below.
+        const requestedPolicy = input.exploration?.policy ?? 'engine-health';
+        const ucb1Active = input.exploration?.plateau?.active === true;
+        let drift = { driftMode: 'deterministic', index: 0, intensity: 0 };
+        let chosen;
+        let selectionPolicy;
+        if (forced.selectedGeneId === undefined && ucb1Active && requestedPolicy !== 'engine-health') {
+            // Canonicalize ties before slicing the UCB window. The legacy/default ranked list intentionally keeps its
+            // stable input-order tie behavior; UCB1 must produce the same arm for any permutation of the same pool.
+            const ucbRanked = [...policyEligible].sort((left, right) => {
+                const leftScore = Number.isFinite(left.score) ? left.score : Number.NEGATIVE_INFINITY;
+                const rightScore = Number.isFinite(right.score) ? right.score : Number.NEGATIVE_INFINITY;
+                return rightScore !== leftScore
+                    ? rightScore - leftScore
+                    : (left.assetId ?? left.geneId).localeCompare(right.assetId ?? right.geneId);
+            });
+            const window = ucbRanked.slice(0, explorationWindowSize(ucbRanked.length, input.exploration));
+            const logicalIdCounts = new Map();
+            for (const scored of window) {
+                logicalIdCounts.set(scored.geneId, (logicalIdCounts.get(scored.geneId) ?? 0) + 1);
+            }
+            const history = input.exploration?.ucb1History;
+            const result = history
+                ? chooseUcb1Arm(window.map((scored) => {
+                    const candidate = candidateForScore(input, scored);
+                    const armId = scored.assetId ?? scored.geneId;
+                    return {
+                        armId,
+                        baseScore: scored.score,
+                        explorationEligible: candidate?.explorationEligible === true,
+                        stats: candidate
+                            ? ucb1StatsForCandidate(history, candidate.geneId, candidate.assetId, (logicalIdCounts.get(candidate.geneId) ?? 0) === 1)
+                            : { armId, pulls: 0, completedPulls: 0, rewardSum: 0, meanReward: 0 },
+                    };
+                }), history.totalPulls)
+                : { choice: null, fallbackReason: 'missing_history' };
+            const ucbChosen = result.choice
+                ? window.find((candidate) => (candidate.assetId ?? candidate.geneId) === result.choice.armId)
+                : undefined;
+            if (requestedPolicy === 'ucb1' && ucbChosen) {
+                chosen = ucbChosen;
+                const choice = compactChoice(result.choice);
+                chosen.reasons.push('ucb1(index=' + (choice.index ?? 'cold') + ',mean=' + choice.meanReward.toFixed(3) + ',pulls=' + choice.pulls + ')');
+                selectionPolicy = {
+                    requested: requestedPolicy,
+                    effective: 'ucb1',
+                    selectionPolicyVersion: UCB1_SELECTION_POLICY_VERSION,
+                    rewardPolicyVersion: UCB1_REWARD_POLICY_VERSION,
+                    arm: choice,
+                };
+            }
+            else {
+                drift = driftSelect(eligible.length, input.exploration, ctx?.rng ?? Math.random);
+                chosen = eligible[drift.index] ?? eligible[0];
+                selectionPolicy = {
+                    requested: requestedPolicy,
+                    effective: 'engine-health',
+                    selectionPolicyVersion: UCB1_SELECTION_POLICY_VERSION,
+                    rewardPolicyVersion: UCB1_REWARD_POLICY_VERSION,
+                    ...(result.choice ? {
+                        arm: compactChoice(result.choice),
+                        shadowArmId: result.choice.armId.slice(0, 160),
+                        shadowDisagrees: Boolean(chosen && (chosen.assetId ?? chosen.geneId) !== result.choice.armId),
+                    } : {}),
+                    ...(result.fallbackReason ? { fallbackReason: result.fallbackReason } : {}),
+                };
+            }
+        }
+        else {
+            drift = driftSelect(eligible.length, input.exploration, ctx?.rng ?? Math.random);
+            chosen = eligible[drift.index] ?? eligible[0];
+        }
+        const forcedSelected = forced.selectedGeneId !== undefined;
+        const ucb1ResolvedPlateau = guardAssessment.reason === 'plateau_flat_match'
+            && selectionPolicy?.effective === 'ucb1';
+        const guardApplied = guardMode === 'enforce'
+            && !forcedSelected
+            && guardAssessment.wouldAbstain
+            && !ucb1ResolvedPlateau;
+        if (guardApplied) {
+            chosen = undefined;
+        }
         let selectedGeneId = forced.selectedGeneId ?? (chosen ? chosen.geneId : null);
         let selectedAssetId = forced.selectedAssetId ?? chosen?.assetId;
+        let fallbackSelected = false;
         if (!selectedGeneId) {
             // Issue #97 (ported from v1 selector.js): no candidate matched any live signal (every gene scored <= 0). Rather
             // than fall straight through to a blind innovate, reuse a *distilled* (or evolved) gene if one is available.
@@ -176,11 +419,14 @@ export const engineHealthSelection = {
             // scored above zero, NOT merely when nothing cleared a positive `floor`. Otherwise a real but weak signal match
             // (0 < score <= floor) would be preempted by an unrelated zero-evidence distilled gene; V1 (which has no floor)
             // keeps such a match. When candidates scored > 0 but below floor, defer to V2's floor policy (innovate).
-            const noSignalMatch = !forced.forceRejected && forced.scoredForChoice.every((s) => s.score <= 0);
+            const normalPoolHasMatch = forced.scoredForChoice.some((candidate) => (candidate.matchScore ?? 0) > SELECTION_GUARD_MATCH_EPS);
+            const noSignalMatch = !forced.forceRejected
+                && ((guardApplied && guardAssessment.reason === 'no_match' && !normalPoolHasMatch)
+                    || forced.scoredForChoice.every((candidate) => candidate.score <= 0));
             const fallback = noSignalMatch
                 ? (input.distilledFallback ?? [])
                     .filter((candidate) => isReusableFallbackCandidate(candidate) && (candidate.epigeneticPenalty ?? 0) === 0)
-                    .map((candidate) => ({ candidate, scored: scoreCandidate(input.signals, candidate) }))
+                    .map((candidate) => ({ candidate, scored: scoreForSelection(candidate) }))
                     .sort((left, right) => right.scored.score - left.scored.score || left.candidate.geneId.localeCompare(right.candidate.geneId))[0]
                 : undefined;
             if (fallback) {
@@ -189,15 +435,48 @@ export const engineHealthSelection = {
                 scored.push(fbScored);
                 selectedGeneId = fb.geneId;
                 selectedAssetId = fb.assetId;
+                fallbackSelected = true;
             }
-            else {
-                forced.scoredForChoice.forEach((s) => s.reasons.push(`< floor ${floor} → innovate`));
+            else if (!guardApplied) {
+                forced.scoredForChoice.forEach((candidate) => candidate.reasons.push(`< floor ${floor} → innovate`));
             }
         }
-        else if (forced.selectedGeneId === undefined && drift.driftMode !== 'deterministic') {
+        else if (forced.selectedGeneId === undefined && selectionPolicy?.effective !== 'ucb1' && drift.driftMode !== 'deterministic') {
             scored.find((s) => s.geneId === selectedGeneId)?.reasons.push(`drift(${drift.driftMode},intensity=${drift.intensity.toFixed(2)})`);
         }
-        return decisionWithWarnings(input, { selectedGeneId, ...(selectedAssetId ? { selectedAssetId } : {}), candidates: scored, weightsVersion: SELECTION_WEIGHTS_VERSION, strategyName: 'engine-health' });
+        if (selectionPolicy?.requested === 'ucb1-shadow' && selectionPolicy.shadowArmId) {
+            selectionPolicy.shadowDisagrees = (selectedAssetId ?? selectedGeneId) !== selectionPolicy.shadowArmId;
+        }
+        const selectionGuard = guardMode === 'legacy'
+            ? undefined
+            : {
+                mode: guardMode,
+                version: SELECTION_GUARD_VERSION,
+                status: forcedSelected
+                    ? 'forced'
+                    : ucb1ResolvedPlateau
+                        ? 'ucb1'
+                        : fallbackSelected
+                            ? 'fallback'
+                            : guardApplied
+                                ? 'innovate'
+                                : guardAssessment.wouldAbstain
+                                    ? 'shadow'
+                                    : 'allowed',
+                ...(guardAssessment.wouldAbstain && guardAssessment.reason ? { reason: guardAssessment.reason } : {}),
+                ...(guardAssessment.maxMatch !== undefined ? { maxMatch: guardAssessment.maxMatch } : {}),
+                ...(guardAssessment.matchSpread !== undefined ? { matchSpread: guardAssessment.matchSpread } : {}),
+            };
+        return decisionWithWarnings(input, {
+            selectedGeneId,
+            ...(selectedAssetId ? { selectedAssetId } : {}),
+            candidates: scored,
+            weightsVersion,
+            ...semanticMetadata,
+            strategyName: 'engine-health',
+            ...(selectionPolicy ? { selectionPolicy } : {}),
+            ...(selectionGuard ? { selectionGuard } : {}),
+        });
     },
 };
 /** 实现2: 纯信号匹配采样(忽略 health, 对照基线 — 经验主义要可对比). */
@@ -229,14 +508,35 @@ export function agentLedSelection(pick) {
         run(input, ctx) {
             const baseDecision = engineHealthSelection.run(input, ctx);
             const base = baseDecision.candidates;
+            const decisionMetadata = {
+                weightsVersion: baseDecision.weightsVersion,
+                ...(baseDecision.semanticProfileVersion
+                    ? { semanticProfileVersion: baseDecision.semanticProfileVersion }
+                    : {}),
+                ...(baseDecision.semanticDocumentCount !== undefined
+                    ? { semanticDocumentCount: baseDecision.semanticDocumentCount }
+                    : {}),
+            };
             const forced = input.forcedGeneId ? base.find((s) => s.reasons.some((r) => r.includes('forced gene'))) : undefined;
             if (forced?.reasons.some((r) => r.includes('forced gene selected'))) {
-                return decisionWithWarnings(input, { selectedGeneId: forced.geneId, ...(forced.assetId ? { selectedAssetId: forced.assetId } : {}), candidates: base, weightsVersion: SELECTION_WEIGHTS_VERSION, strategyName: 'agent-led' });
+                return decisionWithWarnings(input, {
+                    selectedGeneId: forced.geneId,
+                    ...(forced.assetId ? { selectedAssetId: forced.assetId } : {}),
+                    candidates: base,
+                    ...decisionMetadata,
+                    strategyName: 'agent-led',
+                });
             }
             const candidatesForPick = forced?.reasons.some((r) => r.includes('forced gene rejected')) ? base.filter((s) => !matchesScoredIdentity(s, forced)) : base;
             const choice = pick(candidatesForPick, input);
             const selected = candidatesForPick.find((s) => s.geneId === choice) ?? base.find((s) => s.geneId === choice);
-            return decisionWithWarnings(input, { selectedGeneId: choice, ...(selected?.assetId ? { selectedAssetId: selected.assetId } : {}), candidates: base, weightsVersion: SELECTION_WEIGHTS_VERSION, strategyName: 'agent-led' });
+            return decisionWithWarnings(input, {
+                selectedGeneId: choice,
+                ...(selected?.assetId ? { selectedAssetId: selected.assetId } : {}),
+                candidates: base,
+                ...decisionMetadata,
+                strategyName: 'agent-led',
+            });
         },
     };
 }

package/dist/algo/index.d.ts

@@ -1,5 +1,6 @@
 export * from './geneHealth.js';
 export * from './exploration.js';
+export * from './ucb1.js';
 export * from './epigenetics.js';
 export * from './confidence.js';
 export * from './memoryGraph.js';
@@ -8,6 +9,7 @@ export * from './conversationSniffer.js';
 export * from './geneIntake.js';
 export * from './candidateAssembly.js';
 export * from './genePromotion.js';
+export * from './publishEligibility.js';
 export * from './bans.js';
 export * from './antiDistill.js';
 export * from './orchestrator.js';

package/dist/algo/index.js

@@ -1,5 +1,6 @@
 export * from './geneHealth.js';
 export * from './exploration.js';
+export * from './ucb1.js';
 export * from './epigenetics.js';
 export * from './confidence.js';
 export * from './memoryGraph.js';
@@ -8,6 +9,7 @@ export * from './conversationSniffer.js';
 export * from './geneIntake.js';
 export * from './candidateAssembly.js';
 export * from './genePromotion.js';
+export * from './publishEligibility.js';
 export * from './bans.js';
 export * from './antiDistill.js';
 export * from './orchestrator.js';