agent-trellis 0.19.0 → 0.21.0

package/dist/evolve/jobRun.js

@@ -0,0 +1,273 @@
+/**
+ * 一次性作业的作业体(trellis-evolve 任务 11.5;14.1 fixture E2E 的流水
+ * 在此落地为生产入口)。作业体是下述 rule-based 治理流水;引擎内核
+ * (packages/evolve-engine 的 schedule/recursion/proposer/selection/judge)
+ * golden 锚定但生产未经此消费,待 L2/探针任务集接入(review-fixes 纠偏
+ * 旧注"作业即运行移植引擎"的名不副实)。
+ *
+ * 流水(顺序即依赖,与 fixtureE2e 同链):
+ *   0. 级别闸:没有任何 propose/auto-A 设置 → 零副作用返回(触发器只在
+ *      propose+ 拉起;这里是直接 spawn 的防御)。
+ *   1. 可选源探测(11.3):agent-bridge 缺席记 unavailable,不失败。
+ *   2. 信号合并(自上次作业的信号合并时刻以来;首次为全部,11.5"未
+ *      消费"语义)。
+ *   3. 检查发现:全局 + 信号层归属出现过/级别策略声明过的 workspace,
+ *      各自 `runChecks`(L1 的 doctor oracle)。观察面即发现面——只有
+ *      进过信号/策略的 workspace 会被扫描(与"信号是观察记录"一致)。
+ *   4. 提案草稿:rule-based 通道——`proposeFromSignals` 的信号对齐路径
+ *      ∪ 当前发现直接 `ruleBasedProposal`(同一内核、提案 id 同源
+ *      `rule-<findingId>` 天然去重;已入 pending 的跳过)。editor/spawn
+ *      通道(design D7)在 `runDelegatedCall` 就绪前不在作业里拉真实
+ *      CLI 会话,见 `ProposalChannelAvailability` 注释。
+ *   5. 逐草稿治理:域分派(配置类才进通道)→ 机械校验(无 editor 不
+ *      重试)→ L1 前闸(verdict 差集,唯一 verdict)→ 风险分类(不采信
+ *      自报)→ 采纳门(A 仅 auto-A 且闸通过自动采纳并通知;B 永远待批)。
+ *      草稿的提案/采纳级别按其目标层解析(workspace > default;agent
+ *      粒度只闸观察与触发,不进提案产出——提案的来源 agent 不可考,
+ *      发现是 doctor 检查面而非 agent 行为)。
+ *   6. 应用阶段(12.5):全部已批准未应用的编辑在同一备份会话写入;
+ *      按 delivery 分类对原生渲染 agent 触发同步(host 门面 `triggerRenderSync`)。
+ *   7. lesson(12.6):本次应用的每条提案蒸馏一条 lesson;记忆启用走
+ *      记忆管道,否则只留档案(skipped 不是 failed)。
+ *
+ * 每步都只经 `src/host/*` 门面与本目录模块(边界 10.3);无模型调用、
+ * 不 spawn 真实 agent CLI。摘要返回给 jobMain 并入 job-run 档案。
+ */
+import { classifyManagedObservation, isMemoryDeliveryEnabled, loadEvolveLevelPolicy, resolveEvolveLevel, runChecks, triggerRenderSync, } from "../host/index.js";
+import { appendArchiveRecord, readArchiveRecords } from "./archive.js";
+import { applyApprovedProposals } from "./apply.js";
+import { dispatchProposalDomain, evaluateL1Proposal } from "./gate.js";
+import { recordLesson } from "./lesson.js";
+import { decideProposal, enqueueProposal, readPendingRecord, readPendingRecords, safeProposalFileName, } from "./pending.js";
+import { proposeFromSignals, ruleBasedProposal } from "./propose.js";
+import { readAllSignals } from "./recorder.js";
+import { classifyProposalRisk, evaluateAdoptionGate, retargetNotificationRollback } from "./risk.js";
+import { probeAgentBridgeSource } from "./sources.js";
+import { PROPOSAL_ARCHIVE_KIND, lastSignalWatermarkMs, } from "./trigger.js";
+import { validateProposalWithRetry } from "./validate.js";
+/** 作业级闸:任一粒度出现 propose/auto-A 才值得运行(observe 只采集)。
+ * `trellis evolve run` 的早退判定与作业体同源(1.3)。 */
+export function anyProposalLevel(policy) {
+    const levels = [
+        policy.defaultLevel,
+        ...Object.values(policy.agents),
+        ...Object.values(policy.workspaces),
+    ];
+    return levels.some((level) => level === "propose" || level === "auto-A");
+}
+/** 草稿目标层的生效级别(workspace > agent > default > off)。 */
+function draftLevel(policy, layer) {
+    return resolveEvolveLevel(policy, layer.kind === "workspace" ? { workspaceRoot: layer.root } : {});
+}
+/** 缺省草稿组装:信号对齐 ∪ 当前发现直提,id 同源去重。 */
+function defaultPropose(input) {
+    // editor/spawn 通道就绪前,生产走 rule-based 兜底(design D7:委派不可
+    // 用时 doctor finding 形态信号走 rule-based)。ruleBasedProposal 是
+    // proposeFromSignals 的同一内核;这里补上"无对齐信号但发现仍在"的条目
+    // ——发现由作业的 runChecks 观察(9.4①:doctor/sync 检查即原生渲染
+    // agent 的信号来源),生产信号面里事件信号 stableId 恒为 null。
+    const loop = proposeFromSignals({
+        signals: input.signals,
+        findings: input.findings,
+        availability: { delegate: false, spawn: false },
+        now: input.now,
+    });
+    const drafts = [...loop.proposals];
+    const covered = new Set(drafts.map((draft) => draft.id));
+    for (const entry of input.findings) {
+        const draft = ruleBasedProposal(entry, { now: input.now });
+        if (draft === null || covered.has(draft.id))
+            continue;
+        covered.add(draft.id);
+        drafts.push(draft);
+    }
+    return drafts;
+}
+/** 上一作业的信号水位线(优先"信号合并时刻",旧档案回退 endedAtMs);
+ * 从未跑过为 null。 */
+function lastSignalWatermark(homeDir) {
+    return lastSignalWatermarkMs(readArchiveRecords(homeDir));
+}
+export async function runEvolveJob(homeDir, options = {}) {
+    const now = options.now ?? Date.now;
+    const empty = {
+        signalsConsidered: 0,
+        findingsConsidered: 0,
+        draftCount: 0,
+        enqueuedIds: [],
+        autoAdoptedIds: [],
+        discarded: [],
+        skippedNotes: [],
+        applied: { runId: null, appliedProposalIds: [], syncExitCode: null, syncError: null, effects: [] },
+        lessonIds: [],
+        notices: [],
+        optionalSources: [],
+        signalsMergedAtMs: null,
+    };
+    // ── 0. 级别闸 ─────────────────────────────────────────────────────────
+    const policy = loadEvolveLevelPolicy(homeDir);
+    if (!anyProposalLevel(policy))
+        return empty;
+    // ── 1. 可选源探测(缺席合法,记状态不失败)────────────────────────────
+    const optionalSources = [probeAgentBridgeSource(homeDir)];
+    // ── 2. 信号合并(自上次作业的信号水位线以来)────────────────────────
+    const signalsMergedAtMs = now();
+    const signals = readAllSignals(homeDir, lastSignalWatermark(homeDir));
+    // ── 3. 检查发现(全局 + 观察面内的 workspace)────────────────────────
+    const workspaceRoots = new Set();
+    for (const signal of signals) {
+        if (signal.layer.kind === "workspace")
+            workspaceRoots.add(signal.layer.root);
+    }
+    for (const root of Object.keys(policy.workspaces))
+        workspaceRoots.add(root);
+    const findingsById = new Map();
+    const runOne = async (runOptions) => {
+        const result = await runChecks(runOptions);
+        for (const entry of result.entries)
+            findingsById.set(entry.id, entry);
+    };
+    await runOne({ homeDir });
+    for (const root of workspaceRoots)
+        await runOne({ homeDir, workspaceRoot: root });
+    const findings = [...findingsById.values()];
+    // ── 4. 提案草稿 ───────────────────────────────────────────────────────
+    const proposeFn = options.proposeFn ?? defaultPropose;
+    const drafts = proposeFn({ homeDir, signals, findings, now });
+    // ── 5. 逐草稿治理 ─────────────────────────────────────────────────────
+    const enqueuedIds = [];
+    const autoAdoptedIds = [];
+    const discarded = [];
+    const skippedNotes = [];
+    const notices = [];
+    // 自动采纳通知先收集、应用后定稿:决策时备份会话尚不存在,回滚行只能
+    // 是泛化占位,拿到真实 runId 再重写(review-fixes ❌5)。
+    const adoptedNotifications = [];
+    const known = new Set(readPendingRecords(homeDir).map((record) => record.id));
+    for (const draft of drafts) {
+        if (known.has(draft.id)) {
+            skippedNotes.push(`${draft.id}:已有提案记录,不重复产出`);
+            continue;
+        }
+        const level = draftLevel(policy, draft.layer);
+        if (level !== "propose" && level !== "auto-A") {
+            skippedNotes.push(`${draft.id}:目标层级别 ${level},不产出提案`);
+            continue;
+        }
+        const domain = dispatchProposalDomain(draft.kind);
+        if (!domain.entersProposalChannel) {
+            skippedNotes.push(`${draft.id}:${domain.note}`);
+            continue;
+        }
+        const validated = await validateProposalWithRetry({ homeDir, proposal: draft, now });
+        if (validated.status === "discarded") {
+            discarded.push({ id: draft.id, code: validated.code, reason: validated.reason });
+            continue;
+        }
+        const proposal = validated.proposal;
+        const evaluateL1 = options.evaluateL1Fn ?? evaluateL1Proposal;
+        const gate = await evaluateL1({
+            homeDir,
+            workspaceRoot: proposal.layer.kind === "workspace" ? proposal.layer.root : null,
+            proposal,
+            now,
+        });
+        const classification = classifyProposalRisk(proposal, {
+            homeDir,
+            ...(validated.validation.needsExplicitApproval !== undefined
+                ? { needsExplicitApproval: validated.validation.needsExplicitApproval }
+                : {}),
+        });
+        const adoption = evaluateAdoptionGate({
+            level,
+            classification,
+            probePassed: gate.decision === "acceptable",
+            proposal,
+        });
+        if (gate.decision !== "acceptable") {
+            skippedNotes.push(`${proposal.id}:L1 前闸不可采纳(${gate.reason})`);
+            continue;
+        }
+        enqueueProposal({
+            homeDir,
+            proposal,
+            riskClass: classification.riskClass,
+            riskRuleId: classification.ruleId,
+            now,
+        });
+        appendArchiveRecord(homeDir, {
+            kind: PROPOSAL_ARCHIVE_KIND,
+            payload: { proposalId: proposal.id, riskClass: classification.riskClass, riskRuleId: classification.ruleId },
+        }, () => new Date(now()));
+        known.add(proposal.id);
+        if (adoption.action === "auto-adopt") {
+            decideProposal({ homeDir, id: proposal.id, decision: "approved", now });
+            autoAdoptedIds.push(proposal.id);
+            adoptedNotifications.push(adoption.notification);
+        }
+        else {
+            enqueuedIds.push(proposal.id);
+        }
+    }
+    // ── 6. 应用阶段(全部已批准未应用,同一备份会话)──────────────────────
+    const agents = options.applyAgents ?? classifyManagedObservation(homeDir).map((entry) => ({
+        agent: entry.agent,
+        observation: entry.observation,
+    }));
+    const triggerSync = options.triggerSync ?? (async () => await triggerRenderSync({ homeDir }));
+    const applied = await applyApprovedProposals({
+        homeDir,
+        agents,
+        triggerSync,
+        now: () => new Date(now()),
+    });
+    for (const id of applied.skippedInvalidIds) {
+        skippedNotes.push(`${id}:应用前重校验不通过(pending 磁盘状态漂移?),跳过`);
+    }
+    // 自动采纳通知定稿:回滚行重写为真实备份会话标识(应用失败/未开会话时
+    // 保留泛化占位——没有真实 runId 可指)。
+    for (const notification of adoptedNotifications) {
+        notices.push(applied.runId === null
+            ? notification.message
+            : retargetNotificationRollback(notification, `trellis evolve rollback ${applied.runId}`).message);
+    }
+    // ── 7. lesson(本次应用的每条提案蒸馏一条)───────────────────────────
+    const memoryEnabled = isMemoryDeliveryEnabled(homeDir);
+    const lessonIds = [];
+    for (const id of applied.appliedProposalIds) {
+        const record = readPendingRecord(homeDir, id);
+        if (record === null)
+            continue;
+        const lesson = {
+            id: `lesson-${safeProposalFileName(id)}`,
+            createdAt: now(),
+            cue: record.proposal.summary,
+            body: `应用阶段已写入备份会话 ${applied.runId ?? "?"}(风险 ${record.riskClass});` +
+                `编辑:${record.proposal.edits.map((edit) => `${edit.op} ${edit.path}`).join("; ")}(kind ${record.proposal.kind})。`,
+            evidence: record.proposal.evidence,
+            layer: record.proposal.layer,
+        };
+        recordLesson({ homeDir, lesson, memoryEnabled });
+        lessonIds.push(lesson.id);
+    }
+    return {
+        signalsConsidered: signals.length,
+        findingsConsidered: findings.length,
+        draftCount: drafts.length,
+        enqueuedIds,
+        autoAdoptedIds,
+        discarded,
+        skippedNotes,
+        applied: {
+            runId: applied.runId,
+            appliedProposalIds: applied.appliedProposalIds,
+            syncExitCode: applied.syncExitCode,
+            syncError: applied.syncError,
+            effects: applied.effects,
+        },
+        lessonIds,
+        notices,
+        optionalSources,
+        signalsMergedAtMs,
+    };
+}

package/dist/evolve/jobShell.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 作业壳(trellis-evolve-run-backfill 任务 1.1)。
+ *
+ * jobMain(detached 入口)与 `trellis evolve run`(前台手动触发)共享的
+ * 一次作业运行外壳:抢锁 → 跑作业体 → 落 job-run 档案 → 释锁,错误收口
+ * (失败也落档案——不落档案会让水位线与冷却都不推进,同一确定性错误在
+ * 每次会话结束被立即重拉成崩溃循环)。job-run payload 带 `trigger` 触发
+ * 来源(`event` / `manual` / `chain`);旧档案无该字段时消费端视作 `event`。
+ *
+ * 本模块只做壳:作业体在 `jobRun.js`(rule-based 治理流水),锁与档案
+ * 原语在 `trigger.js`。jobMain 仍是唯一 detached 入口(链起用),CLI
+ * 前台调用本壳即手动触发(D1:不另写执行路径)。
+ */
+import { type EvolveJobSummary } from "./jobRun.js";
+import { type JobTriggerKind, type TryLaunchJobOptions } from "./trigger.js";
+/** 触发来源(单一来源在 trigger.js;此处 re-export 保持壳类型面完整)。 */
+export type { JobTriggerKind } from "./trigger.js";
+export interface RunJobShellOptions {
+    /** 触发来源,入 job-run 档案。 */
+    readonly trigger: JobTriggerKind;
+    /** 持锁 N 毫秒后再跑作业体(jobMain `--hold-ms` 测试缝;生产不传)。 */
+    readonly holdMs?: number;
+    /** 时间源(毫秒);缺省 Date.now(测试注入固定时钟)。 */
+    readonly now?: () => number;
+    /** 补跑链起的作业命令/ spawn 注入缝(测试);缺省真实 jobMain 与 spawn。 */
+    readonly chainJobCommand?: TryLaunchJobOptions["jobCommand"];
+    readonly chainSpawnFn?: TryLaunchJobOptions["spawnFn"];
+}
+export type RunJobShellResult = 
+/** 抢锁失败:已有作业在跑(竞态窗口),不做任何工作、不排队。 */
+{
+    readonly status: "lock-busy";
+} | {
+    readonly status: "ok";
+    readonly summary: EvolveJobSummary;
+}
+/** 作业体抛错:job-run 档案已落 error 记录(推进冷却)。 */
+ | {
+    readonly status: "error";
+    readonly message: string;
+};
+/**
+ * 跑一次作业(壳语义):锁由本壳持有,收尾无论成败都释锁并落 job-run。
+ * lock-busy 时不落任何档案(一次根本没发生的运行不在档案说谎)。
+ */
+export declare function runJobShell(homeDir: string, options: RunJobShellOptions): Promise<RunJobShellResult>;

package/dist/evolve/jobShell.js

@@ -0,0 +1,75 @@
+/**
+ * 作业壳(trellis-evolve-run-backfill 任务 1.1)。
+ *
+ * jobMain(detached 入口)与 `trellis evolve run`(前台手动触发)共享的
+ * 一次作业运行外壳:抢锁 → 跑作业体 → 落 job-run 档案 → 释锁,错误收口
+ * (失败也落档案——不落档案会让水位线与冷却都不推进,同一确定性错误在
+ * 每次会话结束被立即重拉成崩溃循环)。job-run payload 带 `trigger` 触发
+ * 来源(`event` / `manual` / `chain`);旧档案无该字段时消费端视作 `event`。
+ *
+ * 本模块只做壳:作业体在 `jobRun.js`(rule-based 治理流水),锁与档案
+ * 原语在 `trigger.js`。jobMain 仍是唯一 detached 入口(链起用),CLI
+ * 前台调用本壳即手动触发(D1:不另写执行路径)。
+ */
+import { loadEvolveLevelPolicy } from "../host/index.js";
+import { appendArchiveRecord } from "./archive.js";
+import { runEvolveJob } from "./jobRun.js";
+import { acquireJobLock, chainAfterJob, consumeRunRequest, releaseJobLock, JOB_RUN_KIND, } from "./trigger.js";
+/**
+ * 跑一次作业(壳语义):锁由本壳持有,收尾无论成败都释锁并落 job-run。
+ * lock-busy 时不落任何档案(一次根本没发生的运行不在档案说谎)。
+ */
+export async function runJobShell(homeDir, options) {
+    const now = options.now ?? Date.now;
+    const pid = process.pid;
+    if (!acquireJobLock(homeDir, pid, now())) {
+        return { status: "lock-busy" };
+    }
+    // 任何作业启动即清补跑标记(D3:该请求已被本次运行满足)。
+    consumeRunRequest(homeDir);
+    const startedAtMs = now();
+    try {
+        if (options.holdMs !== undefined && options.holdMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, options.holdMs));
+        }
+        const summary = await runEvolveJob(homeDir, { now });
+        appendArchiveRecord(homeDir, {
+            kind: JOB_RUN_KIND,
+            payload: {
+                pid,
+                startedAtMs,
+                endedAtMs: now(),
+                trigger: options.trigger,
+                signalsMergedAtMs: summary.signalsMergedAtMs,
+                summary,
+            },
+        });
+        return { status: "ok", summary };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        try {
+            appendArchiveRecord(homeDir, {
+                kind: JOB_RUN_KIND,
+                payload: { pid, startedAtMs, endedAtMs: now(), trigger: options.trigger, error: message },
+            });
+        }
+        catch {
+            // 档案写入自身失败(如磁盘满)时不再连锁,锁仍由 finally 释放。
+        }
+        return { status: "error", message };
+    }
+    finally {
+        releaseJobLock(homeDir, pid);
+        // 收尾(释锁后)消费补跑标记并链起至多一次补跑(D3):运行期间到达的
+        // 请求塌缩为一个标记,在这里被消费;无标记不链。
+        const policy = loadEvolveLevelPolicy(homeDir);
+        chainAfterJob({
+            homeDir,
+            now,
+            ...(policy.trigger !== undefined ? { limits: policy.trigger } : {}),
+            ...(options.chainJobCommand !== undefined ? { jobCommand: options.chainJobCommand } : {}),
+            ...(options.chainSpawnFn !== undefined ? { spawnFn: options.chainSpawnFn } : {}),
+        });
+    }
+}

package/dist/evolve/l2.d.ts

@@ -0,0 +1,93 @@
+/**
+ * L2 匿名前后对比记录协议(trellis-evolve 任务 13.1)。
+ *
+ * spec"匿名前后对比记录协议(L2)":内容类对比的比较记录以类型化档案
+ * 格式持久化——baseline 与候选各自的运行标识、冻结的交付物引用、按
+ * 任务设种子的匿名标识映射、选择器结果与失败收口的 verdict;base 保留在
+ * 比较中;记录格式表达两种收口:选中 baseline ⟹ 不采纳,选择器失败 ⟹
+ * invalid。本模块只定义记录格式与边界;选择器执行(运行比较与裁决)不
+ * 在本期范围。
+ *
+ * 匿名性:呈现给选择器的匿名标识(anonId)由任务种子 + 运行标识派生,
+ * 本身不含角色词;选择器视图(`presentL2Arms`)只给 anonId 与冻结交付
+ * 物引用,不带 role/runId。角色映射只存在于档案(审计用)。
+ */
+import type { ArchiveEntry } from "./archive.js";
+/** 运行档案 kind:一条 L2 比较记录。 */
+export declare const L2_COMPARISON_ARCHIVE_KIND = "l2-comparison";
+export type L2ArmRole = "baseline" | "candidate";
+/** 冻结的交付物引用:标签 + 内容摘要键(切片任何变化即键变)。 */
+export interface L2FrozenArtifact {
+    readonly label: string;
+    readonly digest: string;
+}
+export interface L2Arm {
+    /** 种子派生的匿名标识(呈现面);不含角色词。 */
+    readonly anonId: string;
+    /** 该臂自己的运行标识。 */
+    readonly runId: string;
+    readonly role: L2ArmRole;
+    readonly artifacts: readonly L2FrozenArtifact[];
+}
+/** 按任务设种子:每条探针任务一个种子,匿名标识由此派生。 */
+export interface L2TaskSeed {
+    readonly task: string;
+    readonly seed: string;
+}
+export type L2SelectorResult = {
+    readonly status: "selected";
+    readonly anonId: string;
+} | {
+    readonly status: "failed";
+    readonly reason: string;
+};
+/** 失败收口的 verdict:
+ *   - selected baseline → not-adopted(不采纳);
+ *   - 选择器失败 / 任一臂未交付 → invalid(同样不采纳,收口形态不同)。 */
+export type L2Verdict = {
+    readonly kind: "adopt-candidate";
+    readonly anonId: string;
+} | {
+    readonly kind: "not-adopted-baseline";
+    readonly anonId: string;
+} | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+export interface L2ComparisonRecord {
+    readonly comparisonId: string;
+    readonly createdAt: number;
+    readonly taskSeeds: readonly L2TaskSeed[];
+    /** baseline 与候选全在(base 留池,13.2 的偏差在引擎侧,记录层照存)。 */
+    readonly arms: readonly L2Arm[];
+    readonly selector: L2SelectorResult;
+    readonly verdict: L2Verdict;
+}
+/**
+ * 匿名标识:按任务种子 + 运行标识派生的稳定短哈希。构造上不可能
+ * 含角色词——呈现面与档案里的值同源,泄露面为零。
+ */
+export declare function anonArmId(taskSeeds: readonly L2TaskSeed[], runId: string): string;
+export interface BuildL2ComparisonInput {
+    readonly comparisonId: string;
+    readonly createdAt: number;
+    readonly taskSeeds: readonly L2TaskSeed[];
+    /** 每臂运行标识 + 角色 + 冻结交付物;anonId 由本函数派生。 */
+    readonly arms: readonly {
+        readonly runId: string;
+        readonly role: L2ArmRole;
+        readonly artifacts: readonly L2FrozenArtifact[];
+    }[];
+    readonly selector: L2SelectorResult;
+}
+/** 由臂与选择器结果构建完整记录(派生匿名映射 + 失败收口 verdict)。 */
+export declare function buildL2Comparison(input: BuildL2ComparisonInput): L2ComparisonRecord;
+/** 追加一条比较记录到运行档案。 */
+export declare function appendL2Comparison(homeDir: string, record: L2ComparisonRecord, now?: () => Date): ArchiveEntry;
+/** 读回全部比较记录(档案读取,零副作用)。 */
+export declare function readL2Comparisons(homeDir: string): L2ComparisonRecord[];
+/** 选择器视图:只给匿名标识与冻结交付物引用——不带 role/runId。 */
+export declare function presentL2Arms(record: L2ComparisonRecord): {
+    readonly anonId: string;
+    readonly artifacts: readonly L2FrozenArtifact[];
+}[];

package/dist/evolve/l2.js

@@ -0,0 +1,81 @@
+/**
+ * L2 匿名前后对比记录协议(trellis-evolve 任务 13.1)。
+ *
+ * spec"匿名前后对比记录协议(L2)":内容类对比的比较记录以类型化档案
+ * 格式持久化——baseline 与候选各自的运行标识、冻结的交付物引用、按
+ * 任务设种子的匿名标识映射、选择器结果与失败收口的 verdict;base 保留在
+ * 比较中;记录格式表达两种收口:选中 baseline ⟹ 不采纳,选择器失败 ⟹
+ * invalid。本模块只定义记录格式与边界;选择器执行(运行比较与裁决)不
+ * 在本期范围。
+ *
+ * 匿名性:呈现给选择器的匿名标识(anonId)由任务种子 + 运行标识派生,
+ * 本身不含角色词;选择器视图(`presentL2Arms`)只给 anonId 与冻结交付
+ * 物引用,不带 role/runId。角色映射只存在于档案(审计用)。
+ */
+import { createHash } from "node:crypto";
+import { appendArchiveRecord, readArchiveRecords } from "./archive.js";
+/** 运行档案 kind:一条 L2 比较记录。 */
+export const L2_COMPARISON_ARCHIVE_KIND = "l2-comparison";
+/**
+ * 匿名标识:按任务种子 + 运行标识派生的稳定短哈希。构造上不可能
+ * 含角色词——呈现面与档案里的值同源,泄露面为零。
+ */
+export function anonArmId(taskSeeds, runId) {
+    const seedKey = taskSeeds
+        .map((entry) => `${entry.task}=${entry.seed}`)
+        .join("&");
+    const digest = createHash("sha256").update(`${seedKey}#${runId}`).digest("hex");
+    return `arm-${digest.slice(0, 16)}`;
+}
+function verdictFor(arms, selector) {
+    if (selector.status === "failed") {
+        return { kind: "invalid", reason: selector.reason };
+    }
+    const picked = arms.find((arm) => arm.anonId === selector.anonId);
+    if (picked === undefined) {
+        return { kind: "invalid", reason: `selector picked unknown arm ${selector.anonId}` };
+    }
+    // 任一臂未交付:无 artifacts 的臂视为未交付(design:不采纳收口)。
+    if (arms.some((arm) => arm.artifacts.length === 0)) {
+        return { kind: "invalid", reason: "arm-undelivered" };
+    }
+    if (picked.role === "baseline") {
+        return { kind: "not-adopted-baseline", anonId: picked.anonId };
+    }
+    return { kind: "adopt-candidate", anonId: picked.anonId };
+}
+/** 由臂与选择器结果构建完整记录(派生匿名映射 + 失败收口 verdict)。 */
+export function buildL2Comparison(input) {
+    const arms = input.arms.map((arm) => ({
+        anonId: anonArmId(input.taskSeeds, arm.runId),
+        runId: arm.runId,
+        role: arm.role,
+        artifacts: arm.artifacts,
+    }));
+    return {
+        comparisonId: input.comparisonId,
+        createdAt: input.createdAt,
+        taskSeeds: input.taskSeeds,
+        arms,
+        selector: input.selector,
+        verdict: verdictFor(arms, input.selector),
+    };
+}
+/** 追加一条比较记录到运行档案。 */
+export function appendL2Comparison(homeDir, record, now = () => new Date()) {
+    return appendArchiveRecord(homeDir, { kind: L2_COMPARISON_ARCHIVE_KIND, payload: record }, now);
+}
+/** 读回全部比较记录(档案读取,零副作用)。 */
+export function readL2Comparisons(homeDir) {
+    const records = [];
+    for (const entry of readArchiveRecords(homeDir)) {
+        if (entry.kind !== L2_COMPARISON_ARCHIVE_KIND)
+            continue;
+        records.push(entry.payload);
+    }
+    return records;
+}
+/** 选择器视图:只给匿名标识与冻结交付物引用——不带 role/runId。 */
+export function presentL2Arms(record) {
+    return record.arms.map((arm) => ({ anonId: arm.anonId, artifacts: arm.artifacts }));
+}

package/dist/evolve/lesson.d.ts

@@ -0,0 +1,57 @@
+/**
+ * lesson 记录(trellis-evolve 任务 12.6)。
+ *
+ * 被采纳的编辑产出一条 lesson(cue / 正文 / 证据链接 / 可选 confidence /
+ * 层作用域,类型见 types.ts)。spec"lesson 记录与上下文呈现":
+ *
+ *   - canonical 记忆已启用 → 经现有记忆管道写入(缺省内置写入器把
+ *     lesson 落成 canonical `memories/lesson-<id>.md`;调用方可注入
+ *     自有管道);
+ *   - 未启用 → 只留运行档案,运行不失败:返回 skipped 而非 failed;
+ *   - 后续提案只呈现匹配上下文的 lesson:全局 lesson 处处可见,
+ *     workspace lesson 只给该 workspace;对其他上下文仅作为升格审批
+ *     的跨项目佐证(单独出口,不混入提案上下文)。
+ *
+ * "记忆已启用"是调用方判定后的显式参数(共享 Memory MCP 的 on/off
+ * 属托管配置面,消费者不读 mcp 配置 —— 10.3 边界)。档案恒写:lesson
+ * 的审计源是运行档案,记忆管道是投递产物。
+ */
+import type { Lesson } from "./types.js";
+/** 运行档案 kind:一条 lesson。payload 即 Lesson 的 JSON 形态。 */
+export declare const LESSON_ARCHIVE_KIND = "lesson";
+export type LessonMemoryStatus = "written" | "skipped" | "failed";
+export interface RecordLessonOptions {
+    readonly homeDir: string;
+    readonly lesson: Lesson;
+    /** canonical 记忆是否已启用(调用方按托管配置判定)。 */
+    readonly memoryEnabled: boolean;
+    /** 记忆管道写入缝;缺省内置写入器落 `memories/lesson-<id>.md`。
+     * 抛错按 failed 收口(仍留档案),不拖垮运行。 */
+    readonly writeMemory?: (lesson: Lesson) => void;
+}
+export interface RecordLessonResult {
+    readonly memoryStatus: LessonMemoryStatus;
+    /** 内置写入器落盘的路径(注入自有管道时为 undefined)。 */
+    readonly memoryPath?: string;
+    /** 写入失败时的错误信息(仅 failed)。 */
+    readonly error?: string;
+}
+/**
+ * 记录一条 lesson:恒写运行档案;记忆已启用才走记忆管道(未启用
+ * skipped;管道抛错 failed 但运行不中断)。
+ */
+export declare function recordLesson(options: RecordLessonOptions): RecordLessonResult;
+/** 全部 lesson(档案读取;档案是 lesson 的审计源)。 */
+export declare function readAllLessons(homeDir: string): Lesson[];
+/**
+ * 提案上下文用:只呈现匹配上下文的 lesson——全局处处可见;workspace
+ * lesson 只给同一 workspace root;其他 workspace 的 lesson 不进提案
+ * 上下文(spec 场景:仓库 X 的 lesson 不原样进入 Y)。
+ */
+export declare function lessonsForContext(homeDir: string, workspaceRoot?: string): Lesson[];
+/**
+ * 升格审批的跨项目佐证:当前上下文之外的 workspace lesson(全局
+ * lesson 不在此列——它们本就处处可见)。仅供升格审批参考,绝不混入
+ * 提案生成上下文。
+ */
+export declare function lessonsAsCorroboration(homeDir: string, workspaceRoot?: string): Lesson[];