@evomap/evolver-adapter-public 2.0.0-beta.9 → 2.0.0

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',
@@ -33,10 +34,52 @@ const GENE_WIRE_KEYS = new Set([
     'generation_meta',
     'asset_id',
 ]);
+const HUB_DELIVERY_METADATA_KEYS = new Set([
+    'status',
+    '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',
+    'payload_backfill_reason',
+    'asset_type',
+    '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 +90,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 +183,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 +200,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 +246,15 @@ function stripHubPayloadMetadata(rec) {
     }
     return out;
 }
+function stripHubDeliveryMetadataForIntegrity(rec) {
+    const out = { ...rec };
+    for (const key of HUB_DELIVERY_METADATA_KEYS)
+        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 +276,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 } : {}),
     };
 }
@@ -179,6 +304,68 @@ export function toGeneCandidate(rec) {
         hubAsset: stripHubPayloadMetadata(rec),
     };
 }
+/**
+ * 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 } : {}),
+    };
+}
 /**
  * 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:
@@ -189,40 +376,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 +438,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 +463,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 +475,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 +489,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>;
+}

package/dist/learningPacketFeedback.js

@@ -0,0 +1,104 @@
+import { assertHubUrlSecure, isHubUnreachableError } from './hubFetch.js';
+import { learningOpsAuthHeaders } from './learningPacketSink.js';
+/** Hub appendLearningFeedbackSchema closed enums (evomap-hub src/schemas/learningOps.js). */
+export const LEARNING_FEEDBACK_TYPES = ['outcome', 'rating', 'correction', 'governance', 'note'];
+export const LEARNING_FEEDBACK_DECISIONS = [
+    'accepted', 'rejected', 'needs_redaction', 'not_training_eligible', 'training_candidate', 'note',
+];
+function pickString(record, key) {
+    const value = record[key];
+    if (value === null)
+        return null;
+    return typeof value === 'string' ? value : undefined;
+}
+async function failureReason(res) {
+    const text = await res.text().catch(() => '');
+    return `hub ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`;
+}
+/**
+ * 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 class HubLearningPacketFeedbackClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async submitFeedback(packetId, feedback) {
+        try {
+            const path = `/api/learning-packets/${encodeURIComponent(packetId)}/feedback`;
+            const url = `${this.opts.baseUrl}${path}`;
+            assertHubUrlSecure(url);
+            const headers = await learningOpsAuthHeaders(this.opts.auth, 'POST', path);
+            // Exactly the appendLearningFeedbackSchema fields (strict zod): optional keys are omitted, not nulled.
+            const res = await this.opts.fetchFn(url, {
+                method: 'POST',
+                headers,
+                redirect: 'manual',
+                body: JSON.stringify({
+                    decision: feedback.decision,
+                    ...(feedback.feedbackType !== undefined ? { feedbackType: feedback.feedbackType } : {}),
+                    ...(feedback.rating !== undefined ? { rating: feedback.rating } : {}),
+                    ...(feedback.scores !== undefined ? { scores: feedback.scores } : {}),
+                    ...(feedback.rationale !== undefined ? { rationale: feedback.rationale } : {}),
+                    ...(feedback.verifier !== undefined ? { verifier: feedback.verifier } : {}),
+                    ...(feedback.failureCategory !== undefined ? { failureCategory: feedback.failureCategory } : {}),
+                    ...(feedback.traceEventId !== undefined ? { traceEventId: feedback.traceEventId } : {}),
+                    ...(feedback.actorNodeId !== undefined ? { actorNodeId: feedback.actorNodeId } : {}),
+                }),
+            });
+            if (res.status === 201) {
+                const body = await res.json().catch(() => null);
+                const row = body && typeof body === 'object' ? body.feedback : undefined;
+                return { ok: true, ...(typeof row?.id === 'string' ? { feedbackId: row.id } : {}) };
+            }
+            return { ok: false, reason: await failureReason(res) };
+        }
+        catch (e) {
+            if (isHubUnreachableError(e))
+                return { ok: false, reason: 'hub_unreachable' };
+            return { ok: false, reason: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async getPacket(packetId) {
+        try {
+            const path = `/api/learning-packets/${encodeURIComponent(packetId)}`;
+            const url = `${this.opts.baseUrl}${path}`;
+            assertHubUrlSecure(url);
+            const headers = await learningOpsAuthHeaders(this.opts.auth, 'GET', path);
+            const res = await this.opts.fetchFn(url, { method: 'GET', headers, redirect: 'manual' });
+            if (res.status !== 200)
+                return { ok: false, reason: await failureReason(res) };
+            const body = await res.json().catch(() => null);
+            const packet = body && typeof body === 'object' ? body.packet : undefined;
+            if (!packet || typeof packet !== 'object' || Array.isArray(packet)) {
+                return { ok: false, reason: 'hub 200: response missing packet object' };
+            }
+            const record = packet;
+            if (typeof record['id'] !== 'string' || record['id'].length === 0) {
+                return { ok: false, reason: 'hub 200: packet missing id' };
+            }
+            return {
+                ok: true,
+                packet: {
+                    id: record['id'],
+                    ...(pickString(record, 'status') !== undefined && pickString(record, 'status') !== null ? { status: record['status'] } : {}),
+                    ...(pickString(record, 'outcomeStatus') !== undefined ? { outcomeStatus: pickString(record, 'outcomeStatus') } : {}),
+                    ...(pickString(record, 'verifier') !== undefined ? { verifier: pickString(record, 'verifier') } : {}),
+                    ...(pickString(record, 'trainingEligibilityStatus') !== undefined ? { trainingEligibilityStatus: pickString(record, 'trainingEligibilityStatus') } : {}),
+                    ...(pickString(record, 'governanceStatus') !== undefined ? { governanceStatus: pickString(record, 'governanceStatus') } : {}),
+                    ...(typeof record['trainingEligible'] === 'boolean' ? { trainingEligible: record['trainingEligible'] } : {}),
+                    ...(pickString(record, 'consentStatus') !== undefined ? { consentStatus: pickString(record, 'consentStatus') } : {}),
+                    ...(pickString(record, 'redactionStatus') !== undefined ? { redactionStatus: pickString(record, 'redactionStatus') } : {}),
+                    ...(pickString(record, 'retentionPolicy') !== undefined ? { retentionPolicy: pickString(record, 'retentionPolicy') } : {}),
+                },
+            };
+        }
+        catch (e) {
+            if (isHubUnreachableError(e))
+                return { ok: false, reason: 'hub_unreachable' };
+            return { ok: false, reason: e instanceof Error ? e.message : String(e) };
+        }
+    }
+}