@codyswann/lisa 3.58.0 → 3.59.1

package/dist/configs/vitest/scratch-global-setup.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Upper bound on entries the namespace may hold once a run has torn down.
+ *
+ * A run allocates one root per process — the main process plus one per worker —
+ * and several runs share a workstation, so a healthy namespace legitimately
+ * holds tens of entries while work is in flight. This ceiling is not a tuning
+ * knob for that; it is the point past which the namespace is provably becoming
+ * the very thing it replaced.
+ */
+export declare const MAX_NAMESPACE_ENTRIES = 512;
+/** What an inspection of the namespace found. */
+export interface NamespaceResidue {
+    /** Entries whose owning process is gone but which were not removed */
+    readonly orphaned: readonly string[];
+    /** Entries that do not follow the run-root naming scheme at all */
+    readonly unrecognised: readonly string[];
+    /** Total entries present */
+    readonly total: number;
+}
+/**
+ * Classifies what is left in the namespace.
+ *
+ * `unrecognised` is the interesting bucket. The sweep identifies residue by
+ * parsing the owning pid out of a directory's name, so a change to that naming
+ * scheme does not break the sweep loudly — it makes the sweep silently match
+ * nothing while continuing to report success. Naming that case separately turns
+ * that regression into a failure instead of a slow leak.
+ * @param dir - Namespace directory to inspect
+ * @param alive - Liveness probe, overridable for tests
+ * @returns The classified residue.
+ */
+export declare const inspectNamespace: (dir?: string, alive?: (pid: number) => boolean) => NamespaceResidue;
+/**
+ * Builds the failure message for a namespace that is accumulating.
+ *
+ * Every branch names the directory and the offending entries, because the
+ * failure this replaces was a 60-second timeout that named nothing.
+ *
+ * `unrecognised` is deliberately NOT a failure. It was, and it wedged: one
+ * foreign directory in the namespace failed every subsequent run, forever, with
+ * a message a downstream user could not act on. Those entries are reclaimed on
+ * age by the sweep instead. What remains here are the two conditions that mean
+ * this fix itself has stopped working — residue the sweep should have taken and
+ * did not, and a namespace growing without bound.
+ * @param dir - Namespace directory inspected
+ * @param residue - What the inspection found
+ * @returns The message, or `undefined` when the namespace is healthy.
+ */
+export declare const describeResidueFailure: (dir: string, residue: NamespaceResidue) => string | undefined;
+/**
+ * Reclaims residue from previous runs, then refuses to start into a namespace
+ * that is accumulating.
+ * @throws When residue is present that the sweep cannot or did not reclaim.
+ */
+export declare const setup: () => void;
+/**
+ * Reclaims what this run allocated.
+ *
+ * This hook cannot fail a run — see the module header: Vitest swallows a throw
+ * from here. So it does the one thing it can do reliably, which is the cleanup;
+ * the judgement is made by {@link setup} on the next run, where a throw is
+ * actually honoured.
+ *
+ * The namespace directory itself is deliberately left in place. Creating a name
+ * inside a saturated shared temp root is the expensive operation this whole
+ * module exists to stop paying repeatedly; keeping one directory forever means
+ * the cost is paid once on a machine rather than once per run, and it is what
+ * makes "one entry in the shared temp root, ever" literally true rather than
+ * approximately true.
+ */
+export declare const teardown: () => void;
+//# sourceMappingURL=scratch-global-setup.d.ts.map

package/dist/configs/vitest/scratch-global-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch-global-setup.d.ts","sourceRoot":"","sources":["../../../src/configs/vitest/scratch-global-setup.ts"],"names":[],"mappings":"AA8CA;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAK,MAA8B,EACnC,QAAO,CAAC,GAAG,EAAE,MAAM,KAAK,OAAwB,KAC/C,gBAWF,CAAC;AAUF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,GACjC,KAAK,MAAM,EACX,SAAS,gBAAgB,KACxB,MAAM,GAAG,SAoBX,CAAC;AA2BF;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAO,IAYxB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,QAAO,IAE3B,CAAC"}

package/dist/configs/vitest/scratch-global-setup.js

@@ -0,0 +1,168 @@
+/**
+ * Vitest Configuration - Scratch namespace lifecycle (global setup)
+ *
+ * Runs once in the main Vitest process, on either side of the whole run.
+ *
+ * `setup` reclaims residue left by runs that were killed and then REFUSES TO
+ * START a run whose namespace is accumulating — the accumulation being the
+ * entire defect this exists to prevent, arriving one directory at a time.
+ * `teardown` reclaims what this run allocated.
+ *
+ * The check is deliberately a hard failure. A previous version of this problem
+ * was invisible for a working day because every instrument that met the
+ * saturated directory returned something a caller could mistake for an answer:
+ * an empty count, a dead process, a plausible duration. A guard that merely
+ * printed a warning would reproduce exactly that.
+ *
+ * It lives in `setup` for a measured reason, not an aesthetic one. Vitest
+ * SWALLOWS a throw from globalSetup teardown: it prints `error during close`
+ * and the process still exits 0. The same throw from `setup` exits 1. Measured
+ * both ways on vitest 4.1.9 rather than assumed —
+ *
+ * ```
+ * teardown throws -> Test Files 1 passed ... error during close ...   exit 0
+ * setup    throws -> Error: PROBE: setup refused to start the run     exit 1
+ * ```
+ *
+ * — because the first draft of this module put the check in `teardown`, where
+ * it reported a real overflow into a stream nothing gated on. A guard placed in
+ * a hook the runner ignores is the exact defect this file was written to stop,
+ * reproduced inside the guard itself.
+ *
+ * Checking at the start rather than the end costs nothing that matters: a run's
+ * own residue is reclaimed by the next run's sweep, and the next run's check
+ * sees whatever that sweep could not take. Accumulation is a trend, and a trend
+ * is still visible one run later.
+ * @see {@link module:configs/vitest/scratch} for the reclaim rules
+ * @module configs/vitest/scratch-global-setup
+ */
+import { isProcessAlive, parseRunRootName, readNamespaceEntries, scratchNamespaceDir, sweepScratchNamespace, } from "./scratch.js";
+/**
+ * Upper bound on entries the namespace may hold once a run has torn down.
+ *
+ * A run allocates one root per process — the main process plus one per worker —
+ * and several runs share a workstation, so a healthy namespace legitimately
+ * holds tens of entries while work is in flight. This ceiling is not a tuning
+ * knob for that; it is the point past which the namespace is provably becoming
+ * the very thing it replaced.
+ */
+export const MAX_NAMESPACE_ENTRIES = 512;
+/**
+ * Classifies what is left in the namespace.
+ *
+ * `unrecognised` is the interesting bucket. The sweep identifies residue by
+ * parsing the owning pid out of a directory's name, so a change to that naming
+ * scheme does not break the sweep loudly — it makes the sweep silently match
+ * nothing while continuing to report success. Naming that case separately turns
+ * that regression into a failure instead of a slow leak.
+ * @param dir - Namespace directory to inspect
+ * @param alive - Liveness probe, overridable for tests
+ * @returns The classified residue.
+ */
+export const inspectNamespace = (dir = scratchNamespaceDir(), alive = isProcessAlive) => {
+    const entries = readNamespaceEntries(dir);
+    return {
+        orphaned: entries.filter(name => {
+            const owner = parseRunRootName(name);
+            return owner !== undefined && !alive(owner.pid);
+        }),
+        unrecognised: entries.filter(name => parseRunRootName(name) === undefined),
+        total: entries.length,
+    };
+};
+/**
+ * Renders at most a handful of names for a failure message.
+ * @param names - Offending entry names
+ * @returns A comma-separated sample, elided beyond five.
+ */
+const sample = (names) => names.slice(0, 5).join(", ") + (names.length > 5 ? ", …" : "");
+/**
+ * Builds the failure message for a namespace that is accumulating.
+ *
+ * Every branch names the directory and the offending entries, because the
+ * failure this replaces was a 60-second timeout that named nothing.
+ *
+ * `unrecognised` is deliberately NOT a failure. It was, and it wedged: one
+ * foreign directory in the namespace failed every subsequent run, forever, with
+ * a message a downstream user could not act on. Those entries are reclaimed on
+ * age by the sweep instead. What remains here are the two conditions that mean
+ * this fix itself has stopped working — residue the sweep should have taken and
+ * did not, and a namespace growing without bound.
+ * @param dir - Namespace directory inspected
+ * @param residue - What the inspection found
+ * @returns The message, or `undefined` when the namespace is healthy.
+ */
+export const describeResidueFailure = (dir, residue) => {
+    if (residue.orphaned.length > 0) {
+        return (`Test scratch namespace ${dir} still holds ${String(residue.orphaned.length)} ` +
+            `root(s) whose owning process is gone, after a sweep that should have ` +
+            `removed them: ${sample(residue.orphaned)}. Reclaim-on-start is not ` +
+            `working, so a killed run's residue is now permanent.`);
+    }
+    if (residue.total > MAX_NAMESPACE_ENTRIES) {
+        return (`Test scratch namespace ${dir} holds ${String(residue.total)} entries, past ` +
+            `the ceiling of ${String(MAX_NAMESPACE_ENTRIES)}. Scratch space is ` +
+            `accumulating rather than being reclaimed — the condition this guard ` +
+            `exists to prevent.`);
+    }
+    return undefined;
+};
+/**
+ * Sweeps the namespace and reports what survived.
+ * @param dir - Namespace directory
+ * @returns The residue remaining after the sweep.
+ */
+const sweepThenInspect = (dir) => {
+    sweepScratchNamespace({ dir });
+    return inspectNamespace(dir);
+};
+/**
+ * Audits the namespace, tolerating a sibling run's worker exiting mid-audit.
+ *
+ * That worker's root becomes orphaned in the window between the sweep and the
+ * inspection, through no fault of this run. Sweeping once more before treating
+ * an orphan as a defect keeps a guard built to catch a permanent leak from
+ * failing on a transient one.
+ * @param dir - Namespace directory
+ * @returns The residue to judge.
+ */
+const auditNamespace = (dir) => {
+    const first = sweepThenInspect(dir);
+    return first.orphaned.length > 0 ? sweepThenInspect(dir) : first;
+};
+/**
+ * Reclaims residue from previous runs, then refuses to start into a namespace
+ * that is accumulating.
+ * @throws When residue is present that the sweep cannot or did not reclaim.
+ */
+export const setup = () => {
+    // The namespace directory is not created here. `createRunRoot` makes it
+    // recursively in whichever worker allocates first, and both the sweep and the
+    // inspection treat an absent namespace as an empty one — so creating it would
+    // be a side effect ahead of the audit that buys nothing.
+    const dir = scratchNamespaceDir();
+    const residue = auditNamespace(dir);
+    const failure = describeResidueFailure(dir, residue);
+    if (failure !== undefined) {
+        throw new Error(failure);
+    }
+};
+/**
+ * Reclaims what this run allocated.
+ *
+ * This hook cannot fail a run — see the module header: Vitest swallows a throw
+ * from here. So it does the one thing it can do reliably, which is the cleanup;
+ * the judgement is made by {@link setup} on the next run, where a throw is
+ * actually honoured.
+ *
+ * The namespace directory itself is deliberately left in place. Creating a name
+ * inside a saturated shared temp root is the expensive operation this whole
+ * module exists to stop paying repeatedly; keeping one directory forever means
+ * the cost is paid once on a machine rather than once per run, and it is what
+ * makes "one entry in the shared temp root, ever" literally true rather than
+ * approximately true.
+ */
+export const teardown = () => {
+    sweepScratchNamespace({ dir: scratchNamespaceDir() });
+};
+//# sourceMappingURL=scratch-global-setup.js.map

package/dist/configs/vitest/scratch-global-setup.js.map

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

package/dist/configs/vitest/scratch-setup.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Points this process's temp directory at a run root it owns, creating the root
+ * on first call and reusing it afterwards.
+ *
+ * All three of `TMPDIR`, `TMP` and `TEMP` are set: Node reads `TMPDIR` on POSIX
+ * and `TEMP`/`TMP` on Windows, and non-Node tools spawned by fixtures read
+ * whichever their platform prefers. Setting one would leave the others pointing
+ * at the shared directory for exactly the callers hardest to see.
+ * @returns Absolute path of this process's run root.
+ */
+export declare const installScratchRoot: () => string;
+//# sourceMappingURL=scratch-setup.d.ts.map

package/dist/configs/vitest/scratch-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch-setup.d.ts","sourceRoot":"","sources":["../../../src/configs/vitest/scratch-setup.ts"],"names":[],"mappings":"AAgDA;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAO,MA4BrC,CAAC"}

package/dist/configs/vitest/scratch-setup.js

@@ -0,0 +1,70 @@
+/**
+ * Vitest Configuration - Per-process scratch redirection (setup file)
+ *
+ * Wired as a Vitest `setupFiles` entry, so it executes inside every test worker
+ * before any test file runs. It points `os.tmpdir()` at a run root this process
+ * owns, which relocates EVERY `mkdtemp(os.tmpdir())` call in the suite without
+ * editing a single test — in Lisa's own suite, 481 call sites across 211 files.
+ *
+ * `os.tmpdir()` re-reads the environment on every call rather than caching it at
+ * startup, which is the seam this relies on:
+ *
+ * ```
+ * $ node -e 'const os=require("os"); console.log(os.tmpdir());
+ *            process.env.TMPDIR="/tmp/probe"; console.log(os.tmpdir())'
+ * /var/folders/<...>/T
+ * /tmp/probe
+ * ```
+ *
+ * Because the assignment mutates the process environment, subprocesses the
+ * tests spawn inherit the redirection too — a fixture's `git`, `npm pack` or
+ * `tsc` child writes into the same bounded root, so a child that outlives its
+ * test cannot leak into the shared directory either.
+ *
+ * The work is done once per process, not once per test file, even though Vitest
+ * re-executes setup files for each file.
+ * @see {@link module:configs/vitest/scratch} for why the root is shaped this way
+ * @module configs/vitest/scratch-setup
+ */
+import * as fs from "node:fs";
+import { env } from "node:process";
+import { SCRATCH_ROOT_ENV, reclaimAndCreateRunRoot, removeScratchDir, scratchBaseDir, scratchNamespaceDir, } from "./scratch.js";
+/** Key under which the per-process run root is memoised. */
+const RUN_ROOT_KEY = "__lisaScratchRunRoot__";
+/**
+ * Points this process's temp directory at a run root it owns, creating the root
+ * on first call and reusing it afterwards.
+ *
+ * All three of `TMPDIR`, `TMP` and `TEMP` are set: Node reads `TMPDIR` on POSIX
+ * and `TEMP`/`TMP` on Windows, and non-Node tools spawned by fixtures read
+ * whichever their platform prefers. Setting one would leave the others pointing
+ * at the shared directory for exactly the callers hardest to see.
+ * @returns Absolute path of this process's run root.
+ */
+export const installScratchRoot = () => {
+    const scope = globalThis;
+    const existing = scope[RUN_ROOT_KEY];
+    if (existing !== undefined && fs.existsSync(existing)) {
+        return existing;
+    }
+    // Read before the redirection lands: `scratchNamespaceDir()` derives from
+    // `os.tmpdir()`, so once TMPDIR moves, a later call in this process — or in a
+    // child that inherits the environment — would otherwise compute a namespace
+    // NESTED INSIDE the run root and sweep the wrong directory. Recording the
+    // base makes the resolution idempotent under its own side effect.
+    const base = scratchBaseDir();
+    const root = reclaimAndCreateRunRoot(scratchNamespaceDir());
+    scope[RUN_ROOT_KEY] = root;
+    env[SCRATCH_ROOT_ENV] = base;
+    env["TMPDIR"] = root;
+    env["TMP"] = root;
+    env["TEMP"] = root;
+    // Covers an ordinary exit, including one where tests failed. A signalled exit
+    // does not run this — nothing can — and is handled by the next run's sweep.
+    process.once("exit", () => {
+        removeScratchDir(root);
+    });
+    return root;
+};
+installScratchRoot();
+//# sourceMappingURL=scratch-setup.js.map

package/dist/configs/vitest/scratch-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch-setup.js","sourceRoot":"","sources":["../../../src/configs/vitest/scratch-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,4DAA4D;AAC5D,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAQ9C;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAW,EAAE;IAC7C,MAAM,KAAK,GAAG,UAA2B,CAAC;IAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;IACrC,IAAI,QAAQ,KAAK,SAAS,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,0EAA0E;IAC1E,8EAA8E;IAC9E,4EAA4E;IAC5E,0EAA0E;IAC1E,kEAAkE;IAClE,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,uBAAuB,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAE5D,KAAK,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;IAC3B,GAAG,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC;IAC7B,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACrB,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAClB,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAEnB,8EAA8E;IAC9E,4EAA4E;IAC5E,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;QACxB,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,kBAAkB,EAAE,CAAC"}

package/dist/configs/vitest/scratch.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Single directory name every Lisa scratch root nests under.
+ *
+ * The name is the contract: it is what makes "one entry in the shared temp
+ * root, ever" checkable, and what the sweep enumerates instead of the
+ * (unenumerable) platform root.
+ */
+export declare const SCRATCH_NAMESPACE = "lisa-scratch";
+/** Prefix identifying a per-process run root inside the namespace. */
+export declare const RUN_ROOT_PREFIX = "run-";
+/**
+ * Backstop age after which a run root is reclaimed even though its recorded pid
+ * still resolves to a live process.
+ *
+ * Pids are recycled, so liveness alone can pin an abandoned root forever if an
+ * unrelated process happens to inherit its number. Six hours is longer than any
+ * legitimate suite and short enough that a recycled pid cannot hold a root
+ * across a working day.
+ */
+export declare const DEFAULT_RECLAIM_AGE_MS: number;
+/** Environment variable that relocates the namespace away from the platform temp root. */
+export declare const SCRATCH_ROOT_ENV = "LISA_TEST_SCRATCH_ROOT";
+/**
+ * Resolves the directory the namespace lives in.
+ *
+ * Honours `LISA_TEST_SCRATCH_ROOT` first so an operator or CI job can point
+ * scratch space at a specific volume, then `os.tmpdir()` — which itself re-reads
+ * `TMPDIR` on every call, so the pre-existing `export TMPDIR=...` mitigation
+ * composes with this rather than being defeated by it.
+ * @returns Absolute path to the directory containing the scratch namespace.
+ */
+export declare const scratchBaseDir: () => string;
+/**
+ * Absolute path of the shared namespace directory.
+ * @returns Path to `<base>/lisa-scratch`.
+ */
+export declare const scratchNamespaceDir: () => string;
+/**
+ * Builds the name of a per-process run root.
+ *
+ * The pid is encoded in the name because it is the only durable record of who
+ * owns the directory: a killed process leaves no other trace, and the sweep has
+ * to tell an abandoned root from one a sibling run is using right now.
+ * @param pid - Owning process id
+ * @param startedAt - Epoch milliseconds the root was created
+ * @param suffix - Random suffix disambiguating two roots created in the same millisecond
+ * @returns The directory name, without any leading path.
+ */
+export declare const runRootName: (pid: number, startedAt: number, suffix: string) => string;
+/** Ownership recorded in a run root's directory name. */
+export interface RunRootOwner {
+    /** Process id that created the root */
+    readonly pid: number;
+    /** Epoch milliseconds the root was created */
+    readonly startedAt: number;
+}
+/**
+ * Recovers the pid and creation time encoded in a run root's name.
+ * @param name - A directory name from inside the namespace
+ * @returns The owner, or `undefined` when the name was not produced by {@link runRootName}.
+ */
+export declare const parseRunRootName: (name: string) => RunRootOwner | undefined;
+/** Inputs deciding whether one namespace entry may be removed. */
+export interface ReclaimDecisionInput {
+    /** Directory name inside the namespace */
+    readonly name: string;
+    /** Current epoch milliseconds */
+    readonly now: number;
+    /** Reports whether a pid still resolves to a running process */
+    readonly isProcessAlive: (pid: number) => boolean;
+    /** Age after which a live-pid root is reclaimed anyway */
+    readonly maxAgeMs?: number;
+    /** Name of the caller's own root, which is never reclaimed */
+    readonly selfName?: string;
+}
+/**
+ * Decides whether a namespace entry is abandoned residue.
+ *
+ * A name this module did not produce is not judged here — see
+ * {@link isStaleForeignEntry}, which reclaims it on age alone. Deleting another
+ * tool's fresh data is not this sweep's business; leaving it forever would let
+ * one stray directory wedge every future run.
+ * @param input - The entry and the facts needed to judge it
+ * @param input.name - Directory name inside the namespace
+ * @param input.now - Current epoch milliseconds
+ * @param input.isProcessAlive - Liveness probe for the recorded pid
+ * @param input.maxAgeMs - Age after which a live-pid root is reclaimed anyway
+ * @param input.selfName - Caller's own root name, never reclaimed
+ * @returns True when the entry may be removed.
+ */
+export declare const isReclaimable: ({ name, now, isProcessAlive, maxAgeMs, selfName, }: ReclaimDecisionInput) => boolean;
+/**
+ * Reports whether a pid resolves to a running process.
+ *
+ * `kill(pid, 0)` sends no signal; it only asks the kernel whether the target
+ * exists. `EPERM` means it exists and belongs to someone else, which still
+ * counts as alive.
+ * @param pid - Process id to probe
+ * @returns True when a process with that id exists.
+ */
+export declare const isProcessAlive: (pid: number) => boolean;
+/**
+ * Decides whether an entry this module did not create may be removed.
+ *
+ * Age is the only signal available: a foreign name carries no owner, so there is
+ * nothing to ask the kernel about. Reclaiming on the same backstop the pid arm
+ * uses means the namespace self-heals from anything parked in it — an older
+ * release's naming scheme, a stray `mktemp` — without this sweep ever deleting
+ * something a live tool is still writing to.
+ *
+ * The alternative was to treat a foreign name as a hard failure. That was tried
+ * and rejected: it wedges permanently on one stray directory, and the message a
+ * downstream user gets — "run roots must be named by runRootName()" — names
+ * something they cannot act on.
+ * @param entryPath - Absolute path of the entry
+ * @param now - Current epoch milliseconds
+ * @param maxAgeMs - Age past which a foreign entry is reclaimed
+ * @returns True when the entry is old enough to remove.
+ */
+export declare const isStaleForeignEntry: (entryPath: string, now: number, maxAgeMs: number) => boolean;
+/**
+ * Lists the namespace's direct children, treating an absent namespace as empty.
+ *
+ * A directory that cannot be read is not a directory that is empty — but for the
+ * one case that occurs here, the namespace not existing yet, the two are the
+ * same answer and every caller wants to continue rather than fail.
+ * @param dir - Namespace directory to list
+ * @returns The entry names, or an empty list.
+ */
+export declare const readNamespaceEntries: (dir: string) => readonly string[];
+/** Outcome of one sweep of the namespace. */
+export interface SweepResult {
+    /** Names removed as abandoned residue */
+    readonly removed: readonly string[];
+    /** Names left in place because a live owner still holds them */
+    readonly kept: readonly string[];
+}
+/** Options controlling one sweep. */
+export interface SweepOptions {
+    /** Namespace directory to sweep (defaults to the resolved namespace) */
+    readonly dir?: string;
+    /** Current epoch milliseconds */
+    readonly now?: number;
+    /** Liveness probe, overridable for tests */
+    readonly isProcessAlive?: (pid: number) => boolean;
+    /** Age after which a live-pid root is reclaimed anyway */
+    readonly maxAgeMs?: number;
+    /** Caller's own root name, never reclaimed */
+    readonly selfName?: string;
+}
+/**
+ * Removes abandoned run roots from the namespace.
+ *
+ * This is the arm of the design that survives a kill. It runs at the START of a
+ * run precisely because the run that leaked cannot be the one to clean up.
+ * @param options - Sweep inputs
+ * @param options.dir - Namespace directory to sweep
+ * @param options.now - Current epoch milliseconds
+ * @param options.isProcessAlive - Liveness probe for recorded pids
+ * @param options.maxAgeMs - Age after which a live-pid root is reclaimed anyway
+ * @param options.selfName - Caller's own root name, never reclaimed
+ * @returns Which entries were removed and which were kept.
+ */
+export declare const sweepScratchNamespace: ({ dir, now, isProcessAlive: alive, maxAgeMs, selfName, }?: SweepOptions) => SweepResult;
+/**
+ * Creates a run root owned by the current process and returns its path.
+ * @param options - Overrides for the namespace directory and clock
+ * @param options.dir - Namespace directory to create the root inside
+ * @param options.now - Epoch milliseconds recorded in the root's name
+ * @returns Absolute path of this process's run root.
+ */
+export declare const createRunRoot: ({ dir, now, }?: {
+    readonly dir?: string;
+    readonly now?: number;
+}) => string;
+/**
+ * Reclaims abandoned roots, then allocates one for this process.
+ *
+ * The order is the point, and it is why this is one function rather than two
+ * calls at the call site: reclaiming AFTER allocating leaves a window in which
+ * the namespace holds both, and reclaiming somewhere else entirely is how a
+ * caller ends up allocating without ever reclaiming at all.
+ * @param dir - Namespace directory
+ * @returns Absolute path of the newly created run root.
+ */
+export declare const reclaimAndCreateRunRoot: (dir: string) => string;
+/**
+ * Removes a directory tree, ignoring an already-absent path.
+ * @param dir - Directory to remove
+ */
+export declare const removeScratchDir: (dir: string) => void;
+//# sourceMappingURL=scratch.d.ts.map

package/dist/configs/vitest/scratch.d.ts.map

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