@evomap/evolver-core 2.0.0-beta.0

package/dist/schema/proofOfWork.d.ts

@@ -0,0 +1,97 @@
+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"]>;
+    gitDiff: z.ZodOptional<z.ZodObject<{
+        files: z.ZodNumber;
+        lines: z.ZodNumber;
+        patchRef: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        files: number;
+        lines: number;
+        patchRef?: string | undefined;
+    }, {
+        files: number;
+        lines: number;
+        patchRef?: string | undefined;
+    }>>;
+    artifactHash: z.ZodOptional<z.ZodObject<{
+        sha256: z.ZodString;
+        mime: z.ZodOptional<z.ZodString>;
+        size: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        sha256: string;
+        size: number;
+        mime?: string | undefined;
+    }, {
+        sha256: string;
+        size: number;
+        mime?: string | undefined;
+    }>>;
+    externalReceipt: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        receiptId: z.ZodString;
+        ts: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        receiptId: string;
+        ts: string;
+    }, {
+        provider: string;
+        receiptId: string;
+        ts: string;
+    }>>;
+    toolCallTrace: z.ZodOptional<z.ZodObject<{
+        calls: z.ZodNumber;
+        ref: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        calls: number;
+        ref?: string | undefined;
+    }, {
+        calls: number;
+        ref?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    kind: "git_diff" | "artifact_hash" | "external_receipt" | "tool_call_trace";
+    gitDiff?: {
+        files: number;
+        lines: number;
+        patchRef?: string | undefined;
+    } | undefined;
+    artifactHash?: {
+        sha256: string;
+        size: number;
+        mime?: string | undefined;
+    } | undefined;
+    externalReceipt?: {
+        provider: string;
+        receiptId: string;
+        ts: string;
+    } | undefined;
+    toolCallTrace?: {
+        calls: number;
+        ref?: string | undefined;
+    } | undefined;
+}, {
+    kind: "git_diff" | "artifact_hash" | "external_receipt" | "tool_call_trace";
+    gitDiff?: {
+        files: number;
+        lines: number;
+        patchRef?: string | undefined;
+    } | undefined;
+    artifactHash?: {
+        sha256: string;
+        size: number;
+        mime?: string | undefined;
+    } | undefined;
+    externalReceipt?: {
+        provider: string;
+        receiptId: string;
+        ts: string;
+    } | undefined;
+    toolCallTrace?: {
+        calls: number;
+        ref?: string | undefined;
+    } | undefined;
+}>;
+export type ProofOfWork = z.infer<typeof proofOfWork>;

package/dist/schema/proofOfWork.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** 产出证据 (批注#19): 解锁非 coding agent, 不再"无 git 变动=没产出". */
+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(),
+    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(),
+});

package/dist/schema/signal.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+/** 三层签名·工程层 (军杰 §4.2). camelCase (内部类型, schema §0 / 硬化 A10). */
+export declare const eventSignature: z.ZodString;
+/** 三层签名·领域层 (军杰 §4.3), 不含 gene_id. */
+export declare const problemSignature: z.ZodString;
+/** 选择压. 三条腿: 结构化强 / corpus 弱 / agent 自标 (批注#13). */
+export declare const signal: z.ZodObject<{
+    signalId: z.ZodString;
+    fromMaterial: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    kind: z.ZodEnum<["strong_structured", "weak_corpus", "agent_marked"]>;
+    text: z.ZodString;
+    score: z.ZodDefault<z.ZodNumber>;
+    eventSignature: z.ZodString;
+    problemSignature: z.ZodString;
+    signatureV: z.ZodDefault<z.ZodNumber>;
+    discoveredAt: z.ZodString;
+    extensions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    kind: "strong_structured" | "weak_corpus" | "agent_marked";
+    extensions: Record<string, unknown>;
+    signalId: string;
+    fromMaterial: string[];
+    text: string;
+    score: number;
+    eventSignature: string;
+    problemSignature: string;
+    signatureV: number;
+    discoveredAt: string;
+}, {
+    kind: "strong_structured" | "weak_corpus" | "agent_marked";
+    signalId: string;
+    text: string;
+    eventSignature: string;
+    problemSignature: string;
+    discoveredAt: string;
+    extensions?: Record<string, unknown> | undefined;
+    fromMaterial?: string[] | undefined;
+    score?: number | undefined;
+    signatureV?: number | undefined;
+}>;
+export type Signal = z.infer<typeof signal>;

package/dist/schema/signal.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import { ulid, extensions } from './common.js';
+/** 三层签名·工程层 (军杰 §4.2). camelCase (内部类型, schema §0 / 硬化 A10). */
+export const eventSignature = z.string();
+/** 三层签名·领域层 (军杰 §4.3), 不含 gene_id. */
+export const problemSignature = z.string();
+/** 选择压. 三条腿: 结构化强 / corpus 弱 / agent 自标 (批注#13). */
+export const signal = z.object({
+    signalId: ulid,
+    fromMaterial: z.array(ulid).default([]),
+    kind: z.enum(['strong_structured', 'weak_corpus', 'agent_marked']),
+    text: z.string(),
+    score: z.number().min(0).max(1).default(0),
+    eventSignature,
+    problemSignature,
+    signatureV: z.number().int().positive().default(1),
+    discoveredAt: z.string().datetime(),
+    extensions,
+});

package/dist/shadow/index.d.ts

@@ -0,0 +1,6 @@
+export * from './sink.js';
+export * from './jsonlSink.js';
+export * from './shadowHub.js';
+export * from './shadowStore.js';
+export * from './shadowMailbox.js';
+export * from './redact.js';

package/dist/shadow/index.js

@@ -0,0 +1,6 @@
+export * from './sink.js';
+export * from './jsonlSink.js';
+export * from './shadowHub.js';
+export * from './shadowStore.js';
+export * from './shadowMailbox.js';
+export * from './redact.js';

package/dist/shadow/jsonlSink.d.ts

@@ -0,0 +1,17 @@
+import { BaseShadowSink, type ShadowRecord } from './sink.js';
+/** append-only jsonl shadow 账本(WAL-safe append). 默认不存 payload 全文(只 payloadSize, M8-5). */
+export declare class JsonlShadowSink extends BaseShadowSink {
+    private readonly path;
+    constructor(path: string, nowFn?: () => number);
+    write(r: ShadowRecord): void;
+    readAll(): ShadowRecord[];
+}
+/** 完全不落账本(EVOLVER_SHADOW_TELEMETRY=off). seen/markSeen 仍维护(去重不依赖落盘). */
+export declare class NullShadowSink extends BaseShadowSink {
+    write(): void;
+}
+/** 内存账本(测试). */
+export declare class InMemoryShadowSink extends BaseShadowSink {
+    readonly records: ShadowRecord[];
+    write(r: ShadowRecord): void;
+}

package/dist/shadow/jsonlSink.js

@@ -0,0 +1,27 @@
+import { appendFileSync, mkdirSync, readFileSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { BaseShadowSink } from './sink.js';
+/** append-only jsonl shadow 账本(WAL-safe append). 默认不存 payload 全文(只 payloadSize, M8-5). */
+export class JsonlShadowSink extends BaseShadowSink {
+    path;
+    constructor(path, nowFn) {
+        super(nowFn);
+        this.path = path;
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    write(r) { appendFileSync(this.path, `${JSON.stringify(r)}\n`); }
+    readAll() {
+        if (!existsSync(this.path))
+            return [];
+        return readFileSync(this.path, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    }
+}
+/** 完全不落账本(EVOLVER_SHADOW_TELEMETRY=off). seen/markSeen 仍维护(去重不依赖落盘). */
+export class NullShadowSink extends BaseShadowSink {
+    write() { }
+}
+/** 内存账本(测试). */
+export class InMemoryShadowSink extends BaseShadowSink {
+    records = [];
+    write(r) { this.records.push(r); }
+}

package/dist/shadow/redact.d.ts

@@ -0,0 +1,11 @@
+import type { ShadowSink } from './sink.js';
+/** 脱敏(M8-5): 敏感文本(prompt/reasoning)截断 + sha256 短指纹, 不存全文. */
+export declare function redactText(s: string, keep?: number): string;
+export interface ShadowTelemetryEnv {
+    EVOLVER_SHADOW_TELEMETRY?: string;
+}
+/**
+ * 按 env 选 shadow sink(M8-5 默认最小披露可关):
+ * EVOLVER_SHADOW_TELEMETRY=off → NullShadowSink(完全不落账本); 否则 JsonlShadowSink(只存 payloadSize 不存全文).
+ */
+export declare function shadowSinkFromEnv(env: ShadowTelemetryEnv, ledgerPath: string, now?: () => number): ShadowSink;

package/dist/shadow/redact.js

@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+import { JsonlShadowSink, NullShadowSink } from './jsonlSink.js';
+/** 脱敏(M8-5): 敏感文本(prompt/reasoning)截断 + sha256 短指纹, 不存全文. */
+export function redactText(s, keep = 80) {
+    if (s.length <= keep)
+        return s;
+    const h = createHash('sha256').update(s).digest('hex').slice(0, 12);
+    return `${s.slice(0, keep)}…[+${s.length - keep}chars sha:${h}]`;
+}
+/**
+ * 按 env 选 shadow sink(M8-5 默认最小披露可关):
+ * EVOLVER_SHADOW_TELEMETRY=off → NullShadowSink(完全不落账本); 否则 JsonlShadowSink(只存 payloadSize 不存全文).
+ */
+export function shadowSinkFromEnv(env, ledgerPath, now) {
+    if ((env.EVOLVER_SHADOW_TELEMETRY ?? '').toLowerCase() === 'off')
+        return new NullShadowSink(now);
+    return new JsonlShadowSink(ledgerPath, now);
+}

package/dist/shadow/shadowHub.d.ts

@@ -0,0 +1,12 @@
+import type { HubCapability } from '../hub/capability.js';
+import type { ShadowSink, ShadowMode } from './sink.js';
+/**
+ * shadow 包 HubCapability(M8-1-shadow-c). shadow 下三类碰 hub 状态的动作只记录不执行:
+ * - publish → WOULD_PUBLISH, 返回**伪正常回执**(status:accepted/terminal:false), 否则 makeHubBindings
+ *   抛 PublishRejectedError 改 SyncEngine 异常/DLQ 路由污染对账(gotcha #1/#4)。
+ * - task.complete → WOULD_SETTLE(ATP 结算意图, money-safety 高敏)。
+ * - mailbox.push → WOULD_PUSH。
+ * 其余(fetch/search/mailbox.poll/ack/status/auth/capabilities)直通真 cap(只读不碰状态)。
+ * enforce 模式直接返回原 cap(零开销 pass-through, 秒级回滚)。
+ */
+export declare function shadowHubCapability(cap: HubCapability, sink: ShadowSink, mode: ShadowMode): HubCapability;

package/dist/shadow/shadowHub.js

@@ -0,0 +1,42 @@
+import { computeAssetId } from '../wire/index.js';
+/**
+ * shadow 包 HubCapability(M8-1-shadow-c). shadow 下三类碰 hub 状态的动作只记录不执行:
+ * - publish → WOULD_PUBLISH, 返回**伪正常回执**(status:accepted/terminal:false), 否则 makeHubBindings
+ *   抛 PublishRejectedError 改 SyncEngine 异常/DLQ 路由污染对账(gotcha #1/#4)。
+ * - task.complete → WOULD_SETTLE(ATP 结算意图, money-safety 高敏)。
+ * - mailbox.push → WOULD_PUSH。
+ * 其余(fetch/search/mailbox.poll/ack/status/auth/capabilities)直通真 cap(只读不碰状态)。
+ * enforce 模式直接返回原 cap(零开销 pass-through, 秒级回滚)。
+ */
+export function shadowHubCapability(cap, sink, mode) {
+    if (mode === 'enforce')
+        return cap;
+    return {
+        auth: cap.auth,
+        publish: async (bundle) => {
+            const assetIds = bundle.map((a) => computeAssetId(a) ?? 'sha256:unknown');
+            for (const a of bundle)
+                sink.record({ action: 'WOULD_PUBLISH', assetId: computeAssetId(a) ?? 'sha256:unknown', assetKind: a.type, payloadSize: JSON.stringify(a).length });
+            return { receiptId: `shadow-${(assetIds[0] ?? 'x').slice(7, 19)}`, status: 'accepted', assetId: assetIds[0], assetIds, bundleId: `shadow-bundle`, terminal: false };
+        },
+        fetch: (q) => cap.fetch(q),
+        search: (q) => cap.search(q),
+        task: {
+            claim: (taskId) => cap.task.claim(taskId), // claim 只读不碰结算, 直通
+            complete: async (claimId, result) => {
+                sink.record({ action: 'WOULD_SETTLE', claimId, payloadSize: JSON.stringify(result ?? null).length });
+                return { status: 'completed' };
+            },
+            subscribe: (f) => cap.task.subscribe(f),
+        },
+        mailbox: {
+            poll: () => cap.mailbox.poll(),
+            ack: (id) => cap.mailbox.ack(id),
+            status: () => cap.mailbox.status(),
+            push: async (e) => {
+                sink.record({ action: 'WOULD_PUSH', envelopeType: e.type, payloadSize: JSON.stringify(e.payload ?? null).length });
+            },
+        },
+        ...(cap.capabilities ? { capabilities: () => cap.capabilities() } : {}),
+    };
+}

package/dist/shadow/shadowMailbox.d.ts

@@ -0,0 +1,17 @@
+import { MailboxStore } from '../mailbox/store.js';
+import type { ShadowSink, ShadowMode } from './sink.js';
+/**
+ * shadow 包 MailboxStore(M8-1-shadow-d). MailboxStore 含 private db, wrapper 无法结构赋值 →
+ * **继承** override complete/fail: shadow 下记 WOULD_MAILBOX_* 但 SQL no-op(消息留 in_flight, enforce 可再处理)。
+ * markProcessed/isProcessed/getProcessed 继承真写(保 Dispatcher 幂等, gotcha #3); claim/send/state 等全继承真行为。
+ */
+export declare class ShadowMailboxStore extends MailboxStore {
+    private readonly sink;
+    private readonly mode;
+    constructor(opts: {
+        path: string;
+        busyTimeoutMs?: number;
+    }, sink: ShadowSink, mode: ShadowMode);
+    complete(id: string, now: number): void;
+    fail(id: string, err: string, now: number, maxAttempts?: number): void;
+}

package/dist/shadow/shadowMailbox.js

@@ -0,0 +1,25 @@
+import { MailboxStore } from '../mailbox/store.js';
+/**
+ * shadow 包 MailboxStore(M8-1-shadow-d). MailboxStore 含 private db, wrapper 无法结构赋值 →
+ * **继承** override complete/fail: shadow 下记 WOULD_MAILBOX_* 但 SQL no-op(消息留 in_flight, enforce 可再处理)。
+ * markProcessed/isProcessed/getProcessed 继承真写(保 Dispatcher 幂等, gotcha #3); claim/send/state 等全继承真行为。
+ */
+export class ShadowMailboxStore extends MailboxStore {
+    sink;
+    mode;
+    constructor(opts, sink, mode) {
+        super(opts);
+        this.sink = sink;
+        this.mode = mode;
+    }
+    complete(id, now) {
+        if (this.mode === 'enforce')
+            return super.complete(id, now);
+        this.sink.record({ action: 'WOULD_MAILBOX_COMPLETE' }); // no-op: 留 in_flight
+    }
+    fail(id, err, now, maxAttempts) {
+        if (this.mode === 'enforce')
+            return super.fail(id, err, now, maxAttempts);
+        this.sink.record({ action: 'WOULD_MAILBOX_FAIL' }); // no-op
+    }
+}

package/dist/shadow/shadowStore.d.ts

@@ -0,0 +1,18 @@
+import { type AssetStoreProvider, type AssetRecord, type AssetKind, type PutResult, type SearchQuery } from '../assetstore/provider.js';
+import type { ShadowSink, ShadowMode } from './sink.js';
+/**
+ * shadow 包 AssetStoreProvider(M8-1-shadow-d). shadow 下 put 只记录不真写,
+ * 但维护本地镜像(+sink.markSeen)使 cycle 内 capsule_id→event 引用链(A4)可见、重复 put 返 stored:false(gotcha #2)。
+ * get/search/list 合并真 store(只读) + shadow 镜像。enforce 直通真 store。
+ */
+export declare class ShadowAssetStore implements AssetStoreProvider {
+    private readonly inner;
+    private readonly sink;
+    private readonly mode;
+    private readonly mirror;
+    constructor(inner: AssetStoreProvider, sink: ShadowSink, mode: ShadowMode);
+    put(asset: AssetRecord): Promise<PutResult>;
+    get(assetId: string): Promise<AssetRecord | null>;
+    search(q: SearchQuery): Promise<AssetRecord[]>;
+    list(kind?: AssetKind, limit?: number): Promise<AssetRecord[]>;
+}

package/dist/shadow/shadowStore.js

@@ -0,0 +1,55 @@
+import { normalizeForPut } from '../assetstore/provider.js';
+/**
+ * shadow 包 AssetStoreProvider(M8-1-shadow-d). shadow 下 put 只记录不真写,
+ * 但维护本地镜像(+sink.markSeen)使 cycle 内 capsule_id→event 引用链(A4)可见、重复 put 返 stored:false(gotcha #2)。
+ * get/search/list 合并真 store(只读) + shadow 镜像。enforce 直通真 store。
+ */
+export class ShadowAssetStore {
+    inner;
+    sink;
+    mode;
+    mirror = new Map();
+    constructor(inner, sink, mode) {
+        this.inner = inner;
+        this.sink = sink;
+        this.mode = mode;
+    }
+    async put(asset) {
+        if (this.mode === 'enforce')
+            return this.inner.put(asset);
+        const { record, verified } = normalizeForPut(asset);
+        const already = this.sink.seen(record.asset_id) || this.mirror.has(record.asset_id);
+        this.sink.record({ action: 'WOULD_STORE_PUT', assetId: record.asset_id, assetKind: record.type, payloadSize: JSON.stringify(record).length });
+        if (!already) {
+            this.sink.markSeen(record.asset_id);
+            this.mirror.set(record.asset_id, record);
+        }
+        return { asset_id: record.asset_id, stored: !already, verified };
+    }
+    async get(assetId) {
+        return this.mirror.get(assetId) ?? this.inner.get(assetId);
+    }
+    async search(q) {
+        const real = await this.inner.search(q);
+        if (this.mode === 'enforce' || this.mirror.size === 0)
+            return real;
+        const seen = new Set(real.map((r) => r.asset_id));
+        const shadow = [...this.mirror.values()].filter((r) => !seen.has(r.asset_id) && matches(r, q));
+        return [...real, ...shadow];
+    }
+    async list(kind, limit = 1000) {
+        const real = await this.inner.list(kind, limit);
+        if (this.mode === 'enforce' || this.mirror.size === 0)
+            return real;
+        const seen = new Set(real.map((r) => r.asset_id));
+        const shadow = [...this.mirror.values()].filter((r) => !seen.has(r.asset_id) && (!kind || r.type === kind));
+        return [...real, ...shadow].slice(0, limit);
+    }
+}
+function matches(r, q) {
+    if (q.kind && r.type !== q.kind)
+        return false;
+    if (q.gene && r.gene !== q.gene)
+        return false;
+    return true;
+}

package/dist/shadow/sink.d.ts

@@ -0,0 +1,37 @@
+import type { AssetKind, PublishReceipt } from '../hub/capability.js';
+/** shadow 模式. 默认 'enforce'(=正常执行, decorator 退化 pass-through, 零开销秒级回滚). 'shadow'=只记录. */
+export type ShadowMode = 'shadow' | 'enforce';
+export type ShadowAction = 'WOULD_PUBLISH' | 'WOULD_SETTLE' | 'WOULD_PUSH' | 'WOULD_STORE_PUT' | 'WOULD_MAILBOX_COMPLETE' | 'WOULD_MAILBOX_FAIL' | 'WOULD_INGEST';
+/** WOULD-* 意图日志: shadow 下一切对线上有副作用的动作记录. payload 默认只存字节数(脱敏 M8-5). */
+export interface ShadowRecord {
+    seq: number;
+    at: number;
+    action: ShadowAction;
+    assetId?: string;
+    assetKind?: AssetKind;
+    envelopeType?: string;
+    claimId?: string;
+    payloadSize?: number;
+    /** v1 actual 对照槽(由对账器填, 非 sink 写). */
+    shadowReceipt?: Pick<PublishReceipt, 'status' | 'reason' | 'terminal'>;
+}
+/** shadow sink 抽象. 实现: JsonlShadowSink / NullShadowSink / InMemoryShadowSink. */
+export interface ShadowSink {
+    now(): number;
+    record(r: Omit<ShadowRecord, 'seq' | 'at'>): ShadowRecord;
+    /** 去重镜像(补偿 store.put 不真写导致内存索引缺失, gotcha #2). */
+    seen(assetId: string): boolean;
+    markSeen(assetId: string): void;
+}
+/** 内存镜像 + 序号基类(各 sink 复用). */
+export declare abstract class BaseShadowSink implements ShadowSink {
+    protected readonly nowFn: () => number;
+    protected seq: number;
+    private readonly mirror;
+    constructor(nowFn?: () => number);
+    now(): number;
+    abstract write(r: ShadowRecord): void;
+    record(r: Omit<ShadowRecord, 'seq' | 'at'>): ShadowRecord;
+    seen(assetId: string): boolean;
+    markSeen(assetId: string): void;
+}

package/dist/shadow/sink.js

@@ -0,0 +1,18 @@
+/** 内存镜像 + 序号基类(各 sink 复用). */
+export class BaseShadowSink {
+    nowFn;
+    seq = 0;
+    mirror = new Set();
+    constructor(nowFn = () => Date.now()) {
+        this.nowFn = nowFn;
+    }
+    now() { return this.nowFn(); }
+    record(r) {
+        this.seq += 1;
+        const full = { ...r, seq: this.seq, at: this.now() };
+        this.write(full);
+        return full;
+    }
+    seen(assetId) { return this.mirror.has(assetId); }
+    markSeen(assetId) { this.mirror.add(assetId); }
+}

package/dist/signals/cycleHistoryFromEvents.d.ts

@@ -0,0 +1,11 @@
+import type { CycleRecord } from './metaSignals.js';
+/** Minimal event shape this adapter consumes (a structural subset of RootEvent). */
+export interface CycleLogEvent {
+    type: string;
+    payload?: unknown;
+}
+/**
+ * Fold a window of root_events into per-cycle records (insertion order = chronological), suitable for
+ * {@link deriveCycleHistory}. Newest-last, matching deriveCycleHistory's window expectation.
+ */
+export declare function cycleRecordsFromEvents(events: readonly CycleLogEvent[]): CycleRecord[];

package/dist/signals/cycleHistoryFromEvents.js

@@ -0,0 +1,96 @@
+// Adapter: v2 root_event log → normalized CycleRecord[] for deriveCycleHistory / computeMetaSignals.
+// Mirrors how algo/cycleEngine.recentCycleOutcomes reads the log (cycle.solidified=success, cycle.failed=
+// failed), grouping per cycleId so each terminal cycle becomes one record. Kept separate from metaSignals.ts
+// so the meta-signal math stays a pure function over a clean shape and the v2-event coupling lives in one place.
+//
+// Field provenance from the v2 event payloads (see cycleEngine.ts):
+//  - status:     cycle.solidified → 'success', cycle.failed → 'failed'
+//  - intent:     mutation.built.payload.category (the cycle's GepCategory), if emitted
+//  - genesUsed:  decision.gene_selected.payload.selectedGeneId  ||  cycle.*.payload.gene
+//  - score:      cycle.*.payload.outcome.score
+//  - blastRadius:capsule.produced.payload.blastRadius, if emitted (else absent → not counted as empty)
+// Only terminal cycles (a cycle.solidified or cycle.failed) become records; in-flight cycles are skipped.
+function payloadObj(e) {
+    return e.payload && typeof e.payload === 'object' ? e.payload : {};
+}
+function cycleIdOf(p) {
+    return typeof p['cycleId'] === 'string' ? p['cycleId'] : undefined;
+}
+/**
+ * Fold a window of root_events into per-cycle records (insertion order = chronological), suitable for
+ * {@link deriveCycleHistory}. Newest-last, matching deriveCycleHistory's window expectation.
+ */
+export function cycleRecordsFromEvents(events) {
+    const byCycle = new Map();
+    const order = [];
+    const get = (id) => {
+        let a = byCycle.get(id);
+        if (!a) {
+            a = { terminal: false };
+            byCycle.set(id, a);
+            order.push(id);
+        }
+        return a;
+    };
+    for (const e of events) {
+        const p = payloadObj(e);
+        const id = cycleIdOf(p);
+        if (!id)
+            continue;
+        const a = get(id);
+        switch (e.type) {
+            case 'mutation.built': {
+                if (typeof p['category'] === 'string')
+                    a.intent = p['category'];
+                break;
+            }
+            case 'decision.gene_selected': {
+                if (typeof p['selectedGeneId'] === 'string')
+                    a.gene = p['selectedGeneId'];
+                break;
+            }
+            case 'capsule.produced': {
+                const br = p['blastRadius'];
+                if (br && typeof br === 'object') {
+                    const o = br;
+                    a.blastRadius = {
+                        ...(typeof o['files'] === 'number' ? { files: o['files'] } : {}),
+                        ...(typeof o['lines'] === 'number' ? { lines: o['lines'] } : {}),
+                    };
+                }
+                break;
+            }
+            case 'cycle.solidified':
+            case 'cycle.failed': {
+                a.terminal = true;
+                a.status = e.type === 'cycle.solidified' ? 'success' : 'failed';
+                if (typeof p['gene'] === 'string')
+                    a.gene = p['gene'];
+                const outcome = p['outcome'];
+                if (outcome && typeof outcome === 'object' && typeof outcome['score'] === 'number') {
+                    a.score = outcome['score'];
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    const records = [];
+    for (const id of order) {
+        const a = byCycle.get(id);
+        if (!a.terminal)
+            continue; // skip in-flight cycles
+        const rec = {};
+        if (a.intent !== undefined)
+            rec.intent = a.intent;
+        if (a.status !== undefined)
+            rec.outcome = { status: a.status, ...(a.score !== undefined ? { score: a.score } : {}) };
+        if (a.blastRadius !== undefined)
+            rec.blastRadius = a.blastRadius;
+        if (a.gene !== undefined)
+            rec.genesUsed = [a.gene];
+        records.push(rec);
+    }
+    return records;
+}

package/dist/signals/expand.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Expand a signal list into literal signals + namespace prefixes + semantic category tags.
+ * e.g. ['429', 'auth:token'] → ['429', 'auth:token', 'auth', 'problem:reliability', 'action:repair'].
+ */
+export declare function expandSignals(signals: readonly string[], extraText?: string): string[];
+/**
+ * Bag-of-words cosine similarity (0..1) between two free-text strings (ported from v1 scoreGeneSemantic).
+ * Term-frequency vectors, cosine of the angle. Returns 0 when either side has no tokens or they share none.
+ * This is the lexical-similarity recall path that complements {@link tagOverlapScore}'s curated tags:
+ * a signal 'timeout_slow' and a gene summarized "fix the slow timeout" share the 'timeout'/'slow' tokens
+ * even when neither the literal signal nor the expansion rules connect them.
+ */
+export declare function bagCosine(a: string, b: string): number;
+/** Inputs used to derive a gene's tag set. All optional so callers can pass whatever they have. */
+export interface GeneTagInput {
+    signalsMatch?: readonly string[];
+    category?: string;
+    geneId?: string;
+    summary?: string;
+}
+/** Expand a gene's category + signals_match + id + summary into its semantic tag set. */
+export declare function geneTags(gene: GeneTagInput): string[];
+/**
+ * Semantic tag overlap (0..1): fraction of the expanded SIGNAL tags that the gene's expanded tags cover.
+ * Normalized on the signal (query) side so a gene with a long id/summary is not penalized by noise.
+ * This is the recall component: '429' and a gene tagged 'error'/'repair' both expand to
+ * 'problem:reliability'/'action:repair', so they overlap even with zero literal string match.
+ *
+ * Known v1→v2 fidelity delta: a lone non-Latin signal caps near ~2/3 here — its raw token ('错误') is in the
+ * signal tag-set but never on the English-keyworded gene side, while an exact English signal short-circuits to
+ * 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;