@jini-ai/platform 0.5.9 → 0.5.10

package/dist/download.js

@@ -166,8 +166,15 @@ async function directoryIsEmpty(path) {
     const entries = await readdir(path);
     return entries.length === 0;
 }
+// Every caller feeds this a `JSON.parse` result, and a parsed JSON array can
+// never carry the named string keys (`kind`, `algorithm`, `pid`, ...) each
+// guard goes on to require, so arrays are rejected without a separate
+// `Array.isArray` check.
+function isPlainObject(value) {
+    return typeof value === "object" && value != null;
+}
 function isStoreSentinel(value) {
-    if (typeof value !== "object" || value == null || Array.isArray(value))
+    if (!isPlainObject(value))
         return false;
     const record = value;
     return record.kind === STORE_KIND && record.schemaVersion === STORE_SCHEMA_VERSION && typeof record.createdAt === "string";
@@ -216,30 +223,33 @@ async function ensureManagedBase(basePath) {
     await ensureStoreDirs(basePath);
 }
 function isChecksum(value) {
-    if (typeof value !== "object" || value == null || Array.isArray(value))
+    if (!isPlainObject(value))
         return false;
     const checksum = value;
     return ((checksum.algorithm === "sha256" || checksum.algorithm === "sha512") &&
         typeof checksum.value === "string");
 }
+const MANIFEST_STRING_FIELDS = [
+    "bucket",
+    "fileName",
+    "targetKey",
+    "identityDigest",
+    "urlDigest",
+    "createdAt",
+    "updatedAt",
+];
 function isManifest(value) {
-    if (typeof value !== "object" || value == null || Array.isArray(value))
+    if (!isPlainObject(value))
         return false;
     const record = value;
     return (record.kind === MANIFEST_KIND &&
         record.schemaVersion === MANIFEST_SCHEMA_VERSION &&
-        typeof record.bucket === "string" &&
-        typeof record.fileName === "string" &&
-        typeof record.targetKey === "string" &&
-        typeof record.identityDigest === "string" &&
-        typeof record.urlDigest === "string" &&
+        MANIFEST_STRING_FIELDS.every((field) => typeof record[field] === "string") &&
         isChecksum(record.checksum) &&
-        (record.state === "complete" || record.state === "partial") &&
-        typeof record.createdAt === "string" &&
-        typeof record.updatedAt === "string");
+        (record.state === "complete" || record.state === "partial"));
 }
 function isDownloadLockFile(value) {
-    if (typeof value !== "object" || value == null || Array.isArray(value))
+    if (!isPlainObject(value))
         return false;
     const record = value;
     return typeof record.createdAt === "string" &&
@@ -326,7 +336,8 @@ async function statFileSize(path) {
 }
 async function emitExistingProgress(path, totalBytes, emit) {
     // `totalBytes` is required (not `number | undefined`): its only real call
-    // site (`tryResumeDownload`) always resolves one, via a `??` chain whose
+    // site (`tryResumeDownload`) always resolves one, via a `??` chain (in
+    // `acceptedResumeTotalBytes`) whose
     // last resort is arithmetic (`partialBytes + (contentLength(response) ??
     // 0)`) — never `undefined`.
     const existing = await statFileSize(path);
@@ -361,16 +372,21 @@ function parseContentRange(value) {
     if (value == null)
         return null;
     const match = /^bytes\s+(\d+)-(\d+)\/(\d+|\*)$/i.exec(value.trim());
-    if (match?.[1] == null || match[2] == null || match[3] == null)
+    // Every group in the pattern is mandatory, so a match always carries all three.
+    if (match == null)
         return null;
+    // `\d+` always parses to an integer — except a digit run long enough to
+    // overflow to Infinity, which `Number.isInteger` rejects.
     const start = Number(match[1]);
     const end = Number(match[2]);
-    const totalBytes = match[3] === "*" ? undefined : Number(match[3]);
     if (!Number.isInteger(start) || !Number.isInteger(end) || end < start)
         return null;
-    if (totalBytes != null && (!Number.isInteger(totalBytes) || totalBytes <= end))
+    if (match[3] === "*")
+        return { start, end };
+    const totalBytes = Number(match[3]);
+    if (!Number.isInteger(totalBytes) || totalBytes <= end)
         return null;
-    return { start, end, ...(totalBytes == null ? {} : { totalBytes }) };
+    return { start, end, totalBytes };
 }
 async function writeResponseBodyToPartial(response, target, options) {
     if (response.body == null)
@@ -391,24 +407,36 @@ async function writeResponseBodyToPartial(response, target, options) {
     });
     await pipeline(Readable.fromWeb(response.body), meter, createWriteStream(target.partialPath, { flags: options.startBytes > 0 ? "a" : "w" }));
 }
-async function tryResumeDownload(target, manifest, fetchImpl, emit, requestHeaders) {
+function resumeRequestHeaders(input, options) {
+    const etag = input.manifest.validators?.etag;
+    return {
+        ...(options.requestHeaders ?? {}),
+        ...(etag == null ? {} : { "If-Range": etag }),
+        Range: `bytes=${input.partialBytes}-`,
+    };
+}
+/** The resumed total size, or `null` when the response cannot continue the saved partial. */
+function acceptedResumeTotalBytes(input) {
+    const { manifest, partialBytes, response } = input;
+    if (response.status !== 206)
+        return null;
+    const range = parseContentRange(response.headers.get("content-range"));
+    if (range == null || range.start !== partialBytes || validatorsConflict(manifest.validators, response)) {
+        return null;
+    }
+    return range.totalBytes ?? manifest.totalBytes ?? partialBytes + (contentLength(response) ?? 0);
+}
+async function tryResumeDownload(input, options) {
+    const { emit, fetchImpl, manifest, target } = input;
     const partialBytes = await statFileSize(target.partialPath);
     if (partialBytes == null || partialBytes <= 0)
         return "restart";
     const response = await fetchImpl(target.url, {
-        headers: {
-            ...(requestHeaders ?? {}),
-            ...(manifest.validators?.etag == null ? {} : { "If-Range": manifest.validators.etag }),
-            Range: `bytes=${partialBytes}-`,
-        },
+        headers: resumeRequestHeaders({ manifest, partialBytes }, options),
     });
-    if (response.status !== 206)
-        return "restart";
-    const range = parseContentRange(response.headers.get("content-range"));
-    if (range == null || range.start !== partialBytes || validatorsConflict(manifest.validators, response)) {
+    const totalBytes = acceptedResumeTotalBytes({ manifest, partialBytes, response });
+    if (totalBytes == null)
         return "restart";
-    }
-    const totalBytes = range.totalBytes ?? manifest.totalBytes ?? partialBytes + (contentLength(response) ?? 0);
     await emitExistingProgress(target.partialPath, totalBytes, emit);
     await writeJson(target.manifestPath, {
         ...manifest,
@@ -420,7 +448,9 @@ async function tryResumeDownload(target, manifest, fetchImpl, emit, requestHeade
     await writeResponseBodyToPartial(response, target, { emit, startBytes: partialBytes, totalBytes });
     return { resumed: true, totalBytes };
 }
-async function downloadFromZero(target, fetchImpl, emit, requestHeaders) {
+async function downloadFromZero(input, options) {
+    const { emit, fetchImpl, target } = input;
+    const { requestHeaders } = options;
     await rm(target.partialPath, { force: true }).catch(() => undefined);
     const response = await fetchImpl(target.url, {
         ...(requestHeaders == null ? {} : { headers: requestHeaders }),
@@ -436,63 +466,66 @@ async function downloadFromZero(target, fetchImpl, emit, requestHeaders) {
 async function downloadWithRetries(target, manifest, options) {
     let lastError;
     let nextManifest = manifest;
-    let resumed = false;
+    const deps = { emit: options.emit, fetchImpl: options.fetchImpl };
     for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
         try {
             if (nextManifest?.state === "partial") {
-                const resume = await tryResumeDownload(target, nextManifest, options.fetchImpl, options.emit, options.requestHeaders);
+                const resume = await tryResumeDownload({ ...deps, manifest: nextManifest, target }, options);
                 if (resume !== "restart")
-                    return { ...resume, resumed: true };
+                    return resume;
                 await rm(target.partialPath, { force: true }).catch(() => undefined);
                 nextManifest = null;
             }
-            const full = await downloadFromZero(target, options.fetchImpl, options.emit, options.requestHeaders);
-            resumed = resumed || full.resumed;
-            return { ...full, resumed };
+            return await downloadFromZero({ ...deps, target }, options);
         }
         catch (error) {
             lastError = error;
-            const partialBytes = await statFileSize(target.partialPath);
-            if (partialBytes != null && partialBytes > 0) {
-                nextManifest = {
-                    ...(nextManifest ?? createManifest(target, "partial")),
-                    state: "partial",
-                    updatedAt: new Date().toISOString(),
-                };
-                await writeJson(target.manifestPath, nextManifest).catch(() => undefined);
-            }
+            nextManifest = await manifestAfterFailedAttempt({ manifest: nextManifest, target });
         }
     }
     throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.NETWORK_EXHAUSTED, `download failed after ${options.maxAttempts} attempts: ${errorMessage(lastError)}`);
 }
+/** After a failed attempt, mark any bytes already on disk as a resumable partial (best-effort persisted). */
+async function manifestAfterFailedAttempt(input) {
+    const { manifest, target } = input;
+    const partialBytes = await statFileSize(target.partialPath);
+    if (partialBytes == null || partialBytes <= 0)
+        return manifest;
+    const next = {
+        ...(manifest ?? createManifest(target, "partial")),
+        state: "partial",
+        updatedAt: new Date().toISOString(),
+    };
+    await writeJson(target.manifestPath, next).catch(() => undefined);
+    return next;
+}
 async function acquireLock(target) {
     await mkdir(dirname(target.lockPath), { recursive: true });
-    // The `continue` below is only reachable on `attempt === 0`, so by the time
-    // `attempt` would reach 2 (the old loop bound), the branch above it has
-    // already thrown — there's no way to fall through to a third iteration, so
-    // no trailing fallback throw is needed. Every path out of this loop body is
-    // a `return` or a `throw`; V8 still instruments the loop's closing brace as
-    // a branch (whether execution "falls off" the loop normally), but that
-    // outcome is structurally impossible here — see archived provenance ledger's
-    // 2026-07-22 entry.
-    for (let attempt = 0;; attempt += 1) {
-        try {
-            await writeFile(target.lockPath, `${JSON.stringify({
-                createdAt: new Date().toISOString(),
-                pid: process.pid,
-                processStartedAt: new Date(PROCESS_STARTED_AT_MS).toISOString(),
-            })}\n`, { flag: "wx" });
-            return { path: target.lockPath };
-        }
-        catch (error) {
-            if (errorCode(error) === "EEXIST") {
-                const staleLockCleared = attempt === 0 && await clearStaleLock(target);
-                if (staleLockCleared)
-                    continue;
-                throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.TARGET_LOCKED, `download target is locked: ${target.bucket}/${target.fileName}`);
-            }
-            throw error;
-        }
+    // At most two create attempts: the second only after the first hit an
+    // existing lock that `clearStaleLock` proved stale and removed; a second
+    // EEXIST is real contention. (This was formerly a `for (;;)` loop whose
+    // fall-through branch V8 instrumented but no path could take — see archived
+    // provenance ledger's 2026-07-22 entry; the straight-line form has none.)
+    if (await tryCreateLockFile(target))
+        return { path: target.lockPath };
+    if (await clearStaleLock(target) && await tryCreateLockFile(target))
+        return { path: target.lockPath };
+    throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.TARGET_LOCKED, `download target is locked: ${target.bucket}/${target.fileName}`);
+}
+/** Exclusively create the lock file; `false` when one already exists, any other failure is rethrown. */
+async function tryCreateLockFile(target) {
+    try {
+        await writeFile(target.lockPath, `${JSON.stringify({
+            createdAt: new Date().toISOString(),
+            pid: process.pid,
+            processStartedAt: new Date(PROCESS_STARTED_AT_MS).toISOString(),
+        })}\n`, { flag: "wx" });
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "EEXIST")
+            return false;
+        throw error;
     }
 }
 async function clearStaleLock(target) {
@@ -519,88 +552,52 @@ async function loadReusableState(target) {
         return await suspiciousReset(target);
     }
     if (manifest == null) {
-        if (finalExists || partialExists)
-            return await suspiciousReset(target);
-        return { manifest: null };
+        return finalExists || partialExists ? await suspiciousReset(target) : { manifest: null };
     }
     if (!manifestMatchesTarget(manifest, target)) {
         return await suspiciousReset(target);
     }
-    if (manifest.state === "complete") {
-        if (!finalExists)
-            return await suspiciousReset(target);
-        const actual = await hashFile(target.finalPath, target.checksum.algorithm).catch(() => null);
-        if (actual !== target.checksum.value)
-            return await suspiciousReset(target);
-        const bytes = await statFileSize(target.finalPath);
-        if (bytes == null)
-            return await suspiciousReset(target);
-        return {
-            manifest,
-            result: {
-                bucket: target.bucket,
-                bytes,
-                checksum: target.checksum,
-                fileName: target.fileName,
-                path: target.finalPath,
-                reusedComplete: true,
-                resumed: false,
-                urlDigest: target.urlDigest,
-            },
-        };
-    }
+    if (manifest.state === "complete")
+        return await reusableCompleteState({ manifest, target });
     if (!partialExists)
         return await suspiciousReset(target);
     return { manifest };
 }
+/** Reuse a complete download only when its final file exists and still hashes to the requested checksum. */
+async function reusableCompleteState(input) {
+    const { manifest, target } = input;
+    // A missing final file needs no separate check: hashing it rejects, which
+    // maps to `null` and fails the checksum comparison into the same reset.
+    const actual = await hashFile(target.finalPath, target.checksum.algorithm).catch(() => null);
+    if (actual !== target.checksum.value)
+        return await suspiciousReset(target);
+    const bytes = await statFileSize(target.finalPath);
+    if (bytes == null)
+        return await suspiciousReset(target);
+    return {
+        manifest,
+        result: {
+            bucket: target.bucket,
+            bytes,
+            checksum: target.checksum,
+            fileName: target.fileName,
+            path: target.finalPath,
+            reusedComplete: true,
+            resumed: false,
+            urlDigest: target.urlDigest,
+        },
+    };
+}
 async function runManagedDownload(target, options) {
     await ensureManagedBase(target.basePath);
     await pruneManagedDownloads({ basePath: target.basePath }).catch(() => undefined);
-    let lock = await acquireLock(target);
+    const held = { lock: await acquireLock(target) };
     try {
-        let state = await loadReusableState(target);
+        const state = await loadStateAllowingOneReset({ held, target });
         if (state.result != null)
             return state.result;
-        if (state.reset === true) {
-            // A reset removes the lock as part of the managed base cleanup, so
-            // reacquire it before writing the fresh target state.
-            await releaseLock(lock);
-            lock = null;
-            await ensureManagedBase(target.basePath);
-            lock = await acquireLock(target);
-            state = await loadReusableState(target);
-            if (state.result != null)
-                return state.result;
-            if (state.reset === true) {
-                throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, "download state kept resetting after base cleanup");
-            }
-        }
         const download = await downloadWithRetries(target, state.manifest, options);
-        const actual = await hashFile(target.partialPath, target.checksum.algorithm).catch((error) => {
-            throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, `downloaded partial could not be hashed: ${errorMessage(error)}`);
-        });
-        if (actual !== target.checksum.value) {
-            await resetOwnedBase(target.basePath).catch(() => undefined);
-            throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.CHECKSUM_MISMATCH, "downloaded file checksum did not match requested payload", {
-                actual,
-                expected: target.checksum.value,
-            });
-        }
-        await mkdir(dirname(target.finalPath), { recursive: true });
-        if (await pathExists(target.finalPath)) {
-            const existing = await hashFile(target.finalPath, target.checksum.algorithm).catch(() => null);
-            if (existing !== target.checksum.value) {
-                await resetOwnedBase(target.basePath).catch(() => undefined);
-                throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, "existing complete file did not match requested payload");
-            }
-            await rm(target.partialPath, { force: true }).catch(() => undefined);
-        }
-        else {
-            await rename(target.partialPath, target.finalPath);
-        }
-        const bytes = await statFileSize(target.finalPath);
-        if (bytes == null)
-            throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, "complete file is missing after promotion");
+        const bytes = await promoteVerifiedPartial(target);
         await writeJson(target.manifestPath, createManifest(target, "complete", { totalBytes: download.totalBytes }));
         return {
             bucket: target.bucket,
@@ -614,8 +611,57 @@ async function runManagedDownload(target, options) {
         };
     }
     finally {
-        await releaseLock(lock);
+        await releaseLock(held.lock);
+    }
+}
+/** Load reusable state, re-locking and reloading once if the first load had to reset the managed base. */
+async function loadStateAllowingOneReset(input) {
+    const { held, target } = input;
+    const state = await loadReusableState(target);
+    if (state.reset !== true)
+        return state;
+    // A reset removes the lock as part of the managed base cleanup, so
+    // reacquire it before writing the fresh target state. `held.lock` is
+    // nulled first so a failed re-acquire never releases (deletes) a lock
+    // another process may have taken in the meantime.
+    await releaseLock(held.lock);
+    held.lock = null;
+    await ensureManagedBase(target.basePath);
+    held.lock = await acquireLock(target);
+    const reloaded = await loadReusableState(target);
+    if (reloaded.reset === true) {
+        throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, "download state kept resetting after base cleanup");
+    }
+    return reloaded;
+}
+/** Verify the downloaded partial's checksum, promote it to the final path, and return the final size. */
+async function promoteVerifiedPartial(target) {
+    const actual = await hashFile(target.partialPath, target.checksum.algorithm).catch((error) => {
+        throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, `downloaded partial could not be hashed: ${errorMessage(error)}`);
+    });
+    if (actual !== target.checksum.value) {
+        await resetOwnedBase(target.basePath).catch(() => undefined);
+        throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.CHECKSUM_MISMATCH, "downloaded file checksum did not match requested payload", {
+            actual,
+            expected: target.checksum.value,
+        });
+    }
+    await mkdir(dirname(target.finalPath), { recursive: true });
+    if (await pathExists(target.finalPath)) {
+        const existing = await hashFile(target.finalPath, target.checksum.algorithm).catch(() => null);
+        if (existing !== target.checksum.value) {
+            await resetOwnedBase(target.basePath).catch(() => undefined);
+            throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, "existing complete file did not match requested payload");
+        }
+        await rm(target.partialPath, { force: true }).catch(() => undefined);
+    }
+    else {
+        await rename(target.partialPath, target.finalPath);
     }
+    const bytes = await statFileSize(target.finalPath);
+    if (bytes == null)
+        throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.STORE_CORRUPT, "complete file is missing after promotion");
+    return bytes;
 }
 function activeKey(target) {
     return `${target.basePath}\0${target.targetKey}\0${target.identityDigest}`;
@@ -768,14 +814,18 @@ export async function downloadCopyAndClear(options) {
         await releaseCopyLease(lease);
     }
 }
-export async function inspectManagedDownload(options) {
-    const target = targetFromOptions({
+/** Resolve a target's paths for callers (inspect/remove) that have no payload; the placeholder never reaches the network. */
+function targetWithoutPayload(options) {
+    return targetFromOptions({
         ...options,
         payload: {
             checksum: { algorithm: "sha256", value: "0".repeat(64) },
             url: "https://example.invalid/",
         },
     });
+}
+export async function inspectManagedDownload(options) {
+    const target = targetWithoutPayload(options);
     await ensureManagedBase(target.basePath);
     const rawManifest = await readManifest(target.manifestPath);
     const manifest = rawManifest === "invalid" ? "unreadable" : rawManifest?.state ?? "missing";
@@ -788,13 +838,7 @@ export async function inspectManagedDownload(options) {
     };
 }
 export async function removeManagedDownload(options) {
-    const target = targetFromOptions({
-        ...options,
-        payload: {
-            checksum: { algorithm: "sha256", value: "0".repeat(64) },
-            url: "https://example.invalid/",
-        },
-    });
+    const target = targetWithoutPayload(options);
     if (activeTargets.has(targetActiveKey(target))) {
         throw new ManagedDownloadError(MANAGED_DOWNLOAD_ERROR_CODES.TARGET_LOCKED, `download target is active: ${target.bucket}/${target.fileName}`);
     }