@lmzhen/dsh-evolution-core 0.32.2 → 0.32.4

package/lib/restrictor.js

@@ -1,4 +1,4 @@
-import { n as errorText } from "./errors-Br2-uUSK.js";
+import { n as errorText } from "./errors-DRZ9A187.js";
 //#region lib/types/restrictor.js
 const name = "evolution-restrictor";
 const inject = ["agentPresets"];

package/lib/subagent/index.js

@@ -1,4 +1,4 @@
-import { h as restrictedPresetId, n as ensureRestrictedPreset, r as restrictedPresetState } from "../ensure-BuWsjPGD.js";
+import { h as restrictedPresetId, n as ensureRestrictedPreset, r as restrictedPresetState } from "../ensure-C2tUoF5U.js";
 //#region lib/types/subagent/readiness.js
 function serviceOf$1(ctx, name) {
 	return ctx.get(name);

package/lib/types/errors.d.ts

@@ -35,6 +35,7 @@ export declare const EVOLUTION_ERRORS: Readonly<{
     readonly 'e-310-the-settings-service-refused': "E-310: 设置服务拒绝了这次写入：%a1% —— 归属插件的规则优先（跨字段成对约束，或只能收紧的上限）。/evolution params 会显示当前值。";
     readonly 'e-317-skill-write-not-confirmed': "E-317: 技能 \"%a1%\" 未被%a2% —— 确认提示被拒绝或关闭，因此没有写入任何内容。每次创建与裸删除都会出现该提示；只有操作者要求时才重复调用。";
     readonly 'e-318-skill-write-without-a-read': "E-318: 本会话没有读取技能 \"%a1%\"，因此拒绝这次写入。请先用 `skill` 工具读取它（失败的读取不算），然后重复该写入。";
+    readonly 'e-326-support-write-without-a-read': "E-326: 本会话没有读取技能 \"%a1%\" 的支撑文件 \"%a2%\"，因此拒绝这次写入。只读技能正文不算读过支撑文件；请先读取该文件（失败的读取不算），然后重复该写入。";
     readonly 'e-320-the-profile-home-is-not': "E-320: 本宿主没有报告 profile home，因此无法定位旧设置文档。/evolution migrate 读取 `<profile home>/settings.yaml.imported`；请在由 profile 启动的会话里运行。";
     readonly 'e-322-a-parameter-would-break-a': "E-322: %a1% 至少应为 %a2%，但这次写入把它设成 %a3%。未写入任何内容。";
     readonly 'e-321-no-io-provider-is': "E-321: 没有挂载 evolution-io 提供方，因此无法读取旧设置文档。请挂载 evolution-io 行（evolution-host/evolution-all）后重试。";

package/lib/types/errors.js

@@ -36,6 +36,7 @@ export const EVOLUTION_ERRORS = Object.freeze({
     // 0.9.0: the write-admission sequence's own refusals (tool-skill-manage/src/write-gates.ts).
     'e-317-skill-write-not-confirmed': 'E-317: 技能 "%a1%" 未被%a2% —— 确认提示被拒绝或关闭，因此没有写入任何内容。每次创建与裸删除都会出现该提示；只有操作者要求时才重复调用。',
     'e-318-skill-write-without-a-read': 'E-318: 本会话没有读取技能 "%a1%"，因此拒绝这次写入。请先用 `skill` 工具读取它（失败的读取不算），然后重复该写入。',
+    'e-326-support-write-without-a-read': 'E-326: 本会话没有读取技能 "%a1%" 的支撑文件 "%a2%"，因此拒绝这次写入。只读技能正文不算读过支撑文件；请先读取该文件（失败的读取不算），然后重复该写入。',
     // 0.12.0: the confirmation's own deadline (`skillWriteConfirm: 'timeout'`).
     'e-320-the-profile-home-is-not': 'E-320: 本宿主没有报告 profile home，因此无法定位旧设置文档。/evolution migrate 读取 `<profile home>/settings.yaml.imported`；请在由 profile 启动的会话里运行。',
     // G5.12/U-4: the cross-field constraint the registry declares (params.ts) has one enforcement

package/lib/types/index.d.ts

@@ -100,6 +100,7 @@ export * from './skill-revision.ts';
 export * from './store-ledger.ts';
 export * from './reachability.ts';
 export * from './state-store.ts';
+export * from './write-kernel.ts';
 export * from './threats.ts';
 export * from './tool-dispatch.ts';
 export * from './usage.ts';

package/lib/types/index.js

@@ -101,6 +101,7 @@ export * from "./skill-revision.js";
 export * from "./store-ledger.js";
 export * from "./reachability.js";
 export * from "./state-store.js";
+export * from "./write-kernel.js";
 export * from "./threats.js";
 export * from "./tool-dispatch.js";
 export * from "./usage.js";

package/lib/types/mutation-storage-adapter.d.ts

@@ -6,9 +6,12 @@ import type { MutationJournalPort, MutationSnapshotPort } from './mutation-unit.
  * snapshots do not carry that kind and are ignored by the reader.
  */
 export declare function unitSnapshotPort(io: EvolutionIoLike, home: string): MutationSnapshotPort;
+/** Keep a bounded number of terminal tree-change snapshots; prepared units are never pruned. */
+export declare function pruneTreeChangeUnits(io: EvolutionIoLike, home: string, keep?: number): Promise<number>;
 /**
- * Production adapter onto the existing unit journal. It never writes a second
- * journal file; merge and tree-change units share the one journal directory.
+ * Production adapter onto the skill-owned journal directory. Merge recovery
+ * reads merge/unit-journals only; legacy tree-change journals carry kind and
+ * are skipped by the recovery coordinator.
  */
 export declare function unitJournalPort(io: EvolutionIoLike, home: string): MutationJournalPort;
 //# sourceMappingURL=mutation-storage-adapter.d.ts.map

package/lib/types/mutation-storage-adapter.js

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
 import { contentHash } from "./mutations.js";
 import { readUnitSnapshot, unitSnapshotsDir, unitStorageKey, writeUnitSnapshot } from "./unit-storage.js";
-import { writeUnitJournal } from "./unit-journal.js";
+import { unitJournalPath, writeUnitJournal } from "./unit-journal.js";
 /**
  * Production adapter onto the existing unit snapshot store. A tree-change
  * snapshot is encoded as a UnitSnapshot with kind='tree-change'; merge
@@ -36,10 +36,10 @@ export function unitSnapshotPort(io, home) {
                     ...(op.skill === undefined ? {} : { skill: op.skill }),
                 })),
             };
-            await writeUnitSnapshot(io, home, body);
+            await writeUnitSnapshot(io, home, body, 'skill');
         },
         async read(unitId) {
-            const snapshot = await readUnitSnapshot(io, home, unitId);
+            const snapshot = await readUnitSnapshot(io, home, unitId, 'skill') ?? await readUnitSnapshot(io, home, unitId);
             if (snapshot === null || snapshot.kind !== 'tree-change' || snapshot.ops === undefined)
                 return null;
             return {
@@ -51,29 +51,64 @@ export function unitSnapshotPort(io, home) {
             };
         },
         async listPrepared() {
-            const names = await io.list(unitSnapshotsDir(home));
             const out = [];
-            for (const name of names) {
-                if (!name.endsWith('.json'))
-                    continue;
-                const raw = await io.readText(join(unitSnapshotsDir(home), name));
-                if (raw === null)
-                    continue;
-                let snapshot;
-                try {
-                    snapshot = JSON.parse(raw);
+            const seen = new Set();
+            for (const dir of [unitSnapshotsDir(home, 'skill'), unitSnapshotsDir(home)]) {
+                const names = await io.list(dir);
+                for (const name of names) {
+                    if (!name.endsWith('.json'))
+                        continue;
+                    const raw = await io.readText(join(dir, name));
+                    if (raw === null)
+                        continue;
+                    let snapshot;
+                    try {
+                        snapshot = JSON.parse(raw);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (snapshot.kind !== 'tree-change' || snapshot.mutationState !== 'prepared' || snapshot.ops === undefined)
+                        continue;
+                    if (seen.has(snapshot.unitId))
+                        continue;
+                    seen.add(snapshot.unitId);
+                    out.push({ unitId: snapshot.unitId, state: 'prepared', ops: snapshot.ops, ...(snapshot.cleanup === undefined ? {} : { cleanup: snapshot.cleanup }), createdAt: snapshot.createdAt });
                 }
-                catch {
-                    continue;
-                }
-                if (snapshot.kind !== 'tree-change' || snapshot.mutationState !== 'prepared' || snapshot.ops === undefined)
-                    continue;
-                out.push({ unitId: snapshot.unitId, state: 'prepared', ops: snapshot.ops, ...(snapshot.cleanup === undefined ? {} : { cleanup: snapshot.cleanup }), createdAt: snapshot.createdAt });
             }
             return out;
         },
     };
 }
+/** Keep a bounded number of terminal tree-change snapshots; prepared units are never pruned. */
+export async function pruneTreeChangeUnits(io, home, keep = 500) {
+    if (!Number.isInteger(keep) || keep < 1)
+        return 0;
+    const dir = unitSnapshotsDir(home, 'skill');
+    const names = await io.list(dir);
+    const terminal = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const snapshot = JSON.parse(await io.readText(join(dir, name)) ?? '');
+            if (snapshot.kind !== 'tree-change' || snapshot.mutationState === 'prepared')
+                continue;
+            terminal.push({ name, unitId: snapshot.unitId, createdAt: snapshot.createdAt });
+        }
+        catch {
+            // unreadable files are left for the explicit recovery/audit path
+        }
+    }
+    terminal.sort((a, b) => b.createdAt - a.createdAt);
+    let removed = 0;
+    for (const entry of terminal.slice(keep)) {
+        await io.remove(join(dir, entry.name));
+        await io.remove(unitJournalPath(home, entry.unitId, 'skill')).catch(() => { });
+        removed += 1;
+    }
+    return removed;
+}
 const PHASE = {
     prepared: 'prepared',
     'unit-written': 'unit-written',
@@ -82,8 +117,9 @@ const PHASE = {
     undone: 'rolled-back',
 };
 /**
- * Production adapter onto the existing unit journal. It never writes a second
- * journal file; merge and tree-change units share the one journal directory.
+ * Production adapter onto the skill-owned journal directory. Merge recovery
+ * reads merge/unit-journals only; legacy tree-change journals carry kind and
+ * are skipped by the recovery coordinator.
  */
 export function unitJournalPort(io, home) {
     return {
@@ -98,9 +134,10 @@ export function unitJournalPort(io, home) {
                 phase: PHASE[record.phase],
                 storageKey: unitStorageKey(record.unitId),
                 snapshotSha256: contentHash(JSON.stringify(record)),
+                kind: 'tree-change',
                 updatedAt: Date.now(),
             };
-            await writeUnitJournal(io, home, journal);
+            await writeUnitJournal(io, home, journal, 'skill');
         },
     };
 }

package/lib/types/mutation-unit.d.ts

@@ -107,7 +107,7 @@ export interface MutationUnitOptions {
     hooks?: MutationUnitHooks;
     validateWrite?: (op: TreeChangeOp) => string | null;
     transact?: typeof transactIo;
-    /** Whether the io.transact callback re-checks the baseline. Default true; create sets false under its outer root lock. */
+    /** @deprecated the kernel always re-checks the baseline; kept for source compatibility. */
     transactGuard?: boolean;
     now?: () => number;
 }
@@ -135,7 +135,7 @@ export declare class MutationUnit {
     private readonly snapshots;
     private readonly hooks;
     private readonly validateWrite;
-    private readonly transact;
+    private readonly kernel;
     private readonly transactGuard;
     private readonly now;
     constructor(options: MutationUnitOptions);

package/lib/types/mutation-unit.js

@@ -1,6 +1,7 @@
 import { basename, dirname, isAbsolute, join, relative } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { isCommittedWarning, isProcessAlive } from "./io.js";
+import { WriteKernel } from "./write-kernel.js";
 function underRoot(rootDir, target) {
     if (rootDir === undefined || rootDir === '')
         return false;
@@ -101,7 +102,7 @@ export class MutationUnit {
     snapshots;
     hooks;
     validateWrite;
-    transact;
+    kernel;
     transactGuard;
     now;
     constructor(options) {
@@ -113,9 +114,10 @@ export class MutationUnit {
         this.snapshots = options.snapshots;
         this.hooks = options.hooks;
         this.validateWrite = options.validateWrite;
-        this.transact = options.transact;
-        this.transactGuard = options.transactGuard ?? true;
+        this.transactGuard = options.transactGuard !== false;
         this.now = options.now ?? Date.now;
+        const transact = options.transact;
+        this.kernel = new WriteKernel({ io: this.io, ...(transact === undefined ? {} : { transact }), now: this.now });
     }
     preview(request) {
         const validation = validateMutationRequest(request, this.limits);
@@ -163,7 +165,7 @@ export class MutationUnit {
                     if (current !== baseline) {
                         return { ok: false, unitId, dryRun: false, changed, errors: [{ code: 'cas-drift', message: 'target changed after plan', target: op.target }] };
                     }
-                    snapshots.push({ target: op.target, before: current, baseline });
+                    snapshots.push({ target: op.target, before: current, after: op.kind === 'write' ? op.content : null, baseline });
                 }
                 for (const op of validation.ops) {
                     const refusal = this.validateWrite?.(op) ?? null;
@@ -188,7 +190,8 @@ export class MutationUnit {
                     if (snapshot === undefined)
                         throw new Error('snapshot missing for ' + op.target);
                     try {
-                        await this.applyOp(op, snapshot.baseline);
+                        const opWarnings = await this.applyOp(op, snapshot.baseline);
+                        warnings.push(...opWarnings);
                         changed.push(op.target);
                     }
                     catch (error) {
@@ -200,9 +203,11 @@ export class MutationUnit {
                     }
                 }
                 await bestEffort(async () => this.journal?.write({ unitId, phase: 'unit-written', changed, target: primary, roots: validation.roots.map(root => root.name) }));
-                await bestEffort(async () => this.journal?.write({ unitId, phase: 'committed', changed, target: primary, roots: validation.roots.map(root => root.name) }));
+                // P2-1: the committed snapshot is the recovery authority. Write it BEFORE the journal's
+                // committed phase so a crash in this window recovers as committed, never rolled back.
                 if (this.snapshots !== undefined)
                     await bestEffort(() => this.snapshots.write({ unitId, state: 'committed', ops: eventOps, ...cleanup, createdAt: this.now() }));
+                await bestEffort(async () => this.journal?.write({ unitId, phase: 'committed', changed, target: primary, roots: validation.roots.map(root => root.name) }));
                 try {
                     await this.hooks?.committed?.({ unitId, changed, ops: eventOps, roots: validation.roots.map(root => root.name) });
                 }
@@ -378,48 +383,16 @@ export class MutationUnit {
         });
     }
     async applyOp(op, baseline) {
-        if (this.transact !== undefined && op.kind === 'write') {
-            let ran = false;
-            await this.transact(this.io, op.target, () => {
-                ran = true;
-                return op.content;
-            });
-            if (!ran)
-                throw new Error('internal error: the write transaction did not invoke the task; no write was performed');
-            return;
-        }
-        const next = op.kind === 'delete' ? null : op.content;
-        if (this.io.transact !== undefined) {
-            let conflict = false;
-            let wrote = false;
-            await this.io.transact(op.target, current => {
-                if (current !== baseline) {
-                    if (this.transactGuard)
-                        throw new Error('concurrent modification detected: ' + op.target);
-                    conflict = true;
-                    return current;
-                }
-                wrote = true;
-                return next;
-            });
-            if (conflict && !wrote)
-                throw Object.assign(new Error('concurrent modification detected: ' + op.target), { noWrite: true });
-            return;
-        }
-        const current = await this.io.readText(op.target);
-        if (current !== baseline)
-            throw new Error('concurrent modification detected: ' + op.target);
-        if (next === null)
-            await this.io.remove(op.target);
-        else
-            await this.io.writeText(op.target, next);
+        const result = await this.kernel.writeOne({ path: op.target, expected: baseline, next: op.kind === 'delete' ? null : op.content, ...op.skill === undefined ? {} : { skill: op.skill } }, { guardBaseline: this.transactGuard });
+        if (!result.ok)
+            throw Object.assign(new Error(result.errors[0]?.message ?? 'write failed: ' + op.target), { noWrite: true });
+        return [...(result.warnings ?? [])];
     }
     async rollback(snapshots) {
         for (const snapshot of [...snapshots].reverse()) {
-            if (snapshot.before === null)
-                await this.io.remove(snapshot.target);
-            else
-                await this.io.writeText(snapshot.target, snapshot.before);
+            const result = await this.kernel.restore({ path: snapshot.target, before: snapshot.before, after: snapshot.after });
+            if (!result.ok)
+                throw new Error(result.errors[0]?.message ?? 'rollback failed: ' + snapshot.target);
         }
     }
 }

package/lib/types/params.js

@@ -187,7 +187,7 @@ export const PARAM_EXPOSURE = Object.freeze([
     { id: 'evolution-approval.enabled', group: 'deployment', tier: 'E3', authority: 'cordis', owner: 'evolution-approval', applies: 'live', docAnchor: 'PARAMETERS.md#deployment', summary: 'Master approval switch: run the approval pipeline for foreground writes.', label: '启用批准流水线', hint: '关闭后前台写入不再经批准。', control: 'switch', unit: '', values: '', card: 'evolution-approval' },
     { id: 'evolution-approval.stageForeground', group: 'deployment', tier: 'E2', authority: 'cordis', owner: 'evolution-approval', applies: 'none', docAnchor: 'PARAMETERS.md#deployment', summary: 'Stage foreground agent writes for approval too.', why: 'security' },
     { id: 'evolution-approval.pendingTtlMs', group: 'deployment', tier: 'E3', authority: 'cordis', owner: 'evolution-approval', applies: 'live', docAnchor: 'PARAMETERS.md#deployment', summary: 'How long a staged write may wait before it expires: expired writes are closed as rejected and are NEVER executed; 0 (the default) means the window never expires.', label: '待批过期时间', hint: '一条待批写入最多等多久：超时就按「拒绝」关掉（不会执行，写效果不会落地）；0 = 永不过期（默认）。', control: 'number', unit: '毫秒', values: '', card: 'evolution-approval' },
-    { id: 'approvalConfirm', group: 'write-caps', tier: 'E3', authority: 'cordis', owner: 'evolution-approval', applies: 'live', docAnchor: 'PARAMETERS.md#write-caps', summary: 'What the confirmation before an APPROVE does: write straight through, ask first, or treat an unanswered prompt as a cancel. The same three words skillWriteConfirm uses for a skill write.', label: '批准前先确认', hint: '点「批准」时要不要再确认一次：直接执行 / 先确认 / 等待超时即取消。默认直接执行（不打断批量批准）。', control: 'select', unit: '', values: 'auto|ask|timeout', valueLabels: '直接执行|先确认|等待超时即取消', card: 'evolution-approval' },
+    { id: 'approvalConfirm', group: 'write-caps', tier: 'E3', authority: 'cordis', owner: 'evolution-approval', applies: 'live', docAnchor: 'PARAMETERS.md#write-caps', summary: 'What the confirmation before an APPROVE does: execute immediately, or ask first.', label: '批准前先确认', hint: '点「批准」时要不要再确认一次：直接执行 / 先确认。默认直接执行（不打断批量批准）。', control: 'select', unit: '', values: 'auto|ask', valueLabels: '直接执行|先确认', card: 'evolution-approval' },
     { id: 'qualityWarnThreshold', group: 'deployment', tier: 'E2', authority: 'cordis', owner: 'evolution-feedback', applies: 'none', docAnchor: 'PARAMETERS.md#deployment', summary: 'Feedback score below which a skill carries a warning.', why: 'internal' },
     { id: 'replay.maxPlans', group: 'deployment', tier: 'E2', authority: 'cordis', owner: 'evolution-replay', applies: 'none', docAnchor: 'PARAMETERS.md#deployment', summary: 'Plans compared in one replay report.', why: 'internal' },
     { id: 'replay.weights', group: 'deployment', tier: 'E2', authority: 'cordis', owner: 'evolution-replay', applies: 'none', docAnchor: 'PARAMETERS.md#deployment', summary: 'Scoring weights of the replay comparison.', why: 'internal' },

package/lib/types/platform-services.js

@@ -29,7 +29,6 @@ export const PLATFORM_SERVICE_PROBES = Object.freeze([
     { service: 'evolutionPolicy', feature: 'the policy snapshot that shadows row knobs', side: 'host' },
     { service: 'evolutionReplay', feature: '/evolution replay', side: 'host' },
     { service: 'evolutionState', feature: 'the state facade behind activity and replay', side: 'host' },
-    { service: 'evolutionStateStore', feature: 'generic durable state store for assignment queue and future collections', side: 'host' },
     { service: 'llm', feature: 'the curator one-shot review model call', side: 'host' },
     { service: 'memory', feature: 'the cross-session memory store (review and learning-graph reads)', side: 'host' },
     { service: 'pluginInventory', feature: 'the plugin inventory view', side: 'host' },

package/lib/types/session-projection.d.ts

@@ -40,6 +40,18 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 export declare const evolutionActivityProjection: ProjectionDefinition<'evolutionActivity'>;
 /** The `evolutionEvidence` unit (host-only: no client view is registered for it). */
 export declare const evolutionEvidenceProjection: ProjectionDefinition<'evolutionEvidence'>;
+/**
+ * Whether one session object can be projected at all.
+ *
+ * The family's readers also take STRUCTURAL session views — `skill-reads.ts` documents the tool
+ * path's bare stub — while the registry folds a session's own log (`snapshotEvents(from, to)`,
+ * `eventAt(seq)`, `seq`, `inheritedEventCount`) whenever it has to build or advance a cell. A
+ * view without those members has no projection state to read, and asking for one would fold a
+ * log the unit cannot index.
+ * @param session - the value a caller holds as its session.
+ * @returns true when the registry can fold this object.
+ */
+export declare function isProjectableSession(session: unknown): session is Session;
 /**
  * The skill names one session read through a non-failed dispatch, as a fold state.
  *
@@ -54,6 +66,8 @@ export interface EvolutionReadsState {
         readonly key: string;
         readonly skill: string | null;
         readonly failed: boolean;
+        readonly file?: string | null | undefined;
+        readonly tool?: string | undefined;
     }[];
 }
 /**
@@ -74,14 +88,32 @@ export interface EvolutionSignalsState {
     /** The open turn's window fold. */
     readonly turn: TurnFoldState;
 }
+/** One captured skill-catalog message, bounded for the projection-restore reader. */
+export interface EvolutionCatalogFrame {
+    readonly text: string;
+    readonly entries: readonly {
+        readonly name: string;
+        readonly description: string;
+    }[];
+    readonly update: boolean;
+}
+/** The bounded catalog/projection history the discovery runtime reads for restore and dedupe. */
+export interface EvolutionProjectionHistoryState {
+    readonly catalogs: readonly EvolutionCatalogFrame[];
+    readonly digests: readonly string[];
+}
 declare module '@deepseek-ai/dsh-session-projection/types' {
     interface SessionProjectionStateMap {
         /** The skill names one session read, for the read-before-write gate and the review plan path. */
         evolutionReads: EvolutionReadsState;
+        /** Catalog/projection frames and digests, newest last; bounded so the state cannot grow with the session. */
+        evolutionProjectionHistory: EvolutionProjectionHistoryState;
         /** The open turn's window signals, for the review cadence. */
         evolutionSignals: EvolutionSignalsState;
     }
 }
+/** The `evolutionProjectionHistory` unit (host-only). */
+export declare const evolutionProjectionHistoryProjection: ProjectionDefinition<'evolutionProjectionHistory'>;
 /** The `evolutionReads` unit (host-only: no client view is registered for it). */
 export declare const evolutionReadsProjection: ProjectionDefinition<'evolutionReads'>;
 /** The `evolutionSignals` unit (host-only: no client view is registered for it). */

package/lib/types/session-projection.js

@@ -22,7 +22,7 @@
  */
 import { z } from 'zod';
 import { isBookkeepingFrame } from "./evidence.js";
-import { dispatchStepOf, isSkillReadToolName, skillReadNameOf } from "./tool-dispatch.js";
+import { dispatchPathOf, dispatchStepOf, isSkillReadToolName, skillReadNameOf } from "./tool-dispatch.js";
 import { foldTurnEvent, initialTurnFold } from "./signals.js";
 // Bounds are the persisted-row validation bounds (a millisecond timestamp): the clamp guard
 // requires every `z.number()` field to carry one on the same line.
@@ -77,7 +77,7 @@ export const evolutionEvidenceProjection = {
  * @param session - the value a caller holds as its session.
  * @returns true when the registry can fold this object.
  */
-function isProjectableSession(session) {
+export function isProjectableSession(session) {
     if (session === null || typeof session !== 'object')
         return false;
     const candidate = session;
@@ -89,11 +89,21 @@ function isProjectableSession(session) {
     const logs = typeof candidate.snapshotEvents === 'function';
     return folds && logs && typeof candidate.seq === 'number';
 }
+const projectionHistorySchema = z.object({
+    catalogs: z.array(z.object({
+        text: z.string(),
+        entries: z.array(z.object({ name: z.string(), description: z.string() }).strict()).max(512),
+        update: z.boolean(),
+    }).strict()).max(8),
+    digests: z.array(z.string()).max(64),
+}).strict();
 const readsStateSchema = z.object({
     reads: z.array(z.object({
         key: z.string(),
         skill: z.string().nullable(),
         failed: z.boolean(),
+        file: z.string().nullable().optional(),
+        tool: z.string().optional(),
     }).strict()),
 }).strict();
 const signalsStateSchema = z.object({
@@ -110,6 +120,36 @@ const signalsStateSchema = z.object({
         opened: z.array(z.string()),
     }).strict(),
 }).strict();
+/** The `evolutionProjectionHistory` unit (host-only). */
+export const evolutionProjectionHistoryProjection = {
+    key: 'evolutionProjectionHistory',
+    stateVersion: 1,
+    stateSchema: projectionHistorySchema,
+    init: () => ({ catalogs: [], digests: [] }),
+    apply: (state, event) => {
+        const frame = event;
+        if (frame.type !== 'user/message' || typeof frame.data !== 'object' || frame.data === null)
+            return state;
+        const message = frame.data;
+        const source = message.source;
+        if (source === undefined || typeof source !== 'object')
+            return state;
+        if (source.kind === 'evolution-skill-projection' && typeof source.digest === 'string') {
+            if (state.digests.includes(source.digest))
+                return state;
+            return { catalogs: state.catalogs, digests: [...state.digests, source.digest].slice(-64) };
+        }
+        if (source.kind !== 'skill-catalog' || source.form !== 'catalog' || !Array.isArray(source.entries))
+            return state;
+        if (!Array.isArray(message.content))
+            return state;
+        const text = message.content.map(block => block !== null && typeof block === 'object' && block.type === 'text' ? String(block.text ?? '') : '').join('');
+        if (!text.includes('<available_skills>') || !text.includes('</available_skills>'))
+            return state;
+        const entries = source.entries.filter((entry) => entry !== null && typeof entry === 'object' && typeof entry.name === 'string' && typeof entry.description === 'string').map(entry => ({ name: entry.name, description: entry.description }));
+        return { catalogs: [...state.catalogs, { text, entries, update: source.update === true }].slice(-8), digests: state.digests };
+    },
+};
 /** The `evolutionReads` unit (host-only: no client view is registered for it). */
 export const evolutionReadsProjection = {
     key: 'evolutionReads',
@@ -134,7 +174,7 @@ export const evolutionReadsProjection = {
             if (entry.failed === failed)
                 return state;
             const reads = [...state.reads];
-            reads[at] = { key: entry.key, skill: entry.skill, failed };
+            reads[at] = { key: entry.key, skill: entry.skill, failed, ...(entry.file === undefined ? {} : { file: entry.file }), ...(entry.tool === undefined ? {} : { tool: entry.tool }) };
             return { reads };
         };
         // An event with no name only SETTLES a dispatch: it can flip the failure flag of one already
@@ -144,6 +184,13 @@ export const evolutionReadsProjection = {
         // A replayed open of a tracked dispatch: keep the first entry, still honour its outcome.
         if (at >= 0)
             return settled();
+        // A dispatch naming a path is a candidate SUPPORT-FILE read (P2-27). The
+        // projection stores the raw path; the gate maps it to a skill later, when it
+        // knows the deployment's root and file-tool names.
+        const file = dispatchPathOf(step);
+        if (file !== null) {
+            return { reads: [...state.reads.slice(-511), { key: step.key, skill: null, failed: step.outcome?.ok === false, file, tool: step.name }] };
+        }
         // Only a read-capable tool is worth a state entry: the reader answers skill names, and a
         // state that tracked every dispatch would grow with the session.
         if (!isSkillReadToolName(step.name))
@@ -195,6 +242,7 @@ export function installEvolutionProjections(ctx) {
         registry.register(evolutionActivityProjection);
         registry.register(evolutionEvidenceProjection);
         registry.register(evolutionReadsProjection);
+        registry.register(evolutionProjectionHistoryProjection);
         registry.register(evolutionSignalsProjection);
     };
     // Already-mounted registry first: a reader that runs in the same tick as its own mount

package/lib/types/skill-reads.d.ts

@@ -56,6 +56,25 @@ export interface EvolutionSessionLogView {
  * @returns the names read through a non-failed `skill` dispatch, or `undefined` when unreadable.
  */
 export declare function sessionReadSkillNames(ctx: Context, session: EvolutionSessionLogView | undefined): ReadonlySet<string> | undefined;
+/** The deployment's file-read evidence inputs: its skills root and file-tool names. */
+export interface SupportReadOptions {
+    readonly root: string;
+    readonly toolNames?: readonly string[] | undefined;
+}
+/**
+ * Skill support files ONE session read through a non-failed file tool (P2-27).
+ *
+ * platform-declaration anchor: `sessionProjections` is declared by
+ * `@deepseek-ai/dsh-session-projection` (its registry; capability-probed here).
+ * Same two readers as {@link sessionReadSkillNames}: the family projection first,
+ * then the structural log view. `undefined` means "no evidence", not "nothing was
+ * read" - the write gate then keeps its fail-open posture.
+ * @param ctx - a context of the runtime.
+ * @param session - the session whose reads are wanted.
+ * @param options - the skills root and the configured file-tool names.
+ * @returns skill -> set of skill-root-relative support paths.
+ */
+export declare function sessionReadSupportFiles(ctx: Context, session: EvolutionSessionLogView | undefined, options: SupportReadOptions): ReadonlyMap<string, ReadonlySet<string>> | undefined;
 /** Actions whose target must have been read first (create is authorship, so it is exempt). */
 export declare const READ_REQUIRED_ACTIONS: readonly string[];
 /**

package/lib/types/skill-reads.js

@@ -1,5 +1,5 @@
-import { collectReadSkillNames } from "./tool-dispatch.js";
-import { sessionReadNames } from "./session-projection.js";
+import { collectReadSkillNames, collectReadSupportFiles, DEFAULT_SUPPORT_READ_TOOL_NAMES, supportFileReadFromPath } from "./tool-dispatch.js";
+import { installEvolutionProjections, isProjectableSession, sessionReadNames } from "./session-projection.js";
 /**
  * The skill names ONE session read, or `undefined` when its log is not readable.
  *
@@ -24,6 +24,46 @@ export function sessionReadSkillNames(ctx, session) {
     const events = session.readEvents?.();
     return events === undefined ? undefined : collectReadSkillNames(events);
 }
+/**
+ * Skill support files ONE session read through a non-failed file tool (P2-27).
+ *
+ * platform-declaration anchor: `sessionProjections` is declared by
+ * `@deepseek-ai/dsh-session-projection` (its registry; capability-probed here).
+ * Same two readers as {@link sessionReadSkillNames}: the family projection first,
+ * then the structural log view. `undefined` means "no evidence", not "nothing was
+ * read" - the write gate then keeps its fail-open posture.
+ * @param ctx - a context of the runtime.
+ * @param session - the session whose reads are wanted.
+ * @param options - the skills root and the configured file-tool names.
+ * @returns skill -> set of skill-root-relative support paths.
+ */
+export function sessionReadSupportFiles(ctx, session, options) {
+    if (session === undefined)
+        return undefined;
+    if (isProjectableSession(session)) {
+        installEvolutionProjections(ctx);
+        const state = ctx.get('sessionProjections')?.stateOf(session, 'evolutionReads');
+        if (state !== undefined) {
+            const toolNames = options.toolNames ?? DEFAULT_SUPPORT_READ_TOOL_NAMES;
+            const reads = new Map();
+            for (const entry of state.reads) {
+                if (entry.failed || typeof entry.file !== 'string')
+                    continue;
+                if (entry.tool !== undefined && !toolNames.includes(entry.tool))
+                    continue;
+                const hit = supportFileReadFromPath(entry.file, { root: options.root });
+                if (hit === null)
+                    continue;
+                const set = reads.get(hit.skill) ?? new Set();
+                set.add(hit.rel);
+                reads.set(hit.skill, set);
+            }
+            return reads;
+        }
+    }
+    const events = session.readEvents?.();
+    return events === undefined ? undefined : collectReadSupportFiles(events, { toolNames: options.toolNames ?? DEFAULT_SUPPORT_READ_TOOL_NAMES, root: options.root });
+}
 /** Actions whose target must have been read first (create is authorship, so it is exempt). */
 export const READ_REQUIRED_ACTIONS = Object.freeze([
     'edit', 'update', 'patch', 'delete', 'write_file', 'remove_file', 'restructure', 'extract',

package/lib/types/skill-store.js

@@ -50,7 +50,7 @@ import { supportRefs } from "./support-refs.js";
 import { selectSections } from "./section-selection.js";
 import { MutationUnit, fileMutationLock } from "./mutation-unit.js";
 import { SkillModel } from "./skill-model.js";
-import { unitJournalPort, unitSnapshotPort } from "./mutation-storage-adapter.js";
+import { pruneTreeChangeUnits, unitJournalPort, unitSnapshotPort } from "./mutation-storage-adapter.js";
 import { projectExtractBodies } from "./extract-plan.js";
 import { diffFindings } from "./skill-lint.js";
 import { contentHash, loadMutations, recordMutation } from "./mutations.js";
@@ -583,7 +583,9 @@ export class SkillLibrary {
             journal: unitJournalPort(this.io, home),
             snapshots: unitSnapshotPort(this.io, home),
         });
-        return await unit.recoverPrepared();
+        const results = await unit.recoverPrepared();
+        await pruneTreeChangeUnits(this.io, home).catch(() => { });
+        return results;
     }
     /**
      * Run one single-file read-modify-write for a mutator. When `transact` was