@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.3

package/node_modules/@openvulcan/vulcan-decision/lib/local/engine.js

@@ -0,0 +1,157 @@
+/**
+ * The local backend: keeps one worker process with the selected model loaded, restarts it when
+ * the selection changes and stops it after a quiet period.
+ */
+import { DecisionError, checkResult } from '../protocol.js';
+import { backendOf, modelRoot, readModel } from './models.js';
+import { installedPack, packPython } from './packs.js';
+import { WorkerProcess } from './worker.js';
+function selectionKey(selection) {
+    return `${selection.pack}\n${selection.model}`;
+}
+/** Split `inputs` into requests of at most `limit` inputs, in order; no limit means one request. */
+export function mergeRequests(inputs, limit) {
+    const size = limit === undefined || limit < 1 ? Math.max(inputs.length, 1) : limit;
+    const requests = [];
+    for (let start = 0; start < inputs.length; start += size)
+        requests.push(inputs.slice(start, start + size));
+    return requests;
+}
+/** Hand each caller back its own slice of the merged results. */
+export function splitResults(groups, results) {
+    let offset = 0;
+    return groups.map(group => {
+        const slice = results.slice(offset, offset + group.length);
+        offset += group.length;
+        return slice;
+    });
+}
+/** Stop the process after this long without a judgement, to give its memory back. */
+export const LOCAL_IDLE_MS = 30 * 60_000;
+export class LocalEngine {
+    home;
+    idleMs;
+    worker;
+    current;
+    idleTimer;
+    /** Loads and merged judgements run one at a time, in arrival order. */
+    queue = Promise.resolve();
+    /** Callers waiting for the next merged judgement. */
+    waiting = [];
+    /** Whether a drain of `waiting` is already queued behind the running work. */
+    drainQueued = false;
+    constructor(home, idleMs = LOCAL_IDLE_MS) {
+        this.home = home;
+        this.idleMs = idleMs;
+    }
+    status() {
+        return {
+            running: this.worker?.running === true,
+            ...this.current === undefined ? {} : { selection: this.current.selection },
+            ...this.current?.loaded === undefined ? {} : { loaded: this.current.loaded },
+        };
+    }
+    /**
+     * Judge `inputs` with `selection`, loading it first when needed. Calls that arrive while the
+     * worker is busy wait together and go out as one merged request, split into requests of at most
+     * the package's `max_request_items` calls.
+     */
+    judge(selection, inputs) {
+        return new Promise((resolve, reject) => {
+            this.waiting.push({ selection, inputs, resolve, reject });
+            if (this.drainQueued)
+                return;
+            this.drainQueued = true;
+            const run = this.queue.then(() => {
+                this.drainQueued = false;
+                return this.drain();
+            });
+            this.queue = run.catch(() => { });
+        });
+    }
+    /** Load `selection` ahead of the first judgement. */
+    async warm(selection) {
+        const run = this.queue.then(() => this.ensure(selection));
+        this.queue = run.catch(() => { });
+        return await run;
+    }
+    stop() {
+        clearTimeout(this.idleTimer);
+        void this.worker?.stop();
+        this.worker = undefined;
+        this.current = undefined;
+    }
+    /** Answer every waiting caller, one selection at a time in arrival order. */
+    async drain() {
+        for (let first = this.waiting[0]; first !== undefined; first = this.waiting[0]) {
+            const key = selectionKey(first.selection);
+            const group = this.waiting.filter(entry => selectionKey(entry.selection) === key);
+            this.waiting = this.waiting.filter(entry => selectionKey(entry.selection) !== key);
+            try {
+                const results = await this.run(first.selection, group.map(entry => entry.inputs));
+                group.forEach((entry, index) => entry.resolve(results[index] ?? []));
+            }
+            catch (error) {
+                for (const entry of group)
+                    entry.reject(error);
+            }
+        }
+    }
+    /** Judge several callers' inputs with `selection` in merged requests; answers per caller. */
+    async run(selection, groups) {
+        const loaded = await this.ensure(selection);
+        const worker = this.worker;
+        if (worker === undefined)
+            throw new DecisionError('backend_unavailable', 'the local model process is not running');
+        try {
+            const flat = groups.flat();
+            const results = [];
+            for (const request of mergeRequests(flat, loaded.limits?.max_request_items)) {
+                const answered = await worker.judge(request);
+                if (!Array.isArray(answered) || answered.length !== request.length)
+                    throw new DecisionError('model_failed', 'the local model did not answer every call');
+                results.push(...answered.map(checkResult));
+            }
+            return splitResults(groups, results);
+        }
+        finally {
+            this.armIdle();
+        }
+    }
+    async ensure(selection) {
+        const key = `${selection.pack}\n${selection.model}`;
+        if (this.current?.key === key && this.worker?.running === true)
+            return await this.current.loading;
+        this.stop();
+        const pack = installedPack(this.home, selection.pack);
+        if (pack === undefined)
+            throw new DecisionError('not_installed', `the runtime pack ${selection.pack} is not installed`);
+        const model = readModel(this.home, selection.model);
+        if (model === undefined)
+            throw new DecisionError('not_installed', `the model ${selection.model} is not installed`);
+        if (backendOf(model.package_format) !== pack.backend) {
+            throw new DecisionError('invalid_request', `${model.id} needs a ${backendOf(model.package_format)} runtime pack, not ${pack.pack}`);
+        }
+        const worker = new WorkerProcess(packPython(this.home, pack));
+        this.worker = worker;
+        const current = {
+            key, selection,
+            loading: worker.load(model.package_format, modelRoot(this.home, model.id), pack.device),
+        };
+        this.current = current;
+        try {
+            current.loaded = await current.loading;
+            return current.loaded;
+        }
+        catch (error) {
+            if (this.current === current)
+                this.stop();
+            throw error;
+        }
+    }
+    armIdle() {
+        clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => this.stop(), this.idleMs);
+        this.idleTimer.unref();
+    }
+}

package/node_modules/@openvulcan/vulcan-decision/lib/local/models.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Local model packages: the published catalog and the installed packages.
+ *
+ * Two package formats exist:
+ * - `torch-release`: a published model repository (`manifest.json`, `decision.py`, `runtime/`,
+ *   `tokenizer/`, `weights/`). Only the files needed to run it with its recommended fp32 weights
+ *   are installed; training records, evaluation data and experimental weight formats are skipped.
+ * - `onnx-delivery`: a package of the vulcan-decision-shell-v1-runtime repository (`MANIFEST.json`
+ *   format 2 naming its family and format, `runtime-config.json`, `assets/`, `model.onnx`),
+ *   installed whole.
+ *
+ * Every installed file is checked against the package's own manifest while it is copied or
+ * downloaded, into a staging directory that replaces the installed package only when complete.
+ */
+import { type DecisionHome } from '../home.js';
+import type { Backend, PackId } from './packs.js';
+import type { ModelFormat } from './worker.js';
+/** The model families published for local use. */
+export declare const MODEL_FAMILIES: readonly ["mini", "flash", "standard"];
+export type ModelFamily = typeof MODEL_FAMILIES[number];
+/** Where a published model can be downloaded from. */
+export declare const MODEL_SOURCES: readonly ["huggingface", "modelscope-intl", "modelscope-cn"];
+export type ModelSource = typeof MODEL_SOURCES[number];
+/** One published repository revision. */
+export interface PublishedRepository {
+    readonly repo: string;
+    /** A commit, never a branch, so the files cannot change under the pins. */
+    readonly revision: string;
+}
+/** Precisions the runtime packages are published in. */
+export declare const PACKAGE_PRECISIONS: readonly ["fp16", "fp32"];
+export type PackagePrecision = typeof PACKAGE_PRECISIONS[number];
+/** One package directory of the runtime repository, identical on every hub. */
+export interface RuntimePackage {
+    /** Directory inside the repository, such as `mini/fp16`. */
+    readonly path: string;
+    /** SHA-256 of the package's `MANIFEST.json`. */
+    readonly manifestSha256: string;
+}
+export interface CatalogModel {
+    readonly family: ModelFamily;
+    readonly name: string;
+    readonly parameters: string;
+    readonly format: ModelFormat;
+    /** The ONNX packages published for this family, by precision. */
+    readonly packages: Readonly<Partial<Record<PackagePrecision, RuntimePackage>>>;
+}
+/**
+ * The vulcan-decision-shell-v1-runtime repository on each hub, holding every catalog package;
+ * null until it is published there.
+ */
+export declare const RUNTIME_SOURCES: Readonly<Record<ModelSource, PublishedRepository | null>>;
+/** Published local models: ONNX packages of the runtime repository. */
+export declare const MODEL_CATALOG: readonly CatalogModel[];
+/** The hubs `model` can be downloaded from. */
+export declare function sourcesOf(model: CatalogModel): ModelSource[];
+/**
+ * The precision to download: fp16 where the CUDA ONNX pack runs, fp32 on the CPU, or the only
+ * precision published.
+ */
+export declare function preferredPrecision(model: CatalogModel, onnxPack: PackId): PackagePrecision | undefined;
+/** The backend a package format runs on. */
+export declare function backendOf(format: ModelFormat): Backend;
+/** URL of one file of a published repository. */
+export declare function repositoryFileUrl(source: ModelSource, published: PublishedRepository, file: string): string;
+export interface FileDigest {
+    readonly bytes: number;
+    readonly sha256: string;
+}
+/** `model.json` of an installed package. */
+export interface InstalledModel {
+    readonly format: 1;
+    readonly id: string;
+    readonly name: string;
+    readonly family?: ModelFamily;
+    readonly package_format: ModelFormat;
+    readonly bytes: number;
+    readonly installed_at: string;
+    readonly source: {
+        readonly kind: 'directory';
+        readonly path: string;
+    } | {
+        readonly kind: 'download';
+        readonly source: ModelSource;
+        readonly repo: string;
+        readonly revision: string;
+        readonly path: string;
+    };
+    readonly files: Readonly<Record<string, FileDigest>>;
+}
+/** What a package directory or repository declares. */
+interface PackageDeclaration {
+    readonly id: string;
+    readonly name: string;
+    readonly format: ModelFormat;
+    readonly family?: ModelFamily;
+    /** Files to install, with their declared digests. */
+    readonly files: Readonly<Record<string, FileDigest>>;
+}
+/** Parse a package's manifest into what to install. */
+export declare function declarationOf(manifestName: string, text: string): PackageDeclaration;
+/** The files a manifest lists, refusing any path that is not a plain relative path with `/`. */
+export declare function manifestFiles(manifest: Record<string, unknown>): Record<string, FileDigest>;
+/** Every installed model with a readable `model.json`. */
+export declare function listModels(home: DecisionHome): InstalledModel[];
+export declare function readModel(home: DecisionHome, id: string): InstalledModel | undefined;
+export declare function modelRoot(home: DecisionHome, id: string): string;
+export interface ModelInstallOptions {
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (done: number, total: number, file: string) => void;
+}
+/**
+ * Install the package in `dir`, a torch release repository or an ONNX delivery, verifying every
+ * file against the package's manifest.
+ */
+export declare function installModelFromDirectory(home: DecisionHome, dir: string, options?: ModelInstallOptions): Promise<InstalledModel>;
+/**
+ * Download and install the `precision` package of a published catalog model from `source`.
+ * @throws Error when that package or the runtime repository is not published there yet.
+ */
+export declare function downloadModel(home: DecisionHome, family: ModelFamily, precision: PackagePrecision, source: ModelSource, options?: ModelInstallOptions): Promise<InstalledModel>;
+/** Remove an installed model. */
+export declare function removeModel(home: DecisionHome, id: string): boolean;
+/** Verify every file of an installed model again. @returns the files that no longer match. */
+export declare function verifyModel(home: DecisionHome, model: InstalledModel): Promise<string[]>;
+export {};

package/node_modules/@openvulcan/vulcan-decision/lib/local/models.js

@@ -0,0 +1,261 @@
+/**
+ * Local model packages: the published catalog and the installed packages.
+ *
+ * Two package formats exist:
+ * - `torch-release`: a published model repository (`manifest.json`, `decision.py`, `runtime/`,
+ *   `tokenizer/`, `weights/`). Only the files needed to run it with its recommended fp32 weights
+ *   are installed; training records, evaluation data and experimental weight formats are skipped.
+ * - `onnx-delivery`: a package of the vulcan-decision-shell-v1-runtime repository (`MANIFEST.json`
+ *   format 2 naming its family and format, `runtime-config.json`, `assets/`, `model.onnx`),
+ *   installed whole.
+ *
+ * Every installed file is checked against the package's own manifest while it is copied or
+ * downloaded, into a staging directory that replaces the installed package only when complete.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fetchPinned, matches, sha256Of } from '../download.js';
+import { writeFileAtomic } from '../home.js';
+import { replaceDirectory } from './packs.js';
+/** The model families published for local use. */
+export const MODEL_FAMILIES = ['mini', 'flash', 'standard'];
+/** Where a published model can be downloaded from. */
+export const MODEL_SOURCES = ['huggingface', 'modelscope-intl', 'modelscope-cn'];
+/** Precisions the runtime packages are published in. */
+export const PACKAGE_PRECISIONS = ['fp16', 'fp32'];
+/**
+ * The vulcan-decision-shell-v1-runtime repository on each hub, holding every catalog package;
+ * null until it is published there.
+ */
+export const RUNTIME_SOURCES = {
+    'huggingface': { repo: 'openvulcan/vulcan-decision-shell-v1-runtime', revision: 'fd5e1d09f54df4133956bb9e192ac7771401d7d7' },
+    'modelscope-intl': null,
+    'modelscope-cn': { repo: 'OpenVulcan/vulcan-decision-shell-v1-runtime', revision: 'e96d96744c20f691ea6045cf21c232cbc8fa8e09' },
+};
+/** Published local models: ONNX packages of the runtime repository. */
+export const MODEL_CATALOG = [
+    {
+        family: 'mini', name: 'vulcan-decision-shell-v1-mini', parameters: '0.2B', format: 'onnx-delivery',
+        packages: {
+            fp16: { path: 'mini/fp16', manifestSha256: 'dc57ba263b4b32c1443b78b42ce81371aed85f93fb3f3afd5e5f77afd059dbf9' },
+            fp32: { path: 'mini/fp32', manifestSha256: 'eb3d48b93d030b9f67bbcf7fcea1179b854287b44e5c16b72a8e0be9694c194e' },
+        },
+    },
+    {
+        family: 'flash', name: 'vulcan-decision-shell-v1-flash', parameters: '0.35B', format: 'onnx-delivery',
+        packages: {
+            fp16: { path: 'flash/fp16', manifestSha256: '075e61a05063272b13d966c1f9b6e55ce99acbf5055de16b675ae1b442e6ffed' },
+            fp32: { path: 'flash/fp32', manifestSha256: '6b652427b61922ea573fd3509ed41b47cbc6037ffa47db7d6edf325cd12c4374' },
+        },
+    },
+    {
+        family: 'standard', name: 'vulcan-decision-shell-v1', parameters: '0.8B', format: 'onnx-delivery',
+        packages: {
+            fp16: { path: 'standard/fp16', manifestSha256: 'de1d7e101998b4ac978038c2ae3251a0fdb86567ec22b263fe7cec5b76b26ade' },
+        },
+    },
+];
+/** The hubs `model` can be downloaded from. */
+export function sourcesOf(model) {
+    return Object.keys(model.packages).length === 0 ? [] : MODEL_SOURCES.filter(source => RUNTIME_SOURCES[source] !== null);
+}
+/**
+ * The precision to download: fp16 where the CUDA ONNX pack runs, fp32 on the CPU, or the only
+ * precision published.
+ */
+export function preferredPrecision(model, onnxPack) {
+    const preferred = onnxPack === 'onnx-cuda' ? 'fp16' : 'fp32';
+    return model.packages[preferred] === undefined ? PACKAGE_PRECISIONS.find(precision => model.packages[precision] !== undefined) : preferred;
+}
+/** The backend a package format runs on. */
+export function backendOf(format) {
+    return format === 'onnx-delivery' ? 'onnx' : 'torch';
+}
+/** URL of one file of a published repository. */
+export function repositoryFileUrl(source, published, file) {
+    const encoded = file.split('/').map(encodeURIComponent).join('/');
+    switch (source) {
+        case 'huggingface':
+            return `https://huggingface.co/${published.repo}/resolve/${published.revision}/${encoded}`;
+        case 'modelscope-intl':
+            return `https://www.modelscope.ai/models/${published.repo}/resolve/${published.revision}/${encoded}`;
+        case 'modelscope-cn':
+            return `https://www.modelscope.cn/models/${published.repo}/resolve/${published.revision}/${encoded}`;
+    }
+}
+/** The only `MANIFEST.json` format of ONNX packages this version reads. */
+const ONNX_MANIFEST_FORMAT = 2;
+/** Files of a torch release that running it needs, besides the recommended weights. */
+const TORCH_RUNTIME_PATHS = [/^decision\.py$/, /^runtime\//, /^tokenizer\//, /^weights\/formats\.json$/, /^weights\/fp32\//,
+    /^(LICENSE|LICENSE-DATA\.md|NOTICE\.md|README(\.zh)?\.md|config\.json|configuration\.json)$/, /^licenses\//];
+/** Parse a package's manifest into what to install. */
+export function declarationOf(manifestName, text) {
+    const manifest = JSON.parse(text);
+    const files = manifestFiles(manifest);
+    if (manifestName === 'manifest.json') {
+        const name = manifest.model;
+        if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9.-]{0,63}$/.test(name))
+            throw new Error('manifest.json names no model');
+        const selected = Object.fromEntries(Object.entries(files).filter(([file]) => TORCH_RUNTIME_PATHS.some(pattern => pattern.test(file))));
+        for (const required of ['decision.py', 'weights/formats.json', 'weights/fp32/model.safetensors']) {
+            if (selected[required] === undefined)
+                throw new Error(`manifest.json does not list ${required}`);
+        }
+        return { id: name, name, format: 'torch-release', files: selected };
+    }
+    if (manifest.format_version !== ONNX_MANIFEST_FORMAT) {
+        throw new Error(`MANIFEST.json format ${String(manifest.format_version)} is not supported; use a vulcan-decision-shell-v1-runtime package`);
+    }
+    const family = MODEL_FAMILIES.find(known => known === manifest.family);
+    const format = manifest.format;
+    if (family === undefined || typeof format !== 'string' || !/^[a-z0-9][a-z0-9-]{0,31}$/.test(format)) {
+        throw new Error('MANIFEST.json names no known family and format');
+    }
+    for (const required of ['runtime-config.json', 'assets/policy-v2.json', 'assets/tokenizer.json', 'model.onnx']) {
+        if (files[required] === undefined)
+            throw new Error(`MANIFEST.json does not list ${required}`);
+    }
+    const name = `vulcan-decision-shell-v1-${family}-${format}`;
+    return { id: name, name, format: 'onnx-delivery', family, files };
+}
+/** The files a manifest lists, refusing any path that is not a plain relative path with `/`. */
+export function manifestFiles(manifest) {
+    const listed = manifest.files;
+    if (typeof listed !== 'object' || listed === null)
+        throw new Error('the manifest lists no files');
+    const files = {};
+    for (const [relative, entry] of Object.entries(listed)) {
+        const segments = relative.split('/');
+        if (relative === '' || relative.includes('\\') || segments.some(segment => segment === '' || segment === '.' || segment === '..' || /^[A-Za-z]:/.test(segment))) {
+            throw new Error(`the manifest lists an unsafe path ${relative}`);
+        }
+        if (typeof entry.bytes !== 'number' || typeof entry.sha256 !== 'string' || !/^[0-9a-f]{64}$/i.test(entry.sha256)) {
+            throw new Error(`the manifest entry ${relative} is malformed`);
+        }
+        files[relative] = { bytes: entry.bytes, sha256: entry.sha256.toLowerCase() };
+    }
+    return files;
+}
+/** Every installed model with a readable `model.json`. */
+export function listModels(home) {
+    const models = [];
+    for (const entry of fs.readdirSync(home.models, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const model = readModel(home, entry.name);
+        if (model !== undefined)
+            models.push(model);
+    }
+    return models.sort((a, b) => a.id.localeCompare(b.id));
+}
+export function readModel(home, id) {
+    try {
+        const model = JSON.parse(fs.readFileSync(path.join(home.models, id, 'model.json'), 'utf8'));
+        return model.format === 1 && model.id === id ? model : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function modelRoot(home, id) {
+    return path.join(home.models, id);
+}
+/**
+ * Install the package in `dir`, a torch release repository or an ONNX delivery, verifying every
+ * file against the package's manifest.
+ */
+export async function installModelFromDirectory(home, dir, options = {}) {
+    const root = path.resolve(dir);
+    const manifestName = ['manifest.json', 'MANIFEST.json'].find(name => fs.readdirSync(root).includes(name));
+    if (manifestName === undefined)
+        throw new Error(`${root} has no manifest.json or MANIFEST.json`);
+    const manifestText = fs.readFileSync(path.join(root, manifestName), 'utf8');
+    const declaration = declarationOf(manifestName, manifestText);
+    return await installPackage(home, declaration, manifestName, manifestText, { kind: 'directory', path: root }, async (file, dest) => {
+        fs.copyFileSync(path.join(root, ...file.split('/')), dest);
+    }, options);
+}
+/**
+ * Download and install the `precision` package of a published catalog model from `source`.
+ * @throws Error when that package or the runtime repository is not published there yet.
+ */
+export async function downloadModel(home, family, precision, source, options = {}) {
+    const pinned = MODEL_CATALOG.find(model => model.family === family)?.packages[precision];
+    if (pinned === undefined)
+        throw new Error(`${family} has no published ${precision} package`);
+    const published = RUNTIME_SOURCES[source];
+    if (published === null)
+        throw new Error(`the runtime packages are not published on ${source} yet; install one from a directory instead`);
+    const url = (file) => repositoryFileUrl(source, published, `${pinned.path}/${file}`);
+    const response = await fetch(url('MANIFEST.json'), options.signal === undefined ? {} : { signal: options.signal });
+    if (!response.ok)
+        throw new Error(`cannot download MANIFEST.json: HTTP ${response.status}`);
+    const manifestText = await response.text();
+    const digest = createHash('sha256').update(manifestText, 'utf8').digest('hex');
+    if (digest !== pinned.manifestSha256)
+        throw new Error('the published MANIFEST.json does not match its pin');
+    const declaration = declarationOf('MANIFEST.json', manifestText);
+    if (declaration.family !== family)
+        throw new Error(`${pinned.path}/MANIFEST.json declares the ${String(declaration.family)} family`);
+    const work = path.join(home.downloads, `model-${pinned.manifestSha256.slice(0, 16)}`);
+    return await installPackage(home, declaration, 'MANIFEST.json', manifestText, { kind: 'download', source, repo: published.repo, revision: published.revision, path: pinned.path }, async (file, dest, digest) => {
+        const cached = path.join(work, ...file.split('/'));
+        await fetchPinned({ name: file, url: url(file), ...digest }, cached, options.signal === undefined ? {} : { signal: options.signal });
+        fs.renameSync(cached, dest);
+    }, options).finally(() => fs.rmSync(work, { recursive: true, force: true }));
+}
+async function installPackage(home, declaration, manifestName, manifestText, source, place, options) {
+    const staging = path.join(home.models, `.staging-${declaration.id}`);
+    fs.rmSync(staging, { recursive: true, force: true });
+    fs.mkdirSync(staging, { recursive: true });
+    try {
+        const total = Object.values(declaration.files).reduce((sum, file) => sum + file.bytes, 0);
+        let done = 0;
+        for (const [file, digest] of Object.entries(declaration.files)) {
+            options.signal?.throwIfAborted();
+            options.onProgress?.(done, total, file);
+            const dest = path.join(staging, ...file.split('/'));
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            await place(file, dest, digest);
+            if (!await matches(dest, digest))
+                throw new Error(`${file} does not match the package manifest`);
+            done += digest.bytes;
+        }
+        options.onProgress?.(total, total, '');
+        fs.writeFileSync(path.join(staging, manifestName), manifestText);
+        const family = declaration.family ?? MODEL_CATALOG.find(model => model.name === declaration.name)?.family;
+        const model = {
+            format: 1, id: declaration.id, name: declaration.name, ...family === undefined ? {} : { family },
+            package_format: declaration.format, bytes: total, installed_at: new Date().toISOString(), source, files: declaration.files,
+        };
+        writeFileAtomic(path.join(staging, 'model.json'), `${JSON.stringify(model, null, 2)}\n`);
+        replaceDirectory(staging, modelRoot(home, declaration.id));
+        return model;
+    }
+    catch (error) {
+        fs.rmSync(staging, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** Remove an installed model. */
+export function removeModel(home, id) {
+    if (!/^[a-z0-9][a-z0-9.-]*$/.test(id))
+        return false;
+    const dir = modelRoot(home, id);
+    const existed = fs.existsSync(dir);
+    fs.rmSync(dir, { recursive: true, force: true });
+    return existed;
+}
+/** Verify every file of an installed model again. @returns the files that no longer match. */
+export async function verifyModel(home, model) {
+    const root = modelRoot(home, model.id);
+    const broken = [];
+    for (const [file, digest] of Object.entries(model.files)) {
+        const local = path.join(root, ...file.split('/'));
+        const stat = fs.statSync(local, { throwIfNoEntry: false });
+        if (stat?.size !== digest.bytes || await sha256Of(local) !== digest.sha256)
+            broken.push(file);
+    }
+    return broken;
+}

package/node_modules/@openvulcan/vulcan-decision/lib/local/packs.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Runtime packs: the optional local runtimes, installed on demand next to the cloud-only default.
+ *
+ * A pack is a prebuilt python-build-standalone interpreter plus the official wheels its lock file
+ * (`runtime-packs/<pack>.json`, written by `scripts/lock_runtime.py`) pins for this platform.
+ * Installing downloads exactly those files, verifies each against its size and SHA-256, unpacks
+ * the interpreter, installs the wheels offline with the interpreter's own pip and checks that the
+ * runtime imports. Nothing is compiled and no driver is installed: GPU packs bring their CUDA
+ * libraries as NVIDIA's wheels and only need a recent enough driver.
+ */
+import { type DownloadSource, type PinnedFile } from '../download.js';
+import { type DecisionHome } from '../home.js';
+import { type ProbeResult } from './worker.js';
+/** Packs with a lock file, in the order they are offered. */
+export declare const PACK_IDS: readonly ["onnx-cpu", "onnx-cuda", "torch-cpu", "torch-cu128"];
+export type PackId = typeof PACK_IDS[number];
+export type Backend = 'onnx' | 'torch';
+export type Device = 'cpu' | 'cuda';
+/**
+ * Packs waiting for a release: an NPU needs an ONNX model exported for it, which is not
+ * published yet. They are listed so a host can show what this machine will be able to use.
+ */
+export declare const PLANNED_PACKS: readonly [{
+    readonly id: "onnx-openvino";
+    readonly backend: "onnx";
+    readonly accelerator: "intel-npu";
+}, {
+    readonly id: "onnx-qnn";
+    readonly backend: "onnx";
+    readonly accelerator: "qualcomm-npu";
+}];
+/** Platforms a pack can target, named as in the lock files. */
+export type Target = 'win-x64' | 'linux-x64' | 'linux-arm64' | 'mac-arm64';
+export interface LockedFile extends PinnedFile {
+    readonly kind: 'python' | 'wheel';
+}
+export interface PackLock {
+    readonly format: 1;
+    /** Identity of the exact file set; an installed pack with another id is outdated. */
+    readonly id: string;
+    readonly pack: PackId;
+    readonly backend: Backend;
+    readonly device: Device;
+    readonly python: string;
+    /** Lowest NVIDIA driver version and CUDA compute capability, for GPU packs. */
+    readonly requires: {
+        readonly nvidia_driver?: string;
+        readonly compute_capability?: string;
+    };
+    readonly targets: Readonly<Partial<Record<Target, {
+        readonly bytes: number;
+        readonly macos?: string;
+        readonly files: readonly LockedFile[];
+    }>>>;
+}
+/** `pack.json` of an installed pack. */
+export interface InstalledPack {
+    readonly format: 1;
+    readonly pack: PackId;
+    readonly lock: string;
+    readonly target: Target;
+    readonly backend: Backend;
+    readonly device: Device;
+    /** Interpreter path relative to the pack directory. */
+    readonly python: string;
+    readonly installed_at: string;
+    readonly probe: ProbeResult;
+}
+/** The target this process runs on, or undefined when no pack supports it. */
+export declare function currentTarget(platform?: NodeJS.Platform, arch?: string): Target | undefined;
+export declare function isPackId(value: unknown): value is PackId;
+/** The lock file shipped with this package for `pack`. */
+export declare function readLock(pack: PackId): PackLock;
+/** The installed pack in `home`, or undefined when it is missing or unreadable. */
+export declare function installedPack(home: DecisionHome, pack: PackId): InstalledPack | undefined;
+/** The interpreter of an installed pack. */
+export declare function packPython(home: DecisionHome, record: InstalledPack): string;
+/** Installation progress, reported as it happens. */
+export type InstallProgress = {
+    readonly phase: 'download';
+    readonly done: number;
+    readonly total: number;
+    readonly file: string;
+} | {
+    readonly phase: 'unpack' | 'install' | 'probe';
+};
+export interface InstallOptions {
+    readonly source?: DownloadSource;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: InstallProgress) => void;
+    readonly target?: Target;
+}
+/**
+ * Install `pack` for this platform, replacing an installed one only once the new one works.
+ * @throws Error when the pack has no build for this platform, a download fails verification, or
+ *   the installed runtime does not start.
+ */
+export declare function installPack(home: DecisionHome, pack: PackId, options?: InstallOptions): Promise<InstalledPack>;
+/** Remove an installed pack and any partial download of it. */
+export declare function removePack(home: DecisionHome, pack: PackId): boolean;
+/** Move `staging` to `dest`, keeping the old `dest` until the move succeeded. */
+export declare function replaceDirectory(staging: string, dest: string): void;