@evomap/evolver-core 2.0.0-beta.19 → 2.0.0-beta.22

package/dist/schema/evolutionGraph.js

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+import { extensions, sha256Hash } from './common.js';
+export const EVOLUTION_GRAPH_SCHEMA_VERSION = '1.0.0';
+export const evolutionGraphNodeKinds = [
+    'prompt',
+    'code',
+    'spec',
+    'test',
+    'feedback',
+    'run',
+    'metric',
+    'variant',
+    'selection',
+];
+export const evolutionGraphEdgeKinds = [
+    'derivation',
+    'evaluated_by',
+    'regressed',
+    'fixed',
+    'selected',
+];
+export const evolutionGraphProvenanceKinds = [
+    'root_event',
+    'asset',
+    'material',
+    'review',
+    'cycle',
+    'workflow',
+    'runtime_trace',
+    'plugin',
+    'manual',
+];
+export const evolutionGraphNodeKind = z.enum(evolutionGraphNodeKinds);
+export const evolutionGraphEdgeKind = z.enum(evolutionGraphEdgeKinds);
+export const evolutionGraphProvenanceKind = z.enum(evolutionGraphProvenanceKinds);
+export const evolutionGraphNodeRef = z.string().min(1);
+export const evolutionGraphArtifactRef = z.object({
+    kind: z.enum(['asset', 'material', 'root_event', 'file', 'runtime_trace', 'plugin_resource']),
+    ref: z.string().min(1),
+    sha256: sha256Hash.optional(),
+});
+export const evolutionGraphMetricValue = z.object({
+    metric: z.string().min(1),
+    value: z.number(),
+    unit: z.string().min(1).optional(),
+    direction: z.enum(['higher_is_better', 'lower_is_better', 'target']).default('higher_is_better'),
+    target: z.number().optional(),
+});
+export const evolutionGraphMetricDelta = z.object({
+    metric: z.string().min(1),
+    before: z.number().optional(),
+    after: z.number(),
+    delta: z.number().optional(),
+    direction: z.enum(['improved', 'regressed', 'unchanged', 'unknown']).default('unknown'),
+});
+export const evolutionGraphNode = z.object({
+    id: evolutionGraphNodeRef,
+    kind: evolutionGraphNodeKind,
+    label: z.string().min(1),
+    createdAt: z.string().datetime(),
+    artifact: evolutionGraphArtifactRef.optional(),
+    metrics: z.array(evolutionGraphMetricValue).default([]),
+    summary: z.string().optional(),
+    tags: z.array(z.string().min(1)).default([]),
+    extensions,
+});
+export const evolutionGraphProvenance = z.object({
+    kind: evolutionGraphProvenanceKind,
+    ref: z.string().min(1),
+    capturedAt: z.string().datetime(),
+    actor: z.string().min(1).optional(),
+    digest: sha256Hash.optional(),
+    summary: z.string().optional(),
+});
+export const evolutionGraphEdge = z.object({
+    id: z.string().min(1),
+    kind: evolutionGraphEdgeKind,
+    from: evolutionGraphNodeRef,
+    to: evolutionGraphNodeRef,
+    createdAt: z.string().datetime(),
+    provenance: z.array(evolutionGraphProvenance).min(1),
+    metricDelta: evolutionGraphMetricDelta.optional(),
+    reason: z.string().min(1).optional(),
+    confidence: z.number().min(0).max(1).optional(),
+    extensions,
+});
+export const evolutionGraphDashboardSummary = z.object({
+    nodeCount: z.number().int().nonnegative(),
+    edgeCount: z.number().int().nonnegative(),
+    variantCount: z.number().int().nonnegative(),
+    selectedCount: z.number().int().nonnegative(),
+    regressionCount: z.number().int().nonnegative(),
+    fixedCount: z.number().int().nonnegative(),
+    evaluatedVariantCount: z.number().int().nonnegative(),
+    unevaluatedVariantCount: z.number().int().nonnegative(),
+    orphanEdgeCount: z.number().int().nonnegative(),
+    provenanceGapCount: z.number().int().nonnegative(),
+});
+export const evolutionGraph = z.object({
+    schemaVersion: z.literal(EVOLUTION_GRAPH_SCHEMA_VERSION).default(EVOLUTION_GRAPH_SCHEMA_VERSION),
+    graphId: z.string().min(1),
+    generatedAt: z.string().datetime(),
+    nodes: z.array(evolutionGraphNode),
+    edges: z.array(evolutionGraphEdge),
+    dashboard: evolutionGraphDashboardSummary.optional(),
+    extensions,
+}).superRefine((graph, ctx) => {
+    const nodesById = new Map();
+    for (const [index, node] of graph.nodes.entries()) {
+        if (nodesById.has(node.id)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['nodes', index, 'id'], message: 'duplicate evolution graph node id' });
+            continue;
+        }
+        nodesById.set(node.id, node.kind);
+    }
+    const edgeIds = new Set();
+    for (const [index, edge] of graph.edges.entries()) {
+        if (edgeIds.has(edge.id)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['edges', index, 'id'], message: 'duplicate evolution graph edge id' });
+        }
+        else {
+            edgeIds.add(edge.id);
+        }
+        const fromKind = nodesById.get(edge.from);
+        const toKind = nodesById.get(edge.to);
+        if (!fromKind)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['edges', index, 'from'], message: 'edge source node is missing' });
+        if (!toKind)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['edges', index, 'to'], message: 'edge target node is missing' });
+        if (!fromKind || !toKind)
+            continue;
+        validateEvolutionGraphEdgeShape(edge, fromKind, toKind, ctx, index);
+    }
+});
+export function deriveEvolutionGraphDashboardSummary(input) {
+    const variantIds = new Set(input.nodes.filter((node) => node.kind === 'variant').map((node) => node.id));
+    const evaluatedVariantIds = new Set();
+    let selectedCount = 0;
+    let regressionCount = 0;
+    let fixedCount = 0;
+    let orphanEdgeCount = 0;
+    let provenanceGapCount = 0;
+    const nodeIds = new Set(input.nodes.map((node) => node.id));
+    for (const edge of input.edges) {
+        if (!nodeIds.has(edge.from) || !nodeIds.has(edge.to))
+            orphanEdgeCount += 1;
+        if (edge.provenance.length === 0)
+            provenanceGapCount += 1;
+        if (edge.kind === 'evaluated_by' && variantIds.has(edge.from))
+            evaluatedVariantIds.add(edge.from);
+        if (edge.kind === 'selected')
+            selectedCount += 1;
+        if (edge.kind === 'regressed')
+            regressionCount += 1;
+        if (edge.kind === 'fixed')
+            fixedCount += 1;
+    }
+    return {
+        nodeCount: input.nodes.length,
+        edgeCount: input.edges.length,
+        variantCount: variantIds.size,
+        selectedCount,
+        regressionCount,
+        fixedCount,
+        evaluatedVariantCount: evaluatedVariantIds.size,
+        unevaluatedVariantCount: Math.max(0, variantIds.size - evaluatedVariantIds.size),
+        orphanEdgeCount,
+        provenanceGapCount,
+    };
+}
+function validateEvolutionGraphEdgeShape(edge, fromKind, toKind, ctx, edgeIndex) {
+    if (edge.kind === 'selected' && (fromKind !== 'variant' || toKind !== 'selection')) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['edges', edgeIndex, 'kind'], message: 'selected edges must connect variant -> selection' });
+    }
+    if (edge.kind === 'evaluated_by' && !['run', 'metric', 'test'].includes(toKind)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['edges', edgeIndex, 'to'], message: 'evaluated_by target must be run, metric, or test' });
+    }
+    if ((edge.kind === 'regressed' || edge.kind === 'fixed') && !['run', 'metric', 'test'].includes(toKind)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['edges', edgeIndex, 'to'], message: `${edge.kind} target must be run, metric, or test` });
+    }
+    if ((edge.kind === 'regressed' || edge.kind === 'fixed') && !edge.metricDelta) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['edges', edgeIndex, 'metricDelta'], message: `${edge.kind} edges require metricDelta` });
+    }
+    if (edge.kind === 'selected' && !edge.reason) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['edges', edgeIndex, 'reason'], message: 'selected edges require a reason' });
+    }
+}

package/dist/schema/index.d.ts

@@ -2,4 +2,5 @@ export * from './common.js';
 export * from './material.js';
 export * from './signal.js';
 export * from './problem.js';
+export * from './evolutionGraph.js';
 export * from './proofOfWork.js';

package/dist/schema/index.js

@@ -2,4 +2,5 @@ export * from './common.js';
 export * from './material.js';
 export * from './signal.js';
 export * from './problem.js';
+export * from './evolutionGraph.js';
 export * from './proofOfWork.js';

package/dist/schema/proofOfWork.d.ts

@@ -1,7 +1,55 @@
 import { z } from 'zod';
-/** 产出证据 (批注#19): 解锁非 coding agent, 不再"无 git 变动=没产出". */
 export declare const proofOfWork: z.ZodObject<{
     kind: z.ZodEnum<["git_diff", "artifact_hash", "external_receipt", "tool_call_trace"]>;
+    git_diff: z.ZodOptional<z.ZodObject<{
+        files: z.ZodOptional<z.ZodNumber>;
+        lines: z.ZodOptional<z.ZodNumber>;
+        patch_ref: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        files: z.ZodOptional<z.ZodNumber>;
+        lines: z.ZodOptional<z.ZodNumber>;
+        patch_ref: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        files: z.ZodOptional<z.ZodNumber>;
+        lines: z.ZodOptional<z.ZodNumber>;
+        patch_ref: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    artifact_hash: z.ZodOptional<z.ZodObject<{
+        sha256: z.ZodOptional<z.ZodString>;
+        mime: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        sha256: z.ZodOptional<z.ZodString>;
+        mime: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        sha256: z.ZodOptional<z.ZodString>;
+        mime: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    external_receipt: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        receipt_id: z.ZodOptional<z.ZodString>;
+        ts: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        provider: z.ZodOptional<z.ZodString>;
+        receipt_id: z.ZodOptional<z.ZodString>;
+        ts: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        provider: z.ZodOptional<z.ZodString>;
+        receipt_id: z.ZodOptional<z.ZodString>;
+        ts: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    tool_call_trace: z.ZodOptional<z.ZodObject<{
+        calls: z.ZodOptional<z.ZodNumber>;
+        ref: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        calls: z.ZodOptional<z.ZodNumber>;
+        ref: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        calls: z.ZodOptional<z.ZodNumber>;
+        ref: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
     gitDiff: z.ZodOptional<z.ZodObject<{
         files: z.ZodNumber;
         lines: z.ZodNumber;
@@ -34,12 +82,12 @@ export declare const proofOfWork: z.ZodObject<{
         ts: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         provider: string;
-        receiptId: string;
         ts: string;
+        receiptId: string;
     }, {
         provider: string;
-        receiptId: string;
         ts: string;
+        receiptId: string;
     }>>;
     toolCallTrace: z.ZodOptional<z.ZodObject<{
         calls: z.ZodNumber;
@@ -53,6 +101,25 @@ export declare const proofOfWork: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     kind: "git_diff" | "artifact_hash" | "external_receipt" | "tool_call_trace";
+    git_diff?: z.objectOutputType<{
+        files: z.ZodOptional<z.ZodNumber>;
+        lines: z.ZodOptional<z.ZodNumber>;
+        patch_ref: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    artifact_hash?: z.objectOutputType<{
+        sha256: z.ZodOptional<z.ZodString>;
+        mime: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    external_receipt?: z.objectOutputType<{
+        provider: z.ZodOptional<z.ZodString>;
+        receipt_id: z.ZodOptional<z.ZodString>;
+        ts: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    tool_call_trace?: z.objectOutputType<{
+        calls: z.ZodOptional<z.ZodNumber>;
+        ref: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
     gitDiff?: {
         files: number;
         lines: number;
@@ -65,8 +132,8 @@ export declare const proofOfWork: z.ZodObject<{
     } | undefined;
     externalReceipt?: {
         provider: string;
-        receiptId: string;
         ts: string;
+        receiptId: string;
     } | undefined;
     toolCallTrace?: {
         calls: number;
@@ -74,6 +141,25 @@ export declare const proofOfWork: z.ZodObject<{
     } | undefined;
 }, {
     kind: "git_diff" | "artifact_hash" | "external_receipt" | "tool_call_trace";
+    git_diff?: z.objectInputType<{
+        files: z.ZodOptional<z.ZodNumber>;
+        lines: z.ZodOptional<z.ZodNumber>;
+        patch_ref: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    artifact_hash?: z.objectInputType<{
+        sha256: z.ZodOptional<z.ZodString>;
+        mime: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    external_receipt?: z.objectInputType<{
+        provider: z.ZodOptional<z.ZodString>;
+        receipt_id: z.ZodOptional<z.ZodString>;
+        ts: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    tool_call_trace?: z.objectInputType<{
+        calls: z.ZodOptional<z.ZodNumber>;
+        ref: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
     gitDiff?: {
         files: number;
         lines: number;
@@ -86,12 +172,45 @@ export declare const proofOfWork: z.ZodObject<{
     } | undefined;
     externalReceipt?: {
         provider: string;
-        receiptId: string;
         ts: string;
+        receiptId: string;
     } | undefined;
     toolCallTrace?: {
         calls: number;
         ref?: string | undefined;
     } | undefined;
 }>;
-export type ProofOfWork = z.infer<typeof proofOfWork>;
+export type ProofOfWork = z.infer<typeof proofOfWork>;
+/** #961 兼容读: snake_case 优先, 旧别名只补齐部分迁移 payload 缺失的字段. */
+export declare function gitDiffOf(p: ProofOfWork | undefined): ProofOfWork['git_diff'] | ProofOfWork['gitDiff'] | undefined;
+export declare function artifactHashOf(p: ProofOfWork | undefined): ProofOfWork['artifact_hash'] | undefined;
+export declare function externalReceiptOf(p: ProofOfWork | undefined): ProofOfWork['external_receipt'] | ProofOfWork['externalReceipt'] | undefined;
+export declare function toolCallTraceOf(p: ProofOfWork | undefined): ProofOfWork['tool_call_trace'] | undefined;
+/** #961 写边界: 兼容读到的旧 camelCase proof 必须规范化后才能进入新 Capsule。 */
+export declare function proofOfWorkForWrite(p: ProofOfWork): ProofOfWork;
+/** Accept either canonical snake_case or legacy camelCase stored proof without lossy conversion. */
+export declare function normalizeProofOfWork(input: unknown): ProofOfWork | undefined;
+export interface WireProofOfWork {
+    kind: ProofOfWork['kind'];
+    git_diff?: {
+        files?: number;
+        lines?: number;
+        patch_ref?: string;
+    };
+    artifact_hash?: {
+        sha256?: string;
+        mime?: string;
+        size?: number;
+    };
+    external_receipt?: {
+        provider?: string;
+        receipt_id?: string;
+        ts?: string;
+    };
+    tool_call_trace?: {
+        calls?: number;
+        ref?: string;
+    };
+}
+/** Convert a proof to the gep-sdk wire shape while preserving canonical nested fields and extensions. */
+export declare function toWireProofOfWork(proof: ProofOfWork): WireProofOfWork;

package/dist/schema/proofOfWork.js

@@ -1,9 +1,107 @@
 import { z } from 'zod';
 /** 产出证据 (批注#19): 解锁非 coding agent, 不再"无 git 变动=没产出". */
+/**
+ * #961: 字段名对齐 gep-sdk 官方 capsule.schema.json(snake_case) —— evolver-core 曾是全生态唯一
+ * camelCase 偏离实现, 导致 Hub zod `.strip()` mutate payload 后 verifyAssetId 死锁、静态 proof
+ * 评估丢分。写路径一律 snake_case; camelCase 键仅为解析本地存量旧资产的兼容别名(不声明会被
+ * zod `.strip()` 剥掉 → canonicalize 漂移 → asset_id 对不上), 永不用于新写入, v3 major 移除。
+ */
+const nonnegativeInteger = z.number().int().nonnegative();
+const legacyInteger = z.number().int();
+const gitDiffWire = z.object({
+    files: nonnegativeInteger.optional(),
+    lines: nonnegativeInteger.optional(),
+    patch_ref: z.string().optional(),
+}).passthrough();
+const artifactHashWire = z.object({
+    sha256: z.string().optional(),
+    mime: z.string().optional(),
+    size: nonnegativeInteger.optional(),
+}).passthrough();
+const externalReceiptWire = z.object({
+    provider: z.string().optional(),
+    receipt_id: z.string().optional(),
+    ts: z.string().optional(),
+}).passthrough();
+const toolCallTraceWire = z.object({
+    calls: nonnegativeInteger.optional(),
+    ref: z.string().optional(),
+}).passthrough();
 export const proofOfWork = z.object({
     kind: z.enum(['git_diff', 'artifact_hash', 'external_receipt', 'tool_call_trace']),
-    gitDiff: z.object({ files: z.number().int(), lines: z.number().int(), patchRef: z.string().optional() }).optional(),
-    artifactHash: z.object({ sha256: z.string(), mime: z.string().optional(), size: z.number().int() }).optional(),
+    git_diff: gitDiffWire.optional(),
+    artifact_hash: artifactHashWire.optional(),
+    external_receipt: externalReceiptWire.optional(),
+    tool_call_trace: toolCallTraceWire.optional(),
+    // ── #961 兼容读别名(仅旧资产解析; 新写入禁止使用) ──
+    gitDiff: z.object({ files: legacyInteger, lines: legacyInteger, patchRef: z.string().optional() }).optional(),
+    artifactHash: z.object({ sha256: z.string(), mime: z.string().optional(), size: legacyInteger }).optional(),
     externalReceipt: z.object({ provider: z.string(), receiptId: z.string(), ts: z.string() }).optional(),
-    toolCallTrace: z.object({ calls: z.number().int(), ref: z.string().optional() }).optional(),
-});
+    toolCallTrace: z.object({ calls: legacyInteger, ref: z.string().optional() }).optional(),
+});
+/** #961 兼容读: snake_case 优先, 旧别名只补齐部分迁移 payload 缺失的字段. */
+export function gitDiffOf(p) {
+    const snake = p?.git_diff;
+    const legacy = p?.gitDiff;
+    if (!legacy)
+        return snake;
+    if (!snake)
+        return legacy;
+    return { files: legacy.files, lines: legacy.lines, ...(typeof legacy.patchRef === 'string' ? { patch_ref: legacy.patchRef } : {}), ...snake };
+}
+export function artifactHashOf(p) {
+    const snake = p?.artifact_hash;
+    const legacy = p?.artifactHash;
+    return legacy ? { ...legacy, ...snake } : snake;
+}
+export function externalReceiptOf(p) {
+    const snake = p?.external_receipt;
+    const legacy = p?.externalReceipt;
+    if (!legacy)
+        return snake;
+    if (!snake)
+        return legacy;
+    return { provider: legacy.provider, receipt_id: legacy.receiptId, ts: legacy.ts, ...snake };
+}
+export function toolCallTraceOf(p) {
+    const snake = p?.tool_call_trace;
+    const legacy = p?.toolCallTrace;
+    return legacy ? { ...legacy, ...snake } : snake;
+}
+function normalizeGitDiff(value) {
+    if (!value)
+        return undefined;
+    const raw = value;
+    const { patchRef, ...wire } = raw;
+    return { ...wire, ...(typeof raw.patch_ref === 'string' ? { patch_ref: raw.patch_ref } : typeof patchRef === 'string' ? { patch_ref: patchRef } : {}) };
+}
+function normalizeExternalReceipt(value) {
+    if (!value)
+        return undefined;
+    const raw = value;
+    const { receiptId, ...wire } = raw;
+    return { ...wire, ...(typeof raw.receipt_id === 'string' ? { receipt_id: raw.receipt_id } : typeof receiptId === 'string' ? { receipt_id: receiptId } : {}) };
+}
+/** #961 写边界: 兼容读到的旧 camelCase proof 必须规范化后才能进入新 Capsule。 */
+export function proofOfWorkForWrite(p) {
+    const { gitDiff: _gitDiff, artifactHash: _artifactHash, externalReceipt: _externalReceipt, toolCallTrace: _toolCallTrace, ...wire } = p;
+    const normalized = {
+        ...wire,
+        ...(gitDiffOf(p) ? { git_diff: normalizeGitDiff(gitDiffOf(p)) } : {}),
+        ...(artifactHashOf(p) ? { artifact_hash: artifactHashOf(p) } : {}),
+        ...(externalReceiptOf(p) ? { external_receipt: normalizeExternalReceipt(externalReceiptOf(p)) } : {}),
+        ...(toolCallTraceOf(p) ? { tool_call_trace: toolCallTraceOf(p) } : {}),
+    };
+    return proofOfWork.parse(normalized);
+}
+/** Accept either canonical snake_case or legacy camelCase stored proof without lossy conversion. */
+export function normalizeProofOfWork(input) {
+    const parsed = proofOfWork.safeParse(input);
+    return parsed.success ? parsed.data : undefined;
+}
+/** Convert a proof to the gep-sdk wire shape while preserving canonical nested fields and extensions. */
+export function toWireProofOfWork(proof) {
+    const normalized = proofOfWorkForWrite(proof);
+    const { kind, ...fields } = normalized;
+    return { kind: kind, ...fields };
+}

package/dist/shadow/shadowHub.js

@@ -38,5 +38,6 @@ export function shadowHubCapability(cap, sink, mode) {
             },
         },
         ...(cap.capabilities ? { capabilities: () => cap.capabilities() } : {}),
+        ...(cap.recipes ? { recipes: cap.recipes } : {}),
     };
 }

package/dist/signals/expand.d.ts

@@ -31,4 +31,18 @@ export declare function geneTags(gene: GeneTagInput): string[];
  * literal=1.0 upstream in expandedMatchScore. v1 #99 gave CJK full literal credit via pipe-aliases; v2 reaches
  * the right gene at ~2/3 strength. Lifting this to parity is a scoring-design change beyond this signal port.
  */
-export declare function tagOverlapScore(signals: readonly string[], gene: GeneTagInput): number;
+export declare function tagOverlapScore(signals: readonly string[], gene: GeneTagInput): number;
+export interface SemanticIdfDocument {
+    readonly tags: readonly string[];
+    readonly text: string;
+}
+export interface SemanticIdfProfile {
+    readonly documentCount: number;
+    readonly tagIdf: ReadonlyMap<string, number>;
+    readonly tokenIdf: ReadonlyMap<string, number>;
+    /** Deterministic, data-free identity for replaying the exact document-frequency profile. */
+    readonly version: string;
+}
+export declare function buildSemanticIdfProfile(documents: readonly SemanticIdfDocument[]): SemanticIdfProfile;
+export declare function idfTagOverlapScore(signals: readonly string[], gene: GeneTagInput, profile: SemanticIdfProfile): number;
+export declare function idfBagCosine(a: string, b: string, profile: SemanticIdfProfile): number;