@lmzhen/dsh-evolution-core 0.30.37 → 0.30.38

package/lib/types/evolution-events.d.ts

@@ -48,7 +48,7 @@ export interface EvolutionEvent {
      * observation anchors (C semantics: `usage` events carry the library-wide
      * count snapshot at the moment the observation window opened), and
      * maintain scans (011: verdict + recommendation count + runId). */
-    type: 'feedback' | 'learn' | 'usage' | 'maintain';
+    type: 'feedback' | 'learn' | 'usage' | 'maintain' | 'hard-cap';
     /** Fold key for a `feedback` event: required and non-empty there (P2-10),
      * optional on the other tags and on a record this version only reads. */
     target?: string | undefined;
@@ -71,6 +71,10 @@ export interface EvolutionEvent {
     window?: {
         opened?: string;
     } | undefined;
+    /** hard-cap: the rejected body size and the write source. */
+    bodyChars?: number | undefined;
+    supportFiles?: number | null | undefined;
+    restructureRounds?: number | undefined;
 }
 /** The durable-write shape of one event: `feedback` REQUIRES a `target` —
  * the fold key the aggregate is keyed by (P2-10). The other tags keep every
@@ -79,7 +83,7 @@ type EvolutionEventInput = (Omit<EvolutionEvent, 'seq' | 'at' | 'target'> & {
     type: 'feedback';
     target: string;
 }) | (Omit<EvolutionEvent, 'seq' | 'at'> & {
-    type: 'learn' | 'usage' | 'maintain';
+    type: 'learn' | 'usage' | 'maintain' | 'hard-cap';
 });
 export declare function eventsFile(home: string): string;
 /** I-5 (v18): one lightweight description of the durable event payload

package/lib/types/evolution-events.js

@@ -77,6 +77,12 @@ export function evolutionEventPayloadIssue(event) {
         case 'learn':
         case 'usage':
             return null;
+        case 'hard-cap':
+            if (typeof event.target !== 'string' || event.target.trim() === '')
+                return 'hard-cap event requires a non-empty target';
+            if (typeof event.bodyChars !== 'number' || !Number.isFinite(event.bodyChars))
+                return 'hard-cap event requires a finite bodyChars';
+            return null;
         default:
             // Unreachable for the declared union; reachable when a JS host writes
             // the file. The cast restores the runtime value the union erased.

package/lib/types/extract-plan.js

@@ -118,18 +118,24 @@ export function planExtract(input) {
         return { ok: false, code: selection.code, message: selection.message };
     if (selection.sections.length === 0)
         return { ok: false, code: 'part-empty', message: 'at least one part is required' };
-    const parts = selection.sections.map(section => ({
-        heading: section.heading,
-        anchor: {
+    const externalRewrites = new Map((input.external ?? []).map(file => [file.ref, file.targetPath]));
+    const parts = selection.sections.map(section => {
+        let movedText = section.text;
+        for (const [from, to] of externalRewrites)
+            movedText = movedText.split(from).join(to);
+        return {
             heading: section.heading,
-            ...(section.anchorStart === undefined ? {} : { start: section.anchorStart }),
-            ...(section.anchorEnd === undefined ? {} : { end: section.anchorEnd }),
-        },
-        sourceText: section.text,
-        movedText: section.text,
-        bytes: Buffer.byteLength(section.text, 'utf8'),
-        sha256: sha256(section.text),
-    }));
+            anchor: {
+                heading: section.heading,
+                ...(section.anchorStart === undefined ? {} : { start: section.anchorStart }),
+                ...(section.anchorEnd === undefined ? {} : { end: section.anchorEnd }),
+            },
+            sourceText: section.text,
+            movedText,
+            bytes: Buffer.byteLength(movedText, 'utf8'),
+            sha256: sha256(movedText),
+        };
+    });
     const ownerName = input.owner.mode === 'covered' ? (input.owner.name ?? input.targetName) : (input.owner.neededOwner ?? input.targetName);
     const pointer = 'This capability now lives in ' + ownerName + '; project-specific facts stay here.';
     const ordered = [...selection.sections].sort((a, b) => a.start - b.start);

package/lib/types/extract-prompt.d.ts

@@ -1,8 +1,4 @@
-/**
- * The frozen semantic prompt for skill extraction. One constant, consumed by
- * explicit extract agents and tests; it is deliberately not part of the review
- * prompt bundle, and no review path injects it.
- */
 export declare const EXTRACT_PROMPT_VERSION = "v1";
 export declare const EXTRACT_PROMPT_V1 = "Inspect the source skill, its linked support files, and the candidate owners\nin the library. A part of the skill (one or more sections) is a separate\ncapability when it has its own trigger and outcome, can be used without the\nparent context, and leaves the parent coherent. If it is separate and a\nclass-level owner covers it, extract that part. If no owner covers it, report\nthe owner gap and name the class-level owner that would be needed. If it mixes\na reusable capability with parent-specific facts, return mixed and name only\nthe reusable part. Otherwise keep it. Keep, extract, mixed, and owner-gap are\nall valid outcomes; no split is required.";
+export declare const EXTRACT_PROMPT_HASH: string;
 //# sourceMappingURL=extract-prompt.d.ts.map

package/lib/types/extract-prompt.js

@@ -3,6 +3,7 @@
  * explicit extract agents and tests; it is deliberately not part of the review
  * prompt bundle, and no review path injects it.
  */
+import { createHash } from 'node:crypto';
 export const EXTRACT_PROMPT_VERSION = 'v1';
 export const EXTRACT_PROMPT_V1 = `Inspect the source skill, its linked support files, and the candidate owners
 in the library. A part of the skill (one or more sections) is a separate
@@ -13,4 +14,5 @@ the owner gap and name the class-level owner that would be needed. If it mixes
 a reusable capability with parent-specific facts, return mixed and name only
 the reusable part. Otherwise keep it. Keep, extract, mixed, and owner-gap are
 all valid outcomes; no split is required.`;
+export const EXTRACT_PROMPT_HASH = createHash('sha256').update(EXTRACT_PROMPT_V1, 'utf8').digest('hex');
 //# sourceMappingURL=extract-prompt.js.map

package/lib/types/extract-request.d.ts

@@ -0,0 +1,32 @@
+import { type OwnerCandidate } from './owner-resolver.ts';
+import { type ExtractPlanDraft } from './extract-plan.ts';
+import type { SkillLibrary } from './skill-store.ts';
+import type { SkillModel } from './skill-model.ts';
+export type ExtractPlanLibrary = Pick<SkillLibrary, 'root' | 'read' | 'listSupportFiles'> & {
+    readonly model: Pick<SkillModel, 'list'>;
+};
+export interface ExtractRequestItem {
+    heading?: string;
+    start?: string;
+    end?: string;
+    to_skill?: string;
+    to_heading?: string;
+}
+export interface ExtractRequestInput {
+    source: string;
+    items: readonly ExtractRequestItem[];
+    outcome?: 'extract' | 'mixed';
+    ownerCovers?: boolean;
+}
+export interface ExtractRequestPlan {
+    ok: true;
+    plan: ExtractPlanDraft;
+    candidates: OwnerCandidate[];
+    warnings?: string[];
+}
+/** Build the one extract plan both the tool and CLI consume. */
+export declare function buildExtractPlanFromLibrary(library: ExtractPlanLibrary, input: ExtractRequestInput): Promise<ExtractRequestPlan | {
+    ok: false;
+    message: string;
+}>;
+//# sourceMappingURL=extract-request.d.ts.map

package/lib/types/extract-request.js

@@ -0,0 +1,155 @@
+import { dirname, join } from 'node:path';
+import { DEFAULT_SKILL_LIMITS } from "./limits.js";
+import { contentHash } from "./mutations.js";
+import { parseFrontmatter } from "./frontmatter.js";
+import { isPresent } from "./probe.js";
+import { findOwnerCandidate, ownerCandidatesFromSummaries } from "./owner-resolver.js";
+import { nearDuplicateSummaries } from "./quality.js";
+import { planExtract } from "./extract-plan.js";
+import { readExternalSupport } from "./external-support.js";
+/** Build the one extract plan both the tool and CLI consume. */
+export async function buildExtractPlanFromLibrary(library, input) {
+    const source = input.source.trim();
+    const raw = input.items;
+    if (source === '' || raw.length === 0)
+        return { ok: false, message: 'extract 需要 name 与至少一个 extract 项。' };
+    const requests = [];
+    let target = '';
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object')
+            return { ok: false, message: 'extract 的每一项都必须是对象。' };
+        const heading = typeof item.heading === 'string' ? item.heading.trim().replace(/^#+\s*/, '') : '';
+        const toSkill = typeof item.to_skill === 'string' ? item.to_skill.trim() : '';
+        if (heading === '' || toSkill === '')
+            return { ok: false, message: 'extract 的每一项都需要 heading 与 to_skill。' };
+        if (target === '')
+            target = toSkill;
+        if (target !== toSkill)
+            return { ok: false, message: '一次 extract 只能有一个 to_skill；多目标请分多次调用。' };
+        const toHeading = typeof item.to_heading === 'string' ? item.to_heading.trim().replace(/^#+\s*/, '') : undefined;
+        if (toHeading !== undefined && toHeading !== heading) {
+            return { ok: false, message: 'to_heading 暂不支持改名；G3 要求 heading 与 to_heading 相同。' };
+        }
+        requests.push({
+            heading,
+            ...(typeof item.start === 'string' ? { start: item.start } : {}),
+            ...(typeof item.end === 'string' ? { end: item.end } : {}),
+        });
+    }
+    const sourceMd = await library.read(source);
+    if (sourceMd === null)
+        return { ok: false, message: '技能「' + source + '」不存在。' };
+    if (source === target)
+        return { ok: false, message: 'source 与 target 不能相同。' };
+    const summaries = await library.model.list({ withContent: true, withFrontmatter: true });
+    const lookup = ownerCandidatesFromSummaries(source, summaries);
+    const candidateNames = lookup.candidates.map(candidate => candidate.name);
+    const candidateHint = candidateNames.length === 0
+        ? '当前没有可用 owner candidate（描述为空或被排除）。'
+        : '候选 owner：' + candidateNames.slice(0, 8).join('、') + (candidateNames.length > 8 ? ' 等' : '') + '。';
+    const targetMd = await library.read(target);
+    if (targetMd === null) {
+        const parsed = parseFrontmatter(sourceMd);
+        if (parsed === null)
+            return { ok: false, message: '技能「' + source + '」没有可读取的正文。' };
+        const sourceProbe = await library.listSupportFiles(source);
+        if (!isPresent(sourceProbe))
+            return { ok: false, message: '支撑文件列表不可读；拒绝在不确定的闭包上提取。' };
+        const external = await readExternalSupport(parsed.body, join(library.root, source), dirname(library.root), []);
+        if (!external.ok)
+            return { ok: false, message: external.message };
+        const plan = planExtract({
+            body: parsed.body,
+            sourceName: source,
+            targetName: target,
+            targetExists: false,
+            outcome: 'owner-gap',
+            owner: { mode: 'owner-gap', neededOwner: target, triggerCovers: true, outcomeCovers: false, reason: 'target missing; no auto create' },
+            requests,
+            sourceFiles: sourceProbe.value,
+            targetFiles: [],
+            external: external.files,
+        });
+        if (!plan.ok)
+            return { ok: false, message: plan.message + candidateHint };
+        return { ok: true, plan: plan.plan, candidates: lookup.candidates };
+    }
+    if (targetMd.length > DEFAULT_SKILL_LIMITS.maxSkillContentChars)
+        return { ok: false, message: '目标技能「' + target + '」已超过 ' + DEFAULT_SKILL_LIMITS.maxSkillContentChars + ' 字符，拒绝继续提取。' };
+    const candidate = findOwnerCandidate(lookup, target);
+    if (candidate === undefined)
+        return { ok: false, message: '目标「' + target + '」不是可用的 owner candidate（描述为空或已排除）；owner-gap，不自动 create。' + candidateHint };
+    if (!candidate.managed)
+        return { ok: false, message: '目标「' + target + '」不是家族 managed 技能；拒绝把可复用部分写进不受管目录。' };
+    if (input.ownerCovers === false) {
+        const parsed = parseFrontmatter(sourceMd);
+        if (parsed === null)
+            return { ok: false, message: '技能「' + source + '」没有可读取的正文。' };
+        const sourceProbe = await library.listSupportFiles(source);
+        if (!isPresent(sourceProbe))
+            return { ok: false, message: '支撑文件列表不可读；拒绝在不确定的闭包上提取。' };
+        const external = await readExternalSupport(parsed.body, join(library.root, source), dirname(library.root), []);
+        if (!external.ok)
+            return { ok: false, message: external.message };
+        const plan = planExtract({
+            body: parsed.body,
+            sourceName: source,
+            targetName: target,
+            targetExists: true,
+            outcome: 'owner-gap',
+            owner: { mode: 'owner-gap', neededOwner: target, triggerCovers: false, outcomeCovers: false, reason: 'agent judged the target does not cover this part' },
+            requests,
+            sourceFiles: sourceProbe.value,
+            targetFiles: [],
+            external: external.files,
+        });
+        if (!plan.ok)
+            return { ok: false, message: plan.message + candidateHint };
+        return { ok: true, plan: plan.plan, candidates: lookup.candidates };
+    }
+    const overlaps = nearDuplicateSummaries({
+        candidate: { name: target, description: candidate.description },
+        existing: summaries.filter(summary => summary.name !== source && summary.name !== target),
+    });
+    const overlapWarnings = overlaps.length === 0
+        ? []
+        : ['目标「' + target + '」描述与邻技能重叠：' + overlaps.map(match => match.name + ' (' + match.score.toFixed(2) + ')').join('、') + '；请确认 owner 覆盖，提取仍可继续。'];
+    if (candidate.protectionUnknown || candidate.protectedBy !== null) {
+        return { ok: false, message: '目标「' + target + '」受保护（' + (candidate.protectedBy ?? '未知') + '），拒绝提取。' };
+    }
+    const parsed = parseFrontmatter(sourceMd);
+    if (parsed === null)
+        return { ok: false, message: '技能「' + source + '」没有可读取的正文。' };
+    const sourceProbe = await library.listSupportFiles(source);
+    const targetProbe = await library.listSupportFiles(target);
+    if (!isPresent(sourceProbe) || !isPresent(targetProbe))
+        return { ok: false, message: '支撑文件列表不可读；拒绝在不确定的闭包上提取。' };
+    const external = await readExternalSupport(parsed.body, join(library.root, source), dirname(library.root), targetProbe.value);
+    if (!external.ok)
+        return { ok: false, message: external.message };
+    if (input.outcome !== undefined && input.outcome !== 'extract' && input.outcome !== 'mixed') {
+        return { ok: false, message: 'outcome 只能是 extract 或 mixed；owner-gap 由缺失 target 的路径自动决定。' };
+    }
+    const outcome = input.outcome ?? (requests.some(request => request.start !== undefined || request.end !== undefined) ? 'mixed' : 'extract');
+    const plan = planExtract({
+        body: parsed.body,
+        sourceName: source,
+        targetName: target,
+        targetExists: true,
+        outcome,
+        owner: { mode: 'covered', name: target, triggerCovers: true, outcomeCovers: true, reason: 'explicit target' },
+        requests,
+        sourceFiles: sourceProbe.value,
+        targetFiles: targetProbe.value,
+        external: external.files,
+        anchors: { sourceMdSha256: contentHash(sourceMd), targetMdSha256: contentHash(targetMd) },
+    });
+    if (!plan.ok)
+        return { ok: false, message: plan.message };
+    const projectedChars = targetMd.length + plan.plan.parts.reduce((sum, part) => sum + part.movedText.length + 2, 0);
+    if (projectedChars > DEFAULT_SKILL_LIMITS.maxSkillContentChars) {
+        return { ok: false, message: '目标「' + target + '」投影后约 ' + projectedChars + ' 字符，超过 ' + DEFAULT_SKILL_LIMITS.maxSkillContentChars + ' 上限；拒绝提取。' };
+    }
+    return { ok: true, plan: plan.plan, candidates: lookup.candidates, ...(overlapWarnings.length === 0 ? {} : { warnings: overlapWarnings }) };
+}
+//# sourceMappingURL=extract-request.js.map

package/lib/types/index.d.ts

@@ -44,6 +44,7 @@ export * from './reference-rewrite.ts';
 export * from './support-refs.ts';
 export * from './section-selection.ts';
 export * from './extract-plan.ts';
+export * from './extract-request.ts';
 export * from './owner-resolver.ts';
 export * from './proposal-view.ts';
 export * from './proposal-report.ts';
@@ -92,6 +93,9 @@ export * from './drift-signals.ts';
 export * from './skill-history.ts';
 export * from './unit-members.ts';
 export * from './skill-store.ts';
+export * from './skill-model.ts';
+export * from './mutation-unit.ts';
+export * from './mutation-storage-adapter.ts';
 export * from './skill-revision.ts';
 export * from './store-ledger.ts';
 export * from './reachability.ts';

package/lib/types/index.js

@@ -45,6 +45,7 @@ export * from "./reference-rewrite.js";
 export * from "./support-refs.js";
 export * from "./section-selection.js";
 export * from "./extract-plan.js";
+export * from "./extract-request.js";
 export * from "./owner-resolver.js";
 export * from "./proposal-view.js";
 export * from "./proposal-report.js";
@@ -93,6 +94,9 @@ export * from "./drift-signals.js";
 export * from "./skill-history.js";
 export * from "./unit-members.js";
 export * from "./skill-store.js";
+export * from "./skill-model.js";
+export * from "./mutation-unit.js";
+export * from "./mutation-storage-adapter.js";
 export * from "./skill-revision.js";
 export * from "./store-ledger.js";
 export * from "./reachability.js";

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

@@ -0,0 +1,14 @@
+import type { EvolutionIoLike } from './io.ts';
+import type { MutationJournalPort, MutationSnapshotPort } from './mutation-unit.ts';
+/**
+ * Production adapter onto the existing unit snapshot store. A tree-change
+ * snapshot is encoded as a UnitSnapshot with kind='tree-change'; merge
+ * snapshots do not carry that kind and are ignored by the reader.
+ */
+export declare function unitSnapshotPort(io: EvolutionIoLike, home: string): MutationSnapshotPort;
+/**
+ * Production adapter onto the existing unit journal. It never writes a second
+ * journal file; merge and tree-change units share the one journal directory.
+ */
+export declare function unitJournalPort(io: EvolutionIoLike, home: string): MutationJournalPort;
+//# sourceMappingURL=mutation-storage-adapter.d.ts.map

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

@@ -0,0 +1,107 @@
+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";
+/**
+ * Production adapter onto the existing unit snapshot store. A tree-change
+ * snapshot is encoded as a UnitSnapshot with kind='tree-change'; merge
+ * snapshots do not carry that kind and are ignored by the reader.
+ */
+export function unitSnapshotPort(io, home) {
+    return {
+        async write(snapshot) {
+            const first = snapshot.ops[0];
+            const body = {
+                schemaVersion: 1,
+                unitId: snapshot.unitId,
+                planDigest: contentHash(JSON.stringify(snapshot.ops)),
+                runId: snapshot.unitId,
+                target: first?.target ?? '',
+                targetExists: true,
+                targetBefore: first?.before ?? null,
+                ...(first?.after === null || first?.after === undefined ? {} : { targetAfter: first.after }),
+                supportBefore: [],
+                supportAfter: [],
+                sourceBefore: [],
+                origin: 'foreground',
+                summary: 'tree-change ' + snapshot.unitId,
+                createdAt: snapshot.createdAt,
+                kind: 'tree-change',
+                mutationState: snapshot.state,
+                ...(snapshot.cleanup === undefined ? {} : { cleanup: snapshot.cleanup }),
+                ops: snapshot.ops.map(op => ({
+                    target: op.target,
+                    before: op.before,
+                    after: op.after,
+                    ...(op.skill === undefined ? {} : { skill: op.skill }),
+                })),
+            };
+            await writeUnitSnapshot(io, home, body);
+        },
+        async read(unitId) {
+            const snapshot = await readUnitSnapshot(io, home, unitId);
+            if (snapshot === null || snapshot.kind !== 'tree-change' || snapshot.ops === undefined)
+                return null;
+            return {
+                unitId,
+                state: snapshot.mutationState ?? 'committed',
+                ops: snapshot.ops,
+                ...(snapshot.cleanup === undefined ? {} : { cleanup: snapshot.cleanup }),
+                createdAt: snapshot.createdAt,
+            };
+        },
+        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);
+                }
+                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;
+        },
+    };
+}
+const PHASE = {
+    prepared: 'prepared',
+    'unit-written': 'unit-written',
+    committed: 'committed',
+    failed: 'failed',
+    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.
+ */
+export function unitJournalPort(io, home) {
+    return {
+        async write(record) {
+            const journal = {
+                schemaVersion: 1,
+                unitId: record.unitId,
+                runId: record.unitId,
+                planDigest: contentHash(JSON.stringify(record)),
+                target: record.target ?? record.changed[0] ?? '',
+                sources: record.roots ?? [],
+                phase: PHASE[record.phase],
+                storageKey: unitStorageKey(record.unitId),
+                snapshotSha256: contentHash(JSON.stringify(record)),
+                updatedAt: Date.now(),
+            };
+            await writeUnitJournal(io, home, journal);
+        },
+    };
+}
+//# sourceMappingURL=mutation-storage-adapter.js.map

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

@@ -0,0 +1,164 @@
+import { type transactIo } from './io.ts';
+export interface MutationRoot {
+    name: string;
+    protection: 'write' | 'delete' | 'none';
+}
+export type TreeChangeOp = {
+    kind: 'write';
+    target: string;
+    content: string;
+    expected?: string | null;
+    skill?: string;
+} | {
+    kind: 'delete';
+    target: string;
+    expected?: string | null;
+    skill?: string;
+};
+export interface MutationRequest {
+    name: string;
+    roots: MutationRoot[];
+    ops: TreeChangeOp[];
+    origin: string;
+    auditAction: string;
+    auditSummary: string;
+    eventAction: string;
+    unitId?: string;
+    dryRun?: boolean;
+    /** Optional root directory map; when present, every target must resolve under a declared root. */
+    rootDirs?: Readonly<Record<string, string>>;
+    /** Sidecars that undo/recover must remove after restoring the ops (e.g. a create marker). */
+    cleanupPaths?: readonly string[];
+}
+export interface MutationLimits {
+    maxSkillFileBytes: number;
+    maxSkillContentChars: number;
+}
+export interface MutationValidationError {
+    code: string;
+    message: string;
+    target?: string;
+}
+export interface MutationValidation {
+    ok: boolean;
+    roots: MutationRoot[];
+    ops: TreeChangeOp[];
+    errors: MutationValidationError[];
+}
+/**
+ * Pure preflight for one mutation request. It deliberately does no IO: the
+ * caller must resolve roots and read bodies before this point; the unit kernel
+ * performs CAS/protection/journal after validation.
+ */
+export declare function validateMutationRequest(request: MutationRequest, limits: MutationLimits): MutationValidation;
+export interface MutationJournalRecord {
+    unitId: string;
+    phase: 'prepared' | 'unit-written' | 'committed' | 'failed' | 'undone';
+    changed: readonly string[];
+    target?: string;
+    roots?: readonly string[];
+    error?: string;
+}
+export interface MutationJournalPort {
+    write(record: MutationJournalRecord): Promise<void>;
+}
+export interface MutationLockLease {
+    release(): Promise<void>;
+}
+export interface MutationLockPort {
+    acquire(): Promise<MutationLockLease>;
+}
+export interface MutationSnapshotOp {
+    target: string;
+    before: string | null;
+    after: string | null;
+    skill?: string;
+}
+export interface MutationSnapshot {
+    unitId: string;
+    state: 'prepared' | 'committed' | 'undone';
+    ops: readonly MutationSnapshotOp[];
+    cleanup?: readonly string[];
+    createdAt: number;
+}
+export interface MutationSnapshotPort {
+    write(snapshot: MutationSnapshot): Promise<void>;
+    read(unitId: string): Promise<MutationSnapshot | null>;
+    listPrepared?(): Promise<readonly MutationSnapshot[]>;
+}
+export interface MutationUnitEvent {
+    unitId: string;
+    changed: readonly string[];
+    ops: readonly MutationSnapshotOp[];
+    roots?: readonly string[];
+}
+export interface MutationUnitHooks {
+    committed?(event: MutationUnitEvent): Promise<void> | void;
+    rolledBack?(event: MutationUnitEvent): Promise<void> | void;
+    undone?(event: MutationUnitEvent): Promise<void> | void;
+}
+export interface MutationUnitOptions {
+    io: import('./io.ts').EvolutionIoLike;
+    limits: MutationLimits;
+    serial?: <T>(task: () => Promise<T>) => Promise<T>;
+    lock?: MutationLockPort;
+    journal?: MutationJournalPort;
+    snapshots?: MutationSnapshotPort;
+    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. */
+    transactGuard?: boolean;
+    now?: () => number;
+}
+export interface MutationResult {
+    ok: boolean;
+    unitId: string;
+    dryRun: boolean;
+    changed: string[];
+    errors: MutationValidationError[];
+    warnings?: readonly string[];
+}
+export interface MutationPreviewResult {
+    ok: boolean;
+    unitId: string;
+    roots: MutationRoot[];
+    ops: TreeChangeOp[];
+    errors: MutationValidationError[];
+}
+export declare class MutationUnit {
+    private readonly io;
+    private readonly limits;
+    private readonly serial;
+    private readonly lock;
+    private readonly journal;
+    private readonly snapshots;
+    private readonly hooks;
+    private readonly validateWrite;
+    private readonly transact;
+    private readonly transactGuard;
+    private readonly now;
+    constructor(options: MutationUnitOptions);
+    preview(request: MutationRequest): MutationPreviewResult;
+    apply(request: MutationRequest): Promise<MutationResult>;
+    /** Recover every prepared snapshot known to the port; safe to call at boot. */
+    recoverPrepared(): Promise<MutationResult[]>;
+    /** Converge a prepared unit left by a crash. Every path must be at its after-bytes; a drift refuses the whole recovery. */
+    recover(unitId: string): Promise<MutationResult>;
+    undo(unitId: string): Promise<MutationResult>;
+    private applyOp;
+    private rollback;
+}
+export interface FileMutationLockOptions {
+    waitMs?: number;
+    pollMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Cross-process root mutation lock. A live holder is never stolen; a dead pid
+ * or corrupt record can be taken over. This is separate from merge's run-level
+ * tree lock so an ordinary skill write cannot deadlock a merge run.
+ */
+export declare function fileMutationLock(io: import('./io.ts').EvolutionIoLike, root: string, options?: FileMutationLockOptions): MutationLockPort;
+//# sourceMappingURL=mutation-unit.d.ts.map