@hraness/sponge 0.2.6 → 0.3.0

package/dist/src/models/artifacts.js

@@ -4,18 +4,18 @@ import { dirname, join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { processIdentity, identityAlive } from '../worker/identity.js';
 import { readJournal, writeJournal } from '../worker/journal.js';
+import { acquireIdentityLock } from '../worker/lock.js';
+import { syncDirectoryAsync } from '../util/fsync.js';
 import { privateRoot } from '../acquisition/files.js';
-export class ModelSetupError extends Error {
-    code;
-    constructor(code) {
-        super(code);
-        this.code = code;
-    }
-}
+import { SpongeError, codeOf } from '../errors.js';
 const maximumBytes = 2 * 1024 ** 3;
 function validate(manifest) {
-    if (!/^[a-z0-9][a-z0-9.-]{0,127}$/.test(manifest.id) || !manifest.license || manifest.license.length > 256 || !manifest.artifacts.length || manifest.artifacts.length > 16)
-        throw new ModelSetupError('invalid-input');
+    if (!/^[a-z0-9][a-z0-9.-]{0,127}$/.test(manifest.id) ||
+        !manifest.license ||
+        manifest.license.length > 256 ||
+        !manifest.artifacts.length ||
+        manifest.artifacts.length > 16)
+        throw new SpongeError('invalid-input');
     const names = new Set();
     let bytes = 0;
     for (const artifact of manifest.artifacts) {
@@ -24,49 +24,73 @@ function validate(manifest) {
             url = new URL(artifact.url);
         }
         catch {
-            throw new ModelSetupError('invalid-input');
+            throw new SpongeError('invalid-input');
         }
-        if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(artifact.name) || names.has(artifact.name) || url.protocol !== 'https:' || url.username || url.password || !/^[a-f0-9]{64}$/.test(artifact.sha256) || !Number.isSafeInteger(artifact.bytes) || artifact.bytes < 1 || artifact.bytes > maximumBytes)
-            throw new ModelSetupError('invalid-input');
+        if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(artifact.name) ||
+            names.has(artifact.name) ||
+            url.protocol !== 'https:' ||
+            url.username ||
+            url.password ||
+            !/^[a-f0-9]{64}$/.test(artifact.sha256) ||
+            !Number.isSafeInteger(artifact.bytes) ||
+            artifact.bytes < 1 ||
+            artifact.bytes > maximumBytes)
+            throw new SpongeError('invalid-input');
         names.add(artifact.name);
         bytes += artifact.bytes;
     }
     if (bytes > maximumBytes)
-        throw new ModelSetupError('limit-exceeded');
+        throw new SpongeError('limit-exceeded');
 }
+/** Installed-package identity is content only: artifact names, bytes, sha256 and executable bit. The package id,
+ * license text and per-release download URLs are metadata, so a release that ships byte-identical artifacts keeps
+ * the installed directory. The domain tag keeps these names disjoint from the earlier URL-bound fingerprints. */
 function identity(manifest) {
-    return createHash('sha256').update(JSON.stringify({ id: manifest.id, license: manifest.license, artifacts: manifest.artifacts.map(a => ({ name: a.name, url: a.url, sha256: a.sha256, bytes: a.bytes, executable: !!a.executable })).sort((a, b) => a.name.localeCompare(b.name)) })).digest('hex');
+    return createHash('sha256')
+        .update(JSON.stringify({
+        identity: 'sponge-model-content-v1',
+        artifacts: manifest.artifacts
+            .map((a) => ({ name: a.name, sha256: a.sha256, bytes: a.bytes, executable: !!a.executable }))
+            .sort((a, b) => a.name.localeCompare(b.name)),
+    }))
+        .digest('hex');
 }
 export function modelSetupPlan(manifest) {
     validate(manifest);
     const downloadBytes = manifest.artifacts.reduce((n, a) => n + a.bytes, 0);
-    return { id: manifest.id, license: manifest.license, fingerprint: identity(manifest), downloadBytes, requiredFreeBytes: downloadBytes + 512 * 1024 ** 2, artifacts: manifest.artifacts };
+    return {
+        id: manifest.id,
+        license: manifest.license,
+        fingerprint: identity(manifest),
+        downloadBytes,
+        requiredFreeBytes: downloadBytes + 512 * 1024 ** 2,
+        artifacts: manifest.artifacts,
+    };
 }
-async function syncDirectory(path) { const file = await open(path, constants.O_RDONLY); try {
-    await file.sync();
-}
-finally {
-    await file.close();
-} }
 const uid = () => process.getuid?.();
 const packageName = /^[a-f0-9]{64}$/, linkHolder = /^(?:[a-f0-9]{64}|\.(?:model-install|gc)-[-a-f0-9]{36})$/;
 const missing = (error) => error.code === 'ENOENT';
-async function exists(path) { try {
-    await lstat(path);
-    return true;
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (missing(error))
+            return false;
+        throw error;
+    }
+}
+async function privateDirectory(path) {
+    const stat = await lstat(path);
+    return stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === uid() && (stat.mode & 0o077) === 0;
 }
-catch (error) {
-    if (missing(error))
-        return false;
-    throw error;
-} }
-async function privateDirectory(path) { const stat = await lstat(path); return stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === uid() && (stat.mode & 0o077) === 0; }
 /** A shared artifact inode is trusted only when every one of its links is a top-level file of a private package,
  * stage or GC directory of this cache: nothing outside the private cache can reach (or later rewrite) it. */
 async function linksAccounted(root, stat) {
     if (stat.nlink > 64)
         return false;
-    const holders = (await readdir(root)).filter(name => linkHolder.test(name));
+    const holders = (await readdir(root)).filter((name) => linkHolder.test(name));
     if (holders.length > 256)
         return false;
     let count = 0;
@@ -74,7 +98,7 @@ async function linksAccounted(root, stat) {
         const dir = join(root, name);
         let entries;
         try {
-            if (!await privateDirectory(dir))
+            if (!(await privateDirectory(dir)))
                 continue;
             entries = await readdir(dir);
         }
@@ -105,8 +129,13 @@ async function verifyArtifact(path, artifact, root) {
     const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
         const before = await file.stat();
-        if (!before.isFile() || before.nlink < 1 || before.nlink !== 1 && !(root && await linksAccounted(root, before)) || before.size !== artifact.bytes || (before.mode & 0o077) !== 0 || (artifact.executable && (before.mode & 0o100) === 0))
-            throw new ModelSetupError('integrity');
+        if (!before.isFile() ||
+            before.nlink < 1 ||
+            (before.nlink !== 1 && !(root && (await linksAccounted(root, before)))) ||
+            before.size !== artifact.bytes ||
+            (before.mode & 0o077) !== 0 ||
+            (artifact.executable && (before.mode & 0o100) === 0))
+            throw new SpongeError('integrity');
         const hash = createHash('sha256'), buffer = Buffer.alloc(65536);
         let bytes = 0;
         for (;;) {
@@ -115,12 +144,15 @@ async function verifyArtifact(path, artifact, root) {
                 break;
             bytes += read.bytesRead;
             if (bytes > artifact.bytes)
-                throw new ModelSetupError('integrity');
+                throw new SpongeError('integrity');
             hash.update(buffer.subarray(0, read.bytesRead));
         }
         const after = await file.stat();
-        if (bytes !== artifact.bytes || hash.digest('hex') !== artifact.sha256 || before.mtimeMs !== after.mtimeMs || before.nlink !== after.nlink)
-            throw new ModelSetupError('integrity');
+        if (bytes !== artifact.bytes ||
+            hash.digest('hex') !== artifact.sha256 ||
+            before.mtimeMs !== after.mtimeMs ||
+            before.nlink !== after.nlink)
+            throw new SpongeError('integrity');
     }
     finally {
         await file.close();
@@ -134,21 +166,21 @@ async function writeStaged(path, artifact, chunks, signal) {
     try {
         for await (const chunk of chunks) {
             if (signal?.aborted)
-                throw new ModelSetupError('cancelled');
+                throw new SpongeError('cancelled');
             bytes += chunk.length;
             if (bytes > artifact.bytes)
-                throw new ModelSetupError('integrity');
+                throw new SpongeError('integrity');
             hash.update(chunk);
             let offset = 0;
             while (offset < chunk.length) {
                 const result = await file.write(chunk, offset, chunk.length - offset);
                 if (!result.bytesWritten)
-                    throw new ModelSetupError('unavailable');
+                    throw new SpongeError('unavailable');
                 offset += result.bytesWritten;
             }
         }
         if (bytes !== artifact.bytes || hash.digest('hex') !== artifact.sha256)
-            throw new ModelSetupError('integrity');
+            throw new SpongeError('integrity');
         await file.chmod(artifact.executable ? 0o700 : 0o600);
         await file.sync();
     }
@@ -159,12 +191,19 @@ async function writeStaged(path, artifact, chunks, signal) {
 /** Same name, size and mode class in another installed package that no setup or recovery currently holds. */
 async function reuseCandidates(root, artifact, exclude) {
     const result = [];
-    for (const name of (await readdir(root)).filter(n => packageName.test(n) && n !== exclude).sort()) {
+    for (const name of (await readdir(root)).filter((n) => packageName.test(n) && n !== exclude).sort()) {
         try {
-            if (await exists(join(root, `.${name}.lock`)) || await exists(join(root, `.${name}.recovery-lock`)) || !await privateDirectory(join(root, name)))
+            if ((await exists(join(root, `.${name}.lock`))) ||
+                (await exists(join(root, `.${name}.recovery-lock`))) ||
+                !(await privateDirectory(join(root, name))))
                 continue;
             const s = await lstat(join(root, name, artifact.name));
-            if (s.isFile() && !s.isSymbolicLink() && s.uid === uid() && s.size === artifact.bytes && (s.mode & 0o077) === 0 && !!artifact.executable === ((s.mode & 0o100) !== 0))
+            if (s.isFile() &&
+                !s.isSymbolicLink() &&
+                s.uid === uid() &&
+                s.size === artifact.bytes &&
+                (s.mode & 0o077) === 0 &&
+                !!artifact.executable === ((s.mode & 0o100) !== 0))
                 result.push(join(root, name, artifact.name));
         }
         catch (error) {
@@ -174,14 +213,15 @@ async function reuseCandidates(root, artifact, exclude) {
     }
     return result;
 }
-/** Upgrade reuse: a package whose fingerprint differs only by release URLs carries byte-identical artifacts. A candidate
+/** Upgrade reuse: another installed package (an earlier URL-bound fingerprint, or a partly changed release) may carry
+ * byte-identical artifacts. A candidate
  * is never trusted: it is opened without following links, hard-linked (same inode as the opened file, or undone) or
  * else copied from that descriptor, and the staged file is re-hashed against THIS manifest. Any doubt downloads. */
 async function reuseArtifact(root, stage, artifact, exclude, signal) {
     const target = join(stage, artifact.name), mode = artifact.executable ? 0o700 : 0o600;
     for (const candidate of await reuseCandidates(root, artifact, exclude)) {
         if (signal?.aborted)
-            throw new ModelSetupError('cancelled');
+            throw new SpongeError('cancelled');
         let source;
         try {
             source = await open(candidate, constants.O_RDONLY | constants.O_NOFOLLOW);
@@ -191,7 +231,11 @@ async function reuseArtifact(root, stage, artifact, exclude, signal) {
         }
         try {
             const s = await source.stat();
-            if (!s.isFile() || s.uid !== uid() || s.size !== artifact.bytes || (s.mode & 0o077) !== 0 || !!artifact.executable !== ((s.mode & 0o100) !== 0))
+            if (!s.isFile() ||
+                s.uid !== uid() ||
+                s.size !== artifact.bytes ||
+                (s.mode & 0o077) !== 0 ||
+                !!artifact.executable !== ((s.mode & 0o100) !== 0))
                 continue;
             if ((s.mode & 0o777) === mode) {
                 // A link to anything but the opened inode, or bytes failing this manifest, is undone and the candidate skipped.
@@ -206,7 +250,7 @@ async function reuseArtifact(root, stage, artifact, exclude, signal) {
                     }
                 }
                 catch (error) {
-                    if (linked && !(error instanceof ModelSetupError))
+                    if (linked && !(error instanceof SpongeError))
                         throw error;
                 }
                 if (linked) {
@@ -224,7 +268,7 @@ async function reuseArtifact(root, stage, artifact, exclude, signal) {
             }
             catch (error) {
                 await rm(target, { force: true });
-                if (error instanceof ModelSetupError && error.code === 'cancelled')
+                if (codeOf(error) === 'cancelled')
                     throw error;
             }
         }
@@ -245,94 +289,133 @@ export async function inspectModelPackage(cacheRoot, manifest) {
     }
     return paths;
 }
-const pending = () => { throw new ModelSetupError('cleanup-required'); };
-async function sameFile(a, b) { try {
-    const [x, y] = await Promise.all([lstat(a), lstat(b)]);
-    if (!x.isFile() || !y.isFile() || x.isSymbolicLink() || y.isSymbolicLink() || x.ino !== y.ino || x.dev !== y.dev)
+const pending = () => {
+    throw new SpongeError('cleanup-required');
+};
+async function sameFile(a, b) {
+    try {
+        const [x, y] = await Promise.all([lstat(a), lstat(b)]);
+        if (!x.isFile() || !y.isFile() || x.isSymbolicLink() || y.isSymbolicLink() || x.ino !== y.ino || x.dev !== y.dev)
+            pending();
+    }
+    catch {
+        return pending();
+    }
+}
+async function readOwner(path, fingerprint) {
+    const owner = (await readJournal(path));
+    if (owner.schemaVersion !== 1 ||
+        owner.fingerprint !== fingerprint ||
+        !/^[-a-f0-9]{36}$/.test(owner.incarnation) ||
+        owner.stage !== '.model-install-' + owner.incarnation ||
+        !owner.identity ||
+        !Number.isSafeInteger(owner.identity.pid) ||
+        owner.identity.pid < 1 ||
+        owner.identity.uid !== process.getuid?.() ||
+        typeof owner.identity.started !== 'string' ||
+        !owner.identity.started.trim())
         pending();
+    return owner;
 }
-catch {
-    return pending();
-} }
-async function readOwner(path, fingerprint) { const owner = await readJournal(path); if (owner.schemaVersion !== 1 || owner.fingerprint !== fingerprint || !/^[-a-f0-9]{36}$/.test(owner.incarnation) || owner.stage !== '.model-install-' + owner.incarnation || !owner.identity || !Number.isSafeInteger(owner.identity.pid) || owner.identity.pid < 1 || owner.identity.uid !== process.getuid?.() || typeof owner.identity.started !== 'string' || !owner.identity.started.trim())
-    pending(); return owner; }
-async function cleanupStage(root, owner, file) { const stage = join(root, owner.stage); let stat; try {
-    stat = await lstat(stage);
+async function cleanupStage(root, owner, file) {
+    const stage = join(root, owner.stage);
+    let stat;
+    try {
+        stat = await lstat(stage);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        stat.uid !== process.getuid?.() ||
+        (stat.mode & 0o077) !== 0 ||
+        (await realpath(stage)) !== stage)
+        pending();
+    const entries = await readdir(stage);
+    if (entries.length) {
+        await sameFile(file, join(stage, 'ownership.json'));
+    }
+    await rm(stage, { recursive: true });
+    await syncDirectoryAsync(root);
 }
-catch (error) {
-    if (error.code === 'ENOENT')
-        return;
-    throw error;
-} if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || await realpath(stage) !== stage)
-    pending(); const entries = await readdir(stage); if (entries.length) {
-    await sameFile(file, join(stage, 'ownership.json'));
-} await rm(stage, { recursive: true }); await syncDirectory(root); }
 /** Explicit recovery only: an absent or different process birth identity proves the downloader is gone.
  * Downloading is in-process fetch; no native child can outlive this owner. A missing or
- * foreign stage receipt remains pending, as does an interrupted recovery guard. */
+ * foreign stage receipt remains pending, as does a recovery guard held by a live or unknown recoverer. The guard names
+ * the recovering process, so a recovery that itself died is taken over on exact proof of that death. */
+async function recoveryGuard(guard) {
+    try {
+        return await acquireIdentityLock(guard);
+    }
+    catch (error) {
+        const code = codeOf(error);
+        if (code === 'owner-busy')
+            return pending();
+        if (code === 'unavailable')
+            throw new SpongeError('unavailable');
+        throw error;
+    }
+}
 export async function recoverModelPackage(cacheRoot, manifest) {
-    const plan = modelSetupPlan(manifest), root = await privateRoot(cacheRoot), lock = join(root, `.${plan.fingerprint}.lock`);
+    const plan = modelSetupPlan(manifest), root = await privateRoot(cacheRoot), lock = join(root, `.${plan.fingerprint}.lock`), guard = join(root, `.${plan.fingerprint}.recovery-lock`);
     let owner;
+    // A recovery that died after unlinking the owner lock leaves only its guard: clear it when its holder is provably dead.
     try {
         owner = await readOwner(lock, plan.fingerprint);
     }
     catch (error) {
-        if (error.code === 'ENOENT')
+        if (error.code === 'ENOENT') {
+            if (await exists(guard))
+                await (await recoveryGuard(guard)).release();
             return { recovered: false };
+        }
         return pending();
     }
     try {
         if (await identityAlive(owner.identity))
-            throw new ModelSetupError('owner-busy');
+            throw new SpongeError('owner-busy');
     }
     catch (error) {
-        if (error instanceof ModelSetupError)
+        if (codeOf(error) === 'owner-busy')
             throw error;
         return pending();
     }
-    const file = join(root, `.model-owner-${owner.incarnation}.json`), guard = join(root, `.${plan.fingerprint}.recovery-lock`);
+    const file = join(root, `.model-owner-${owner.incarnation}.json`);
     await sameFile(file, lock);
-    try {
-        await link(file, guard);
-        await syncDirectory(root);
-    }
-    catch (error) {
-        if (error.code === 'EEXIST')
-            return pending();
-        throw error;
-    }
+    const held = await recoveryGuard(guard);
     try {
         await sameFile(file, lock);
         if (await identityAlive(owner.identity))
-            throw new ModelSetupError('owner-busy');
+            throw new SpongeError('owner-busy');
         await cleanupStage(root, owner, file);
         await sameFile(file, lock);
         await unlink(lock);
-        await syncDirectory(root);
+        await syncDirectoryAsync(root);
         return { recovered: true };
     }
     finally {
-        await sameFile(file, guard);
-        await unlink(guard);
-        await syncDirectory(root);
+        await held.release();
         try {
             await lstat(lock);
         }
         catch (error) {
             if (error.code === 'ENOENT') {
                 await unlink(file);
-                await syncDirectory(root);
+                await syncDirectoryAsync(root);
             }
             else
                 throw error;
         }
     }
 }
-/** Explicit setup only. Never called by install hooks or by inference fallback. */
+/** Explicit setup only. Never called by install hooks or by inference fallback, except `reuseOnly`: that adopts an
+ * installed package from verified local artifacts under the same setup lock and never reaches the network. */
 export async function provisionModelPackage(cacheRoot, manifest, options = {}) {
     const plan = modelSetupPlan(manifest), root = await privateRoot(cacheRoot), destination = join(root, plan.fingerprint);
     if (options.signal?.aborted)
-        throw new ModelSetupError('cancelled');
+        throw new SpongeError('cancelled');
     try {
         await lstat(destination);
         return await inspectModelPackage(root, manifest);
@@ -341,25 +424,36 @@ export async function provisionModelPackage(cacheRoot, manifest, options = {}) {
         if (error.code !== 'ENOENT')
             throw error;
     }
+    // Nothing to adopt takes no lock and writes nothing.
+    if (options.reuseOnly)
+        for (const artifact of manifest.artifacts)
+            if (!(await reuseCandidates(root, artifact, plan.fingerprint)).length)
+                throw new SpongeError('unavailable');
     const lock = join(root, `.${plan.fingerprint}.lock`), incarnation = randomUUID(), ownerFile = join(root, `.model-owner-${incarnation}.json`);
     const identity = await processIdentity(process.pid);
     if (!identity)
         pending();
-    const owner = { schemaVersion: 1, incarnation, fingerprint: plan.fingerprint, stage: '.model-install-' + incarnation, identity: identity };
+    const owner = {
+        schemaVersion: 1,
+        incarnation,
+        fingerprint: plan.fingerprint,
+        stage: '.model-install-' + incarnation,
+        identity: identity,
+    };
     await writeJournal(ownerFile, owner);
     let linked = false;
     try {
         await link(ownerFile, lock);
         linked = true;
-        await syncDirectory(root);
+        await syncDirectoryAsync(root);
     }
     catch (error) {
         if (linked)
             return pending();
         await unlink(ownerFile);
-        await syncDirectory(root);
+        await syncDirectoryAsync(root);
         if (error.code === 'EEXIST')
-            throw new ModelSetupError('owner-busy');
+            throw new SpongeError('owner-busy');
         throw error;
     }
     let stage;
@@ -371,38 +465,42 @@ export async function provisionModelPackage(cacheRoot, manifest, options = {}) {
                 needed += artifact.bytes;
         const disk = await statfs(root);
         if (disk.bavail * disk.bsize < needed)
-            throw new ModelSetupError('limit-exceeded');
+            throw new SpongeError('limit-exceeded');
         stage = join(root, owner.stage);
         await mkdir(stage, { mode: 0o700 });
         await chmod(stage, 0o700);
         await link(ownerFile, join(stage, 'ownership.json'));
-        await syncDirectory(stage);
-        await syncDirectory(root);
+        await syncDirectoryAsync(stage);
+        await syncDirectoryAsync(root);
         for (const artifact of manifest.artifacts) {
             if (await reuseArtifact(root, stage, artifact, plan.fingerprint, options.signal))
                 continue;
-            const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(600000)]) : AbortSignal.timeout(600000);
+            if (options.reuseOnly)
+                throw new SpongeError('unavailable');
+            const signal = options.signal
+                ? AbortSignal.any([options.signal, AbortSignal.timeout(600000)])
+                : AbortSignal.timeout(600000);
             const response = await (options.fetch ?? fetch)(artifact.url, { signal });
             if (!response.ok || !response.body || (response.url && new URL(response.url).protocol !== 'https:'))
-                throw new ModelSetupError('unavailable');
+                throw new SpongeError('unavailable');
             const declared = response.headers.get('content-length');
             if (declared !== null && Number(declared) !== artifact.bytes) {
                 await response.body.cancel();
-                throw new ModelSetupError('integrity');
+                throw new SpongeError('integrity');
             }
             await writeStaged(join(stage, artifact.name), artifact, response.body, signal);
         }
         if (options.signal?.aborted)
-            throw new ModelSetupError('cancelled');
-        await syncDirectory(stage);
+            throw new SpongeError('cancelled');
+        await syncDirectoryAsync(stage);
         await rename(stage, destination);
         stage = undefined;
-        await syncDirectory(root);
+        await syncDirectoryAsync(root);
         return await inspectModelPackage(root, manifest);
     }
     catch (error) {
         if (options.signal?.aborted)
-            throw new ModelSetupError('cancelled');
+            throw new SpongeError('cancelled');
         throw error;
     }
     finally {
@@ -411,6 +509,39 @@ export async function provisionModelPackage(cacheRoot, manifest, options = {}) {
         await sameFile(ownerFile, lock);
         await unlink(lock);
         await unlink(ownerFile);
-        await syncDirectory(root);
+        await syncDirectoryAsync(root);
+    }
+}
+const absent = (error) => error.code === 'ENOENT';
+/** The installed package for this manifest, by content, or null when none is. A package installed under an earlier
+ * URL-bound fingerprint is adopted once: its verified artifacts are hard-linked into the content-named directory under
+ * the setup lock (no network; the old directory stays intact for any process holding its paths until runtime GC
+ * supersedes it). Anything short of a fully verified adoption is reported as not installed, as before. */
+export async function inspectInstalledModelPackage(cacheRoot, manifest, options = {}) {
+    try {
+        return await inspectModelPackage(cacheRoot, manifest);
     }
+    catch (error) {
+        if (!absent(error))
+            throw error;
+    }
+    try {
+        return await provisionModelPackage(cacheRoot, manifest, { reuseOnly: true });
+    }
+    catch (error) {
+        if (codeOf(error) !== 'owner-busy')
+            return null;
+    }
+    // A concurrent adoption or setup of this package is linking or downloading: briefly wait for its verified result.
+    for (let i = 0; i < 20; i++) {
+        await (options.pause ?? ((ms) => new Promise((r) => setTimeout(r, ms))))(100);
+        try {
+            return await inspectModelPackage(cacheRoot, manifest);
+        }
+        catch (error) {
+            if (!absent(error))
+                throw error;
+        }
+    }
+    return null;
 }

package/dist/src/models/catalog.d.ts

@@ -2,7 +2,7 @@ import type { ModelPackage } from './artifacts.js';
 export type NativeKind = 'asr' | 'embedding';
 export type NativeRole = 'asr-helper' | 'embedding-helper' | 'embedding-library' | 'notices';
 export declare const nativeAssetNames: Record<NativeRole, string>;
-export interface NativeArtifact {
+interface NativeArtifact {
     role: NativeRole;
     name: string;
     bytes: number;
@@ -23,13 +23,10 @@ export interface NativeCatalog {
         clangVersion: string;
     };
 }
-export declare class NativeCatalogError extends Error {
-    readonly code: 'runtime-missing' | 'unsupported' | 'integrity';
-    constructor(code: 'runtime-missing' | 'unsupported' | 'integrity');
-}
 /** Package-embedded release hashes are authority; local probe helper hashes never enter this catalog. */
 export declare function parseNativeCatalog(value: unknown, expectedVersion: string): NativeCatalog;
 export declare function nativePlatformSupported(platform?: NodeJS.Platform, architecture?: NodeJS.Architecture, kernel?: string): boolean;
 export declare function nativeCatalogPath(): string;
 export declare function loadNativeCatalog(expectedVersion: string, path?: string): Promise<NativeCatalog>;
 export declare function nativeModelPackage(catalog: NativeCatalog, kind: NativeKind): ModelPackage;
+export {};