@angri450/zvec-grep 0.2.2

package/dist/engine/models/artifact-cache-lock.js

@@ -0,0 +1,228 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, rename, rm, rmdir, stat, unlink, utimes, writeFile, } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join } from "node:path";
+export async function acquireModelArtifactCacheLock(lockPath, options) {
+    while (true) {
+        const lock = await tryAcquire(lockPath, options);
+        if (lock) {
+            return lock;
+        }
+        if (await removeAbandonedLock(lockPath, options)) {
+            continue;
+        }
+        await new Promise((resolve) => {
+            options.dependencies.setTimeout(resolve, options.pollMs);
+        });
+    }
+}
+async function tryAcquire(lockPath, options) {
+    try {
+        // Preserve the expiry policy for existing locks, including old empty ones.
+        await lstat(lockPath);
+        return undefined;
+    }
+    catch (error) {
+        if (!isMissingFileError(error)) {
+            throw error;
+        }
+    }
+    const token = randomUUID();
+    const ownerName = `.owner-${token}`;
+    const ownerPath = join(lockPath, ownerName);
+    const stagingPath = `${lockPath}.pending-${process.pid}-${token}`;
+    await mkdir(stagingPath);
+    try {
+        await writeFile(join(stagingPath, ownerName), `${JSON.stringify({ token, pid: process.pid, hostname: hostname(), createdAt: options.dependencies.now() })}\n`, { flag: "wx" });
+        // Publish an already initialized, nonempty directory. Concurrent publishers
+        // cannot replace one another's locks or write owners into a successor's lock.
+        try {
+            await rename(stagingPath, lockPath);
+        }
+        catch (error) {
+            if (await isDirectoryConflict(error, lockPath)) {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    finally {
+        await rm(stagingPath, { recursive: true, force: true });
+    }
+    let lastHeartbeat = options.dependencies.now();
+    let released = false;
+    const refresh = async (force) => {
+        const now = options.dependencies.now();
+        if (!force && now - lastHeartbeat < options.heartbeatMs) {
+            return;
+        }
+        // A replaced directory cannot contain this owner's unique token. Updating
+        // the token file therefore also fences an owner after a stale takeover.
+        await utimes(ownerPath, new Date(now), new Date(now));
+        lastHeartbeat = now;
+    };
+    const lock = {
+        async touch() {
+            await refresh(false);
+        },
+        async assertOwned() {
+            await refresh(true);
+        },
+        async release() {
+            if (released) {
+                return;
+            }
+            released = true;
+            try {
+                await unlink(ownerPath);
+            }
+            catch (error) {
+                if (isMissingFileError(error)) {
+                    return;
+                }
+                throw error;
+            }
+            try {
+                await rmdir(lockPath);
+            }
+            catch (error) {
+                if (!isMissingFileError(error) &&
+                    !isErrorCode(error, "ENOTEMPTY") &&
+                    !isErrorCode(error, "EEXIST")) {
+                    throw error;
+                }
+            }
+        },
+    };
+    try {
+        // Initialization may have been paused for longer than the lease. Refresh on
+        // publication and verify that this owner has not already been displaced.
+        await lock.assertOwned();
+        return lock;
+    }
+    catch (error) {
+        await lock.release().catch(() => undefined);
+        if (isMissingFileError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function isDirectoryConflict(error, path) {
+    if (isErrorCode(error, "EEXIST") || isErrorCode(error, "ENOTEMPTY")) {
+        return true;
+    }
+    // Windows reports EPERM when rename targets an existing directory. Do not
+    // mistake a permission failure with no competing directory for contention.
+    if (isErrorCode(error, "EPERM")) {
+        return await lstat(path).then((stats) => stats.isDirectory(), () => false);
+    }
+    return false;
+}
+async function removeAbandonedLock(lockPath, options) {
+    try {
+        const observed = await inspectLock(lockPath);
+        if (!isAbandoned(observed, options)) {
+            return false;
+        }
+        const stalePath = `${lockPath}.stale-${process.pid}-${randomUUID()}`;
+        await rename(lockPath, stalePath);
+        const moved = await inspectLock(stalePath);
+        if (moved.device !== observed.device ||
+            moved.inode !== observed.inode ||
+            !isAbandoned(moved, options)) {
+            // Another owner may have acquired or refreshed the lock while we were
+            // inspecting it. Restore that directory, never delete its owner file.
+            try {
+                await rename(stalePath, lockPath);
+            }
+            catch (error) {
+                if (!(await isDirectoryConflict(error, lockPath))) {
+                    throw error;
+                }
+                // A successor already owns lockPath. Keep its directory untouched;
+                // the displaced owner is fenced by its missing token at lockPath.
+            }
+            return false;
+        }
+        await rm(stalePath, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return true;
+        }
+        throw error;
+    }
+}
+function isAbandoned(observation, options) {
+    return (observation.deadOwner ||
+        options.dependencies.now() - observation.newestHeartbeat >= options.staleMs);
+}
+async function inspectLock(lockPath) {
+    const lockStats = await stat(lockPath);
+    let newestHeartbeat = lockStats.mtimeMs;
+    const owners = (await readdir(lockPath, { withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.startsWith(".owner-"));
+    for (const owner of owners) {
+        try {
+            const ownerStats = await stat(join(lockPath, owner.name));
+            newestHeartbeat = Math.max(newestHeartbeat, ownerStats.mtimeMs);
+        }
+        catch (error) {
+            if (!isMissingFileError(error)) {
+                throw error;
+            }
+        }
+    }
+    return {
+        device: lockStats.dev,
+        inode: lockStats.ino,
+        newestHeartbeat,
+        deadOwner: owners.length === 1 && (await isKnownDeadOwner(lockPath, owners[0].name)),
+    };
+}
+async function isKnownDeadOwner(lockPath, ownerName) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(join(lockPath, ownerName), "utf8"));
+    }
+    catch (error) {
+        if (isMissingFileError(error) || error instanceof SyntaxError) {
+            return false;
+        }
+        throw error;
+    }
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const owner = value;
+    if (owner.hostname !== hostname() ||
+        typeof owner.token !== "string" ||
+        owner.token.length === 0 ||
+        `.owner-${owner.token}` !== ownerName ||
+        typeof owner.pid !== "number" ||
+        !Number.isSafeInteger(owner.pid) ||
+        owner.pid <= 0 ||
+        owner.pid > 2_147_483_647) {
+        return false;
+    }
+    try {
+        process.kill(owner.pid, 0);
+        return false;
+    }
+    catch (error) {
+        // Only ESRCH proves this local PID has exited. EPERM and all other errors
+        // are inconclusive and retain the ordinary heartbeat expiry period.
+        return isErrorCode(error, "ESRCH");
+    }
+}
+function isMissingFileError(error) {
+    return isErrorCode(error, "ENOENT") || isErrorCode(error, "ENOTDIR");
+}
+function isErrorCode(error, code) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}
+//# sourceMappingURL=artifact-cache-lock.js.map

package/dist/engine/models/artifact-cache-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-cache-lock.js","sourceRoot":"","sources":["../../../src/engine/models/artifact-cache-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,KAAK,EACL,KAAK,EACL,QAAQ,EACR,OAAO,EACP,MAAM,EACN,EAAE,EACF,KAAK,EACL,IAAI,EACJ,MAAM,EACN,MAAM,EACN,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA4BjC,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,QAAgB,EAChB,OAAoB;IAEpB,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACjD,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,MAAM,mBAAmB,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;YACjD,SAAS;QACX,CAAC;QACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAClC,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,KAAK,UAAU,UAAU,CACvB,QAAgB,EAChB,OAAoB;IAEpB,IAAI,CAAC;QACH,2EAA2E;QAC3E,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;IAC3B,MAAM,SAAS,GAAG,UAAU,KAAK,EAAE,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,GAAG,QAAQ,YAAY,OAAO,CAAC,GAAG,IAAI,KAAK,EAAE,CAAC;IAClE,MAAM,KAAK,CAAC,WAAW,CAAC,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,SAAS,CACb,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,EAC5B,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,EAC/G,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;QACF,4EAA4E;QAC5E,8EAA8E;QAC9E,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAC/C,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC;IAC/C,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,OAAO,GAAG,KAAK,EAAE,KAAc,EAAiB,EAAE;QACtD,MAAM,GAAG,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC;QACvC,IAAI,CAAC,KAAK,IAAI,GAAG,GAAG,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YACxD,OAAO;QACT,CAAC;QACD,0EAA0E;QAC1E,wEAAwE;QACxE,MAAM,MAAM,CAAC,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACtD,aAAa,GAAG,GAAG,CAAC;IACtB,CAAC,CAAC;IACF,MAAM,IAAI,GAA2B;QACnC,KAAK,CAAC,KAAK;YACT,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,KAAK,CAAC,WAAW;YACf,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QACD,KAAK,CAAC,OAAO;YACX,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO;YACT,CAAC;YACD,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC9B,OAAO;gBACT,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;YACxB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IACE,CAAC,kBAAkB,CAAC,KAAK,CAAC;oBAC1B,CAAC,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC;oBAChC,CAAC,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,EAC7B,CAAC;oBACD,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;IACF,IAAI,CAAC;QACH,4EAA4E;QAC5E,yEAAyE;QACzE,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,mBAAmB,CAChC,KAAc,EACd,IAAY;IAEZ,IAAI,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,0EAA0E;IAC1E,2EAA2E;IAC3E,IAAI,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;QAChC,OAAO,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAC3B,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,EAC9B,GAAG,EAAE,CAAC,KAAK,CACZ,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,mBAAmB,CAChC,QAAgB,EAChB,OAAoB;IAEpB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC7C,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;YACpC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,SAAS,GAAG,GAAG,QAAQ,UAAU,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,EAAE,CAAC;QACrE,MAAM,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,CAAC;QAC3C,IACE,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;YAChC,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,KAAK;YAC9B,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,EAC5B,CAAC;YACD,sEAAsE;YACtE,sEAAsE;YACtE,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YACpC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,CAAC,MAAM,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;oBAClD,MAAM,KAAK,CAAC;gBACd,CAAC;gBACD,mEAAmE;gBACnE,kEAAkE;YACpE,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAClB,WAA4B,EAC5B,OAAoB;IAEpB,OAAO,CACL,WAAW,CAAC,SAAS;QACrB,OAAO,CAAC,YAAY,CAAC,GAAG,EAAE,GAAG,WAAW,CAAC,eAAe,IAAI,OAAO,CAAC,OAAO,CAC5E,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,QAAgB;IACzC,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,eAAe,GAAG,SAAS,CAAC,OAAO,CAAC;IACxC,MAAM,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CACtE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAC9D,CAAC;IACF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YAC1D,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;QAClE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/B,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO;QACL,MAAM,EAAE,SAAS,CAAC,GAAG;QACrB,KAAK,EAAE,SAAS,CAAC,GAAG;QACpB,eAAe;QACf,SAAS,EACP,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,gBAAgB,CAC7B,QAAgB,EAChB,SAAiB;IAEjB,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACxE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,kBAAkB,CAAC,KAAK,CAAC,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YAC9D,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,KAAgC,CAAC;IAC/C,IACE,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE;QAC7B,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAC/B,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QACxB,UAAU,KAAK,CAAC,KAAK,EAAE,KAAK,SAAS;QACrC,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ;QAC7B,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC;QAChC,KAAK,CAAC,GAAG,IAAI,CAAC;QACd,KAAK,CAAC,GAAG,GAAG,aAAa,EACzB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0EAA0E;QAC1E,oEAAoE;QACpE,OAAO,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,OAAO,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,WAAW,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,WAAW,CAAC,KAAc,EAAE,IAAY;IAC/C,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,IAAI,KAAK;QACf,KAAK,CAAC,IAAI,KAAK,IAAI,CACpB,CAAC;AACJ,CAAC"}

package/dist/engine/models/artifact-downloader.d.ts

@@ -0,0 +1,77 @@
+export type ModelArtifactSourceKind = "huggingface" | "modelscope";
+export type ModelArtifactSource = Readonly<{
+    kind: ModelArtifactSourceKind;
+    repo: string;
+    revision: string;
+    cacheDirectory: string;
+    /** Maps a remote artifact path to a path relative to cacheDirectory. */
+    localPaths?: Readonly<Record<string, string>>;
+}>;
+export type ModelArtifact = Readonly<{
+    path: string;
+    size: number;
+    sha256: string;
+}>;
+export type ModelArtifactDownloadProgress = Readonly<{
+    model: string;
+    source: ModelArtifactSourceKind;
+    artifact: string;
+    downloadedBytes: number;
+    totalBytes: number;
+}>;
+export type ResolvedModelArtifacts = Readonly<{
+    source: ModelArtifactSource;
+    directory: string;
+    /** Absolute local paths keyed by the corresponding remote artifact path. */
+    paths: Readonly<Record<string, string>>;
+}>;
+export type ArtifactDownloadFailureKind = "http" | "network" | "timeout" | "integrity" | "filesystem" | "aborted" | "callback" | "invalid-input";
+export declare class ArtifactDownloadError extends Error {
+    readonly kind: ArtifactDownloadFailureKind;
+    readonly source?: ModelArtifactSourceKind | undefined;
+    readonly artifact?: string | undefined;
+    readonly status?: number | undefined;
+    readonly fallbackAllowed: boolean;
+    constructor(message: string, kind: ArtifactDownloadFailureKind, source?: ModelArtifactSourceKind | undefined, artifact?: string | undefined, status?: number | undefined, options?: ErrorOptions);
+}
+export declare class ModelArtifactResolutionError extends AggregateError {
+    readonly model: string;
+    readonly primaryError: unknown;
+    readonly fallbackError: unknown;
+    constructor(model: string, primaryError: unknown, fallbackError: unknown);
+}
+export declare function isFallbackEligibleArtifactError(error: unknown): boolean;
+export type ArtifactDownloaderDependencies = Readonly<{
+    fetch: typeof globalThis.fetch;
+    setTimeout: (callback: () => void, milliseconds: number) => ReturnType<typeof setTimeout>;
+    clearTimeout: (handle: ReturnType<typeof setTimeout>) => void;
+    now: () => number;
+}>;
+export type ResolveModelArtifactsOptions = Readonly<{
+    model: string;
+    sources: readonly ModelArtifactSource[];
+    artifacts: readonly ModelArtifact[];
+    onProgress?: (progress: ModelArtifactDownloadProgress) => void;
+    /** The verified missing files for this source; resets progress on fallback. */
+    onDownloadPlan?: (artifacts: readonly ModelArtifact[]) => void;
+    onFallback?: (message: string) => void;
+    dependencies?: Partial<ArtifactDownloaderDependencies>;
+    timeouts?: Partial<Readonly<{
+        responseHeaderMs: number;
+        readIdleMs: number;
+    }>>;
+    lock?: Partial<Readonly<{
+        pollMs: number;
+        staleMs: number;
+        heartbeatMs: number;
+    }>>;
+}>;
+/**
+ * Resolves a complete, integrity-checked local artifact snapshot.
+ *
+ * Cache lookup is performed for every source before any network request. Source
+ * order is always Hugging Face followed by ModelScope, independent of the input
+ * array order.
+ */
+export declare function resolveModelArtifacts(options: ResolveModelArtifactsOptions): Promise<ResolvedModelArtifacts>;
+export declare function modelArtifactUrl(source: Pick<ModelArtifactSource, "kind" | "repo" | "revision">, artifactPath: string): string;