@lmzhen/dsh-evolution-core 0.27.3 → 0.29.0

package/lib/types/subagent/types.d.ts

@@ -50,9 +50,48 @@ export interface ChannelSpec<T = undefined> {
     readonly signal?: AbortSignal;
     readonly afterResult?: (child: Agent) => T;
 }
+/** Open one child for a multi-turn conversation. Round 1 is the prompt. */
+export interface ConversationOpenSpec {
+    readonly parent: Agent;
+    readonly label: string;
+    readonly promptText: string;
+    readonly kind: ChannelKind;
+    readonly allow: readonly string[];
+    readonly cwd?: string;
+    readonly agentOptions?: AgentOptions;
+    readonly maxDepth?: number;
+    readonly timeoutMs: number;
+    readonly signal?: AbortSignal;
+}
+export interface ConversationTurnOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ConversationTurn {
+    readonly childId: SessionId;
+    readonly stopReason: SubagentStopReason;
+    readonly text: string;
+    readonly structured?: unknown;
+    readonly diagnostic?: string;
+}
+export type ConversationOutcome = {
+    readonly kind: 'ok';
+    readonly childId: SessionId;
+    readonly turn: ConversationTurn;
+} | {
+    readonly kind: 'unavailable';
+    readonly code: ChannelCode;
+    readonly reason: string;
+} | {
+    readonly kind: 'aborted';
+};
 export interface SubagentChannel {
     readonly state: ChannelState;
     prepare(spec: Pick<ChannelSpec, 'kind' | 'allow'>): Promise<ChannelState>;
     run<T = undefined>(spec: ChannelSpec<T>): Promise<ChannelOutcome<T>>;
+    /** Optional during the staged rollout: open/continue/dispose are the two-turn path. */
+    open?(spec: ConversationOpenSpec): Promise<ConversationOutcome>;
+    continueTurn?(childId: SessionId, promptText: string, options?: ConversationTurnOptions): Promise<ConversationOutcome>;
+    dispose?(childId: SessionId): Promise<void>;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,51 @@
+import type { EvolutionIoLike } from './io.ts';
+export interface TreeLockRecord {
+    readonly token: string;
+    readonly pid: number;
+    readonly startedAt: number;
+}
+export interface TreeLock {
+    readonly token: string;
+    readonly path: string;
+    readonly acquiredAt: number;
+    release(): Promise<void>;
+}
+export type TreeLockAcquireResult = {
+    readonly ok: true;
+    readonly lock: TreeLock;
+} | {
+    readonly ok: false;
+    readonly reason: 'busy' | 'io';
+    readonly holder?: TreeLockRecord;
+    readonly message?: string;
+};
+export interface TreeLockOptions {
+    readonly io: EvolutionIoLike;
+    /** Evolution home; the lock lives at <home>/merge/.tree-lock. */
+    readonly home: string;
+    /** How long to wait for a busy lock. Default 5000 ms. */
+    readonly waitMs?: number;
+    /** Poll interval. Default 25 ms. */
+    readonly pollMs?: number;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/** The one lock path. */
+export declare function treeLockFile(home: string): string;
+/** Read the current holder without creating or changing anything. */
+export declare function readTreeLock(io: EvolutionIoLike, home: string): Promise<TreeLockRecord | undefined>;
+/**
+ * Acquire the tree write lock, waiting up to `waitMs`.
+ *
+ * A live holder is never stolen. A record whose pid is gone (or a corrupt record) is
+ * taken over; that is how a killed process releases its lock without a timer.
+ */
+export declare function acquireTreeWriteLock(options: TreeLockOptions): Promise<TreeLockAcquireResult>;
+/** Acquire, run, release; the lock is released even when the body throws. */
+export declare function withTreeWriteLock<T>(options: TreeLockOptions, body: (lock: TreeLock) => Promise<T>): Promise<{
+    ok: true;
+    value: T;
+} | Exclude<TreeLockAcquireResult, {
+    ok: true;
+}>>;
+//# sourceMappingURL=tree-lock.d.ts.map

package/lib/types/tree-lock.js

@@ -0,0 +1,115 @@
+/**
+ * Cross-process tree write lock.
+ *
+ * The merge run holds this lock for its whole lifetime; curator's pass takes the same
+ * lock. The lock is a cooperative file record, created through `transactIo` so two
+ * processes cannot both win the create. A holder whose pid is gone is stale and may be
+ * taken over; a live pid is always respected, even for a long run (a live long run is
+ * exactly what the lock protects).
+ *
+ * `commitMerge` deliberately does NOT take this lock itself: the run shell owns it, so a
+ * run and its commit share one acquisition. Taking it inside the store would also
+ * deadlock the same-process curator path.
+ */
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { isProcessAlive, transactIo } from "./io.js";
+/** The one lock path. */
+export function treeLockFile(home) {
+    return join(home, 'merge', '.tree-lock');
+}
+function parseLock(raw) {
+    if (raw === null)
+        return undefined;
+    try {
+        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 };
+    }
+    catch {
+        return undefined;
+    }
+}
+const sleepDefault = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/** Read the current holder without creating or changing anything. */
+export async function readTreeLock(io, home) {
+    return parseLock(await io.readText(treeLockFile(home)));
+}
+/** Try once. A stale record (dead pid or unparsable) is replaced. */
+async function tryAcquire(io, home, now) {
+    const path = treeLockFile(home);
+    let token;
+    let holder;
+    await transactIo(io, path, (current) => {
+        const existing = parseLock(current);
+        if (existing !== undefined && isProcessAlive(existing.pid)) {
+            holder = existing;
+            return current;
+        }
+        // Absent, corrupt, our own stale row, or a dead owner: take it.
+        token = randomUUID();
+        return JSON.stringify({ token, pid: process.pid, startedAt: now() });
+    });
+    return token === undefined ? (holder === undefined ? {} : { holder }) : { token };
+}
+/**
+ * Acquire the tree write lock, waiting up to `waitMs`.
+ *
+ * A live holder is never stolen. A record whose pid is gone (or a corrupt record) is
+ * taken over; that is how a killed process releases its lock without a timer.
+ */
+export async function acquireTreeWriteLock(options) {
+    const now = options.now ?? (() => Date.now());
+    const waitMs = options.waitMs ?? 5_000;
+    const pollMs = options.pollMs ?? 25;
+    const sleep = options.sleep ?? sleepDefault;
+    const deadline = now() + Math.max(0, waitMs);
+    let lastHolder;
+    try {
+        for (;;) {
+            const attempt = await tryAcquire(options.io, options.home, now);
+            if (attempt.token !== undefined) {
+                const token = attempt.token;
+                const path = treeLockFile(options.home);
+                let released = false;
+                const lock = {
+                    token,
+                    path,
+                    acquiredAt: now(),
+                    async release() {
+                        if (released)
+                            return;
+                        released = true;
+                        await transactIo(options.io, path, (current) => {
+                            const existing = parseLock(current);
+                            return existing?.token === token ? null : current;
+                        });
+                    },
+                };
+                return { ok: true, lock };
+            }
+            lastHolder = attempt.holder;
+            if (now() >= deadline)
+                break;
+            await sleep(pollMs);
+        }
+        return { ok: false, reason: 'busy', ...(lastHolder !== undefined ? { holder: lastHolder } : {}) };
+    }
+    catch (error) {
+        return { ok: false, reason: 'io', message: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Acquire, run, release; the lock is released even when the body throws. */
+export async function withTreeWriteLock(options, body) {
+    const acquired = await acquireTreeWriteLock(options);
+    if (!acquired.ok)
+        return acquired;
+    try {
+        return { ok: true, value: await body(acquired.lock) };
+    }
+    finally {
+        await acquired.lock.release();
+    }
+}
+//# sourceMappingURL=tree-lock.js.map

package/lib/types/unit-undo-plan.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Cross-skill unit undo planner.
+ *
+ * The curator's single-skill undo already proves the rule: one path is described by
+ * (baseline, oldest after, newest after), and a path the unit created is removed. A merge
+ * unit adds two shapes:
+ *
+ * - a source that the merge ARCHIVED: undo restores it from .archive; it has no live ops;
+ * - a target the merge CREATED: undo archives the target (never hard-deletes it); it has no
+ *   body op.
+ *
+ * The plan is pure; the executor resolves hashes to bytes and applies anchors. Any refusal
+ * means the caller writes nothing.
+ */
+import { type SkillVersion } from './skill-history.ts';
+export interface UnitUndoMember {
+    readonly skill: string;
+    /** Entries of this unit for this skill. */
+    readonly entries: readonly SkillVersion[];
+    readonly status: 'live' | 'archived' | 'missing';
+    /** Required when status is archived: the archived directory to restore from. */
+    readonly archivedPath?: string;
+    /** True when this unit created the skill (the target of a merge-into-new). */
+    readonly createdInUnit?: boolean;
+}
+export interface UnitUndoOp {
+    readonly skill: string;
+    /** '' means SKILL.md; otherwise a support path relative to the skill directory. */
+    readonly path: string;
+    readonly remove: boolean;
+    readonly preUnitHash?: string;
+    /** The bytes the unit left on disk; the executor's CAS anchor. */
+    readonly expectedHash: string;
+}
+export interface UnitUndoRestore {
+    readonly skill: string;
+    readonly archivedPath: string;
+}
+export interface UnitUndoPlan {
+    readonly ops: readonly UnitUndoOp[];
+    readonly restores: readonly UnitUndoRestore[];
+    /** New targets: undo archives them instead of writing a body. */
+    readonly archiveTargets: readonly string[];
+    readonly refusals: readonly string[];
+}
+/** Plan one unit across a live target and any archived sources. */
+export declare function planUnitUndoAcross(members: readonly UnitUndoMember[]): UnitUndoPlan;
+//# sourceMappingURL=unit-undo-plan.d.ts.map

package/lib/types/unit-undo-plan.js

@@ -0,0 +1,94 @@
+/**
+ * Cross-skill unit undo planner.
+ *
+ * The curator's single-skill undo already proves the rule: one path is described by
+ * (baseline, oldest after, newest after), and a path the unit created is removed. A merge
+ * unit adds two shapes:
+ *
+ * - a source that the merge ARCHIVED: undo restores it from .archive; it has no live ops;
+ * - a target the merge CREATED: undo archives the target (never hard-deletes it); it has no
+ *   body op.
+ *
+ * The plan is pure; the executor resolves hashes to bytes and applies anchors. Any refusal
+ * means the caller writes nothing.
+ */
+import { BASELINE_ACTION, entryTarget } from "./skill-history.js";
+function slotsOf(entries) {
+    const body = {};
+    const support = new Map();
+    const refusals = [];
+    for (const entry of entries) {
+        const isSupport = entry.path !== undefined && entryTarget(entry, entries) === 'support';
+        if (!isSupport) {
+            if (entry.action === BASELINE_ACTION)
+                body.baseline ??= entry;
+            else {
+                body.oldest ??= entry;
+                body.newest = entry;
+            }
+            continue;
+        }
+        const path = entry.path;
+        const slot = support.get(path) ?? {};
+        support.set(path, slot);
+        if (entry.action === BASELINE_ACTION)
+            slot.baseline ??= entry;
+        else {
+            slot.oldest ??= entry;
+            slot.newest = entry;
+        }
+    }
+    for (const [path, slot] of support) {
+        if (slot.newest === undefined)
+            refusals.push(`${path}（单元里没有该路径的 after 条目）`);
+    }
+    return { body, support, refusals };
+}
+/** Plan one unit across a live target and any archived sources. */
+export function planUnitUndoAcross(members) {
+    const ops = [];
+    const restores = [];
+    const archiveTargets = [];
+    const refusals = [];
+    for (const member of members) {
+        if (member.status === 'missing') {
+            refusals.push(`${member.skill}（成员技能不在活动树或归档里）`);
+            continue;
+        }
+        if (member.status === 'archived') {
+            if (member.archivedPath === undefined || member.archivedPath === '') {
+                refusals.push(`${member.skill}（归档成员缺少归档路径）`);
+                continue;
+            }
+            restores.push({ skill: member.skill, archivedPath: member.archivedPath });
+            continue;
+        }
+        if (member.createdInUnit === true) {
+            archiveTargets.push(member.skill);
+            continue;
+        }
+        const { body, support, refusals: slotRefusals } = slotsOf(member.entries);
+        refusals.push(...slotRefusals.map(reason => member.skill + '：' + reason));
+        for (const [path, slot] of support) {
+            if (slot.newest === undefined)
+                continue;
+            const preUnitHash = slot.baseline !== undefined ? slot.baseline.hash : slot.oldest?.beforeHash;
+            ops.push({
+                skill: member.skill,
+                path,
+                remove: preUnitHash === undefined,
+                ...(preUnitHash === undefined ? {} : { preUnitHash }),
+                expectedHash: slot.newest.hash,
+            });
+        }
+        if (body.newest !== undefined) {
+            const preUnitHash = body.baseline !== undefined ? body.baseline.hash : body.oldest?.beforeHash;
+            if (preUnitHash === undefined)
+                refusals.push(`${member.skill}：SKILL.md 缺少单元前字节`);
+            else
+                ops.push({ skill: member.skill, path: '', remove: false, preUnitHash, expectedHash: body.newest.hash });
+        }
+    }
+    return { ops, restores, archiveTargets, refusals };
+}
+//# sourceMappingURL=unit-undo-plan.js.map

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

@@ -0,0 +1,28 @@
+import type { SkillActionResult } from './skill-store.ts';
+import type { UnitUndoPlan } from './unit-undo-plan.ts';
+export interface UnitUndoSink {
+    readSkill(skill: string): Promise<string | null>;
+    readSupport(skill: string, path: string): Promise<string | null>;
+    /** Read one blob by hash; null means the blob is gone. */
+    readBlob(hash: string): Promise<string | null>;
+    /** Optional archived-member probe; without it the restore itself is the first proof. */
+    hasArchived?(skill: string): Promise<boolean>;
+    restoreFromArchive(skill: string): Promise<SkillActionResult>;
+    archive(skill: string, reason: string): Promise<SkillActionResult>;
+    updateSkill(skill: string, body: string, anchor: {
+        sha256: string;
+    }): Promise<SkillActionResult>;
+    writeSupportFile(skill: string, path: string, content: string, anchor: {
+        sha256: string;
+    }): Promise<SkillActionResult>;
+    removeSupportFile(skill: string, path: string, anchor: {
+        sha256: string;
+    }): Promise<SkillActionResult>;
+}
+export interface UnitUndoExecution {
+    readonly ok: boolean;
+    readonly message: string;
+    readonly reverted: readonly string[];
+}
+export declare function executeUnitUndo(plan: UnitUndoPlan, sink: UnitUndoSink): Promise<UnitUndoExecution>;
+//# sourceMappingURL=unit-undo.d.ts.map

package/lib/types/unit-undo.js

@@ -0,0 +1,81 @@
+/**
+ * Cross-skill unit undo executor.
+ *
+ * Phase A is a zero-write preflight: every live path still carries the unit's after-bytes and
+ * every pre-unit blob is readable. Phase B restores archived members, applies support files,
+ * writes the body last, then archives a target the unit created. Any preflight refusal means
+ * no write at all.
+ */
+import { contentHash } from "./mutations.js";
+export async function executeUnitUndo(plan, sink) {
+    const refusals = [...plan.refusals];
+    const restores = [];
+    for (const restore of plan.restores) {
+        if (sink.hasArchived !== undefined) {
+            const present = await sink.hasArchived(restore.skill);
+            if (!present)
+                refusals.push(`${restore.skill}（归档成员不在 .archive）`);
+            else
+                restores.push(restore);
+            continue;
+        }
+        restores.push(restore);
+    }
+    const prepared = [];
+    for (const op of plan.ops) {
+        const live = op.path === '' ? await sink.readSkill(op.skill) : await sink.readSupport(op.skill, op.path);
+        if (live === null) {
+            refusals.push(`${op.skill}/${op.path === '' ? 'SKILL.md' : op.path}（盘上文件不存在）`);
+            continue;
+        }
+        if (contentHash(live) !== op.expectedHash) {
+            refusals.push(`${op.skill}/${op.path === '' ? 'SKILL.md' : op.path}（盘上字节已变，回退会覆盖别人的改动）`);
+            continue;
+        }
+        if (op.remove) {
+            prepared.push({ ...op, bytes: '', live });
+            continue;
+        }
+        const bytes = op.preUnitHash === undefined ? null : await sink.readBlob(op.preUnitHash);
+        if (bytes === null) {
+            refusals.push(`${op.skill}/${op.path === '' ? 'SKILL.md' : op.path}（单元前字节读不到：blob ${op.preUnitHash ?? '(missing)'}）`);
+            continue;
+        }
+        prepared.push({ ...op, bytes, live });
+    }
+    if (refusals.length > 0) {
+        return { ok: false, message: `整单元撤销未开始（零写）—— 预检未通过：${refusals.join('；')}。修好后可重试。`, reverted: [] };
+    }
+    const reverted = [];
+    const done = () => reverted.length === 0 ? '无' : reverted.join(', ');
+    for (const restore of restores) {
+        const result = await sink.restoreFromArchive(restore.skill);
+        if (!result.ok)
+            return { ok: false, message: `恢复「${restore.skill}」失败：${result.message} —— 撤销未完成（已回退：${done()}）。`, reverted };
+        reverted.push(restore.skill);
+    }
+    const supportOps = prepared.filter(op => op.path !== '');
+    const bodyOps = prepared.filter(op => op.path === '');
+    for (const op of supportOps) {
+        const result = op.remove
+            ? await sink.removeSupportFile(op.skill, op.path, { sha256: op.expectedHash })
+            : await sink.writeSupportFile(op.skill, op.path, op.bytes, { sha256: op.expectedHash });
+        if (!result.ok)
+            return { ok: false, message: `${op.skill}/${op.path}：${result.message} —— 撤销未完成（已回退：${done()}）。`, reverted };
+        reverted.push(op.skill + '/' + op.path);
+    }
+    for (const op of bodyOps) {
+        const result = await sink.updateSkill(op.skill, op.bytes, { sha256: op.expectedHash });
+        if (!result.ok)
+            return { ok: false, message: `${op.skill}/SKILL.md：${result.message} —— 撤销未完成（已回退：${done()}）。`, reverted };
+        reverted.push(op.skill + '/SKILL.md');
+    }
+    for (const skill of plan.archiveTargets) {
+        const result = await sink.archive(skill, 'merge undone');
+        if (!result.ok)
+            return { ok: false, message: `归档新目标「${skill}」失败：${result.message} —— 撤销未完成（已回退：${done()}）。`, reverted };
+        reverted.push(skill);
+    }
+    return { ok: true, message: `已按单元撤销：${reverted.join(', ')}。`, reverted };
+}
+//# sourceMappingURL=unit-undo.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.27.3",
+  "version": "0.29.0",
   "publishConfig": {
     "access": "public"
   },

package/persisted-write-inventory.json

@@ -171,6 +171,42 @@
       "marker": "transactIo(io(), pathOf(PENDING_ARCHIVE_FILE)",
       "state": [],
       "note": "The resolved-pending archive (the legacy merge target). The store already declared its record map; v46 S1.12 declared the archive append as well — the second site in one file is exactly what the reverse scan exists to find."
+    },
+    {
+      "id": "merge-state",
+      "path": "<evolutionHome>/merge/merge-state.json",
+      "writer": "evolution-merge/src/state.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, mergeStatePath(home)",
+      "state": [],
+      "note": "The merge rows and their persisted round-one decisions. One transaction per mutation; reads stay pure projections."
+    },
+    {
+      "id": "merge-gate-cache",
+      "path": "<evolutionHome>/merge/gate-cache.json",
+      "writer": "evolution-merge/src/gate-cache.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, gateCachePath(home)",
+      "state": [],
+      "note": "The L0-L2 gate cache. A cache is still a durable write and goes through the same transaction seam."
+    },
+    {
+      "id": "merge-tree-lock-acquire",
+      "path": "<evolutionHome>/merge/.tree-lock",
+      "writer": "evolution-core/src/tree-lock.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, path",
+      "state": [],
+      "note": "The cooperative merge/curator tree lock create/replace. Two processes must not both win; the transaction is the lock."
+    },
+    {
+      "id": "merge-tree-lock-release",
+      "path": "<evolutionHome>/merge/.tree-lock",
+      "writer": "evolution-core/src/tree-lock.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(options.io, path",
+      "state": [],
+      "note": "The release half of the same lock: delete only when the recorded token still matches."
     }
   ]
 }