@foldrun/core 0.4.0 → 0.6.0

package/dist/src/runtime.d.ts

@@ -8,6 +8,10 @@ export interface RuntimeSpec {
      *  the script with "no module named pandas" is the least debuggable outcome
      *  available. Never part of the fingerprint — it names nothing installed. */
     rejected?: string[];
+    /** Installer options a requirements.txt carried (`--hash`, `-r`,
+     *  `--index-url`), by name only. Not applied — the installer takes options
+     *  from the same argv as its packages — and said so in the build log. */
+    ignored?: string[];
 }
 export declare function parseRuntime(raw: unknown): RuntimeSpec | null;
 /**
@@ -37,5 +41,53 @@ export interface PreparedRuntime {
     /** Human-readable lines describing what was built, for the run log. */
     log: string[];
     error: string | null;
+    /** Removes what only this step may use — the private build a wedged or
+     *  failed shared build left it with. Absent when there is nothing to
+     *  remove; call it when the step is done with the environment. */
+    dispose?: () => void;
 }
+/**
+ * Claim the right to build `root`, or discover someone else holds it.
+ *
+ * The cache became shared the moment it started surviving the container, and
+ * two steps of the same account with the same dependencies now start at the
+ * same instant routinely — the platform runs four at a time. Both would run
+ * `python -m venv` into one directory and pip into it concurrently, and the
+ * loser's half-written venv is not a slow run, it is a corrupt cache that
+ * every later step inherits. `mkdir` is the lock because it is atomic on
+ * every filesystem this runs on; O_EXCL on a file would do as well.
+ */
+export declare function claimBuild(root: string, 
+/** Test seam: runs once the claim is judged abandoned, before the
+ *  takeover — where a second claimer used to slip in. */
+seam?: {
+    beforeTakeover?: () => void;
+}): string | null;
+/** Release the claim — only if it is still ours. */
+export declare function releaseBuild(root: string, token: string): void;
+/** A requirement's distribution name: `requests[socks]>=2` → `requests`. */
+export declare function distName(req: string): string;
+/** An npm requirement's package name: `@scope/pkg@^1` → `@scope/pkg`. */
+export declare function npmName(req: string): string;
+/**
+ * Does a `.ready` entry still hold what the declaration asks for? Null when it
+ * does, else why not.
+ *
+ * `.ready` is written once and trusted for ever, and that trust was misplaced
+ * more than once: a build interrupted between install and marker, a cache
+ * volume restored without its contents, and — the quiet one — an image whose
+ * python moved (bookworm's 3.11 to trixie's 3.13), which leaves every venv
+ * with a valid-looking bin/python pointing at an interpreter that is gone.
+ * Each reported "cached" and failed later inside somebody's tool. One spawn
+ * of the venv's python per step is the price of never doing that again.
+ */
+export declare function checkEntry(root: string, spec: RuntimeSpec): string | null;
+/**
+ * Remove entries nobody has used for maxAgeDays. `.ready`'s mtime is the
+ * last-used clock (every hit touches it); an entry with no `.ready` is a
+ * failed build and ages from its directory's own mtime. Never an entry that
+ * is being built, and never `keep`. Runs after a successful build — the only
+ * moment a cache grows — so it costs nothing on the hot path.
+ */
+export declare function pruneRuntimes(cacheRoot: string, keep: string): string[];
 export declare function prepareRuntime(tenant: string, spec: RuntimeSpec | null): PreparedRuntime;