@evomap/evolver-core 2.0.0-beta.19 → 2.0.0-beta.22

package/dist/algo/geneHealth.d.ts

@@ -21,4 +21,37 @@ export declare const DEFAULT_HEALTH_WEIGHTS: GeneHealthWeights;
 export declare function geneHealthScore(view: GeneLearningView, opts?: {
     reuseCount?: number;
     antiPatternCount?: number;
-}, w?: GeneHealthWeights): GeneHealth;
+}, w?: GeneHealthWeights): GeneHealth;
+/**
+ * Whether a gene has any DECISIVE evidence behind its health score.
+ *
+ * `aggregateLearningHistory` divides successes by `success + failed`, excluding inert runs from both
+ * sides, so a gene whose capsules are all inert — or which has never run — yields `successRate = 0` and
+ * therefore `score = 0`. That zero means "nothing is known", not "known to be bad", and the two must not
+ * render the same: showing 0% for an unproven gene is the same class of lie as showing a self-reported
+ * 98%. A surface reporting a score must check this first and say "not assessed" when it is false.
+ */
+export declare function isGeneHealthAssessable(view: Pick<GeneLearningView, 'success' | 'failed'>): boolean;
+/**
+ * The best score {@link geneHealthScore} can return under `w`: a gene with a perfect success rate, reuse
+ * saturated, and no anti-patterns. Derived from the weights rather than hard-coded, so retuning them
+ * cannot silently leave the display scale calibrated to the old ceiling.
+ */
+export declare function geneHealthScoreCeiling(w?: GeneHealthWeights): number;
+/**
+ * Map a raw health score onto [0, 1] for DISPLAY only.
+ *
+ * `geneHealthScore` is not a 0–1 quantity: under the default weights it tops out at 0.7 and floors at
+ * -0.4 (the anti-pattern penalty). Rendering the raw number as a percentage would report a flawless gene
+ * as 70%, so any surface showing a percentage has to rescale — and doing that at each surface is how two
+ * surfaces end up disagreeing.
+ *
+ * Negative scores clamp to 0 rather than mapping the full [-ceiling_penalty, ceiling] range onto [0, 1]:
+ * a linear map would place "no evidence at all" (raw 0) near the middle of the bar, which reads as a
+ * passing grade for a gene that has proven nothing. The penalty is not lost, it is just not separately
+ * legible below zero — callers that need it read `GeneHealth.score` / `antiPatternPenalty` directly.
+ *
+ * Never feed this back into selection: ranking consumes the raw score, and clamping there would make
+ * every penalized gene tie at 0.
+ */
+export declare function normalizeGeneHealthScore(score: number, w?: GeneHealthWeights): number;

package/dist/algo/geneHealth.js

@@ -14,4 +14,46 @@ export function geneHealthScore(view, opts = {}, w = DEFAULT_HEALTH_WEIGHTS) {
     const confidenceAdjustedSuccess = view.successRate * (w.successRate + w.reuse * reuseScore(reuseCount));
     const score = confidenceAdjustedSuccess - w.antiPattern * antiPatternPenalty;
     return { geneId: view.geneId, successRate: view.successRate, reuseCount, antiPatternPenalty, score };
+}
+/**
+ * Whether a gene has any DECISIVE evidence behind its health score.
+ *
+ * `aggregateLearningHistory` divides successes by `success + failed`, excluding inert runs from both
+ * sides, so a gene whose capsules are all inert — or which has never run — yields `successRate = 0` and
+ * therefore `score = 0`. That zero means "nothing is known", not "known to be bad", and the two must not
+ * render the same: showing 0% for an unproven gene is the same class of lie as showing a self-reported
+ * 98%. A surface reporting a score must check this first and say "not assessed" when it is false.
+ */
+export function isGeneHealthAssessable(view) {
+    return view.success + view.failed >= 1;
+}
+/**
+ * The best score {@link geneHealthScore} can return under `w`: a gene with a perfect success rate, reuse
+ * saturated, and no anti-patterns. Derived from the weights rather than hard-coded, so retuning them
+ * cannot silently leave the display scale calibrated to the old ceiling.
+ */
+export function geneHealthScoreCeiling(w = DEFAULT_HEALTH_WEIGHTS) {
+    return w.successRate + w.reuse;
+}
+/**
+ * Map a raw health score onto [0, 1] for DISPLAY only.
+ *
+ * `geneHealthScore` is not a 0–1 quantity: under the default weights it tops out at 0.7 and floors at
+ * -0.4 (the anti-pattern penalty). Rendering the raw number as a percentage would report a flawless gene
+ * as 70%, so any surface showing a percentage has to rescale — and doing that at each surface is how two
+ * surfaces end up disagreeing.
+ *
+ * Negative scores clamp to 0 rather than mapping the full [-ceiling_penalty, ceiling] range onto [0, 1]:
+ * a linear map would place "no evidence at all" (raw 0) near the middle of the bar, which reads as a
+ * passing grade for a gene that has proven nothing. The penalty is not lost, it is just not separately
+ * legible below zero — callers that need it read `GeneHealth.score` / `antiPatternPenalty` directly.
+ *
+ * Never feed this back into selection: ranking consumes the raw score, and clamping there would make
+ * every penalized gene tie at 0.
+ */
+export function normalizeGeneHealthScore(score, w = DEFAULT_HEALTH_WEIGHTS) {
+    const ceiling = geneHealthScoreCeiling(w);
+    if (!Number.isFinite(score) || ceiling <= 0)
+        return 0;
+    return Math.min(1, Math.max(0, score / ceiling));
 }

package/dist/algo/geneIntake.d.ts

@@ -1,4 +1,4 @@
-import { type Gene, type GenerationSource } from '../wire/index.js';
+import { type EnvClass, type Gene, type GeneClaim, type GeneRuntimeProfile, type GeneScope, type GeneVerifierProfile, type GenerationSource } from '../wire/index.js';
 /**
  * True when a gene id is in the `gene_distilled_` namespace. NB this prefix is now a NAMESPACE marker, NOT a
  * provenance tag: v1 used it to mean "skill-derived" (auto-evolved genes were `gene_auto_`), but v2's intakeGene
@@ -26,9 +26,27 @@ export interface GeneCandidate {
         forbidden_paths?: readonly string[];
     };
     validation?: readonly string[];
+    /**
+     * Runtime profile: which LLM produced this gene. This is the \(K_{auto}\) runtime coordinate, and it was the
+     * binding constraint on automatic-governance eligibility in production (32.9% populated vs 99%+ for the
+     * retrieval coordinates, bench/thesis/result-kauto-coverage.json) — because intake never populated it, so it
+     * only appeared when some other writer happened to set it. Intake now fills it from the SAME producer the
+     * environment fingerprint already uses (detectModelName), which resolves an explicit EVOLVER_MODEL_NAME or a
+     * host CLI's model env var. Callers may pass it explicitly to override detection.
+     *
+     * The literal 'unknown' is what detectModelName returns when nothing is discoverable, and it is deliberately
+     * NOT written: an undetectable runtime is not a machine-decidable coordinate, and recording 'unknown' would
+     * inflate K_auto coverage with rows that cannot actually be governed by runtime. Absent therefore keeps its
+     * existing meaning (not recorded), and a present value always names a real runtime.
+     */
+    model_name?: string;
     routing_hint?: unknown;
     tool_policy?: unknown;
     generation_meta?: unknown;
+    claims?: unknown;
+    scope?: unknown;
+    runtime_profile?: unknown;
+    verifier_profile?: unknown;
 }
 /** Minimal shape of an existing gene needed for dedup. */
 export interface ExistingGeneRef {
@@ -40,6 +58,33 @@ export interface GeneIntakeResult {
     gene?: Gene;
     errors: string[];
 }
+/**
+ * Map free-text retrieval signals into the closed constraint language so scope containment is decidable.
+ * Already-namespaced terms and version intervals pass through; bare tokens become `capability:<token>`.
+ * Hard facets (`required:…`) keep the marker around the namespaced term.
+ */
+export declare function namespaceScopeSignals(signals: readonly string[]): string[];
+/** Detect a coarse env_class for runtime_profile from process env (CI → ci, else local). */
+export declare function detectEnvClass(env?: NodeJS.ProcessEnv): EnvClass;
+/**
+ * Honest defaults for K_auto coordinates the producer did not state. Never invents a coordinate from
+ * nothing: each default is grounded in fields the gene already carries (signals, model, validation).
+ */
+export declare function deriveDefaultKautoCoordinates(input: {
+    signals: readonly string[];
+    modelName?: string;
+    validation: readonly string[];
+    claims?: GeneClaim[] | null;
+    scope?: GeneScope | null;
+    runtime_profile?: GeneRuntimeProfile | null;
+    verifier_profile?: GeneVerifierProfile | null;
+    env?: NodeJS.ProcessEnv;
+}): {
+    claims: GeneClaim[] | null;
+    scope: GeneScope | null;
+    runtime_profile: GeneRuntimeProfile | null;
+    verifier_profile: GeneVerifierProfile | 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.

package/dist/algo/geneIntake.js

@@ -5,12 +5,14 @@
 // 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, normalizeGenerationMeta, stripGeneHints, } from '../wire/index.js';
+import { detectModelName } from '../bootstrap/envFingerprint.js';
+import { computeAssetId, validateWire, SCHEMA_VERSION, normalizeRoutingHint, normalizeToolPolicy, normalizeGenerationMeta, normalizeClaims, normalizeGeneScope, normalizeRuntimeProfile, normalizeVerifierProfile, stripGeneHints, ENV_CLASSES, } 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_';
+const LEGACY_CONVERSATION_ID_PREFIX = 'gene_conversation_';
 /**
  * True when a gene id is in the `gene_distilled_` namespace. NB this prefix is now a NAMESPACE marker, NOT a
  * provenance tag: v1 used it to mean "skill-derived" (auto-evolved genes were `gene_auto_`), but v2's intakeGene
@@ -51,7 +53,84 @@ function fnv1a(s) {
     }
     return (h >>> 0).toString(16).padStart(8, '0');
 }
+const nonEmptyModel = (v) => {
+    const t = (v ?? '').trim();
+    return t.length > 0 ? t.slice(0, 100) : undefined;
+};
 const clean = (xs) => (xs ?? []).map((s) => String(s).trim()).filter((s) => s.length > 0);
+/** Already-namespaced closed-constraint scope terms (kautoValidator.SCOPE_TERM prefixes). */
+const NAMESPACED_SCOPE = /^(?:repo|lineage|pkg|lang|framework|capability|tool|model|time|env):[A-Za-z0-9._@/:-]+$/;
+const VERSION_INTERVAL_SCOPE = /^[A-Za-z0-9._-]+@(?:[><=^~]{1,2})?\d[\w.*-]*(?:\s*-\s*\d[\w.*-]*)?$/;
+const PLACEHOLDER_VERIFIER = /^(?:node|python3?|ruby|deno|bun|go|java|npm|pnpm|yarn)\s+(?:--?v(?:ersion)?|-V)\s*$/i;
+const TRIVIAL_VERIFIER = /^(?:true|:|echo\b.*|exit\s+0)\s*$/i;
+/**
+ * Map free-text retrieval signals into the closed constraint language so scope containment is decidable.
+ * Already-namespaced terms and version intervals pass through; bare tokens become `capability:<token>`.
+ * Hard facets (`required:…`) keep the marker around the namespaced term.
+ */
+export function namespaceScopeSignals(signals) {
+    const out = [];
+    for (const raw of signals) {
+        const t = String(raw ?? '').trim();
+        if (!t)
+            continue;
+        const required = t.startsWith('required:');
+        const bare = required ? t.slice('required:'.length).trim() : t;
+        if (!bare)
+            continue;
+        const namespaced = (NAMESPACED_SCOPE.test(bare) || VERSION_INTERVAL_SCOPE.test(bare))
+            ? bare
+            : `capability:${bare.replace(/[^A-Za-z0-9._@/-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80)}`;
+        if (!namespaced || namespaced === 'capability:')
+            continue;
+        out.push(required ? `required:${namespaced}` : namespaced);
+    }
+    return out;
+}
+/** Detect a coarse env_class for runtime_profile from process env (CI → ci, else local). */
+export function detectEnvClass(env = process.env) {
+    const truthy = (v) => {
+        const t = (v ?? '').trim().toLowerCase();
+        return t !== '' && t !== '0' && t !== 'false' && t !== 'no';
+    };
+    if (truthy(env['CI']) || truthy(env['GITHUB_ACTIONS']) || truthy(env['GITLAB_CI'])
+        || truthy(env['BUILDKITE']) || truthy(env['CIRCLECI']) || truthy(env['TRAVIS'])) {
+        return 'ci';
+    }
+    if (truthy(env['EVOLVER_ENV_CLASS'])) {
+        const v = String(env['EVOLVER_ENV_CLASS']).trim().toLowerCase();
+        if (ENV_CLASSES.includes(v))
+            return v;
+    }
+    return 'local';
+}
+/**
+ * Honest defaults for K_auto coordinates the producer did not state. Never invents a coordinate from
+ * nothing: each default is grounded in fields the gene already carries (signals, model, validation).
+ */
+export function deriveDefaultKautoCoordinates(input) {
+    const claims = input.claims ?? (input.signals.length > 0
+        ? [{ predicate: 'output_contract', kind: 'behavioral' }]
+        : null);
+    const scope = input.scope ?? (() => {
+        const namespaced = namespaceScopeSignals(input.signals);
+        return namespaced.length > 0 ? { signals: namespaced } : null;
+    })();
+    const runtime_profile = input.runtime_profile ?? (input.modelName
+        ? { runtime: input.modelName, env_class: detectEnvClass(input.env) }
+        : null);
+    const verifier_profile = input.verifier_profile ?? (() => {
+        const cmds = input.validation.map((c) => String(c).trim()).filter(Boolean);
+        if (cmds.length === 0)
+            return null;
+        const substantive = cmds.find((c) => !PLACEHOLDER_VERIFIER.test(c) && !TRIVIAL_VERIFIER.test(c));
+        // Light distill validation deliberately keeps `node --version` for sandbox safety; the gene still
+        // passed through evolver's sandboxed validation gate, which is a real verifier identity (not a
+        // shell placeholder). Prefer a substantive command when present; else name the gate.
+        return { verifier: substantive ?? 'evolver-sandboxed-validation', decision: 'pass' };
+    })();
+    return { claims, scope, runtime_profile, verifier_profile };
+}
 /** 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());
@@ -84,14 +163,42 @@ export function intakeGene(candidate, existing = []) {
     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
+    // First-class EvoX hints (v1 PR #93): normalized so a candidate carrying them lands canonical, not dropped, and
     // absent when malformed/empty. The router / tool-gate reads absent === "no opinion".
     const routingHint = normalizeRoutingHint(candidate.routing_hint);
     const toolPolicy = normalizeToolPolicy(candidate.tool_policy);
-    // v2-delta provenance + quality metadata (v1 #302): normalized so a candidate carrying it lands canonical,
+    // Local provenance + quality metadata (v1 #302): normalized so a candidate carrying it lands canonical,
     // dropped to absent when malformed/no-recognized-source.
     const generationMeta = normalizeGenerationMeta(candidate.generation_meta);
+    // 只有调用方明确证明记录来自蒸馏时，才保留 intake 之前的会话命名空间。
+    // 这样既兼容重试和下游逻辑 ID 查询，也不允许任意调用方 ID 绕过 intake 的命名空间所有权规则。
+    const preservesLegacyConversationId = generationMeta?.source === 'distilled'
+        && typeof candidate.id === 'string'
+        && candidate.id.startsWith(LEGACY_CONVERSATION_ID_PREFIX);
+    const id = candidate.id && (candidate.id.startsWith(DISTILLED_ID_PREFIX) || preservesLegacyConversationId)
+        ? candidate.id : `${DISTILLED_ID_PREFIX}${fnv1a(signals.join('|'))}`;
+    // K_auto runtime coordinate. Explicit caller value wins; otherwise detect from the environment using the same
+    // producer the env fingerprint uses. 'unknown' means undetectable, so it is dropped rather than recorded (see
+    // GeneCandidate.model_name) — absent keeps meaning "not recorded", never "runtime is literally unknown".
+    const detectedModel = nonEmptyModel(candidate.model_name) ?? nonEmptyModel(detectModelName());
+    const modelName = detectedModel === 'unknown' ? undefined : detectedModel;
+    // First-class K_auto projection-key coordinates. Producer-supplied values win when they normalize; otherwise
+    // derive honest defaults grounded in signals/model/validation so forward intake can clear strict K_auto
+    // without fabricating coordinates from nothing. Still ride along in asset_id and strip before validateWire.
+    const validation = candidate.validation ? [...candidate.validation] : [];
+    const derived = deriveDefaultKautoCoordinates({
+        signals,
+        ...(modelName ? { modelName } : {}),
+        validation,
+        claims: normalizeClaims(candidate.claims),
+        scope: normalizeGeneScope(candidate.scope),
+        runtime_profile: normalizeRuntimeProfile(candidate.runtime_profile),
+        verifier_profile: normalizeVerifierProfile(candidate.verifier_profile),
+    });
+    const claims = derived.claims;
+    const scope = derived.scope;
+    const runtimeProfile = derived.runtime_profile;
+    const verifierProfile = derived.verifier_profile;
     const gene = {
         type: 'Gene',
         schema_version: SCHEMA_VERSION,
@@ -103,12 +210,17 @@ export function intakeGene(candidate, existing = []) {
             max_files: candidate.constraints?.max_files ?? DEFAULT_MAX_FILES,
             forbidden_paths: [...(candidate.constraints?.forbidden_paths ?? DEFAULT_FORBIDDEN_PATHS)],
         },
-        validation: candidate.validation ? [...candidate.validation] : [],
+        validation,
         summary: candidate.summary ?? `Strategy for: ${signals.slice(0, 3).join(', ')}`,
+        ...(modelName ? { model_name: modelName } : {}),
         ...(candidate.preconditions ? { preconditions: [...candidate.preconditions] } : {}),
         ...(routingHint ? { routing_hint: routingHint } : {}),
         ...(toolPolicy ? { tool_policy: toolPolicy } : {}),
         ...(generationMeta ? { generation_meta: generationMeta } : {}),
+        ...(claims ? { claims } : {}),
+        ...(scope ? { scope } : {}),
+        ...(runtimeProfile ? { runtime_profile: runtimeProfile } : {}),
+        ...(verifierProfile ? { verifier_profile: verifierProfile } : {}),
         asset_id: '',
     };
     // asset_id folds in the hints + generation_meta (intake's own canonical shape — gep-sdk canonicalize hashes every
@@ -116,11 +228,10 @@ export function intakeGene(candidate, existing = []) {
     // 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 / generation_meta 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.
+    // Structural gate validates the gep-sdk-known Gene shape. gep-sdk 1.13.0 made routing_hint/tool_policy plus the
+    // K_auto coordinates first-class, so stripGeneHints removes only local annotations (generation_meta/model_name)
+    // before the check. That keeps SDK constraints active for every first-class field while preserving local-only
+    // metadata in asset_id and in the returned gene.
     const v = validateWire(stripGeneHints(gene));
     if (!v.ok)
         return { ok: false, errors: v.errors };

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;
@@ -47,17 +48,35 @@ export interface GeneCandidateInput {
      * effect, so the factor is dormant until a caller injects the signal (default-off).
      */
     reuseAdjust?: number;
+    /**
+     * Soft preference for genes whose five K_auto coordinates are machine-decidable (decideKauto.inKauto).
+     * Assembly stamps this when the source record clears the strict predicate. SOFT only: it re-orders near-ties
+     * among already-admitted candidates and can NEVER resurrect a gene excluded by trust/review/ban. Absent/false
+     * → 0 contribution, so the historical catalogue (strict membership 0%) is not zero-scored.
+     */
+    kautoMember?: boolean;
     /**
      * Authoritative provenance tag from Gene.generation_meta.source. The legacy `gene_distilled_` prefix remains a
      * 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 +89,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).
      */
@@ -88,6 +108,8 @@ export interface ScoredCandidate {
     geneId: string;
     assetId?: string;
     score: number;
+    /** Internal expanded match in [0,1]; omitted from root-event candidate payloads. */
+    matchScore?: number;
     reasons: string[];
     health?: GeneHealth;
 }
@@ -114,6 +136,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 +181,68 @@ 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;
+/**
+ * Soft boost for strict K_auto members. Smaller than CONFIDENCE_WEIGHT: membership is a writer-side property,
+ * not verified cycle history, so it only breaks near-ties between already-eligible candidates.
+ */
+export declare const KAUTO_WEIGHT = 0.05;
 /**
  * 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.
+ * + CONFIDENCE_WEIGHT × confidence + REUSE_WEIGHT × reuse-sentiment + KAUTO_WEIGHT × kauto-member).
+ * 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-2,conf=0.15,memory=0.12,reuse=0.1)";
+export declare const LEGACY_SELECTION_WEIGHTS_VERSION = "sel-6-domain(gh-2,conf=0.15,memory=0.12,reuse=0.1,domain=0.08)";
+export declare const SELECTION_WEIGHTS_VERSION = "sel-7-idf-domain(gh-2,conf=0.15,memory=0.12,reuse=0.1,domain=0.08)";
+export interface KautoAblationPoolResult {
+    lambda: number;
+    ranking: Array<{
+        rank: number;
+        geneId: string;
+        assetId?: string;
+        score: number;
+        scoreBase: number;
+        kautoContribution: number;
+        kautoMember: boolean;
+    }>;
+    selectedGeneId: string | null;
+    selectedAssetId?: string;
+    scoreBaseMin: number;
+    scoreBaseMax: number;
+    scoreBaseMean: number;
+}
+export interface KautoAblationCompare {
+    lambdas: readonly number[];
+    pools: KautoAblationPoolResult[];
+    /** Pairs (baseline λ=0 vs each λ>0) where any gene's rank changed. */
+    rankChangesByLambda: Record<string, number>;
+    /** Pairs where the selected (top) gene changed vs λ=0. */
+    selectedChangesByLambda: Record<string, boolean>;
+    /** Pairs where the top-k set changed vs λ=0. */
+    topKChangesByLambda: Record<string, number>;
+    topK: number;
+}
+/**
+ * Offline λ ablation over an already-admitted candidate pool.
+ * Does not run hard gates / force / distilled fallback — those stay outside the soft preference.
+ * Pure ranking sensitivity for score_T2 = score_base + λ · 1[k_a ∈ K_auto].
+ */
+export declare function ablateKautoLambda(input: Pick<SelectionInput, 'signals' | 'candidates' | 'semanticCorpus' | 'disableSemanticIdf'>, lambdas?: readonly number[], opts?: {
+    topK?: number;
+    floor?: number;
+}): KautoAblationCompare;
+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 +250,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 {};