@evomap/evolver-core 2.0.0-beta.9 → 2.0.0

package/dist/feedback/envelope.js

@@ -0,0 +1,168 @@
+export const PRIORITY_AXES = Object.freeze([
+    'task_success',
+    'user_preference',
+    'quality',
+    'safety',
+    'cost',
+    'latency',
+    'other',
+]);
+export const LABELS = Object.freeze(['positive', 'negative', 'mixed', 'neutral']);
+export const ATTENTION_LEVELS = Object.freeze(['full', 'limited', 'skimmed', 'unknown']);
+export const EVIDENCE_KINDS = Object.freeze([
+    'evolution_event',
+    'evolution_outcome',
+    'user_override',
+    'review',
+    'turn',
+    'external',
+]);
+export function clamp01(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return 0.5;
+    if (n < 0)
+        return 0;
+    if (n > 1)
+        return 1;
+    return n;
+}
+export function labelFromScalar(value) {
+    const scalar = clamp01(value);
+    if (scalar >= 0.6)
+        return 'positive';
+    if (scalar <= 0.4)
+        return 'negative';
+    return 'mixed';
+}
+export function normalizeAttention(input) {
+    const record = asRecord(input);
+    if (!record)
+        return { level: 'unknown' };
+    const attention = {
+        level: enumValue(record['level'], ATTENTION_LEVELS, 'unknown'),
+    };
+    const observedItems = nonNegativeInteger(record['observed_items']);
+    const elapsedMs = nonNegativeInteger(record['elapsed_ms']);
+    if (observedItems !== null)
+        attention.observed_items = observedItems;
+    if (elapsedMs !== null)
+        attention.elapsed_ms = elapsedMs;
+    return attention;
+}
+export function evidenceRef(kind, id, options = {}) {
+    const ref = {
+        kind: enumValue(kind, EVIDENCE_KINDS, 'external'),
+        id: String(id ?? '').trim() || 'unknown',
+    };
+    if (typeof options.summary === 'string' && options.summary.trim()) {
+        ref.summary = options.summary.trim();
+    }
+    return ref;
+}
+export function normalizeEvidenceRef(input) {
+    const record = asRecord(input);
+    if (!record)
+        return evidenceRef('external', 'unknown');
+    return evidenceRef(record['kind'], record['id'], { summary: record['summary'] });
+}
+export function envelopeUncertainty(scalar, attentionLevel, indecision, conflict) {
+    const normalizedScalar = clamp01(scalar);
+    const ambiguity = 1 - Math.abs(normalizedScalar - 0.5) * 2;
+    const attentionPenalty = {
+        full: 0,
+        limited: 0.15,
+        skimmed: 0.30,
+        unknown: 0.20,
+    };
+    return clamp01(0.10
+        + 0.30 * ambiguity
+        + attentionPenalty[attentionLevel]
+        + (indecision ? 0.25 : 0)
+        + (conflict ? 0.35 : 0));
+}
+export function fromScalarFeedback(options = {}) {
+    const input = options ?? {};
+    const scalar = clamp01(input.scalar);
+    const label = labelFromScalar(scalar);
+    const indecision = Boolean(input.indecision) || label === 'mixed';
+    const conflict = Boolean(input.conflict);
+    const evaluatorAttention = normalizeAttention(input.evaluator_attention ?? input.evaluatorAttention);
+    const priorityAxis = enumValue(input.priority_axis ?? input.priorityAxis, PRIORITY_AXES, 'task_success');
+    const evidence = input.evidence_ref ?? input.evidenceRef ?? evidenceRef('external', 'unknown');
+    return {
+        priority_axis: priorityAxis,
+        label,
+        scalar,
+        indecision,
+        conflict,
+        evaluator_attention: evaluatorAttention,
+        evidence_ref: normalizeEvidenceRef(evidence),
+        uncertainty: envelopeUncertainty(scalar, evaluatorAttention.level, indecision, conflict),
+    };
+}
+export function fromOutcomeScalar(outcome, options = {}) {
+    const record = asRecord(outcome);
+    if (!record)
+        return null;
+    const scalar = record['user_override'] ?? record['score'];
+    if (scalar === null || scalar === undefined)
+        return null;
+    return fromScalarFeedback({ ...options, scalar });
+}
+export function withConflict(envelope) {
+    const evaluatorAttention = normalizeAttention(envelope.evaluator_attention);
+    return {
+        ...envelope,
+        conflict: true,
+        evaluator_attention: evaluatorAttention,
+        uncertainty: envelopeUncertainty(envelope.scalar, evaluatorAttention.level, envelope.indecision, true),
+    };
+}
+export function withIndecision(envelope) {
+    const evaluatorAttention = normalizeAttention(envelope.evaluator_attention);
+    return {
+        ...envelope,
+        indecision: true,
+        evaluator_attention: evaluatorAttention,
+        uncertainty: envelopeUncertainty(envelope.scalar, evaluatorAttention.level, true, envelope.conflict),
+    };
+}
+export function aggregateFeedbackEnvelopes(envelopes) {
+    const list = Array.isArray(envelopes) ? envelopes.filter(Boolean) : [];
+    if (list.length === 0)
+        return { dominant_label: null, uncertainty: 1, sample_count: 0 };
+    const sampleCount = list.length;
+    const meanUncertainty = list.reduce((sum, envelope) => sum + clamp01(envelope.uncertainty), 0) / sampleCount;
+    const hasPositive = list.some((envelope) => envelope.label === 'positive');
+    const hasNegative = list.some((envelope) => envelope.label === 'negative');
+    const hasConflict = list.some((envelope) => envelope.conflict) || (hasPositive && hasNegative);
+    const hasIndecision = list.some((envelope) => envelope.indecision || envelope.label === 'mixed' || envelope.label === 'neutral');
+    const hasLowAttention = list.some((envelope) => normalizeAttention(envelope.evaluator_attention).level !== 'full');
+    const uncertainty = clamp01(meanUncertainty
+        + (hasConflict ? 0.25 : 0)
+        + (hasIndecision ? 0.10 : 0)
+        + (hasLowAttention ? 0.10 : 0));
+    let dominantLabel = null;
+    if (!hasConflict && !hasLowAttention && uncertainty < 0.5) {
+        if (hasPositive)
+            dominantLabel = 'positive';
+        else if (hasNegative)
+            dominantLabel = 'negative';
+    }
+    return { dominant_label: dominantLabel, uncertainty, sample_count: sampleCount };
+}
+function enumValue(value, allowed, fallback) {
+    return typeof value === 'string' && allowed.includes(value)
+        ? value
+        : fallback;
+}
+function nonNegativeInteger(value) {
+    const n = Number(value);
+    return Number.isFinite(n) ? Math.max(0, Math.floor(n)) : null;
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}

package/dist/feedback/index.d.ts

@@ -0,0 +1 @@
+export * from './envelope.js';

package/dist/feedback/index.js

@@ -0,0 +1 @@
+export * from './envelope.js';

package/dist/hooks/hooks.js

@@ -69,6 +69,7 @@ export function composeSessionStartWithRecap(base, recapCtx, estimateTokensOrOpt
 export function signalsFromToolUse(event) {
     const turn = {
         toolName: event.toolName,
+        ...(event.toolResult ? { toolResult: event.toolResult } : {}),
         ...(event.isError && event.toolResult ? { errorMessage: event.toolResult } : {}),
         ...(event.text ? { text: event.text } : {}),
         isMeta: false,

package/dist/hub/assetCallLog.d.ts

@@ -1,4 +1,5 @@
-export type AssetCallAction = 'hub_search_hit' | 'hub_search_miss' | 'asset_reuse' | 'asset_reference' | 'asset_publish' | 'asset_publish_skip' | 'hub_review_submitted' | 'hub_review_rejected' | 'hub_review_failed';
+export type AssetCallAction = 'hub_search_hit' | 'hub_search_miss' | 'asset_reuse' | 'asset_reference' | 'asset_publish' | 'asset_publish_skip' | 'asset_inject' | 'asset_inject_shadow' | 'hub_review_submitted' | 'hub_review_rejected' | 'hub_review_failed';
+export type TokensSavedBasis = 'measured' | 'cost_index' | 'estimated_blast_radius' | 'estimated_default';
 export interface AssetCallEntry {
     run_id?: string | null;
     action: AssetCallAction;
@@ -10,6 +11,9 @@ export interface AssetCallEntry {
     mode?: 'direct' | 'reference';
     signals?: readonly string[];
     reason?: string;
+    tokens_saved?: number | null;
+    tokens_saved_basis?: TokensSavedBasis | null;
+    tokens_spent?: number | null;
     extra?: Record<string, unknown>;
 }
 export interface AssetCallRecord extends AssetCallEntry {
@@ -30,6 +34,32 @@ export interface CallLogSummary {
     by_action: Record<string, number>;
     entries: AssetCallRecord[];
 }
+export interface AssetReuseAttribution {
+    asset_id: string;
+    source_node_id: string | null;
+    chain_id: string | null;
+    reuse: number;
+    reference: number;
+    tokens_saved: number;
+}
+export interface ReuseAttributionSummary {
+    total_reuse: number;
+    total_reference: number;
+    total_tokens_saved: number;
+    by_asset: AssetReuseAttribution[];
+}
+export interface ReuseSavingsMetric {
+    tokens_saved: number;
+    tokens_saved_basis: TokensSavedBasis;
+}
+/** Measured derivation cost carried by an asset (or by a Hub wrapper's payload). */
+export declare function assetDerivationTokenCost(asset: unknown): number | undefined;
+/**
+ * Attribute savings without inventing a measured value: asset telemetry wins, then this node's publish-cost
+ * index, then the savings-core blast/default estimator. Reference reuse applies the same fractional discount
+ * to measured and estimated costs.
+ */
+export declare function reuseSavingsForAsset(asset: unknown, mode: 'direct' | 'reference', indexedTokenCost?: unknown): ReuseSavingsMetric;
 export declare class AssetCallLog {
     private readonly path;
     private readonly now;
@@ -40,4 +70,8 @@ export declare class AssetCallLog {
     read(opts?: ReadOpts): AssetCallRecord[];
     /** Totals + per-action counts (for CLI / observability). */
     summarize(opts?: ReadOpts): CallLogSummary;
+    /** Local-only attribution rollup over reuse/reference audit rows. */
+    reuseAttributionSummary(opts?: ReadOpts): ReuseAttributionSummary;
+    /** Later valid publish rows win; malformed/non-positive costs never erase a prior measurement. */
+    assetCostIndex(opts?: ReadOpts): Record<string, number>;
 }

package/dist/hub/assetCallLog.js

@@ -5,6 +5,69 @@
 // or fails an evolution. The log path is injected so it's testable without a real home dir.
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { REUSE_ESTIMATOR, reuseEstimate } from '../ops/savingsCore.js';
+function objectRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function positiveNumber(value, coerceLegacy = false) {
+    const number = typeof value === 'number' ? value : coerceLegacy ? Number(value) : Number.NaN;
+    return Number.isFinite(number) && number > 0 ? number : undefined;
+}
+function nestedAssetRecord(asset) {
+    const direct = objectRecord(asset);
+    return { ...(direct ? { direct } : {}), ...(objectRecord(direct?.['payload']) ? { payload: objectRecord(direct?.['payload']) } : {}) };
+}
+/** Measured derivation cost carried by an asset (or by a Hub wrapper's payload). */
+export function assetDerivationTokenCost(asset) {
+    const records = nestedAssetRecord(asset);
+    for (const record of [records.direct, records.payload]) {
+        const derivation = objectRecord(record?.['derivation_tokens']);
+        const total = positiveNumber(derivation?.['total_tokens']);
+        if (total !== undefined)
+            return total;
+    }
+    return undefined;
+}
+function assetBlastRadiusLines(asset) {
+    const records = nestedAssetRecord(asset);
+    for (const record of [records.direct, records.payload]) {
+        const blast = objectRecord(record?.['blast_radius']);
+        const lines = positiveNumber(blast?.['lines']);
+        if (lines !== undefined)
+            return lines;
+    }
+    return undefined;
+}
+/**
+ * Attribute savings without inventing a measured value: asset telemetry wins, then this node's publish-cost
+ * index, then the savings-core blast/default estimator. Reference reuse applies the same fractional discount
+ * to measured and estimated costs.
+ */
+export function reuseSavingsForAsset(asset, mode, indexedTokenCost) {
+    const measured = assetDerivationTokenCost(asset);
+    const indexed = measured === undefined ? positiveNumber(indexedTokenCost) : undefined;
+    const cost = measured ?? indexed;
+    if (cost !== undefined) {
+        return {
+            tokens_saved: Math.round(mode === 'reference' ? cost * REUSE_ESTIMATOR.reference_saving_fraction : cost),
+            tokens_saved_basis: measured !== undefined ? 'measured' : 'cost_index',
+        };
+    }
+    const estimated = reuseEstimate(assetBlastRadiusLines(asset), mode);
+    return { tokens_saved: estimated.tokens_saved, tokens_saved_basis: estimated.basis };
+}
+function isAssetCallRecord(value) {
+    const record = objectRecord(value);
+    return record !== undefined
+        && typeof record['timestamp'] === 'string'
+        && typeof record['action'] === 'string'
+        && record['action'].length > 0;
+}
 export class AssetCallLog {
     path;
     now;
@@ -33,7 +96,9 @@ export class AssetCallLog {
                 if (!line)
                     continue;
                 try {
-                    entries.push(JSON.parse(line));
+                    const parsed = JSON.parse(line);
+                    if (isAssetCallRecord(parsed))
+                        entries.push(parsed);
                 }
                 catch { /* skip corrupt */ }
             }
@@ -69,4 +134,62 @@ export class AssetCallLog {
         }
         return { total_entries: entries.length, unique_assets: assets.size, unique_runs: runs.size, by_action: byAction, entries };
     }
+    /** Local-only attribution rollup over reuse/reference audit rows. */
+    reuseAttributionSummary(opts = {}) {
+        const entries = this.read(opts).filter((entry) => entry.action === 'asset_reuse' || entry.action === 'asset_reference');
+        const byAsset = new Map();
+        let totalTokensSaved = 0;
+        let totalReuse = 0;
+        let totalReference = 0;
+        for (const entry of entries) {
+            const id = nonEmptyString(entry.asset_id) ?? '(unknown)';
+            let aggregate = byAsset.get(id);
+            if (!aggregate) {
+                aggregate = {
+                    asset_id: id,
+                    source_node_id: nonEmptyString(entry.source_node_id) ?? null,
+                    chain_id: nonEmptyString(entry.chain_id) ?? null,
+                    reuse: 0,
+                    reference: 0,
+                    tokens_saved: 0,
+                };
+                byAsset.set(id, aggregate);
+            }
+            if (entry.action === 'asset_reuse') {
+                aggregate.reuse += 1;
+                totalReuse += 1;
+            }
+            else {
+                aggregate.reference += 1;
+                totalReference += 1;
+            }
+            const tokensSaved = positiveNumber(entry['tokens_saved'], true);
+            if (tokensSaved !== undefined) {
+                aggregate.tokens_saved += tokensSaved;
+                totalTokensSaved += tokensSaved;
+            }
+            aggregate.source_node_id ??= nonEmptyString(entry.source_node_id) ?? null;
+            aggregate.chain_id ??= nonEmptyString(entry.chain_id) ?? null;
+        }
+        const byAssetRows = [...byAsset.values()].sort((left, right) => (right.reuse + right.reference) - (left.reuse + left.reference));
+        return {
+            total_reuse: totalReuse,
+            total_reference: totalReference,
+            total_tokens_saved: totalTokensSaved,
+            by_asset: byAssetRows,
+        };
+    }
+    /** Later valid publish rows win; malformed/non-positive costs never erase a prior measurement. */
+    assetCostIndex(opts = {}) {
+        const costs = new Map();
+        for (const entry of this.read(opts)) {
+            if (entry.action !== 'asset_publish')
+                continue;
+            const assetId = nonEmptyString(entry.asset_id);
+            const tokensSpent = positiveNumber(entry['tokens_spent'], true);
+            if (assetId && tokensSpent !== undefined)
+                costs.set(assetId, tokensSpent);
+        }
+        return Object.fromEntries(costs);
+    }
 }

package/dist/hub/bindings.d.ts

@@ -1,4 +1,4 @@
-import type { HubCapability, HubBindings } from './capability.js';
+import type { HubCapability, HubBindings, PublishReceipt } from './capability.js';
 import { type LeakCheckMode } from './sanitize.js';
 /** publish 回执非 accepted → 抛此错; SyncEngine 据 terminal 决定是否重试. */
 export declare class PublishRejectedError extends Error {
@@ -19,6 +19,13 @@ export interface HubBindingsOptions {
         mode?: LeakCheckMode;
     };
 }
+/**
+ * Internal publish-handler result. `submittedAssetIds` identifies the exact sanitized
+ * content sent to the Hub, even when the Hub's accepted receipt omits asset ids.
+ */
+export interface PublishDispatchResult extends PublishReceipt {
+    submittedAssetIds?: string[];
+}
 /**
  * 把 HubCapability 接到 core 两 seam(M6-1):
  * - asProxyHandler: Dispatcher.handlers.proxy — 按 envelope.type 路由到 hub. 抛错→store.fail()重试;

package/dist/hub/bindings.js

@@ -37,14 +37,18 @@ export function makeHubBindings(cap, options = {}) {
     const sanEnabled = sanCfg.enabled ?? true;
     const sanEnv = sanCfg.env ?? (typeof process !== 'undefined' ? process.env : {});
     /** Single publish chokepoint: sanitize (on by default) → strict + leak found → refuse (terminal, not retryable) → cap.publish the redacted bundle. */
-    const publishSanitized = (bundle) => {
+    const publishSanitized = async (bundle, publishOptions) => {
         if (!sanEnabled)
-            return cap.publish(bundle);
+            return publishOptions ? cap.publish(bundle, publishOptions) : cap.publish(bundle);
         const r = sanitizeBundle(bundle, { env: sanEnv, ...(sanCfg.mode ? { mode: sanCfg.mode } : {}) });
         if (r.blocked) {
             throw new PublishRejectedError('leak_blocked', true, `sensitive data detected before publish, refused (not retryable): ${summarizeLeaks(r.leaks)}`);
         }
-        return cap.publish(r.bundle);
+        const receipt = publishOptions
+            ? await cap.publish(r.bundle, publishOptions)
+            : await cap.publish(r.bundle);
+        const submittedAssetIds = contentAssetIds(r.bundle);
+        return submittedAssetIds ? { ...receipt, submittedAssetIds } : receipt;
     };
     return {
         asProxyHandler() {
@@ -54,9 +58,10 @@ export function makeHubBindings(cap, options = {}) {
                         // payload 可为 bundle {assets:[...]} 或单资产; 统一成 bundle 数组发.
                         const p = e.payload;
                         const bundle = Array.isArray(p.assets) ? p.assets : [p];
-                        const r = await publishSanitized(bundle);
-                        if (r.status !== 'accepted')
-                            throw new PublishRejectedError(r.status, r.terminal ?? true, r.reason);
+                        const r = await publishSanitized(bundle, { idempotencyKey: e.idempotencyKey });
+                        if (r.status !== 'accepted') {
+                            throw new PublishRejectedError(r.rejection?.code ?? r.status, r.terminal ?? true, r.reason, r.rejection?.retryAfterMs);
+                        }
                         return r;
                     }
                     case 'task_claim': {
@@ -98,6 +103,12 @@ export function makeHubBindings(cap, options = {}) {
         },
     };
 }
+function contentAssetIds(bundle) {
+    const ids = bundle.map((asset) => asset.asset_id);
+    return ids.every((id) => typeof id === 'string' && /^sha256:[a-f0-9]{64}$/i.test(id))
+        ? ids
+        : undefined;
+}
 function firstString(...values) {
     for (const value of values) {
         if (typeof value !== 'string')

package/dist/hub/capability.d.ts

@@ -16,6 +16,11 @@ export interface PublishReceipt {
     assetIds?: string[];
     /** 终态标记: true=不可重试(reject/quarantine/402), SyncEngine 不得 incrementRetry(money-safety risk). */
     terminal?: boolean;
+    /** Adapter-owned structured rejection metadata; callers must not infer policy from free-form `reason`. */
+    rejection?: {
+        code: 'invalid_request' | 'credit_shortage' | 'node_unauthorized' | 'not_found' | 'duplicate' | 'invalid_payload' | 'cooldown' | 'hub_rejected';
+        retryAfterMs?: number;
+    };
     /** M8-1: 公版经济侧只读回执(core 不解释经济语义, 仅透传供观测/UI). private hub 多为空. */
     economic?: {
         creditShortage?: boolean;
@@ -25,6 +30,10 @@ export interface PublishReceipt {
         gdiScore?: number;
     };
 }
+export interface PublishOptions {
+    /** Stable, non-blank per logical publish so adapters can make transport retries idempotent. */
+    idempotencyKey?: string;
+}
 /** 资产查询. 复用 assetstore SearchQuery, 不发明第二套查询 DSL. */
 export type HubQuery = SearchQuery;
 /** task 子系统事件(订阅流元素). 公版含经济上下文(bounty/credit), 私有仅 workflow. */
@@ -111,6 +120,75 @@ export interface ReuseResultReceipt {
     reason?: string;
     id?: string;
 }
+export type LearningAssetType = 'memory' | 'skill' | 'playbook' | 'eval';
+export type LearningAssetStatus = 'pending_review' | 'active' | 'disabled' | 'stale' | 'archived';
+export type LearningAssetEffectiveStatus = LearningAssetStatus | 'expired';
+export type LearningAssetUsageOutcome = ReuseResultOutcome;
+export interface LearningAssetOwner {
+    node_id?: string | null;
+    user_id?: string | null;
+    org_id?: string | null;
+    workspace_id?: string | null;
+}
+/** Hub-owned learning asset record. Core keeps it opaque; adapters own wire shape and auth. */
+export interface LearningAssetRecord {
+    asset_id: string;
+    type: LearningAssetType;
+    source_packet_id?: string;
+    scope?: string[];
+    owner?: LearningAssetOwner;
+    title?: string;
+    summary?: string;
+    confidence?: number;
+    last_used_at?: string | null;
+    usage_count?: number;
+    success_count?: number;
+    success_rate?: number;
+    expires_at?: string | null;
+    conflicts_with?: string[];
+    status?: LearningAssetStatus;
+    effective_status?: LearningAssetEffectiveStatus;
+    status_reason?: string;
+    provenance?: Record<string, unknown>;
+    payload?: Record<string, unknown>;
+    created_at?: string | null;
+    updated_at?: string | null;
+    [k: string]: unknown;
+}
+export interface LearningAssetListOptions {
+    type?: LearningAssetType;
+    scope?: readonly string[];
+    status?: LearningAssetStatus | readonly LearningAssetStatus[];
+    includeExpired?: boolean;
+    includePayload?: boolean;
+    limit?: number;
+}
+export interface LearningAssetListResult {
+    assets: LearningAssetRecord[];
+    limit: number;
+    reason?: string;
+}
+export interface LearningAssetUsageReport {
+    assetId?: string;
+    usedAssetIds?: readonly string[];
+    outcome: LearningAssetUsageOutcome;
+    score?: number;
+    sourceEventId: string;
+    reason?: string;
+}
+export interface LearningAssetUsageResultRow {
+    asset_id: string;
+    recorded: boolean;
+    duplicated?: boolean;
+    error?: string;
+    [k: string]: unknown;
+}
+/** Learning-asset usage reporting is best-effort; failures must not break runtime solve paths. */
+export interface LearningAssetUsageReceipt {
+    recorded: boolean;
+    reason?: string;
+    results: LearningAssetUsageResultRow[];
+}
 /**
  * Pre-publish dry-run result. The hub runs the same hub-side quality + content-safety
  * gate as publish but stores nothing and charges no credits, so an agent can check a
@@ -141,6 +219,10 @@ export interface RecipeCreateRequest {
     pricePerExecution?: number;
     currency?: string;
     maxConcurrent?: number;
+    idempotencyKey?: string;
+}
+export interface RecipePublishOptions {
+    idempotencyKey?: string;
 }
 export interface RecipeReceipt {
     recipeId?: string;
@@ -159,11 +241,11 @@ export interface RecipeExpressionReceipt extends RecipeReceipt {
 /** Optional Hub recipe/DNA capability. Core stays wire-agnostic; adapters own REST shape. */
 export interface RecipeCapability {
     create(request: RecipeCreateRequest): Promise<RecipeReceipt>;
-    publish(recipeId: string): Promise<RecipeReceipt>;
+    publish(recipeId: string, options?: RecipePublishOptions): Promise<RecipeReceipt>;
     get(recipeId: string): Promise<RecipeFetchReceipt>;
     express(recipeId: string, request?: RecipeExpressRequest): Promise<RecipeExpressionReceipt>;
 }
-export type HubCapabilityName = 'publish' | 'fetch' | 'search' | 'task' | 'mailbox' | 'auth' | 'audit' | 'air_gap' | 'tenant_isolation' | 'marketplace' | 'economy' | 'questions' | 'recipes' | 'agent_directory';
+export type HubCapabilityName = 'publish' | 'fetch' | 'search' | 'task' | 'mailbox' | 'auth' | 'audit' | 'air_gap' | 'tenant_isolation' | 'marketplace' | 'economy' | 'questions' | 'recipes' | 'agent_directory' | 'learning_assets';
 /** hub 能力清单(可选). core 据此动态适配 UI/行为, "按需耦合". */
 export interface HubManifest {
     capabilities: HubCapabilityName[] | string[];
@@ -201,6 +283,7 @@ export interface HttpRequestLike {
     method: string;
     path: string;
     body?: string;
+    signal?: AbortSignal;
 }
 /**
  * Pluggable auth. Example implementations: public OAuth device token / Ed25519 keypair / enterprise SSO (OIDC/LDAP).
@@ -222,7 +305,7 @@ export interface HubCapability {
      * 异步发布. 公版 /a2a/publish 收 **bundle**[Gene,Capsule,(EvolutionEvent)](一个 cycle 的产物一起发, +GDI);
      * 传单资产=[asset]。core 已 normalizeForPut(算/校验 asset_id), hub 做经济/治理/质量 gate。
      */
-    publish(bundle: AssetRecord[]): Promise<PublishReceipt>;
+    publish(bundle: AssetRecord[], options?: PublishOptions): Promise<PublishReceipt>;
     /** 拉取资产. hub 侧排序/scope(公版 GDI, 私有 RBAC); core 不重排. */
     fetch(query: HubQuery): Promise<AssetRecord[]>;
     /** 搜索资产. 与 fetch 同 shape, 差异在 hub 侧召回策略. */
@@ -231,6 +314,10 @@ export interface HubCapability {
     fetchAssetById?(assetId: string): Promise<AssetRecord | null>;
     /** 可选: 报告某个资产被复用后的结果. PHub/enterprise adapter 实现; 不支持时 runtime 应明确降级. */
     recordReuseResult?(report: ReuseResultReport): Promise<ReuseResultReceipt>;
+    /** 可选: 列出 hub 端 runtime learning assets. Missing means the adapter does not support this MVP surface. */
+    listLearningAssets?(options?: LearningAssetListOptions): Promise<LearningAssetListResult>;
+    /** 可选: 上报 learning asset 使用结果. Best-effort; failures must never break solve paths. */
+    recordLearningAssetUsage?(report: LearningAssetUsageReport): Promise<LearningAssetUsageReceipt>;
     /**
      * 可选: 发布前 dry-run 校验(公版 POST /a2a/validate). 跑与 publish 相同的 hub 端质量门禁 + 内容安全扫描,
      * 但不落库、不计费; 经由 Proxy 暴露时调用方需先执行与 publish 相同的客户端脱敏/泄漏拦截.

package/dist/hub/fake.d.ts

@@ -1,4 +1,4 @@
-import type { HubCapability, PublishReceipt, AgentEvent, TaskEvent, AuthProvider, HubQuery, AssetRecord, TaskCompleteContext } from './capability.js';
+import type { HubCapability, PublishReceipt, AgentEvent, TaskEvent, AuthProvider, HubQuery, AssetRecord, TaskCompleteContext, PublishOptions } from './capability.js';
 export interface FakeHubOptions {
     /** 脚本化 publish gate: 返回 reject/quarantine 以测 PublishReceipt 终态路径. */
     publishGate?: (asset: AssetRecord) => Pick<PublishReceipt, 'status' | 'reason' | 'terminal'>;
@@ -28,7 +28,7 @@ export declare class FakeHubCapability implements HubCapability {
     constructor(opts?: FakeHubOptions);
     /** 测试注入: 排一条 inbound 事件供 poll 拉. */
     seedInbound(e: AgentEvent): void;
-    publish(bundle: AssetRecord[]): Promise<PublishReceipt>;
+    publish(bundle: AssetRecord[], _options?: PublishOptions): Promise<PublishReceipt>;
     fetch(query: HubQuery): Promise<AssetRecord[]>;
     search(query: HubQuery): Promise<AssetRecord[]>;
     task: {

package/dist/hub/fake.js

@@ -26,7 +26,7 @@ export class FakeHubCapability {
     }
     /** 测试注入: 排一条 inbound 事件供 poll 拉. */
     seedInbound(e) { this.inbox.push(e); }
-    async publish(bundle) {
+    async publish(bundle, _options) {
         const assetIds = bundle.map((a) => computeAssetId(a));
         const gate = this.opts.publishGate?.(bundle[0] ?? {}) ?? { status: 'accepted' };
         if (gate.status === 'accepted')

package/dist/hub/questionGenerator.d.ts

@@ -54,6 +54,10 @@ export interface QuestionGenerationResult {
     state: QuestionGeneratorState;
     changed: boolean;
 }
-export declare function extractTopicKeywords(transcript: string | undefined, memory: string | undefined, max?: number): string[];
+export interface TopicKeywordOptions {
+    minOccurrences?: number;
+    preserveSourceOrder?: boolean;
+}
+export declare function extractTopicKeywords(transcript: string | undefined, memory: string | undefined, max?: number, opts?: TopicKeywordOptions): string[];
 export declare function generateQuestions(input?: GenerateQuestionsInput): QuestionGenerationResult;
 export declare function generateUrgentQuestions(input?: GenerateUrgentQuestionsInput): QuestionGenerationResult;