@animalabs/agent-framework 0.21.1 → 0.22.0

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

@@ -0,0 +1,278 @@
+/**
+ * How the workspace observes disk for reconciliation, under the mount's
+ * boundary.
+ *
+ * Observation honors the boundary the way openContainedFile does: the lexical
+ * path is lstat'd first, a symlink is refused unless the mount follows
+ * symlinks, and a followed one must resolve inside the canonical mount root.
+ * Anything that isn't a regular file inside the mount is `unobserved` — it
+ * proves nothing either way, and reconciliation leaves the path alone.
+ *
+ * Reads go through one descriptor that is fstat'd, located inside the mount
+ * and then read, so what is read and the fingerprint recorded with its hash
+ * describe the same file, inside the mount. A hard link is a name inside the
+ * mount like any other, and reading through it shows what that path holds;
+ * only a write in place reaches a file's other names, so effects.ts refuses
+ * that instead.
+ *
+ * Directories are checked (CheckedDir): located inside the mount, with their
+ * identity, and what they showed — a listing, an absence — is accepted only
+ * if each is still the directory its logical path names afterwards. A walk records which
+ * directories it listed completely, and only those prove a file absent: an
+ * unreadable directory, an ignored subtree, the file cap, a symlink the walk
+ * doesn't descend, or a directory that changed while it was listed leave
+ * everything beneath them unproven. Outside a walk, absence is proven the
+ * same way: by a directory inside the mount, still at its path, that lacks
+ * the entry (confirmAbsent). A missing parent alone proves nothing, since a
+ * dangling symlink or a swapped directory looks just like one.
+ *
+ * Each check is made where the operation happens, against what is there at
+ * that moment, so the boundary holds against what is in the mount, including
+ * what appears while an operation runs. Node has no openat or fdopendir, so
+ * a directory is checked by its canonical path and identity, not held open:
+ * a parent replaced concurrently in the window between a check and its use
+ * (or replaced and restored around it) can still redirect a listing or
+ * lookup there. File contents are bound regardless: a file is read only
+ * through a descriptor bound to its path first.
+ */
+import { type Fingerprint, type RootIdentity } from './disk-agreement.js';
+export interface MountView {
+    /** Mount root as configured. */
+    root: string;
+    /**
+     * The root directory disk last agreed under, once the mount has evidence.
+     * A root that resolves to any other directory is unavailable.
+     */
+    rootIdentity?: RootIdentity;
+    followSymlinks: boolean;
+    /** Text above this size is not ingested. */
+    maxFileSize: number;
+    ignore: string[];
+}
+export type StatFingerprint = Omit<Fingerprint, 'hashedAt'>;
+/**
+ * Opened with every read or write of a workspace path, where the platform has
+ * it: for a regular file it changes nothing, and a FIFO or other special file
+ * swapped in at the path neither blocks the open nor passes the regular-file
+ * check that follows.
+ */
+export declare const NONBLOCK: number;
+export type Observation = {
+    kind: 'absent';
+} | {
+    kind: 'file';
+    size: number;
+    mtimeMs: number;
+    fp: StatFingerprint;
+} | {
+    kind: 'unobserved';
+    reason: string;
+};
+export interface ReadResult {
+    kind: 'read';
+    size: number;
+    mtimeMs: number;
+    fp: Fingerprint;
+    hash: string;
+    /** The whole file, when it is at most the requested limit. */
+    bytes: Buffer | null;
+    /** First bytes, for binary detection and MIME sniffing. */
+    head: Buffer;
+}
+/** The first bytes of a file and its size: nothing else was read or hashed. */
+export interface HeadResult {
+    kind: 'head';
+    size: number;
+    mtimeMs: number;
+    head: Buffer;
+}
+/** Bytes kept for binary detection and MIME sniffing. */
+export declare const HEAD_BYTES = 8192;
+/** Timestamps this close to the hashing time can't vouch for the bytes. */
+export declare const RACY_WINDOW_MS = 2000;
+export declare const OUTSIDE_PARENT = "a parent directory resolves outside the mount";
+export declare const NOT_FOLLOWED = "a symlink, which this mount does not follow";
+export declare const ROOT_UNAVAILABLE = "the mount root is unavailable";
+export declare const ROOT_REPLACED: string;
+export declare function errno(err: unknown): string | undefined;
+export declare function contained(rootReal: string, candidate: string): boolean;
+/** The mount-relative parent of a path ('' for the root). */
+export declare function parentOf(relativePath: string): string;
+/** The last component of a mount-relative path. */
+export declare function nameOf(relativePath: string): string;
+export type DirCheck = {
+    kind: 'checked';
+    dir: CheckedDir;
+}
+/**
+ * No directory there, proven: nothing can exist beneath the path. `by` is
+ * the directory whose entries prove it — the one that lacks it, or that
+ * holds the non-directory in its place.
+ */
+ | {
+    kind: 'absent';
+    by: string;
+}
+/** Unproven either way; `outside` when it resolves outside the mount. */
+ | {
+    kind: 'unobserved';
+    reason: string;
+    outside?: true;
+};
+/**
+ * A directory inside the mount, as it was checked: its canonical path and
+ * its identity. Its entries are named through that path, and what it showed
+ * is accepted only while it is still the directory its logical path names
+ * (see the module doc for what that does and doesn't bind).
+ */
+export declare class CheckedDir {
+    /** Mount-relative path ('' for the root). */
+    readonly rel: string;
+    /** Its canonical location when checked. */
+    readonly real: string;
+    private readonly lexical;
+    private readonly dev;
+    private readonly ino;
+    constructor(
+    /** Mount-relative path ('' for the root). */
+    rel: string, 
+    /** Its canonical location when checked. */
+    real: string, lexical: string, dev: bigint, ino: bigint);
+    /** Which directory it is. */
+    identity(): RootIdentity;
+    /** A path that reaches `name` in this directory. */
+    at(name: string): string;
+    /** Whether it is still the directory its logical path names: same location, same directory. */
+    stillHere(): Promise<boolean>;
+    /**
+     * Make its entries durable: this very directory, never one that replaced
+     * it at its path. Throws if it can't; a filesystem that can't sync
+     * directories (or Windows, where a directory can't be opened for it) is
+     * not a failure.
+     */
+    sync(): Promise<void>;
+}
+/**
+ * The mount root as it is now: its identity if it is available (a directory,
+ * the one the pass was given, and the one disk last agreed under), else why not.
+ */
+export declare function locateRoot(view: MountView, rootReal: string): Promise<{
+    identity: RootIdentity;
+} | {
+    reason: string;
+}>;
+/** The mount root as locateRoot finds it, checked, so a caller can ask later whether it's still there. */
+export declare function checkRoot(view: MountView, rootReal: string): Promise<{
+    dir: CheckedDir;
+} | {
+    reason: string;
+}>;
+/**
+ * Check the directory at a mount-relative path. With `create`, missing
+ * directories are made one at a time beneath the deepest one that exists;
+ * the mount root itself is never created (a missing root is an unavailable
+ * mount). Without it, a missing directory is `absent` only where that can be
+ * proven (confirmAbsent).
+ */
+export declare function checkDir(view: MountView, rootReal: string, rel: string, opts?: {
+    create?: boolean;
+}): Promise<DirCheck>;
+/**
+ * Prove that nothing exists at a mount-relative path (`entry`), or that no
+ * directory does, so nothing can exist beneath it (`beneath`). Walking down
+ * from the root through checked directories: some directory lacks the next
+ * component; or a component is a non-directory, still the same one, beneath
+ * which nothing can exist. Either proves it only while every directory the
+ * walk went through, the root included, is still the one its path names
+ * afterwards: a root or parent replaced during the walk would otherwise lend
+ * its replacement's absence to the original's path. Symlinked directories
+ * inside the mount are followed as parents; any other symlink proves
+ * nothing. Returns the directory whose entries prove it, or why absence
+ * couldn't be shown.
+ */
+export declare function confirmAbsent(view: MountView, rootReal: string, rel: string, target?: 'entry' | 'beneath'): Promise<{
+    by: string;
+} | string>;
+/** Same file, same bytes, as far as stat can tell. */
+export declare function sameFingerprint(a: StatFingerprint, b: StatFingerprint): boolean;
+/**
+ * Whether a recorded fingerprint vouches that the current file still holds
+ * the bytes hashed with it: the filesystem maintains ctime (so no user-space
+ * tool can restore the old stamps after a write), every field matches, and
+ * the file's timestamps were already more than the racy window old when it
+ * was hashed (a write in the same timestamp tick can't hide behind them).
+ * Device and inode are part of it, so a stat that reached another file — a
+ * path whose parent was swapped, say — can never vouch for P's bytes.
+ */
+export declare function fingerprintVouches(recorded: Fingerprint | undefined, current: StatFingerprint, trusted: boolean): boolean;
+/** Whether a statfs f_type is one of those filesystems. */
+export declare function fsTypeTrustsCtime(type: number | bigint): boolean;
+export declare function filesystemTrustsCtime(root: string): Promise<boolean>;
+/**
+ * Observe a mount-relative path without reading it. A `file` here is only a
+ * stat — anything decided on its bytes is read through a located descriptor,
+ * or vouched for by a fingerprint of the very inode P was recorded from — so
+ * only `absent` needs proof beyond the path lookup, and gets it.
+ */
+export declare function observePath(view: MountView, rootReal: string, relativePath: string): Promise<Observation>;
+/**
+ * Read and hash a mount-relative file through one located descriptor. The
+ * whole file is returned when it is at most `limit` bytes; larger files are
+ * hashed in chunks and only their head is kept.
+ */
+export declare function readPath(view: MountView, rootReal: string, relativePath: string, limit: number): Promise<ReadResult | Exclude<Observation, {
+    kind: 'file';
+}>>;
+/**
+ * The first bytes of a mount-relative file and its size, through the same
+ * located descriptor as readPath — for listing a file nothing tracks, which
+ * needs a MIME type, not a hash.
+ */
+export declare function readHead(view: MountView, rootReal: string, relativePath: string): Promise<HeadResult | Exclude<Observation, {
+    kind: 'file';
+}>>;
+/** Null bytes in the first 8 KB: the store holds text only from disk. */
+export declare function looksBinary(head: Buffer): boolean;
+/** Image MIME type from magic bytes, for listing disk-only files. */
+export declare function sniffImageMime(head: Buffer): string | undefined;
+export interface Walk {
+    /** Regular files seen. */
+    files: Set<string>;
+    /** Directories seen. */
+    dirs: Set<string>;
+    /** Names seen that are neither (symlinks, sockets…), or ignored: present, unproven. */
+    others: Map<string, string>;
+    /** Directories listed completely. */
+    complete: Set<string>;
+    /** Directories that don't exist (everything beneath them is absent). */
+    missing: Set<string>;
+    /**
+     * Where the walk didn't reach, and why. `error` and `cap` regions may hide
+     * files the listing would show; `ignored` and `symlink` ones matter only
+     * where tracked entries lie beneath them.
+     */
+    incomplete: Array<{
+        path: string;
+        reason: string;
+        kind: 'error' | 'cap' | 'ignored' | 'symlink';
+    }>;
+}
+/** Simple ignore patterns, as the watcher and the old walk read them. */
+export declare function isIgnored(relativePath: string, name: string, patterns: string[]): boolean;
+/**
+ * List a directory scope ('' for the mount root), descending when recursive,
+ * up to `cap` files in total. A scope that resolves outside the mount is not
+ * listed at all; beneath it, the walk only descends real directories, never
+ * symlinks. Each directory's listing counts only if, once listed, it is still
+ * the directory at its path: a directory moved or replaced meanwhile is an
+ * incomplete region, contributing no names and proving nothing absent.
+ */
+export declare function walkScope(view: MountView, rootReal: string, scope: string, recursive: boolean, cap: number): Promise<Walk>;
+/**
+ * Whether the walk proves nothing exists at `path`: some ancestor directory
+ * is missing, or a completely listed ancestor holds no entry that could lead
+ * to it. Ancestors outside the walked scope are passed through, so a walk of
+ * `a/b` decides paths beneath `a/b` and nothing else.
+ */
+export declare function provenAbsent(walk: Walk, path: string): boolean;
+//# sourceMappingURL=observe.d.ts.map

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

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