@lmzhen/dsh-evolution-core 0.30.17 → 0.30.19

package/lib/types/skill-store.js

@@ -48,10 +48,11 @@ import { makeSerialQueue } from "./serial.js";
 import { h2Sections } from "./document-body.js";
 import { diffFindings } from "./skill-lint.js";
 import { contentHash, loadMutations, recordMutation } from "./mutations.js";
+import { revisionFingerprint, revisionSupportDigest } from "./skill-revision.js";
 import { contentRetentionFeedback, HISTORY_DIR, loadVersionContent, loadVersions, recordVersions } from "./skill-history.js";
-import { suppressedFile, usageFile } from "./usage.js";
+import { getRecord, mutateUsage, suppressedFile, usageFile } from "./usage.js";
 import { assessStructureHealth, DEFAULT_HEALTH_THRESHOLDS, lintBody } from "./skill-health.js";
-import { CONTENT_SPLIT_HINT, DEFAULT_SKILL_VERSION_KEEP, SKILL_NAME_RE, SUPPORT_DIRS } from "./constants.js";
+import { CONTENT_SPLIT_HINT, DEFAULT_SKILL_VERSION_KEEP, PROTECTED_BUILTIN_SKILLS, SKILL_NAME_RE, SUPPORT_DIRS } from "./constants.js";
 /**
  * The CLASS boundary default authority (G1/1.1, Stage 2).
  *
@@ -472,6 +473,12 @@ function serialForRoot(root) {
     ROOT_SERIAL.set(key, created);
     return created;
 }
+/** Same-content test for two revision anchors (absent only equals absent). */
+function sameRevisionAnchor(expected, live) {
+    if (expected.kind !== live.kind)
+        return false;
+    return expected.kind === 'absent' || expected.sha256 === live.sha256;
+}
 export class SkillLibrary {
     root;
     limits;
@@ -861,7 +868,55 @@ export class SkillLibrary {
         }
     }
     /**
-  
+     * Content anchor of one live skill: name + body + every support file under SUPPORT_DIRS.
+     *
+     * This is the commit-side counterpart of the decision-time anchor recorded by the merge
+     * domain (see skill-revision.ts): both sides call the same fingerprint, so a changed
+     * source, target or support file cannot slip past the commit CAS.
+     * @param rawName - caller-supplied skill name (trimmed here).
+     * @returns present anchor, or absent when the skill has no SKILL.md.
+     */
+    async revisionFingerprint(rawName) {
+        const name = rawName.trim();
+        if (this.badName(name) !== null)
+            return null;
+        let body;
+        try {
+            body = await this.io.readText(join(this.dirOf(name), 'SKILL.md'));
+        }
+        catch (error) {
+            if (error?.code === 'EISDIR')
+                return null;
+            throw error;
+        }
+        if (body === null)
+            return null;
+        return revisionFingerprint(name, body, await this.liveSupportFiles(name));
+    }
+    /** Content anchor of one live skill; the hash a decision records and a commit re-checks. */
+    async revisionAnchor(rawName) {
+        const fingerprint = await this.revisionFingerprint(rawName);
+        return fingerprint === null ? { kind: 'absent' } : { kind: 'present', sha256: contentHash(fingerprint) };
+    }
+    /** Every support file of one live skill, in listing order; unreadable/missing files fail loud. */
+    async liveSupportFiles(rawName) {
+        const name = rawName.trim();
+        if (this.badName(name) !== null)
+            return [];
+        const listed = await this.listSupportFiles(name);
+        if (isUnknown(listed))
+            throw new Error('support file list is unknown: ' + name);
+        if (!isPresent(listed))
+            return [];
+        const dir = this.dirOf(name);
+        return await Promise.all(listed.value.map(async (path) => {
+            const content = await this.io.readText(join(dir, ...path.replace(/\\/g, '/').split('/').filter(Boolean)));
+            if (content === null)
+                throw new Error('support file disappeared: ' + name + '/' + path);
+            return { path, content };
+        }));
+    }
+    /**
      * Single path-building choke point (rc.42 audit P2-5): every directory path
   
      * is built from the TRIMMED name, so a name that passes `badName` (which
@@ -949,6 +1004,13 @@ export class SkillLibrary {
         }
         return null;
     }
+    /** Whether the target directory exists at all (a SKILL.md-less ghost still occupies the name). */
+    async skillDirExists(rawName) {
+        const name = rawName.trim();
+        if (this.badName(name) !== null)
+            return false;
+        return await this.io.exists(this.dirOf(name));
+    }
     async isManaged(rawName) {
         // One trim per entry: paths (dirOf), validation and messages all see the same name.
         const name = rawName.trim();
@@ -1247,6 +1309,18 @@ export class SkillLibrary {
             return [];
         return await loadVersions(this.root, this.io, name);
     }
+    /** Versions from the latest merge baseline onward; old versions stay listable via listVersions. */
+    async listBaselineVersions(rawName) {
+        const versions = await this.listVersions(rawName);
+        let start = -1;
+        for (let index = versions.length - 1; index >= 0; index -= 1) {
+            if (versions[index]?.unitHead?.baseline === true) {
+                start = index;
+                break;
+            }
+        }
+        return start < 0 ? versions : versions.slice(start);
+    }
     /**
      * One version's content, read back from the content-addressed blob store.
      * @param rawName - the skill's name.
@@ -1260,6 +1334,50 @@ export class SkillLibrary {
             return null;
         return await loadVersionContent(this.root, this.io, name, v);
     }
+    /** Read an archived skill's human-readable reason, exact or stamped. */
+    async readArchiveReason(rawName) {
+        const name = rawName.trim();
+        if (this.badName(name) !== null)
+            return null;
+        const archiveRoot = join(this.root, '.archive');
+        const exact = await this.io.readText(join(archiveRoot, name, '.archive-reason'));
+        if (exact !== null)
+            return exact.trim();
+        const entries = await this.io.list(archiveRoot).catch(() => []);
+        for (const entry of [...entries].reverse()) {
+            if (entry !== name && !entry.startsWith(name + '-'))
+                continue;
+            const marker = await this.io.readText(join(archiveRoot, entry, '.archive-name'));
+            if (marker !== null && marker.trim() !== name)
+                continue;
+            const reason = await this.io.readText(join(archiveRoot, entry, '.archive-reason'));
+            if (reason !== null)
+                return reason.trim();
+        }
+        return null;
+    }
+    /** Read an archived skill body (SKILL.md) by its original name, exact or stamped. */
+    async readArchived(rawName) {
+        const name = rawName.trim();
+        if (this.badName(name) !== null)
+            return null;
+        const archiveRoot = join(this.root, '.archive');
+        const exact = await this.io.readText(join(archiveRoot, name, 'SKILL.md'));
+        if (exact !== null)
+            return exact;
+        const entries = await this.io.list(archiveRoot).catch(() => []);
+        for (const entry of [...entries].reverse()) {
+            if (entry !== name && !entry.startsWith(name + '-'))
+                continue;
+            const marker = await this.io.readText(join(archiveRoot, entry, '.archive-name'));
+            if (marker !== null && marker.trim() !== name)
+                continue;
+            const text = await this.io.readText(join(archiveRoot, entry, 'SKILL.md'));
+            if (text !== null)
+                return text;
+        }
+        return null;
+    }
     /**
      * Pin or unpin a skill (`.pinned` marker). Pinned skills are protected from
      * deletion, from background-review writes, and from the lifecycle — a
@@ -1477,7 +1595,7 @@ export class SkillLibrary {
         // marker never landed" inside the fsync/durability wrapper, producing a
         // self-contradicting operator-facing message.
         let markerWarning = '';
-        if (origin !== 'foreground') {
+        if (origin !== 'foreground' || options.managed === true) {
             // v29 SK-05: the marker write gets the same committed-only tolerance as
             // every other write in this file (A1-15) — a post-rename dir-fsync
             // failure means the MARKER landed; rejecting the create as a plain
@@ -1805,6 +1923,19 @@ export class SkillLibrary {
             && !name.includes('/') && !name.includes('\\')
             && basename(name) === name;
     }
+    /** Mark merge-absorbed sources archived in the usage sidecar (FR-DATA-07). */
+    async foldArchivedUsage(sources, at) {
+        try {
+            await mutateUsage(this.root, this.io, map => {
+                for (const name of sources) {
+                    const record = getRecord(map, name);
+                    record.state = 'archived';
+                    record.archived_at = at;
+                }
+            });
+        }
+        catch { /* lifecycle telemetry is best-effort; the archive already landed */ }
+    }
     async archive(rawName, options = {}, origin = this.authority.origin) {
         // One trim per entry: paths (dirOf), validation and messages all see the same name.
         const name = rawName.trim();
@@ -1942,9 +2073,18 @@ export class SkillLibrary {
             if (bad)
                 return { ok: false, message: bad };
         }
+        if (PROTECTED_BUILTIN_SKILLS.has(target))
+            return { ok: false, message: `目标技能「${target}」是受保护的内置技能。` };
+        const protectedSource = sources.find(name => PROTECTED_BUILTIN_SKILLS.has(name));
+        if (protectedSource !== undefined)
+            return { ok: false, message: `来源技能「${protectedSource}」是受保护的内置技能。` };
+        const limits = plan.limits ?? this.limits;
         return await this.serial(async () => {
             const dir = this.dirOf(target);
             const targetPath = join(dir, 'SKILL.md');
+            if (!plan.targetExists && await this.io.exists(dir)) {
+                return { ok: false, message: `目标目录「${target}」已存在但不是技能；拒绝把 SKILL.md 写进同名目录。` };
+            }
             const currentTarget = await this.io.readText(targetPath);
             if (plan.targetExists !== (currentTarget !== null)) {
                 return { ok: false, message: plan.targetExists ? `目标技能「${target}」不存在。` : `目标技能「${target}」已存在。` };
@@ -1952,6 +2092,12 @@ export class SkillLibrary {
             if (currentTarget !== plan.expectedTargetBody) {
                 return { ok: false, message: `目标技能「${target}」在计划之后被改过；拒绝提交（未写入任何内容）。` };
             }
+            if (plan.targetExists && !(await this.isManaged(target))) {
+                return { ok: false, message: `目标技能「${target}」不是 family-managed；拒绝提交。` };
+            }
+            if (await this.io.exists(markerPath(dir, 'pinned'))) {
+                return { ok: false, message: `目标技能「${target}」已被固定；拒绝提交。` };
+            }
             const targetProtection = await this.writeProtection(target, plan.origin);
             if (targetProtection)
                 return { ok: false, message: `技能「${target}」受保护（${targetProtection}）。` };
@@ -1971,7 +2117,38 @@ export class SkillLibrary {
                     return { ok: false, message: `来源技能「${source}」在计划之后被改过；拒绝提交（未写入任何内容）。` };
                 sourceBodies.set(source, body);
             }
-            const validation = validateFrontmatter(plan.body, target, this.limits);
+            // Decision-time CAS (FR-EXEC-12/GAP-CAND-02): the body compare above only covers
+            // SKILL.md; a changed support file (or a changed target body recorded with different
+            // formatting) would still slip through. Re-hash the LIVE tree with the same canonical
+            // fingerprint the decision recorded and refuse before the first write.
+            if (plan.targetRevision !== undefined) {
+                const liveTargetRevision = await this.revisionAnchor(target);
+                if (!sameRevisionAnchor(plan.targetRevision, liveTargetRevision)) {
+                    return { ok: false, code: 'target-changed', message: `目标技能「${target}」的内容在决策之后被改过；拒绝提交（未写入任何内容）。` };
+                }
+            }
+            if (plan.sourceRevisions !== undefined) {
+                for (const [name, expected] of Object.entries(plan.sourceRevisions)) {
+                    if (!sources.includes(name))
+                        continue;
+                    const live = await this.revisionAnchor(name);
+                    if (!sameRevisionAnchor(expected, live)) {
+                        return { ok: false, code: 'source-changed', message: `来源技能「${name}」的内容在决策之后被改过；拒绝提交（未写入任何内容）。` };
+                    }
+                }
+            }
+            if (plan.supportDigest !== undefined) {
+                const fingerprints = [];
+                for (const name of [target, ...sources]) {
+                    const fingerprint = await this.revisionFingerprint(name);
+                    if (fingerprint !== null)
+                        fingerprints.push(fingerprint);
+                }
+                if (revisionSupportDigest(fingerprints) !== plan.supportDigest) {
+                    return { ok: false, code: 'support-changed', message: '参与合并的技能支撑文件在决策之后被改过；拒绝提交（未写入任何内容）。' };
+                }
+            }
+            const validation = validateFrontmatter(plan.body, target, limits);
             if (validation)
                 return { ok: false, message: validation };
             const supportPaths = new Set();
@@ -1983,8 +2160,8 @@ export class SkillLibrary {
                 if (supportPaths.has(file.path))
                     return { ok: false, message: `支撑文件重复：${file.path}` };
                 supportPaths.add(file.path);
-                if (Buffer.byteLength(file.content, 'utf8') > this.limits.maxSkillFileBytes)
-                    return { ok: false, message: `支撑文件超过 ${this.limits.maxSkillFileBytes} 字节：${file.path}` };
+                if (Buffer.byteLength(file.content, 'utf8') > limits.maxSkillFileBytes)
+                    return { ok: false, message: `支撑文件超过 ${limits.maxSkillFileBytes} 字节：${file.path}` };
                 const threat = this.contentThreatBlock(file.content);
                 if (threat)
                     return { ok: false, message: threat };
@@ -2000,7 +2177,7 @@ export class SkillLibrary {
                 if (!existing)
                     return { ok: false, message: `正文引用了未提供的支撑文件「${ref}」；拒绝提交。` };
             }
-            const unitId = 'u-' + Date.now().toString(36) + '-' + (nextUnitSeq += 1).toString(36);
+            const unitId = plan.unitId ?? ('u-' + Date.now().toString(36) + '-' + (nextUnitSeq += 1).toString(36));
             const supportMoves = plan.supportFiles.map((file) => {
                 const previous = supportPrevious.get(file.path) ?? null;
                 return {
@@ -2012,6 +2189,8 @@ export class SkillLibrary {
                 };
             });
             const unitHead = {
+                ...(plan.runId === undefined ? {} : { runId: plan.runId }),
+                baseline: true,
                 moves: supportMoves,
                 sources: [{ skill: target }, ...sources.map(source => ({ skill: source }))],
             };
@@ -2081,6 +2260,9 @@ export class SkillLibrary {
                         expected: supportPrevious.get(file.path) ?? null,
                     })),
                 ];
+                await plan.onPhase?.('target-pending');
+                if (plan.assertFence !== undefined && !(await plan.assertFence()))
+                    return { ok: false, message: 'tree fence lost before target write' };
                 const result = await this.applyTreeChange({
                     name: target,
                     origin: plan.origin,
@@ -2094,13 +2276,28 @@ export class SkillLibrary {
                 });
                 if (!result.ok)
                     return rollbackMessage(result.message, []);
+                await plan.onPhase?.('target-applied');
+                await plan.onPhase?.('target-written');
+                if (plan.signal?.aborted) {
+                    const stuck = await rollbackTarget();
+                    return rollbackMessage('cancelled before sources archived', stuck);
+                }
                 for (const source of sources) {
+                    if (plan.signal?.aborted) {
+                        const stuck = await rollbackSources();
+                        stuck.push(...await rollbackTarget());
+                        return rollbackMessage('cancelled before next source archive', stuck);
+                    }
                     const fresh = await this.io.readText(join(this.dirOf(source), 'SKILL.md'));
                     if (fresh !== sourceBodies.get(source)) {
                         const stuck = await rollbackSources();
                         stuck.push(...await rollbackTarget());
                         return rollbackMessage(`来源技能「${source}」在归档前被改过`, stuck);
                     }
+                    if (plan.assertFence !== undefined && !(await plan.assertFence())) {
+                        return { ok: false, message: 'tree fence lost before source archive; recovery required' };
+                    }
+                    await plan.onPhase?.('source-archiving', { source });
                     const archivedResult = await this.archive(source, {
                         absorbedInto: target,
                         unitId,
@@ -2114,12 +2311,31 @@ export class SkillLibrary {
                     }
                     archived.push(source);
                 }
+                await plan.onPhase?.('sources-archived');
+                await this.foldArchivedUsage(sources, new Date().toISOString());
+                await plan.onPhase?.('unit-written');
                 return { ok: true, message: `已把 ${sources.join(', ')} 合并进「${target}」。`, unitId, targetPath: dir, archived, mutations: 1 + sources.length };
             }
-            const created = await this.createCore(target, plan.body, plan.origin, { unitId, unitHead });
+            await plan.onPhase?.('target-pending');
+            if (plan.assertFence !== undefined && !(await plan.assertFence()))
+                return { ok: false, message: 'tree fence lost before target write' };
+            const created = await this.createCore(target, plan.body, plan.origin, { unitId, unitHead, managed: true });
             if (!created.ok)
                 return { ok: false, message: created.message };
+            await plan.onPhase?.('target-applied');
+            await plan.onPhase?.('target-written');
+            if (plan.signal?.aborted) {
+                const targetRollback = await this.archive(target, { reason: 'merge cancelled' }, plan.origin);
+                return rollbackMessage('cancelled before sources archived', targetRollback.ok ? [] : [target]);
+            }
             for (const source of sources) {
+                if (plan.signal?.aborted) {
+                    const stuck = await rollbackSources();
+                    const targetRollback = await this.archive(target, { reason: 'merge cancelled' }, plan.origin);
+                    if (!targetRollback.ok)
+                        stuck.push(target);
+                    return rollbackMessage('cancelled before next source archive', stuck);
+                }
                 const fresh = await this.io.readText(join(this.dirOf(source), 'SKILL.md'));
                 if (fresh !== sourceBodies.get(source)) {
                     const stuck = await rollbackSources();
@@ -2128,6 +2344,10 @@ export class SkillLibrary {
                         stuck.push(target);
                     return rollbackMessage(`来源技能「${source}」在归档前被改过`, stuck);
                 }
+                if (plan.assertFence !== undefined && !(await plan.assertFence())) {
+                    return { ok: false, message: 'tree fence lost before source archive; recovery required' };
+                }
+                await plan.onPhase?.('source-archiving', { source });
                 const result = await this.archive(source, {
                     absorbedInto: target,
                     unitId,
@@ -2144,6 +2364,10 @@ export class SkillLibrary {
                 archived.push(source);
             }
             if (plan.supportFiles.length > 0) {
+                await plan.onPhase?.('support-pending');
+                if (plan.assertFence !== undefined && !(await plan.assertFence())) {
+                    return { ok: false, message: 'tree fence lost before support write; recovery required' };
+                }
                 const writes = plan.supportFiles.map(file => ({
                     target: join(dir, ...file.path.replace(/\\/g, '/').split('/').filter(Boolean)),
                     content: file.content,
@@ -2168,6 +2392,8 @@ export class SkillLibrary {
                     return rollbackMessage(result.message, stuck);
                 }
             }
+            await plan.onPhase?.('sources-archived');
+            await plan.onPhase?.('unit-written');
             return { ok: true, message: `已把 ${sources.join(', ')} 合并进「${target}」。`, unitId, targetPath: dir, archived, mutations: 1 + sources.length };
         });
     }

package/lib/types/tree-lock.d.ts

@@ -1,14 +1,17 @@
 import type { EvolutionIoLike } from './io.ts';
 export interface TreeLockRecord {
     readonly token: string;
+    readonly epoch: number;
     readonly pid: number;
     readonly startedAt: number;
 }
 export interface TreeLock {
     readonly token: string;
+    readonly epoch: number;
     readonly path: string;
     readonly acquiredAt: number;
     release(): Promise<void>;
+    assertHeld(): Promise<boolean>;
 }
 export type TreeLockAcquireResult = {
     readonly ok: true;

package/lib/types/tree-lock.js

@@ -25,7 +25,7 @@ function parseLock(raw) {
         const value = JSON.parse(raw);
         if (typeof value.token !== 'string' || typeof value.pid !== 'number' || typeof value.startedAt !== 'number')
             return undefined;
-        return { token: value.token, pid: value.pid, startedAt: value.startedAt };
+        return { token: value.token, epoch: typeof value.epoch === 'number' ? value.epoch : 0, pid: value.pid, startedAt: value.startedAt };
     }
     catch {
         return undefined;
@@ -40,6 +40,7 @@ export async function readTreeLock(io, home) {
 async function tryAcquire(io, home, now) {
     const path = treeLockFile(home);
     let token;
+    let epoch;
     let holder;
     await transactIo(io, path, (current) => {
         const existing = parseLock(current);
@@ -47,11 +48,12 @@ async function tryAcquire(io, home, now) {
             holder = existing;
             return current;
         }
-        // Absent, corrupt, our own stale row, or a dead owner: take it.
+        // Absent, corrupt, our own stale row, or a dead owner: take it and bump the epoch.
         token = randomUUID();
-        return JSON.stringify({ token, pid: process.pid, startedAt: now() });
+        epoch = (existing?.epoch ?? 0) + 1;
+        return JSON.stringify({ token, epoch, pid: process.pid, startedAt: now() });
     });
-    return token === undefined ? (holder === undefined ? {} : { holder }) : { token };
+    return token === undefined ? (holder === undefined ? {} : { holder }) : { token, epoch: epoch ?? 0 };
 }
 /**
  * Acquire the tree write lock, waiting up to `waitMs`.
@@ -71,19 +73,25 @@ export async function acquireTreeWriteLock(options) {
             const attempt = await tryAcquire(options.io, options.home, now);
             if (attempt.token !== undefined) {
                 const token = attempt.token;
+                const epoch = attempt.epoch ?? 0;
                 const path = treeLockFile(options.home);
                 let released = false;
                 const lock = {
                     token,
+                    epoch,
                     path,
                     acquiredAt: now(),
+                    async assertHeld() {
+                        const current = parseLock(await options.io.readText(path));
+                        return current?.token === token && current.epoch === epoch;
+                    },
                     async release() {
                         if (released)
                             return;
                         released = true;
                         await transactIo(options.io, path, (current) => {
                             const existing = parseLock(current);
-                            return existing?.token === token ? null : current;
+                            return existing?.token === token && existing.epoch === epoch ? null : current;
                         });
                     },
                 };

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

@@ -0,0 +1,5 @@
+/** G2 adapter: core UnitBackend over the existing SkillLibrary. */
+import type { SkillLibrary } from './skill-store.ts';
+import type { UnitBackend } from './unit-transaction.ts';
+export declare function skillLibraryUnitBackend(skills: SkillLibrary): UnitBackend;
+//# sourceMappingURL=unit-backend.d.ts.map

package/lib/types/unit-backend.js

@@ -0,0 +1,55 @@
+export function skillLibraryUnitBackend(skills) {
+    return {
+        async readSkill(name) { return await skills.read(name); },
+        async readSupportFile(name, path) {
+            const probe = skills.readSupportFile;
+            return typeof probe === 'function' ? await probe.call(skills, name, path) : null;
+        },
+        async commit(plan, onPhase, signal, assertFence) {
+            const result = await skills.commitMerge({
+                ...(plan.runId === undefined ? {} : { runId: plan.runId }),
+                ...(plan.unitId === undefined ? {} : { unitId: plan.unitId }),
+                target: plan.target,
+                targetExists: plan.targetExists,
+                sources: plan.sources,
+                body: plan.body,
+                supportFiles: plan.supportFiles,
+                expectedTargetBody: plan.expectedTargetBody,
+                expectedSourceBodies: plan.expectedSourceBodies,
+                origin: plan.origin,
+                summary: plan.summary,
+                ...(plan.skillLimits === undefined ? {} : { limits: plan.skillLimits }),
+                ...(plan.targetRevision === undefined ? {} : { targetRevision: plan.targetRevision }),
+                ...(plan.sourceRevisions === undefined ? {} : { sourceRevisions: plan.sourceRevisions }),
+                ...(plan.supportDigest === undefined ? {} : { supportDigest: plan.supportDigest }),
+                ...(onPhase === undefined ? {} : { onPhase }),
+                ...(signal === undefined ? {} : { signal }),
+                ...(assertFence === undefined ? {} : { assertFence }),
+            });
+            return { ok: result.ok, message: result.message, ...(result.code === undefined ? {} : { code: result.code }), ...(result.archived === undefined ? {} : { archived: result.archived }), ...(result.mutations === undefined ? {} : { mutations: result.mutations }) };
+        },
+        async restoreTarget(name, body) {
+            if (body === null) {
+                await skills.archive(name, { reason: 'unit-rollback' });
+                return;
+            }
+            const result = await skills.update(name, body);
+            if (!result.ok)
+                throw new Error(result.message);
+        },
+        async restoreSupportFile(name, path, content) {
+            const result = content === null ? await skills.removeSupportFile(name, path) : await skills.writeSupportFile(name, path, content);
+            if (!result.ok)
+                throw new Error(result.message);
+        },
+        async restoreSource(name, body) {
+            const restored = await skills.restoreFromArchive(name);
+            if (restored.ok)
+                return;
+            const result = await skills.update(name, body);
+            if (!result.ok)
+                throw new Error(result.message);
+        },
+    };
+}
+//# sourceMappingURL=unit-backend.js.map

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

@@ -0,0 +1,29 @@
+import type { EvolutionIoLike } from './io.ts';
+export declare const UNIT_JOURNAL_SCHEMA_VERSION = 1;
+export declare const UNIT_JOURNAL_PHASES: readonly ["prepared", "target-pending", "target-written", "source-archiving", "sources-archived", "support-pending", "unit-written", "committed", "failed", "rolled-back"];
+export type UnitJournalPhase = typeof UNIT_JOURNAL_PHASES[number];
+export interface UnitJournalCheckpoint {
+    readonly source: string;
+    readonly phase: 'archived';
+    readonly hash: string;
+    readonly at: number;
+}
+export interface UnitJournal {
+    readonly schemaVersion: typeof UNIT_JOURNAL_SCHEMA_VERSION;
+    readonly unitId: string;
+    readonly runId: string;
+    readonly planDigest: string;
+    readonly target: string;
+    readonly sources: readonly string[];
+    readonly phase: UnitJournalPhase;
+    readonly storageKey: string;
+    readonly snapshotSha256: string;
+    readonly checkpoints?: readonly UnitJournalCheckpoint[];
+    readonly updatedAt: number;
+}
+export declare function unitJournalPath(home: string, unitId: string): string;
+export declare function unitJournalPhaseRank(phase: UnitJournalPhase): number;
+export declare function assertUnitJournalTransition(from: UnitJournalPhase, to: UnitJournalPhase): void;
+export declare function writeUnitJournal(io: EvolutionIoLike, home: string, journal: UnitJournal): Promise<string>;
+export declare function readUnitJournal(io: EvolutionIoLike, home: string, unitId: string): Promise<UnitJournal | null>;
+//# sourceMappingURL=unit-journal.d.ts.map

package/lib/types/unit-journal.js

@@ -0,0 +1,51 @@
+/** G2 unit journal: intent/phase/checkpoint only, never evidence bodies. */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+export const UNIT_JOURNAL_SCHEMA_VERSION = 1;
+export const UNIT_JOURNAL_PHASES = [
+    'prepared',
+    'target-pending',
+    'target-written',
+    'source-archiving',
+    'sources-archived',
+    'support-pending',
+    'unit-written',
+    'committed',
+    'failed',
+    'rolled-back',
+];
+export function unitJournalPath(home, unitId) {
+    return join(home, 'merge', 'unit-journals', createHash('sha256').update(unitId).digest('hex') + '.json');
+}
+export function unitJournalPhaseRank(phase) {
+    return UNIT_JOURNAL_PHASES.indexOf(phase);
+}
+export function assertUnitJournalTransition(from, to) {
+    if (to === 'failed' || to === 'rolled-back')
+        return;
+    if (from === 'failed' || from === 'rolled-back' || from === 'committed')
+        throw new Error('unit-journal-terminal:' + from);
+    if (unitJournalPhaseRank(to) <= unitJournalPhaseRank(from))
+        throw new Error('unit-journal-nonmonotonic:' + from + '->' + to);
+}
+export async function writeUnitJournal(io, home, journal) {
+    const path = unitJournalPath(home, journal.unitId);
+    const content = JSON.stringify(journal, null, 2) + '\n';
+    if (io.transact !== undefined)
+        await io.transact(path, () => content);
+    else
+        await io.writeText(path, content);
+    return path;
+}
+export async function readUnitJournal(io, home, unitId) {
+    const raw = await io.readText(unitJournalPath(home, unitId));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=unit-journal.js.map

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

@@ -0,0 +1,5 @@
+/** G2 recovery arbitration: unit journal/evidence wins over a legacy commit journal. */
+import type { EvolutionIoLike } from './io.ts';
+export type UnitAuthority = 'unit' | 'legacy' | 'none';
+export declare function resolveUnitAuthority(io: EvolutionIoLike, home: string, unitId: string, legacyExists: boolean): Promise<UnitAuthority>;
+//# sourceMappingURL=unit-recovery.d.ts.map

package/lib/types/unit-recovery.js

@@ -0,0 +1,12 @@
+import { readUnitEvidence, readUnitSnapshot } from "./unit-storage.js";
+import { readUnitJournal } from "./unit-journal.js";
+export async function resolveUnitAuthority(io, home, unitId, legacyExists) {
+    if (await readUnitEvidence(io, home, unitId) !== null)
+        return 'unit';
+    if (await readUnitJournal(io, home, unitId) !== null)
+        return 'unit';
+    if (await readUnitSnapshot(io, home, unitId) !== null)
+        return 'unit';
+    return legacyExists ? 'legacy' : 'none';
+}
+//# sourceMappingURL=unit-recovery.js.map