@codyswann/lisa 4.48.0 → 4.49.0

package/dist/configs/vitest/fleet-admission.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Environment variable that switches admission off entirely.
+ *
+ * The value `off` disables the wait; anything else leaves it armed. This
+ * matches the escape hatch `LISA_VITEST_MAX_WORKERS` already provides and the
+ * reason given for it — a cap nobody can lift is a cap that gets worked around
+ * by deleting it. This is a load control, not a safety guard, and the two want
+ * opposite answers about overrides.
+ */
+export declare const FLEET_ADMISSION_VAR = "LISA_FLEET_ADMISSION";
+/** Value of {@link FLEET_ADMISSION_VAR} that disables the wait. */
+export declare const FLEET_ADMISSION_OFF = "off";
+/** Environment variable overriding how long a run may wait for a slot. */
+export declare const FLEET_ADMISSION_DEADLINE_VAR = "LISA_FLEET_ADMISSION_DEADLINE_MS";
+/**
+ * How long a run waits for a slot before starting anyway.
+ *
+ * Two minutes is long enough for a typical unit suite ahead of it to finish and
+ * short enough that a stuck older run cannot look like a hang. It is not a
+ * measured optimum and is overridable; what matters is that it is finite.
+ */
+export declare const DEFAULT_ADMISSION_DEADLINE_MS = 120000;
+/** How often a waiting run re-reads the namespace. */
+export declare const ADMISSION_POLL_MS = 2000;
+/** One live run root, as the namespace names it. */
+export interface FleetRunRoot {
+    /** The directory basename, which is the run's identity. */
+    readonly basename: string;
+    /** Owning process id. */
+    readonly pid: number;
+    /** Epoch milliseconds at which the root was created. */
+    readonly startedAt: number;
+}
+/** What admission decided, and why. */
+export type AdmissionDecision = "admit-alone" | "admit-within-capacity" | "admit-unranked" | "admit-disabled" | "admit-deadline-expired" | "wait";
+/** One admission verdict, with the sentence an operator reads. */
+export interface AdmissionVerdict {
+    /** What was decided. */
+    readonly decision: AdmissionDecision;
+    /** Whether the run may execute now. */
+    readonly admitted: boolean;
+    /** Operator-readable single line, or empty when there is nothing to say. */
+    readonly notice: string;
+}
+/**
+ * How many runs may execute workers at once before demand exceeds the machine.
+ *
+ * The bound is the same one the divisor layer starts from — half the cores —
+ * divided by the smallest pool a run may be given. Below that, admitting
+ * another run necessarily pushes total demand past the machine, because every
+ * admitted run is entitled to {@link MIN_FLEET_WORKERS}.
+ *
+ * Never zero. A machine too small to host one run at the minimum still has to
+ * run its tests, and a capacity of zero would refuse every run on every
+ * two-core CI runner.
+ * @param cores - Logical cores available.
+ * @returns The number of runs that may execute concurrently, at least one.
+ */
+export declare function fleetCapacity(cores: number): number;
+/**
+ * Total workers the fleet demands once admission is enforced.
+ *
+ * The property #3941 asks for, expressed as a number a test can check at any
+ * fleet size. Pool sizing alone cannot satisfy it: `fleetShare(cores, fleet) *
+ * fleet` grows without bound in `fleet`, because the share stops falling at the
+ * floor. Capping the count of runs that execute is what makes the product stop
+ * growing.
+ * @param fleet - How many runs want to execute.
+ * @param cores - Logical cores available.
+ * @returns Workers demanded by the runs actually executing.
+ */
+export declare function admittedWorkerDemand(fleet: number, cores: number): number;
+/**
+ * Where a run stands in the queue, oldest first.
+ *
+ * Ordered by creation time, then by pid, then by basename — a total order over
+ * facts every run reads identically, so two runs never both believe they hold
+ * the same slot. Ties on the millisecond are real: several lanes launched
+ * together routinely share a timestamp.
+ * @param roots - Live run roots read from the namespace.
+ * @param selfBasename - This run's own root basename, if it has one.
+ * @returns The zero-based position, or undefined when this run is not among them.
+ */
+export declare function admissionRank(roots: readonly FleetRunRoot[], selfBasename: string | undefined): number | undefined;
+/**
+ * Parse the run roots out of one namespace listing.
+ * @param names - Directory basenames, already bounded by the caller.
+ * @returns The entries that are run roots, in the order given.
+ */
+export declare function readFleetRunRoots(names: readonly string[]): readonly FleetRunRoot[];
+/**
+ * Read the admission deadline an operator stated, or the default.
+ * @param environment - Environment to read.
+ * @returns Milliseconds a run may wait before starting anyway.
+ */
+export declare function admissionDeadlineMs(environment?: NodeJS.ProcessEnv): number;
+/**
+ * Whether admission is armed at all.
+ * @param environment - Environment to read.
+ * @returns Whether the wait should be attempted.
+ */
+export declare function admissionEnabled(environment?: NodeJS.ProcessEnv): boolean;
+/** Everything one admission decision is made from. */
+export interface AdmissionInput {
+    /** This run's queue position, or undefined when it has none. */
+    readonly rank: number | undefined;
+    /** How many runs may execute at once. */
+    readonly capacity: number;
+    /** How many live runs were observed, including this one. */
+    readonly liveRuns: number;
+    /** Milliseconds spent waiting so far. */
+    readonly elapsedMs: number;
+    /** Milliseconds this run may wait in total. */
+    readonly deadlineMs: number;
+    /** Whether admission is armed. */
+    readonly enabled: boolean;
+}
+/**
+ * Decide whether this run may execute now, and say so in one line.
+ *
+ * The order of the branches is the order of confidence. Anything this cannot
+ * measure admits before anything it can measure is consulted, so a defect in
+ * the ranking can only make the control weaker, never make it refuse a run it
+ * should have allowed.
+ * @param input - The facts the decision is made from.
+ * @returns The verdict and its operator-readable notice.
+ */
+export declare function admissionVerdict(input: AdmissionInput): AdmissionVerdict;
+//# sourceMappingURL=fleet-admission.d.ts.map

package/dist/configs/vitest/fleet-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-admission.d.ts","sourceRoot":"","sources":["../../../src/configs/vitest/fleet-admission.ts"],"names":[],"mappings":"AAmEA;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC,0EAA0E;AAC1E,eAAO,MAAM,4BAA4B,qCAAqC,CAAC;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAErD,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AAEvC,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yBAAyB;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,uCAAuC;AACvC,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,uBAAuB,GACvB,gBAAgB,GAChB,gBAAgB,GAChB,wBAAwB,GACxB,MAAM,CAAC;AAEX,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAcpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,SAAS,YAAY,EAAE,CAOzB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,GAAE,MAAM,CAAC,UAAgB,GACnC,MAAM,CAOR;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,GAAE,MAAM,CAAC,UAAgB,GACnC,OAAO,CAET;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB,CAsBxE"}

package/dist/configs/vitest/fleet-admission.js

@@ -0,0 +1,239 @@
+/**
+ * Admission control for the fleet's test runs.
+ *
+ * ## The gap this fills
+ *
+ * `resolveMaxWorkers` has three layers and all three size a *pool*. None of
+ * them decides whether a run may start. Past the point where the divisor
+ * saturates that distinction becomes the whole problem: on eighteen cores
+ * `floor(cores / 2 / fleet)` clamps to {@link MIN_FLEET_WORKERS} from a fleet of
+ * five upward, so fleets of 5, 13, 20 and 50 all resolve to two workers each and
+ * the fleet's TOTAL demand is `2 x fleet` — 26 workers at thirteen runs, 100 at
+ * fifty, on a machine with eighteen cores. The layer's own docstring says it
+ * bounds the fleet "rather than multiplied by its own size"; past four runs it
+ * multiplies (CodySwannGT/lisa#3941).
+ *
+ * The arithmetic is not a bug in the divisor. **With a per-run floor that may
+ * not be lowered, no pool-sizing rule can bound a sum over an unbounded number
+ * of runs.** Bounding it requires deciding that some run does not execute yet.
+ * That decision is what this module is.
+ *
+ * ## Why the floor is not the lever
+ *
+ * {@link MIN_FLEET_WORKERS} is measured and deliberately out of scope. One
+ * worker serialises a suite, so every file waits behind every other file and
+ * per-test budgets expire even as machine load falls — the recorded 124-timeouts
+ * -against-54 result. Lowering it trades a visible failure for a subtler one,
+ * which is the move this module exists to avoid rather than to make.
+ *
+ * ## The rule, and why it cannot deadlock
+ *
+ * Every supervised run registers a `run-<pid>-<startedAt>-<suffix>` root before
+ * its payload starts. A run admits itself when its own root is among the
+ * {@link fleetCapacity} OLDEST live roots. That is a total order on facts each
+ * run can read for itself: no lock, no leader, no coordinator, and no message
+ * anybody has to receive. At least `capacity` runs always satisfy it, so the
+ * fleet always makes progress, and a waiting run's rank improves for free as
+ * older runs finish and their roots disappear.
+ *
+ * Ranking by age rather than by, say, pid also makes the queue fair in the one
+ * direction that matters: the run that has been waiting longest goes first, so
+ * nothing starves.
+ *
+ * ## Every unknown admits
+ *
+ * This runs before a single test does, so a mistake here does not degrade a run,
+ * it prevents one. Unranked (the run registered no root, or is unsupervised), an
+ * unreadable namespace, a capacity of zero, a disabled switch, an expired
+ * deadline — all admit. The control bounds demand when it can see the fleet and
+ * gets out of the way when it cannot. It is deliberately NOT fail-closed:
+ * refusing to run on missing information would turn a load control into a
+ * correctness signal, and a red gate reads exactly like a regression.
+ *
+ * ## Why the deadline exists
+ *
+ * A run that waits forever is worse than an overloaded machine. The agent
+ * watching it sees a hang, kills it, and retries — which is the cascade the cap
+ * exists to stop, arriving through the control rather than around it. So the
+ * wait is bounded, and expiry admits with a notice rather than refusing. Past
+ * the deadline the behaviour degrades exactly to what shipped before this
+ * module, loudly.
+ * @module configs/vitest/fleet-admission
+ */
+import { env } from "node:process";
+import { MIN_FLEET_WORKERS, fleetShare } from "./base.js";
+import { parseScratchRunRootName } from "./scratch-owner.js";
+/**
+ * Environment variable that switches admission off entirely.
+ *
+ * The value `off` disables the wait; anything else leaves it armed. This
+ * matches the escape hatch `LISA_VITEST_MAX_WORKERS` already provides and the
+ * reason given for it — a cap nobody can lift is a cap that gets worked around
+ * by deleting it. This is a load control, not a safety guard, and the two want
+ * opposite answers about overrides.
+ */
+export const FLEET_ADMISSION_VAR = "LISA_FLEET_ADMISSION";
+/** Value of {@link FLEET_ADMISSION_VAR} that disables the wait. */
+export const FLEET_ADMISSION_OFF = "off";
+/** Environment variable overriding how long a run may wait for a slot. */
+export const FLEET_ADMISSION_DEADLINE_VAR = "LISA_FLEET_ADMISSION_DEADLINE_MS";
+/**
+ * How long a run waits for a slot before starting anyway.
+ *
+ * Two minutes is long enough for a typical unit suite ahead of it to finish and
+ * short enough that a stuck older run cannot look like a hang. It is not a
+ * measured optimum and is overridable; what matters is that it is finite.
+ */
+export const DEFAULT_ADMISSION_DEADLINE_MS = 120_000;
+/** How often a waiting run re-reads the namespace. */
+export const ADMISSION_POLL_MS = 2_000;
+/**
+ * How many runs may execute workers at once before demand exceeds the machine.
+ *
+ * The bound is the same one the divisor layer starts from — half the cores —
+ * divided by the smallest pool a run may be given. Below that, admitting
+ * another run necessarily pushes total demand past the machine, because every
+ * admitted run is entitled to {@link MIN_FLEET_WORKERS}.
+ *
+ * Never zero. A machine too small to host one run at the minimum still has to
+ * run its tests, and a capacity of zero would refuse every run on every
+ * two-core CI runner.
+ * @param cores - Logical cores available.
+ * @returns The number of runs that may execute concurrently, at least one.
+ */
+export function fleetCapacity(cores) {
+    return Math.max(1, Math.floor(cores / 2 / MIN_FLEET_WORKERS));
+}
+/**
+ * Total workers the fleet demands once admission is enforced.
+ *
+ * The property #3941 asks for, expressed as a number a test can check at any
+ * fleet size. Pool sizing alone cannot satisfy it: `fleetShare(cores, fleet) *
+ * fleet` grows without bound in `fleet`, because the share stops falling at the
+ * floor. Capping the count of runs that execute is what makes the product stop
+ * growing.
+ * @param fleet - How many runs want to execute.
+ * @param cores - Logical cores available.
+ * @returns Workers demanded by the runs actually executing.
+ */
+export function admittedWorkerDemand(fleet, cores) {
+    const wanted = Math.max(1, Math.floor(fleet));
+    const admitted = Math.min(wanted, fleetCapacity(cores));
+    return admitted * fleetShare(cores, wanted);
+}
+/**
+ * Where a run stands in the queue, oldest first.
+ *
+ * Ordered by creation time, then by pid, then by basename — a total order over
+ * facts every run reads identically, so two runs never both believe they hold
+ * the same slot. Ties on the millisecond are real: several lanes launched
+ * together routinely share a timestamp.
+ * @param roots - Live run roots read from the namespace.
+ * @param selfBasename - This run's own root basename, if it has one.
+ * @returns The zero-based position, or undefined when this run is not among them.
+ */
+export function admissionRank(roots, selfBasename) {
+    if (selfBasename === undefined)
+        return undefined;
+    const ordered = [...roots].sort((left, right) => left.startedAt - right.startedAt ||
+        left.pid - right.pid ||
+        (left.basename < right.basename
+            ? -1
+            : left.basename > right.basename
+                ? 1
+                : 0));
+    const position = ordered.findIndex(root => root.basename === selfBasename);
+    return position === -1 ? undefined : position;
+}
+/**
+ * Parse the run roots out of one namespace listing.
+ * @param names - Directory basenames, already bounded by the caller.
+ * @returns The entries that are run roots, in the order given.
+ */
+export function readFleetRunRoots(names) {
+    return names.flatMap(basename => {
+        const owner = parseScratchRunRootName(basename);
+        return owner === undefined
+            ? []
+            : [{ basename, pid: owner.pid, startedAt: owner.startedAt }];
+    });
+}
+/**
+ * Read the admission deadline an operator stated, or the default.
+ * @param environment - Environment to read.
+ * @returns Milliseconds a run may wait before starting anyway.
+ */
+export function admissionDeadlineMs(environment = env) {
+    const raw = environment[FLEET_ADMISSION_DEADLINE_VAR]?.trim();
+    if (raw === undefined || !/^\d+$/u.test(raw)) {
+        return DEFAULT_ADMISSION_DEADLINE_MS;
+    }
+    const value = Number(raw);
+    return value > 0 ? value : DEFAULT_ADMISSION_DEADLINE_MS;
+}
+/**
+ * Whether admission is armed at all.
+ * @param environment - Environment to read.
+ * @returns Whether the wait should be attempted.
+ */
+export function admissionEnabled(environment = env) {
+    return environment[FLEET_ADMISSION_VAR]?.trim() !== FLEET_ADMISSION_OFF;
+}
+/**
+ * Decide whether this run may execute now, and say so in one line.
+ *
+ * The order of the branches is the order of confidence. Anything this cannot
+ * measure admits before anything it can measure is consulted, so a defect in
+ * the ranking can only make the control weaker, never make it refuse a run it
+ * should have allowed.
+ * @param input - The facts the decision is made from.
+ * @returns The verdict and its operator-readable notice.
+ */
+export function admissionVerdict(input) {
+    if (!input.enabled) {
+        return { decision: "admit-disabled", admitted: true, notice: "" };
+    }
+    if (input.rank === undefined) {
+        return { decision: "admit-unranked", admitted: true, notice: "" };
+    }
+    if (input.rank < input.capacity) {
+        return {
+            decision: input.liveRuns <= 1 ? "admit-alone" : "admit-within-capacity",
+            admitted: true,
+            notice: "",
+        };
+    }
+    if (input.elapsedMs >= input.deadlineMs) {
+        return {
+            decision: "admit-deadline-expired",
+            admitted: true,
+            notice: overCapacityNotice(input),
+        };
+    }
+    return { decision: "wait", admitted: false, notice: waitingNotice(input) };
+}
+/**
+ * The line a run prints while it is waiting for a slot.
+ * @param input - The facts the decision was made from.
+ * @returns One operator-readable line.
+ */
+function waitingNotice(input) {
+    return (`lisa fleet admission: waiting for a worker slot — ` +
+        `${String(input.liveRuns)} run(s) live, this run is #${String((input.rank ?? 0) + 1)}, ` +
+        `${String(input.capacity)} may execute at once. ` +
+        `Starting anyway in ${String(Math.max(0, Math.ceil((input.deadlineMs - input.elapsedMs) / 1000)))}s. ` +
+        `Set ${FLEET_ADMISSION_VAR}=${FLEET_ADMISSION_OFF} to disable this wait.`);
+}
+/**
+ * The line a run prints when it starts despite being over capacity.
+ * @param input - The facts the decision was made from.
+ * @returns One operator-readable line.
+ */
+function overCapacityNotice(input) {
+    return (`lisa fleet admission: starting OVER CAPACITY after ` +
+        `${String(Math.round(input.elapsedMs / 1000))}s — ` +
+        `${String(input.liveRuns)} run(s) live, this run is #${String((input.rank ?? 0) + 1)}, ` +
+        `${String(input.capacity)} may execute at once. ` +
+        `The machine is oversubscribed; expect timeouts rather than failures.`);
+}
+//# sourceMappingURL=fleet-admission.js.map

package/dist/configs/vitest/fleet-admission.js.map

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

package/dist/configs/vitest/synthesis-scratch-reclaim.d.ts

@@ -0,0 +1,86 @@
+/** Prefix CDK uses for a `mkdtemp` cloud-assembly directory. */
+export declare const SYNTHESIS_PREFIX = "cdk.out";
+/** File CDK writes when an assembly completes. */
+export declare const COMPLETION_MANIFEST = "manifest.json";
+/** How long an assembly must be untouched before completion authorizes removal. */
+export declare const DEFAULT_QUIESCENCE_MS: number;
+/** Why one entry was placed in its bucket. */
+export type ReclaimDisposition = "reclaimable" | "live" | "undetermined";
+/** Facts read from one candidate, separated from the judgement about them. */
+export interface SynthesisEntryFacts {
+    /** Direct child basename. */
+    readonly name: string;
+    /** Whether the candidate is a real directory rather than a link or file. */
+    readonly directory: boolean;
+    /** Whether the candidate's children could be listed. */
+    readonly readable: boolean;
+    /** Whether the completion manifest is present. */
+    readonly complete: boolean;
+    /** Milliseconds since the candidate was last modified. */
+    readonly ageMs: number;
+}
+/** One entry's bucket, with the reason stated for an operator. */
+export interface SynthesisEntryVerdict {
+    /** Direct child basename. */
+    readonly name: string;
+    /** Bucket this entry falls in. */
+    readonly disposition: ReclaimDisposition;
+    /** Operator-readable reason, always populated. */
+    readonly reason: string;
+}
+/**
+ * Judge one candidate from its facts alone.
+ *
+ * Ordered so the conservative arms win: anything that is not a plain directory,
+ * or cannot be read, or was touched recently, is kept before completion is even
+ * consulted. Completion is necessary but never sufficient.
+ * @param facts - Facts read from the candidate
+ * @param quiescenceMs - Required untouched interval
+ * @returns The bucket and the reason for it
+ */
+export declare const classifySynthesisEntry: (facts: SynthesisEntryFacts, quiescenceMs?: number) => SynthesisEntryVerdict;
+/**
+ * Read the facts for one candidate without ever following a symlink.
+ * @param root - Directory holding the candidate
+ * @param name - Direct child basename
+ * @param now - Clock reading for the age computation
+ * @returns Facts describing the candidate
+ */
+export declare const readSynthesisEntryFacts: (root: string, name: string, now: number) => SynthesisEntryFacts;
+/** Inputs for one reclaim pass. */
+export interface ReclaimSynthesisScratchOptions {
+    /** Temp root to inspect. */
+    readonly root: string;
+    /** Clock reading used for every age computation. */
+    readonly now?: number;
+    /** Required untouched interval before completion authorizes removal. */
+    readonly quiescenceMs?: number;
+    /** Whether to remove. False reports without touching anything. */
+    readonly apply?: boolean;
+    /** Adversarial hook invoked after quarantine and before unlink, for tests. */
+    readonly afterQuarantine?: (quarantine: string) => void;
+}
+/** What one reclaim pass found and did. */
+export interface ReclaimSynthesisScratchResult {
+    /** Whether any candidate matched the expected naming convention. */
+    readonly recognised: boolean;
+    /** Entries removed, or that would be removed when not applying. */
+    readonly reclaimed: readonly SynthesisEntryVerdict[];
+    /** Entries kept because they are inside the quiescence window. */
+    readonly live: readonly SynthesisEntryVerdict[];
+    /** Entries kept because their status could not be established. */
+    readonly undetermined: readonly SynthesisEntryVerdict[];
+    /** Entries whose removal was attempted and refused by the fence. */
+    readonly refused: readonly SynthesisEntryVerdict[];
+}
+/**
+ * Reclaim completed, quiescent synthesis assemblies from one temp root.
+ *
+ * Removes nothing when no candidate matches the convention: a naming change in
+ * the producing tool must read as "recognised nothing" rather than as a clean
+ * sweep, because the two are opposite facts and only one of them is good news.
+ * @param options - Root, clock, thresholds and hooks
+ * @returns What was found in each bucket, and what was removed
+ */
+export declare function reclaimSynthesisScratch(options: ReclaimSynthesisScratchOptions): ReclaimSynthesisScratchResult;
+//# sourceMappingURL=synthesis-scratch-reclaim.d.ts.map

package/dist/configs/vitest/synthesis-scratch-reclaim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesis-scratch-reclaim.d.ts","sourceRoot":"","sources":["../../../src/configs/vitest/synthesis-scratch-reclaim.ts"],"names":[],"mappings":"AA2BA,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,QAAsB,CAAC;AAEzD,8CAA8C;AAC9C,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,MAAM,GAAG,cAAc,CAAC;AAEzE,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,mBAAmB,EAC1B,eAAc,MAA8B,KAC3C,qBAkCF,CAAC;AA8BF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAClC,MAAM,MAAM,EACZ,MAAM,MAAM,EACZ,KAAK,MAAM,KACV,mBAmBF,CAAC;AAEF,mCAAmC;AACnC,MAAM,WAAW,8BAA8B;IAC7C,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CACzD;AAED,2CAA2C;AAC3C,MAAM,WAAW,6BAA6B;IAC5C,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACrD,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAChD,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACxD,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACpD;AA2FD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,8BAA8B,GACtC,6BAA6B,CA8B/B"}