@skanl/brambo-projection 0.1.1

package/dist/materialise.js

@@ -0,0 +1,620 @@
+import { lstat, mkdir, readdir, readFile, rm, rmdir, stat } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { BRAMBO_ERROR_CODES, BramboError } from '@skanl/brambo-contracts';
+import { atomicWriteBytes } from './atomic-write.js';
+import { canonicalBytesHash, hashOwnedBytes, hashOwnedText, isUnderRoot, resolveOwnedPath, sameOwnedPath, } from './ledger.js';
+function driftEntry(kind, entryId, location, detail) {
+    return { kind, entryId, location, detail };
+}
+/**
+ * `undefined` — nothing there. `'unreadable'` — something IS there and brambo
+ * cannot read it (a directory where a file was, a mode the user changed).
+ *
+ * The second case is deliberately not a throw: it means "present and not what
+ * brambo wrote", which is drift on one entry, and throwing would fail the whole
+ * target and unmaterialise every OTHER skill for that executor.
+ */
+async function readIfPresent(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        const code = error?.code;
+        return code === 'ENOENT' || code === 'ENOTDIR' ? undefined : 'unreadable';
+    }
+}
+// `isUnderRoot` is the shared boundary check in `ledger.ts`, beside the path
+// canonicalisation it is inseparable from. The destination of every write is
+// built from a root-relative path a target supplied, and a target is ordinary
+// code: it is what stops `../..` in a registry id from turning a projection into
+// an arbitrary write. The REMOVAL path applies the same check to every path a
+// ledger record names, because a record is parsed from a file and is therefore
+// input, not fact — and so does the ADOPT path, because the record it writes is
+// an authority to delete on some later run.
+function absolutePathOf(root, relativePath, entryId) {
+    const resolved = resolveOwnedPath(join(root, ...relativePath.split('/')));
+    if (!isUnderRoot(resolved, root)) {
+        throw new BramboError(BRAMBO_ERROR_CODES.projectionTraitsInvalid, `materialisation target planned '${relativePath}' for entry '${entryId}', which resolves outside its own root '${root}'`);
+    }
+    return resolved;
+}
+async function isLink(path) {
+    try {
+        return (await lstat(path)).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether reaching `path` from `root` passes through any link.
+ *
+ * `lstat` refuses to follow only the FINAL component, so checking the file
+ * alone would miss the case that matters most: a junction at `<root>/<id>`
+ * whose files resolve perfectly through it.
+ */
+async function traversesLink(path, root) {
+    let current = path;
+    while (isUnderRoot(current, root)) {
+        if (await isLink(current))
+            return true;
+        current = dirname(current);
+    }
+    return false;
+}
+/** Machine-independent identity of a whole tree: its paths and their bytes. */
+function treeHash(root, owned) {
+    return hashOwnedText(JSON.stringify(owned.map((entry) => [relative(root, entry.path).split(sep).join('/'), entry.contentHash])));
+}
+/**
+ * `rmdir` upward from a directory brambo emptied, stopping at the first one that
+ * is not empty and never reaching the root.
+ *
+ * `rmdir` rather than a recursive delete on purpose: it REFUSES a directory
+ * that still holds anything, so a foreign file the user put inside brambo's tree
+ * keeps its directory alive without brambo having to notice it. It does NOT
+ * refuse a junction to a non-empty directory — measured — so a link stops the
+ * walk before `rmdir` is ever reached.
+ */
+async function pruneEmptyDirectories(from, root) {
+    let directory = from;
+    while (isUnderRoot(directory, root)) {
+        if (await isLink(directory))
+            return;
+        try {
+            await rmdir(directory);
+        }
+        catch {
+            return;
+        }
+        directory = dirname(directory);
+    }
+}
+/**
+ * Whether anything at all occupies `path`. An error brambo cannot classify is
+ * reported as OCCUPIED: the caller uses this to prove a location is free, and an
+ * unreadable answer is not a proof.
+ */
+async function occupied(path) {
+    try {
+        await stat(path);
+        return { taken: true, detail: 'it already exists' };
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { taken: false, detail: '' };
+        return {
+            taken: true,
+            detail: `brambo could not determine whether it is free (${code ?? 'unknown error'})`,
+        };
+    }
+}
+/**
+ * Whether an entry's own DIRECTORY holds content brambo must not resolve.
+ *
+ * AN EMPTY DIRECTORY IS NOBODY'S CONTENT, and treating one as a foreign
+ * collision built a state with no exit that brambo's own instructions walked the
+ * user into: delete a materialised `SKILL.md` and its directory survives; doctor
+ * reports `removed-by-user` and says `release` frees the location so the next
+ * run writes it back; `release` drops the claim; the next run then finds the
+ * EMPTY directory, calls it foreign and refuses; `adopt` has nothing to claim
+ * and refuses; `release` has no claim left and refuses. Exit 1 forever, escapable
+ * only with `rmdir` by hand. Brambo was refusing to write in order to protect
+ * nothing.
+ *
+ * The protection that stays exactly as it was: a directory holding ANY entry is
+ * foreign, and so is one brambo cannot list — an unreadable answer is not a proof
+ * that a location is free. A LINK is occupation whatever it points at, because
+ * writing through it lands outside the root brambo owns.
+ */
+async function occupiedByContent(directory) {
+    const state = await occupied(directory);
+    if (!state.taken)
+        return state;
+    if (await isLink(directory))
+        return state;
+    try {
+        if ((await readdir(directory)).length > 0)
+            return state;
+    }
+    catch {
+        return state;
+    }
+    return { taken: false, detail: '' };
+}
+/** One spelling of a path for set membership, matching `sameOwnedPath`. */
+function pathKey(path) {
+    const resolved = resolveOwnedPath(path);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/**
+ * The ONE place a materialisation plan is obtained, and the one place the
+ * SOURCE-IS-THE-DESTINATION verdict is reached (spec M9.A amendment 3).
+ *
+ * `brambo ingest` reads the same roots the projection writes into, so an ingested
+ * skill arrives already sitting at one of its own destinations. Brambo's ledger
+ * does not claim it — brambo did not write it — and the plain reading of that was
+ * `foreign-collision`, so using the feature immediately reported a broken
+ * environment. The verdict was also factually wrong: the bytes that should be
+ * there ARE there, byte for byte, because the file brambo would copy FROM and the
+ * file brambo would copy TO are the same file.
+ *
+ * So the entry is ALREADY SATISFIED: nothing to write, nothing to claim, no
+ * drift. It stays in `presentEntryIds`, which is what keeps it out of the
+ * removal path, and it is deliberately NOT reported as `skipped` — a skipped
+ * entry is one a target could not express (C5), and this one is expressed
+ * perfectly. Reporting it would be reporting a problem that is not there.
+ *
+ * NOT ADOPTED, and that is the load-bearing half: brambo did not write these
+ * bytes, so claiming them would make `brambo remediate release` an authority to
+ * delete a skill the user owns. The ledger keeps telling the truth.
+ *
+ * Both consumers of a plan route through here — the engine below and
+ * {@link claimMaterialised} — so the rule is stated once rather than guarded at
+ * each decision that would otherwise have to re-derive it.
+ */
+async function planFor(target, entries, claimed, root) {
+    const plan = await target.plan({ entries, records: claimed, rootPath: root });
+    const satisfied = new Set();
+    for (const entry of plan.entries) {
+        // CANONICAL comparison, never string equality: a target's `sourcePath` and
+        // the destination brambo builds from the root are two spellings arrived at by
+        // different routes, and on win32 they can differ in drive-letter and
+        // directory casing while naming one file. `pathKey` is the same spelling the
+        // removal path keys ownership on.
+        const same = entry.files.every((file) => {
+            let destination;
+            try {
+                destination = absolutePathOf(root, file.relativePath, entry.entryId);
+            }
+            catch {
+                // Outside the root: not satisfied, and the ordinary path reports it.
+                return false;
+            }
+            return pathKey(destination) === pathKey(file.sourcePath);
+        });
+        if (same && entry.files.length > 0)
+            satisfied.add(entry.entryId);
+    }
+    if (satisfied.size === 0)
+        return { plan, satisfied };
+    return {
+        plan: { ...plan, entries: plan.entries.filter((entry) => !satisfied.has(entry.entryId)) },
+        satisfied,
+    };
+}
+/**
+ * The ledger record that would claim the tree currently at one entry's location
+ * — the materialisation half of `adopt`, and the exit from every reported state
+ * a skills root can be in: a `foreign-collision` (brambo's own tree left
+ * unclaimed by a crash included), an `edited` tree, and a tree that is only
+ * PARTLY there.
+ *
+ * IT LIVES HERE, BESIDE THE REMOVAL RULE, ON PURPOSE. A record this returns is
+ * an authority to DELETE on some later run, so every clause of that rule is
+ * applied while the record is built rather than trusted afterwards: the paths
+ * come from the target's own plan (never from a directory listing, so a file the
+ * user put beside brambo's is not swept into the claim and cannot later be
+ * removed); each is resolved and containment-checked against the root; a link
+ * anywhere between the root and the file disqualifies it; and a path any OTHER
+ * record already claims is refused rather than duplicated.
+ *
+ * A PARTIALLY PRESENT TREE IS CLAIMED AS THE SUBSET THAT IS THERE, and that is
+ * the correction that gives that state an exit at all. Claiming the whole
+ * planned set would write a record reading `edited` on the very next run — the
+ * state adoption exists to leave — so brambo claims exactly the files that exist,
+ * the record reads `intact`, and the ordinary run writes the missing ones back.
+ * Refusing instead (the first shipped shape) left three separate routes into a
+ * tree with no exit but `rm -rf`: `release` on an edited tree, a crash inside
+ * `land()` between two file writes, and a user deleting one file from a skill.
+ *
+ * ponytail: when a record claims MORE paths than the plan wants — a file that
+ * left the source — adoption claims the planned subset and lets that path go
+ * unclaimed, so the ordinary run stops being authorised to take it back and it
+ * stays inside brambo's tree. Under-claiming, which is the safe direction and the
+ * one this whole file errs towards; the alternative is claiming the union, which
+ * widens what an explicit user action makes deletable. Upgrade path: claim the
+ * union once a case exists where the leftover file matters.
+ *
+ * WHEN THE ENTRY HAS LEFT THE REGISTRY the plan holds nothing for it, and the
+ * ledger record is the fallback authority — that is the shape reported as
+ * `edited` on the removal path, whose only other exit was `release`, which drops
+ * the claim and leaves the tree on disk forever. Adoption there means the next
+ * ordinary run REMOVES the tree, which is why the claim carries `removedNext`
+ * and the caller has to say so before writing it.
+ */
+export async function claimMaterialised(target, entries, claimed, entryId) {
+    const root = resolveOwnedPath(target.rootPath);
+    const { plan, satisfied } = await planFor(target, entries, claimed, root);
+    const planned = plan.entries.find((candidate) => candidate.entryId === entryId);
+    const held = claimed.find((record) => record.entryId === entryId &&
+        record.targetId === target.targetId &&
+        sameOwnedPath(resolveOwnedPath(record.filePath), root) &&
+        (record.ownedPaths ?? []).length > 0);
+    const location = planned?.location ?? held?.nativeLocation ?? entryId;
+    const refuse = (refusal) => ({ location, byteLength: 0, refusal });
+    if (planned === undefined && held === undefined) {
+        if (satisfied.has(entryId)) {
+            // Already satisfied, so there is nothing to adopt — and adopting is the
+            // one thing that must not happen here: brambo did not write these bytes,
+            // and a claim over them is an authority to DELETE them on a later run.
+            return refuse(`'${entryId}' under '${root}' is the very source brambo would copy from, so it is already exactly what brambo would write; brambo did not put it there and will not claim a file it did not write`);
+        }
+        const skipped = (plan.skipped ?? []).find((candidate) => candidate.entryId === entryId);
+        return refuse(skipped?.reason ??
+            `brambo would not materialise '${entryId}' under '${root}' and holds no record of ever having done so, so there is nothing there for brambo to claim`);
+    }
+    // Every path a SURVIVING claim holds, so two registry ids that land on one
+    // path cannot both own it — the same clause 6 the removal path applies, and
+    // for the same reason: a record that claims another entry's file is an
+    // authority to delete it.
+    const otherClaims = new Set(claimed
+        .filter((record) => record.entryId !== entryId)
+        .flatMap((record) => (record.ownedPaths ?? []).map((item) => pathKey(item.path))));
+    // The plan's paths where brambo would write, the RECORD's where brambo no longer
+    // would. Never a directory listing: a file the user added beside brambo's must
+    // stay outside every claim brambo writes.
+    let candidates;
+    if (planned !== undefined) {
+        try {
+            candidates = planned.files.map((file) => absolutePathOf(root, file.relativePath, entryId));
+        }
+        catch (error) {
+            return refuse(error instanceof Error ? error.message : String(error));
+        }
+    }
+    else {
+        candidates = (held?.ownedPaths ?? []).map((item) => resolveOwnedPath(item.path));
+    }
+    const owned = [];
+    let byteLength = 0;
+    let absent = 0;
+    for (const path of candidates) {
+        // Re-checked for the record-derived list too: a record is a file brambo
+        // PARSED, so its paths are input rather than fact.
+        if (!isUnderRoot(path, root)) {
+            return refuse(`'${path}' is outside '${root}'; brambo will not claim a path it cannot prove it owns`);
+        }
+        if (await traversesLink(path, root)) {
+            return refuse(`'${path}' is reached through a link, so it is not a path brambo can prove it owns; brambo will not claim it`);
+        }
+        if (otherClaims.has(pathKey(path))) {
+            return refuse(`'${path}' is already claimed by another registry entry at this root; brambo will not claim one file twice`);
+        }
+        const bytes = await readIfPresent(path);
+        if (bytes === undefined) {
+            // The subset rule. Not a refusal: claiming what IS there is what makes a
+            // partially materialised tree leavable, and the ordinary run writes the
+            // rest back because the record it reads is `intact`.
+            absent += 1;
+            continue;
+        }
+        if (bytes === 'unreadable') {
+            return refuse(`'${path}' cannot be read, so brambo cannot hash what it would be claiming`);
+        }
+        byteLength += bytes.byteLength;
+        owned.push({
+            path,
+            contentHash: hashOwnedBytes(bytes),
+            canonicalHash: canonicalBytesHash(bytes),
+        });
+    }
+    if (owned.length === 0) {
+        return refuse(`nothing of '${entryId}' is on disk under '${root}'${absent === 0 ? '' : ` (${absent} path(s) brambo would claim are absent)`}; there is nothing to claim`);
+    }
+    return {
+        location,
+        byteLength,
+        ownedPaths: owned.map((item) => item.path),
+        removedNext: !plan.presentEntryIds.includes(entryId),
+        record: {
+            targetId: target.targetId,
+            filePath: root,
+            nativeLocation: location,
+            entryId,
+            contentHash: treeHash(root, owned),
+            ownedPaths: owned,
+        },
+    };
+}
+/**
+ * Runs one materialisation target: plan, classify against the ledger, then —
+ * under `apply` — land exactly the difference.
+ *
+ * Under inspection NOTHING touches the filesystem except reads, and
+ * `result.written` reads as "these paths WOULD change", which is the one field
+ * whose sentence the mode alters.
+ */
+export async function materialiseTarget(target, entries, claimed, apply) {
+    const root = resolveOwnedPath(target.rootPath);
+    const { plan } = await planFor(target, entries, claimed, root);
+    const drift = [];
+    const records = [];
+    const skipped = [...(plan.skipped ?? [])];
+    const writes = [];
+    const candidateRemovals = [];
+    const keep = (record) => {
+        records.push(record);
+    };
+    // A record is authority ONLY if it claims PATHS, and only paths inside this
+    // root. Everything else is CARRIED THROUGH UNTOUCHED rather than dropped:
+    // persisting a reduced record set is how a one-run under-claim becomes a
+    // permanent orphan, which Story 2.8's review already declared terminal for
+    // the whole-ledger case. The same rule has to hold per record.
+    const authoritative = [];
+    for (const record of claimed) {
+        const owned = record.ownedPaths ?? [];
+        if (record.targetId !== target.targetId ||
+            !sameOwnedPath(resolveOwnedPath(record.filePath), root) ||
+            owned.length === 0) {
+            keep(record);
+            continue;
+        }
+        // THE ENTRY'S OWN DIRECTORY, not the root. Every path brambo materialises for
+        // an entry lives under `<root>/<nativeLocation>/` — driven on a real run:
+        // `mysk` owns `skills\mysk\SKILL.md` and `skills\mysk\nested\more.md`,
+        // never anything beside them. Containing to the ROOT made one entry's record
+        // authority over every sibling directory in it, and `ownedPaths` is a DELETE
+        // authority: a record for `mysk` claiming `usersk/NOTES.md` deleted a file
+        // brambo never wrote and pruned its directory, exit 0, EMPTY STDERR, zero
+        // drift. Present and hash-matching, so every verdict voted `intact` and the
+        // path reached `candidateRemovals` unopposed.
+        //
+        // `home` is resolved against the root FIRST, so a `nativeLocation` of `..`
+        // or an absolute path is caught by the same comparison rather than widening
+        // the boundary it is supposed to narrow.
+        const home = resolveOwnedPath(join(root, record.nativeLocation));
+        const escaping = isUnderRoot(home, root)
+            ? owned.find((item) => !isUnderRoot(resolveOwnedPath(item.path), home))
+            : owned[0];
+        if (escaping !== undefined) {
+            drift.push(driftEntry('foreign-collision', record.entryId, record.nativeLocation, `brambo's ledger claims '${escaping.path}' for '${record.entryId}', which is outside '${join(root, record.nativeLocation)}'; brambo will not touch a path it cannot prove it owns`));
+            keep(record);
+            continue;
+        }
+        authoritative.push(record);
+    }
+    const sizes = new Map();
+    const states = new Map();
+    for (const record of authoritative) {
+        const owned = record.ownedPaths ?? [];
+        let present = 0;
+        let exact = 0;
+        let canonical = 0;
+        let linked = false;
+        for (const item of owned) {
+            if (await traversesLink(item.path, root)) {
+                linked = true;
+                present += 1;
+                continue;
+            }
+            const bytes = await readIfPresent(item.path);
+            if (bytes === undefined)
+                continue;
+            present += 1;
+            if (bytes === 'unreadable')
+                continue;
+            sizes.set(item.path, bytes.byteLength);
+            if (hashOwnedBytes(bytes) === item.contentHash)
+                exact += 1;
+            // No `canonicalHash` means a record an older build wrote: fall back to the
+            // exact hash, which is the conservative direction for both predicates.
+            if (canonicalBytesHash(bytes) === (item.canonicalHash ?? item.contentHash))
+                canonical += 1;
+        }
+        const total = owned.length;
+        const verdict = (matches) => present === 0 ? 'gone' : !linked && present === total && matches === total ? 'intact' : 'edited';
+        states.set(record.entryId, { remove: verdict(exact), write: verdict(canonical) });
+    }
+    const wanted = new Map(plan.entries.map((entry) => [entry.entryId, entry]));
+    const registered = new Set(plan.presentEntryIds);
+    const byEntry = new Map(authoritative.map((record) => [record.entryId, record]));
+    // 1. Trees whose entry left the REGISTRY. The only removals brambo performs.
+    for (const record of [...authoritative].sort((a, b) => (a.entryId < b.entryId ? -1 : 1))) {
+        if (wanted.has(record.entryId))
+            continue;
+        if (registered.has(record.entryId)) {
+            // Registered, and this run could not render it (an unreadable source, an
+            // id brambo cannot use as a directory). The claim survives untouched, or
+            // the next run would treat brambo's own tree as foreign forever.
+            keep(record);
+            continue;
+        }
+        const state = states.get(record.entryId)?.remove;
+        if (state === 'gone')
+            continue;
+        if (state === 'edited') {
+            drift.push(driftEntry('edited', record.entryId, record.nativeLocation, `'${record.entryId}' under '${root}' is no longer byte-for-byte what brambo wrote, or is reached through a link; brambo will not remove a tree it no longer recognises`));
+            keep(record);
+            continue;
+        }
+        for (const owned of record.ownedPaths ?? [])
+            candidateRemovals.push(owned.path);
+    }
+    // 2. Trees the registry holds. Brambo writes only where it already owns the
+    //    location or where the location is provably free.
+    for (const entry of plan.entries) {
+        const record = byEntry.get(entry.entryId);
+        const directory = absolutePathOf(root, entry.location, entry.entryId);
+        const planned = entry.files.map((file) => ({
+            file,
+            path: absolutePathOf(root, file.relativePath, entry.entryId),
+        }));
+        if (record === undefined) {
+            const state = await occupiedByContent(directory);
+            if (state.taken) {
+                drift.push(driftEntry('foreign-collision', entry.entryId, entry.location, `'${directory}' is not claimed by brambo's ledger and ${state.detail}; brambo will not resolve the collision`));
+                continue;
+            }
+        }
+        else {
+            const state = states.get(entry.entryId)?.write;
+            if (state === 'edited') {
+                drift.push(driftEntry('edited', entry.entryId, entry.location, `'${entry.entryId}' under '${root}' has been edited since brambo wrote it; brambo will not overwrite it`));
+                keep(record);
+                continue;
+            }
+            if (state === 'gone') {
+                drift.push(driftEntry('removed-by-user', entry.entryId, entry.location, `brambo wrote '${entry.entryId}' under '${root}' and it is gone; brambo will not re-add it`));
+                keep(record);
+                continue;
+            }
+            // Intact, but a file the plan wants may still be someone else's: a path
+            // inside brambo's directory that no record claims was put there by hand.
+            const owned = (record.ownedPaths ?? []).map((item) => pathKey(item.path));
+            const foreign = planned.find((item) => !owned.includes(pathKey(item.path)));
+            if (foreign !== undefined && (await occupied(foreign.path)).taken) {
+                drift.push(driftEntry('foreign-collision', entry.entryId, entry.location, `'${foreign.path}' exists and brambo's ledger does not claim it; brambo will not resolve the collision`));
+                keep(record);
+                continue;
+            }
+        }
+        // Every source read BEFORE the first byte lands, so a skill whose source
+        // cannot be read is reported with nothing of it partially materialised.
+        let sources;
+        try {
+            sources = await Promise.all(planned.map(async (item) => await readFile(item.file.sourcePath)));
+        }
+        catch (error) {
+            const code = error?.code ?? 'unknown error';
+            skipped.push({
+                entryId: entry.entryId,
+                reason: `'${entry.entryId}' names a source brambo cannot read (${code}); nothing was materialised for it`,
+            });
+            if (record !== undefined)
+                keep(record);
+            continue;
+        }
+        const newOwned = [];
+        for (const [index, item] of planned.entries()) {
+            const bytes = sources[index];
+            const contentHash = hashOwnedBytes(bytes);
+            const previous = await readIfPresent(item.path);
+            const disk = previous === 'unreadable' ? undefined : previous;
+            // Byte-exact, not canonical: this is the idempotence predicate, and it is
+            // also what quietly repairs a materialised file whose line endings were
+            // rewritten under brambo.
+            if (disk === undefined || hashOwnedBytes(disk) !== contentHash) {
+                writes.push({ path: item.path, bytes, previous: disk });
+            }
+            newOwned.push({ path: item.path, contentHash, canonicalHash: canonicalBytesHash(bytes) });
+        }
+        // A file that left the source is a file brambo still claims: taking it back
+        // is part of keeping the tree equal to the registry, and it is safe because
+        // the whole tree is `intact`.
+        if (record !== undefined) {
+            const keptPaths = newOwned.map((item) => pathKey(item.path));
+            for (const owned of record.ownedPaths ?? []) {
+                if (!keptPaths.includes(pathKey(owned.path)))
+                    candidateRemovals.push(owned.path);
+            }
+        }
+        records.push({
+            targetId: target.targetId,
+            filePath: root,
+            nativeLocation: entry.location,
+            entryId: entry.entryId,
+            contentHash: treeHash(root, newOwned),
+            ownedPaths: newOwned,
+        });
+    }
+    // Clause 6, applied last because it needs the FINAL record set: a path some
+    // surviving record still claims is never removed, whichever entry scheduled
+    // it. Without this the survivor's file disappears with no drift and is then
+    // locked out as `removed-by-user` on the next run.
+    const stillClaimed = new Set(records.flatMap((record) => (record.ownedPaths ?? []).map((item) => pathKey(item.path))));
+    const removals = [];
+    for (const path of candidateRemovals) {
+        if (!stillClaimed.has(pathKey(path))) {
+            removals.push(path);
+            continue;
+        }
+        const location = relative(root, resolveOwnedPath(path)).split(sep).join('/');
+        drift.push(driftEntry('foreign-collision', location, location, `'${path}' is claimed by more than one registry entry at this root; brambo kept it rather than removing a file another entry still owns`));
+    }
+    const written = writes.length > 0 || removals.length > 0;
+    const byteDelta = writes.reduce((total, write) => total + Math.abs(write.bytes.byteLength - (write.previous?.byteLength ?? 0)), 0) + removals.reduce((total, path) => total + (sizes.get(path) ?? 0), 0);
+    if (apply && written)
+        await land(writes, removals, root);
+    return {
+        result: {
+            targetId: target.targetId,
+            written,
+            byteDelta,
+            drift,
+            skippedEntryIds: [...skipped.map((item) => item.entryId)].sort((a, b) => a < b ? -1 : a > b ? 1 : 0),
+            skipped,
+        },
+        records,
+    };
+}
+/**
+ * Lands the plan, or leaves the filesystem as it found it.
+ *
+ * Writes come first and every one of them is reversible — a created file is
+ * deleted again, an overwritten one is restored from the bytes read before the
+ * write — so a failure halfway through a tree leaves no partial tree behind.
+ *
+ * ponytail: the removals that follow are not reversible, and they are last for
+ * that reason. A removal that fails after earlier ones succeeded leaves those
+ * entries still claimed in the ledger (the target failed, so no ledger write
+ * happens) and the next run finishes the job. Upgrade path: a staging directory
+ * per target, which buys real transactionality at the price of copying every
+ * tree twice.
+ */
+async function land(writes, removals, root) {
+    const applied = [];
+    try {
+        for (const write of writes) {
+            await mkdir(dirname(write.path), { recursive: true });
+            await atomicWriteBytes(write.path, write.bytes);
+            applied.push(write);
+        }
+    }
+    catch (error) {
+        for (const write of [...applied].reverse()) {
+            if (write.previous === undefined) {
+                await rm(write.path, { force: true }).catch(() => { });
+                await pruneEmptyDirectories(dirname(write.path), root);
+            }
+            else {
+                await atomicWriteBytes(write.path, write.previous).catch(() => { });
+            }
+        }
+        throw error;
+    }
+    const pruneFrom = new Set();
+    for (const path of removals) {
+        // Last line of defence, and cheap: nothing reaches `rm` without being
+        // inside the root brambo owns. The list was filtered on the same predicate
+        // when it was built; this is the copy that runs next to the syscall.
+        const resolved = resolveOwnedPath(path);
+        if (!isUnderRoot(resolved, root))
+            continue;
+        await rm(resolved, { force: true });
+        pruneFrom.add(dirname(resolved));
+    }
+    for (const directory of pruneFrom)
+        await pruneEmptyDirectories(directory, root);
+}

package/dist/remediate.d.ts

@@ -0,0 +1,65 @@
+import type { ProjectionTarget, RegistryEntriesByKind, RemediationOutcome } from '@skanl/brambo-contracts';
+import type { ProjectionMode } from './engine.ts';
+import type { FileFormat } from './formats.ts';
+import type { ProjectionLedger } from './ledger.ts';
+/** A vendor file that may still hold brambo's own prior output (correction-01 C6). */
+export interface LegacyBlockLocation {
+    /** The executor's target id, carried through so a caller can attribute the row. */
+    readonly targetId: string;
+    readonly filePath: string;
+    readonly fileFormat: FileFormat;
+    /**
+     * The scope directory this file must lie inside — the home directory for the
+     * machine scope, the project root for a project. Brambo derives `filePath` from
+     * its own catalogue, and this is the check that says so out loud rather than
+     * trusting it: a caller reaching this API from outside the CLI supplies both.
+     */
+    readonly rootPath: string;
+}
+interface RemediationBase {
+    /**
+     * Defaults to `'inspect'` — the OPPOSITE default from `runProjection`, and the
+     * same one `remediate` in `@skanl/brambo-environment` uses.
+     *
+     * Two exported layers of one operation with opposite defaults is how the
+     * describe-before-act guarantee becomes true of the command and false of the
+     * SDK surface underneath it, and this is on the FR-29 surface where untyped
+     * callers reach it. Under `'inspect'` NOTHING is written — not the ledger, not
+     * a vendor file — and `changes` reads as "these are the changes this would
+     * make", which is the one field whose sentence the mode alters.
+     */
+    readonly mode?: ProjectionMode;
+}
+export interface AdoptRemediationOptions extends RemediationBase {
+    readonly remediation: 'adopt';
+    readonly target: ProjectionTarget;
+    readonly entryId: string;
+    /** What the registry wants; a materialisation target plans its files from it. */
+    readonly entries: RegistryEntriesByKind;
+    readonly ledger: ProjectionLedger;
+}
+export interface ReleaseRemediationOptions extends RemediationBase {
+    readonly remediation: 'release';
+    readonly target: ProjectionTarget;
+    readonly entryId: string;
+    readonly ledger: ProjectionLedger;
+}
+export interface RepairRemediationOptions extends RemediationBase {
+    readonly remediation: 'repair';
+    readonly ledger: ProjectionLedger;
+}
+export interface DiscardRemediationOptions extends RemediationBase {
+    readonly remediation: 'discard';
+    readonly legacy: LegacyBlockLocation;
+}
+export type RunRemediationOptions = AdoptRemediationOptions | ReleaseRemediationOptions | RepairRemediationOptions | DiscardRemediationOptions;
+/**
+ * Performs — or, under `'inspect'`, describes — exactly one remediation.
+ *
+ * The caller names the verb and its subject; nothing else is touched, and
+ * nothing runs by default. A state brambo will not leave is reported as a coded
+ * refusal in the result rather than thrown, because under inspection "brambo will
+ * not do this, and here is why" is part of the description.
+ */
+export declare function runRemediation(options: RunRemediationOptions): Promise<RemediationOutcome>;
+export {};