@smoothbricks/nx-cache-server 0.0.0-stage → 0.1.1

package/dist/ts/server.d.ts

@@ -0,0 +1,71 @@
+/**
+ * An nx self-hosted remote cache: `GET /v1/cache/<hash>` returns an artifact, `PUT /v1/cache/<hash>`
+ * publishes one, and a bearer token guards both.
+ *
+ * WHY this exists as our own process rather than a bucket: CVE-2025-36852 — CREEP, "Cache
+ * Race-condition Exploit Enables Poisoning", CVSS 9.4 — is a first-to-cache-wins race. A task hash is
+ * a function of the source state, so any environment that can write the cache can publish the artifact
+ * every later build with that same source state will consume, production included. The published
+ * mitigation is that untrusted environments must be able to read the cache and never write it, which is
+ * a property of the *server*: a bucket credential is read-write or nothing, so the trust boundary has
+ * nowhere to live. Here it does:
+ *
+ *   - **Tokens are read-only-capable.** A principal in `NX_CACHE_SERVER_READ_TOKENS` fetches artifacts
+ *     and is refused the write path with 403. A pull-request runner, a developer shed, or anything else
+ *     whose code has not been reviewed gets one of those and cannot reach into a trusted build's
+ *     lookup. Only `NX_CACHE_SERVER_WRITE_TOKENS` publishes.
+ *   - **Writes never replace.** `store.ts` publishes by `link(2)`, so an existing key is answered 409
+ *     and its bytes are never touched. A write token that leaks cannot go back and swap the artifact a
+ *     trusted build already published, and a retried upload is idempotent rather than a second chance
+ *     to change history.
+ *   - **Every publication is attributable.** Tokens carry labels (`config.ts`), so the log line for a
+ *     stored artifact names the principal that stored it. Forensics after a poisoning need that name.
+ *
+ * The status codes are not ours to choose; they are what the client already does with them
+ * (`packages/nx/src/native/cache/http_remote_cache.rs` in nx 23.2.0):
+ *
+ *   - `store` accepts **200** as stored, treats **409** and **403** as "not stored, carry on", and
+ *     turns *everything else* into a failed task. This server answers 200, the status nx's native
+ *     `store` accepts, so the write succeeds.
+ *   - `retrieve` accepts **200** and **404** and fails the task on anything else — so a bad token is a
+ *     loud error rather than a silent stream of cache misses, which is what we want.
+ *   - A refusal we want the operator to *read* must therefore be a 401, and `errors.rs` only reads a
+ *     401's body when the content type is exactly `text/plain`.
+ *
+ * Retention is filesystem SIEVE (`gc.ts`), serialized at startup and after successful publication.
+ * The project owner keeps backend credentials out of client environments; the server stores opaque
+ * Nx task archives, not workspace databases.
+ */
+import type { CacheServerConfig } from './config.js';
+export interface RunningCacheServer {
+    /** The origin to hand nx as `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`. */
+    readonly origin: string;
+    readonly port: number;
+    /** Staged uploads a previous process left behind, removed while opening the store. */
+    readonly reclaimedStagingFiles: number;
+    stop(): Promise<void>;
+}
+/** The single stdout readiness record emitted by the foreground executable. */
+export interface CacheServerReadyRecord {
+    readonly kind: 'ready';
+    readonly origin: string;
+    readonly port: number;
+    readonly reclaimedStagingFiles: number;
+}
+export type CacheServerStartResult = {
+    readonly ok: true;
+    readonly server: RunningCacheServer;
+} | {
+    readonly ok: false;
+    readonly stage: 'store' | 'gc' | 'listen';
+    readonly directory: string;
+    readonly reason: string;
+} | {
+    readonly ok: false;
+    readonly stage: 'store-locked';
+    readonly directory: string;
+    readonly path: string;
+    readonly reason: string;
+};
+export declare function startCacheServer(config: CacheServerConfig): Promise<CacheServerStartResult>;
+//# sourceMappingURL=server.d.ts.map

package/dist/ts/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAkB,iBAAiB,EAAE,MAAM,aAAa,CAAC;AA4CrE,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC1D;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,QAAQ,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAMN,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA0FjG"}

package/dist/ts/server.js

@@ -0,0 +1,282 @@
+/// <reference types="bun" />
+import { sweepDirectory } from './gc.js';
+import { logLine, logValue } from './log.js';
+import { describe, isCacheKey, openCacheStore, publishEntry, readEntry, stageEntry, } from './store.js';
+const CACHE_ROUTE = '/v1/cache/:hash';
+/** nx sends and expects `application/octet-stream` for artifact bodies. */
+const OCTET_STREAM = {
+    'content-type': 'application/octet-stream',
+};
+/** Exactly `text/plain`, no charset: see the note on `errors.rs` in the module header. */
+const PLAIN = {
+    'content-type': 'text/plain',
+};
+const PLAIN_UNAUTHENTICATED = {
+    'content-type': 'text/plain',
+    'www-authenticate': 'Bearer',
+};
+const MISS_BODY = 'No cache entry for that key.\n';
+/**
+ * Bun answers a body larger than this with a 413 the handler never sees — measured: it compares
+ * `content-length` before invoking the route, and it also trips mid-stream on a body that declared no
+ * length. Since nx turns any status but 200/409/403 into a failed task, the *policy* limits cannot live
+ * here. `handlePut` owns the bounds: a PUT with no declared length is refused 411, a declared length over
+ * `maxBytes` is refused 403 before a byte of body is read, and aggregate in-flight staging is reserved
+ * against a separate cap. The published archive cap is enforced by sweeps after publication. This
+ * ceiling is only a framing tripwire; it does not by itself bound bytes on disk or in flight.
+ */
+const FRAMING_CEILING = Number.MAX_SAFE_INTEGER;
+export async function startCacheServer(config) {
+    let opened;
+    try {
+        opened = await openCacheStore(config.directory);
+    }
+    catch (cause) {
+        return { ok: false, stage: 'store', directory: config.directory, reason: describe(cause) };
+    }
+    if (!opened.ok) {
+        return {
+            ok: false,
+            stage: 'store-locked',
+            directory: config.directory,
+            path: opened.path,
+            reason: `EWOULDBLOCK: another process holds the store lock at ${opened.path}`,
+        };
+    }
+    const store = opened.store;
+    const initial = await sweepDirectory(store, config.capBytes);
+    if (!initial.ok) {
+        await store.close();
+        return { ok: false, stage: 'gc', directory: config.directory, reason: initial.reason };
+    }
+    const admission = { reservedBytes: 0 };
+    let publishing = Promise.resolve();
+    function publish(upload) {
+        const next = publishing.then(async () => {
+            const outcome = await publishEntry(store, upload);
+            if (outcome.kind !== 'stored')
+                return outcome;
+            const retained = await sweepDirectory(store, config.capBytes, upload.key);
+            return retained.ok
+                ? outcome
+                : {
+                    kind: 'failed',
+                    reason: retained.reason,
+                    stagingRetained: outcome.stagingRetained,
+                };
+        });
+        publishing = next.then(() => { });
+        return next;
+    }
+    try {
+        const server = Bun.serve({
+            hostname: config.host,
+            port: config.port,
+            maxRequestBodySize: FRAMING_CEILING,
+            routes: {
+                [CACHE_ROUTE]: {
+                    GET: (request) => handleGet(store, config, request),
+                    PUT: (request) => handlePut(store, config, request, admission, publish),
+                },
+            },
+            fetch(request) {
+                const { pathname } = new URL(request.url);
+                logLine(`ev=unrouted method=${logValue(request.method)} path=${logValue(pathname)} status=404`);
+                return new Response('This server serves /v1/cache/<hash> only (GET, PUT). A path with a doubled slash means NX_SELF_HOSTED_REMOTE_CACHE_SERVER carries a trailing slash.\n', { status: 404, headers: PLAIN });
+            },
+            error(failure) {
+                logLine(`ev=server.error status=500 reason=${logValue(String(failure.message ?? failure))}`);
+                return new Response('The cache server failed to handle that request; see its log.\n', {
+                    status: 500,
+                    headers: PLAIN,
+                });
+            },
+        });
+        const principals = config.principals.map((principal) => `${principal.label}:${principal.capability}`).join(',');
+        logLine(`ev=listening origin=${server.url.origin} dir=${logValue(config.directory)} principals=${principals} max_bytes=${config.maxBytes} cap_bytes=${config.capBytes} reclaimed_staging=${store.reclaimedStagingFiles}`);
+        return {
+            ok: true,
+            server: {
+                origin: server.url.origin,
+                port: server.port ?? config.port,
+                reclaimedStagingFiles: store.reclaimedStagingFiles,
+                async stop() {
+                    await server.stop(false);
+                    await publishing;
+                    await store.close();
+                },
+            },
+        };
+    }
+    catch (cause) {
+        await store.close();
+        return { ok: false, stage: 'listen', directory: config.directory, reason: describe(cause) };
+    }
+}
+async function handleGet(store, config, request) {
+    const startedNs = Bun.nanoseconds();
+    const key = request.params.hash;
+    const principal = authorize(config.principals, request.headers.get('authorization'));
+    if (principal === undefined) {
+        record('get', key, undefined, 401, 0, startedNs, 'unauthenticated');
+        return unauthenticated();
+    }
+    if (!isCacheKey(key)) {
+        // A key outside the charset cannot name an entry, so a miss is the honest answer, and nx reads a
+        // 404 as "not cached" without failing the task.
+        record('get', key, principal, 404, 0, startedNs, 'invalid-key');
+        return new Response(MISS_BODY, { status: 404, headers: PLAIN });
+    }
+    const entry = await readEntry(store, key);
+    switch (entry.kind) {
+        case 'missing':
+            record('get', key, principal, 404, 0, startedNs, 'miss');
+            return new Response(MISS_BODY, { status: 404, headers: PLAIN });
+        case 'failed':
+            record('get', key, principal, 500, 0, startedNs, entry.reason);
+            return new Response('The cache server could not read that artifact; see its log.\n', {
+                status: 500,
+                headers: PLAIN,
+            });
+        case 'found':
+            record('get', key, principal, 200, entry.bytes, startedNs, undefined);
+            return new Response(entry.body, { status: 200, headers: OCTET_STREAM });
+    }
+}
+async function handlePut(store, config, request, admission, publish) {
+    const startedNs = Bun.nanoseconds();
+    const key = request.params.hash;
+    const principal = authorize(config.principals, request.headers.get('authorization'));
+    if (principal === undefined) {
+        record('put', key, undefined, 401, 0, startedNs, 'unauthenticated');
+        return unauthenticated();
+    }
+    if (principal.capability !== 'write') {
+        // The CREEP boundary. nx reads 403 as "the server declined to store this" and the build carries on
+        // with its own outputs, so an untrusted context loses nothing but the ability to publish.
+        record('put', key, principal, 403, 0, startedNs, 'read-only-token');
+        return new Response('This token may read the cache but not publish into it.\n', { status: 403, headers: PLAIN });
+    }
+    if (!isCacheKey(key)) {
+        // nx cannot produce such a key, so whatever did is a broken client or an attempt at the filesystem
+        // underneath: 400 fails the caller loudly instead of pretending to have stored something.
+        record('put', key, principal, 400, 0, startedNs, 'invalid-key');
+        return new Response('A cache key is 1-128 characters of [A-Za-z0-9_-].\n', {
+            status: 400,
+            headers: PLAIN,
+        });
+    }
+    // A declared length is required, and every bound below is derived from it. That is what keeps the
+    // size limit total: nothing is streamed whose length is unknown, so no body can outrun the limit,
+    // and `stageEntry` can refuse a body that arrives short of what it promised. nx always
+    // sends `content-length` (it hands reqwest a fully built buffer), so a request without one is not
+    // nx and deserves the loud answer.
+    const header = request.headers.get('content-length');
+    if (header === null) {
+        record('put', key, principal, 411, 0, startedNs, 'no-declared-length');
+        return new Response('A cache artifact must arrive with a content-length.\n', { status: 411, headers: PLAIN });
+    }
+    const declared = Number(header);
+    if (!Number.isInteger(declared) || declared < 1) {
+        // Zero included: an empty artifact is one nx can never extract, and never-replace would make it a
+        // permanent failure for that task hash.
+        record('put', key, principal, 400, 0, startedNs, 'bad-declared-length');
+        return new Response('content-length must be a positive integer.\n', {
+            status: 400,
+            headers: PLAIN,
+        });
+    }
+    if (declared > config.maxBytes) {
+        // 403 rather than 413 on purpose: an artifact too large to keep must not fail the build that
+        // produced it, and 403 is the one refusal nx absorbs silently. The log is where it is not silent.
+        record('put', key, principal, 403, declared, startedNs, 'over-max-bytes');
+        return new Response(`This artifact exceeds the server's ${config.maxBytes}-byte limit.\n`, {
+            status: 403,
+            headers: PLAIN,
+        });
+    }
+    if (declared > config.capBytes - admission.reservedBytes) {
+        record('put', key, principal, 403, declared, startedNs, 'staging-capacity');
+        return new Response('The staging byte budget is full; nothing was stored.\n', {
+            status: 403,
+            headers: PLAIN,
+        });
+    }
+    admission.reservedBytes += declared;
+    logLine(`ev=staging.reserved key=${logValue(key)} declared_bytes=${declared} reserved_bytes=${admission.reservedBytes} cap=${config.capBytes}`);
+    let stagingRetained = false;
+    try {
+        const staged = await stageEntry(store, key, request.body, declared);
+        if (staged.kind !== 'ready') {
+            stagingRetained = staged.stagingRetained;
+            if (staged.kind === 'incomplete') {
+                record('put', key, principal, 400, staged.bytes, startedNs, 'body-shorter-than-declared');
+                return new Response(`That body ended after ${staged.bytes} of the ${declared} bytes it declared; nothing was stored.\n`, { status: 400, headers: PLAIN });
+            }
+            record('put', key, principal, 500, 0, startedNs, staged.reason);
+            return new Response('The cache server could not stage that artifact; see its log.\n', {
+                status: 500,
+                headers: PLAIN,
+            });
+        }
+        const outcome = await publish(staged);
+        stagingRetained = outcome.stagingRetained;
+        if (outcome.kind === 'stored') {
+            record('put', key, principal, 200, outcome.bytes, startedNs, undefined);
+            return new Response('stored\n', { status: 200, headers: PLAIN });
+        }
+        if (outcome.kind === 'exists') {
+            record('put', key, principal, 409, 0, startedNs, 'already-stored');
+            return new Response('That key already holds an artifact; a cache entry is never replaced.\n', {
+                status: 409,
+                headers: PLAIN,
+            });
+        }
+        record('put', key, principal, 500, 0, startedNs, outcome.reason);
+        return new Response('The cache server could not publish or retain that artifact; see its log.\n', {
+            status: 500,
+            headers: PLAIN,
+        });
+    }
+    finally {
+        if (stagingRetained) {
+            logLine(`ev=staging.reservation-retained key=${logValue(key)} declared_bytes=${declared} reserved_bytes=${admission.reservedBytes} reason=cleanup-failed`);
+        }
+        else {
+            admission.reservedBytes -= declared;
+            logLine(`ev=staging.released key=${logValue(key)} declared_bytes=${declared} reserved_bytes=${admission.reservedBytes}`);
+        }
+    }
+}
+/**
+ * Resolve the presented header to a principal, comparing every configured token with no early exit so
+ * the time taken says nothing about how much of a secret was correct.
+ */
+function authorize(principals, header) {
+    if (header === null)
+        return undefined;
+    let authorized;
+    for (const principal of principals) {
+        if (secretEquals(header, principal.bearer))
+            authorized = principal;
+    }
+    return authorized;
+}
+function secretEquals(received, expected) {
+    if (received.length !== expected.length)
+        return false;
+    let difference = 0;
+    for (let index = 0; index < expected.length; index += 1) {
+        difference |= received.charCodeAt(index) ^ expected.charCodeAt(index);
+    }
+    return difference === 0;
+}
+function unauthenticated() {
+    return new Response('Missing or unknown bearer token. Send `Authorization: Bearer <token>` with a token this server was started with (NX_CACHE_SERVER_WRITE_TOKENS or NX_CACHE_SERVER_READ_TOKENS); nx sends the one in NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN.\n', { status: 401, headers: PLAIN_UNAUTHENTICATED });
+}
+function record(event, key, principal, status, bytes, startedNs, reason) {
+    const microseconds = Math.round((Bun.nanoseconds() - startedNs) / 1000);
+    const attribution = principal === undefined ? '-' : principal.label;
+    const because = reason === undefined ? '' : ` reason=${logValue(reason)}`;
+    logLine(`ev=${event} key=${logValue(key)} principal=${attribution} status=${status} bytes=${bytes} us=${microseconds}${because}`);
+}

package/dist/ts/store.d.ts

@@ -0,0 +1,74 @@
+export interface CacheStore {
+    readonly directory: string;
+    readonly staging: string;
+    /** Staged uploads a previous process left behind, removed while opening. */
+    readonly reclaimedStagingFiles: number;
+    /** Releases the root lease. Call only after in-flight requests and publication have drained. */
+    close(): Promise<void>;
+}
+export type CacheStoreOpenResult = {
+    readonly ok: true;
+    readonly store: CacheStore;
+} | {
+    readonly ok: false;
+    readonly kind: 'store-locked';
+    readonly path: string;
+};
+/** A whole, verified staged upload; only publication makes it visible to GET. */
+export interface CompleteUpload {
+    readonly kind: 'ready';
+    readonly key: string;
+    readonly stagedPath: string;
+    readonly bytes: number;
+}
+export type StageOutcome = CompleteUpload | {
+    readonly kind: 'incomplete';
+    readonly bytes: number;
+    readonly stagingRetained: boolean;
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+    readonly stagingRetained: boolean;
+};
+export type StoreOutcome = {
+    readonly kind: 'stored';
+    readonly bytes: number;
+    readonly stagingRetained: boolean;
+} | {
+    readonly kind: 'exists';
+    readonly stagingRetained: boolean;
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+    readonly stagingRetained: boolean;
+};
+export declare function isCacheKey(candidate: string): boolean;
+export declare function entryPath(store: CacheStore, key: string): string;
+export declare function openCacheStore(directory: string): Promise<CacheStoreOpenResult>;
+export type ReadOutcome = {
+    readonly kind: 'found';
+    readonly bytes: number;
+    readonly body: ReadableStream<Uint8Array>;
+} | {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+/** Pin an opened inode before answering: a concurrent sweep may unlink its path, not truncate GET. */
+export declare function readEntry(store: CacheStore, key: string): Promise<ReadOutcome>;
+/**
+ * Stage the body and verify its length. Publication is a separate atomic operation.
+ *
+ * WHY the length is checked before the link and not after: an entry is permanent, so publishing a
+ * truncated one poisons that task hash forever — every later build fetches an artifact nx cannot
+ * extract, and never-replace means nobody can correct it. A body that ends short of `declaredBytes`
+ * is therefore discarded while it is still only a staged file.
+ */
+export declare function stageEntry(store: CacheStore, key: string, body: ReadableStream<Uint8Array> | null, declaredBytes: number): Promise<StageOutcome>;
+/** Publish by never-replace hard link. The server serializes this operation with its SIEVE sweep. */
+export declare function publishEntry(store: CacheStore, upload: CompleteUpload): Promise<StoreOutcome>;
+/** Read an errno off a thrown value without asserting its type. */
+export declare function errnoOf(cause: unknown): string | undefined;
+export declare function describe(cause: unknown): string;
+//# sourceMappingURL=store.d.ts.map

package/dist/ts/store.d.ts.map

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

package/dist/ts/store.js

@@ -0,0 +1,166 @@
+/// <reference types="bun" />
+/**
+ * The cache directory: one file per key, and a write that cannot replace one.
+ *
+ * `link(2)` is the whole design. A staged upload becomes an entry by hard-linking it to
+ * `<directory>/<key>`, which the kernel either performs or refuses with `EEXIST` — atomically, with no
+ * window in which a reader sees a partial file and no window in which two writers of the same key both
+ * believe they won. `rename(2)` would be wrong here: it replaces silently, so the loser of a race
+ * would overwrite the winner's artifact and both would be told they stored it.
+ *
+ * Staging lives at `<directory>/.staging` for two reasons: it is on the same filesystem, which
+ * `link(2)` requires, and the leading dot puts it outside the cache-key charset, so no request can
+ * name it. Opening the store reclaims whatever a crash left there — a nonzero count in the startup log
+ * is how an operator learns a previous process died mid-upload.
+ *
+ * One process owns one directory at a time. `openCacheStore` takes a persistent kernel lock on
+ * `<directory>/.owner.lock` before it touches staging, so a second open is refused with `store-locked`
+ * and reclaims nothing until the first store is closed or its process dies.
+ */
+import { link, mkdir, open, readdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { logLine, logValue } from './log.js';
+import { tryAcquireRootLease } from './root-lease.js';
+const STAGING = '.staging';
+/**
+ * The cache-key charset. nx sends a task hash and nothing else — twenty decimal digits today
+ * (`.nx/cache/10018087211778381691`) — and this accepts any hex, decimal or base64url rendering of
+ * one. What it rejects is what makes `join(directory, key)` safe by construction: no `/`, no `\`, and
+ * no `.`, so no key can name a parent directory, an absolute path, or the staging directory.
+ */
+const CACHE_KEY = /^[A-Za-z0-9_-]{1,128}$/;
+/** The common conflict outcome carries no per-request data. */
+const ALREADY_STORED = { kind: 'exists', stagingRetained: false };
+export function isCacheKey(candidate) {
+    return CACHE_KEY.test(candidate);
+}
+export function entryPath(store, key) {
+    return join(store.directory, key);
+}
+export async function openCacheStore(directory) {
+    await mkdir(directory, { recursive: true });
+    const lockPath = join(directory, '.owner.lock');
+    const lease = await tryAcquireRootLease(lockPath);
+    if (!lease)
+        return { ok: false, kind: 'store-locked', path: lockPath };
+    try {
+        const staging = join(directory, STAGING);
+        await mkdir(staging, { recursive: true });
+        const abandoned = await readdir(staging);
+        for (const name of abandoned) {
+            await unlink(join(staging, name));
+        }
+        return {
+            ok: true,
+            store: { directory, staging, reclaimedStagingFiles: abandoned.length, close: () => lease.close() },
+        };
+    }
+    catch (failure) {
+        await lease.close();
+        throw failure;
+    }
+}
+const MISSING = { kind: 'missing' };
+/** Pin an opened inode before answering: a concurrent sweep may unlink its path, not truncate GET. */
+export async function readEntry(store, key) {
+    try {
+        const file = await open(entryPath(store, key), 'r');
+        try {
+            const stats = await file.stat();
+            if (!stats.isFile() || stats.size === 0) {
+                await file.close();
+                return MISSING;
+            }
+            // APFS can leave atime unchanged on a real read. Mark SIEVE's visited bit explicitly on the
+            // pinned inode, and only when it is clear; the original modification time remains the cursor.
+            if (stats.atimeMs <= stats.mtimeMs) {
+                await file.utimes((stats.mtimeMs + 1) / 1000, stats.mtimeMs / 1000);
+            }
+            return {
+                kind: 'found',
+                bytes: stats.size,
+                body: Readable.toWeb(file.createReadStream({ autoClose: true })),
+            };
+        }
+        catch (cause) {
+            await file.close();
+            return { kind: 'failed', reason: describe(cause) };
+        }
+    }
+    catch (cause) {
+        return errnoOf(cause) === 'ENOENT' ? MISSING : { kind: 'failed', reason: describe(cause) };
+    }
+}
+/**
+ * Stage the body and verify its length. Publication is a separate atomic operation.
+ *
+ * WHY the length is checked before the link and not after: an entry is permanent, so publishing a
+ * truncated one poisons that task hash forever — every later build fetches an artifact nx cannot
+ * extract, and never-replace means nobody can correct it. A body that ends short of `declaredBytes`
+ * is therefore discarded while it is still only a staged file.
+ */
+export async function stageEntry(store, key, body, declaredBytes) {
+    const staged = join(store.staging, `${key}.${crypto.randomUUID()}`);
+    let bytes;
+    try {
+        // `Response` is the streaming form of `Bun.write`: the body reaches the disk in chunks instead of
+        // being buffered whole in this process.
+        bytes = await Bun.write(staged, new Response(body));
+    }
+    catch (cause) {
+        const stagingRetained = !(await discard(staged));
+        return { kind: 'failed', reason: describe(cause), stagingRetained };
+    }
+    if (bytes !== declaredBytes) {
+        const stagingRetained = !(await discard(staged));
+        return { kind: 'incomplete', bytes, stagingRetained };
+    }
+    return { kind: 'ready', key, stagedPath: staged, bytes };
+}
+/** Publish by never-replace hard link. The server serializes this operation with its SIEVE sweep. */
+export async function publishEntry(store, upload) {
+    try {
+        await link(upload.stagedPath, entryPath(store, upload.key));
+    }
+    catch (cause) {
+        const stagingRetained = !(await discard(upload.stagedPath));
+        if (errnoOf(cause) === 'EEXIST') {
+            return stagingRetained ? { kind: 'exists', stagingRetained } : ALREADY_STORED;
+        }
+        return { kind: 'failed', reason: describe(cause), stagingRetained };
+    }
+    const stagingRetained = !(await discard(upload.stagedPath));
+    return { kind: 'stored', bytes: upload.bytes, stagingRetained };
+}
+/**
+ * Drop a staged upload once it has been published or abandoned. A staging file that outlives its
+ * request is leaked disk, so a failure to remove one is reported rather than dropped; `ENOENT` is not
+ * a failure, it is the file already being gone.
+ */
+async function discard(staged) {
+    try {
+        await unlink(staged);
+        return true;
+    }
+    catch (cause) {
+        if (errnoOf(cause) === 'ENOENT')
+            return true;
+        logLine(`ev=staging.leaked path=${logValue(staged)} reason=${logValue(describe(cause))}`);
+        return false;
+    }
+}
+/** Read an errno off a thrown value without asserting its type. */
+export function errnoOf(cause) {
+    if (typeof cause !== 'object' || cause === null || !('code' in cause))
+        return undefined;
+    const { code } = cause;
+    return typeof code === 'string' ? code : undefined;
+}
+export function describe(cause) {
+    if (cause instanceof Error) {
+        const errno = errnoOf(cause);
+        return errno === undefined ? cause.message : `${errno}: ${cause.message}`;
+    }
+    return String(cause);
+}