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

package/dist/algo/orchestrator.d.ts

@@ -3,10 +3,14 @@ import type { ProvenanceStore } from '../assetstore/provenance.js';
 import type { ReviewLedger } from '../assetstore/reviewLedger.js';
 import type { GepCategory } from '../wire/index.js';
 import type { ProblemPattern } from '../schema/problem.js';
-import type { GeneCandidateInput } from './geneSelection.js';
+import type { GeneCandidateInput, SelectionGuardMode } from './geneSelection.js';
 import { CycleEngine, type CycleInput, type CycleResult, type SolidifyPermitGate } from './cycleEngine.js';
 import { type PendingSignalsContext } from '../assetstore/pendingSignals.js';
 import { type ReuseOutcomeSummary, type ReuseOutcomeEvent } from '../ops/reuseOutcomes.js';
+import type { MemoryGraphAdvice } from './memoryGraph.js';
+import type { SelectionPolicy } from './ucb1.js';
+import type { FrozenExecutionBinding } from '../exec/executionBinding.js';
+import type { CompatibilityEvidenceIndex } from '../modelCompatibility.js';
 export interface RunCycleOptions {
     cycleId: string;
     problem: ProblemPattern;
@@ -19,10 +23,18 @@ export interface RunCycleOptions {
     summary: string;
     confidence: number;
     selectionFloor?: number;
+    /** Emergency rollback for semantic IDF. Also skips pre-admission corpus collection. */
+    disableSemanticIdf?: boolean;
+    /** Experimental plateau policy. Omit for current engine-health + random drift behavior. */
+    selectionPolicy?: SelectionPolicy;
+    /** Versioned relevance-guard rollout. Omit for legacy direct-call behavior. */
+    selectionGuard?: SelectionGuardMode;
     /** Optional explicit gene chosen by GEP / an external runtime; forwarded to CycleEngine after assembly. */
     forcedGeneId?: string;
     /** The agent runtime's work: run the mutation, return the outcome. */
     execute: CycleInput['execute'];
+    /** Immutable external execution binding; omitted for legacy local cycles. */
+    executionBinding?: FrozenExecutionBinding;
     /** Optional triage context forwarded to CycleEngine for cycle.failed classification. */
     failureContext?: CycleInput['failureContext'];
     /** Optional adapter/runtime permit gate. Runs after execute succeeds and before solidify writes assets. */
@@ -60,6 +72,10 @@ export interface RunCycleOptions {
      * agent self-report) gains teeth on selection. Omit → no recall contribution. Never feeds quarantine.
      */
     recallEvents?: readonly ReuseOutcomeEvent[];
+    /** Scoped local MemoryGraph query result. Omit to keep selection unchanged. */
+    memoryGraphAdvice?: MemoryGraphAdvice;
+    /** Exact model compatibility evidence; quarantine decisions are removed before forced selection. */
+    compatibility?: CompatibilityEvidenceIndex;
 }
 /** Drive one full evolution cycle end-to-end: assemble candidates from the store, then run the cycle. */
 export declare function runEvolutionCycle(engine: CycleEngine, store: AssetStoreProvider, opts: RunCycleOptions): Promise<CycleResult>;

package/dist/algo/orchestrator.js

@@ -18,6 +18,12 @@ export async function runEvolutionCycle(engine, store, opts) {
             console.warn(`[ExplicitSignals] Failed to consume pending signals (non-fatal): ${message}`);
         }
     }
+    // Curriculum targets must be present before candidate assembly; injecting them only inside CycleEngine would
+    // be too late to recall a gene whose signals_match is curriculum_target:*. The engine repeats this enrichment
+    // for direct runCycle callers; the operation is deterministic and set-idempotent.
+    const baseSignals = signals;
+    const preparedCurriculum = engine.prepareCurriculumSignals(baseSignals);
+    const selectionSignals = preparedCurriculum.signals;
     // #268 phase 1 + #274 slice 3: fold cross-runtime reuse counts AND observed recall into the pool (soft re-order).
     // Absent both → no map → default-off. Recall is folded at a lower weight (RECALL_WEIGHT). Assembly sums a gene's
     // ids → sentiment; bounded + clamped in geneSelection; the hard trust/review/ban gates in assembly run first.
@@ -31,21 +37,39 @@ export async function runEvolutionCycle(engine, store, opts) {
         }
     }
     const asmOpts = {
+        includeSemanticCorpus: opts.disableSemanticIdf !== true,
         ...(opts.candidateLimit ? { limit: opts.candidateLimit } : {}),
         ...(opts.provenance ? { provenance: opts.provenance } : {}),
         ...(opts.review ? { review: opts.review } : {}),
         ...(opts.includeProbation ? { includeProbation: true } : {}),
         ...(opts.hubCandidates && opts.hubCandidates.length > 0 ? { hubCandidates: opts.hubCandidates } : {}),
         ...(reuseCounts.size > 0 ? { reuseCounts } : {}),
+        ...(opts.compatibility ? { compatibility: opts.compatibility } : {}),
     };
-    const { candidates, distilledFallback, antiWarnings } = await assembleSelectionPool(store, signals, asmOpts);
+    const { candidates: assembledCandidates, distilledFallback, semanticCorpus, antiWarnings } = await assembleSelectionPool(store, selectionSignals, asmOpts);
+    const memoryByGene = new Map((opts.memoryGraphAdvice?.genes ?? []).map((evidence) => [evidence.geneId, evidence]));
+    const candidates = assembledCandidates.map((candidate) => {
+        const evidence = memoryByGene.get(candidate.geneId) ?? (candidate.assetId ? memoryByGene.get(candidate.assetId) : undefined);
+        return evidence ? { ...candidate, memoryBoost: evidence.boost } : candidate;
+    });
+    const memoryDistilledFallback = distilledFallback.map((candidate) => {
+        const evidence = memoryByGene.get(candidate.geneId) ?? (candidate.assetId ? memoryByGene.get(candidate.assetId) : undefined);
+        return evidence ? { ...candidate, memoryBoost: evidence.boost } : candidate;
+    });
+    const memoryEligible = [...candidates, ...memoryDistilledFallback];
+    const memoryEvidence = opts.memoryGraphAdvice?.genes.filter((evidence) => memoryEligible.some((candidate) => candidate.geneId === evidence.geneId || candidate.assetId === evidence.geneId)).slice(0, 3) ?? [];
     return engine.runCycle({
         cycleId: opts.cycleId,
         problem: opts.problem,
-        signals,
+        signals: baseSignals,
+        curriculumSignals: preparedCurriculum.curriculumSignals,
         category: opts.category,
         ...(opts.strategyName !== undefined ? { strategyName: opts.strategyName } : {}),
         candidates,
+        semanticCorpus,
+        ...(opts.disableSemanticIdf ? { disableSemanticIdf: true } : {}),
+        ...(opts.selectionPolicy ? { selectionPolicy: opts.selectionPolicy } : {}),
+        ...(opts.selectionGuard ? { selectionGuard: opts.selectionGuard } : {}),
         target: opts.target,
         expectedEffect: opts.expectedEffect,
         summary: opts.summary,
@@ -53,11 +77,13 @@ export async function runEvolutionCycle(engine, store, opts) {
         ...(opts.selectionFloor !== undefined ? { selectionFloor: opts.selectionFloor } : {}),
         ...(opts.forcedGeneId !== undefined ? { forcedGeneId: opts.forcedGeneId } : {}),
         execute: opts.execute,
+        ...(opts.executionBinding !== undefined ? { executionBinding: opts.executionBinding } : {}),
         ...(opts.failureContext !== undefined ? { failureContext: opts.failureContext } : {}),
         ...(opts.solidifyPermit ? { solidifyPermit: opts.solidifyPermit } : {}),
         // #97: forward the distilled-gene fallback pool so a no-signal-match cycle reuses a distilled strategy
-        // (instead of a blind innovate) when nothing clears the floor.
-        ...(distilledFallback.length > 0 ? { distilledFallback } : {}),
+        // (instead of a blind innovate) when normal selection has no reusable positive choice.
+        ...(memoryDistilledFallback.length > 0 ? { distilledFallback: memoryDistilledFallback } : {}),
         ...(antiWarnings.length > 0 ? { antiWarnings } : {}),
+        ...(memoryEvidence.length > 0 ? { memoryEvidence } : {}),
     });
 }

package/dist/algo/publishEligibility.d.ts

@@ -0,0 +1,34 @@
+import { type GeneLearningView } from '../assetstore/learningHistory.js';
+import type { AssetStoreProvider } from '../assetstore/provider.js';
+export type PublishEligibilityReason = 'eligible' | 'no_proven_success';
+export interface GenePublishEvidence {
+    geneId: string;
+    /** Real, value-producing successes (inert zero-work successes excluded upstream). */
+    success: number;
+    failed: number;
+    inert: number;
+    total: number;
+    eligible: boolean;
+    reason: PublishEligibilityReason;
+}
+/**
+ * The single publish/upload eligibility predicate: a gene may be published iff
+ * it has at least one capsule with a `success` outcome.
+ *
+ * We count `success + inert`, NOT just `success`. aggregateLearningHistory
+ * demotes a `success` capsule that carries no `proof_of_work` to `inert`
+ * (#195), but the evox capsule builder (asset_builder.rs) does NOT emit
+ * `proof_of_work` — a genuine successful run surfaces there as `inert`. Gating
+ * publish on the proof-only `success` count would therefore block genes that
+ * actually succeeded in production. "Has a success outcome" is the honest bar
+ * for the publish gate; the proof/inert distinction stays where it belongs
+ * (success-rate, auto-promote), not here. A gene with only failures — or one
+ * never run at all — has `success + inert === 0` and is not publishable.
+ */
+export declare function isGenePublishEligible(view: Pick<GeneLearningView, 'success' | 'inert'>): boolean;
+/**
+ * Read-only: derive a gene's outcome evidence and whether it clears the publish
+ * bar. Returns `no_proven_success` for a gene the store has never seen succeed,
+ * so callers can surface a precise, self-serviceable reason.
+ */
+export declare function assessGenePublishEvidence(store: AssetStoreProvider, geneId: string): Promise<GenePublishEvidence>;

package/dist/algo/publishEligibility.js

@@ -0,0 +1,52 @@
+// Proven-success gate for publishing / uploading a gene (#581).
+//
+// A gene's `confidence` is minted from model self-report (solidify), text
+// completeness (conversationDistiller), or is absent (like) — none of which
+// prove the gene ever WORKED. Publishing such a gene to the market pairs it
+// with a capsule and lets the Hub quality gate reject it after a round-trip
+// ("never truly succeeded"). This predicate is the single, outcome-driven bar
+// every publish/upload surface routes through, so an unproven gene is stopped
+// locally with a clear reason instead of leaking to the Hub.
+//
+// Deliberately DISTINCT from `probationWouldPromote` (genePromotion.ts):
+// auto-promotion runs with NO human in the loop, so it demands a strong, clean
+// record (>= minSuccess successes AND zero failures). Publishing is human-
+// initiated, so the bar is only "has this gene truly succeeded at least once"
+// — a gene with many successes and one stray failure is still worth publishing,
+// and blocking it on `failed === 0` would be wrong.
+import { aggregateLearningHistory } from '../assetstore/learningHistory.js';
+/**
+ * The single publish/upload eligibility predicate: a gene may be published iff
+ * it has at least one capsule with a `success` outcome.
+ *
+ * We count `success + inert`, NOT just `success`. aggregateLearningHistory
+ * demotes a `success` capsule that carries no `proof_of_work` to `inert`
+ * (#195), but the evox capsule builder (asset_builder.rs) does NOT emit
+ * `proof_of_work` — a genuine successful run surfaces there as `inert`. Gating
+ * publish on the proof-only `success` count would therefore block genes that
+ * actually succeeded in production. "Has a success outcome" is the honest bar
+ * for the publish gate; the proof/inert distinction stays where it belongs
+ * (success-rate, auto-promote), not here. A gene with only failures — or one
+ * never run at all — has `success + inert === 0` and is not publishable.
+ */
+export function isGenePublishEligible(view) {
+    return view.success + (view.inert ?? 0) >= 1;
+}
+/**
+ * Read-only: derive a gene's outcome evidence and whether it clears the publish
+ * bar. Returns `no_proven_success` for a gene the store has never seen succeed,
+ * so callers can surface a precise, self-serviceable reason.
+ */
+export async function assessGenePublishEvidence(store, geneId) {
+    const view = await aggregateLearningHistory(store, geneId);
+    const eligible = isGenePublishEligible(view);
+    return {
+        geneId,
+        success: view.success,
+        failed: view.failed,
+        inert: view.inert ?? 0,
+        total: view.total,
+        eligible,
+        reason: eligible ? 'eligible' : 'no_proven_success',
+    };
+}

package/dist/algo/solidify.d.ts

@@ -1,6 +1,13 @@
 import { type Capsule } from '../wire/index.js';
-import type { ProofOfWork } from '../schema/proofOfWork.js';
+import { type ProofOfWork } from '../schema/proofOfWork.js';
 export type ResolutionStatus = 'pending' | 'suppressed_observationally' | 'resolved_by_evidence' | 'regressed' | 'inconclusive';
+export interface FailureEvidenceIdentityInput {
+    failureId?: string;
+    rootAttemptId?: string;
+    executionId?: string;
+    verifierDigest?: string;
+    artifactDigest?: string;
+}
 export interface SolidifyInput {
     geneId: string;
     trigger: readonly string[];
@@ -11,6 +18,8 @@ export interface SolidifyInput {
         score: number;
     };
     proofOfWork?: ProofOfWork;
+    /** Failure-threshold identity. Stored only for failed Capsules; retry roots dedupe automatic fan-out. */
+    failureIdentity?: FailureEvidenceIdentityInput;
     /** 是否有强证据(validation/测试在证据下通过). 默认 false → 不自动升级到 resolved. */
     strongEvidence?: boolean;
     /** regressed 判定阈: 失败且分低于此 → regressed, 否则 inconclusive. 默认 0.3. */
@@ -22,7 +31,7 @@ export interface SolidifyResult {
     producedValue: boolean;
     reasons: string[];
 }
-/** ProofOfWork 是否表明有实际产出(解锁非 coding agent, 批注#17/#19). */
+/** ProofOfWork 是否表明有实际产出(解锁非 coding agent, 批注#17/#19). #961: 兼容读 helper(snake_case 优先, 回退旧 camelCase 存量). */
 export declare function proofIndicatesOutput(p?: ProofOfWork): boolean;
 /**
  * 两级 resolution(M4A-8) + ProofOfWork 判价值(M4A-5):

package/dist/algo/solidify.js

@@ -1,17 +1,45 @@
 import { ulid as makeUlid } from 'ulid';
 import { computeAssetId, SCHEMA_VERSION } from '../wire/index.js';
-/** ProofOfWork 是否表明有实际产出(解锁非 coding agent, 批注#17/#19). */
+import { gitDiffOf, artifactHashOf, externalReceiptOf, toolCallTraceOf, proofOfWorkForWrite } from '../schema/proofOfWork.js';
+/** ProofOfWork 是否表明有实际产出(解锁非 coding agent, 批注#17/#19). #961: 兼容读 helper(snake_case 优先, 回退旧 camelCase 存量). */
 export function proofIndicatesOutput(p) {
     if (!p)
         return false;
     switch (p.kind) {
-        case 'git_diff': return (p.gitDiff?.files ?? 0) > 0 || (p.gitDiff?.lines ?? 0) > 0;
-        case 'artifact_hash': return Boolean(p.artifactHash?.sha256);
-        case 'external_receipt': return Boolean(p.externalReceipt?.receiptId);
-        case 'tool_call_trace': return (p.toolCallTrace?.calls ?? 0) > 0;
+        case 'git_diff': return (gitDiffOf(p)?.files ?? 0) > 0 || (gitDiffOf(p)?.lines ?? 0) > 0;
+        case 'artifact_hash': return Boolean(artifactHashOf(p)?.sha256);
+        case 'external_receipt': {
+            const r = externalReceiptOf(p);
+            return Boolean(r?.receipt_id ?? r?.receiptId);
+        }
+        case 'tool_call_trace': return (toolCallTraceOf(p)?.calls ?? 0) > 0;
         default: return false;
     }
 }
+function nonEmpty(s) {
+    return typeof s === 'string' && s.trim().length > 0 ? s.trim() : undefined;
+}
+function failureIdentityTrace(input) {
+    if (input.outcome.status !== 'failed' || !input.failureIdentity)
+        return undefined;
+    const trace = { stage: 'validate' };
+    const root = nonEmpty(input.failureIdentity.rootAttemptId);
+    const execution = nonEmpty(input.failureIdentity.executionId);
+    const failure = nonEmpty(input.failureIdentity.failureId);
+    const verifier = nonEmpty(input.failureIdentity.verifierDigest);
+    const artifact = nonEmpty(input.failureIdentity.artifactDigest);
+    if (root)
+        trace['root_attempt_id'] = root;
+    if (execution)
+        trace['execution_id'] = execution;
+    if (failure)
+        trace['failure_id'] = failure;
+    if (verifier)
+        trace['verifier_digest'] = verifier;
+    if (artifact)
+        trace['artifact_digest'] = artifact;
+    return Object.keys(trace).length > 1 ? [trace] : undefined;
+}
 /**
  * 两级 resolution(M4A-8) + ProofOfWork 判价值(M4A-5):
  * - 失败: 分 < 阈 → regressed, 否则 inconclusive.
@@ -44,7 +72,8 @@ export function solidify(input) {
     // (artifact_hash/external_receipt/tool_call_trace) gd is undefined and blast falls back to {0,0} — which here
     // means "blast unknown", NOT "no change". Consumers that read blast=0 as a no-op signal (e.g. cycleFailure's
     // local_gene_no_blast bucket) MUST first confirm the proof kind is git_diff; the cycleEngine guard does this.
-    const gd = input.proofOfWork?.kind === 'git_diff' ? input.proofOfWork.gitDiff : undefined;
+    const gd = input.proofOfWork?.kind === 'git_diff' ? gitDiffOf(input.proofOfWork) : undefined;
+    const identityTrace = failureIdentityTrace(input);
     const base = {
         type: 'Capsule',
         schema_version: SCHEMA_VERSION,
@@ -56,7 +85,8 @@ export function solidify(input) {
         blast_radius: { files: gd?.files ?? 0, lines: gd?.lines ?? 0 },
         outcome: input.outcome,
         resolution_status: status,
-        ...(input.proofOfWork ? { proof_of_work: input.proofOfWork } : {}),
+        ...(input.proofOfWork ? { proof_of_work: proofOfWorkForWrite(input.proofOfWork) } : {}),
+        ...(identityTrace ? { execution_trace: identityTrace } : {}),
     };
     const asset_id = computeAssetId(base);
     return { capsule: { ...base, asset_id }, resolutionStatus: status, producedValue, reasons };

package/dist/algo/ucb1.d.ts

@@ -0,0 +1,53 @@
+import type { RootEvent } from '../events/eventSchema.js';
+export declare const SELECTION_POLICIES: readonly ["engine-health", "ucb1-shadow", "ucb1"];
+export type SelectionPolicy = (typeof SELECTION_POLICIES)[number];
+export declare const UCB1_SELECTION_POLICY_VERSION = "ucb1-v1";
+export declare const UCB1_REWARD_POLICY_VERSION = "productive-binary-v1";
+export interface Ucb1ArmStats {
+    armId: string;
+    pulls: number;
+    completedPulls: number;
+    rewardSum: number;
+    meanReward: number;
+}
+export interface Ucb1History {
+    arms: ReadonlyMap<string, Ucb1ArmStats>;
+    /** Every non-ad-hoc decision counts immediately, including decisions whose terminal event is still pending. */
+    totalPulls: number;
+}
+export interface Ucb1Arm {
+    armId: string;
+    baseScore: number;
+    explorationEligible: boolean;
+    stats: Ucb1ArmStats;
+}
+export interface Ucb1Choice {
+    armId: string;
+    pulls: number;
+    completedPulls: number;
+    totalPulls: number;
+    meanReward: number;
+    /** Null represents the canonical +Infinity cold-start index without putting Infinity on the event wire. */
+    bonus: number | null;
+    /** Null represents the canonical +Infinity cold-start index without putting Infinity on the event wire. */
+    index: number | null;
+    coldStart: boolean;
+}
+export type Ucb1FallbackReason = 'empty_pool' | 'ineligible_arm' | 'missing_history';
+export interface Ucb1Decision {
+    choice: Ucb1Choice | null;
+    fallbackReason?: Ucb1FallbackReason;
+}
+/**
+ * Rebuild UCB1 state from the append-only root event log. Decisions are pulls immediately, so later readers no
+ * longer treat an in-flight arm as cold. The read-select-append sequence is not an atomic reservation across
+ * workers. A terminal event adds reward exactly once per cycle; duplicate rows collapse to their latest projection.
+ */
+export declare function deriveUcb1History(events: readonly RootEvent[]): Ucb1History;
+/** Combine current asset identity with legacy gene-only history when that bridge is unambiguous. */
+export declare function ucb1StatsForCandidate(history: Ucb1History, geneId: string, assetId?: string, includeLegacyGeneHistory?: boolean): Ucb1ArmStats;
+/**
+ * Canonical UCB1: mean reward + sqrt(2 ln(total pulls) / arm pulls). Cold arms have +Infinity and are ordered
+ * deterministically by base score then arm identity. The caller supplies only the already-gated exploration window.
+ */
+export declare function chooseUcb1Arm(arms: readonly Ucb1Arm[], historyTotalPulls: number): Ucb1Decision;

package/dist/algo/ucb1.js

@@ -0,0 +1,156 @@
+export const SELECTION_POLICIES = ['engine-health', 'ucb1-shadow', 'ucb1'];
+export const UCB1_SELECTION_POLICY_VERSION = 'ucb1-v1';
+export const UCB1_REWARD_POLICY_VERSION = 'productive-binary-v1';
+function nonEmptyString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function decisionProjection(event) {
+    if (event.type !== 'decision.gene_selected')
+        return undefined;
+    const payload = event.payload;
+    const cycleId = nonEmptyString(payload['cycleId']);
+    const geneId = nonEmptyString(payload['selectedGeneId']);
+    if (!cycleId)
+        return undefined;
+    if (!geneId || geneId === 'ad-hoc')
+        return { cycleId, decision: null };
+    return {
+        cycleId,
+        decision: { armId: nonEmptyString(payload['selectedAssetId']) ?? geneId },
+    };
+}
+function terminalReward(event) {
+    if (event.type !== 'cycle.failed' && event.type !== 'cycle.solidified')
+        return null;
+    const payload = event.payload;
+    const cycleId = nonEmptyString(payload['cycleId']);
+    if (!cycleId)
+        return null;
+    if (event.type === 'cycle.failed' || payload['producedValue'] === false)
+        return { cycleId, reward: 0 };
+    // Legacy solidified events predate producedValue. Preserve the existing confidence replay compatibility policy.
+    return { cycleId, reward: 1 };
+}
+/**
+ * Rebuild UCB1 state from the append-only root event log. Decisions are pulls immediately, so later readers no
+ * longer treat an in-flight arm as cold. The read-select-append sequence is not an atomic reservation across
+ * workers. A terminal event adds reward exactly once per cycle; duplicate rows collapse to their latest projection.
+ */
+export function deriveUcb1History(events) {
+    const cycles = new Map();
+    for (const event of events) {
+        const decision = decisionProjection(event);
+        // A restarted/re-emitted decision for the same cycleId begins a new pending lifecycle. Never let a terminal
+        // from the earlier lifecycle leak reward into this newer arm.
+        if (decision) {
+            if (decision.decision)
+                cycles.set(decision.cycleId, { decision: decision.decision });
+            else
+                cycles.delete(decision.cycleId);
+        }
+        const terminal = terminalReward(event);
+        if (terminal) {
+            const cycle = cycles.get(terminal.cycleId);
+            if (cycle)
+                cycle.reward = terminal.reward;
+        }
+    }
+    const mutable = new Map();
+    for (const cycle of cycles.values()) {
+        const current = mutable.get(cycle.decision.armId) ?? { pulls: 0, completedPulls: 0, rewardSum: 0 };
+        current.pulls += 1;
+        if (cycle.reward !== undefined) {
+            current.completedPulls += 1;
+            current.rewardSum += cycle.reward;
+        }
+        mutable.set(cycle.decision.armId, current);
+    }
+    const arms = new Map();
+    for (const [armId, stats] of mutable) {
+        arms.set(armId, {
+            armId,
+            ...stats,
+            meanReward: stats.completedPulls > 0 ? stats.rewardSum / stats.completedPulls : 0,
+        });
+    }
+    return { arms, totalPulls: cycles.size };
+}
+function emptyStats(armId) {
+    return { armId, pulls: 0, completedPulls: 0, rewardSum: 0, meanReward: 0 };
+}
+/** Combine current asset identity with legacy gene-only history when that bridge is unambiguous. */
+export function ucb1StatsForCandidate(history, geneId, assetId, includeLegacyGeneHistory = true) {
+    const armId = assetId ?? geneId;
+    const identities = assetId === undefined
+        ? [geneId]
+        : [...new Set([assetId, ...(includeLegacyGeneHistory ? [geneId] : [])])];
+    const matches = identities.map((identity) => history.arms.get(identity)).filter((stats) => stats !== undefined);
+    if (matches.length === 0)
+        return emptyStats(armId);
+    const pulls = matches.reduce((sum, stats) => sum + stats.pulls, 0);
+    const completedPulls = matches.reduce((sum, stats) => sum + stats.completedPulls, 0);
+    const rewardSum = matches.reduce((sum, stats) => sum + stats.rewardSum, 0);
+    return {
+        armId,
+        pulls,
+        completedPulls,
+        rewardSum,
+        meanReward: completedPulls > 0 ? rewardSum / completedPulls : 0,
+    };
+}
+function finiteBaseScore(value) {
+    return Number.isFinite(value) ? value : Number.NEGATIVE_INFINITY;
+}
+function finiteCount(value) {
+    return Number.isFinite(value) ? Math.min(Number.MAX_SAFE_INTEGER, Math.floor(Math.max(0, value))) : 0;
+}
+function finiteMeanReward(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
+}
+function saturatingCountSum(total, value) {
+    const count = finiteCount(value);
+    return total >= Number.MAX_SAFE_INTEGER - count ? Number.MAX_SAFE_INTEGER : total + count;
+}
+/**
+ * Canonical UCB1: mean reward + sqrt(2 ln(total pulls) / arm pulls). Cold arms have +Infinity and are ordered
+ * deterministically by base score then arm identity. The caller supplies only the already-gated exploration window.
+ */
+export function chooseUcb1Arm(arms, historyTotalPulls) {
+    if (arms.length === 0)
+        return { choice: null, fallbackReason: 'empty_pool' };
+    if (arms.some((arm) => !arm.explorationEligible))
+        return { choice: null, fallbackReason: 'ineligible_arm' };
+    const totalPulls = Math.max(1, finiteCount(historyTotalPulls), arms.reduce((sum, arm) => saturatingCountSum(sum, arm.stats.pulls), 0));
+    const ranked = arms.map((arm) => {
+        const pulls = finiteCount(arm.stats.pulls);
+        const meanReward = finiteMeanReward(arm.stats.meanReward);
+        const coldStart = pulls === 0;
+        const bonus = coldStart ? null : Math.sqrt((2 * Math.log(totalPulls)) / pulls);
+        const index = coldStart ? null : meanReward + bonus;
+        return { arm, pulls, meanReward, coldStart, bonus, index };
+    }).sort((left, right) => {
+        if (left.coldStart !== right.coldStart)
+            return left.coldStart ? -1 : 1;
+        if (left.index !== null && right.index !== null && left.index !== right.index)
+            return right.index - left.index;
+        const leftScore = finiteBaseScore(left.arm.baseScore);
+        const rightScore = finiteBaseScore(right.arm.baseScore);
+        return rightScore !== leftScore ? rightScore - leftScore : left.arm.armId.localeCompare(right.arm.armId);
+    });
+    const winner = ranked[0];
+    return {
+        choice: {
+            armId: winner.arm.armId,
+            pulls: winner.pulls,
+            completedPulls: finiteCount(winner.arm.stats.completedPulls),
+            totalPulls,
+            meanReward: winner.meanReward,
+            bonus: winner.bonus,
+            index: winner.index,
+            coldStart: winner.coldStart,
+        },
+    };
+}

package/dist/assetrepair/hubRejection.d.ts

@@ -0,0 +1,12 @@
+import type { RepairIssue } from './repair.js';
+/** Field-level issues reported by the Hub, keyed to the asset index they belong to (`-1` = bundle-level). */
+export interface HubRejectionReport {
+    issues: RepairIssue[];
+    /** Issues for one asset of the published bundle, by its position in `payload.assets`. */
+    byAssetIndex: Map<number, RepairIssue[]>;
+}
+export interface HubRejectionOptions {
+    /** The bundle's asset types in `payload.assets` order, so a `<type>_*` rule reason routes to its own asset. */
+    assetTypes?: readonly (string | undefined)[];
+}
+export declare function hubRejectionIssues(body: unknown, options?: HubRejectionOptions): HubRejectionReport;

package/dist/assetrepair/hubRejection.js

@@ -0,0 +1,109 @@
+const MAX_ISSUES = 50;
+const MAX_MESSAGE_CHARS = 300;
+const REASON_TOKEN = /^[a-z][a-z0-9_]*$/;
+const REASON_PREFIXES = [
+    { prefix: 'gene', assetType: 'Gene' },
+    { prefix: 'capsule', assetType: 'Capsule' },
+    { prefix: 'event', assetType: 'EvolutionEvent' },
+    { prefix: 'bundle' },
+];
+const REPAIRABLE_REASON_PATHS = new Map([
+    ['asset_id_verification_failed', 'asset_id'],
+    ['missing_asset_id', 'asset_id'],
+]);
+export function hubRejectionIssues(body, options = {}) {
+    const fieldReport = fieldLevelIssues(body);
+    if (fieldReport.issues.length > 0)
+        return fieldReport;
+    return ruleReasonIssues(body, options.assetTypes ?? []);
+}
+function fieldLevelIssues(body) {
+    const report = { issues: [], byAssetIndex: new Map() };
+    for (const raw of detailRows(body).slice(0, MAX_ISSUES)) {
+        const detail = asRecord(raw);
+        if (!detail)
+            continue;
+        const path = pathSegments(detail['path']);
+        const message = text(detail['message']) ?? text(detail['code']);
+        if (!message)
+            continue;
+        const issue = {
+            path: assetRelativePath(path),
+            keyword: text(detail['code']) ?? 'invalid',
+            message: message.slice(0, MAX_MESSAGE_CHARS),
+            source: 'hub',
+        };
+        report.issues.push(issue);
+        const index = assetIndex(path);
+        const bucket = report.byAssetIndex.get(index);
+        if (bucket)
+            bucket.push(issue);
+        else
+            report.byAssetIndex.set(index, [issue]);
+    }
+    return report;
+}
+function ruleReasonIssues(body, assetTypes) {
+    const report = { issues: [], byAssetIndex: new Map() };
+    const reason = ruleReason(body);
+    if (!reason)
+        return report;
+    const prefix = REASON_PREFIXES.find((entry) => reason.token.startsWith(`${entry.prefix}_`));
+    if (!prefix)
+        return report;
+    const issue = {
+        path: REPAIRABLE_REASON_PATHS.get(reason.token.slice(prefix.prefix.length + 1)) ?? '',
+        keyword: reason.token,
+        message: reason.message.slice(0, MAX_MESSAGE_CHARS),
+        source: 'hub',
+    };
+    const index = prefix.assetType === undefined ? -1 : assetTypes.indexOf(prefix.assetType);
+    report.issues.push(issue);
+    report.byAssetIndex.set(index, [issue]);
+    return report;
+}
+function ruleReason(body) {
+    const root = asRecord(body);
+    if (!root)
+        return undefined;
+    const payload = asRecord(root['payload']);
+    const raw = [root['error'], root['reason'], payload?.['error'], payload?.['reason']]
+        .map((candidate) => text(candidate))
+        .find((candidate) => candidate !== undefined);
+    if (!raw)
+        return undefined;
+    const token = raw.split(":", 1)[0]?.trim() ?? '';
+    return REASON_TOKEN.test(token) ? { token, message: raw } : undefined;
+}
+function detailRows(body) {
+    const root = asRecord(body);
+    if (!root)
+        return [];
+    const payload = asRecord(root['payload']);
+    for (const candidate of [root['details'], root['errors'], payload?.['details'], payload?.['errors']]) {
+        if (Array.isArray(candidate))
+            return candidate;
+    }
+    return [];
+}
+function pathSegments(value) {
+    if (!Array.isArray(value))
+        return typeof value === 'string' ? value.split('.') : [];
+    return value.filter((segment) => typeof segment === 'string' || typeof segment === 'number');
+}
+/** `['payload','assets',0,'constraints','forbidden_paths']` → `constraints.forbidden_paths`. */
+function assetRelativePath(path) {
+    const at = path.findIndex((segment) => typeof segment === 'number');
+    const tail = at >= 0 ? path.slice(at + 1) : path.filter((segment) => segment !== 'payload');
+    return tail.join('.');
+}
+function assetIndex(path) {
+    const found = path.find((segment) => typeof segment === 'number');
+    return typeof found === 'number' ? found : -1;
+}
+function text(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}

package/dist/assetrepair/index.d.ts

@@ -0,0 +1,2 @@
+export { repairAssetRecord, type RepairChange, type RepairIssue, type RepairOptions, type RepairReport, type RepairStatus, } from './repair.js';
+export { hubRejectionIssues, type HubRejectionReport } from './hubRejection.js';

package/dist/assetrepair/index.js

@@ -0,0 +1,2 @@
+export { repairAssetRecord, } from './repair.js';
+export { hubRejectionIssues } from './hubRejection.js';