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

package/dist/hubCapability.js

@@ -1,15 +1,17 @@
-import { hub as hubNs } from '@evomap/evolver-core';
+import { createHash } from 'node:crypto';
+import { bootstrap, hub as hubNs, signals, wire } from '@evomap/evolver-core';
 import { AuthError, HubFetch, HubClientError, isHubUnreachableError } from './hubFetch.js';
 import { isNodeSecret, parseNodeSecretVersion } from './auth/legacyShim.js';
-import { inboundToAgentEvent, agentEventToOutbound, publishRespToReceipt, searchQueryToFetchWire } from './wireMap.js';
+import { inboundToAgentEvent, agentEventToOutbound, publishRespToReceipt, searchQueryToFetchWire, searchQueryToSearchOnlyWire, } from './wireMap.js';
 import { antiAbuseTelemetryMode, buildHeartbeatAntiAbuseTelemetry, } from './antiAbuseTelemetry.js';
 import { getWorkspaceKeychainMode } from './auth/workspaceKeychain.js';
 import { agentDirectoryFailure, parsePublicAgentPage, parsePublicAgentProfile, paginatePublicAgentPage, mergePublicAgentPages, publicAgentSearchQuery, publicTaskDiscoveryQuery, PUBLIC_TASK_DISCOVERY_MAX_CANDIDATES, unsupportedPublicAvailability, unsupportedPublicSort, withDirectoryTimeout, } from './agentDirectory.js';
+import { assetMatchesId, stripHubDeliveryMetadataForIntegrity } from './hubReuse.js';
 export const INBOUND_LIMIT = 100;
 export const OUTBOUND_MAX_BATCH = 50;
 export const OUTBOUND_MAX_BODY_BYTES = 4 * 1024 * 1024;
 export const PUBLIC_PROTOCOL_VERSION = 'gep-a2a/1.0.0';
-export const PUBLIC_HUB_CAPABILITIES = ['publish', 'fetch', 'search', 'task', 'mailbox', 'auth', 'marketplace', 'economy', 'questions', 'recipes', 'agent_directory'];
+export const PUBLIC_HUB_CAPABILITIES = ['publish', 'fetch', 'search', 'task', 'mailbox', 'auth', 'marketplace', 'economy', 'questions', 'recipes', 'agent_directory', 'learning_assets'];
 const QUESTION_SUBMIT_FAST_PATH_BYPASS_CONTENT_HASH = 'sha256:0000000000000000000000000000000000000000000000000000000000000000';
 const DRY_RUN_RECIPE_ID = 'dry-run-recipe';
 const HUB_DRY_RUN_VALUES = new Set(['1', 'true', 'yes', 'on']);
@@ -18,14 +20,29 @@ const HUB_DRY_RUN_VALUES = new Set(['1', 'true', 'yes', 'on']);
 // equals what the hub will KEEP.
 export const USED_ASSET_IDS_MAX = 50;
 export const USED_ASSET_ID_MAX_LEN = 200;
+export const LEARNING_ASSET_IDS_MAX = 50;
+export const LEARNING_ASSET_ID_MAX_LEN = 128;
+export class MalformedAccountAssetPageError extends Error {
+    constructor() {
+        super('Hub account asset page is malformed');
+        this.name = 'MalformedAccountAssetPageError';
+    }
+}
 /** 完整 GEP-A2A 信封(实测 dev: publish/fetch/validate 等协议消息端点必须全信封, 非仅 protocol+message_type). */
-export function gepEnvelope(messageType, payload) {
+export function gepEnvelope(messageType, payload, options = {}) {
     return {
         protocol: 'gep-a2a', protocol_version: '1.0.0', message_type: messageType,
-        message_id: `msg_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`,
+        message_id: options.messageId ?? `msg_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`,
         timestamp: new Date().toISOString(), payload,
     };
 }
+function stablePublishMessageId(idempotencyKey) {
+    const digest = createHash('sha256')
+        .update(idempotencyKey.trim())
+        .digest('hex')
+        .slice(0, 40);
+    return `msg_idem_${digest}`;
+}
 // v1 a2aProtocol.js L1999-2003: the three app-level rejection reasons that mean
 // our cached node_secret has DIVERGED from the hub's record (hub-side reset,
 // restored-from-backup machine, manual unlink) — not a transport/generic failure.
@@ -83,18 +100,38 @@ export class PublicHubCapability {
     auth;
     recipes = {
         create: async (request) => this.createRecipe(request),
-        publish: async (recipeId) => this.publishRecipe(recipeId),
+        publish: async (recipeId, options) => this.publishRecipe(recipeId, options),
         get: async (recipeId) => this.getRecipe(recipeId),
         express: async (recipeId, request = {}) => this.expressRecipe(recipeId, request),
+        search: async (request = {}) => this.searchRecipes(request),
+        list: async (request = {}) => this.listRecipes(request),
     };
     constructor(opts) {
         this.opts = opts;
         this.auth = opts.auth;
         this.http = new HubFetch({ baseUrl: opts.baseUrl, auth: opts.auth, fetchFn: opts.fetchFn, senderId: opts.senderId });
     }
+    evolverVersionForWire(explicitVersion) {
+        const antiAbuse = this.opts.antiAbuse;
+        return bootstrap.normalizeEvolverVersion(explicitVersion !== undefined
+            ? explicitVersion
+            : antiAbuse?.evolverVersion ?? antiAbuse?.envFingerprint?.evolver_version);
+    }
+    envFingerprintForWire(evolverVersion) {
+        const fingerprint = {
+            ...(this.opts.antiAbuse?.envFingerprint
+                ?? bootstrap.captureEnvFingerprint({ env: this.opts.antiAbuse?.env ?? process.env })),
+        };
+        if (evolverVersion)
+            fingerprint.evolver_version = evolverVersion;
+        else
+            delete fingerprint.evolver_version;
+        return fingerprint;
+    }
     async hello(opts) {
         try {
             const sender = this.opts.senderId();
+            const evolverVersion = this.evolverVersionForWire(opts.evolverVersion);
             const body = await this.http.call('POST', '/a2a/hello', gepEnvelope('hello', {
                 rotate_secret: opts.rotate,
                 capabilities: { supported_types: ['publish', 'fetch', 'mailbox', 'questions'] },
@@ -102,7 +139,12 @@ export class PublicHubCapability {
                 status: 'active',
                 timestamp: new Date().toISOString(),
                 ...(sender ? { node_id: sender } : {}),
-                ...(opts.evolverVersion ? { evolver_version: opts.evolverVersion } : {}),
+                ...(evolverVersion ? { evolver_version: evolverVersion } : {}),
+                // v1 parity (a2aProtocol.js buildHello): every hello carries the env fingerprint — it is how the
+                // hub builds node/IP trust for its anti-abuse layer. v2 had moved it to heartbeat-only meta, which
+                // one-shot CLI paths never send; the hub then answers heartbeats with resend_hello
+                // `missing_env_fingerprint` and 403-antibodies /a2a/fetch (#555).
+                env_fingerprint: this.envFingerprintForWire(evolverVersion),
             }));
             const payload = asRecord(body['payload']) ?? body;
             const retryAfterMs = numberField(payload, 'retry_after_ms') ?? numberField(payload, 'retryAfterMs');
@@ -115,10 +157,12 @@ export class PublicHubCapability {
             // cleanly; retrying with the diverged secret never can. Signals the caller NOT to arm reauth
             // backoff. Only legacy node_secret auth exposes this hook — enterprise_token is a no-op.
             if (isSecretDivergenceRejection(body, payload)) {
-                this.auth.notifyNodeSecretDiverged?.();
+                if (!opts.preserveCredentials) {
+                    this.auth.notifyNodeSecretDiverged?.();
+                }
                 return {
                     ok: false,
-                    error: 'secret_diverged_cleared',
+                    error: opts.preserveCredentials ? 'secret_diverged' : 'secret_diverged_cleared',
                     secretDiverged: true,
                     ...(rateLimitUntilMs !== undefined ? { rateLimitUntilMs } : {}),
                     ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
@@ -134,15 +178,21 @@ export class PublicHubCapability {
                 ?? this.opts.senderId();
             const nodeSecret = stringField(payload, 'node_secret') ?? stringField(payload, 'nodeSecret');
             const nodeSecretVersion = parseNodeSecretVersion(payload['node_secret_version'] ?? payload['nodeSecretVersion']);
-            if (nodeSecret && isNodeSecret(nodeSecret)) {
-                this.auth.adoptNodeSecret?.(nodeSecret, nodeSecretVersion);
-            }
-            else {
-                this.auth.adoptNodeSecretVersion?.(nodeSecretVersion);
+            const claimCode = stringField(payload, 'claim_code') ?? stringField(payload, 'claimCode');
+            const claimUrl = stringField(payload, 'claim_url') ?? stringField(payload, 'claimUrl');
+            if (!opts.preserveCredentials) {
+                if (nodeSecret && isNodeSecret(nodeSecret)) {
+                    this.auth.adoptNodeSecret?.(nodeSecret, nodeSecretVersion);
+                }
+                else {
+                    this.auth.adoptNodeSecretVersion?.(nodeSecretVersion);
+                }
             }
             return {
                 ok: payload['ok'] !== false && Boolean(nodeId),
                 ...(nodeId ? { nodeId } : {}),
+                ...(claimCode ? { claimCode } : {}),
+                ...(claimUrl ? { claimUrl } : {}),
                 ...(nodeSecretVersion !== undefined ? { nodeSecretVersion } : {}),
                 ...(rateLimitUntilMs !== undefined ? { rateLimitUntilMs } : {}),
                 ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
@@ -161,12 +211,13 @@ export class PublicHubCapability {
     async heartbeat(opts = {}) {
         try {
             const nodeSecretVersion = this.auth.getNodeSecretVersion?.();
-            const meta = this.heartbeatMeta(opts, nodeSecretVersion);
+            const evolverVersion = this.evolverVersionForWire(opts.evolverVersion);
+            const meta = this.heartbeatMeta(evolverVersion, nodeSecretVersion);
             const body = await this.http.call('POST', '/a2a/heartbeat', {
                 ...(this.opts.senderId() ? { node_id: this.opts.senderId() } : {}),
                 timestamp: new Date().toISOString(),
                 status: 'active',
-                ...(opts.evolverVersion ? { evolver_version: opts.evolverVersion } : {}),
+                ...(evolverVersion ? { evolver_version: evolverVersion } : {}),
                 ...(opts.lastUpdate ? { last_update: opts.lastUpdate } : {}),
                 ...(nodeSecretVersion !== undefined ? { node_secret_version: nodeSecretVersion } : {}),
                 ...(meta ? { meta } : {}),
@@ -183,7 +234,7 @@ export class PublicHubCapability {
             throw err;
         }
     }
-    heartbeatMeta(opts, nodeSecretVersion) {
+    heartbeatMeta(evolverVersion, nodeSecretVersion) {
         const meta = {};
         if (nodeSecretVersion !== undefined)
             meta['node_secret_version'] = nodeSecretVersion;
@@ -193,7 +244,7 @@ export class PublicHubCapability {
                 meta['anti_abuse'] = buildHeartbeatAntiAbuseTelemetry({
                     ...antiAbuse,
                     nodeId: this.opts.senderId(),
-                    evolverVersion: opts.evolverVersion,
+                    evolverVersion,
                 });
             }
             catch (err) {
@@ -204,15 +255,29 @@ export class PublicHubCapability {
         }
         return Object.keys(meta).length > 0 ? meta : undefined;
     }
-    async publish(bundle) {
+    async publish(bundle, options = {}) {
+        const normalizedIdempotencyKey = options.idempotencyKey?.trim();
+        if (options.idempotencyKey !== undefined && !normalizedIdempotencyKey) {
+            return {
+                receiptId: 'local_invalid_idempotency_key',
+                status: 'rejected',
+                terminal: true,
+                reason: 'publish idempotency key must not be blank',
+            };
+        }
         try {
             // 公版 /a2a/publish 收 payload.assets=[Gene,Capsule,(Event)] 捆绑(实测 dev).
-            const body = await this.http.call('POST', '/a2a/publish', gepEnvelope('publish', { assets: bundle }));
+            const idempotencyKey = normalizedIdempotencyKey;
+            const messageId = idempotencyKey !== undefined
+                ? stablePublishMessageId(idempotencyKey)
+                : undefined;
+            const body = await this.http.call('POST', '/a2a/publish', gepEnvelope('publish', { assets: bundle }, messageId ? { messageId } : {}));
             return publishRespToReceipt(200, body);
         }
         catch (e) {
-            if (e instanceof HubClientError)
-                return publishRespToReceipt(e.status, e.body ?? {});
+            if (e instanceof HubClientError) {
+                return publishRespToReceipt(e.status, e.body ?? {}, e.retryAfterMs);
+            }
             throw e; // 5xx/网络 → 重试
         }
     }
@@ -221,29 +286,79 @@ export class PublicHubCapability {
         // /a2a/fetch responses are FULL GEP envelopes (buildResponse('fetch', …)); the rows live at payload.results,
         // NOT at the top level. Reading body.results here always yielded [] — every fetch silently returned nothing.
         const body = await this.http.call('POST', '/a2a/fetch', gepEnvelope('fetch', searchQueryToFetchWire(query)));
-        return (body.payload?.results ?? []);
+        return assetsFromBody(body);
     }
-    async fetchAssetById(assetId) {
+    /**
+     * Fetch one asset AND say why, when the answer is not an asset. `fetchAssetById` collapses every outcome to
+     * `null`, so a caller could not tell "the hub does not have this" from "the hub delivered something the
+     * client refuses" — and the CLI reported both as `not_found` on assets that demonstrably exist (#964).
+     */
+    async fetchAssetDeliveryById(assetId, options) {
         const id = assetId.trim();
         if (!id)
-            return null;
+            return { status: 'absent' };
         const body = await this.http.call('POST', '/a2a/fetch', gepEnvelope('fetch', { asset_ids: [id] }));
-        return assetsFromBody(body).find((asset) => assetMatchesId(asset, id)) ?? null;
+        const matches = [];
+        for (const row of assetCandidatesFromBody(body)) {
+            const asset = unwrapFetchDeliveryRow(row);
+            if (!fetchDeliveryIdentityConsistent(row, asset))
+                return { status: 'rejected', reason: 'identity_mismatch' };
+            if (isContentAssetIdRequest(id)) {
+                // Identity is what this gate is for: the delivery must bind the REQUESTED content id through its own
+                // canonical `asset_id`. Whether the delivered body then hashes to that id, or satisfies the wire schema,
+                // is a trust question the caller resolves (quarantine + repair) — not grounds to drop the asset here.
+                if (!assetMatchesId(asset, id) && stringField(asset, 'asset_id') !== id) {
+                    return { status: 'rejected', reason: 'identity_mismatch' };
+                }
+                if (isRevokedFetchDelivery(row))
+                    return { status: 'rejected', reason: 'revoked' };
+                matches.push(asset);
+                continue;
+            }
+            if (fetchResultMatchesId(asset, id)) {
+                if (isRevokedFetchDelivery(row))
+                    return { status: 'rejected', reason: 'revoked' };
+                matches.push(asset);
+            }
+        }
+        if (matches.length === 0)
+            return { status: 'absent' };
+        const result = unambiguousFetchResult(matches);
+        if (!result)
+            return { status: 'rejected', reason: 'ambiguous' };
+        // Logical-id lookups retain their historical matching semantics. Only a canonical sha256 lookup can opt in
+        // to a content-hash drift, and every non-opted-in caller remains strict.
+        const verified = assetMatchesId(result, id);
+        if (verified || !isContentAssetIdRequest(id))
+            return { status: 'delivered', asset: result, verified: true };
+        return options?.allowUnverifiedExactIdentity === true
+            ? { status: 'delivered', asset: result, verified: false }
+            : { status: 'rejected', reason: 'unverified_not_allowed' };
+    }
+    async fetchAssetById(assetId, options) {
+        const outcome = await this.fetchAssetDeliveryById(assetId, options);
+        return outcome.status === 'delivered' ? outcome.asset : null;
     }
     /**
      * #69: search != fetch. Free-text is the hub's vector endpoint (GET /a2a/assets/semantic-search?q=);
-     * signals/id queries fall through to fetch. /a2a/fetch does NOT do semantic, so text must not go there.
+     * signal/id queries use the Hub's free search-only phase on /a2a/fetch. /a2a/fetch does NOT do semantic,
+     * so text must not go there and paid/full fetch must remain an explicit follow-up.
      */
     async search(query) {
         if (query.text && query.text.trim()) {
             // GET /a2a/assets/semantic-search returns a FLAT object keyed `assets` (no GEP envelope), plus a
-            // `search_status` (found / degraded(retryable) / low_confidence_only / no_match). Reading body.results
-            // here always yielded [] — the semantic path could never return a hit. (Status not surfaced yet: the
-            // HubCapability.search contract is AssetRecord[]; honoring search_status needs an interface change — later.)
-            const body = await this.http.call('GET', '/a2a/assets/semantic-search', undefined, { q: query.text, ...(query.limit !== undefined ? { limit: query.limit } : {}) });
-            return (body.assets ?? []);
+            // `search_status` (found / degraded(retryable) / low_confidence_only / no_match). Only an explicit
+            // no_match is a verified empty result; degraded or malformed 200 responses must not trigger ATP spend.
+            const body = await this.http.call('GET', '/a2a/assets/semantic-search', undefined, {
+                q: query.text,
+                ...(query.kind !== undefined ? { type: query.kind } : {}),
+                ...(query.domain !== undefined ? { domain: query.domain } : {}),
+                ...(query.limit !== undefined ? { limit: query.limit } : {}),
+            });
+            return semanticSearchAssets(body);
         }
-        return this.fetch(query);
+        const body = await this.http.call('POST', '/a2a/fetch', gepEnvelope('fetch', searchQueryToSearchOnlyWire(query)));
+        return signalSearchAssets(body);
     }
     agentDirectory = {
         search: async (request) => {
@@ -305,16 +420,18 @@ export class PublicHubCapability {
             ...(opts.scope === 'published' && opts.status && opts.status !== 'all' ? { status: opts.status } : {}),
         };
         const body = await this.http.call('GET', path, undefined, query);
-        const payload = asRecord(body['payload']) ?? body;
+        const payload = Object.prototype.hasOwnProperty.call(body, 'payload')
+            ? asRecord(body['payload'])
+            : body;
+        if (!payload)
+            throw new MalformedAccountAssetPageError();
         const assets = accountAssetsFromPayload(payload);
         const count = numberField(payload, 'count');
-        const nextCursor = stringField(payload, 'next_cursor') ?? stringField(payload, 'nextCursor');
-        const hasMore = booleanField(payload, 'has_more') ?? booleanField(payload, 'hasMore') ?? Boolean(nextCursor);
+        const pagination = accountPaginationFromPayload(payload);
         return {
             assets,
             ...(count !== undefined ? { count } : {}),
-            hasMore,
-            ...(nextCursor ? { nextCursor } : {}),
+            ...pagination,
         };
     }
     /**
@@ -393,6 +510,52 @@ export class PublicHubCapability {
             return { recorded: false, reason: e instanceof Error ? e.message : String(e) };
         }
     }
+    async listLearningAssets(options = {}) {
+        const limit = normalizeLearningAssetLimit(options.limit);
+        if (!this.opts.senderId()?.trim())
+            return { assets: [], limit, reason: 'sender_id_required' };
+        try {
+            const body = await this.http.call('GET', '/a2a/learning-assets', undefined, learningAssetListQuery(options, limit));
+            const payload = asRecord(body['payload']) ?? body;
+            return {
+                assets: learningAssetsFromPayload(payload),
+                limit: numberField(payload, 'limit') ?? limit,
+            };
+        }
+        catch (e) {
+            return { assets: [], limit, reason: failureReason(e) };
+        }
+    }
+    async recordLearningAssetUsage(report) {
+        if (!this.opts.senderId()?.trim())
+            return { recorded: false, reason: 'sender_id_required', results: [] };
+        const sourceEventId = trimStringField(report.sourceEventId, 160);
+        if (!sourceEventId)
+            return { recorded: false, reason: 'source_event_id_required', results: [] };
+        const assetIds = normalizeLearningAssetIds(report.usedAssetIds && report.usedAssetIds.length > 0 ? report.usedAssetIds : [report.assetId]);
+        if (assetIds.length === 0)
+            return { recorded: false, reason: 'asset_id_required', results: [] };
+        const outcome = normalizeLearningAssetOutcome(report.outcome);
+        if (!outcome)
+            return { recorded: false, reason: 'invalid_learning_asset_outcome', results: [] };
+        const score = optionalLearningAssetScore(report.score);
+        if ('reason' in score)
+            return { recorded: false, reason: score.reason, results: [] };
+        const reason = trimStringField(report.reason, 2_000);
+        try {
+            const body = await this.http.call('POST', '/a2a/learning-assets/usage', {
+                ...(assetIds.length === 1 ? { asset_id: assetIds[0] } : { used_asset_ids: assetIds }),
+                outcome,
+                source_event_id: sourceEventId,
+                ...(score.value !== undefined ? { score: score.value } : {}),
+                ...(reason ? { reason } : {}),
+            });
+            return learningAssetUsageReceiptFromBody(body);
+        }
+        catch (e) {
+            return { recorded: false, reason: failureReason(e), results: [] };
+        }
+    }
     /**
      * Pre-publish dry-run (POST /a2a/validate). The hub runs the same hub-side quality +
      * content-safety gate as publish but stores nothing and charges no credits. This adapter is
@@ -448,14 +611,14 @@ export class PublicHubCapability {
             ...(request.pricePerExecution !== undefined ? { price_per_execution: request.pricePerExecution } : {}),
             ...(request.currency ? { currency: request.currency } : {}),
             ...(request.maxConcurrent !== undefined ? { max_concurrent: request.maxConcurrent } : {}),
-        });
+        }, undefined, request.idempotencyKey ? { 'idempotency-key': request.idempotencyKey } : undefined);
         return recipeReceiptFromBody(body);
     }
-    async publishRecipe(recipeId) {
+    async publishRecipe(recipeId, options) {
         if (isHubDryRunEnabled())
             return dryRunRecipeReceipt('publish_recipe', recipeId);
         const sender = this.opts.senderId();
-        const body = await this.http.call('POST', `/a2a/recipe/${encodeURIComponent(recipeId)}/publish`, { ...(sender ? { node_id: sender } : {}) });
+        const body = await this.http.call('POST', `/a2a/recipe/${encodeURIComponent(recipeId)}/publish`, { ...(sender ? { node_id: sender } : {}) }, undefined, options?.idempotencyKey ? { 'idempotency-key': options.idempotencyKey } : undefined);
         return recipeReceiptFromBody(body);
     }
     async getRecipe(recipeId) {
@@ -472,6 +635,20 @@ export class PublicHubCapability {
             ...(recipe !== undefined ? { recipe } : {}),
         };
     }
+    async searchRecipes(request = {}) {
+        if (isHubDryRunEnabled()) {
+            return dryRunRecipeSearchReceipt('search_recipe', request);
+        }
+        const body = await this.http.call('GET', '/a2a/recipe/search', undefined, recipeSearchQuery(request));
+        return recipeSearchReceiptFromBody(body);
+    }
+    async listRecipes(request = {}) {
+        if (isHubDryRunEnabled()) {
+            return dryRunRecipeSearchReceipt('list_recipe', request);
+        }
+        const body = await this.http.call('GET', '/a2a/recipe/list', undefined, recipeSearchQuery(request));
+        return recipeSearchReceiptFromBody(body);
+    }
     async expressRecipe(recipeId, request = {}) {
         if (isHubDryRunEnabled()) {
             return dryRunRecipeReceipt('express_recipe', recipeId, { input_payload: request.inputPayload ?? {} });
@@ -546,7 +723,10 @@ export class PublicHubCapability {
         const body = await this.http.call('POST', '/a2a/events/poll', gepEnvelope('events_poll', { timeout_ms: 1000 }));
         for (const e of body.events ?? []) {
             if (String(e['type']).startsWith('task_')) {
-                yield { taskId: String(e['payload']?.taskId ?? e['id']), type: String(e['type']), payload: e['payload'], priority: e['priority'] ?? 'medium', createdAt: Date.parse(String(e['created_at'] ?? '')) || 0 };
+                const payload = asRecord(e['payload']);
+                const wireTaskId = payload?.['task_id'] ?? payload?.['taskId'];
+                const taskId = typeof wireTaskId === 'string' && wireTaskId.length > 0 ? wireTaskId : String(e['id']);
+                yield { taskId, type: String(e['type']), payload: e['payload'], priority: e['priority'] ?? 'medium', createdAt: Date.parse(String(e['created_at'] ?? '')) || 0 };
             }
         }
     }
@@ -646,6 +826,44 @@ export class PublicHubCapability {
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }
+function searchAssets(value, source) {
+    if (!Array.isArray(value))
+        throw new Error(`${source}_results_invalid`);
+    return value.map((candidate) => {
+        const record = asRecord(candidate);
+        if (!record)
+            throw new Error(`${source}_asset_invalid`);
+        const asset = unwrapFetchDeliveryRow(record);
+        const assetId = stringField(asset, 'asset_id') ?? stringField(asset, 'assetId');
+        if (!assetId)
+            throw new Error(`${source}_asset_invalid`);
+        return asset;
+    });
+}
+function semanticSearchAssets(body) {
+    const status = stringField(body, 'search_status');
+    if (status === 'degraded' || body['retryable'] === true)
+        throw new Error('semantic_search_degraded');
+    const assets = searchAssets(body['assets'], 'semantic_search');
+    if (status === 'no_match') {
+        if (assets.length !== 0)
+            throw new Error('semantic_search_status_invalid');
+        return assets;
+    }
+    if (status === 'found' || status === 'low_confidence_only') {
+        if (assets.length === 0)
+            throw new Error('semantic_search_status_invalid');
+        return assets;
+    }
+    // Older successful Hub responses are usable only when they carry a concrete candidate.
+    if (status === undefined && assets.length > 0)
+        return assets;
+    throw new Error('semantic_search_status_invalid');
+}
+function signalSearchAssets(body) {
+    const payload = asRecord(body['payload']);
+    return searchAssets(payload?.['results'], 'signal_search');
+}
 function recipeStepToWire(step) {
     return {
         asset_id: step.assetId,
@@ -676,6 +894,58 @@ function recipeOrganismIdFromPayload(payload) {
         ? stringField(organism, 'id') ?? stringField(organism, 'organism_id') ?? stringField(organism, 'organismId')
         : undefined;
 }
+function recipeSearchQuery(request) {
+    return {
+        ...(request.q ? { q: request.q } : {}),
+        ...(request.limit !== undefined ? { limit: request.limit } : {}),
+        ...(request.cursor ? { cursor: request.cursor } : {}),
+        ...(request.sort ? { sort: request.sort } : {}),
+    };
+}
+function recipeListFromRecord(value) {
+    for (const key of ['recipes', 'items', 'results']) {
+        const found = value[key];
+        if (Array.isArray(found))
+            return found;
+    }
+    const nested = asRecord(value['data']);
+    if (!nested)
+        return undefined;
+    for (const key of ['recipes', 'items', 'results']) {
+        const found = nested[key];
+        if (Array.isArray(found))
+            return found;
+    }
+    return undefined;
+}
+function recipeSearchReceiptFromBody(body) {
+    const payload = recipePayload(body);
+    const recipes = recipeListFromRecord(payload) ?? recipeListFromRecord(body) ?? [];
+    const nextCursor = stringField(payload, 'next_cursor')
+        ?? stringField(payload, 'nextCursor')
+        ?? stringField(body, 'next_cursor')
+        ?? stringField(body, 'nextCursor');
+    const hasMore = booleanField(payload, 'has_more')
+        ?? booleanField(payload, 'hasMore')
+        ?? booleanField(body, 'has_more')
+        ?? booleanField(body, 'hasMore');
+    return {
+        recipes,
+        ...(nextCursor ? { nextCursor } : {}),
+        ...(hasMore !== undefined ? { hasMore } : {}),
+        raw: body,
+    };
+}
+function dryRunRecipeSearchReceipt(action, request) {
+    return {
+        recipes: [],
+        raw: {
+            dry_run: true,
+            would: action,
+            ...request,
+        },
+    };
+}
 function recipeReceiptFromBody(body) {
     const payload = recipePayload(body);
     const recipe = asRecord(payload['recipe']);
@@ -700,7 +970,7 @@ function dryRunRecipeReceipt(action, recipeId, extra = {}) {
         },
     };
 }
-function assetsFromBody(body) {
+function assetCandidatesFromBody(body) {
     const payload = asRecord(body['payload']);
     const candidates = [
         body['asset'],
@@ -710,9 +980,134 @@ function assetsFromBody(body) {
         ...(Array.isArray(payload?.['assets']) ? payload['assets'] : []),
         ...(Array.isArray(payload?.['results']) ? payload['results'] : []),
     ];
-    return candidates.filter((candidate) => Boolean(candidate && typeof candidate === 'object' && !Array.isArray(candidate)));
+    return candidates
+        .filter((candidate) => Boolean(candidate && typeof candidate === 'object' && !Array.isArray(candidate)));
+}
+function assetsFromBody(body) {
+    return assetCandidatesFromBody(body).map(unwrapFetchDeliveryRow);
+}
+// Delivery-row metadata carried over onto the unwrapped GEP record. Ranking fields are consumed by
+// hubReuse and stripped before canonical storage. `payload_backfill_reason` must also survive this
+// boundary so integrity consumers can report that the Hub synthesized the payload (#570). Do not
+// carry `confidence`: it is transport metadata on Gene rows but canonical content on Capsules, so
+// overloading it can either poison a Gene hash or overwrite Capsule content (#565).
+const FETCH_ROW_CARRYOVER_KEYS = [
+    'gdi_score',
+    'success_rate',
+    'reuse_count',
+    'source_node_id',
+    'payload_backfill_reason',
+    'status',
+    'trust_state',
+];
+/**
+ * The live hub's /a2a/fetch results are DELIVERY ROWS, not raw GEP records (#565, observed on
+ * evomap.ai 2026-07-22): the record itself nests under `payload`, while the row's own keys are
+ * delivery metadata (asset_type, bundle_id, confidence, gdi_score_mean, callable, …). Treating the
+ * row as the asset made reuse's integrity check (computeAssetId over the row) fail on every
+ * delivered asset. A GEP record always carries a string `type`; delivery rows carry `asset_type`
+ * instead — so unwrap exactly when the row has no `type` and nests an object payload that looks
+ * like a GEP record. Rows that already ARE raw records (older hubs, tests) pass through unchanged.
+ */
+function unwrapFetchDeliveryRow(row) {
+    const record = row;
+    if (typeof record['type'] === 'string')
+        return row;
+    const inner = asRecord(record['payload']);
+    if (!inner || typeof inner['type'] !== 'string' || typeof inner['asset_id'] !== 'string')
+        return row;
+    const carryover = {};
+    for (const key of FETCH_ROW_CARRYOVER_KEYS) {
+        if (record[key] !== undefined && inner[key] === undefined)
+            carryover[key] = record[key];
+    }
+    return { ...inner, ...carryover };
+}
+function fetchDeliveryIdentityConsistent(row, asset) {
+    const outer = row;
+    if (typeof outer['type'] === 'string') {
+        const transportType = stringField(outer, 'asset_type');
+        if (transportType !== undefined && transportType !== outer['type'])
+            return false;
+        const transportLogicalId = stringField(outer, 'local_id');
+        if (transportLogicalId !== undefined && transportLogicalId !== stringField(outer, 'id'))
+            return false;
+        return true;
+    }
+    const inner = asRecord(outer['payload']);
+    if (!inner)
+        return false;
+    const outerAssetId = stringField(outer, 'asset_id');
+    const innerAssetId = stringField(inner, 'asset_id');
+    if (!outerAssetId || !innerAssetId || outerAssetId !== innerAssetId)
+        return false;
+    const outerType = stringField(outer, 'asset_type');
+    const innerType = stringField(inner, 'type');
+    if (outerType !== undefined && outerType !== innerType)
+        return false;
+    const innerLogicalId = stringField(inner, 'id');
+    for (const key of ['id', 'local_id']) {
+        const outerLogicalId = stringField(outer, key);
+        if (outerLogicalId !== undefined && outerLogicalId !== innerLogicalId)
+            return false;
+    }
+    for (const key of ['status', 'trust_state']) {
+        const outerMarker = stringField(outer, key);
+        const innerMarker = stringField(inner, key);
+        const outerRevoked = isRevokedMarker(outerMarker);
+        const innerRevoked = isRevokedMarker(innerMarker);
+        if (outerMarker !== undefined && innerMarker !== undefined && outerRevoked !== innerRevoked)
+            return false;
+    }
+    return asset === row || stringField(asset, 'asset_id') === innerAssetId;
+}
+function isRevokedFetchDelivery(row) {
+    const record = row;
+    const nested = asRecord(record['payload']);
+    return [record, ...(nested ? [nested] : [])].some((value) => (isRevokedMarker(value['status'])
+        || isRevokedMarker(value['trust_state'])));
+}
+function isRevokedMarker(raw) {
+    return typeof raw === 'string' && raw.trim().toLowerCase() === 'revoked';
 }
 function accountAssetsFromPayload(payload) {
+    const keys = ['assets', 'results', 'items']
+        .filter((key) => Object.prototype.hasOwnProperty.call(payload, key));
+    if (keys.length !== 1)
+        throw new MalformedAccountAssetPageError();
+    const candidate = payload[keys[0]];
+    if (!Array.isArray(candidate) || candidate.some((asset) => !asset || typeof asset !== 'object' || Array.isArray(asset))) {
+        throw new MalformedAccountAssetPageError();
+    }
+    return candidate.map((row) => {
+        const asset = unwrapFetchDeliveryRow(row);
+        return fetchDeliveryIdentityConsistent(row, asset) ? asset : row;
+    });
+}
+function accountPaginationFromPayload(payload) {
+    const snakeHasMore = payload['has_more'];
+    const camelHasMore = payload['hasMore'];
+    if ((snakeHasMore !== undefined && typeof snakeHasMore !== 'boolean')
+        || (camelHasMore !== undefined && typeof camelHasMore !== 'boolean')
+        || (snakeHasMore === undefined && camelHasMore === undefined)
+        || (typeof snakeHasMore === 'boolean' && typeof camelHasMore === 'boolean' && snakeHasMore !== camelHasMore)) {
+        throw new MalformedAccountAssetPageError();
+    }
+    const hasMore = typeof snakeHasMore === 'boolean' ? snakeHasMore : camelHasMore;
+    const rawCursors = [payload['next_cursor'], payload['nextCursor']]
+        .filter((value) => value !== undefined && value !== null);
+    if (rawCursors.some((value) => typeof value !== 'string' || !value.trim())) {
+        throw new MalformedAccountAssetPageError();
+    }
+    if (rawCursors.length === 2 && rawCursors[0] !== rawCursors[1]) {
+        throw new MalformedAccountAssetPageError();
+    }
+    const nextCursor = rawCursors[0];
+    if (hasMore !== Boolean(nextCursor))
+        throw new MalformedAccountAssetPageError();
+    return { hasMore, ...(nextCursor ? { nextCursor } : {}) };
+}
+function learningAssetsFromPayload(payload) {
     const candidates = [
         payload['assets'],
         payload['results'],
@@ -721,12 +1116,123 @@ function accountAssetsFromPayload(payload) {
     for (const candidate of candidates) {
         if (!Array.isArray(candidate))
             continue;
-        return candidate.filter((asset) => Boolean(asset && typeof asset === 'object' && !Array.isArray(asset)));
+        return candidate.filter((asset) => isLearningAssetRecord(asset));
     }
     return [];
 }
-function assetMatchesId(asset, assetId) {
-    return Boolean(asset && (asset.asset_id === assetId || stringField(asset, 'id') === assetId));
+function isLearningAssetRecord(value) {
+    const record = asRecord(value);
+    return Boolean(record && typeof record['asset_id'] === 'string' && typeof record['type'] === 'string');
+}
+function normalizeLearningAssetLimit(value) {
+    if (!Number.isFinite(value))
+        return 20;
+    return Math.min(100, Math.max(1, Math.floor(value)));
+}
+function learningAssetListQuery(options, limit) {
+    const status = normalizeLearningAssetStatusParam(options.status);
+    const query = {
+        limit,
+        runtime: options.includeExpired === true ? undefined : 'true',
+        include_expired: options.includeExpired === true ? 'true' : undefined,
+        include_payload: options.includePayload === true ? 'true' : undefined,
+        ...(options.type ? { type: options.type } : {}),
+        ...(status ? { status } : options.includeExpired === true ? { status: 'active' } : {}),
+    };
+    const scope = compactLearningAssetParam(options.scope);
+    if (scope)
+        query['scope'] = scope;
+    return query;
+}
+function normalizeLearningAssetStatusParam(status) {
+    if (Array.isArray(status))
+        return compactLearningAssetParam(status);
+    return typeof status === 'string' && status.trim() ? status.trim() : undefined;
+}
+function compactLearningAssetParam(values) {
+    if (!values)
+        return undefined;
+    const out = [...new Set(values.map((value) => String(value).trim()).filter(Boolean))];
+    return out.length > 0 ? out.join(',') : undefined;
+}
+function trimStringField(value, maxLen) {
+    return typeof value === 'string' && value.trim() ? value.trim().slice(0, maxLen) : undefined;
+}
+function normalizeLearningAssetIds(values) {
+    const out = [];
+    const seen = new Set();
+    for (const value of values) {
+        if (typeof value !== 'string')
+            continue;
+        const trimmed = value.trim();
+        if (!trimmed || trimmed.length > LEARNING_ASSET_ID_MAX_LEN || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+        if (out.length >= LEARNING_ASSET_IDS_MAX)
+            break;
+    }
+    return out;
+}
+function normalizeLearningAssetOutcome(value) {
+    if (value === 'success' || value === 'failed' || value === 'mismatched' || value === 'stale' || value === 'unsafe')
+        return value;
+    return undefined;
+}
+function optionalLearningAssetScore(value) {
+    if (value === undefined)
+        return { value: undefined };
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1)
+        return { reason: 'invalid_score' };
+    return { value };
+}
+function learningAssetUsageReceiptFromBody(body) {
+    const payload = asRecord(body['payload']) ?? body;
+    const rows = Array.isArray(payload['results'])
+        ? payload['results'].filter((row) => Boolean(asRecord(row)))
+        : [];
+    const reason = stringField(payload, 'reason') ?? stringField(payload, 'error');
+    return {
+        recorded: rows.length > 0 && rows.some((row) => row.recorded === true),
+        ...(reason ? { reason } : {}),
+        results: rows,
+    };
+}
+function failureReason(error) {
+    if (error instanceof HubClientError) {
+        const body = asRecord(error.body) ?? {};
+        const payload = asRecord(body['payload']) ?? body;
+        return stringField(payload, 'reason') ?? stringField(payload, 'error') ?? `hub ${error.status}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function fetchResultMatchesId(asset, requestedId) {
+    if (assetMatchesId(asset, requestedId))
+        return true;
+    if (!asset)
+        return false;
+    if (!requestedId.startsWith('sha256:'))
+        return stringField(asset, 'id') === requestedId;
+    return false;
+}
+function unambiguousFetchResult(matches) {
+    if (matches.length === 0)
+        return null;
+    let canonical;
+    try {
+        canonical = wire.canonicalize(stripHubDeliveryMetadataForIntegrity(matches[0]));
+        for (const asset of matches.slice(1)) {
+            if (wire.canonicalize(stripHubDeliveryMetadataForIntegrity(asset)) !== canonical)
+                return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return matches.find((asset) => stringField(asset, 'payload_backfill_reason') !== undefined) ?? matches[0];
+}
+function isContentAssetIdRequest(requestedId) {
+    return /^sha256:[0-9a-f]{64}$/.test(requestedId);
 }
 function stringField(value, key) {
     return typeof value[key] === 'string' && value[key].length > 0 ? value[key] : undefined;
@@ -800,14 +1306,39 @@ function mailboxPushResultFromBody(body, events) {
     if (results.length === 0) {
         return { outcomes: events.map((event) => ({ id: event.id, status: 'accepted' })) };
     }
+    const resultIds = results.map(mailboxPushResultId);
+    const hasCompletePositions = results.length === events.length;
     return {
-        outcomes: events.map((event, index) => mailboxPushOutcomeFromRow(event.id, results, index)),
+        outcomes: events.map((event, index) => {
+            const matches = results.filter((_, resultIndex) => resultIds[resultIndex] === event.id);
+            if (matches.length === 1)
+                return mailboxPushOutcomeFromRow(event.id, matches[0]);
+            const positionalMatch = matches.length === 0
+                && hasCompletePositions
+                && resultIds[index] === undefined
+                ? results[index]
+                : undefined;
+            return mailboxPushOutcomeFromRow(event.id, positionalMatch);
+        }),
     };
 }
-function mailboxPushOutcomeFromRow(eventId, results, index) {
-    const match = results.find((result) => String(result['id'] ?? result['message_id'] ?? '') === eventId) ?? results[index];
-    if (!match)
-        return { id: eventId, status: 'accepted' };
+function mailboxPushResultId(row) {
+    const value = row['id'] ?? row['message_id'];
+    if (typeof value !== 'string' && typeof value !== 'number')
+        return undefined;
+    const id = String(value);
+    return id.length > 0 ? id : undefined;
+}
+function mailboxPushOutcomeFromRow(eventId, match) {
+    if (!match) {
+        return {
+            id: eventId,
+            status: 'failed',
+            reason: 'mailbox_response_incomplete',
+            retryable: true,
+            terminal: false,
+        };
+    }
     const reason = mailboxPushFailureReason(match);
     if (!reason)
         return { id: eventId, status: 'accepted', raw: match };
@@ -860,9 +1391,12 @@ function hubErrorStatus(err) {
     }
     return undefined;
 }
-// Retry-After hint from a HubClientError JSON body (429 cooldown). Headers aren't
-// carried on HubClientError, so we read the body's retry_after_ms / retry_after.
+// Prefer the standardized Retry-After header carried by HubClientError, then
+// preserve the existing JSON body hints as a compatibility fallback.
 function clientErrorRetryAfterMs(err) {
+    if (err instanceof HubClientError && typeof err.retryAfterMs === 'number' && Number.isFinite(err.retryAfterMs)) {
+        return err.retryAfterMs;
+    }
     const body = err instanceof HubClientError ? asRecord(err.body) : undefined;
     if (!body)
         return undefined;
@@ -1006,6 +1540,10 @@ function heartbeatResultFromBody(httpStatus, body) {
     const details = payload['details'] ?? body['details'];
     const ack = asRecord(payload['last_update_ack']);
     const forceUpdate = forceUpdateFromRecord(asRecord(payload['force_update']));
+    const rawCapabilityGaps = payload['capability_gaps'] ?? payload['capabilityGaps'];
+    const capabilityGaps = Array.isArray(rawCapabilityGaps)
+        ? signals.normalizeCapabilityGaps(rawCapabilityGaps)
+        : undefined;
     const ok = httpStatus >= 200
         && httpStatus < 300
         && payload['ok'] !== false
@@ -1023,6 +1561,7 @@ function heartbeatResultFromBody(httpStatus, body) {
                 ...(typeof ack['reason'] === 'string' ? { reason: ack['reason'] } : {}),
             } } : {}),
         ...(forceUpdate ? { forceUpdate } : {}),
+        ...(capabilityGaps !== undefined ? { capabilityGaps } : {}),
     };
 }
 function forceUpdateFromRecord(value) {