@animalabs/agent-framework 0.28.0 → 0.29.0

package/dist/src/modules/workspace/reconcile.js

@@ -39,9 +39,9 @@
  */
 import { candidateOf, sameCandidate, sameRootIdentity, } from './disk-agreement.js';
 import { storedBytes } from './sync.js';
-import { IGNORED, NOT_A_DIRECTORY, OTHER_MOUNT, ROOT_REPLACED, fingerprintVouches, ignoreBeneath, inOtherMount, locateRoot, looksBinary, observePath, passedOverAt, passedOverBetween, provenAbsent, readHead, readPath, sniffImageMime, walkScope, withinIncludes, } from './observe.js';
-import { EffectFailed, chainOf, chmodContained, narrowedTo, syncDirectories, unlinkContained, writeContained } from './effects.js';
-import { errnoWords } from './answers.js';
+import { BENEATH_SYMLINK, CHANGED, CHANGED_WALK, DIRECTORY, EDITOR_FILE_REASON, FILE_CHANGED, IGNORED, LEAVES_MOUNT, LINK_NOT_WALKED, LINK_TO_DIRECTORY, NOT_A_DIRECTORY, NOT_FOLLOWED, NOT_REGULAR, OUTSIDE_PARENT, RESOLVES_OUTSIDE, ROOT_UNAVAILABLE, OTHER_MOUNT, ROOT_REPLACED, fingerprintVouches, ignoreBeneath, inOtherMount, locateRoot, looksBinary, observePath, passedOverAt, passedOverBetween, provenAbsent, readHead, readPath, sniffImageMime, walkScope, withinIncludes, } from './observe.js';
+import { EffectFailed, callFailed, chainOf, chmodContained, narrowedTo, syncDirectories, unlinkContained, writeContained } from './effects.js';
+import { OUTSIDE_STEP, RESOLVED_OUTSIDE_STEP, UNFOLLOWED_STEP, errnoClause, errnoWords } from './answers.js';
 const ABSENT = { kind: 'absent' };
 export const WALK_CAP = 5000;
 function diskCandidate(d) {
@@ -198,21 +198,22 @@ function settleAdoption(p, s) {
 /**
  * What's in the way, and the way out, when disk's shape keeps a push from a
  * path: no push writes a file over a directory or unlinks one, unlinks
- * anything but a regular file or a followed symlink to one, or writes below
- * a file or a symlink the walk won't take (`writeContained`,
- * `unlinkContained`), forced or not. Null for any other reason, which is
- * passed on as it is.
+ * anything but a regular file or a followed symlink to one, writes below a
+ * file or a symlink the walk won't take, or writes or unlinks through a
+ * symlink the mount doesn't follow or one that leads out of the mount
+ * (`writeContained`, `unlinkContained`), forced or not. Null for any other
+ * reason.
  */
 function inTheWay(reason, deletion) {
     // Observation's words for what a deletion never unlinks, which the unlink
     // refuses in the same words.
-    if (deletion && (reason === 'not a regular file' || reason === 'a symlink to a directory, not walked')) {
-        const what = reason === 'not a regular file'
+    if (deletion && (reason === NOT_REGULAR || reason === LINK_TO_DIRECTORY)) {
+        const what = reason === NOT_REGULAR
             ? 'a pipe, socket or device at this path, or a symlink to one'
             : 'a symlink to a directory at this path';
         return `disk has ${what}, and no push unlinks it, forced or not — ask whoever runs this host if it should go`;
     }
-    if (reason === 'a directory') {
+    if (reason === DIRECTORY) {
         return deletion
             ? 'disk has a directory at this path, and no push unlinks one, forced or not — if it should go, move or remove it on disk'
             : 'disk has a directory at this path, and no push writes a file over one, forced or not — ' +
@@ -224,8 +225,90 @@ function inTheWay(reason, deletion) {
         return 'disk has a file or a symlink where this path needs a directory, and no push writes below one, forced or not — ' +
             'move or remove it on disk and materialize again, or write the file under another path';
     }
+    const link = reason === NOT_FOLLOWED ? 'disk has a symlink at this path, which this mount does not follow'
+        : reason === LEAVES_MOUNT ? 'this path leads out of the mount through a symlink on it'
+            : null;
+    if (link !== null) {
+        return deletion
+            ? `${link}, and no push unlinks ${reason === NOT_FOLLOWED ? 'one' : 'through one'}, forced or not — ask whoever runs this host if it should go`
+            : `${link}, and no push writes through one, forced or not — write the file under another path, ` +
+                `or whoever runs this host can remove the link, and ${THEN.write}`;
+    }
+    if (deletion && reason === BENEATH_SYMLINK) {
+        return 'a symlink on this path does not lead to a directory inside the mount, so nothing beneath it is in this mount, and no push unlinks beneath one, '
+            + `forced or not — whoever runs this host can remove the link or make it lead to a directory inside the mount, and ${THEN.unlink}`;
+    }
+    if (reason === OUTSIDE_PARENT) {
+        return `a directory on this path leads out of the mount, and no push ${deletion ? 'unlinks' : 'writes'} beneath one, forced or not — ` +
+            (deletion ? 'ask whoever runs this host if what is there should go' : 'write the file under another path');
+    }
+    if (reason === NOT_REGULAR || reason === LINK_TO_DIRECTORY) {
+        const what = reason === NOT_REGULAR ? 'a pipe, socket or device at this path, or a symlink to one' : 'a symlink to a directory at this path';
+        return `disk has ${what}, and no push writes a file over it, forced or not — write the file under another path, ` +
+            `or whoever runs this host can remove it, and ${THEN.write}`;
+    }
     return null;
 }
+const AGAIN = {
+    write: 'materializing again',
+    unlink: 'materializing again with applyDeletions',
+    sync: 'syncing this path again',
+    list: 'listing it',
+    read: 'calling again',
+};
+const THEN = {
+    write: 'materializing again then gets past it',
+    unlink: 'materializing again with applyDeletions then gets past it',
+    sync: 'a sync of this path then takes it in',
+    list: 'the workspace then reaches it',
+    read: 'a read then reaches it',
+};
+const CHANGED_WHILE = new Set([CHANGED, CHANGED_WALK, FILE_CHANGED]);
+const WALKED_PAST = new Set([IGNORED, EDITOR_FILE_REASON, LINK_NOT_WALKED]);
+export function explained(reason, cause, meets) {
+    if (meets === 'write' || meets === 'unlink') {
+        const shaped = inTheWay(reason, meets === 'unlink');
+        if (shaped !== null)
+            return shaped;
+    }
+    return withWayOn(reason, cause, meets);
+}
+function withWayOn(reason, cause, meets) {
+    const on = wayOn(reason, cause, meets);
+    return on === null ? reason : `${reason} — ${on}`;
+}
+export function wayOn(reason, cause, meets) {
+    const lasting = `${AGAIN[meets]} won't change that; `;
+    if (reason === ROOT_UNAVAILABLE) {
+        if (cause.errno === 'ENOENT' || cause.errno === 'ENOTDIR')
+            return `${lasting}whoever runs this host can put the mount's directory back at its path, and ${THEN[meets]}`;
+        if (cause.errno === undefined)
+            return `${AGAIN[meets]} checks it afresh; if it's still unavailable, whoever runs this host can check the mount's directory and its path`;
+    }
+    if (cause.errno !== undefined)
+        return errnoClause(cause.errno, AGAIN[meets], THEN[meets]);
+    if (cause.again === true || CHANGED_WHILE.has(reason))
+        return `${AGAIN[meets]} checks it afresh`;
+    switch (reason) {
+        case NOT_FOLLOWED:
+            return lasting + UNFOLLOWED_STEP;
+        case LEAVES_MOUNT:
+            return lasting + OUTSIDE_STEP;
+        case BENEATH_SYMLINK:
+            return `${lasting}nothing beneath it is in this mount, and whoever runs this host can make it lead to a directory inside the mount, or, where it leads to a directory outside, mount that directory`;
+        case OUTSIDE_PARENT:
+        case RESOLVES_OUTSIDE:
+            return lasting + RESOLVED_OUTSIDE_STEP;
+        case NOT_REGULAR:
+            return `${lasting}whoever runs this host can put a regular file there, and ${THEN[meets]}`;
+        case DIRECTORY:
+            return `${lasting}ls of this path lists what's in it`;
+        case LINK_TO_DIRECTORY:
+            return `${lasting}ls of the directory it leads to lists what's in it`;
+        default:
+            return meets === 'sync' && WALKED_PAST.has(reason) ? 'a sync of this path checks it' : null;
+    }
+}
 /**
  * The forced way out the refusal of a disk copy that couldn't be verified
  * names, if any. A forced push skips the verification, so it gets past the
@@ -243,6 +326,12 @@ function forcedWay(note, deletion, forced) {
         return `, or, if disk lets the workspace ${deletion ? 'unlink' : 'write'} the file, ${forced}`;
     return '';
 }
+const UNSETTLED = "whether disk holds the change isn't known until it's checked: a materialize of this path checks it and says how it ended";
+function unverifiedCopy(v, meets, forced) {
+    const note = v.note ?? 'not observed';
+    const on = wayOn(note, v.noteCause ?? {}, meets);
+    return `cannot verify disk copy (${note})${on !== null ? ` — ${on}` : ''}${forcedWay(v.note, meets === 'unlink', forced)}`;
+}
 /**
  * The synchronous precondition of every workspace mutation: evidence owed a
  * barrier is made durable first, and an adoption left pending on the
@@ -362,6 +451,9 @@ function adoptDisk(d, s) {
         return { state: 'synced', adopt: 'ingest', op: s ? 'modified' : 'created', p: agreedFromDisk(d), intent: {} };
     return { state: 'disk-only', ...(s ? { adopt: 'drop', op: 'deleted' } : {}), p: 'forget', intent: {} };
 }
+function causeOf({ errno, ownStep }) {
+    return { ...(errno !== undefined ? { errno } : {}), ...(ownStep ? { ownStep } : {}) };
+}
 /** The rule (see module doc). Pure. */
 function decide(d, s, pIn, bi, branchId, adopt) {
     // A branch intent that can't be read may have held a tombstone or a
@@ -371,9 +463,9 @@ function decide(d, s, pIn, bi, branchId, adopt) {
     if (d.kind === 'unobserved') {
         // Disk proves nothing, but an adoption on this branch settles by the tree.
         if (pIn?.kind === 'pending' && pIn.effect === 'adopt' && pIn.branchId === branchId && !adopt) {
-            return { state: 'unverified', note: d.reason, p: settleAdoption(pIn, s) };
+            return { state: 'unverified', note: d.reason, noteCause: causeOf(d), p: settleAdoption(pIn, s) };
         }
-        return { state: 'unverified', note: d.reason };
+        return { state: 'unverified', note: d.reason, noteCause: causeOf(d) };
     }
     if (d.kind === 'unhashed') {
         // Observed this way only when nothing tracks the path, which is then a
@@ -551,6 +643,7 @@ async function gather(store, agreement, mount, scope, opts) {
     // is followed, as `rootReal` is: `followSymlinks` governs links within it.
     const root = await locateRoot(mount.view, mount.rootReal);
     const rootUnavailable = 'reason' in root ? root.reason : null;
+    const rootCause = 'reason' in root && root.errno !== undefined ? { errno: root.errno } : {};
     // The branch is labelled where the tracked candidates are read, with no
     // await between: the decision is checked against this label.
     const branchId = store.currentBranch().id;
@@ -565,7 +658,7 @@ async function gather(store, agreement, mount, scope, opts) {
     if (rootUnavailable !== null) {
         // Said whether or not anything is tracked: an unavailable mount must not
         // read as a verified empty directory.
-        gathered.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason: rootUnavailable });
+        gathered.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason: explained(rootUnavailable, rootCause, 'list') });
     }
     // Which paths to decide: what disk shows, and what the store, P and intent
     // track. The tracked ones are read synchronously, on this branch. A path
@@ -617,7 +710,7 @@ async function gather(store, agreement, mount, scope, opts) {
     // Observe. Tracked facts are read again, synchronously, when deciding.
     for (const path of candidates) {
         if (rootUnavailable !== null) {
-            gathered.facts.set(path, { kind: 'unobserved', reason: rootUnavailable });
+            gathered.facts.set(path, { kind: 'unobserved', reason: rootUnavailable, ...rootCause });
             continue;
         }
         // What the mount passes over by design stays unobserved by a pass that
@@ -672,7 +765,9 @@ async function gather(store, agreement, mount, scope, opts) {
                 if (region === undefined || r.path.length > region.path.length)
                     region = r;
             }
-            gathered.facts.set(path, { kind: 'unobserved', reason: region ? region.reason : 'not reached by the walk' });
+            gathered.facts.set(path, region
+                ? { kind: 'unobserved', reason: region.reason, ...(region.errno !== undefined ? { errno: region.errno } : {}) }
+                : { kind: 'unobserved', reason: 'not reached by the walk' });
             continue;
         }
         const p = agreement.get(mount.name, path);
@@ -688,12 +783,13 @@ async function gather(store, agreement, mount, scope, opts) {
         const after = await locateRoot(mount.view, mount.rootReal);
         if (!('identity' in after) || !sameRootIdentity(after.identity, gathered.rootIdentity)) {
             const reason = 'reason' in after ? after.reason : ROOT_REPLACED;
+            const errno = 'errno' in after ? after.errno : undefined;
             for (const path of gathered.facts.keys())
-                gathered.facts.set(path, { kind: 'unobserved', reason });
+                gathered.facts.set(path, { kind: 'unobserved', reason, ...(errno !== undefined ? { errno } : {}) });
             gathered.rootIdentity = null;
             gathered.walk = null;
             gathered.dirs = [];
-            gathered.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason });
+            gathered.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason: explained(reason, errno !== undefined ? { errno } : {}, 'list') });
         }
     }
     return gathered;
@@ -723,14 +819,13 @@ export async function reconcilePass(store, agreement, mount, scope, opts = {}) {
         }
     }
     if (gathered === null) {
-        result.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason: 'the selected branch kept changing while the scan ran' });
+        result.undecided = 'the selected branch kept changing while the scan ran';
+        result.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason: explained(result.undecided, { again: true }, 'list') });
         return result;
     }
     if (opts.branchId !== undefined && gathered.branchId !== opts.branchId) {
-        result.incomplete.push({
-            path: scope.kind === 'dir' ? scope.dir : scope.paths.join(', '),
-            reason: 'the selected branch changed before this sync ran; nothing was taken from disk — sync again on this branch to take it',
-        });
+        result.undecided = 'the selected branch changed before this sync ran; nothing was taken from disk — sync again on this branch to take it';
+        result.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : scope.paths.join(', '), reason: result.undecided });
         return result;
     }
     const { walk, facts } = gathered;
@@ -861,6 +956,8 @@ export async function reconcilePass(store, agreement, mount, scope, opts = {}) {
         }
         if (x.verdict.note)
             report.note = x.verdict.note;
+        if (x.verdict.noteCause !== undefined)
+            report.noteCause = x.verdict.noteCause;
         if (!(x.verdict.state === 'synced' && !entry))
             result.reports.set(x.path, report);
     }
@@ -891,8 +988,9 @@ export async function reconcilePass(store, agreement, mount, scope, opts = {}) {
             // holder), so naming the directory as unreached would never clear.
             const wholeScope = scope.kind === 'dir' && scope.dir !== '' && region.path === scope.dir;
             const unreached = hides && region.reason !== OTHER_MOUNT;
-            if (region.kind === 'error' || region.kind === 'cap' || unreached || wholeScope)
-                result.incomplete.push({ path: region.path, reason: region.reason });
+            if (region.kind === 'error' || region.kind === 'cap' || unreached || wholeScope) {
+                result.incomplete.push({ path: region.path, reason: explained(region.reason, region.errno !== undefined ? { errno: region.errno } : {}, 'list') });
+            }
             // A name passed over by design that hides nothing tracked is reported nowhere else:
             // counted, so a sync that says 0 also says what it didn't look at
             // (agent-framework #276). A symlink region isn't counted: a link the
@@ -941,8 +1039,9 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
     // unmounted from. The push plans nothing, so it reports no branch.
     const root = await locateRoot(mount.view, mount.rootReal);
     if ('reason' in root) {
+        const why = explained(root.reason, root.errno !== undefined ? { errno: root.errno } : {}, 'write');
         for (const path of paths)
-            result.skipped.push({ path, reason: root.reason });
+            result.skipped.push({ path, reason: why });
         return result;
     }
     // Another mount's directory nested in this one is that mount's: no push
@@ -971,7 +1070,7 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
     // nothing is decided or recorded from them.
     const after = await locateRoot(mount.view, mount.rootReal);
     if (!('identity' in after) || !sameRootIdentity(after.identity, root.identity)) {
-        const reason = 'reason' in after ? after.reason : ROOT_REPLACED;
+        const reason = 'reason' in after ? explained(after.reason, after.errno !== undefined ? { errno: after.errno } : {}, 'write') : ROOT_REPLACED;
         for (const path of paths)
             result.skipped.push({ path, reason });
         return result;
@@ -992,9 +1091,6 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
         const p = agreement.get(mount.name, path);
         const bi = mount.intents.get(path);
         const v = decide(d, s, p, bi, branchId, false);
-        // The ways out a refusal names, as materialize takes them: a deletion
-        // reaches disk only with applyDeletions.
-        const again = s ? 'materialize again' : 'materialize again with applyDeletions';
         // Where disk has deleted a file the workspace holds, a sync takes the
         // deletion, which removes the workspace's copy, and a forced push writes
         // the workspace's copy back: there is no disk copy to adopt or overwrite.
@@ -1118,8 +1214,7 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
                         ? d.kind === 'absent' || d.kind === 'file'
                             ? `${v.note} — ${sync}`
                             : `${v.note}, and disk's copy can't be verified (${d.kind === 'unobserved' ? d.reason : 'not hashed'}) — once it can be, ${sync}`
-                        : inTheWay(v.note, !s) ??
-                            `cannot verify disk copy (${v.note ?? 'not observed'}) — fix it and ${again}${forcedWay(v.note, !s, forced)}`,
+                        : inTheWay(v.note, !s) ?? unverifiedCopy(v, s ? 'write' : 'unlink', forced),
                 });
                 continue;
             }
@@ -1186,7 +1281,7 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
                 // A deletion no push makes, forced or not (inTheWay), is refused for
                 // that, as an unforced push refuses it, rather than left for
                 // applyDeletions, which couldn't make it either.
-                const lasting = inTheWay(v.note, true);
+                const lasting = inTheWay(v.note, true) ?? (v.noteCause?.ownStep === true ? v.note ?? null : null);
                 if (lasting !== null)
                     result.skipped.push({ path, reason: lasting });
                 else
@@ -1319,19 +1414,19 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
             }
         }
         catch (err) {
-            const failure = err instanceof EffectFailed ? err : new EffectFailed(err instanceof Error ? err.message : String(err), true);
+            const failure = err instanceof EffectFailed ? err : callFailed('the push failed', err, true, 'colon');
             if (!failure.touched) {
                 // Disk at this path is as planning saw it: its evidence goes back to
                 // exactly what it was, whatever kind that was.
                 agreement.restore(mount.name, step.path, step.before);
                 recorded = true;
-                const why = inTheWay(failure.message, step.kind === 'unlink') ?? failure.message;
+                const why = step.kind === 'chmod' ? withWayOn(failure.message, failure.detail, 'write') : explained(failure.message, failure.detail, step.kind);
                 result.skipped.push({ path: step.path, reason: `not ${step.kind === 'unlink' ? 'unlinked' : step.kind === 'chmod' ? 'given the workspace\'s mode' : 'written'}: ${why}` });
             }
             else {
                 // No completion: the intent stays pending, and the next observation
                 // resolves it from whatever disk then holds.
-                result.skipped.push({ path: step.path, reason: `${failure.message}; the outcome is checked at the next observation` });
+                result.skipped.push({ path: step.path, reason: `${failure.message} — ${UNSETTLED}` });
             }
         }
     }
@@ -1349,7 +1444,7 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
             result.skipped.push({
                 path: step.path,
                 reason: `could not make the ${step.kind === 'write' ? 'write' : 'unlink'} durable (directory fsync of ${failed === '' ? 'the mount root' : failed}): ` +
-                    `${unsynced.get(failed)}; the outcome is checked at the next observation`,
+                    `${unsynced.get(failed)} — ${UNSETTLED}`,
             });
             continue;
         }
@@ -1429,6 +1524,7 @@ export async function pushPaths(store, agreement, mount, paths, opts = {}) {
     return result;
 }
 function unstoredCopy(stored) {
-    return 'missing' in stored ? 'the workspace copy is missing from the store' : `the workspace copy is unreadable in the store (${stored.unreadable})`;
+    return `${'missing' in stored ? 'the workspace copy is missing from the store' : `the workspace copy is unreadable in the store (${stored.unreadable})`}`
+        + " — a read of this path takes disk's copy where it can, and otherwise says what can be done";
 }
 //# sourceMappingURL=reconcile.js.map