@vibe-agent-toolkit/utils 0.2.0-rc.10 → 0.2.0-rc.12

package/dist/tree-change/plan.d.ts

@@ -0,0 +1,206 @@
+/**
+ * The plan half of the tree-change primitive: every destructive verb describes
+ * what it wants as {@link TreeChange}s, and {@link planTreeChanges} decides, with
+ * no side effect, what will actually happen to each — before anything is written.
+ *
+ * The decisions, in order:
+ *
+ * 1. **What is there** at each destination (`lstat`; a destination the OS refuses
+ *    to examine throws, classified `destination`; "absent" is believed only when
+ *    the parent's listing agrees).
+ * 2. **Keep.** A `remove` with nothing there, or whose `keepIfSameAs` names an
+ *    entry that is `same` **or `unknown`** to it, is kept, with the reason. Only
+ *    the target's own unexaminability throws, never a sibling's. A `remove` that
+ *    holds a kept entry (or cannot be proven not to) is kept too: a kept entry is
+ *    kept whole, never taken away with a directory above it.
+ * 3. **Aliasing and containment, by identity.** A `remove` that is the same entry
+ *    as a `replace` (`plugins/Old` and `plugins/old` on APFS or NTFS, a link and its
+ *    target), or an earlier `remove`, or lies inside any other change's
+ *    destination, is `subsumed`: that change parks it. `unknown` is never a merge
+ *    and never a refusal — the two changes run as two, and a wrong guess fails the
+ *    apply, which rolls back; refusing would refuse every change on a filesystem
+ *    that reports `ino` 0. Any other two changes still active whose destinations
+ *    are one entry or nest are refused ({@link TREE_DESTS_OVERLAP_CODE}): the
+ *    calling verb's defect, never the user's input.
+ * 4. **Ownership** of whatever is there: `must-be-free` refuses anything but an
+ *    empty directory ({@link TREE_DEST_OCCUPIED_CODE}); `vat-made` refuses what its
+ *    `recognise` disowns ({@link TREE_DEST_NOT_OWNED_CODE}); `force` and
+ *    `vat-state` take anything — except that a `replace-file` never takes a directory
+ *    (or a link to one), under any ownership ({@link TREE_DEST_OCCUPIED_CODE}).
+ * 5. **Holding.** A `copy` source, or a `write` fill's declared `reads`, that is the
+ *    destination or inside it ({@link TREE_DEST_HOLDS_SOURCE_CODE}: the replace
+ *    would delete it — never asked of a destination that is a link, which holds
+ *    nothing: only the link is parked), or that holds the destination
+ *    ({@link TREE_SOURCE_HOLDS_DEST_CODE}: a copy into itself), is refused.
+ * 6. **Readable source.** Every `copy` source is proven readable (the one
+ *    special-file and link policy, `proveTreeReadable`, on the fill's declared `side`).
+ *
+ * Utils names no refusal code: these are library codes, and the CLI's refusal map
+ * decides which refusal each is.
+ */
+import { type FsSide } from '../errors/fs-fault.js';
+import type { EntryContainment, EntrySameness } from './identity-compare.js';
+import type { LinkPolicy } from './tree-walk.js';
+/** A destination that must be absent or an empty directory already holds something. */
+export declare const TREE_DEST_OCCUPIED_CODE = "TREE_DEST_OCCUPIED";
+/** A destination VAT may replace only when it made it holds something its recogniser disowns. */
+export declare const TREE_DEST_NOT_OWNED_CODE = "TREE_DEST_NOT_OWNED";
+/**
+ * Two changes of one plan whose destinations are one entry or nest (other than a remove the other
+ * change takes with it): they cannot be one transaction — the outer park would carry the inner
+ * change's staging away. The calling verb built a plan it must not, so it is VAT's defect.
+ */
+export declare const TREE_DESTS_OVERLAP_CODE = "TREE_DESTS_OVERLAP";
+/** A copy's destination lies inside its source: the copy would copy into itself. */
+export declare const TREE_SOURCE_HOLDS_DEST_CODE = "TREE_SOURCE_HOLDS_DEST";
+/** A copy's source is its destination or lies inside it: the replace would delete what it copies. */
+export declare const TREE_DEST_HOLDS_SOURCE_CODE = "TREE_DEST_HOLDS_SOURCE";
+/** What a recogniser says about a destination that is there. */
+export type OwnershipVerdict = {
+    readonly owned: true;
+} | {
+    readonly owned: false;
+    readonly reason: string;
+};
+/** Who may lose whatever is at a destination. */
+export type Ownership = 
+/** Only an absent destination or an empty directory; anything else is refused. */
+{
+    readonly kind: 'must-be-free';
+}
+/** The user said `--force`: whatever is there may go. */
+ | {
+    readonly kind: 'force';
+}
+/** Something VAT made before, as `recognise` judges it; anything else is refused. */
+ | {
+    readonly kind: 'vat-made';
+    readonly recognise: (dest: string) => OwnershipVerdict;
+}
+/** State VAT owns outright (a cache, a marketplace under `~/.claude`, `dist/`). */
+ | {
+    readonly kind: 'vat-state';
+};
+/** How a replacement tree is made, in a staged place beside its destination. */
+export type TreeFill = 
+/**
+ * `copy` copies `source` by the readable-tree walk. `side` is the side of the verb `source` is on — an input
+ * (`source`), VAT's staging (`environment`), or a copy already made into user state (`destination`) — and
+ * every read of it, by the proof and by the copy, is classified on it. Required: only the caller knows.
+ */
+{
+    readonly from: 'copy';
+    readonly source: string;
+    readonly side: FsSide;
+    readonly links: LinkPolicy;
+    readonly filter?: (relative: string) => boolean;
+}
+/** `write` fills the empty staged directory; `reads` are the inputs it reads, held to the same holding check as a copy source. */
+ | {
+    readonly from: 'write';
+    readonly write: (staged: string) => Promise<void>;
+    readonly reads?: readonly string[];
+}
+/** The staged entry is a link to `target` (a `--dev` lane). */
+ | {
+    readonly from: 'link';
+    readonly target: string;
+};
+/**
+ * A `replace-file`'s bytes: given, or made when the file is staged. Staging runs in the plan's order, so a
+ * function is called only after every earlier change of the plan has staged — a file made FROM a tree the
+ * same plan stages (an archive of a staged bundle) is one change of that plan, not a second transaction.
+ */
+export type FileContents = string | Uint8Array | (() => string | Uint8Array);
+/** One change a verb wants. `label` names it in the dry run and in every message. */
+export type TreeChange = {
+    readonly op: 'replace';
+    readonly dest: string;
+    readonly ownership: Ownership;
+    readonly fill: TreeFill;
+    readonly label: string;
+} | {
+    readonly op: 'replace-file';
+    readonly dest: string;
+    readonly ownership: Ownership;
+    readonly contents: FileContents;
+    readonly label: string;
+} | {
+    readonly op: 'remove';
+    readonly dest: string;
+    readonly ownership: Ownership;
+    readonly keepIfSameAs?: () => readonly string[];
+    readonly label: string;
+};
+/** What is at a destination. */
+export type EntryKind = 'absent' | 'directory' | 'file' | 'link' | 'special';
+/** What will happen to a destination. */
+export type PlannedAction = 'create' | 'replace' | 'remove' | 'keep' | 'subsumed';
+/** One change, decided. */
+export interface PlannedChange {
+    readonly change: TreeChange;
+    readonly existing: EntryKind;
+    readonly action: PlannedAction;
+    /** Why it is kept or subsumed. */
+    readonly reason?: string;
+    /**
+     * Set on a remove kept because the OS refused to examine an entry it may be (its `keepIfSameAs`):
+     * that entry. A caller that drops its own record of the kept entry names it, so the user can tell
+     * what stayed and why (ruling R7 d-I-1: never delete what may BE a kept sibling).
+     */
+    readonly unexaminedSibling?: string;
+}
+/** Every change, decided; `describe()` is the dry run, one line per change. */
+export interface TreePlan {
+    readonly changes: readonly PlannedChange[];
+    describe(): readonly string[];
+}
+/** The filesystem facts the planner decides by: live in {@link planTreeChanges}, faked in its unit test. */
+export interface PlanFacts {
+    /** What is at `dest`; throws when the OS refuses to examine it. */
+    readonly existing: (dest: string) => EntryKind;
+    readonly isEmptyDirectory: (dest: string) => boolean;
+    /** Whether the link at `dest` leads to a directory (false for a dangling link, or one to a file). */
+    readonly linksToDirectory: (dest: string) => boolean;
+    readonly sameEntry: (a: string, b: string) => EntrySameness;
+    readonly isInside: (child: string, ancestor: string) => EntryContainment;
+    /** Throws when the OS refuses to examine `dest`'s identity: a remove's own unexaminability is never a keep. */
+    readonly requireExaminable: (dest: string) => void;
+    /** Whether the OS refuses to examine `entry`'s identity (an `unknown` that is a refusal, not a fold that cannot tell). */
+    readonly refusesToExamine: (entry: string) => boolean;
+}
+/** Whether a planned change touches its destination (`keep` and `subsumed` do not). */
+export declare const isActive: ({ action }: PlannedChange) => boolean;
+/**
+ * The pure planner: every decision of {@link planTreeChanges} but the source
+ * proof, made from `facts`.
+ *
+ * @throws VatError coded `TREE_DESTS_OVERLAP` (a defect in the caller's plan), `TREE_DEST_OCCUPIED`,
+ *   `TREE_DEST_NOT_OWNED`, `TREE_DEST_HOLDS_SOURCE` or `TREE_SOURCE_HOLDS_DEST`; whatever `facts` throws
+ */
+export declare function planFromFacts(changes: readonly TreeChange[], facts: PlanFacts): TreePlan;
+/**
+ * What is at `dest` NOW, for the apply to hold against what the plan decided
+ * (`changedSincePlan`). The emptiness of a directory is read only where the plan took it as free.
+ *
+ * @throws FsFaultError side `destination` when the OS refuses to examine or list it
+ */
+export declare function destinationNow(dest: string, planned: PlannedChange): {
+    kind: EntryKind;
+    emptyDirectory: boolean;
+};
+/**
+ * Decide every change against the filesystem as it is, with no side effect. Each
+ * destination is taken in its canonical spelling (`safePath.resolve`: absolute,
+ * `.`/`..` resolved, forward slashes); `describe()` prints that spelling.
+ * Hand the result to `applyTreePlan`; print `describe()` for a dry run — the two
+ * cannot disagree, because the apply does exactly what the plan says.
+ *
+ * @param changes - What the verb wants, in the order it wants it
+ * @throws VatError coded `TREE_DEST_OCCUPIED`, `TREE_DEST_NOT_OWNED`,
+ *   `TREE_DEST_HOLDS_SOURCE` or `TREE_SOURCE_HOLDS_DEST`; `FsFaultError` side
+ *   `destination` for a destination the OS refuses to examine, on the fill's
+ *   declared side for a copy source it refuses to read
+ */
+export declare function planTreeChanges(changes: readonly TreeChange[]): Promise<TreePlan>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/tree-change/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/tree-change/plan.ts"],"names":[],"mappings":"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"}

package/dist/tree-change/plan.js

@@ -0,0 +1,320 @@
+/**
+ * The plan half of the tree-change primitive: every destructive verb describes
+ * what it wants as {@link TreeChange}s, and {@link planTreeChanges} decides, with
+ * no side effect, what will actually happen to each — before anything is written.
+ *
+ * The decisions, in order:
+ *
+ * 1. **What is there** at each destination (`lstat`; a destination the OS refuses
+ *    to examine throws, classified `destination`; "absent" is believed only when
+ *    the parent's listing agrees).
+ * 2. **Keep.** A `remove` with nothing there, or whose `keepIfSameAs` names an
+ *    entry that is `same` **or `unknown`** to it, is kept, with the reason. Only
+ *    the target's own unexaminability throws, never a sibling's. A `remove` that
+ *    holds a kept entry (or cannot be proven not to) is kept too: a kept entry is
+ *    kept whole, never taken away with a directory above it.
+ * 3. **Aliasing and containment, by identity.** A `remove` that is the same entry
+ *    as a `replace` (`plugins/Old` and `plugins/old` on APFS or NTFS, a link and its
+ *    target), or an earlier `remove`, or lies inside any other change's
+ *    destination, is `subsumed`: that change parks it. `unknown` is never a merge
+ *    and never a refusal — the two changes run as two, and a wrong guess fails the
+ *    apply, which rolls back; refusing would refuse every change on a filesystem
+ *    that reports `ino` 0. Any other two changes still active whose destinations
+ *    are one entry or nest are refused ({@link TREE_DESTS_OVERLAP_CODE}): the
+ *    calling verb's defect, never the user's input.
+ * 4. **Ownership** of whatever is there: `must-be-free` refuses anything but an
+ *    empty directory ({@link TREE_DEST_OCCUPIED_CODE}); `vat-made` refuses what its
+ *    `recognise` disowns ({@link TREE_DEST_NOT_OWNED_CODE}); `force` and
+ *    `vat-state` take anything — except that a `replace-file` never takes a directory
+ *    (or a link to one), under any ownership ({@link TREE_DEST_OCCUPIED_CODE}).
+ * 5. **Holding.** A `copy` source, or a `write` fill's declared `reads`, that is the
+ *    destination or inside it ({@link TREE_DEST_HOLDS_SOURCE_CODE}: the replace
+ *    would delete it — never asked of a destination that is a link, which holds
+ *    nothing: only the link is parked), or that holds the destination
+ *    ({@link TREE_SOURCE_HOLDS_DEST_CODE}: a copy into itself), is refused.
+ * 6. **Readable source.** Every `copy` source is proven readable (the one
+ *    special-file and link policy, `proveTreeReadable`, on the fill's declared `side`).
+ *
+ * Utils names no refusal code: these are library codes, and the CLI's refusal map
+ * decides which refusal each is.
+ */
+import { lstatSync, readdirSync } from 'node:fs';
+import { requireConfirmedAbsent } from '../errors/confirmed-absent.js';
+import { isPathAbsentError } from '../errors/errno-table.js';
+import { classifyFsFault, everywhere, withFsFaultSync } from '../errors/fs-fault.js';
+import { VatError } from '../errors/vat-error.js';
+import { forEachInOrder } from '../in-order.js';
+import { followedStatSync } from '../link-following.js';
+import { relativeEscapesRoot, safePath } from '../path-core.js';
+import { identityOracle } from './identity.js';
+import { proveTreeReadable } from './readable-tree.js';
+/** A destination that must be absent or an empty directory already holds something. */
+export const TREE_DEST_OCCUPIED_CODE = 'TREE_DEST_OCCUPIED';
+/** A destination VAT may replace only when it made it holds something its recogniser disowns. */
+export const TREE_DEST_NOT_OWNED_CODE = 'TREE_DEST_NOT_OWNED';
+/**
+ * Two changes of one plan whose destinations are one entry or nest (other than a remove the other
+ * change takes with it): they cannot be one transaction — the outer park would carry the inner
+ * change's staging away. The calling verb built a plan it must not, so it is VAT's defect.
+ */
+export const TREE_DESTS_OVERLAP_CODE = 'TREE_DESTS_OVERLAP';
+/** A copy's destination lies inside its source: the copy would copy into itself. */
+export const TREE_SOURCE_HOLDS_DEST_CODE = 'TREE_SOURCE_HOLDS_DEST';
+/** A copy's source is its destination or lies inside it: the replace would delete what it copies. */
+export const TREE_DEST_HOLDS_SOURCE_CODE = 'TREE_DEST_HOLDS_SOURCE';
+function refusal(code, message) {
+    return new VatError(code, message);
+}
+/** Why a remove is kept — and the sibling the OS refused to examine, when that is why — or `undefined` when it goes ahead. */
+function keepReason(change, existing, facts) {
+    if (change.op !== 'remove')
+        return undefined;
+    if (existing === 'absent')
+        return { reason: 'nothing there' };
+    const others = change.keepIfSameAs?.() ?? [];
+    // The target's own refusal throws; only an OTHER entry's refusal is `unknown`, a keep.
+    if (others.length > 0)
+        facts.requireExaminable(change.dest);
+    for (const other of others) {
+        const verdict = facts.sameEntry(change.dest, other);
+        if (verdict === 'same')
+            return { reason: `${other} is the same entry` };
+        if (verdict === 'unknown') {
+            const reason = `could not tell whether ${other} is the same entry`;
+            return facts.refusesToExamine(other) ? { reason, unexaminedSibling: other } : { reason };
+        }
+    }
+    return undefined;
+}
+/** The kept entry `planned` (a remove) holds, or may hold: removing it would take that entry with it. */
+function heldKeep(planned, all, facts) {
+    if (planned.action !== 'remove')
+        return undefined;
+    return all.find((other) => other !== planned && other.action === 'keep' && other.existing !== 'absent' && facts.isInside(other.change.dest, planned.change.dest) !== 'outside');
+}
+/**
+ * Keep every remove that holds — or cannot be proven not to hold — a kept entry: a
+ * kept entry is kept whole, never taken away with a directory above it. Repeated until
+ * nothing changes, so a remove holding one that was just kept is kept as well.
+ */
+function keepingHolders(planned, facts) {
+    const next = planned.map((each) => {
+        const held = heldKeep(each, planned, facts);
+        return held === undefined ? each : { ...each, action: 'keep', reason: `holds ${held.change.dest}, which is kept` };
+    });
+    return next.some((each, index) => each !== planned[index]) ? keepingHolders(next, facts) : planned;
+}
+function initialAction(change, existing) {
+    if (change.op === 'remove')
+        return 'remove';
+    return existing === 'absent' ? 'create' : 'replace';
+}
+/** Whether `other` takes `change`'s destination with it: the same entry as a replace or an earlier remove, or an ancestor of it. */
+function subsumes(change, index, other, otherIndex, facts) {
+    if (otherIndex === index || other.action === 'keep' || other.existing === 'absent')
+        return false;
+    const sameAllowed = other.change.op !== 'remove' || otherIndex < index;
+    if (sameAllowed && facts.sameEntry(change.change.dest, other.change.dest) === 'same')
+        return true;
+    return facts.isInside(change.change.dest, other.change.dest) === 'inside';
+}
+function withSubsumption(planned, index, all, facts) {
+    if (planned.action !== 'remove')
+        return planned;
+    const by = all.find((other, otherIndex) => subsumes(planned, index, other, otherIndex, facts));
+    return by === undefined ? planned : { ...planned, action: 'subsumed', reason: `parked by ${by.change.op} ${by.change.label}` };
+}
+/** Whether a planned change touches its destination (`keep` and `subsumed` do not). */
+export const isActive = ({ action }) => action === 'create' || action === 'replace' || action === 'remove';
+/**
+ * Whether `inner`'s destination is `outer`'s or lies under it. Judged by identity where `outer`
+ * exists; an absent destination has no identity, so there it is judged by the spelling.
+ */
+function holds(outer, inner, facts) {
+    if (outer.existing === 'absent')
+        return !relativeEscapesRoot(safePath.relative(outer.change.dest, inner.change.dest));
+    return facts.sameEntry(inner.change.dest, outer.change.dest) === 'same' || facts.isInside(inner.change.dest, outer.change.dest) === 'inside';
+}
+/** Refuse two active changes over one tree: the plan is the calling verb's defect. `unknown` is never proof. */
+function checkOverlap(planned, facts) {
+    const active = planned.filter((each) => isActive(each));
+    for (const [index, first] of active.entries()) {
+        const second = active.slice(index + 1).find((other) => holds(first, other, facts) || holds(other, first, facts));
+        if (second !== undefined) {
+            throw refusal(TREE_DESTS_OVERLAP_CODE, `${first.change.label} (${first.change.dest}) and ${second.change.label} (${second.change.dest}) change one tree; a plan may not overlap its own destinations`);
+        }
+    }
+}
+/**
+ * Refuse a FILE change whose destination is a directory, or a link to one — under every ownership,
+ * `force` included: `--force` means "overwrite the file", and a file landing on a directory's name
+ * would park the whole tree and delete it.
+ */
+function checkFileOverDirectory({ change, existing }, facts) {
+    if (change.op !== 'replace-file')
+        return;
+    const { dest, label } = change;
+    if (existing === 'directory') {
+        throw refusal(TREE_DEST_OCCUPIED_CODE, `${label}: ${dest} is a directory; a file is never written over a directory`);
+    }
+    if (existing === 'link' && facts.linksToDirectory(dest)) {
+        throw refusal(TREE_DEST_OCCUPIED_CODE, `${label}: ${dest} is a link to a directory; a file is never written over a directory`);
+    }
+}
+/** Refuse a destination its ownership does not let this change take. */
+function checkOwnership(planned, facts) {
+    const { change, existing, action } = planned;
+    if (existing === 'absent' || action === 'keep' || action === 'subsumed')
+        return;
+    checkFileOverDirectory(planned, facts);
+    const { ownership, dest, label } = change;
+    // An empty directory is free for a tree that lands in its place, never for a FILE: a file
+    // replacing a directory the user made (a folder they named as an output) is a surprise, not a fill.
+    const freeDirectory = change.op !== 'replace-file' && existing === 'directory' && facts.isEmptyDirectory(dest);
+    // The refusal says what this change would have done to the destination.
+    const verb = change.op === 'remove' ? 'remove' : 'replace';
+    if (ownership.kind === 'must-be-free' && !freeDirectory) {
+        throw refusal(TREE_DEST_OCCUPIED_CODE, `${label}: ${dest} already holds something (a ${existing}); refusing to ${verb} it`);
+    }
+    if (ownership.kind === 'vat-made') {
+        const verdict = ownership.recognise(dest);
+        if (!verdict.owned)
+            throw refusal(TREE_DEST_NOT_OWNED_CODE, `${label}: refusing to ${verb} ${dest}: ${verdict.reason}`);
+    }
+}
+/** The inputs a replace reads, which its destination must neither be, hold, nor lie inside. */
+function readsOf(change) {
+    if (change.op !== 'replace')
+        return [];
+    if (change.fill.from === 'copy')
+        return [change.fill.source];
+    return change.fill.from === 'write' ? change.fill.reads ?? [] : [];
+}
+function checkHolding(planned, facts) {
+    if (planned.action !== 'create' && planned.action !== 'replace')
+        return;
+    const { dest, label } = planned.change;
+    // A destination that is a LINK holds nothing: the replace parks the link itself, never what it points
+    // at — so a source the link leads to (a `--dev` link to the build being installed) is not lost with it.
+    const destHoldsEntries = planned.existing !== 'link';
+    for (const source of readsOf(planned.change)) {
+        if (destHoldsEntries && (facts.sameEntry(source, dest) === 'same' || facts.isInside(source, dest) === 'inside')) {
+            throw refusal(TREE_DEST_HOLDS_SOURCE_CODE, `${label}: ${source} is ${dest} or lies inside it, so replacing ${dest} would delete it`);
+        }
+        if (facts.isInside(dest, source) === 'inside') {
+            throw refusal(TREE_SOURCE_HOLDS_DEST_CODE, `${label}: ${dest} lies inside ${source}, which it is made from`);
+        }
+    }
+}
+function describeChange({ change, action, reason }) {
+    const line = `${action} ${change.label} ${change.dest}`;
+    return reason === undefined ? line : `${line} (${reason})`;
+}
+/**
+ * The pure planner: every decision of {@link planTreeChanges} but the source
+ * proof, made from `facts`.
+ *
+ * @throws VatError coded `TREE_DESTS_OVERLAP` (a defect in the caller's plan), `TREE_DEST_OCCUPIED`,
+ *   `TREE_DEST_NOT_OWNED`, `TREE_DEST_HOLDS_SOURCE` or `TREE_SOURCE_HOLDS_DEST`; whatever `facts` throws
+ */
+export function planFromFacts(changes, facts) {
+    const drafted = changes.map((change) => {
+        const existing = facts.existing(change.dest);
+        const kept = keepReason(change, existing, facts);
+        return kept === undefined ? { change, existing, action: initialAction(change, existing) } : { change, existing, action: 'keep', ...kept };
+    });
+    const kept = keepingHolders(drafted, facts);
+    const planned = kept.map((draft, index) => withSubsumption(draft, index, kept, facts));
+    checkOverlap(planned, facts);
+    for (const each of planned)
+        checkOwnership(each, facts);
+    for (const each of planned)
+        checkHolding(each, facts);
+    return { changes: planned, describe: () => planned.map((each) => describeChange(each)) };
+}
+const EXAMINE_DEST = { side: 'destination', action: 'examine the destination' };
+function kindOf(dest) {
+    let stats;
+    try {
+        stats = lstatSync(dest);
+    }
+    catch (error) {
+        if (!isPathAbsentError(error))
+            throw classifyFsFault(error, { ...EXAMINE_DEST, path: dest });
+        // Absent only when the parent's listing agrees: a refused probe of an entry that is there is a fault.
+        requireConfirmedAbsent(dest, error, { action: EXAMINE_DEST.action, path: dest }, { follows: false, sideOf: everywhere(EXAMINE_DEST.side) });
+        return 'absent';
+    }
+    if (stats.isSymbolicLink())
+        return 'link';
+    if (stats.isDirectory())
+        return 'directory';
+    return stats.isFile() ? 'file' : 'special';
+}
+/** Whether the link at `dest` leads to a directory: a dangling link leads nowhere; a target the OS refuses to examine is a fault. */
+function linksToDirectory(dest) {
+    try {
+        // `dest` is the destination the verb names: the operator's own path, its own link the edge.
+        return followedStatSync(dest, dest)?.isDirectory() ?? false;
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return false;
+        throw classifyFsFault(error, { ...EXAMINE_DEST, path: dest });
+    }
+}
+/**
+ * What is at `dest` NOW, for the apply to hold against what the plan decided
+ * (`changedSincePlan`). The emptiness of a directory is read only where the plan took it as free.
+ *
+ * @throws FsFaultError side `destination` when the OS refuses to examine or list it
+ */
+export function destinationNow(dest, planned) {
+    const kind = kindOf(dest);
+    const askEmpty = kind === 'directory' && planned.existing === 'directory' && planned.change.ownership.kind === 'must-be-free';
+    return { kind, emptyDirectory: askEmpty && withFsFaultSync({ side: 'destination', action: 'list the destination', path: dest }, () => readdirSync(dest).length === 0) };
+}
+/** The live facts of one plan: every identity question asks each entry once, so no two decisions see the filesystem differently. */
+function liveFacts() {
+    const oracle = identityOracle();
+    return {
+        existing: kindOf,
+        isEmptyDirectory: (dest) => withFsFaultSync({ side: 'destination', action: 'list the destination', path: dest }, () => readdirSync(dest).length === 0),
+        linksToDirectory,
+        sameEntry: oracle.sameEntry,
+        isInside: oracle.isInside,
+        requireExaminable: (dest) => {
+            oracle.identities(dest);
+        },
+        refusesToExamine: (entry) => oracle.refuses(entry),
+    };
+}
+/** Prove a copy source readable, as the copy will read it. */
+function proveSource({ change, action }) {
+    if (change.op !== 'replace' || change.fill.from !== 'copy' || (action !== 'create' && action !== 'replace'))
+        return Promise.resolve();
+    const { source, links, side, filter } = change.fill;
+    return proveTreeReadable(source, { links, side, ...(filter === undefined ? {} : { filter }) });
+}
+/**
+ * Decide every change against the filesystem as it is, with no side effect. Each
+ * destination is taken in its canonical spelling (`safePath.resolve`: absolute,
+ * `.`/`..` resolved, forward slashes); `describe()` prints that spelling.
+ * Hand the result to `applyTreePlan`; print `describe()` for a dry run — the two
+ * cannot disagree, because the apply does exactly what the plan says.
+ *
+ * @param changes - What the verb wants, in the order it wants it
+ * @throws VatError coded `TREE_DEST_OCCUPIED`, `TREE_DEST_NOT_OWNED`,
+ *   `TREE_DEST_HOLDS_SOURCE` or `TREE_SOURCE_HOLDS_DEST`; `FsFaultError` side
+ *   `destination` for a destination the OS refuses to examine, on the fill's
+ *   declared side for a copy source it refuses to read
+ */
+export async function planTreeChanges(changes) {
+    // One canonical spelling of every destination (absolute, normalized, forward slashes), which the
+    // plan, the dry run and the apply — down to the parents a create makes and removes — all use.
+    const canonical = changes.map((change) => ({ ...change, dest: safePath.resolve(change.dest) }));
+    const plan = planFromFacts(canonical, liveFacts());
+    await forEachInOrder(plan.changes, proveSource);
+    return plan;
+}
+//# sourceMappingURL=plan.js.map

package/dist/tree-change/plan.js.map

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

package/dist/tree-change/readable-tree.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The readable-tree proof: before a verb writes anything for a tree it is about to
+ * read whole, it proves every entry readable, so an unreadable input is refused as
+ * the input it is rather than surfacing half-way through as an output failure.
+ */
+import type { FsSide } from '../errors/fs-fault.js';
+import { type TreeWalkOptions } from './tree-walk.js';
+/** What {@link proveTreeReadable} is told: the walk's link policy and filter, and the side its faults are on. */
+export interface ProveTreeReadableOptions extends TreeWalkOptions {
+    /**
+     * The side of the verb the tree is on: an input (`source`), VAT's staging
+     * (`environment`), or a copy already made into user state (`destination`).
+     */
+    readonly side: FsSide;
+}
+/**
+ * Prove the directory `root` readable: every directory listed, every regular file
+ * opened without blocking and judged by `fstat` on that handle, each entry held to
+ * the one special-file and link policy `copyTree` copies by (see `tree-walk.ts`).
+ * A root that is not a directory is refused by its listing (`ENOTDIR`), as
+ * `copyTree` refuses it. Each file is opened, never `access`ed: on Windows `access`
+ * does not consult ACLs.
+ *
+ * @param root - The directory the caller is about to read
+ * @param options - `links` and `filter` as the read will use them, and the `side` the tree is on
+ * @throws FsFaultError on `options.side` (origin `content`) naming the first entry
+ *   the OS refused, in listing order — a named pipe, socket or device as class
+ *   `wrong-type`; `CopyLinkEscapesSourceError` / `DirectoryWalkRevisitedError` for
+ *   a link out of, or back into, a `follow-contained` tree
+ */
+export declare function proveTreeReadable(root: string, options: ProveTreeReadableOptions): Promise<void>;
+/**
+ * Read a regular file whole, through a handle opened without blocking and judged
+ * by `fstat` on that handle: a named pipe, socket or device is refused before a
+ * byte is read, never waited on.
+ *
+ * @param path - The file to read
+ * @returns Its bytes
+ * @throws an `EFTYPE` errno for a special file, `EISDIR` for a directory, and
+ *   whatever `open` / `read` throw otherwise — raw, for the caller to classify on
+ *   the side it knows the file is on
+ */
+export declare function readRegularFile(path: string): Promise<Buffer>;
+//# sourceMappingURL=readable-tree.d.ts.map

package/dist/tree-change/readable-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readable-tree.d.ts","sourceRoot":"","sources":["../../src/tree-change/readable-tree.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,EAAoB,KAAK,eAAe,EAAY,MAAM,gBAAgB,CAAC;AAElF,iHAAiH;AACjH,MAAM,WAAW,wBAAyB,SAAQ,eAAe;IAC/D;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtG;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnE"}