@skanl/brambo-projection 0.1.1

package/dist/ledger.js

@@ -0,0 +1,552 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { BRAMBO_ERROR_CODES, BramboError, PROJECTION_LEDGER_VERSION, isRecord } from '@skanl/brambo-contracts';
+import { acquireLock } from '@skanl/brambo-lock';
+import { atomicWriteText } from './atomic-write.js';
+import { strictFaultLocation } from './document-fault.js';
+// The durable ownership ledger (AD-6, correction-01 C2): brambo's own record of
+// every entry it placed in someone else's file. It lives beside the registry
+// store in brambo's own directory and follows the same atomic temp+rename
+// discipline, but it owns its state alone — @skanl/brambo-projection depends on
+// @skanl/brambo-contracts and nothing else (AD-2), so rendering a config file never
+// drags the Registry store or the microkernel in behind it.
+//
+// The ledger is the ONLY proof of ownership. That is deliberate: no vendor
+// schema can reject a record that lives outside the vendor's file, and no
+// format has to carry a marker it has nowhere to put.
+//
+// Failure policy, and it only bends one way. A ledger that cannot be READ is
+// treated as "brambo has written nothing" for this run, which makes brambo report
+// its own entries as foreign and touch nothing — recoverable. PERSISTING that
+// under-claim is not recoverable: it would orphan every entry brambo has ever
+// written, in every config, with no way back. So an unreadable ledger is never
+// written over; it is reported and left exactly as it is.
+//
+// Writes MERGE: a run replaces only the records for the target and file it just
+// projected, so it can never drop a claim for a target+file pair it did not
+// touch. Merging alone is NOT enough, because `update` rewrites the whole
+// document from a read taken before it: two interleaved read-modify-writes lose
+// one side's claim permanently, and the entry is then a foreign collision
+// forever. Serialisation therefore keys on the LEDGER FILE and is process-wide
+// — two ProjectionLedger INSTANCES over one path share a queue, which is what
+// two concurrent inits in one process actually are.
+const LEDGER_FILE_NAME = 'projection-ledger.json';
+const RECORD_FIELDS = ['targetId', 'filePath', 'nativeLocation', 'entryId', 'contentHash'];
+/**
+ * Hash of the CANONICAL form of the text brambo placed at a native location.
+ *
+ * EOL is normalised because a file that git, an editor or a formatter rewrites
+ * from LF to CRLF has not been edited in any sense a vendor can observe — and
+ * `~/.claude.json` is rewritten by Claude Code itself. Treating that as an edit
+ * would make brambo disown every entry it has in the file. Format-specific
+ * canonicalisation (indentation, key order) happens in the strategies, which
+ * are the only code that knows what "the same entry" means per format.
+ */
+export function hashOwnedText(text) {
+    return createHash('sha256').update(text.replaceAll('\r\n', '\n'), 'utf8').digest('hex');
+}
+/**
+ * Hash of the exact BYTES brambo copied to a path.
+ *
+ * Deliberately not {@link hashOwnedText}: a materialised file is copied verbatim
+ * from a source brambo does not author, so "the same file" means the same bytes.
+ * Normalising EOL here would let brambo overwrite a file whose line endings a
+ * user deliberately changed, and — far worse, since this is the delete path —
+ * let it REMOVE one.
+ */
+export function hashOwnedBytes(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/**
+ * The EOL-normalised form of the same bytes, for the OVERWRITE comparison only.
+ *
+ * Never for a removal. A removal is decided byte for byte, because a false
+ * match there precedes `rm`; an overwrite decided byte for byte instead makes
+ * a skills root kept under `core.autocrlf` report every brambo file as edited
+ * forever, and the product has no adopt, force or reclaim path out of that.
+ */
+export function canonicalBytesHash(bytes) {
+    return hashOwnedText(Buffer.from(bytes).toString('utf8'));
+}
+/** Ownership keys must be one canonical spelling of a path, never two. */
+export function resolveOwnedPath(filePath) {
+    return resolve(filePath);
+}
+/** win32 paths differ in drive-letter and directory casing between processes. */
+export function sameOwnedPath(left, right) {
+    return process.platform === 'win32'
+        ? left.toLowerCase() === right.toLowerCase()
+        : left === right;
+}
+/**
+ * Whether `path` is strictly inside `root`. Both arguments must already be
+ * resolved — this predicate answers about paths, not about strings a caller
+ * hopes are paths.
+ *
+ * It lives beside {@link resolveOwnedPath} because it is the second half of the
+ * same rule: a path brambo acts on is CANONICALISED and then proven to be inside
+ * the location brambo owns. Every caller that skips either half has been a
+ * user-data defect — the removal path took raw ledger strings straight to `rm`,
+ * and a relative one resolved against the process working directory.
+ */
+export function isUnderRoot(path, root) {
+    const rest = relative(root, path);
+    return rest !== '' && !rest.startsWith('..') && !rest.startsWith(sep + '..');
+}
+/**
+ * The right to replace the WHOLE ownership document without merging.
+ *
+ * A module-scope symbol rather than a convention: the only way to hold it is to
+ * import it, so "one caller" stops being a claim a text scan makes and becomes
+ * something the runtime enforces. `test/guard.test.ts` pins who imports it.
+ */
+export const LEDGER_REPAIR_AUTHORITY = Symbol('brambo.projection.ledger.repair');
+/**
+ * A malformed `ownedPaths` makes the WHOLE record invalid, and that direction is
+ * the point: a dropped record claims nothing, so brambo under-claims and removes
+ * nothing. Keeping a record whose path list is half-readable would hand the one
+ * operation that deletes a user's files an authority brambo cannot vouch for.
+ */
+function isOwnedPathList(value) {
+    return (Array.isArray(value) &&
+        value.every((item) => isRecord(item) &&
+            typeof item['path'] === 'string' &&
+            item['path'] !== '' &&
+            typeof item['contentHash'] === 'string' &&
+            item['contentHash'] !== '' &&
+            (item['canonicalHash'] === undefined ||
+                (typeof item['canonicalHash'] === 'string' && item['canonicalHash'] !== ''))));
+}
+function isLedgerRecord(value) {
+    if (!isRecord(value))
+        return false;
+    if (!RECORD_FIELDS.every((field) => typeof value[field] === 'string' && value[field] !== '')) {
+        return false;
+    }
+    return value['ownedPaths'] === undefined || isOwnedPathList(value['ownedPaths']);
+}
+/**
+ * The hash brambo writes for a claim it can still ADDRESS but can no longer
+ * VOUCH for.
+ *
+ * Deliberately not hex. A real `contentHash` is `sha256` output, so this can
+ * never compare equal to one by accident — the never-matching property is
+ * structural rather than improbable. `isLedgerRecord` asks only for a non-empty
+ * string, and nothing anywhere validates the shape, so this survives a round
+ * trip and reads as `edited` forever: brambo knows which bytes the claim covers
+ * and admits it does not know what it wrote there.
+ */
+export const UNVOUCHED_CONTENT_HASH = 'unreadable-after-repair';
+function salvageOwnedPaths(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const salvaged = [];
+    for (const item of value) {
+        // The PATH is the claim; the hashes are only the vouching. An item whose
+        // path is gone names nothing and cannot be salvaged.
+        if (!isRecord(item) || typeof item['path'] !== 'string' || item['path'] === '')
+            continue;
+        const contentHash = item['contentHash'];
+        const canonicalHash = item['canonicalHash'];
+        salvaged.push({
+            path: item['path'],
+            contentHash: typeof contentHash === 'string' && contentHash !== '' ? contentHash : UNVOUCHED_CONTENT_HASH,
+            ...(typeof canonicalHash === 'string' && canonicalHash !== ''
+                ? { canonicalHash }
+                : contentHash === undefined
+                    ? {}
+                    : { canonicalHash: UNVOUCHED_CONTENT_HASH }),
+        });
+    }
+    return salvaged.length === 0 ? undefined : salvaged;
+}
+/**
+ * A record `isLedgerRecord` rejects, reduced to the smallest claim brambo can
+ * still act on — or `undefined` when nothing addressable survives.
+ *
+ * WHY THIS EXISTS. `repair` used to drop every record it could not read, and
+ * dropping the RECORD throws away far more than the broken FIELD: measured, a
+ * record whose only damage was its `contentHash` still carried all four identity
+ * fields, so brambo knew exactly which bytes it covered. Dropping it left `brambo
+ * doctor` reporting NOTHING, `brambo remediate adopt` refusing with exit 1, and
+ * `brambo remove` + `brambo init` leaving the entry in the user's config
+ * permanently — while `repair` printed that those entries "report as foreign
+ * collisions until they are adopted".
+ *
+ * Only `repair` uses this. An ordinary `read()` still drops a malformed record
+ * and warns, because salvaging on every read would silently promote damage into
+ * a claim nobody asked brambo to make.
+ */
+function salvageRecord(value) {
+    if (!isRecord(value))
+        return undefined;
+    // `entryId` is part of `recordKey`, and the other three say WHERE. Without all
+    // four the claim cannot be addressed, updated or removed, so there is nothing
+    // to keep.
+    const identity = ['targetId', 'filePath', 'nativeLocation', 'entryId'];
+    if (!identity.every((field) => typeof value[field] === 'string' && value[field] !== '')) {
+        return undefined;
+    }
+    const owned = value['ownedPaths'];
+    let ownedPaths;
+    if (owned !== undefined) {
+        ownedPaths = salvageOwnedPaths(owned);
+        // For a MATERIALISATION record `ownedPaths` IS the claim: a record without
+        // it claims nothing, so keeping one would be a claim that authorises and
+        // protects nothing while looking like ownership.
+        if (ownedPaths === undefined)
+            return undefined;
+    }
+    const contentHash = value['contentHash'];
+    return {
+        targetId: value['targetId'],
+        filePath: value['filePath'],
+        nativeLocation: value['nativeLocation'],
+        entryId: value['entryId'],
+        contentHash: typeof contentHash === 'string' && contentHash !== '' ? contentHash : UNVOUCHED_CONTENT_HASH,
+        ...(ownedPaths === undefined ? {} : { ownedPaths }),
+    };
+}
+function recordKey(record) {
+    return `${record.targetId}\u0000${record.filePath}\u0000${record.entryId}`;
+}
+/**
+ * Stable on-disk order with a total ordering over the record key, so an
+ * unchanged ledger really is a byte-unchanged file. Later records win a
+ * duplicate key: a run's own output must override whatever it is replacing.
+ */
+function normalizeRecords(records) {
+    const deduped = new Map();
+    for (const record of records)
+        deduped.set(recordKey(record), record);
+    return [...deduped.values()].sort((a, b) => {
+        const left = recordKey(a);
+        const right = recordKey(b);
+        return left < right ? -1 : left > right ? 1 : 0;
+    });
+}
+/**
+ * The exact bytes of the ledger document for a record set.
+ *
+ * Exported so a remediation can PREDICT the document it is about to write and
+ * report the byte delta before writing it, using the same serialisation the
+ * write itself performs. A second spelling here would let a preview report a
+ * size the act does not produce.
+ */
+export function serialiseLedgerDocument(records) {
+    return JSON.stringify({ version: PROJECTION_LEDGER_VERSION, records: normalizeRecords(records) }, null, 2);
+}
+function detailOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Read-modify-write queues, keyed by resolved ledger path. Module-level on
+ * purpose: an instance-level queue serialises one ProjectionLedger object, and
+ * every caller that constructs its own — `initMachine` and `initProject` run
+ * concurrently, for instance — gets its own object over the SAME file.
+ *
+ * This is the INNER boundary and it covers one process. The outer one is the
+ * `<ledger>.lock` file taken in `#locked`, which covers two brambo PROCESSES —
+ * that gap used to lose 10 of 24 claims across three measured rounds, silently,
+ * with every writer exiting 0. The queue is kept rather than replaced: it is
+ * cheaper than a lockfile and it is exactly right for its own case, so the file
+ * lock only ever contends between processes.
+ */
+const LEDGER_QUEUES = new Map();
+/**
+ * The leaf lock's neutral codes, translated at this package's boundary (AD-7).
+ * `@skanl/brambo-lock` may not raise a projection code and this package may not
+ * publish a `BRAMBO_LOCK_*` one, so the mapping lives exactly here.
+ */
+function asLedgerFailure(filePath, error) {
+    if (!(error instanceof BramboError))
+        return error;
+    if (error.code === BRAMBO_ERROR_CODES.lockContention) {
+        return new BramboError(BRAMBO_ERROR_CODES.projectionLedgerContention, `projection ledger '${filePath}' is held by another brambo process: ${error.message}`, { cause: error });
+    }
+    if (error.code === BRAMBO_ERROR_CODES.lockUnavailable) {
+        return new BramboError(BRAMBO_ERROR_CODES.projectionLedgerUnavailable, `projection ledger '${filePath}' could not be locked for writing: ${error.message}`, { cause: error });
+    }
+    return error;
+}
+export class ProjectionLedger {
+    filePath;
+    #queueKey;
+    #lockPath;
+    #lockTimeoutMs;
+    #onStaleLockBreak;
+    constructor(options = {}) {
+        this.filePath = options.filePath ?? join(options.homeDir ?? homedir(), '.brambo', LEDGER_FILE_NAME);
+        const resolved = resolveOwnedPath(this.filePath);
+        this.#queueKey = process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+        // Beside the document, like the registry store's. Derived from the RESOLVED
+        // path so two processes spelling the same ledger differently — a relative
+        // argv, a different drive-letter case on win32 — still contend for one file.
+        this.#lockPath = `${resolved}.lock`;
+        this.#lockTimeoutMs = options.lockTimeoutMs;
+        this.#onStaleLockBreak = options.onStaleLockBreak;
+    }
+    /** Never throws: the three states are what callers must distinguish. */
+    async read() {
+        let raw;
+        try {
+            raw = await readFile(this.filePath, 'utf8');
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT') {
+                return { state: 'absent', records: [], salvaged: [], warnings: [] };
+            }
+            return this.#unreadable(`cannot be read: ${detailOf(error)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // LOCATED, never quoted (`document-fault.ts`). This ledger holds paths and
+            // hashes rather than server arguments, so no leak was measured out of it —
+            // and it is brought under the rule anyway, because "no credential happens
+            // to sit inside V8's snippet window today" is not a property of the code.
+            return this.#unreadable(`is not valid JSON: ${strictFaultLocation(raw)}`);
+        }
+        if (!isRecord(parsed) || parsed['version'] !== PROJECTION_LEDGER_VERSION) {
+            return this.#unreadable(`declares version ${JSON.stringify(isRecord(parsed) ? parsed['version'] : undefined)} but this build reads version ${PROJECTION_LEDGER_VERSION}`);
+        }
+        const records = parsed['records'];
+        if (!Array.isArray(records))
+            return this.#unreadable('has no records array');
+        // One damaged record is not a damaged ledger: keeping the valid claims
+        // keeps brambo able to update and remove everything it still recognises.
+        const valid = records.filter(isLedgerRecord);
+        const dropped = records.length - valid.length;
+        // Computed here because this is the only place that holds the RAW records;
+        // `repair` is the sole consumer and every other caller sees `records` alone.
+        const salvaged = records
+            .filter((record) => !isLedgerRecord(record))
+            .map(salvageRecord)
+            .filter((record) => record !== undefined);
+        return {
+            state: 'readable',
+            records: valid,
+            salvaged,
+            warnings: dropped === 0
+                ? []
+                : [
+                    {
+                        code: BRAMBO_ERROR_CODES.projectionLedgerUnavailable,
+                        detail: `projection ledger '${this.filePath}' has ${dropped} malformed record(s); those entries are no longer claimed by brambo`,
+                    },
+                ],
+        };
+    }
+    /**
+     * Replaces the records this caller TOOK A POSITION ON inside one scope,
+     * keeping every other claim — including claims inside the same scope that
+     * landed after the caller's snapshot was taken.
+     *
+     * `examined` is the third parameter and it is required, because omission used
+     * to mean deletion and nobody could see it. The caller passes the entry ids it
+     * read out of its own ledger snapshot for this scope; `update` adds the ids it
+     * is being handed now. An id in neither set belongs to a writer this caller
+     * never saw, and survives untouched.
+     *
+     * WITHOUT IT, A CONCURRENT RUN ERASES CLAIMS IT DELIBERATELY LEFT ALONE.
+     * Measured on the binary: ten rounds of two concurrent `brambo init` over one
+     * home lost 20 of 40 claims, 20 of 20 processes exited 0, and no stderr line
+     * named foreign, skip, collision or ledger; the one-process control lost 0 of
+     * 40. A wider run lost 72 of 144 and left 16 vendor entries owned by nobody,
+     * after which `brambo doctor` exited 0 reporting `"drift": []` and a later
+     * `remove` + `init` could no longer take those entries back out — brambo had
+     * permanently lost the ability to undo bytes it wrote.
+     *
+     * The mechanism is a granularity mismatch, not a lock. Process B reads the
+     * ledger before A persists, so B's snapshot holds none of A's claims. B then
+     * reads the vendor file, which by now holds A's entries, and classifies them
+     * as foreign — CORRECTLY, since nothing B can see claims them — so they never
+     * reach `projected.records`. The merge decided per entry; the write then
+     * replaced the whole scope. B left A's bytes alone and erased A's claim in the
+     * same breath. Keying the drop to what the caller examined is what makes the
+     * two agree.
+     *
+     * Deliberately NOT one write per entry: that shape preserves the same claims,
+     * but measured 99 writes per init instead of 6 (p50 61.5 ms each, 69x the
+     * ledger phase) and opened a contention cliff — 17 of 48 scopes failing at
+     * eight concurrent inits against 0 of 48 today. This keeps one write per scope.
+     *
+     * Still serialised against concurrent calls on this instance, and still NOT a
+     * fix for the orphan window above it: `engine.ts` writes the vendor file
+     * before it reaches this method, so a persist that throws — or a crash in
+     * between — leaves bytes no record claims. That is a different defect with a
+     * different fix, and it is open.
+     */
+    async update(scope, records, examined) {
+        await this.#queued(async () => {
+            const current = await this.read();
+            if (current.state === 'unreadable') {
+                throw new BramboError(BRAMBO_ERROR_CODES.projectionLedgerUnavailable, `projection ledger '${this.filePath}' became unreadable; refusing to overwrite it and orphan every claim it holds`);
+            }
+            const surrendered = new Set([...examined, ...records.map((record) => record.entryId)]);
+            const kept = current.records.filter((record) => record.targetId !== scope.targetId ||
+                !sameOwnedPath(record.filePath, scope.filePath) ||
+                !surrendered.has(record.entryId));
+            await this.#persist([...kept, ...records]);
+        });
+    }
+    /**
+     * Replaces ONE entry's record inside one scope, reading the current document
+     * INSIDE the queue.
+     *
+     * The granularity is the point. A caller that read the ledger, decided, and
+     * then handed `update` a whole replacement set for the scope would resurrect
+     * every claim another writer legitimately dropped in between — brambo would
+     * then claim a path it does not own, which on the materialisation path is a
+     * delete authority. Only the named entry moves here; every sibling claim is
+     * whatever the document says at the moment of the write.
+     *
+     * `record === undefined` drops the entry instead of replacing it.
+     */
+    async updateEntry(scope, entryId, record) {
+        await this.#queued(async () => {
+            const current = await this.read();
+            if (current.state === 'unreadable') {
+                throw new BramboError(BRAMBO_ERROR_CODES.projectionLedgerUnavailable, `projection ledger '${this.filePath}' became unreadable; refusing to overwrite it and orphan every claim it holds`);
+            }
+            const kept = current.records.filter((candidate) => candidate.entryId !== entryId ||
+                candidate.targetId !== scope.targetId ||
+                !sameOwnedPath(resolveOwnedPath(candidate.filePath), scope.filePath));
+            await this.#persist(record === undefined ? kept : [...kept, record]);
+        });
+    }
+    /**
+     * Replaces the WHOLE document with whatever `select` returns for the document
+     * as it is INSIDE the queue.
+     *
+     * This is the one write that does not merge, and it exists for exactly one
+     * caller: the user-named `repair` remediation, which is how a ledger holding
+     * records brambo cannot read stops being a state with no exit. Nothing else may
+     * use it — `update` is the merging write every projection performs, and its
+     * refusal to overwrite an unreadable ledger is a load-bearing guarantee that
+     * this method deliberately does not have. `test/guard.test.ts` pins the caller
+     * list, because a second one would silently reintroduce the orphan-every-claim
+     * failure Story 2.8 declared terminal.
+     *
+     * `select` runs INSIDE the queue and is handed the read the write will be
+     * based on. A caller that read the document itself and passed the result would
+     * destroy every claim written in between — with no merge to save it, which is
+     * exactly what makes this method the dangerous one. It may throw to abort the
+     * write, which is how `repair` refuses when the document moved under it.
+     */
+    async rewriteAll(authority, select) {
+        // A CAPABILITY, not a spelling check. The static caller list in
+        // `test/guard.test.ts` catches the honest second caller and was evaded by a
+        // reviewer with `ledger['rewrite' + 'All']([])` — a scan cannot see a name
+        // assembled at runtime. Holding the sentinel can only come from importing
+        // it, which both the symbol scan and the package's import graph do see, so
+        // the obfuscated route now fails at run time instead of silently working.
+        if (authority !== LEDGER_REPAIR_AUTHORITY) {
+            throw new BramboError(BRAMBO_ERROR_CODES.projectionLedgerUnavailable, `projection ledger '${this.filePath}': rewriting the whole document is reserved for the repair remediation`);
+        }
+        await this.#queued(async () => {
+            await this.#persist(select(await this.read()));
+        });
+    }
+    /** The read-modify-write queue, keyed by ledger path and shared by instances. */
+    async #queued(work) {
+        const run = (LEDGER_QUEUES.get(this.#queueKey) ?? Promise.resolve()).then(() => this.#locked(work));
+        // The chain must survive a rejection, or one failed target would deadlock
+        // every later one.
+        const settled = run.catch(() => undefined);
+        LEDGER_QUEUES.set(this.#queueKey, settled);
+        try {
+            await run;
+        }
+        finally {
+            // Drop the entry once this is the tail, so a long-lived process does not
+            // accumulate one resolved promise per ledger path it ever touched.
+            if (LEDGER_QUEUES.get(this.#queueKey) === settled)
+                LEDGER_QUEUES.delete(this.#queueKey);
+        }
+    }
+    /**
+     * The OUTER boundary: THIS METHOD's read-modify-write happens while this
+     * process holds `<ledger>.lock`, so two calls into `update`, `updateEntry` or
+     * `replace` cannot interleave their own read and write. Merging alone never
+     * closed that window — the read is what interleaves, and only mutual exclusion
+     * over the read AND the write can close it.
+     *
+     * WHERE THE BOUNDARY ENDS, and it is not where this comment used to imply. A
+     * caller that reads the document ITSELF, decides, and then hands `update` a
+     * whole replacement set is outside this lock for the part that matters, and
+     * `updateEntry`'s own comment names the consequence: it "would resurrect every
+     * claim another writer legitimately dropped in between — brambo would then
+     * claim a path it does not own, which on the materialisation path is a delete
+     * authority."
+     *
+     * `runProjection` is that caller and its window is still open: `engine.ts`
+     * takes `await store.read()` before the target loop and decides every target
+     * against that one snapshot. Measured while the window was also AUTHORITY,
+     * ten rounds of two concurrent `brambo init` against one home lost 76 of 120
+     * claims with zero bytes on stderr, against a one-process control that lost 0
+     * of 120.
+     *
+     * What closed that is NOT this lock — it never could be, because the decision
+     * happens outside it. `update` now takes the entry ids the caller EXAMINED and
+     * drops only those, so a stale snapshot can no longer speak for entries it
+     * never saw; the same harness reports 0 of 120 after. The window remains, and
+     * is now merely stale rather than destructive: two runs can still reach
+     * different conclusions about the same entry and resolve last-writer-wins.
+     *
+     * `finally { release }` mirrors `RegistryStore.#persist` exactly: the lock is
+     * given back whether the write succeeded or threw, and a release failure is
+     * itself coded rather than swallowed.
+     */
+    async #locked(work) {
+        // The lockfile is created inside this directory; on a fresh machine nothing
+        // has created ~/.brambo yet, and an exclusive create into a missing directory
+        // is an ENOENT the lock would report as an unavailable medium.
+        try {
+            await mkdir(dirname(this.filePath), { recursive: true });
+        }
+        catch (error) {
+            throw new BramboError(BRAMBO_ERROR_CODES.projectionLedgerUnavailable, `projection ledger '${this.filePath}' could not be written: ${detailOf(error)}`, { cause: error });
+        }
+        const lock = await acquireLock(this.#lockPath, {
+            timeoutMs: this.#lockTimeoutMs,
+            onStaleBreak: this.#onStaleLockBreak,
+        }).catch((error) => {
+            throw asLedgerFailure(this.filePath, error);
+        });
+        try {
+            await work();
+        }
+        finally {
+            await lock.release().catch((error) => {
+                throw asLedgerFailure(this.filePath, error);
+            });
+        }
+    }
+    async #persist(records) {
+        try {
+            await atomicWriteText(this.filePath, serialiseLedgerDocument(records));
+        }
+        catch (error) {
+            throw new BramboError(BRAMBO_ERROR_CODES.projectionLedgerUnavailable, `projection ledger '${this.filePath}' could not be written: ${detailOf(error)}`, { cause: error });
+        }
+    }
+    #unreadable(reason) {
+        return {
+            state: 'unreadable',
+            records: [],
+            // Nothing parsed, so nothing can be addressed, let alone salvaged.
+            salvaged: [],
+            warnings: [
+                {
+                    code: BRAMBO_ERROR_CODES.projectionLedgerUnavailable,
+                    detail: `projection ledger '${this.filePath}' ${reason}; treating it as if brambo had written nothing, and leaving the file untouched`,
+                },
+            ],
+        };
+    }
+}

package/dist/materialise.d.ts

@@ -0,0 +1,55 @@
+import type { ProjectionClaim, ProjectionLedgerRecord, ProjectionMaterialiseTarget, ProjectionResult, RegistryEntriesByKind } from '@skanl/brambo-contracts';
+export interface MaterialiseOutcome {
+    readonly result: ProjectionResult;
+    readonly records: readonly ProjectionLedgerRecord[];
+}
+/**
+ * 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 declare function claimMaterialised(target: ProjectionMaterialiseTarget, entries: RegistryEntriesByKind, claimed: readonly ProjectionLedgerRecord[], entryId: string): Promise<ProjectionClaim>;
+/**
+ * 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 declare function materialiseTarget(target: ProjectionMaterialiseTarget, entries: RegistryEntriesByKind, claimed: readonly ProjectionLedgerRecord[], apply: boolean): Promise<MaterialiseOutcome>;