@nanonets/graft 0.23.1 → 0.24.1

package/dist/skills/versions-fs.js

@@ -0,0 +1,234 @@
+/**
+ * The file side of kept versions (versions.ts): plain reads that never
+ * follow a link or open a FIFO, synced writes, folders kept whole by temp
+ * folder and rename, pruning, lesson files by id and kind, and swapping a
+ * skill's scripts/ with a way back. Nothing here decides whether to write.
+ */
+import { randomBytes } from 'node:crypto';
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { MAX_SKILL_BYTES } from './store-fs.js';
+import { localDate } from './settings.js';
+import { matter } from '../util/front-matter.js';
+import { isGuardrailLesson } from './lessons.js';
+const HAND_KEPT = 3;
+export const V_DIR = /^v([1-9]\d{0,5})$/;
+export function versionsDir(ref) {
+    return join(ref.dir, '.versions');
+}
+export const lst = (p) => {
+    try {
+        return lstatSync(p);
+    }
+    catch {
+        return null;
+    }
+};
+/** The text of a regular file of at most 64 KB, never through a link; null otherwise (a FIFO is never opened). */
+export function regularText(path) {
+    const s = lst(path);
+    if (!s?.isFile() || s.size > MAX_SKILL_BYTES)
+        return null;
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** A new file, written and synced (O_EXCL: never over something there). */
+export function writeSynced(path, data, mode = 0o600) {
+    const fd = openSync(path, 'wx', mode);
+    try {
+        const buf = Buffer.from(data, 'utf8');
+        for (let off = 0; off < buf.length;)
+            off += writeSync(fd, buf, off, buf.length - off);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function syncDir(dir) {
+    try {
+        const fd = openSync(dir, 'r');
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch { /* not every platform syncs a folder */ }
+}
+/** A folder of ours, made 0700; a link or a file in its place refuses (throws). */
+export function ownDir(dir) {
+    const s = lst(dir);
+    if (s && !s.isDirectory())
+        throw new LinkError(dir);
+    if (!s)
+        mkdirSync(dir, { mode: 0o700 });
+}
+export class LinkError extends Error {
+}
+/** The plain files of `from` (scripts/, lessons/) copied into a new folder `to`; links and folders inside are left out. */
+export function copyFlat(from, to, mode, only) {
+    if (!lst(from)?.isDirectory())
+        return 0;
+    let n = 0;
+    for (const name of readdirSync(from)) {
+        if (name.startsWith('.') || (only && !only(name)))
+            continue;
+        const s = lst(join(from, name));
+        if (!s?.isFile() || s.size > MAX_SKILL_BYTES)
+            continue;
+        if (!n)
+            mkdirSync(to, { mode: 0o700 });
+        writeSynced(join(to, name), readFileSync(join(from, name), 'utf8'), mode);
+        n++;
+    }
+    return n;
+}
+export const tmpName = (dir, tag) => join(dir, `.${tag}.tmp-${randomBytes(4).toString('hex')}`);
+/**
+ * `.versions/<name>/` holding `text` as SKILL.md (and `scripts` copied when given): written in a temp folder, synced,
+ * renamed into place. A folder already there with the same SKILL.md is reused; with other bytes, 'changed'.
+ */
+export function keepFolder(ref, name, text, scripts) {
+    const vdir = versionsDir(ref);
+    ownDir(vdir);
+    const at = join(vdir, name);
+    if (lst(at))
+        return regularText(join(at, 'SKILL.md')) === text && lst(at).isDirectory() ? 'same' : 'changed';
+    const tmp = tmpName(vdir, name);
+    mkdirSync(tmp, { mode: 0o700 });
+    try {
+        writeSynced(join(tmp, 'SKILL.md'), text);
+        if (scripts)
+            copyFlat(scripts, join(tmp, 'scripts'), 0o700);
+        syncDir(tmp);
+        renameSync(tmp, at);
+        syncDir(vdir);
+        return 'kept';
+    }
+    catch (e) {
+        rmSync(tmp, { recursive: true, force: true });
+        throw e;
+    }
+}
+/** The person's edited file kept as `hand-<date>` (`-2`, `-3` the same day; the same bytes reuse it), the last 3 kept. */
+export function keepHand(ref, text, now) {
+    const base = `hand-${localDate(now)}`;
+    for (let k = 1; k < 100; k++) {
+        const name = k === 1 ? base : `${base}-${k}`;
+        const r = keepFolder(ref, name, text, null);
+        if (r !== 'changed') {
+            prune(ref, /^hand-\d{4}-\d{2}-\d{2}(?:-\d+)?$/, HAND_KEPT, name);
+            return name;
+        }
+    }
+    throw new Error('trail: too many kept copies of this skill today');
+}
+/** Removes the oldest folders matching `re` past `keep` (by version number, else by name), never `spare`. */
+export function prune(ref, re, keep, spare) {
+    let names;
+    try {
+        names = readdirSync(versionsDir(ref)).filter((n) => re.test(n) && n !== spare && lst(join(versionsDir(ref), n))?.isDirectory());
+    }
+    catch {
+        return;
+    }
+    const key = (n) => V_DIR.exec(n)?.[1] ?? n;
+    names.sort((a, b) => key(a).localeCompare(key(b), 'en', { numeric: true }));
+    const extra = names.length + (spare ? 1 : 0) - keep;
+    for (const n of names.slice(0, Math.max(0, extra)))
+        rmSync(join(versionsDir(ref), n), { recursive: true, force: true });
+}
+/** The top-level lesson files of a skill folder, with the id and kind readLessons gives them. */
+export function lessonFiles(dir) {
+    let names;
+    try {
+        if (!lst(join(dir, 'lessons'))?.isDirectory())
+            return [];
+        names = readdirSync(join(dir, 'lessons')).filter((n) => n.endsWith('.md') && !n.startsWith('.'));
+    }
+    catch {
+        return [];
+    }
+    return names.flatMap((name) => {
+        const text = regularText(join(dir, 'lessons', name));
+        if (text === null)
+            return [];
+        const fm = matter(text, { scalars: ['id', 'kind', 'skill', 'src', 'at', 'wall'] });
+        if (fm.refused)
+            return [];
+        const d = fm.data;
+        const id = typeof d.id === 'string' ? d.id : '';
+        const lesson = { text: String(fm.content ?? ''), kind: d.kind === 'guardrail' ? 'guardrail' : 'lesson' };
+        return [{ name, id, guardrail: isGuardrailLesson(lesson) }];
+    });
+}
+/** Moves lesson files into `to` (made 0700); a move that fails leaves the lesson riding the block, which is harmless. */
+export function moveLessons(dir, files, to) {
+    if (!files.length)
+        return;
+    try {
+        ownDir(to);
+    }
+    catch {
+        return;
+    }
+    for (const f of files) {
+        try {
+            renameSync(join(dir, 'lessons', f.name), join(to, f.name));
+        }
+        catch { /* stays where it was */ }
+    }
+}
+/** scripts/ replaced by the files in `from` (a folder) or `helpers`; `undo` puts the old ones back, `done` drops them. */
+export function swapScripts(ref, src) {
+    const scripts = join(ref.dir, 'scripts');
+    const s = lst(scripts);
+    if (s && !s.isDirectory())
+        throw new LinkError(scripts);
+    const tmp = tmpName(ref.dir, 'scripts');
+    mkdirSync(tmp, { mode: 0o700 });
+    try {
+        if (src.from)
+            copyFlat(src.from, join(tmp, 'new'), 0o700);
+        else {
+            mkdirSync(join(tmp, 'new'), { mode: 0o700 });
+            for (const h of src.helpers ?? []) {
+                if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(h.file))
+                    throw new Error('trail: a helper script needs a plain file name');
+                writeSynced(join(tmp, 'new', h.file), h.content, 0o700);
+            }
+        }
+        if (!lst(join(tmp, 'new')))
+            mkdirSync(join(tmp, 'new'), { mode: 0o700 });
+        if (s)
+            renameSync(scripts, join(tmp, 'old'));
+        renameSync(join(tmp, 'new'), scripts);
+    }
+    catch (e) {
+        if (!lst(scripts) && lst(join(tmp, 'old')))
+            renameSync(join(tmp, 'old'), scripts);
+        rmSync(tmp, { recursive: true, force: true });
+        throw e;
+    }
+    return {
+        undo: () => {
+            try {
+                if (lst(join(tmp, 'old'))) {
+                    rmSync(scripts, { recursive: true, force: true });
+                    renameSync(join(tmp, 'old'), scripts);
+                }
+            }
+            finally {
+                rmSync(tmp, { recursive: true, force: true });
+            }
+        },
+        done: () => rmSync(tmp, { recursive: true, force: true }),
+    };
+}
+//# sourceMappingURL=versions-fs.js.map

package/dist/skills/versions-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions-fs.js","sourceRoot":"","sources":["../../src/skills/versions-fs.ts"],"names":[],"mappings":"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"}

package/dist/skills/versions.d.ts

@@ -0,0 +1,56 @@
+import type { ChangeOp, CompiledSkill, FoldOp, SkillRef, SkillState } from './types.js';
+export { versionsDir } from './versions-fs.js';
+export declare const VERSIONS_KEPT = 10;
+export type VersionWhy = 'busy' | 'changed' | 'link' | 'io';
+/** Test seam: runs right before the write's state update (step 4), so a test can hold the state lock. */
+export declare const VERSION_SEAMS: {
+    beforeState?: () => void;
+};
+/** Kept version numbers, ascending: `v<n>` folders only (links and files skipped). */
+export declare function listVersions(ref: SkillRef): number[];
+/** The number the next written version gets: one past both the file's own and every kept one. */
+export declare function nextVersion(ref: SkillRef, current: number): number;
+/**
+ * 4.5: keeps the current file, writes `next` as the next version, updates state and the ledger. `next.meta.version`
+ * must be that next number (`nextVersion`), or nothing is written: the bytes written are the bytes shown.
+ */
+export declare function writeNewVersion(ref: SkillRef, next: CompiledSkill, o: {
+    op: ChangeOp;
+    offerId: string | null;
+    baseHash: string;
+    lessonIds?: string[];
+    env?: NodeJS.ProcessEnv;
+    now?: Date;
+}): {
+    ok: true;
+    version: number;
+} | {
+    ok: false;
+    why: 'busy' | 'changed' | 'link' | 'io';
+};
+/** 4.6: the proposal beside a hand-edited file, the person's file kept as hand-<date>. Never touches SKILL.md. */
+export declare function writeProposal(ref: SkillRef, next: CompiledSkill, op: FoldOp | 'replace', env?: NodeJS.ProcessEnv, now?: Date): {
+    path: string;
+    diff: string;
+    hand: string;
+    version: number;
+} | null;
+/**
+ * 4.6 and R8, from a read of the file (`candidatesHere`): a file equal to an unfinished write's hash finishes it; one
+ * equal to the state's hash clears a stale marker; one equal to the proposal is taken as Trail's own (adopted). True
+ * when the file was adopted. One compare when nothing is pending; the locks only on a match.
+ */
+export declare function adoptIfCopied(ref: SkillRef, st: SkillState | null, fileHash: string, env?: NodeJS.ProcessEnv, now?: Date): boolean;
+/**
+ * 4.12, person only (the CLI checks the terminal; the agent guard denies `restore-version`): `.versions/v<n>/` back
+ * as a new version. The current file is kept first (a hand-edited one as hand-<date>, R6). The restored file's
+ * `version` is rewritten to the new number through the round trip; one that doesn't round-trip goes back as it is.
+ */
+export declare function restoreVersion(ref: SkillRef, version: number, env?: NodeJS.ProcessEnv, now?: Date): {
+    ok: true;
+    version: number;
+} | {
+    ok: false;
+    why: 'unknown' | 'busy' | 'link' | 'io';
+};
+//# sourceMappingURL=versions.d.ts.map

package/dist/skills/versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/skills/versions.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAaxF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;AAE5D,yGAAyG;AACzG,eAAO,MAAM,aAAa,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,CAAC;AAE9D,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,EAAE,CAYpD;AAED,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAoJD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,EAAE;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAC9H,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,CASrJ;AAID,kHAAkH;AAClH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GACvI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAyBrE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CA+C9I;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,CAgBtM"}

package/dist/skills/versions.js

@@ -0,0 +1,351 @@
+/**
+ * Kept versions of a personal skill (phase 2 design 2.1, 4.5, 4.6, 4.12):
+ * `skills/<name>/.versions/`. Trail writes a new SKILL.md only over the file
+ * it wrote itself, byte for byte (0 rule 2), and only after the file it is
+ * about to replace is kept as `v<n>/` (0 rule 3). A file the person changed
+ * is never written: the change goes beside it as `proposed-v<n>/`, with the
+ * person's file kept as `hand-<date>/`, and Trail takes the file as its own
+ * again only when the person copied the proposal over it, byte for byte.
+ *
+ * A write marks itself in the state first (`pendingWrite`, R8), so a process
+ * killed between the new file and the state is finished on the next read
+ * instead of looking hand-edited forever. A state that can't be written
+ * puts the old file back (D68). Every path refuses a link, a file that isn't
+ * regular, or one over 64 KB, and fails closed: nothing changes.
+ *
+ * This module never imports the fold (fold.ts imports recall.ts, which
+ * calls `adoptIfCopied`): it writes text it is given.
+ */
+import { readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseSkillMd, renderSkillMd, skillHash } from './skillmd.js';
+import { getSkillState, updateSkillState } from './state.js';
+import { appendLedger } from './ledger.js';
+import { underStoreLock } from './store-fs.js';
+import { phraseSha } from './staleness.js';
+import { rebuildCompiled } from './skill-rebuild.js';
+import { printDiff } from './skill-diff.js';
+import { writePrivate } from '../util/private-fs.js';
+import { copyFlat, keepFolder, keepHand, lessonFiles, LinkError, lst, moveLessons, ownDir, prune, regularText, swapScripts, V_DIR, versionsDir, } from './versions-fs.js';
+export { versionsDir } from './versions-fs.js';
+export const VERSIONS_KEPT = 10;
+/** Test seam: runs right before the write's state update (step 4), so a test can hold the state lock. */
+export const VERSION_SEAMS = {};
+/** Kept version numbers, ascending: `v<n>` folders only (links and files skipped). */
+export function listVersions(ref) {
+    let names;
+    try {
+        if (!lst(versionsDir(ref))?.isDirectory())
+            return [];
+        names = readdirSync(versionsDir(ref));
+    }
+    catch {
+        return [];
+    }
+    return names.flatMap((n) => {
+        const m = V_DIR.exec(n);
+        return m && lst(join(versionsDir(ref), n))?.isDirectory() ? [Number(m[1])] : [];
+    }).sort((a, b) => a - b);
+}
+/** The number the next written version gets: one past both the file's own and every kept one. */
+export function nextVersion(ref, current) {
+    return Math.max(current, 0, ...listVersions(ref)) + 1;
+}
+const intOf = (v) => (typeof v === 'string' && /^[1-9]\d{0,5}$/.test(v) ? Number(v) : 1);
+/** 2.2: what a new version resets. Uses, checked uses, where it came from and when it was added stay. */
+function versionReset(s, hash, asks, at) {
+    s.hash = hash;
+    s.status = 'candidate';
+    s.changedAt = at;
+    s.firings = [];
+    s.lastFails = [];
+    delete s.statusWhy;
+    delete s.prevStatus;
+    delete s.fixHash;
+    s.proposed = null;
+    s.pendingWrite = null;
+    const keep = new Set(asks.split(',').map((p) => p.trim()).filter(Boolean).map(phraseSha));
+    if (s.cueMisses && typeof s.cueMisses === 'object')
+        s.cueMisses = Object.fromEntries(Object.entries(s.cueMisses).filter(([k]) => keep.has(k)));
+}
+const clearPending = (id, env) => {
+    try {
+        updateSkillState(id, (s) => (s ? { ...s, pendingWrite: null } : s), env);
+    }
+    catch { /* the marker is harmless: its hash isn't the file's */ }
+};
+/** 4.5 steps 1 to 6 under the store lock, then the state lock. */
+function commit(ref, c, env, now) {
+    if (ref.scope !== 'personal')
+        return { ok: false, why: 'changed' };
+    try {
+        return underStoreLock(env, () => commitLocked(ref, c, env, now));
+    }
+    catch (e) {
+        if (e instanceof LinkError)
+            return { ok: false, why: 'link' };
+        return { ok: false, why: /busy/.test(e instanceof Error ? e.message : '') ? 'busy' : 'io' };
+    }
+}
+function commitLocked(ref, c, env, now) {
+    // 1. The folder and the file are Trail's: no link, a regular file of at most 64 KB, Trail's own bytes.
+    const dirSt = lst(ref.dir);
+    if (!dirSt || dirSt.isSymbolicLink())
+        return { ok: false, why: dirSt ? 'link' : 'io' };
+    if (!dirSt.isDirectory())
+        return { ok: false, why: 'io' };
+    const vs = lst(versionsDir(ref));
+    if (vs && !vs.isDirectory())
+        return { ok: false, why: 'link' };
+    const fileSt = lst(ref.file);
+    if (fileSt?.isSymbolicLink())
+        return { ok: false, why: 'link' };
+    const text = regularText(ref.file);
+    if (text === null)
+        return { ok: false, why: 'changed' };
+    const parsed = parseSkillMd(text, ref.name);
+    const st = getSkillState(ref.id, env);
+    if (!parsed || parsed.meta.trail !== ref.id || !st || st.scope !== 'personal')
+        return { ok: false, why: 'changed' };
+    const hash = skillHash(text);
+    const handEdited = hash !== st.hash;
+    if (c.baseHash !== null && (handEdited || hash !== c.baseHash))
+        return { ok: false, why: 'changed' };
+    const from = intOf(parsed.meta.version);
+    const to = nextVersion(ref, from);
+    if (c.expect !== undefined && c.expect !== to)
+        return { ok: false, why: 'changed' };
+    const next = c.render(to);
+    const nextHash = skillHash(next);
+    const at = now.toISOString();
+    if (!updateSkillState(ref.id, (s) => (s ? { ...s, pendingWrite: { hash: nextHash, from, at } } : s), env))
+        return { ok: false, why: 'busy' };
+    let swap = null;
+    try {
+        // 2. The file it replaces is kept first: Trail's own as v<from>, a hand-edited one (a restore only) as hand-<date>.
+        let keptAs = null;
+        if (handEdited)
+            keepHand(ref, text, now);
+        else {
+            keptAs = `v${from}`;
+            if (keepFolder(ref, keptAs, text, join(ref.dir, 'scripts')) === 'changed') {
+                clearPending(ref.id, env);
+                return { ok: false, why: 'changed' };
+            }
+        }
+        // 3. The new file (temp file and rename), and for a replace or restore its scripts.
+        if (c.helpers)
+            swap = swapScripts(ref, { helpers: c.helpers });
+        else if (c.restoreFrom && lst(join(c.restoreFrom, 'scripts'))?.isDirectory())
+            swap = swapScripts(ref, { from: join(c.restoreFrom, 'scripts') });
+        writePrivate(ref.file, next);
+        if (regularText(ref.file) !== next)
+            throw new Error('trail: the new SKILL.md did not read back');
+        // 4. The state, then the ledger line. A state that can't be written puts the old file back (D68).
+        VERSION_SEAMS.beforeState?.();
+        const asks = String(parseSkillMd(next, ref.name)?.meta.asks ?? '');
+        const done = updateSkillState(ref.id, (s) => {
+            if (!s)
+                return s;
+            versionReset(s, nextHash, asks, at);
+            return s;
+        }, env);
+        if (!done) {
+            putBack(ref, text, swap);
+            swap = null;
+            clearPending(ref.id, env);
+            return { ok: false, why: 'busy' };
+        }
+        try {
+            swap?.done();
+        }
+        catch { /* the old scripts stay in a dot folder nobody reads */ }
+        swap = null;
+        try {
+            appendLedger(ref.id, { at, event: 'changed', skill: ref.id, op: c.op, from, to, offerId: c.offerId, ...(c.lessonIds?.length ? { lessonIds: c.lessonIds } : {}) }, env);
+        }
+        catch { /* the state is the truth; the ledger is its record */ }
+        // 5. Lessons: folded ones move to lessons/.folded; a replace's go with the old version; a restore brings its own back.
+        try {
+            const files = lessonFiles(ref.dir);
+            if (c.lessonIds?.length)
+                moveLessons(ref.dir, files.filter((f) => c.lessonIds.includes(f.id)), join(ref.dir, 'lessons', '.folded'));
+            if (c.replace && keptAs)
+                moveLessons(ref.dir, files.filter((f) => !f.guardrail), join(versionsDir(ref), keptAs, 'lessons'));
+            if (c.restoreFrom && lst(join(c.restoreFrom, 'lessons'))?.isDirectory()) {
+                const have = new Set(files.map((f) => f.name));
+                copyFlat(join(c.restoreFrom, 'lessons'), join(ref.dir, 'lessons'), 0o600, (n) => n.endsWith('.md') && !have.has(n));
+            }
+        }
+        catch { /* a lesson left riding the block is harmless */ }
+        // 6. Ten kept versions.
+        prune(ref, V_DIR, VERSIONS_KEPT);
+        return { ok: true, version: to };
+    }
+    catch (e) {
+        putBack(ref, text, swap);
+        clearPending(ref.id, env);
+        if (e instanceof LinkError)
+            return { ok: false, why: 'link' };
+        return { ok: false, why: 'io' };
+    }
+}
+/** The old file (and scripts) back, when it isn't already. */
+function putBack(ref, text, swap) {
+    try {
+        if (regularText(ref.file) !== text)
+            writePrivate(ref.file, text);
+    }
+    catch { /* the marker lets the next read tell the new file from a hand edit */ }
+    try {
+        swap?.undo();
+    }
+    catch { /* scripts/ as the new version left it */ }
+}
+/**
+ * 4.5: keeps the current file, writes `next` as the next version, updates state and the ledger. `next.meta.version`
+ * must be that next number (`nextVersion`), or nothing is written: the bytes written are the bytes shown.
+ */
+export function writeNewVersion(ref, next, o) {
+    if (typeof o.baseHash !== 'string' || !o.baseHash)
+        return { ok: false, why: 'changed' };
+    const replace = o.op === 'replace';
+    return commit(ref, {
+        render: (v) => renderSkillMd({ ...next, meta: { ...next.meta, version: String(v) } }),
+        op: o.op, offerId: o.offerId, baseHash: o.baseHash, lessonIds: o.op === 'extend' ? o.lessonIds : undefined,
+        // A fold keeps scripts/ as it is (a rebuilt skill's helpers are names only); a replace writes the fresh compile's (R22).
+        helpers: replace ? next.helpers : null, replace, expect: Number(next.meta.version),
+    }, o.env, o.now ?? new Date());
+}
+/* ---------------------------------------------------------- hand edits (4.6) */
+/** 4.6: the proposal beside a hand-edited file, the person's file kept as hand-<date>. Never touches SKILL.md. */
+export function writeProposal(ref, next, op, env, now = new Date()) {
+    if (ref.scope !== 'personal')
+        return null;
+    try {
+        return underStoreLock(env, () => {
+            const dirSt = lst(ref.dir);
+            if (!dirSt?.isDirectory() || lst(ref.file)?.isSymbolicLink())
+                return null;
+            const current = regularText(ref.file);
+            if (current === null)
+                return null;
+            const version = intOf(next.meta.version);
+            const text = renderSkillMd(next);
+            const name = `proposed-v${version}`;
+            // One proposal at a time: an older one goes first.
+            ownDir(versionsDir(ref));
+            for (const n of readdirSync(versionsDir(ref)))
+                if (/^proposed-/.test(n) && n !== name)
+                    rmSync(join(versionsDir(ref), n), { recursive: true, force: true });
+            if (lst(join(versionsDir(ref), name)))
+                rmSync(join(versionsDir(ref), name), { recursive: true, force: true });
+            keepFolder(ref, name, text, null);
+            const hand = keepHand(ref, current, now);
+            const done = updateSkillState(ref.id, (s) => (s ? { ...s, proposed: { hash: skillHash(text), version, op, at: now.toISOString() } } : s), env);
+            if (!done)
+                return null;
+            const path = join(versionsDir(ref), name, 'SKILL.md');
+            return { path, hand, version, diff: printDiff(current, text, [`${ref.name}/SKILL.md (yours)`, `${ref.name}/.versions/${name}/SKILL.md`]) };
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 4.6 and R8, from a read of the file (`candidatesHere`): a file equal to an unfinished write's hash finishes it; one
+ * equal to the state's hash clears a stale marker; one equal to the proposal is taken as Trail's own (adopted). True
+ * when the file was adopted. One compare when nothing is pending; the locks only on a match.
+ */
+export function adoptIfCopied(ref, st, fileHash, env, now = new Date()) {
+    if (!st || ref.scope !== 'personal' || typeof fileHash !== 'string')
+        return false;
+    const pending = st.pendingWrite && typeof st.pendingWrite === 'object' ? st.pendingWrite : null;
+    const proposed = st.proposed && typeof st.proposed === 'object' ? st.proposed : null;
+    if (pending && (fileHash === pending.hash || fileHash === st.hash)) {
+        // Under the store lock (a try): a write still running holds it, so its own new file is never "finished" here and
+        // then put back by that write (D68), which would leave Trail's file looking hand-edited. The file is read again inside.
+        try {
+            underStoreLock(env, () => {
+                const text = regularText(ref.file);
+                const now = text === null ? null : skillHash(text);
+                if (now !== fileHash)
+                    return;
+                const asks = fileHash === pending.hash ? String(parseSkillMd(text, ref.name)?.meta.asks ?? '') : null;
+                updateSkillState(ref.id, (s) => {
+                    if (!s?.pendingWrite)
+                        return s;
+                    if (fileHash === s.pendingWrite.hash)
+                        versionReset(s, fileHash, asks ?? '', s.pendingWrite.at);
+                    else if (fileHash === s.hash)
+                        s.pendingWrite = null;
+                    return s;
+                }, env);
+            }, 200);
+        }
+        catch { /* busy: the next read finishes it */ }
+        return false;
+    }
+    if (!proposed || fileHash !== proposed.hash)
+        return false;
+    let adopted = false;
+    try {
+        underStoreLock(env, () => {
+            const text = regularText(ref.file);
+            if (text === null || skillHash(text) !== fileHash || lst(ref.dir)?.isSymbolicLink())
+                return;
+            const asks = String(parseSkillMd(text, ref.name)?.meta.asks ?? '');
+            const at = now.toISOString();
+            const done = updateSkillState(ref.id, (s) => {
+                if (!s?.proposed || s.proposed.hash !== fileHash)
+                    return s;
+                versionReset(s, fileHash, asks, at);
+                adopted = true;
+                return s;
+            }, env);
+            if (!done || !adopted)
+                return;
+            try {
+                appendLedger(ref.id, { at, event: 'changed', skill: ref.id, op: 'adopted', from: Math.max(0, proposed.version - 1), to: proposed.version, offerId: null }, env);
+            }
+            catch { /* the state is the truth */ }
+            try {
+                rmSync(join(versionsDir(ref), `proposed-v${proposed.version}`), { recursive: true, force: true });
+            }
+            catch { /* left beside it */ }
+        }, 200);
+    }
+    catch {
+        return false;
+    }
+    return adopted;
+}
+/* ------------------------------------------------------- restore (4.12, P28) */
+/**
+ * 4.12, person only (the CLI checks the terminal; the agent guard denies `restore-version`): `.versions/v<n>/` back
+ * as a new version. The current file is kept first (a hand-edited one as hand-<date>, R6). The restored file's
+ * `version` is rewritten to the new number through the round trip; one that doesn't round-trip goes back as it is.
+ */
+export function restoreVersion(ref, version, env, now = new Date()) {
+    if (!Number.isSafeInteger(version) || version < 1)
+        return { ok: false, why: 'unknown' };
+    const from = join(versionsDir(ref), `v${version}`);
+    const fs = lst(from);
+    if (fs?.isSymbolicLink() || lst(versionsDir(ref))?.isSymbolicLink())
+        return { ok: false, why: 'link' };
+    const old = fs?.isDirectory() ? regularText(join(from, 'SKILL.md')) : null;
+    const parsed = old === null ? null : parseSkillMd(old, ref.name);
+    if (old === null || !parsed || parsed.meta.trail !== ref.id)
+        return { ok: false, why: 'unknown' };
+    const st = getSkillState(ref.id, env);
+    const rebuilt = rebuildCompiled(old, parsed, { source: st?.source ?? null, helpers: [], runId: st?.runId ?? null });
+    const r = commit(ref, {
+        render: (v) => (rebuilt ? renderSkillMd({ ...rebuilt, meta: { ...rebuilt.meta, version: String(v) } }) : old),
+        op: 'restore-version', offerId: null, baseHash: null, restoreFrom: from,
+    }, env, now);
+    if (r.ok)
+        return r;
+    return { ok: false, why: r.why === 'changed' ? 'io' : r.why };
+}
+//# sourceMappingURL=versions.js.map