@animalabs/agent-framework 0.21.0 → 0.22.0

package/dist/src/modules/workspace/disk-agreement.js

@@ -0,0 +1,259 @@
+/**
+ * Physical disk-agreement evidence (P): for each mount and path, what disk held
+ * when it last agreed with the workspace store, or what the module last wrote
+ * there or adopted from it.
+ *
+ * P describes disk, and disk does not rewind with a branch switch, so P lives
+ * in global chronicle records (RecordJournal) rather than branch state: after
+ * an undo selects an older tree, P still says what disk holds, and a
+ * difference reads as a store-side change, never as a disk edit. Branch-local
+ * intent — tombstones, store origin, conflicts — lives in BranchIntents and
+ * rewinds with the tree.
+ *
+ * P is evidence about one directory, so each mount also records the identity
+ * (device and inode) of the root that evidence was gathered under. A root
+ * that isn't that directory any more (an unmounted drive whose mountpoint is
+ * now empty, a replaced directory) is an unavailable mount, never a disk on
+ * which every file was deleted; only an explicit acceptance takes it, and
+ * that starts its evidence afresh.
+ *
+ * Every transition is write-ahead (see reconcile.ts): an `intent` entry
+ * (`pending`, with the prior value and the expected one) is durable before the
+ * disk effect or tree adoption it announces, and the completion `set` is
+ * appended only after that effect is durable. One tree adoption has no
+ * intent: a drop, which removes the store's copy of a disk version the
+ * workspace can't hold, forgets P first, so a crash before the removal leaves
+ * P unknown, never a wrong adoption. A pending adoption resolves at its next
+ * observation, by the tree. A pending disk effect resolves there only when
+ * disk shows it didn't happen (the prior) or can't tell (`interrupted`, a
+ * sticky conflict resolved explicitly, or by disk and the store coming to
+ * agree); one that shows on disk is completed only by a push whose barriers
+ * succeed, since its completion releases a draft's protection.
+ */
+import { resolve } from 'node:path';
+import { RecordJournal } from '../../record-journal.js';
+/** Whether two configured roots name the same path, whatever their spelling
+ *  (a trailing slash, a relative form). A symlinked alias is another path. */
+function sameRootPath(a, b) {
+    return resolve(a) === resolve(b);
+}
+export function sameRootIdentity(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+export const DISK_AGREEMENT_RECORD_TYPE = 'workspace/disk-agreement';
+/** Checkpoint once the tail outgrows this many entries, or the live paths, whichever is larger. */
+const MIN_CHECKPOINT_TAIL = 1000;
+export function candidateOf(value) {
+    return value.kind === 'absent' ? { kind: 'absent' } : { kind: 'content', hash: value.hash };
+}
+export function sameCandidate(a, b) {
+    return a.kind === b.kind && (a.kind === 'absent' || a.hash === b.hash);
+}
+export class DiskAgreement {
+    store;
+    journal;
+    mounts = new Map();
+    configured = [];
+    /**
+     * An append (or a rebuild) not yet made durable. Cleared only by a
+     * barrier that succeeds, so a failed barrier stays owed: a later pass with
+     * nothing new to record still settles it before deciding anything.
+     */
+    unsynced = false;
+    constructor(store) {
+        this.store = store;
+        this.journal = new RecordJournal(store, { type: DISK_AGREEMENT_RECORD_TYPE });
+    }
+    /**
+     * Rebuild P from the journal for the configured mounts. A mount whose
+     * recorded root differs from its configured one starts empty: evidence
+     * about another directory says nothing about this one.
+     */
+    open(mounts) {
+        this.configured = mounts;
+        this.rebuild();
+    }
+    /**
+     * Re-read the journal when an earlier write left it unreconciled, and throw
+     * once an append failed inside the store. P may then lack what that append
+     * recorded (the store may hold it where this process can't read it back),
+     * and a decision from stale P can record what reopening contradicts, such
+     * as a conflict that stays after the right evidence is back. So until the
+     * store is reopened, no evidence is read, written or checkpointed, and
+     * every pass and tool call that needs it fails.
+     */
+    ensureReconciled() {
+        if (this.journal.needsReopen) {
+            throw new Error('Disk-agreement evidence is unavailable until the store is reopened, as at the next start: ' +
+                'an append to its journal failed inside the store, and the evidence may lack what it recorded');
+        }
+        if (this.journal.needsReconcile)
+            this.rebuild();
+    }
+    /** Whether evidence recorded so far still awaits a barrier. */
+    get needsBarrier() {
+        return this.unsynced;
+    }
+    /**
+     * Replay the journal into memory. Records that read back are not proven
+     * durable — a previous owner may have appended them and died before any
+     * barrier — so evidence rebuilt here owes one, whether at open or after an
+     * ambiguous append.
+     */
+    rebuild() {
+        this.unsynced = true;
+        const { snapshot, entries } = this.journal.load();
+        const replayed = new Map();
+        for (const [name, mount] of Object.entries(snapshot?.mounts ?? {})) {
+            replayed.set(name, {
+                root: mount.root,
+                ...(mount.identity ? { identity: mount.identity } : {}),
+                paths: new Map(Object.entries(mount.paths)),
+            });
+        }
+        for (const { entry } of entries) {
+            if (entry.t === 'mount') {
+                const existing = replayed.get(entry.mount);
+                if (!existing || !sameRootPath(existing.root, entry.root))
+                    replayed.set(entry.mount, { root: entry.root, paths: new Map() });
+                continue;
+            }
+            const mount = replayed.get(entry.mount);
+            if (!mount)
+                continue;
+            if (entry.t === 'root')
+                applyRoot(mount, entry);
+            else if (entry.t === 'set')
+                mount.paths.set(entry.path, entry.value);
+            else
+                mount.paths.delete(entry.path);
+        }
+        this.mounts.clear();
+        for (const { name, root } of this.configured) {
+            const found = replayed.get(name);
+            if (found && sameRootPath(found.root, root)) {
+                this.mounts.set(name, found);
+            }
+            else {
+                this.mounts.set(name, { root, paths: new Map() });
+                this.journal.append({ t: 'mount', mount: name, root });
+            }
+        }
+    }
+    /** The identity of the root this mount's evidence was gathered under, once any was. */
+    rootIdentity(mount) {
+        this.ensureReconciled();
+        return this.mounts.get(mount)?.identity;
+    }
+    /**
+     * Record the root's identity just before the first evidence a mount gains:
+     * the caller saw it as the root while gathering that evidence. A no-op once
+     * one is recorded; changing it is acceptRoot's alone.
+     */
+    recordRootIdentity(mount, identity) {
+        if (this.rootIdentity(mount) !== undefined)
+            return;
+        this.write({ t: 'root', mount, identity }, {});
+    }
+    /**
+     * Take the root as it is now, at the operator's word: record its identity
+     * and forget every path's evidence, which described another directory.
+     */
+    acceptRoot(mount, identity) {
+        this.write({ t: 'root', mount, identity, reset: true }, {});
+    }
+    get(mount, path) {
+        this.ensureReconciled(); // an ambiguous append may have landed: read it back first
+        return this.mounts.get(mount)?.paths.get(path);
+    }
+    /** Every path with evidence under a prefix ('' for the whole mount). */
+    paths(mount, prefix = '') {
+        this.ensureReconciled();
+        const paths = this.mounts.get(mount)?.paths;
+        if (!paths)
+            return [];
+        const out = [];
+        for (const [path, value] of paths) {
+            if (prefix === '' || path === prefix || path.startsWith(prefix + '/'))
+                out.push([path, value]);
+        }
+        return out;
+    }
+    /**
+     * Record an intent. `durable` makes it (and every append before it) stable
+     * before the caller performs the effect; batches pass it on their last one.
+     */
+    intend(mount, path, intent, opts = {}) {
+        this.write({ t: 'set', mount, path, value: { kind: 'pending', ...intent } }, { durable: opts.durable });
+    }
+    /**
+     * Record agreed evidence. `afterCommittedState` when it asserts a tree
+     * commit made just before (the commit is synced first).
+     */
+    set(mount, path, value, opts = {}) {
+        this.write({ t: 'set', mount, path, value }, { afterCommittedState: opts.afterCommittedState });
+    }
+    /** Forget a path: P becomes unknown, the most conservative evidence. */
+    forget(mount, path) {
+        if (this.get(mount, path) === undefined)
+            return;
+        this.write({ t: 'forget', mount, path }, {});
+    }
+    /**
+     * Put back exactly the evidence a path had before an intent whose effect
+     * never touched it — whatever kind it was (agreed, pending, interrupted, or
+     * unknown) — so the intent leaves no trace in what P says.
+     */
+    restore(mount, path, value) {
+        if (value === undefined)
+            this.forget(mount, path);
+        else
+            this.write({ t: 'set', mount, path, value }, {});
+    }
+    write(entry, opts) {
+        this.ensureReconciled();
+        this.unsynced = true; // until proven durable: a failed append may still have landed
+        this.journal.append(entry, opts);
+        if (opts.durable)
+            this.unsynced = false; // synced after this append, and so everything before it
+        const mount = this.mounts.get(entry.mount);
+        if (!mount)
+            return;
+        if (entry.t === 'root')
+            applyRoot(mount, entry);
+        else if (entry.t === 'set')
+            mount.paths.set(entry.path, entry.value);
+        else if (entry.t === 'forget')
+            mount.paths.delete(entry.path);
+    }
+    /** Checkpoint when the tail has outgrown the live evidence. */
+    maybeCheckpoint() {
+        // Like every entry point: an ambiguous write is read back first.
+        this.ensureReconciled();
+        let live = 0;
+        for (const mount of this.mounts.values())
+            live += mount.paths.size;
+        if (this.journal.entriesSinceCheckpoint < Math.max(MIN_CHECKPOINT_TAIL, live))
+            return;
+        const snapshot = { mounts: {} };
+        for (const [name, mount] of this.mounts) {
+            snapshot.mounts[name] = {
+                root: mount.root,
+                ...(mount.identity ? { identity: mount.identity } : {}),
+                paths: Object.fromEntries(mount.paths),
+            };
+        }
+        this.journal.checkpoint(snapshot);
+    }
+    /** Make every append so far stable. Throws, and stays owed, if the sync fails. */
+    barrier() {
+        this.store.sync();
+        this.unsynced = false;
+    }
+}
+function applyRoot(mount, entry) {
+    mount.identity = entry.identity;
+    if (entry.reset)
+        mount.paths.clear();
+}
+//# sourceMappingURL=disk-agreement.js.map

package/dist/src/modules/workspace/disk-agreement.js.map

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

package/dist/src/modules/workspace/effects.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The workspace's disk effects — a materialize's writes and unlinks, and the
+ * barriers that make them durable — under the mount boundary.
+ *
+ * Each effect is bound at its point of use, not at planning time: the parent
+ * directory is checked (located inside the mount, see observe.ts), the file is
+ * reached through it, and before anything is changed the effect checks that
+ * it acts on what was decided on — a regular file inside the mount, at this
+ * path, still holding the bytes planning saw (unless `force`, which overrides
+ * that freshness but never the boundary). Content is written only through a
+ * descriptor whose own location was confirmed inside the mount first, and
+ * only into a file with no other hard links: a write in place changes the
+ * file under every name it has, and the others may lie outside the mount (a
+ * package store's, say), so such a file is refused. Unlinking one name
+ * changes no other, so an unlink needs no such check.
+ *
+ * What an effect reports matters to the caller's evidence: a failure that
+ * never touched the path's entry leaves disk as planning saw it, so the
+ * path's evidence can be put back as it was; once the entry was touched
+ * (created, truncated, written or unlinked) the outcome is for the next
+ * observation to resolve. Directories created for a write don't touch the
+ * path's entry; they stay, empty, if the write is refused.
+ *
+ * Node has no openat, so a create, mkdir or unlink still resolves its path by
+ * name after the parent was checked: a parent replaced concurrently in that
+ * window can redirect that one operation, leaving an empty file or directory
+ * outside the mount or unlinking a same-named file there. Nor is there an
+ * unlink bound to an inode: an unlink checks the entry's identity again just
+ * before it, and a file replaced at its path after that check is the one
+ * unlinked. Content writes stay bound to the descriptor verified before
+ * modification: inside the mount, with no other hard links (a link another
+ * process makes to it after that check shares the write). The hash, which
+ * reads the whole file, comes before the checks of where the file is, and
+ * the root is checked again beside the parent, since the parent is found by
+ * path beneath the root's. A last look at the file (its descriptor's stat
+ * before a write, its entry's lstat before an unlink) refuses one written
+ * since it was first seen, so only an edit made in the moment between that
+ * look and the effect is overwritten or removed.
+ */
+import { type MountView } from './observe.js';
+/** What a write or unlink may find at its path when it acts. */
+export type Expect = {
+    kind: 'absent';
+}
+/** The bytes planning decided on, by hash. */
+ | {
+    kind: 'content';
+    hash: string;
+}
+/** Anything (force): freshness is overridden, the boundary is not. */
+ | {
+    kind: 'any';
+};
+export declare class EffectFailed extends Error {
+    /** Whether the path's entry was touched before the failure. */
+    readonly touched: boolean;
+    constructor(message: string, touched: boolean);
+}
+/**
+ * Write `bytes` at a mount-relative path, creating missing parent
+ * directories, and make the file durable (its directories are synced by the
+ * caller, after all of a push's effects: syncDirectories).
+ */
+export declare function writeContained(view: MountView, rootReal: string, rel: string, bytes: Buffer, expect: Expect): Promise<void>;
+/**
+ * Unlink a mount-relative file, or confirm it gone (`absent` expected: a
+ * file found there is never removed). Returns the mount directory whose
+ * entries make the absence durable, for the caller's barrier: the file's
+ * parent, or — when the parent itself is gone — the directory proven to lack
+ * it, since that removal may not be durable either.
+ */
+export declare function unlinkContained(view: MountView, rootReal: string, rel: string, expect: Expect): Promise<string>;
+/**
+ * Sync each mount directory (mount-relative), deepest first, so the entries
+ * a push created or removed in them are durable. Each is checked first and the
+ * directory it holds is the one synced — never a replacement at its path.
+ * Returns the ones that failed, with why. Where directories can't be synced
+ * at all (Windows, or a filesystem answering EINVAL/ENOTSUP), there is
+ * nothing to wait for.
+ */
+export declare function syncDirectories(view: MountView, rootReal: string, rels: Iterable<string>): Promise<Map<string, string>>;
+/** The directories whose entries make a written file reachable: its parent up to the mount root. */
+export declare function chainOf(rel: string): string[];
+//# sourceMappingURL=effects.d.ts.map

package/dist/src/modules/workspace/effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAMH,OAAO,EAEL,KAAK,SAAS,EAWf,MAAM,cAAc,CAAC;AAEtB,gEAAgE;AAChE,MAAM,MAAM,MAAM,GACd;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE;AACpB,8CAA8C;GAC5C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACnC,sEAAsE;GACpE;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAKpB,qBAAa,YAAa,SAAQ,KAAK;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;CAI9C;AAmFD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmFjI;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA0DrH;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA0B7H;AAED,oGAAoG;AACpG,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAM7C"}