@hraness/sponge 0.3.5 → 0.4.1

package/dist/src/digest/runner.js

@@ -0,0 +1,82 @@
+import { inspectDigest } from '../models/digest.js';
+import { withDigestServer } from './server.js';
+import { createDigest } from './pipeline.js';
+import { codeOf } from '../errors.js';
+const minute = 60000;
+/** How long ready jobs wait when drafting cannot start, by cause. Nothing reached the model, so no attempt is counted. */
+const postponeMs = {
+    'model-busy': 5 * minute,
+    'model-unavailable': 30 * minute,
+    'runtime-missing': 60 * minute,
+    unsupported: 60 * minute,
+};
+const at = (ms) => new Date(Date.now() + ms).toISOString();
+/**
+ * Draft queued digests with one Sponge-owned server per drain (`withDigestServer`), claiming jobs under the worker lease
+ * until the queue is empty, the budget is spent or the signal aborts. Never throws for a missing runtime, a busy GPU or
+ * a server that would not start: the ready jobs are postponed with that reason, so capture and indexing keep running.
+ * `cleanup-required` and `owner-busy` still throw, as the service loop expects.
+ */
+export async function drainDigestQueue(store, options) {
+    if (options.signal?.aborted || !store.digests.due())
+        return [];
+    const settings = store.digests.settings(), results = [], deadline = Date.now() + (options.budgetMs ?? 10 * minute), create = options.create ?? createDigest;
+    const postpone = (code) => [
+        { ok: false, code, postponed: store.digests.postpone(code, at(postponeMs[code] ?? 6 * 60 * minute)) },
+    ];
+    let runtime;
+    try {
+        runtime = await (options.inspect ?? inspectDigest)(options.nativeRoot, settings.model ?? undefined);
+    }
+    catch (error) {
+        return postpone(codeOf(error));
+    }
+    try {
+        await withDigestServer(store.root, runtime, async (model, { incarnation }) => {
+            const owner = store.queue.acquireOwner(incarnation);
+            try {
+                while (!options.signal?.aborted && Date.now() < deadline) {
+                    const claim = store.digests.claim(owner);
+                    if (!claim)
+                        break;
+                    try {
+                        const { derivation, duplicate } = await create(store, claim.itemId, model, { signal: options.signal });
+                        store.digests.finish(claim, { derivationId: derivation.id });
+                        results.push({ ok: true, jobId: claim.jobId, digestId: derivation.id, duplicate });
+                    }
+                    catch (error) {
+                        const code = codeOf(error);
+                        if (code === 'cleanup-required')
+                            throw error;
+                        // A cancelled draft goes back to the queue as it was; a server that stopped answering ends the drain.
+                        if (options.signal?.aborted)
+                            store.digests.finish(claim, {
+                                reason: 'cancelled',
+                                retryable: true,
+                                countAttempt: false,
+                                notBefore: at(0),
+                            });
+                        else
+                            store.digests.finish(claim, { reason: code, retryable: code === 'model-unavailable' });
+                        results.push({ ok: false, jobId: claim.jobId, code });
+                        if (options.signal?.aborted || code === 'model-unavailable')
+                            break;
+                    }
+                }
+            }
+            finally {
+                store.queue.releaseOwner(owner);
+            }
+        }, { ...options.server, signal: options.signal });
+    }
+    catch (error) {
+        const code = codeOf(error);
+        if (code === 'cleanup-required' || code === 'owner-busy')
+            throw error;
+        // Before any claim, the server would not start or verify. After one, every job is settled already.
+        if (!results.length)
+            return postpone(code);
+        results.push({ ok: false, code });
+    }
+    return results;
+}

package/dist/src/digest/server.d.ts

@@ -0,0 +1,40 @@
+import type { ProcessRunner } from '../worker/supervisor.js';
+import { type DigestRuntime } from '../models/digest.js';
+import type { DigestModel } from './pipeline.js';
+/**
+ * The Sponge-owned digest server: the verified llama.cpp archive is unpacked into the attempt's scratch root and
+ * `llama-server` runs under `sandbox-exec` with outbound connections other than loopback denied, bound to 127.0.0.1
+ * on a free port, through the caller's process runner (the worker supervisor), so the server's process group is
+ * collected and proved like any helper even if this process dies. Captured text never leaves the machine.
+ */
+export declare const sandboxProfile = "(version 1) (allow default) (deny network-outbound (remote ip \"*:*\")) (allow network-outbound (remote ip \"localhost:*\"))";
+/** Other `llama-server` processes in `ps -axo pid=,command=` output, with the model each loaded when it names one. */
+export declare function otherServers(ps: string, self?: number): {
+    pid: number;
+    model?: string;
+}[];
+/** An ephemeral loopback port; the kernel picks one that is free now. */
+export declare function freePort(): Promise<number>;
+export interface DigestServerOptions {
+    runProcess: ProcessRunner;
+    /** A private directory owned by the caller's attempt; removed by the caller after `stop`. */
+    scratchRoot: string;
+    signal?: AbortSignal;
+    ctx?: number;
+    readyTimeoutMs?: number;
+    /** Longest a server may run before the runner stops it. */
+    lifetimeMs?: number;
+    processes?: () => Promise<string>;
+    /** The executable inside the archive's directory; tests substitute a fake. */
+    executable?: string;
+    sandbox?: boolean;
+}
+/**
+ * Run `fn` against a Sponge-owned server for `runtime`, held as a `digest-server` attempt under worker custody: the
+ * server is stopped and its process group proved collected before custody is released.
+ */
+export declare function withDigestServer<T>(libraryRoot: string, runtime: DigestRuntime, fn: (model: DigestModel, custody: {
+    incarnation: string;
+}) => Promise<T>, options?: {
+    signal?: AbortSignal;
+} & Partial<Omit<DigestServerOptions, 'runProcess' | 'scratchRoot'>>): Promise<T>;

package/dist/src/digest/server.js

@@ -0,0 +1,166 @@
+import { execFile } from 'node:child_process';
+import { lstat, readdir, realpath } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { join } from 'node:path';
+import { directory } from '../worker/journal.js';
+import { llamaRuntimePin } from '../models/digest.js';
+import { withTransientAttempt } from '../worker/transient.js';
+import { connectEndpoint } from './endpoint.js';
+import { SpongeError } from '../errors.js';
+/**
+ * The Sponge-owned digest server: the verified llama.cpp archive is unpacked into the attempt's scratch root and
+ * `llama-server` runs under `sandbox-exec` with outbound connections other than loopback denied, bound to 127.0.0.1
+ * on a free port, through the caller's process runner (the worker supervisor), so the server's process group is
+ * collected and proved like any helper even if this process dies. Captured text never leaves the machine.
+ */
+export const sandboxProfile = '(version 1) (allow default) (deny network-outbound (remote ip "*:*")) (allow network-outbound (remote ip "localhost:*"))';
+/** Other `llama-server` processes in `ps -axo pid=,command=` output, with the model each loaded when it names one. */
+export function otherServers(ps, self = process.pid) {
+    return ps.split('\n').flatMap((line) => {
+        const m = /^\s*(\d+)\s+(\S*llama-server)(\s.*)?$/.exec(line);
+        if (!m || Number(m[1]) === self)
+            return [];
+        const model = /\s(?:-m|--model)\s+(\S+)/.exec(m[3] ?? '')?.[1];
+        return [{ pid: Number(m[1]), ...(model ? { model: model.split('/').pop() } : {}) }];
+    });
+}
+const listProcesses = () => new Promise((ok, fail) => execFile('/bin/ps', ['-axo', 'pid=,command='], { maxBuffer: 16 * 1024 ** 2 }, (e, out) => (e ? fail(e) : ok(out))));
+/** An ephemeral loopback port; the kernel picks one that is free now. */
+export function freePort() {
+    return new Promise((ok, fail) => {
+        const s = createServer();
+        s.once('error', fail);
+        s.listen(0, '127.0.0.1', () => {
+            const port = s.address().port;
+            s.close(() => ok(port));
+        });
+    });
+}
+/** Every unpacked entry is a file, directory or a symlink resolving inside `root`. */
+async function confined(root, dir = root) {
+    for (const name of await readdir(dir)) {
+        const path = join(dir, name), s = await lstat(path);
+        if (s.isDirectory())
+            await confined(root, path);
+        else if (s.isSymbolicLink()) {
+            if (!(await realpath(path)).startsWith(root + '/'))
+                throw new SpongeError('integrity');
+        }
+        else if (!s.isFile())
+            throw new SpongeError('integrity');
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function startDigestServer(runtime, o) {
+    const [other] = otherServers(await (o.processes ?? listProcesses)());
+    // Two loaded models exhaust GPU memory and every request fails; wait for the other server instead.
+    if (other)
+        throw new SpongeError('model-busy', { detail: { pid: other.pid } });
+    const unpacked = await directory(join(o.scratchRoot, 'llama')), env = { PATH: '/usr/bin:/bin', HOME: o.scratchRoot, TMPDIR: o.scratchRoot, LANG: 'en_US.UTF-8' };
+    const tar = await o.runProcess('/usr/bin/tar', ['-xzf', runtime.archive, '-C', unpacked, '--no-same-owner'], {
+        env,
+        signal: o.signal,
+        deadlineMs: 120000,
+        maxOutputBytes: 65536,
+    });
+    if (tar.stopped === 'cancelled')
+        throw new SpongeError('cancelled');
+    if (tar.cleanup !== 'settled')
+        throw new SpongeError('cleanup-required');
+    if (tar.code !== 0 || tar.stopped)
+        throw new SpongeError('integrity');
+    await confined(await realpath(unpacked));
+    const server = join(unpacked, llamaRuntimePin.directory, o.executable ?? 'llama-server'), s = await lstat(server).catch(() => undefined);
+    if (!s?.isFile() || !(s.mode & 0o100))
+        throw new SpongeError('integrity');
+    const port = await freePort(), args = [
+        '-m',
+        runtime.model,
+        '--alias',
+        runtime.pin.alias,
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(port),
+        '-c',
+        String(o.ctx ?? 16384),
+        '-np',
+        '1',
+        '--jinja',
+        '--reasoning',
+        'off',
+        '--offline',
+        '--no-webui',
+        '--log-disable',
+    ];
+    const own = new AbortController(), signal = o.signal ? AbortSignal.any([o.signal, own.signal]) : own.signal, sandbox = o.sandbox ?? true;
+    let result;
+    const run = o
+        .runProcess(sandbox ? '/usr/bin/sandbox-exec' : server, sandbox ? ['-p', sandboxProfile, server, ...args] : args, {
+        env,
+        signal,
+        deadlineMs: o.lifetimeMs ?? 6 * 3600 * 1000,
+        maxOutputBytes: 4 * 1024 ** 2,
+        graceMs: 5000,
+    })
+        .then((r) => (result = r));
+    let stopping;
+    const endpoint = `http://127.0.0.1:${port}`, handle = {
+        endpoint,
+        model: runtime.pin.alias,
+        stop: () => (stopping ??= (async () => {
+            own.abort();
+            return (await run).cleanup;
+        })()),
+    };
+    const deadline = Date.now() + (o.readyTimeoutMs ?? 180000);
+    try {
+        while (Date.now() < deadline) {
+            if (o.signal?.aborted)
+                throw new SpongeError('cancelled');
+            if (result)
+                throw new SpongeError('model-unavailable', { detail: { exited: result.code } });
+            // `/health` can answer before the model is listed; ready means both.
+            const models = await fetch(`${endpoint}/health`, { redirect: 'error', signal: AbortSignal.timeout(2000) })
+                .then(async (r) => {
+                await r.body?.cancel().catch(() => undefined);
+                if (!r.ok)
+                    return undefined;
+                const m = await fetch(`${endpoint}/v1/models`, { redirect: 'error', signal: AbortSignal.timeout(2000) });
+                return m.ok ? (await m.json()) : undefined;
+            })
+                .catch(() => undefined);
+            if (models?.data?.some((m) => m?.id === runtime.pin.alias))
+                return handle;
+            await sleep(200);
+        }
+        throw new SpongeError('model-unavailable', { detail: { ready: false } });
+    }
+    catch (error) {
+        if ((await handle.stop()) === 'pending')
+            throw new SpongeError('cleanup-required', { cause: error });
+        throw error;
+    }
+}
+/**
+ * Run `fn` against a Sponge-owned server for `runtime`, held as a `digest-server` attempt under worker custody: the
+ * server is stopped and its process group proved collected before custody is released.
+ */
+export function withDigestServer(libraryRoot, runtime, fn, options = {}) {
+    return withTransientAttempt(libraryRoot, 'digest-server', async ({ scratchRoot, runProcess, incarnation }) => {
+        const server = await startDigestServer(runtime, { ...options, runProcess, scratchRoot });
+        let result;
+        try {
+            const model = await connectEndpoint({ endpoint: server.endpoint, model: server.model, signal: options.signal });
+            // The identity must be the pinned build, so a digest's input hash names what drafted it.
+            if (!model.identity.runtime.includes(String(llamaRuntimePin.build)))
+                throw new SpongeError('integrity');
+            result = await fn(model, { incarnation });
+        }
+        finally {
+            if ((await server.stop()) === 'pending')
+                throw new SpongeError('cleanup-required');
+        }
+        return result;
+    });
+}

package/dist/src/errors.d.ts

@@ -18,6 +18,8 @@ declare const parents: {
     readonly 'no-capture': "invalid-input";
     readonly 'draft-rejected': "unavailable";
     readonly 'model-unavailable': "unavailable";
+    readonly 'model-busy': "unavailable";
+    readonly 'source-too-thin': "unavailable";
     readonly 'parent-missing': "invalid-input";
     readonly 'target-exists': "invalid-input";
 };

package/dist/src/errors.js

@@ -32,6 +32,8 @@ const parents = {
     'no-capture': 'invalid-input',
     'draft-rejected': 'unavailable',
     'model-unavailable': 'unavailable',
+    'model-busy': 'unavailable',
+    'source-too-thin': 'unavailable',
     'parent-missing': 'invalid-input',
     'target-exists': 'invalid-input',
 };
@@ -83,6 +85,8 @@ export const hints = {
 export const detailHints = {
     'draft-rejected': 'The model draft failed the digest checks listed above, even after one repair. Drafting is deterministic, so the same capture and model fail again; refresh the item or use another model.',
     'model-unavailable': 'The model server did not answer or returned an error. Check that it is still running and has free GPU memory (another loaded model can exhaust it), then retry.',
+    'source-too-thin': 'The capture holds too little text to digest: under 20 words of prose, or only an archive’s metadata. Refresh the item when a fuller capture is possible.',
+    'model-busy': 'Another llama-server is running, and two loaded models can exhaust GPU memory. Wait for it to exit, then retry.',
 };
 /** The one error type. `message` is the code, so bare `String(error)` never carries detail, paths or causes. */
 export class SpongeError extends Error {

package/dist/src/importers/custody.d.ts

@@ -1,6 +1,3 @@
-import { supervisedRunner } from '../worker/supervisor.js';
+import { type TransientAttempt } from '../worker/transient.js';
 /** Read-only verification still owns subprocesses, including during an import preview. */
-export declare function withImportVerification<T>(libraryRoot: string, verify: (context: {
-    scratchRoot: string;
-    runProcess: ReturnType<typeof supervisedRunner>;
-}) => Promise<T>): Promise<T>;
+export declare function withImportVerification<T>(libraryRoot: string, verify: (context: Pick<TransientAttempt, 'scratchRoot' | 'runProcess'>) => Promise<T>): Promise<T>;

package/dist/src/importers/custody.js

@@ -1,53 +1,5 @@
-import { randomUUID } from 'node:crypto';
-import { join } from 'node:path';
-import { rm } from 'node:fs/promises';
-import { acquireWorkerCustody, proveAttemptCleanup } from '../worker/custody.js';
-import { directory, writeJournal, readJournal } from '../worker/journal.js';
-import { syncDirectoryAsync } from '../util/fsync.js';
-import { supervisedRunner } from '../worker/supervisor.js';
-import { SpongeError, codeOf } from '../errors.js';
-const pending = () => new SpongeError('cleanup-required');
+import { withTransientAttempt } from '../worker/transient.js';
 /** Read-only verification still owns subprocesses, including during an import preview. */
-export async function withImportVerification(libraryRoot, verify) {
-    const custody = await acquireWorkerCustody(libraryRoot), attemptId = randomUUID();
-    let scratchRoot, unknown = false;
-    try {
-        const attempt = await directory(join(custody.directory, 'attempts', attemptId));
-        await writeJournal(join(attempt, 'import-verification.json'), {
-            schemaVersion: 1,
-            kind: 'import-verification',
-            attemptId,
-            ownerIncarnation: custody.incarnation,
-        });
-        scratchRoot = await directory(join(libraryRoot, 'staging', 'import-verification-' + attemptId));
-        await writeJournal(join(scratchRoot, 'ownership.json'), {
-            schemaVersion: 1,
-            kind: 'import-verification',
-            requestId: attemptId,
-            ownerIncarnation: custody.incarnation,
-        });
-        return await verify({
-            scratchRoot,
-            runProcess: supervisedRunner(custody.directory, custody.incarnation, attemptId),
-        });
-    }
-    catch (error) {
-        unknown = codeOf(error) === 'cleanup-required';
-        throw error;
-    }
-    finally {
-        if (unknown || !(await proveAttemptCleanup(custody.directory, custody.incarnation, attemptId)))
-            throw pending();
-        if (scratchRoot) {
-            const marker = await readJournal(join(scratchRoot, 'ownership.json'));
-            if (marker.schemaVersion !== 1 ||
-                marker.kind !== 'import-verification' ||
-                marker.requestId !== attemptId ||
-                marker.ownerIncarnation !== custody.incarnation)
-                throw pending();
-            await rm(scratchRoot, { recursive: true });
-            await syncDirectoryAsync(join(libraryRoot, 'staging'));
-        }
-        await custody.release();
-    }
+export function withImportVerification(libraryRoot, verify) {
+    return withTransientAttempt(libraryRoot, 'import-verification', ({ scratchRoot, runProcess }) => verify({ scratchRoot, runProcess }));
 }

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

@@ -9,6 +9,8 @@ export interface ModelPackage {
     id: string;
     license: string;
     artifacts: readonly ModelArtifact[];
+    /** Per-artifact and per-package byte limit; 2 GiB unless a package that needs more (a local LLM) says so. */
+    maximumBytes?: number;
 }
 export declare function modelSetupPlan(manifest: ModelPackage): {
     id: string;
@@ -28,6 +30,9 @@ export declare function provisionModelPackage(cacheRoot: string, manifest: Model
     signal?: AbortSignal;
     fetch?: typeof fetch;
     reuseOnly?: boolean;
+    /** Local files to adopt by artifact name instead of downloading; cloned or copied, verified, never modified. */
+    adopt?: Readonly<Record<string, string>>;
+    idleMs?: number;
 }): Promise<Record<string, string>>;
 /** 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

package/dist/src/models/artifacts.js

@@ -1,5 +1,5 @@
 import { constants } from 'node:fs';
-import { chmod, lstat, mkdir, open, rename, rm, statfs, link, unlink, readdir, realpath } from 'node:fs/promises';
+import { chmod, copyFile, lstat, mkdir, open, rename, rm, statfs, link, unlink, readdir, realpath, } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { processIdentity, identityAlive } from '../worker/identity.js';
@@ -8,9 +8,15 @@ import { acquireIdentityLock } from '../worker/lock.js';
 import { syncDirectoryAsync } from '../util/fsync.js';
 import { privateRoot } from '../acquisition/files.js';
 import { SpongeError, codeOf } from '../errors.js';
-const maximumBytes = 2 * 1024 ** 3;
+const defaultMaximumBytes = 2 * 1024 ** 3, packageCeiling = 64 * 1024 ** 3;
+/** A download fails after this long without a byte, and after its size at 1 MB/s (at least 10 minutes) in all. */
+const idleMs = 120000, downloadDeadline = (bytes) => Math.max(600000, bytes / 1000);
 function validate(manifest) {
-    if (!/^[a-z0-9][a-z0-9.-]{0,127}$/.test(manifest.id) ||
+    const maximumBytes = manifest.maximumBytes ?? defaultMaximumBytes;
+    if (!Number.isSafeInteger(maximumBytes) ||
+        maximumBytes < 1 ||
+        maximumBytes > packageCeiling ||
+        !/^[a-z0-9][a-z0-9.-]{0,127}$/.test(manifest.id) ||
         !manifest.license ||
         manifest.license.length > 256 ||
         !manifest.artifacts.length ||
@@ -125,10 +131,14 @@ async function linksAccounted(root, stat) {
     }
     return count === stat.nlink;
 }
+/** Files this process already hashed, by inode and change time (which user space cannot set back): a worker
+ * re-verifies a 17 GB model by stat after the first time. Any change to the file, its links or its mode misses. */
+const verified = new Map();
+const statKey = (s) => [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs, s.nlink, s.mode].join(':');
 async function verifyArtifact(path, artifact, root) {
     const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
-        const before = await file.stat();
+        const before = await file.stat(), key = statKey(await file.stat({ bigint: true }));
         if (!before.isFile() ||
             before.nlink < 1 ||
             (before.nlink !== 1 && !(root && (await linksAccounted(root, before)))) ||
@@ -136,6 +146,9 @@ async function verifyArtifact(path, artifact, root) {
             (before.mode & 0o077) !== 0 ||
             (artifact.executable && (before.mode & 0o100) === 0))
             throw new SpongeError('integrity');
+        if (verified.get(path) === `${key}:${artifact.sha256}`)
+            return;
+        verified.delete(path);
         const hash = createHash('sha256'), buffer = Buffer.alloc(65536);
         let bytes = 0;
         for (;;) {
@@ -153,13 +166,14 @@ async function verifyArtifact(path, artifact, root) {
             before.mtimeMs !== after.mtimeMs ||
             before.nlink !== after.nlink)
             throw new SpongeError('integrity');
+        verified.set(path, `${key}:${artifact.sha256}`);
     }
     finally {
         await file.close();
     }
 }
 /** Write one stream into a fresh staged file while hashing; the caller verifies against the manifest. */
-async function writeStaged(path, artifact, chunks, signal) {
+async function writeStaged(path, artifact, chunks, signal, onChunk) {
     const file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
     const hash = createHash('sha256');
     let bytes = 0;
@@ -167,6 +181,7 @@ async function writeStaged(path, artifact, chunks, signal) {
         for await (const chunk of chunks) {
             if (signal?.aborted)
                 throw new SpongeError('cancelled');
+            onChunk?.();
             bytes += chunk.length;
             if (bytes > artifact.bytes)
                 throw new SpongeError('integrity');
@@ -410,6 +425,44 @@ export async function recoverModelPackage(cacheRoot, manifest) {
         }
     }
 }
+/** Adopt a local file the user named (a model they already downloaded): an APFS clone when the volume allows, else a
+ * copy, then verified against the manifest. The source is only read; a mismatch fails without downloading. */
+async function adoptArtifact(root, stage, artifact, source, signal) {
+    if (signal?.aborted)
+        throw new SpongeError('cancelled');
+    const target = join(stage, artifact.name);
+    let real;
+    try {
+        real = await realpath(source);
+    }
+    catch {
+        throw new SpongeError('invalid-input');
+    }
+    const s = await lstat(real);
+    if (!s.isFile() || real.startsWith(root + '/'))
+        throw new SpongeError('invalid-input');
+    if (s.size !== artifact.bytes)
+        throw new SpongeError('integrity');
+    try {
+        try {
+            await copyFile(real, target, constants.COPYFILE_EXCL | constants.COPYFILE_FICLONE_FORCE);
+        }
+        catch (error) {
+            if (!['ENOTSUP', 'EXDEV', 'ENOSYS', 'EINVAL'].includes(error.code ?? ''))
+                throw error;
+            const disk = await statfs(root);
+            if (disk.bavail * disk.bsize < artifact.bytes + 512 * 1024 ** 2)
+                throw new SpongeError('limit-exceeded');
+            await copyFile(real, target, constants.COPYFILE_EXCL);
+        }
+        await chmod(target, artifact.executable ? 0o700 : 0o600);
+        await verifyArtifact(target, artifact, root);
+    }
+    catch (error) {
+        await rm(target, { force: true });
+        throw error;
+    }
+}
 /** 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 = {}) {
@@ -461,7 +514,7 @@ export async function provisionModelPackage(cacheRoot, manifest, options = {}) {
         // Reusable artifacts need no download space; a copy fallback rechecks space for itself.
         let needed = 512 * 1024 ** 2;
         for (const artifact of manifest.artifacts)
-            if (!(await reuseCandidates(root, artifact, plan.fingerprint)).length)
+            if (!options.adopt?.[artifact.name] && !(await reuseCandidates(root, artifact, plan.fingerprint)).length)
                 needed += artifact.bytes;
         const disk = await statfs(root);
         if (disk.bavail * disk.bsize < needed)
@@ -475,20 +528,42 @@ export async function provisionModelPackage(cacheRoot, manifest, options = {}) {
         for (const artifact of manifest.artifacts) {
             if (await reuseArtifact(root, stage, artifact, plan.fingerprint, options.signal))
                 continue;
+            const local = options.adopt?.[artifact.name];
+            if (local) {
+                await adoptArtifact(root, stage, artifact, local, options.signal);
+                continue;
+            }
             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 SpongeError('unavailable');
-            const declared = response.headers.get('content-length');
-            if (declared !== null && Number(declared) !== artifact.bytes) {
-                await response.body.cancel();
-                throw new SpongeError('integrity');
+            const idle = new AbortController(), wait = options.idleMs ?? idleMs;
+            let timer = setTimeout(() => idle.abort(), wait);
+            const signal = AbortSignal.any([
+                idle.signal,
+                AbortSignal.timeout(downloadDeadline(artifact.bytes)),
+                ...(options.signal ? [options.signal] : []),
+            ]);
+            try {
+                const response = await (options.fetch ?? fetch)(artifact.url, { signal });
+                if (!response.ok || !response.body || (response.url && new URL(response.url).protocol !== 'https:'))
+                    throw new SpongeError('unavailable');
+                const declared = response.headers.get('content-length');
+                if (declared !== null && Number(declared) !== artifact.bytes) {
+                    await response.body.cancel();
+                    throw new SpongeError('integrity');
+                }
+                await writeStaged(join(stage, artifact.name), artifact, response.body, signal, () => {
+                    clearTimeout(timer);
+                    timer = setTimeout(() => idle.abort(), wait);
+                });
+            }
+            catch (error) {
+                if (idle.signal.aborted && !options.signal?.aborted)
+                    throw new SpongeError('limit-exceeded', { cause: error });
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
             }
-            await writeStaged(join(stage, artifact.name), artifact, response.body, signal);
         }
         if (options.signal?.aborted)
             throw new SpongeError('cancelled');

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

@@ -0,0 +1,64 @@
+import { type ModelPackage } from './artifacts.js';
+/**
+ * The local digest runtime: upstream llama.cpp's macOS arm64 release build and one pinned GGUF, installed together as
+ * one model package (one fingerprint per model, so the shared archive hard-links across them). Pins live in source,
+ * not the per-release native catalog: they are third-party bytes that do not change with Sponge releases.
+ */
+export interface DigestModelPin {
+    readonly alias: string;
+    readonly file: string;
+    readonly bytes: number;
+    readonly sha256: string;
+    readonly repo: string;
+    readonly revision: string;
+    readonly base: string;
+    /** The smallest physical memory this model is chosen for by default. */
+    readonly minimumMemoryBytes: number;
+}
+/** llama.cpp b11669 (0.7.0, commit 620d2225c): self-contained, `@loader_path` dylibs, ad hoc signed. */
+export declare const llamaRuntimePin: {
+    readonly name: "llama-b11669-bin-macos-arm64.tar.gz";
+    readonly url: "https://github.com/ggml-org/llama.cpp/releases/download/b11669/llama-b11669-bin-macos-arm64.tar.gz";
+    readonly bytes: 12191582;
+    readonly sha256: "dbed55493d72bc1ba2babc8770d669c2289b5bc4ee9fb2a4dfc158d45b7d13fd";
+    readonly directory: "llama-b11669";
+    readonly build: 11669;
+    readonly commit: "620d2225c";
+};
+/**
+ * Gemma 4 26B-A4B (Apache 2.0) at Unsloth's dynamic Q4_K_M is the default: on the 40-item Jungle eval it matched the
+ * 9B's idea coverage with no failures, a tenth of its copied details and about 60% of its time per item (see
+ * src/digest/README.md). Qwen3.5-9B is the pin for machines with 16-32 GiB.
+ */
+export declare const digestModels: readonly DigestModelPin[];
+export declare const modelUrl: (m: Pick<DigestModelPin, "repo" | "revision" | "file">) => string;
+/** An explicit alias, or the largest pin this machine's memory allows; `unsupported` below every pin. */
+export declare function digestModel(alias?: string, memory?: number): DigestModelPin;
+export declare function digestModelPackage(pin: DigestModelPin): ModelPackage;
+/** Every pin's fingerprint, so runtime GC keeps any installed digest package. */
+export declare const digestFingerprints: () => string[];
+export interface DigestRuntime {
+    /** The verified llama.cpp release archive; extracted per run into owned scratch space. */
+    archive: string;
+    model: string;
+    pin: DigestModelPin;
+}
+export declare function digestSetupPlan(pin: DigestModelPin): {
+    id: string;
+    license: string;
+    fingerprint: string;
+    downloadBytes: number;
+    requiredFreeBytes: number;
+    artifacts: readonly import("./artifacts.js").ModelArtifact[];
+    model: string;
+    memoryBytes: number;
+    supported: boolean;
+};
+/** Explicit setup: download (or adopt `modelFile`, a copy of the pinned GGUF the user already has) and verify. */
+export declare function provisionDigest(cacheRoot: string, pin: DigestModelPin, options?: {
+    signal?: AbortSignal;
+    modelFile?: string;
+    fetch?: typeof fetch;
+}): Promise<DigestRuntime>;
+/** The installed runtime for `alias`, or for this machine's default pin, else the first installed pin. */
+export declare function inspectDigest(cacheRoot: string, alias?: string): Promise<DigestRuntime>;