@evomap/evolver-core 2.0.0-beta.13 → 2.0.0-beta.15

package/dist/algo/index.d.ts

@@ -8,6 +8,7 @@ export * from './conversationSniffer.js';
 export * from './geneIntake.js';
 export * from './candidateAssembly.js';
 export * from './genePromotion.js';
+export * from './publishEligibility.js';
 export * from './bans.js';
 export * from './antiDistill.js';
 export * from './orchestrator.js';

package/dist/algo/index.js

@@ -8,6 +8,7 @@ export * from './conversationSniffer.js';
 export * from './geneIntake.js';
 export * from './candidateAssembly.js';
 export * from './genePromotion.js';
+export * from './publishEligibility.js';
 export * from './bans.js';
 export * from './antiDistill.js';
 export * from './orchestrator.js';

package/dist/algo/publishEligibility.d.ts

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

package/dist/algo/publishEligibility.js

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

package/dist/events/paths.d.ts

@@ -19,4 +19,6 @@ export declare function tracesDir(env?: Readonly<Record<string, string | undefin
  *  reads it. Defaults to the evomap home root, beside assets/ + evolution/.
  *  NOTE(reuse/#234): confirm this matches where the proxy/RecallHistory reads — best-effort append, so a path
  *  mismatch degrades the audit line, never the reuse write itself. */
-export declare function assetCallLogPath(env?: Readonly<Record<string, string | undefined>>): string;
+export declare function assetCallLogPath(env?: Readonly<Record<string, string | undefined>>): string;
+/** Learning Ops local output dir: per-run LearningPacket drafts + trace-event JSONL (hub upload is a later slice). */
+export declare function learningTraceDir(env?: Readonly<Record<string, string | undefined>>): string;

package/dist/events/paths.js

@@ -41,4 +41,8 @@ export function tracesDir(env = process.env) {
  *  mismatch degrades the audit line, never the reuse write itself. */
 export function assetCallLogPath(env = process.env) {
     return join(evomapHome(env), 'asset_call_log.jsonl');
+}
+/** Learning Ops local output dir: per-run LearningPacket drafts + trace-event JSONL (hub upload is a later slice). */
+export function learningTraceDir(env = process.env) {
+    return env['EVOLVER_LEARNING_TRACE_DIR'] ?? join(evomapHome(env), 'evolution', 'learning-trace');
 }

package/dist/events/public.d.ts

@@ -7,7 +7,7 @@ export type { EventCountsMV } from './projectors.js';
 export { LineTooLargeError, MAX_LINE_BYTES } from './eventStore.js';
 export { ArchiveSegmentConflictError, InvalidRootEventArchiveError, InvalidRootEventLogError, RootEventHistoryGapError, archiveRootEvents, inspectRootEventArchive, planRootEventArchive, readRootEventHistory, rootEventArchiveDir, rootEventArchiveSegmentName, validateRootEventHistory, ROOT_EVENT_ARCHIVE_DEFAULT_KEEP_EVENTS, } from './eventArchive.js';
 export type { RootEventArchiveOptions, RootEventArchivePlan, RootEventArchiveResult, RootEventArchiveStats, } from './eventArchive.js';
-export { rootEventsPath, evomapHome, mvDir, personalityStatePath, assetsDir, materialDir, materialStorePath, materialWatermarkPath, tracesDir, assetCallLogPath } from './paths.js';
+export { rootEventsPath, evomapHome, mvDir, personalityStatePath, assetsDir, materialDir, materialStorePath, materialWatermarkPath, tracesDir, assetCallLogPath, learningTraceDir } from './paths.js';
 export { EVENT_SCHEMA_VERSION } from './eventSchema.js';
 export type { RootEvent, RawEvent, HumanNarrative, Actor, Replayability } from './eventSchema.js';
 export { readEvents, statusReport, listCycles, showCycle, listTriggers, dailySummary, buildNarrativeSnapshot, NARRATIVE_DEFAULT_LIMIT, NARRATIVE_MAX_LIMIT, } from './reports.js';

package/dist/events/public.js

@@ -3,7 +3,7 @@ export { Replayer } from './replayer.js';
 export { eventCountsProjector, DEFAULT_PROJECTORS } from './projectors.js';
 export { LineTooLargeError, MAX_LINE_BYTES } from './eventStore.js';
 export { ArchiveSegmentConflictError, InvalidRootEventArchiveError, InvalidRootEventLogError, RootEventHistoryGapError, archiveRootEvents, inspectRootEventArchive, planRootEventArchive, readRootEventHistory, rootEventArchiveDir, rootEventArchiveSegmentName, validateRootEventHistory, ROOT_EVENT_ARCHIVE_DEFAULT_KEEP_EVENTS, } from './eventArchive.js';
-export { rootEventsPath, evomapHome, mvDir, personalityStatePath, assetsDir, materialDir, materialStorePath, materialWatermarkPath, tracesDir, assetCallLogPath } from './paths.js';
+export { rootEventsPath, evomapHome, mvDir, personalityStatePath, assetsDir, materialDir, materialStorePath, materialWatermarkPath, tracesDir, assetCallLogPath, learningTraceDir } from './paths.js';
 export { EVENT_SCHEMA_VERSION } from './eventSchema.js';
 export { readEvents, statusReport, listCycles, showCycle, listTriggers, dailySummary, buildNarrativeSnapshot, NARRATIVE_DEFAULT_LIMIT, NARRATIVE_MAX_LIMIT, } from './reports.js';
 export { buildRetentionReport, defaultMaterialCursorPath, defaultMaterialCursorPaths, RETENTION_DEFAULT_MAX_MATERIAL_BYTES, RETENTION_DEFAULT_MAX_MATERIAL_RECORDS, RETENTION_DEFAULT_MAX_ROOT_BYTES, RETENTION_DEFAULT_MAX_ROOT_EVENTS, RETENTION_DEFAULT_ROOT_TAIL_EVENTS, RETENTION_DEFAULT_WATCH_RATIO, } from './retention.js';

package/dist/exec/autoExec.d.ts

@@ -10,6 +10,7 @@ import { type OpenPrLister } from './openPrRegistry.js';
 import type { ReuseOutcomeSummary, ReuseOutcomeEvent } from '../ops/reuseOutcomes.js';
 import type { PersonalityStore } from '../personality/store.js';
 import type { MemoryGraphProvider } from '../algo/memoryGraph.js';
+import { type LearningPacketSink, type TraceSink } from '../trace/learningTrace.js';
 export interface AutoExecTask {
     id: string;
     repo: string;
@@ -110,6 +111,20 @@ export interface AutoExecDeps {
     agent?: AgentRunner;
     /** Test/custom seam: inject git instead of spawning git. */
     git?: GitRunner;
+    /**
+     * Learning trace (Learning Ops slice 2): when set, each task run gets its own AgentRunTraceRecorder
+     * (traceId = the cycleId) emitting run.started/model.called/tool.failed/run.completed, and a
+     * LearningPacket draft is submitted here after the cycle. Best-effort: trace/packet failures never
+     * change the verdict. Omit → zero trace work, byte-identical to today.
+     */
+    learningTrace?: {
+        /** Where packet drafts go (file/memory/hub-adapter implementation). */
+        packetSink: LearningPacketSink;
+        /** Optional live per-event sink (e.g. FileTraceSink JSONL tail). */
+        traceSink?: TraceSink;
+        /** Hub packet sourceRepo column; default 'evolver-v2'. */
+        sourceRepo?: string;
+    };
 }
 export interface ForcedGeneFields {
     forcedGeneId?: unknown;

package/dist/exec/autoExec.js

@@ -11,6 +11,7 @@ import { intakeGene } from '../algo/geneIntake.js';
 import { runEvolutionCycle } from '../algo/orchestrator.js';
 import { makeSafeExecute, makeTrustedGeneResolver } from './autonomousCycle.js';
 import { findSignalHints } from './openPrRegistry.js';
+import { AgentRunTraceRecorder, buildLearningPacketDraft } from '../trace/learningTrace.js';
 /** Same path-containment as the bridge guard — used here to refuse before running anything (clean verdict). */
 function withinAllowlist(repo, roots) {
     const c = resolvePath(repo);
@@ -136,6 +137,20 @@ export async function runAutoExecTask(deps, rawTask, safety) {
     // that throws degrades to solving fresh (no hub candidates) rather than failing the task.
     let hubCandidates = [];
     const cycleId = `autoexec-${task.id}`;
+    // Learning trace (slice 2): one recorder per task run, traceId = cycleId so the trace joins the event log.
+    // Purely observational — every recorder call and the packet submit are wrapped so they can never change
+    // the verdict or fail the task.
+    const traceRecorder = deps.learningTrace
+        ? new AgentRunTraceRecorder({
+            runId: cycleId,
+            taskId: task.id,
+            ...(deps.learningTrace.traceSink ? { sink: deps.learningTrace.traceSink } : {}),
+        })
+        : undefined;
+    try {
+        traceRecorder?.runStarted({ taskSummary: task.expectedEffect, signals: cycleSignals, metadata: { repo: task.repo, target: task.target } });
+    }
+    catch { /* observability only */ }
     if (deps.hubReuse) {
         try {
             hubCandidates = await executableHubCandidates(deps, await deps.hubReuse(cycleSignals, { cycleId }));
@@ -153,6 +168,7 @@ export async function runAutoExecTask(deps, rawTask, safety) {
         ...(deps.personality ? { personality: deps.personality } : {}),
         ...(deps.agent ? { agent: deps.agent } : {}),
         ...(deps.git ? { git: deps.git } : {}),
+        ...(traceRecorder ? { traceRecorder } : {}),
     });
     const strategyName = task.strategyName ?? deps.strategyName;
     // Intentional semantics (see #308 review M1): a task carrying `strategy` — even without an
@@ -194,6 +210,24 @@ export async function runAutoExecTask(deps, rawTask, safety) {
     });
     const status = res.finalStage === 'solidified' ? 'solidified' : res.finalStage === 'failed' ? 'failed' : 'innovated';
     const cap = res.capsule;
+    if (traceRecorder && deps.learningTrace) {
+        try {
+            traceRecorder.runCompleted({
+                status: res.finalStage === 'solidified' ? 'success' : 'failed',
+                ...(cap?.outcome?.score !== undefined ? { score: cap.outcome.score } : {}),
+                ...(res.reasons.length > 0 ? { reason: res.reasons.join('; ') } : {}),
+                ...(res.producedValue !== undefined ? { producedValue: res.producedValue } : {}),
+                ...(res.failureKind !== undefined ? { failureKind: res.failureKind } : {}),
+            });
+            await deps.learningTrace.packetSink.submit(buildLearningPacketDraft(traceRecorder, {
+                sourceRepo: deps.learningTrace.sourceRepo ?? 'evolver-v2',
+                taskSummary: task.expectedEffect,
+                signals: cycleSignals,
+                environment: { repo: task.repo, runner: safety.runner ?? 'claude' },
+            }));
+        }
+        catch { /* packet delivery is best-effort; never fail the task */ }
+    }
     if (deps.memoryGraph && res.decision?.selectedGeneId && (res.finalStage === 'solidified' || res.finalStage === 'failed')) {
         const producedSuccess = res.finalStage === 'solidified' && res.producedValue === true;
         try {

package/dist/exec/autonomousCycle.d.ts

@@ -6,6 +6,7 @@ import type { GeneDecision } from '../algo/geneSelection.js';
 import type { ExecutionResult } from '../algo/cycleEngine.js';
 import { type GeneResolver, type ValidateHook, type AgentRunnerOptions, type RunnerName, type AgentRunner, type GitRunner } from './claudeBridge.js';
 import type { PersonalityStore } from '../personality/store.js';
+import type { AgentRunTraceRecorder } from '../trace/learningTrace.js';
 /**
  * Resolve a gene's strategy from the store and whether it is safe to EMBED into an autonomous agent's prompt —
  * the exec-side link from #30 (provenance ledger) and the review-state gate to #45 (requireTrustedGene gate). A
@@ -47,4 +48,6 @@ export declare function makeSafeExecute(repo: string, store: AssetStoreProvider,
     personality?: PersonalityStore;
     agent?: AgentRunner;
     git?: GitRunner;
+    /** Optional learning-trace recorder forwarded to the exec bridge (Learning Ops slice 2). */
+    traceRecorder?: AgentRunTraceRecorder;
 }): (mutation: Mutation, decision: GeneDecision) => Promise<ExecutionResult>;

package/dist/exec/autonomousCycle.js

@@ -67,6 +67,7 @@ export function makeSafeExecute(repo, store, safety, opts = {}) {
         enabled: true,
         ...(opts.agent ? { agent: opts.agent } : {}),
         ...(opts.git ? { git: opts.git } : {}),
+        ...(opts.traceRecorder ? { traceRecorder: opts.traceRecorder } : {}),
         allowedRoots: safety.allowedRoots,
         ...(safety.runner ? { runner: safety.runner } : {}),
         ...(safety.isolation === 'none' ? {} : { isolation: 'worktree' }),

package/dist/exec/claudeBridge.d.ts

@@ -3,6 +3,7 @@ import type { GeneDecision } from '../algo/geneSelection.js';
 import type { ExecutionResult } from '../algo/cycleEngine.js';
 import { type GeneStrategyInfo } from './prompt.js';
 import type { PersonalityStore } from '../personality/store.js';
+import type { AgentRunTraceRecorder } from '../trace/learningTrace.js';
 import { type AgentRunner, type AgentRunnerOptions, type RunnerName } from './runnerRegistry.js';
 export { resolveSpawnCommand, spawnCapture, DEFAULT_MAX_CAPTURE_BYTES, UnboundedSkipPermissionsError, UnsupportedCursorSkipPermissionsError, UnsupportedGeminiPermissionOptionsError, claudeRunnerArgs, makeClaudeHeadlessRunner, claudeHeadlessRunner, codexRunnerArgs, makeCodexHeadlessRunner, cursorRunnerArgs, makeCursorHeadlessRunner, getRunnerSpec, geminiRunnerArgs, makeGeminiHeadlessRunner, classifyGeminiRunnerResult, } from './runnerRegistry.js';
 export type { AgentRunContext, AgentRunResult, AgentRunner, RunnerName, AgentRunnerOptions, ClaudeRunnerOptions, CodexRunnerOptions, AgentRunnerSpec, } from './runnerRegistry.js';
@@ -86,6 +87,12 @@ export interface ExecBridgeOptions {
      * the store's default state (store.load never throws), it never fails the run.
      */
     personality?: PersonalityStore;
+    /**
+     * Optional learning-trace recorder (Learning Ops slice 2): when set, the bridge emits `model.called` around
+     * each agent spawn and `tool.failed`/`retry.attempted` metadata on failures. Best-effort observability — a
+     * recorder/sink failure must never affect the execution result, so every emission is wrapped defensively.
+     */
+    traceRecorder?: AgentRunTraceRecorder;
 }
 export declare class ExecBridgeDisabledError extends Error {
     constructor();

package/dist/exec/claudeBridge.js

@@ -429,6 +429,23 @@ export function makeClaudeExecBridge(opts) {
                 ...(opts.signal ? { signal: opts.signal } : {}),
             });
             observedRun = run;
+            // Learning trace (slice 2): one model.called per agent spawn — the headless runner is one opaque
+            // model-driven turn from the bridge's viewpoint (per-request fidelity arrives via the proxy's llm_turn
+            // records; recordLlmTurn folds those when a caller has them). Best-effort: never affects the result.
+            try {
+                opts.traceRecorder?.modelCalled({
+                    ...(opts.runner !== undefined ? { provider: opts.runner } : { provider: 'claude' }),
+                    ...(opts.agentOptions?.model !== undefined ? { model: opts.agentOptions.model } : {}),
+                    ...(run.exitCode !== undefined && run.exitCode !== null ? { stopReason: `exit_${run.exitCode}` } : {}),
+                });
+                if (!run.ok) {
+                    opts.traceRecorder?.toolFailed({
+                        toolName: 'agent_runner',
+                        error: run.error ?? run.failureKind ?? 'agent run failed',
+                    });
+                }
+            }
+            catch { /* trace emission is observability only */ }
             if (run.failureKind === 'cancelled' || opts.signal?.aborted)
                 throw new ExecBridgeRunCancelledError();
             // A worktree can contain three independent change surfaces after the agent exits: staged tracked changes,

package/dist/hub/capability.d.ts

@@ -111,6 +111,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 +210,10 @@ export interface RecipeCreateRequest {
     pricePerExecution?: number;
     currency?: string;
     maxConcurrent?: number;
+    idempotencyKey?: string;
+}
+export interface RecipePublishOptions {
+    idempotencyKey?: string;
 }
 export interface RecipeReceipt {
     recipeId?: string;
@@ -159,11 +232,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[];
@@ -231,6 +304,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/trace/index.d.ts

@@ -1,2 +1,3 @@
 export * from './trajectory.js';
-export * from './trajectoryExport.js';
+export * from './trajectoryExport.js';
+export * from './learningTrace.js';

package/dist/trace/index.js

@@ -1,2 +1,3 @@
 export * from './trajectory.js';
-export * from './trajectoryExport.js';
+export * from './trajectoryExport.js';
+export * from './learningTrace.js';

package/dist/trace/learningTrace.d.ts

@@ -0,0 +1,194 @@
+import type { Observer } from '../observers/observerBus.js';
+import type { TraceTurnDraft } from './trajectory.js';
+export declare const TRACE_EVENT_SCHEMA = "trace_event.v0";
+export declare const LEARNING_PACKET_SCHEMA = "learning_packet.v0";
+/** Lifecycle vocabulary for slice 1. Kept flat + closed so hub-side eventType stays queryable. */
+export declare const TRACE_EVENT_TYPES: readonly ["run.started", "run.completed", "model.called", "tool.called", "tool.failed", "retry.attempted", "reflection.recorded", "intervention.received"];
+export type TraceEventType = (typeof TRACE_EVENT_TYPES)[number];
+/** Mirrors hub LearningOpsTraceEvent columns (eventId/eventType/traceId/sessionId/taskId/sequence/occurredAt/payload/metadata). */
+export interface TraceEvent {
+    schemaVersion: typeof TRACE_EVENT_SCHEMA;
+    eventId: string;
+    eventType: TraceEventType;
+    /** Run-scoped trace id; every event of one agent run shares it. */
+    traceId: string;
+    sessionId?: string;
+    taskId?: string;
+    /** 1-based, strictly increasing per run — hub-side ordering key. */
+    sequence: number;
+    occurredAt: string;
+    payload: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+}
+export interface TraceSink {
+    emit(event: TraceEvent): void;
+}
+export declare class InMemoryTraceSink implements TraceSink {
+    readonly events: TraceEvent[];
+    emit(event: TraceEvent): void;
+}
+/** JSONL append sink for local inspection / offline replay. */
+export declare class FileTraceSink implements TraceSink {
+    private readonly path;
+    constructor(path: string);
+    emit(event: TraceEvent): void;
+}
+export declare class ConsoleTraceSink implements TraceSink {
+    private readonly log;
+    constructor(log?: (line: string) => void);
+    emit(event: TraceEvent): void;
+}
+export interface AgentRunTraceRecorderOptions {
+    /** Stable run identity; becomes traceId and the packet sourceRun. */
+    runId: string;
+    sessionId?: string;
+    taskId?: string;
+    sink?: TraceSink;
+    /** Injected clock for deterministic tests. */
+    now?: () => number;
+    /** Injected id factory for deterministic tests. */
+    eventIdFactory?: (sequence: number) => string;
+}
+export interface RunStartedInput {
+    taskSummary?: string;
+    signals?: readonly string[];
+    geneId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RunCompletedInput {
+    status: 'success' | 'failed';
+    score?: number;
+    reason?: string;
+    producedValue?: boolean;
+    failureKind?: string;
+}
+export interface ModelCalledInput {
+    provider?: string;
+    model?: string;
+    requestId?: string;
+    latencyMs?: number;
+    usage?: Record<string, unknown>;
+    stopReason?: string;
+}
+export interface ToolCalledInput {
+    toolName: string;
+    callId?: string;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface ToolFailedInput {
+    toolName: string;
+    callId?: string;
+    error: string;
+}
+export interface RetryInput {
+    attempt: number;
+    reason?: string;
+    target?: string;
+}
+export interface ReflectionInput {
+    outcome: string;
+    action?: string;
+    summary?: string;
+}
+export interface InterventionInput {
+    kind: string;
+    actorId?: string;
+    detail?: string;
+}
+/**
+ * Per-run trace recorder: the single hook surface the runtime calls at lifecycle points.
+ * Sequence numbers are assigned here (monotonic per run), so downstream ordering never depends on
+ * sink latency or clock resolution.
+ */
+export declare class AgentRunTraceRecorder {
+    private readonly opts;
+    private sequence;
+    private readonly recorded;
+    constructor(opts: AgentRunTraceRecorderOptions);
+    get events(): readonly TraceEvent[];
+    runStarted(input?: RunStartedInput): TraceEvent;
+    modelCalled(input?: ModelCalledInput): TraceEvent;
+    toolCalled(input: ToolCalledInput): TraceEvent;
+    toolFailed(input: ToolFailedInput): TraceEvent;
+    retryAttempted(input: RetryInput): TraceEvent;
+    reflectionRecorded(input: ReflectionInput): TraceEvent;
+    interventionReceived(input: InterventionInput): TraceEvent;
+    runCompleted(input: RunCompletedInput): TraceEvent;
+    /** Fold one normalized llm_turn (trace/trajectory.ts) into model.called + tool.called/tool.failed events. */
+    recordLlmTurn(turn: TraceTurnDraft): TraceEvent[];
+    private record;
+}
+/**
+ * Bypass-side bridge (never blocks the write path): maps the engine's existing root events onto the
+ * run's TraceEvent stream, so CycleEngine needs no code change for run start/completion, reflection,
+ * or human intervention coverage.
+ */
+export declare function learningTraceObserver(deps: {
+    recorder: AgentRunTraceRecorder;
+    timeoutMs?: number;
+}): Observer;
+export interface LearningPacketDraftInput {
+    /** e.g. 'evolver-v2'. Hub column sourceRepo. */
+    sourceRepo: string;
+    taskSummary?: string;
+    signals?: readonly string[];
+    environment?: Record<string, unknown>;
+}
+/** Local draft aligned with hub LearningOpsPacket ingest fields; placeholders are explicit, not implied. */
+export interface LearningPacketDraft {
+    schemaVersion: typeof LEARNING_PACKET_SCHEMA;
+    status: 'draft';
+    source: {
+        repo: string;
+        run: string;
+        type: 'agent_run';
+        id: string;
+    };
+    task: {
+        taskId: string | null;
+        summary: string | null;
+        signals: string[];
+    };
+    context: {
+        sessionId: string | null;
+        traceId: string;
+        environment: Record<string, unknown>;
+    };
+    trajectory: TraceEvent[];
+    artifacts: {
+        placeholder: true;
+        items: never[];
+    };
+    evaluation: {
+        placeholder: true;
+        outcomeStatus: 'success' | 'failed' | 'unknown';
+        verifier: null;
+        failureCategory: string | null;
+    };
+    governance: {
+        placeholder: true;
+        redactionStatus: 'metadata_only';
+        consentStatus: 'unknown';
+        trainingEligible: false;
+        retentionPolicy: 'standard';
+    };
+}
+export declare function buildLearningPacketDraft(recorder: AgentRunTraceRecorder, input: LearningPacketDraftInput): LearningPacketDraft;
+export interface LearningPacketSubmitResult {
+    accepted: boolean;
+    reason?: string;
+}
+export interface LearningPacketSink {
+    submit(draft: LearningPacketDraft): Promise<LearningPacketSubmitResult>;
+}
+export declare class InMemoryLearningPacketSink implements LearningPacketSink {
+    readonly drafts: LearningPacketDraft[];
+    submit(draft: LearningPacketDraft): Promise<LearningPacketSubmitResult>;
+}
+/** Writes one JSON file per run — the offline/no-hub path (and a manual-inspection artifact). */
+export declare class FileLearningPacketSink implements LearningPacketSink {
+    private readonly dir;
+    constructor(dir: string);
+    submit(draft: LearningPacketDraft): Promise<LearningPacketSubmitResult>;
+}