@apexops/kernel 0.10.0-next.4 → 0.11.0-next.0

package/dist/repeat-files.js

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { sha256Json } from "./canonical.js";
+import { retrySharingViolations } from "./files.js";
+/** Most entries a repeat file snapshot covers; a larger tree fails the snapshot, which disables replay and storage. */
+export const MAX_REPEAT_FILE_ENTRIES = 20_000;
+/** Most file bytes a repeat file snapshot hashes; a larger tree fails the snapshot, which disables replay and storage. */
+export const MAX_REPEAT_FILE_BYTES = 64 * 1024 * 1024;
+const HASH_CHUNK_BYTES = 64 * 1024;
+const HASH_ATTEMPTS = 3;
+/** A bound tree is too large or kept changing while it was read, so it cannot be bound by content. */
+export class RepeatFileSnapshotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RepeatFileSnapshotError";
+    }
+}
+function within(root, path) {
+    const offset = relative(root, path);
+    return offset === "" || (offset !== ".." && !offset.startsWith(`..${sep}`) && !isAbsolute(offset));
+}
+function statKey(metadata) {
+    return [metadata.dev, metadata.ino, metadata.mode, metadata.size, metadata.mtimeNs, metadata.ctimeNs].join(":");
+}
+function missing(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+ * Reads the trees under `roots` and hashes every regular file with streaming SHA-256. Roots nested in another root are
+ * read once. Symbolic links below a root are bound by their own stat and never followed; a root that is a symbolic
+ * link fails the snapshot. A file that keeps changing while it is hashed, or a tree over the entry or byte budget,
+ * fails the snapshot with {@link RepeatFileSnapshotError}. Windows sharing violations are retried.
+ */
+export async function snapshotRepeatFiles(roots, options = {}) {
+    const maxEntries = options.maxEntries ?? MAX_REPEAT_FILE_ENTRIES;
+    const maxBytes = options.maxBytes ?? MAX_REPEAT_FILE_BYTES;
+    const retry = {
+        ...(options.platform === undefined ? {} : { platform: options.platform }),
+        ...(options.attempts === undefined ? {} : { attempts: options.attempts }),
+        ...(options.sleep === undefined ? {} : { sleep: options.sleep }),
+    };
+    const unique = [...new Set(roots.map((root) => resolve(root)))].sort();
+    const entries = {};
+    let count = 0;
+    let bytes = 0;
+    const add = (path, entry) => {
+        if (++count > maxEntries)
+            throw new RepeatFileSnapshotError("Repeat-bound files exceed their entry budget");
+        entries[path] = entry;
+    };
+    const hash = async (path) => {
+        for (let attempt = 1;; attempt += 1) {
+            let handle;
+            try {
+                handle = await retrySharingViolations(() => open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)), retry);
+            }
+            catch (error) {
+                if (missing(error))
+                    return undefined;
+                throw error;
+            }
+            try {
+                const before = await handle.stat({ bigint: true });
+                if (!before.isFile())
+                    throw new RepeatFileSnapshotError("A repeat-bound file changed type while it was read");
+                const digest = createHash("sha256");
+                const buffer = Buffer.allocUnsafe(HASH_CHUNK_BYTES);
+                let read = 0;
+                for (;;) {
+                    const { bytesRead } = await retrySharingViolations(() => handle.read(buffer, 0, buffer.byteLength, null), retry);
+                    if (bytesRead === 0)
+                        break;
+                    read += bytesRead;
+                    if (bytes + read > maxBytes)
+                        throw new RepeatFileSnapshotError("Repeat-bound files exceed their byte budget");
+                    digest.update(buffer.subarray(0, bytesRead));
+                }
+                const after = await handle.stat({ bigint: true });
+                if (statKey(before) === statKey(after) && BigInt(read) === after.size) {
+                    bytes += read;
+                    return { type: "file", sha256: digest.digest("hex"), stat: statKey(after) };
+                }
+            }
+            finally {
+                await handle.close();
+            }
+            if (attempt >= HASH_ATTEMPTS)
+                throw new RepeatFileSnapshotError("A repeat-bound file kept changing while it was read");
+        }
+    };
+    const visit = async (path, root) => {
+        let metadata;
+        try {
+            metadata = await retrySharingViolations(() => lstat(path, { bigint: true }), retry);
+        }
+        catch (error) {
+            if (missing(error))
+                return;
+            throw error;
+        }
+        if (metadata.isDirectory()) {
+            add(path, { type: "directory" });
+            let names;
+            try {
+                names = await retrySharingViolations(() => readdir(path), retry);
+            }
+            catch (error) {
+                if (missing(error))
+                    return;
+                throw error;
+            }
+            for (const name of names.sort())
+                await visit(join(path, name), false);
+            return;
+        }
+        if (root && metadata.isSymbolicLink())
+            throw new RepeatFileSnapshotError("A repeat-bound root is a symbolic link");
+        if (!metadata.isFile()) {
+            add(path, { type: "other", stat: statKey(metadata) });
+            return;
+        }
+        const entry = await hash(path);
+        if (entry !== undefined)
+            add(path, entry);
+    };
+    for (const root of unique) {
+        if (!unique.some((other) => other !== root && within(other, root)))
+            continue;
+        // A nested root is read through its enclosing root, so check it here for the symbolic-link rule.
+        try {
+            const metadata = await retrySharingViolations(() => lstat(root, { bigint: true }), retry);
+            if (metadata.isSymbolicLink())
+                throw new RepeatFileSnapshotError("A repeat-bound root is a symbolic link");
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+    }
+    for (const root of unique) {
+        if (unique.some((other) => other !== root && within(other, root)))
+            continue;
+        await visit(root, true);
+    }
+    return { roots: unique, entries };
+}
+/** Digest of a snapshot for the repeat state token; equal only for equal roots, paths, contents and stat identities. */
+export function repeatFilesDigest(snapshot) {
+    return sha256Json({ version: 1, roots: snapshot.roots, entries: snapshot.entries });
+}
+/**
+ * Writes a repeat-guarded operation made itself to bound files, in order. The guard compares the bound trees after the
+ * operation with their content at its start changed only by these writes.
+ */
+export class RepeatFileWrites {
+    #writes = [];
+    /** The operation wrote `path` with content of SHA-256 `sha256`, creating missing parent directories. */
+    file(path, sha256) {
+        if (!/^[0-9a-f]{64}$/u.test(sha256))
+            throw new TypeError("Repeat file write needs a SHA-256 content hash");
+        this.#writes.push({ path: resolve(path), sha256 });
+    }
+    /** The operation removed `path` and everything below it. */
+    removed(path) {
+        this.#writes.push({ path: resolve(path), sha256: null });
+    }
+    get writes() {
+        return this.#writes;
+    }
+}
+/**
+ * True when every tree bound at `start` holds, in `end`, exactly its start content changed only by the operation's own
+ * `writes`: a file the operation wrote holds what it wrote, and every other path is unchanged in content and stat
+ * identity. A bound root missing from `end` fails the check, so `end` must be read over at least the start roots.
+ */
+export function repeatFilesHeld(start, end, writes) {
+    if (!start.roots.every((root) => end.roots.includes(root)))
+        return false;
+    const rootOf = (path) => start.roots.filter((root) => within(root, path)).sort((left, right) => right.length - left.length)[0];
+    const expected = new Map(Object.entries(start.entries).filter(([path]) => rootOf(path) !== undefined));
+    for (const { path, sha256 } of writes?.writes ?? []) {
+        if (sha256 === null) {
+            for (const key of [...expected.keys()])
+                if (within(path, key))
+                    expected.delete(key);
+            continue;
+        }
+        const root = rootOf(path);
+        if (root === undefined)
+            continue;
+        expected.set(path, { type: "written", sha256 });
+        for (let parent = dirname(path); within(root, parent); parent = dirname(parent)) {
+            if (!expected.has(parent))
+                expected.set(parent, { type: "directory" });
+            if (parent === root)
+                break;
+        }
+    }
+    const actual = Object.entries(end.entries).filter(([path]) => rootOf(path) !== undefined);
+    if (actual.length !== expected.size)
+        return false;
+    return actual.every(([path, entry]) => {
+        const wanted = expected.get(path);
+        if (wanted === undefined)
+            return false;
+        if (wanted.type === "written")
+            return entry.type === "file" && entry.sha256 === wanted.sha256;
+        return sha256Json(wanted) === sha256Json(entry);
+    });
+}
+//# sourceMappingURL=repeat-files.js.map

package/dist/repeat-files.js.map

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

package/dist/repeat-guard.d.ts

@@ -0,0 +1,197 @@
+import { type EventV1, type ProjectId, type RepeatGuardRecordV1, type RunId } from "@apexops/contracts";
+import { type RepeatFileSnapshot, type RepeatFileWrites } from "./repeat-files.js";
+/** Run-scoped file holding the bounded set of calls that may still be answered from their original result. */
+export declare const REPEAT_GUARD_FILE = ".repeat-guard.json";
+/** Run-scoped, hash-chained audit journal of answered repeats. Separate from the run journal, whose head it keeps. */
+export declare const REPEAT_JOURNAL_DIRECTORY = "repeats";
+export declare const REPEAT_EVENT_TYPE = "call.repeated";
+/**
+ * Workspace-scoped directory lock serializing guarded calls across processes from record lookup through record
+ * publication. It does not depend on the selected run, so calls that change the selection are serialized too.
+ */
+export declare const REPEAT_LOCK_FILE = ".repeat-guard.lock";
+export declare const DEFAULT_REPEAT_LOCK_WAIT_MS = 30000;
+export declare const DEFAULT_REPEAT_WINDOW_MS: number;
+export declare const MAX_REPEAT_RECORDS = 16;
+export declare const MAX_REPEAT_RESULT_BYTES: number;
+export interface RepeatCall {
+    /** Stable operation name, for example the MCP tool name. */
+    operation: string;
+    /** Worktree that issued the call; compared in canonical form. */
+    workspace: string;
+    /** JSON arguments after input validation; undefined members are dropped and keys are sorted. */
+    arguments: unknown;
+}
+export interface RepeatStateInput {
+    selection: {
+        projectId: string;
+        runId: string;
+    };
+    projects: readonly string[];
+    runHash: string;
+    journalHead: string | null;
+    writer: string | null;
+    /**
+     * Content digest of the mutable files the run's operations read, such as staged work and generated source trees, from
+     * {@link repeatFilesDigest}.
+     */
+    files?: string | null;
+}
+/** The selected run a call applies to, with the state token that decides the repeat window. */
+export interface RepeatScope {
+    runDirectory: string;
+    projectId: ProjectId;
+    runId: RunId;
+    ownerEpoch: number;
+    state: string;
+    /**
+     * Content of the mutable files the state token covers, read with it. The snapshot taken before a call executes binds
+     * its record: the result is stored only if those trees still hold that content afterwards, changed only by the
+     * call's own {@link RepeatSafeHooks.writes}.
+     */
+    files?: RepeatFileSnapshot;
+}
+export interface RepeatSafeHooks<T> {
+    /**
+     * Machine-local workspace directory that holds the repeat lock, created when missing. While its parent does not exist
+     * there is no workspace state yet, and calls run unserialized.
+     */
+    lockDirectory: string;
+    /** Current selected run and state token, or undefined when no run is selected. */
+    scope(): Promise<RepeatScope | undefined>;
+    /** Ownership check for an answered repeat, such as the run writer lease. Must not write state. */
+    assertReplayAllowed(scope: RepeatScope): Promise<void>;
+    execute(): Promise<T>;
+    /** Optional instant after which the original result must not be returned, such as a task expiry. */
+    validUntil?(value: T): string | undefined;
+    /**
+     * Optional check that the call identity still holds, for example that a file bound by content was not modified since
+     * the identity was taken. Before a replay, false makes the call execute instead; after execution, false returns the
+     * result without storing it.
+     */
+    identityStable?(): Promise<boolean>;
+    /**
+     * Writes the operation makes to files the scope binds, filled while `execute` runs. Any other change to a bound file
+     * between the scope read before execution and the one after it returns the result without storing it.
+     */
+    writes?: RepeatFileWrites;
+}
+export interface RepeatSafeOptions {
+    clock?: () => Date;
+    idSource?: () => string;
+    windowMs?: number;
+    maxRecords?: number;
+    /** Longest wait for another guarded call in the workspace before failing with {@link RepeatGuardBusyError}. */
+    lockWaitMs?: number;
+    /** Cancels the call while it waits for the lock, and before lookup or execution once the lock is held. */
+    signal?: AbortSignal;
+}
+/** Another guarded call in the workspace is still running; the caller should refresh state and retry later. */
+/** The caller cancelled the call before it started; nothing was looked up, executed or recorded. */
+export declare class RepeatGuardCancelledError extends Error {
+    constructor();
+}
+export declare class RepeatGuardBusyError extends Error {
+    constructor();
+}
+/**
+ * The workspace changed while its lock holder waited without the lock, so a decision taken during the wait would apply
+ * to state it was not taken against. Nothing after the wait ran; the caller should refresh state and run again.
+ */
+export declare class RepeatGuardStaleError extends Error {
+    constructor();
+}
+/**
+ * A snapshot read reached a step that needs the workspace lock, such as finishing a pending recovery. Nothing was
+ * written; {@link withRepeatGuardReadLock} discards the attempt and waits for the lock instead.
+ */
+export declare class RepeatGuardSnapshotUnavailableError extends Error {
+    constructor();
+}
+/**
+ * A holder's share window could not be closed, so snapshot readers might still trust it. Every later atomic write and
+ * share in the holder's operation fails with this error, and so does the operation itself, even if it handled the
+ * error; releasing the lock then closes the window. The caller should run the operation again.
+ */
+export declare class RepeatGuardShareCloseError extends Error {
+    constructor(cause: unknown);
+}
+/** How {@link withRepeatGuardReadLock} runs a read: holding the workspace lock, or as a validated snapshot without it. */
+export type RepeatGuardReadMode = "locked" | "snapshot";
+/** The workspace lock as held by one {@link withRepeatGuardLock} operation. */
+export interface WorkspaceLockHold {
+    /**
+     * Gives the workspace lock up while `wait` runs, for example while a command waits for interactive input, then takes
+     * it again and throws {@link RepeatGuardStaleError} unless `state` returns the token it returned before the wait.
+     * When `state` fails before the wait the lock is kept, because an unchanged state could not be proven afterwards. A
+     * workspace created during the wait is locked from then on. Not reentrant: one suspension at a time.
+     */
+    suspend<R>(wait: () => Promise<R>, state: () => Promise<string>): Promise<R>;
+    /**
+     * Keeps the workspace lock while `operation` runs, for example a long provider, Git or Azure CLI process, but lets
+     * {@link withRepeatGuardReadLock} readers in other processes read the workspace meanwhile. The holder must not write
+     * workspace state until `operation` settles. Writers still wait. While this hold has no lock to share, because the
+     * workspace has no state yet or the hold is suspended, it runs `operation` without a share window.
+     * When the window cannot be closed afterwards it throws {@link RepeatGuardShareCloseError}, which also fences every
+     * later write of the holding operation.
+     */
+    share<R>(operation: () => Promise<R>): Promise<R>;
+}
+export interface RepeatSafeOutcome<T> {
+    value: T;
+    repeated: boolean;
+    fingerprint: string;
+}
+/** A stored result; the persisted file is the versioned `repeat-guard-records-v1` contract. */
+export type RepeatRecord = RepeatGuardRecordV1;
+/** Identifies a call independent of state: operation, canonical worktree and canonical arguments. */
+export declare function repeatCallHash(call: RepeatCall): string;
+/** Fingerprint of a call against the run state it applies to. */
+export declare function repeatFingerprint(callHash: string, state: string | null): string;
+/**
+ * State token for the repeat window. It changes whenever the selection, the project set, the selected run document,
+ * its journal head, its writer lease holder or the content of its mutable files changes; lease expiry renewals do not
+ * change it.
+ */
+export declare function repeatStateToken(input: RepeatStateInput): string;
+/**
+ * Reads the run's repeat records. An absent, unsafe or malformed file yields no records: losing a record only makes a
+ * repeat a new request that normal kernel checks decide, so corruption cannot replay a forged result.
+ */
+export declare function readRepeatRecords(runDirectory: string): Promise<RepeatRecord[]>;
+export declare function readRepeatEvents(runDirectory: string): Promise<EventV1[]>;
+/**
+ * Executes a state-changing call at most once per run state. An identical call (same operation, worktree and
+ * arguments) made while the selected run is unchanged since the original succeeded, and within the window, returns the
+ * original serialized result and appends a `call.repeated` audit event instead of executing again. Any intervening
+ * state change, an expired window, a failed original call or a missing record makes the call a new request. A result
+ * is stored only if the files the scope binds kept their content from the start of the call, changed only by the
+ * call's own writes, so a later repeat is never answered from a result computed on other content. Guarded
+ * calls in one workspace are serialized across processes from record lookup through record publication, including
+ * calls that create or change the selected run.
+ */
+export declare function executeRepeatSafe<T extends object>(call: RepeatCall, hooks: RepeatSafeHooks<T>, options?: RepeatSafeOptions): Promise<RepeatSafeOutcome<T>>;
+/**
+ * Runs `operation` while holding the workspace repeat lock in `lockDirectory`. Guarded calls take it, and so must every
+ * other writer of the same workspace (such as state-changing CLI commands), so that no write lands between a guarded
+ * call's state reads, execution and record publication. While the parent of `lockDirectory` does not exist there is no
+ * workspace state yet, and `operation` runs unserialized. The lock is not reentrant. `operation` may give the lock up
+ * while it waits, for example for interactive input, through {@link WorkspaceLockHold.suspend}; guarded calls never do.
+ */
+export declare function withRepeatGuardLock<T>(lockDirectory: string, operation: (hold: WorkspaceLockHold) => Promise<T>, options?: {
+    lockWaitMs?: number;
+    signal?: AbortSignal;
+}): Promise<T>;
+/**
+ * Runs a read that may need the workspace lock, for example to finish a pending recovery. It takes the lock like
+ * {@link withRepeatGuardLock} when the lock is free. While another process holds the lock but shares it through
+ * {@link WorkspaceLockHold.share}, `operation` runs in `snapshot` mode without the lock instead, and its outcome counts
+ * only if the holder kept the same share window open throughout, so the holder wrote nothing meanwhile. In `snapshot`
+ * mode `operation` must not write workspace state; it throws {@link RepeatGuardSnapshotUnavailableError} instead, and
+ * the read waits for the lock. Fails with {@link RepeatGuardBusyError} after `lockWaitMs` without either.
+ */
+export declare function withRepeatGuardReadLock<T>(lockDirectory: string, operation: (mode: RepeatGuardReadMode) => Promise<T>, options?: {
+    lockWaitMs?: number;
+    signal?: AbortSignal;
+}): Promise<T>;
+//# sourceMappingURL=repeat-guard.d.ts.map

package/dist/repeat-guard.d.ts.map

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