@evomap/evolver-adapter-public 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/hubReuse.d.ts

@@ -5,6 +5,9 @@ type GeneCandidateInput = algo.GeneCandidateInput;
 export declare const SEARCH_CACHE_TTL_MS: number;
 export declare const SEARCH_CACHE_MAX = 200;
 export declare const PAYLOAD_CACHE_MAX = 100;
+export declare const SEMANTIC_SEARCH_LIMIT = 10;
+export declare const SEMANTIC_QUERY_MAX_TERMS = 12;
+export declare const SEMANTIC_QUERY_MAX_CHARS = 512;
 /** Default reuse mode (ported from v1): 'reference' injects the asset as a strong hint; 'direct' applies it. */
 export type ReuseMode = 'direct' | 'reference';
 export declare const DEFAULT_REUSE_MODE: ReuseMode;
@@ -12,8 +15,23 @@ export declare const DEFAULT_REUSE_MODE: ReuseMode;
 export declare function getMinReuseScore(env?: NodeJS.ProcessEnv): number;
 /** Reads EVOLVER_REUSE_MODE here (adapter concern). */
 export declare function getReuseMode(env?: NodeJS.ProcessEnv): ReuseMode;
+/** V1-compatible kill-switch. Semantic recall is on unless explicitly disabled. */
+export declare function isSemanticSearchEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Derive a bounded public semantic query from structured signal tags. Error signatures, paths, prose, and other
+ * unstructured values are excluded so the vector-search leg cannot become a side channel for local diagnostics.
+ */
+export declare function buildSemanticQuery(signals: readonly string[]): string;
 /** Stable signal fingerprint (ported from v1 _cacheKey: sort + join). */
 export declare function signalFingerprint(signals: readonly string[]): string;
+export declare const TASK_DOMAIN_SIGNAL_PREFIX: "task_domain:";
+/**
+ * Resolve the hub-side domain fence from this turn's signals. Exactly one domain is used and only
+ * when the turn is unambiguous: with two or more distinct task_domain:* signals the turn spans
+ * domains, and scoping recall to either one would hide the other's assets — so we return null and
+ * fall back to unscoped recall (today's behaviour).
+ */
+export declare function hubDomainFromSignals(signals: readonly string[]): string | null;
 /**
  * The two-layer reuse cache. Bounded + TTL'd, per-process. A search-cache hit means phase 1 makes ZERO hub
  * calls; a payload-cache hit means phase 3 makes ZERO hub calls. The clock is injected for deterministic tests.
@@ -32,6 +50,7 @@ export declare class ReuseCache {
     setPayload(assetId: string, payload: hub.AssetRecord): void;
     clear(): void;
 }
+export declare function stripHubDeliveryMetadataForIntegrity(rec: hub.AssetRecord): hub.AssetRecord;
 /**
  * Map a hub search row (AssetRecord with arbitrary quality fields) → the core's price-free HubMetadata.
  * Accepts both camelCase and the hub's snake_case (gdi_score / success_rate / reuse_count / ...). Drops any
@@ -55,6 +74,8 @@ export interface ReuseBeforeSolveOptions {
     searchLimit?: number;
     /** Reuse mode label carried into the result (direct/reference). */
     mode?: ReuseMode;
+    /** Environment snapshot for adapter-owned reuse settings and the semantic-search kill-switch. */
+    env?: NodeJS.ProcessEnv;
     /** Observability sink (asset-call log). Receives structured records; never throws. */
     log?: {
         append(entry: Record<string, unknown>): void;
@@ -97,6 +118,26 @@ export interface ReuseBeforeSolveResult {
     /** Why we didn't reuse, when action === 'solve-fresh' (no_signals / no_results / below_threshold). */
     reason?: string;
 }
+export interface HubMetadataSearchOptions {
+    /** Environment snapshot for the semantic-search kill-switch. */
+    env?: NodeJS.ProcessEnv;
+    /** Cap on the signal-search leg. The semantic leg keeps its own bounded limit. */
+    searchLimit?: number;
+}
+export interface HubMetadataSearchResult {
+    signals: string[];
+    fingerprint: string;
+    metadata: hub.HubMetadata[];
+    searchCached: boolean;
+    /** False when either free search leg failed. Incomplete results must never prove a miss. */
+    complete: boolean;
+    error?: unknown;
+}
+/**
+ * Run the complete free-search phase shared by reuse and economic miss probes. This function never performs the
+ * paid fetch. Only complete dual-leg results enter the cache, so a partial outage cannot become a verified miss.
+ */
+export declare function searchHubMetadata(cap: hub.HubCapability, cache: ReuseCache, signals: readonly string[], opts?: HubMetadataSearchOptions): Promise<HubMetadataSearchResult>;
 /**
  * The reuse-before-solve flow. Returns the single winner (already fetched) as a selection candidate, or a
  * solve-fresh verdict. Never throws on a hub error — reuse is an optimization, not a hard dependency:

package/dist/hubReuse.js

@@ -12,7 +12,8 @@
 //   - search cache: signal-fingerprint → phase-1 metadata (short TTL). Repeat signal set → ZERO hub calls.
 //   - payload cache: assetId → phase-3 payload (content-addressed, long/permanent, bounded LRU). A cached
 //     payload → ZERO fetch. Both clocks are injected so TTL/eviction is deterministic and testable.
-import { hub, algo } from '@evomap/evolver-core';
+import { createHash } from 'node:crypto';
+import { hub, algo, signals as signalNs, wire } from '@evomap/evolver-core';
 const { scoreSearchResults, decideReuse, DEFAULT_MIN_REUSE_SCORE, } = hub;
 const GENE_WIRE_KEYS = new Set([
     'type',
@@ -31,12 +32,68 @@ const GENE_WIRE_KEYS = new Set([
     'routing_hint',
     'tool_policy',
     'generation_meta',
+    // K_auto projection-key coordinates + runtime authorship (v2-delta; ride-along until gep-sdk 1.13).
+    'model_name',
+    'claims',
+    'scope',
+    'runtime_profile',
+    'verifier_profile',
     'asset_id',
 ]);
+const HUB_DELIVERY_METADATA_KEYS = new Set([
+    'status',
+    'trust_state',
+    'success_streak',
+    'reputation_score',
+    'gdi_score',
+    'gdi_score_mean',
+    'success_rate',
+    'reuse_count',
+    'ranking_score',
+    'credit_cost',
+    'source_node_id',
+    'fetched_at',
+    'receipt',
+    'hub_receipt',
+    'already_purchased',
+    '_semantic_similarity',
+    'semantic_similarity',
+    'similarity',
+    'semanticSimilarity',
+    '_search_score',
+    'search_score',
+    '_match_score',
+    'match_score',
+    '_retrieval_rank',
+    'retrieval_rank',
+    'payload_backfill_reason',
+    'original_asset_id',
+    'asset_type',
+    'local_id',
+    'source',
+    'bundle_id',
+    'callable',
+    'payload_ready',
+    'bundle_capsule',
+    'bundle_events',
+]);
 // ── Cache config (ported from v1 hubSearch.js) ───────────────────────────────
 export const SEARCH_CACHE_TTL_MS = 5 * 60 * 1000; // metadata is hot but staleable — short TTL
 export const SEARCH_CACHE_MAX = 200;
 export const PAYLOAD_CACHE_MAX = 100;
+export const SEMANTIC_SEARCH_LIMIT = 10;
+export const SEMANTIC_QUERY_MAX_TERMS = 12;
+export const SEMANTIC_QUERY_MAX_CHARS = 512;
+// Namespace filtering removes obviously private signal classes. The term allowlist below is still mandatory:
+// even a public namespace can contain an arbitrary user-controlled value that must not enter a logged GET URL.
+const PUBLIC_SEMANTIC_NAMESPACES = new Set(['area', 'cap', 'capability_gap', 'risk']);
+const PUBLIC_SEMANTIC_TERMS = new Set([
+    '401', '403', '404', '409', '429', '500', '502', '503', '504',
+    'auth', 'cache', 'capability_gap', 'code_review', 'concurrency', 'database', 'debugging', 'go',
+    'javascript', 'latency', 'memory', 'network', 'performance', 'python',
+    'rate_limit', 'reliability', 'retry', 'rust', 'security', 'testing', 'timeout',
+    'typescript',
+]);
 export const DEFAULT_REUSE_MODE = 'reference';
 /** Reads EVOLVER_MIN_REUSE_SCORE here (env is an ADAPTER concern — core never reads it). */
 export function getMinReuseScore(env = process.env) {
@@ -47,10 +104,74 @@ export function getMinReuseScore(env = process.env) {
 export function getReuseMode(env = process.env) {
     return String(env['EVOLVER_REUSE_MODE'] ?? DEFAULT_REUSE_MODE).toLowerCase() === 'direct' ? 'direct' : 'reference';
 }
+/** V1-compatible kill-switch. Semantic recall is on unless explicitly disabled. */
+export function isSemanticSearchEnabled(env = process.env) {
+    const value = String(env['HUBSEARCH_SEMANTIC'] ?? '').trim().toLowerCase();
+    return value !== '0' && value !== 'false';
+}
+/**
+ * Derive a bounded public semantic query from structured signal tags. Error signatures, paths, prose, and other
+ * unstructured values are excluded so the vector-search leg cannot become a side channel for local diagnostics.
+ */
+export function buildSemanticQuery(signals) {
+    const terms = [];
+    const seen = new Set();
+    for (const raw of signals) {
+        const signal = String(raw).trim();
+        const lower = signal.toLowerCase();
+        if (!signal || lower.startsWith('errsig:') || lower.startsWith('errsig_norm:') || lower.startsWith('recurring_errsig'))
+            continue;
+        const colon = signal.indexOf(':');
+        if (colon > 0 && !PUBLIC_SEMANTIC_NAMESPACES.has(lower.slice(0, colon)))
+            continue;
+        const candidate = (colon > 0 && colon < 30 ? signal.slice(colon + 1) : signal).trim().toLowerCase();
+        if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(candidate)
+            // Signals are user-controlled. Only a fixed public taxonomy may enter the GET query because URLs are
+            // commonly retained by Hub and reverse-proxy access logs. Unknown terms remain in the structured POST leg.
+            || !PUBLIC_SEMANTIC_TERMS.has(candidate)
+            || seen.has(candidate))
+            continue;
+        const nextLength = terms.length === 0 ? candidate.length : terms.join(' ').length + 1 + candidate.length;
+        if (nextLength > SEMANTIC_QUERY_MAX_CHARS)
+            break;
+        seen.add(candidate);
+        terms.push(candidate);
+        if (terms.length >= SEMANTIC_QUERY_MAX_TERMS)
+            break;
+    }
+    return terms.join(' ');
+}
 /** Stable signal fingerprint (ported from v1 _cacheKey: sort + join). */
 export function signalFingerprint(signals) {
     return [...signals].map((s) => String(s).trim()).filter(Boolean).sort().join('|');
 }
+export const TASK_DOMAIN_SIGNAL_PREFIX = signalNs.TASK_DOMAIN_SIGNAL_PREFIX;
+/**
+ * evolver domain slug → hub domain taxonomy (evomap-hub domainDetectionService VALID_DOMAINS).
+ * Only mapped slugs may ride the wire: the hub validates against its own taxonomy and silently
+ * ignores unknown values (fail-open), so an unmapped slug would just waste the fence. Slugs the
+ * hub has no counterpart for (pdf/mail/calendar) intentionally map to nothing.
+ */
+const HUB_DOMAIN_BY_SLUG = {
+    coding: 'software_engineering',
+    sql: 'software_engineering',
+    pptx: 'content_creation',
+    docx: 'content_creation',
+    xlsx: 'data_analysis',
+    marketing: 'marketing',
+};
+/**
+ * Resolve the hub-side domain fence from this turn's signals. Exactly one domain is used and only
+ * when the turn is unambiguous: with two or more distinct task_domain:* signals the turn spans
+ * domains, and scoping recall to either one would hide the other's assets — so we return null and
+ * fall back to unscoped recall (today's behaviour).
+ */
+export function hubDomainFromSignals(signals) {
+    const resolution = signalNs.resolveTaskDomainSignals(signals);
+    return resolution.status === 'resolved'
+        ? HUB_DOMAIN_BY_SLUG[resolution.slug] ?? null
+        : null;
+}
 /**
  * The two-layer reuse cache. Bounded + TTL'd, per-process. A search-cache hit means phase 1 makes ZERO hub
  * calls; a payload-cache hit means phase 3 makes ZERO hub calls. The clock is injected for deterministic tests.
@@ -76,10 +197,13 @@ export class ReuseCache {
             this.search.delete(key);
             return null;
         }
+        this.search.delete(key);
+        this.search.set(key, e);
         return e.value;
     }
     setSearch(key, value) {
-        if (this.search.size >= this.searchMax) {
+        const exists = this.search.delete(key);
+        if (!exists && this.search.size >= this.searchMax) {
             const oldest = this.search.keys().next().value;
             if (oldest !== undefined)
                 this.search.delete(oldest);
@@ -90,15 +214,19 @@ export class ReuseCache {
         const asset = this.payload.get(assetId) ?? null;
         if (!asset)
             return null;
-        if (assetMatchesId(asset, assetId))
+        if (assetMatchesId(asset, assetId)) {
+            this.payload.delete(assetId);
+            this.payload.set(assetId, asset);
             return asset;
+        }
         this.payload.delete(assetId);
         return null;
     }
     setPayload(assetId, payload) {
         if (!assetMatchesId(payload, assetId))
             return;
-        if (this.payload.size >= this.payloadMax) {
+        const exists = this.payload.delete(assetId);
+        if (!exists && this.payload.size >= this.payloadMax) {
             const oldest = this.payload.keys().next().value;
             if (oldest !== undefined)
                 this.payload.delete(oldest);
@@ -132,6 +260,20 @@ function stripHubPayloadMetadata(rec) {
     }
     return out;
 }
+// Shared content projection for by-id verification and sync quarantine classification.
+export function stripHubDeliveryMetadataForIntegrity(rec) {
+    const out = { ...rec };
+    for (const key of HUB_DELIVERY_METADATA_KEYS) {
+        // Hub ranking streak is metadata for Genes, while Capsule.success_streak is canonical content.
+        if (key === 'success_streak' && out['type'] === 'Capsule')
+            continue;
+        delete out[key];
+    }
+    // Hub ranking confidence is metadata for Genes, while Capsule.confidence is canonical content.
+    if (out['type'] === 'Gene')
+        delete out['confidence'];
+    return out;
+}
 /**
  * Map a hub search row (AssetRecord with arbitrary quality fields) → the core's price-free HubMetadata.
  * Accepts both camelCase and the hub's snake_case (gdi_score / success_rate / reuse_count / ...). Drops any
@@ -153,7 +295,9 @@ export function toHubMetadata(rec) {
         ...(num(r['gdi_score'] ?? r['gdiScore']) !== undefined ? { gdiScore: num(r['gdi_score'] ?? r['gdiScore']) } : {}),
         ...(num(r['success_rate'] ?? r['successRate']) !== undefined ? { successRate: num(r['success_rate'] ?? r['successRate']) } : {}),
         ...(num(r['reuse_count'] ?? r['reuseCount']) !== undefined ? { reuseCount: num(r['reuse_count'] ?? r['reuseCount']) } : {}),
-        ...(num(r['similarity'] ?? r['semanticSimilarity']) !== undefined ? { semanticSimilarity: num(r['similarity'] ?? r['semanticSimilarity']) } : {}),
+        ...(num(r['similarity'] ?? r['semantic_similarity'] ?? r['_semantic_similarity'] ?? r['semanticSimilarity']) !== undefined
+            ? { semanticSimilarity: num(r['similarity'] ?? r['semantic_similarity'] ?? r['_semantic_similarity'] ?? r['semanticSimilarity']) }
+            : {}),
         ...(updatedAt !== undefined ? { updatedAt } : {}),
     };
 }
@@ -165,6 +309,10 @@ export function toGeneCandidate(rec) {
     const signalsMatch = strArr(r['signals_match'] ?? r['signalsMatch']) ?? [];
     const reuseCount = num(r['reuse_count'] ?? r['reuseCount']) ?? 0;
     const generationSource = algo.geneGenerationSource(r, geneId);
+    // Project onto the wire allowlist first, then re-run strict K_auto on the same bytes selection
+    // will see. Soft-preference must not stamp membership from hub delivery metadata that strip drops.
+    const hubAsset = stripHubPayloadMetadata(rec);
+    const kautoMember = algo.decideKauto(hubAsset).inKauto;
     return {
         geneId,
         assetId,
@@ -176,7 +324,70 @@ export function toGeneCandidate(rec) {
         ...(typeof r['category'] === 'string' ? { category: r['category'] } : {}),
         ...(typeof r['summary'] === 'string' ? { summary: r['summary'] } : {}),
         ...(generationSource ? { generationSource } : {}),
-        hubAsset: stripHubPayloadMetadata(rec),
+        ...(kautoMember ? { kautoMember: true } : {}),
+        hubAsset,
+    };
+}
+/**
+ * Run the complete free-search phase shared by reuse and economic miss probes. This function never performs the
+ * paid fetch. Only complete dual-leg results enter the cache, so a partial outage cannot become a verified miss.
+ */
+export async function searchHubMetadata(cap, cache, signals, opts = {}) {
+    const signalList = signals.map((signal) => String(signal).trim()).filter(Boolean);
+    const fingerprint = signalFingerprint(signalList);
+    if (signalList.length === 0) {
+        return { signals: signalList, fingerprint, metadata: [], searchCached: false, complete: true };
+    }
+    const env = opts.env ?? process.env;
+    const semanticQuery = isSemanticSearchEnabled(env) ? buildSemanticQuery(signalList) : '';
+    const semanticActive = semanticQuery.length >= 3;
+    const semanticQueryDigest = semanticActive
+        ? createHash('sha256').update(semanticQuery).digest('hex')
+        : undefined;
+    // Domain fence: derived from the turn's own task_domain:* signals (never from prose), mapped to
+    // the hub taxonomy. Scopes the structured signal leg only — the semantic leg already carries its
+    // own allowlisted free-text and stays domain-agnostic as the discovery fallback.
+    const hubDomain = hubDomainFromSignals(signals);
+    const signalSearchLimit = opts.searchLimit ? opts.searchLimit : undefined;
+    const limitKey = signalSearchLimit === undefined ? 'all' : String(signalSearchLimit);
+    const domainKey = hubDomain === null ? '' : `:domain:${hubDomain}`;
+    const key = semanticQueryDigest
+        ? `semantic:${fingerprint}:${semanticQueryDigest}:limit:${limitKey}${domainKey}`
+        : `signals:${fingerprint}:limit:${limitKey}${domainKey}`;
+    const cached = cache.getSearch(key);
+    if (cached !== null) {
+        return { signals: signalList, fingerprint, metadata: cached, searchCached: true, complete: true };
+    }
+    // Enter a promise boundary before invoking an injected provider: interface implementations can still throw
+    // synchronously even though their declared return type is Promise, and reuse must remain best-effort.
+    const signalSearch = Promise.resolve().then(() => cap.search({
+        signalsAny: signalList,
+        ...(hubDomain !== null ? { domain: hubDomain } : {}),
+        ...(signalSearchLimit ? { limit: signalSearchLimit } : {}),
+    }));
+    const semanticSearch = semanticActive
+        ? Promise.resolve().then(() => cap.search({ text: semanticQuery, kind: 'Gene', limit: SEMANTIC_SEARCH_LIMIT }))
+        : Promise.resolve([]);
+    const [signalResult, semanticResult] = await Promise.allSettled([signalSearch, semanticSearch]);
+    const signalRows = signalResult.status === 'fulfilled' ? signalResult.value : [];
+    const semanticRows = semanticResult.status === 'fulfilled' ? semanticResult.value : [];
+    const failedSearch = signalResult.status === 'rejected'
+        ? signalResult
+        : semanticResult.status === 'rejected'
+            ? semanticResult
+            : undefined;
+    const metadata = mergeSearchRows(signalRows, semanticRows)
+        .map(toHubMetadata)
+        .filter((candidate) => candidate.assetId.length > 0);
+    if (!failedSearch)
+        cache.setSearch(key, metadata);
+    return {
+        signals: signalList,
+        fingerprint,
+        metadata,
+        searchCached: false,
+        complete: failedSearch === undefined,
+        ...(failedSearch ? { error: failedSearch.reason } : {}),
     };
 }
 /**
@@ -189,40 +400,58 @@ export function toGeneCandidate(rec) {
  * @param signals the local problem signals.
  */
 export async function reuseBeforeSolve(cap, cache, signals, opts = {}) {
-    const mode = opts.mode ?? getReuseMode();
-    const threshold = opts.threshold ?? getMinReuseScore();
+    const env = opts.env ?? process.env;
+    const mode = opts.mode ?? getReuseMode(env);
+    const threshold = opts.threshold ?? getMinReuseScore(env);
     const runId = opts.runId ?? null;
     const log = opts.log;
-    const signalList = signals.map((s) => String(s).trim()).filter(Boolean);
+    const searchResult = await searchHubMetadata(cap, cache, signals, {
+        env,
+        ...(opts.searchLimit ? { searchLimit: opts.searchLimit } : {}),
+    });
+    const { signals: signalList, fingerprint, metadata, searchCached, complete: searchComplete, error: searchFailure, } = searchResult;
     if (signalList.length === 0) {
         return { action: 'solve-fresh', mode, zeroHubCalls: true, reason: 'no_signals' };
     }
     // ── Phase 1: free search (signal fingerprint cache → ZERO hub calls on hit) ──
-    const key = signalFingerprint(signalList);
-    let metadata = cache.getSearch(key);
-    const searchCached = metadata !== null;
-    if (metadata === null) {
-        let rows = [];
-        try {
-            rows = await cap.search({ signalsAny: signalList, ...(opts.searchLimit ? { limit: opts.searchLimit } : {}) });
-        }
-        catch (e) {
-            log?.append({ run_id: runId, action: 'hub_search_miss', signals: signalList, reason: 'search_error', error: errMsg(e) });
-            return { action: 'solve-fresh', mode, zeroHubCalls: false, reason: 'search_error' };
-        }
-        metadata = rows.map(toHubMetadata).filter((m) => m.assetId.length > 0);
-        cache.setSearch(key, metadata);
+    const searchIncomplete = !searchComplete;
+    if (searchIncomplete && metadata.length === 0) {
+        log?.append({
+            run_id: runId,
+            action: 'hub_search_miss',
+            signals: signalList,
+            reason: 'search_error',
+            error: errMsg(searchFailure),
+        });
+        return { action: 'solve-fresh', mode, zeroHubCalls: false, reason: 'search_error' };
     }
     if (metadata.length === 0) {
-        log?.append({ run_id: runId, action: 'hub_search_miss', signals: signalList, reason: 'no_results', via: searchCached ? 'search_cached' : 'search' });
-        return { action: 'solve-fresh', mode, zeroHubCalls: searchCached, reason: 'no_results' };
+        const reason = searchIncomplete ? 'search_error' : 'no_results';
+        log?.append({
+            run_id: runId,
+            action: 'hub_search_miss',
+            signals: signalList,
+            reason,
+            via: searchCached ? 'search_cached' : 'search',
+            ...(searchIncomplete ? { error: errMsg(searchFailure) } : {}),
+        });
+        return { action: 'solve-fresh', mode, zeroHubCalls: searchCached, reason };
     }
     // ── Phase 2: PURE decision (core — no price) ──
     const ranked = scoreSearchResults(signalList, metadata, opts.now !== undefined ? { now: opts.now } : {});
     const decision = decideReuse(ranked, { threshold });
     if (decision.action === 'solve-fresh' || !decision.candidate) {
-        log?.append({ run_id: runId, action: 'hub_search_miss', signals: signalList, reason: 'below_threshold', candidates: metadata.length, threshold });
-        return { action: 'solve-fresh', mode, zeroHubCalls: searchCached, reason: 'below_threshold' };
+        const reason = searchIncomplete ? 'search_error' : 'below_threshold';
+        log?.append({
+            run_id: runId,
+            action: 'hub_search_miss',
+            signals: signalList,
+            reason,
+            candidates: metadata.length,
+            threshold,
+            ...(searchIncomplete ? { error: errMsg(searchFailure) } : {}),
+        });
+        return { action: 'solve-fresh', mode, zeroHubCalls: searchCached, reason };
     }
     // ── Phase 3: paid fetch for the ONE winner (payload cache → ZERO hub calls on hit) ──
     const winner = decision.candidate;
@@ -233,14 +462,14 @@ export async function reuseBeforeSolve(cap, cache, signals, opts = {}) {
     if (asset === null) {
         try {
             if (isAssetByIdFetcher(cap)) {
-                asset = await cap.fetchAssetById(winnerId);
+                asset = normalizeMatchedAssetId(await cap.fetchAssetById(winnerId), winnerId);
                 creditCost = asset?.['credit_cost'];
             }
             else {
                 const results = await cap.fetch({ signalsAny: signalList, limit: metadata.length });
                 // The paid fetch returns full payloads; select the winner by id (content-addressed match).
-                asset = results.find((a) => String(a['asset_id'] ?? '') === winnerId)
-                    ?? null;
+                const fetched = results.find((candidate) => assetMatchesId(candidate, winnerId));
+                asset = normalizeMatchedAssetId(fetched, winnerId);
                 // Economic receipt read-through (read-only): surface credit_cost if the hub attached one, never gate.
                 const carrier = results.credit_cost
                     ?? asset?.['credit_cost'];
@@ -258,7 +487,7 @@ export async function reuseBeforeSolve(cap, cache, signals, opts = {}) {
         payloadCached = false;
     }
     if (!asset) {
-        return { action: 'solve-fresh', mode, zeroHubCalls: searchCached, reason: 'fetch_empty' };
+        return { action: 'solve-fresh', mode, zeroHubCalls: false, reason: 'fetch_empty' };
     }
     const zeroHubCalls = searchCached && payloadCached;
     log?.append({
@@ -270,7 +499,7 @@ export async function reuseBeforeSolve(cap, cache, signals, opts = {}) {
     // payload/cache pull rather than a fresh LLM solve, so ≈0 here. Never lets an emission error break reuse.
     if (opts.onReuseHit) {
         try {
-            opts.onReuseHit({ assetId: winnerId, cycleId: opts.cycleId ?? '', signalFingerprint: key, fetchTokens: 0 });
+            opts.onReuseHit({ assetId: winnerId, cycleId: opts.cycleId ?? '', signalFingerprint: fingerprint, fetchTokens: 0 });
         }
         catch { /* emission must never break the reuse path */ }
     }
@@ -284,12 +513,78 @@ export async function reuseBeforeSolve(cap, cache, signals, opts = {}) {
         zeroHubCalls,
     };
 }
+function mergeSearchRows(signalRows, semanticRows) {
+    const merged = [];
+    const indexById = new Map();
+    for (const row of signalRows) {
+        const record = row;
+        const assetId = String(record['asset_id'] ?? record['assetId'] ?? '');
+        if (!assetId || indexById.has(assetId))
+            continue;
+        indexById.set(assetId, merged.length);
+        merged.push(row);
+    }
+    for (const row of semanticRows) {
+        const record = row;
+        const assetId = String(record['asset_id'] ?? record['assetId'] ?? '');
+        if (!assetId)
+            continue;
+        const existingIndex = indexById.get(assetId);
+        if (existingIndex === undefined) {
+            indexById.set(assetId, merged.length);
+            merged.push(row);
+            continue;
+        }
+        const similarity = num(record['similarity'] ?? record['semantic_similarity'] ?? record['_semantic_similarity'] ?? record['semanticSimilarity']);
+        if (similarity !== undefined) {
+            merged[existingIndex] = { ...merged[existingIndex], similarity };
+        }
+    }
+    return merged;
+}
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }
 function isAssetByIdFetcher(value) {
     return typeof value.fetchAssetById === 'function';
 }
+function normalizeMatchedAssetId(asset, assetId) {
+    if (!assetMatchesId(asset, assetId))
+        return null;
+    const record = asset;
+    if (typeof record['asset_id'] === 'string')
+        return asset;
+    const normalized = { ...record, asset_id: assetId };
+    if (record['assetId'] === assetId)
+        delete normalized['assetId'];
+    if (record['id'] === assetId)
+        delete normalized['id'];
+    return normalized;
+}
 export function assetMatchesId(asset, assetId) {
-    return Boolean(asset && asset.asset_id === assetId);
+    if (!asset)
+        return false;
+    const record = asset;
+    const canonicalAssetId = typeof record['asset_id'] === 'string' ? record['asset_id'] : undefined;
+    if (canonicalAssetId !== undefined && canonicalAssetId !== assetId)
+        return false;
+    const hasCamelAlias = typeof record['assetId'] === 'string';
+    if (canonicalAssetId === undefined && hasCamelAlias && record['assetId'] !== assetId)
+        return false;
+    if (canonicalAssetId === undefined && !hasCamelAlias && record['id'] !== assetId)
+        return false;
+    const content = { ...record };
+    if (record['assetId'] === assetId)
+        delete content['assetId'];
+    if (record['id'] === assetId)
+        delete content['id'];
+    try {
+        if (assetId.startsWith('sha256:') && !/^sha256:[0-9a-f]{64}$/.test(assetId))
+            return false;
+        const contentMatches = wire.computeAssetId(stripHubDeliveryMetadataForIntegrity(content)) === assetId;
+        return assetId.startsWith('sha256:') ? contentMatches : canonicalAssetId !== undefined || contentMatches;
+    }
+    catch {
+        return false;
+    }
 }

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export * from './antiAbuseTelemetry.js';
 export * from './offlinePermit.js';
 export * from './hubReuse.js';
 export * from './hubUrl.js';
+export * from './learningPacketSink.js';
+export * from './learningPacketFeedback.js';
 export * from './atp.js';
 export * from './pricing/modelPrices.js';
 export * from './connect.js';

package/dist/index.js

@@ -14,6 +14,8 @@ export * from './antiAbuseTelemetry.js';
 export * from './offlinePermit.js';
 export * from './hubReuse.js';
 export * from './hubUrl.js';
+export * from './learningPacketSink.js';
+export * from './learningPacketFeedback.js';
 export * from './atp.js';
 export * from './pricing/modelPrices.js';
 export * from './connect.js';

package/dist/learningPacketFeedback.d.ts

@@ -0,0 +1,68 @@
+import type { hub } from '@evomap/evolver-core';
+import { type FetchLike } from './hubFetch.js';
+/** Hub appendLearningFeedbackSchema closed enums (evomap-hub src/schemas/learningOps.js). */
+export declare const LEARNING_FEEDBACK_TYPES: readonly ["outcome", "rating", "correction", "governance", "note"];
+export type LearningFeedbackType = (typeof LEARNING_FEEDBACK_TYPES)[number];
+export declare const LEARNING_FEEDBACK_DECISIONS: readonly ["accepted", "rejected", "needs_redaction", "not_training_eligible", "training_candidate", "note"];
+export type LearningFeedbackDecision = (typeof LEARNING_FEEDBACK_DECISIONS)[number];
+export interface LearningPacketFeedbackInput {
+    /** Default hub-side: 'outcome'. */
+    feedbackType?: LearningFeedbackType;
+    decision: LearningFeedbackDecision;
+    /** 0..1 (hub-validated). */
+    rating?: number;
+    scores?: Record<string, unknown>;
+    rationale?: string;
+    /** Hub VERIFIERS enum member (e.g. 'automated_test', 'human'). */
+    verifier?: string;
+    /** Hub FAILURE_CATEGORIES enum member. */
+    failureCategory?: string;
+    /** Anchor the feedback to one trace event instead of the whole packet. */
+    traceEventId?: string;
+    actorNodeId?: string;
+}
+export type LearningFeedbackResult = {
+    ok: true;
+    feedbackId?: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Server-managed governance/eligibility state read back from GET /api/learning-packets/:id. */
+export interface LearningPacketStatus {
+    id: string;
+    status?: string;
+    outcomeStatus?: string | null;
+    verifier?: string | null;
+    /** LearningOpsTrainingEligibility mirror: pending/eligible/ineligible/revoked/expired. */
+    trainingEligibilityStatus?: string | null;
+    /** pending/approved/blocked/purge_requested. */
+    governanceStatus?: string | null;
+    trainingEligible?: boolean;
+    consentStatus?: string | null;
+    redactionStatus?: string | null;
+    retentionPolicy?: string | null;
+}
+export type LearningPacketReadResult = {
+    ok: true;
+    packet: LearningPacketStatus;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface HubLearningPacketFeedbackClientOptions {
+    baseUrl: string;
+    auth: hub.AuthProvider;
+    fetchFn: FetchLike;
+}
+/**
+ * Feedback append + packet governance read-back against the hub Learning Ops API. Best-effort by the
+ * same contract as HubLearningPacketSink: this is observability/ops tooling, so every failure —
+ * network, auth, 4xx/5xx, unparseable body — returns { ok:false, reason } and never throws.
+ */
+export declare class HubLearningPacketFeedbackClient {
+    private readonly opts;
+    constructor(opts: HubLearningPacketFeedbackClientOptions);
+    submitFeedback(packetId: string, feedback: LearningPacketFeedbackInput): Promise<LearningFeedbackResult>;
+    getPacket(packetId: string): Promise<LearningPacketReadResult>;
+}