@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.0

package/node_modules/@openvulcan/vulcan-decision/lib/download.js

@@ -0,0 +1,99 @@
+/**
+ * Pinned downloads: every file has a known size and SHA-256, is fetched through a partial file
+ * that resumes after an interruption, and is refused unless both match.
+ *
+ * The `cn` source rewrites the official hosts to mirrors reachable from mainland China. A mirror
+ * serves the same bytes, so the same pins apply; a failing mirror is reported, never silently
+ * replaced by the official host.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+/** Where runtime downloads come from. */
+export const DOWNLOAD_SOURCES = ['official', 'cn'];
+/** Official prefix → mainland China mirror prefix. */
+const CN_MIRRORS = [
+    ['https://github.com/astral-sh/python-build-standalone/releases/download/', 'https://registry.npmmirror.com/-/binary/python-build-standalone/'],
+    ['https://files.pythonhosted.org/packages/', 'https://mirrors.aliyun.com/pypi/packages/'],
+    ['https://download-r2.pytorch.org/whl/', 'https://mirrors.aliyun.com/pytorch-wheels/'],
+    ['https://download.pytorch.org/whl/', 'https://mirrors.aliyun.com/pytorch-wheels/'],
+];
+/** The URL to fetch `url` from with `source`. */
+export function sourceUrl(url, source) {
+    if (source === 'official')
+        return url;
+    for (const [official, mirror] of CN_MIRRORS) {
+        // The PyTorch mirror stores file names unescaped, like `torch-2.9.1+cu128-...whl`.
+        if (url.startsWith(official))
+            return mirror + (official.includes('pytorch') ? decodeURIComponent(url.slice(official.length)) : url.slice(official.length));
+    }
+    throw new Error(`no mirror is known for ${new URL(url).host}`);
+}
+/**
+ * Make `dest` hold exactly `file`: kept when it already matches, otherwise fetched (resuming a
+ * `.part` file left by an earlier attempt) and verified.
+ * @throws Error on HTTP failure or when the size or digest does not match.
+ */
+export async function fetchPinned(file, dest, options = {}) {
+    if (await matches(dest, file)) {
+        options.onBytes?.(file.bytes);
+        return;
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const partial = `${dest}.part`;
+    let have = fs.statSync(partial, { throwIfNoEntry: false })?.size ?? 0;
+    if (have > file.bytes) {
+        fs.rmSync(partial, { force: true });
+        have = 0;
+    }
+    const url = sourceUrl(file.url, options.source ?? 'official');
+    if (have < file.bytes) {
+        const response = await fetch(url, {
+            ...options.signal === undefined ? {} : { signal: options.signal },
+            headers: have > 0 ? { Range: `bytes=${have}-` } : {},
+        });
+        const resumed = response.status === 206;
+        if (!response.ok || response.body === null)
+            throw new Error(`cannot download ${file.name} from ${new URL(url).host}: HTTP ${response.status}`);
+        if (!resumed)
+            have = 0;
+        options.onBytes?.(have);
+        const counter = new CountingStream(options.onBytes);
+        // The DOM and node:stream/web declarations of ReadableStream differ only in their typings.
+        await pipeline(Readable.fromWeb(response.body), counter, fs.createWriteStream(partial, { flags: resumed ? 'a' : 'w' }), ...options.signal === undefined ? [] : [{ signal: options.signal }]);
+    }
+    else {
+        options.onBytes?.(have);
+    }
+    if (!await matches(partial, file)) {
+        fs.rmSync(partial, { force: true });
+        throw new Error(`${file.name} does not match its pinned size and SHA-256`);
+    }
+    fs.renameSync(partial, dest);
+}
+/** Whether `local` is a file of the pinned size and digest. */
+export async function matches(local, file) {
+    const stat = fs.statSync(local, { throwIfNoEntry: false });
+    if (stat === undefined || !stat.isFile() || stat.size !== file.bytes)
+        return false;
+    return await sha256Of(local) === file.sha256.toLowerCase();
+}
+/** SHA-256 of a file, as lowercase hex. */
+export async function sha256Of(file) {
+    const hash = createHash('sha256');
+    await pipeline(fs.createReadStream(file), hash);
+    return hash.digest('hex');
+}
+class CountingStream extends Transform {
+    onBytes;
+    constructor(onBytes) {
+        super();
+        this.onBytes = onBytes;
+    }
+    _transform(chunk, _encoding, done) {
+        this.onBytes?.(chunk.length);
+        done(null, chunk);
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * One entry point for hosts: judge a call with the cloud or the local backend, as selected.
+ */
+import type { AccountSource } from '@openvulcan/openvulcan-account';
+import { EdgeClient } from './cloud/edge.js';
+import type { DecisionHome } from './home.js';
+import { LocalEngine, type LocalSelection } from './local/engine.js';
+import { type BackendKind, type DecisionOptions, type JudgeCall, type Verdict } from './protocol.js';
+/** How the host wants calls judged. */
+export interface EngineSettings {
+    readonly backend: BackendKind;
+    /** Cloud model id; empty uses the first model OpenVulcan lists for the account. */
+    readonly cloudModel: string;
+    /** Endpoint id the user locked; absent means the measured best. */
+    readonly cloudEndpoint?: string;
+    /** Installed pack and model for the local backend. */
+    readonly local?: LocalSelection;
+    readonly options: DecisionOptions;
+}
+export interface EngineOptions {
+    readonly home: DecisionHome;
+    /** The OpenVulcan account the cloud backend signs its requests with; the host owns signing in. */
+    readonly account: AccountSource;
+}
+export declare class DecisionEngine {
+    readonly home: DecisionHome;
+    readonly account: AccountSource;
+    readonly cloud: EdgeClient;
+    readonly local: LocalEngine;
+    constructor(options: EngineOptions);
+    /**
+     * Judge one call.
+     * @throws DecisionError for every failure; hosts must treat it as "not allowed".
+     */
+    judge(call: JudgeCall, settings: EngineSettings): Promise<Verdict>;
+    stop(): void;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * One entry point for hosts: judge a call with the cloud or the local backend, as selected.
+ */
+import { EdgeClient } from './cloud/edge.js';
+import { LocalEngine } from './local/engine.js';
+import { DecisionError } from './protocol.js';
+import { renderCall } from './render.js';
+export class DecisionEngine {
+    home;
+    account;
+    cloud;
+    local;
+    constructor(options) {
+        this.home = options.home;
+        this.account = options.account;
+        this.cloud = new EdgeClient(this.account);
+        this.local = new LocalEngine(options.home);
+    }
+    /**
+     * Judge one call.
+     * @throws DecisionError for every failure; hosts must treat it as "not allowed".
+     */
+    async judge(call, settings) {
+        const input = { settings: settings.options, rendered: renderCall(call) };
+        const started = performance.now();
+        if (settings.backend === 'cloud') {
+            const model = await this.cloud.resolveModel(settings.cloudModel);
+            const { results, endpoint } = await this.cloud.judge(model, [input], settings.cloudEndpoint);
+            return { ...results[0], backend: 'cloud', model, via: endpoint, elapsed_ms: Math.round(performance.now() - started) };
+        }
+        if (settings.local === undefined)
+            throw new DecisionError('not_installed', 'no local runtime pack and model are selected');
+        const [result] = await this.local.judge(settings.local, [input]);
+        return { ...result, backend: 'local', model: settings.local.model, via: settings.local.pack, elapsed_ms: Math.round(performance.now() - started) };
+    }
+    stop() {
+        this.local.stop();
+    }
+}

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

@@ -0,0 +1,105 @@
+/**
+ * What this machine offers the local model, and which runtime pack to recommend for it.
+ *
+ * Only ready-made runtimes are considered. NVIDIA cards run the CUDA packs, whose CUDA libraries
+ * come as NVIDIA's own wheels, so only the driver has to be recent enough; this package never
+ * installs or updates a driver. AMD, Intel and Apple graphics have no published runtime for these
+ * models, so they get the CPU pack or the cloud. An NPU is reported, but it needs an ONNX model
+ * exported for it, which is not published yet.
+ */
+import { type PackId, type Target } from './local/packs.js';
+/** One graphics card. */
+export interface GpuInfo {
+    readonly name: string;
+    readonly vendor: 'nvidia' | 'amd' | 'intel' | 'apple' | 'other';
+    /** Dedicated memory, when the driver reports it. */
+    readonly memoryBytes?: number;
+    /** CUDA compute capability such as `8.9`, NVIDIA only. */
+    readonly computeCapability?: string;
+    readonly driver?: string;
+}
+/** One neural processing unit. */
+export interface NpuInfo {
+    readonly name: string;
+    readonly vendor: 'intel' | 'amd' | 'qualcomm' | 'apple' | 'other';
+}
+export interface Hardware {
+    readonly platform: NodeJS.Platform;
+    readonly arch: string;
+    readonly target?: Target;
+    readonly totalMemory: number;
+    readonly cpus: number;
+    readonly gpus: readonly GpuInfo[];
+    readonly npus: readonly NpuInfo[];
+}
+/** Raw observations, injectable for tests. */
+export interface Probes {
+    readonly platform: NodeJS.Platform;
+    readonly arch: string;
+    readonly totalMemory: number;
+    readonly cpus: number;
+    /** NVIDIA cards from `nvidia-smi`; undefined when no NVIDIA driver answered. */
+    readonly nvidia: readonly GpuInfo[] | undefined;
+    /** Display adapter names the system reports. */
+    readonly adapters: readonly string[];
+    /** NPU device names the system reports. */
+    readonly npus: readonly string[];
+}
+export declare function assess(probes: Probes): Hardware;
+/** How an NVIDIA generation handles the model's arithmetic. */
+export interface GpuGeneration {
+    /** Architecture name, such as `Ada Lovelace`. */
+    readonly architecture: string;
+    /** Fast half precision; the recommended format computes in fp16 on the GPU. */
+    readonly fp16: 'tensor-cores' | 'native' | 'slow';
+    /** Whether bf16 is supported; it is never used for these models, which lose accuracy in it. */
+    readonly bf16: boolean;
+    /** Whether the CUDA packs run on it. */
+    readonly supported: boolean;
+}
+/** Lowest compute capability the CUDA packs run on (Turing). */
+export declare const MIN_COMPUTE_CAPABILITY = 7.5;
+export declare function gpuGeneration(computeCapability: string): GpuGeneration;
+/**
+ * Why a pack is or is not usable here.
+ * - `ok`: everything it needs was found.
+ * - `no_build`: the pack has no build for this platform.
+ * - `no_nvidia_gpu`: no NVIDIA card answered `nvidia-smi`.
+ * - `gpu_too_old`: the card's compute capability is below {@link MIN_COMPUTE_CAPABILITY}.
+ * - `driver_too_old`: the driver is older than the pack needs; update it from NVIDIA.
+ */
+export type PackFit = 'ok' | 'no_build' | 'no_nvidia_gpu' | 'gpu_too_old' | 'driver_too_old';
+export interface PackAssessment {
+    readonly pack: PackId;
+    readonly fit: PackFit;
+    /** Download size for this platform. */
+    readonly bytes?: number;
+    /** The driver version the pack needs, for `driver_too_old`. */
+    readonly needsDriver?: string;
+}
+/** Whether `pack` can run here. */
+export declare function assessPack(hardware: Hardware, pack: PackId): PackAssessment;
+/** Compare dotted numeric versions. */
+export declare function compareVersions(a: string, b: string): number;
+/** The recommendation for this machine. */
+export interface Recommendation {
+    /** Cloud stays the default; local is recommended only with a usable NVIDIA card. */
+    readonly backend: 'cloud' | 'local';
+    /** The pack to install for torch-release models (the published format). */
+    readonly torchPack: PackId;
+    /** The pack to install for ONNX deliveries. */
+    readonly onnxPack: PackId;
+    /**
+     * Why: `cuda` (a supported NVIDIA card), `cpu_only` (no usable GPU runtime),
+     * `driver_update` (a supported card whose driver is too old), `gpu_too_old`.
+     */
+    readonly reason: 'cuda' | 'cpu_only' | 'driver_update' | 'gpu_too_old';
+    /** Set when an NPU was found; it waits for an ONNX model exported for it. */
+    readonly npuWaiting: boolean;
+    readonly packs: readonly PackAssessment[];
+}
+export declare function recommend(hardware: Hardware): Recommendation;
+/** Probe this machine once per process; blocking, a few seconds at most. */
+export declare function detectHardware(): Hardware;
+/** Parse `name,driver_version,memory.total` rows (memory in MiB) and optional `compute_cap` rows. */
+export declare function parseNvidiaRows(rows: string, capabilities?: readonly string[]): GpuInfo[];

package/node_modules/@openvulcan/vulcan-decision/lib/hardware.js

@@ -0,0 +1,207 @@
+/**
+ * What this machine offers the local model, and which runtime pack to recommend for it.
+ *
+ * Only ready-made runtimes are considered. NVIDIA cards run the CUDA packs, whose CUDA libraries
+ * come as NVIDIA's own wheels, so only the driver has to be recent enough; this package never
+ * installs or updates a driver. AMD, Intel and Apple graphics have no published runtime for these
+ * models, so they get the CPU pack or the cloud. An NPU is reported, but it needs an ONNX model
+ * exported for it, which is not published yet.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import { currentTarget, readLock } from './local/packs.js';
+/** Adapters that are not graphics hardware: the software renderer and remote or virtual displays. */
+const NON_GPU_ADAPTER = /microsoft basic (display|render)|remote display|virtual|indirect display|idd ?driver|parsec|citrix/i;
+export function assess(probes) {
+    const nvidia = probes.nvidia ?? [];
+    const others = probes.adapters
+        .filter(name => !NON_GPU_ADAPTER.test(name) && !nvidia.some(gpu => gpu.name === name) && !(probes.nvidia !== undefined && /nvidia/i.test(name)))
+        .map((name) => ({ name, vendor: vendorOf(name) }));
+    const target = currentTarget(probes.platform, probes.arch);
+    const npus = probes.npus.map((name) => ({ name, vendor: npuVendorOf(name) }));
+    if (probes.platform === 'darwin' && probes.arch === 'arm64')
+        npus.push({ name: 'Apple Neural Engine', vendor: 'apple' });
+    return {
+        platform: probes.platform, arch: probes.arch, ...target === undefined ? {} : { target },
+        totalMemory: probes.totalMemory, cpus: probes.cpus, gpus: [...nvidia, ...others], npus,
+    };
+}
+function vendorOf(name) {
+    if (/nvidia|geforce|quadro|tesla|rtx/i.test(name))
+        return 'nvidia';
+    if (/amd|radeon/i.test(name))
+        return 'amd';
+    if (/intel/i.test(name))
+        return 'intel';
+    if (/apple/i.test(name))
+        return 'apple';
+    return 'other';
+}
+function npuVendorOf(name) {
+    if (/intel|ai boost/i.test(name))
+        return 'intel';
+    if (/amd|ryzen/i.test(name))
+        return 'amd';
+    if (/qualcomm|hexagon|snapdragon/i.test(name))
+        return 'qualcomm';
+    return 'other';
+}
+/** Lowest compute capability the CUDA packs run on (Turing). */
+export const MIN_COMPUTE_CAPABILITY = 7.5;
+export function gpuGeneration(computeCapability) {
+    const capability = Number(computeCapability);
+    const supported = capability >= MIN_COMPUTE_CAPABILITY;
+    if (capability >= 12)
+        return { architecture: 'Blackwell', fp16: 'tensor-cores', bf16: true, supported };
+    if (capability >= 10)
+        return { architecture: 'Blackwell (data center)', fp16: 'tensor-cores', bf16: true, supported };
+    if (capability >= 9)
+        return { architecture: 'Hopper', fp16: 'tensor-cores', bf16: true, supported };
+    if (capability >= 8.9)
+        return { architecture: 'Ada Lovelace', fp16: 'tensor-cores', bf16: true, supported };
+    if (capability >= 8)
+        return { architecture: 'Ampere', fp16: 'tensor-cores', bf16: true, supported };
+    if (capability >= 7.5)
+        return { architecture: 'Turing', fp16: 'tensor-cores', bf16: false, supported };
+    if (capability >= 7)
+        return { architecture: 'Volta', fp16: 'tensor-cores', bf16: false, supported };
+    if (capability === 6 || capability === 5.3 || capability === 6.2)
+        return { architecture: 'Pascal', fp16: 'native', bf16: false, supported };
+    if (capability >= 6)
+        return { architecture: 'Pascal', fp16: 'slow', bf16: false, supported };
+    return { architecture: 'Maxwell or older', fp16: 'slow', bf16: false, supported };
+}
+/** Whether `pack` can run here. */
+export function assessPack(hardware, pack) {
+    const lock = readLock(pack);
+    const build = hardware.target === undefined ? undefined : lock.targets[hardware.target];
+    if (build === undefined)
+        return { pack, fit: 'no_build' };
+    const base = { pack, bytes: build.bytes };
+    if (lock.device === 'cpu')
+        return { ...base, fit: 'ok' };
+    const cards = hardware.gpus.filter(gpu => gpu.vendor === 'nvidia' && gpu.driver !== undefined);
+    if (cards.length === 0)
+        return { ...base, fit: 'no_nvidia_gpu' };
+    const best = cards.reduce((a, b) => Number(b.computeCapability ?? 0) > Number(a.computeCapability ?? 0) ? b : a);
+    const minimum = Number(lock.requires.compute_capability ?? MIN_COMPUTE_CAPABILITY);
+    if (best.computeCapability !== undefined && Number(best.computeCapability) < minimum)
+        return { ...base, fit: 'gpu_too_old' };
+    const needed = lock.requires.nvidia_driver;
+    if (needed !== undefined && best.driver !== undefined && compareVersions(best.driver, needed) < 0) {
+        return { ...base, fit: 'driver_too_old', needsDriver: needed };
+    }
+    return { ...base, fit: 'ok' };
+}
+/** Compare dotted numeric versions. */
+export function compareVersions(a, b) {
+    const left = a.split('.').map(Number);
+    const right = b.split('.').map(Number);
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return Math.sign(difference);
+    }
+    return 0;
+}
+export function recommend(hardware) {
+    const packs = ['onnx-cpu', 'onnx-cuda', 'torch-cpu', 'torch-cu128'].map(pack => assessPack(hardware, pack));
+    const fit = (pack) => packs.find(item => item.pack === pack)?.fit;
+    const torchCuda = fit('torch-cu128') === 'ok';
+    const onnxCuda = fit('onnx-cuda') === 'ok';
+    const cudaFits = [fit('torch-cu128'), fit('onnx-cuda')];
+    const reason = torchCuda || onnxCuda ? 'cuda'
+        : cudaFits.includes('driver_too_old') ? 'driver_update'
+            : cudaFits.includes('gpu_too_old') ? 'gpu_too_old' : 'cpu_only';
+    return {
+        backend: torchCuda || onnxCuda ? 'local' : 'cloud',
+        torchPack: torchCuda ? 'torch-cu128' : 'torch-cpu',
+        onnxPack: onnxCuda ? 'onnx-cuda' : 'onnx-cpu',
+        reason,
+        npuWaiting: hardware.npus.length > 0,
+        packs,
+    };
+}
+/** Longest wait for one probing command. */
+const PROBE_TIMEOUT_MS = 15_000;
+let cached;
+/** Probe this machine once per process; blocking, a few seconds at most. */
+export function detectHardware() {
+    cached ??= assess(systemProbes());
+    return cached;
+}
+function systemProbes() {
+    return {
+        platform: process.platform,
+        arch: process.arch,
+        totalMemory: os.totalmem(),
+        cpus: os.availableParallelism(),
+        nvidia: probeNvidia(),
+        adapters: process.platform === 'win32' ? windowsDevices('Win32_VideoController', 'Name') : linuxAdapters(),
+        npus: process.platform === 'win32' ? windowsNpus() : linuxNpus(),
+    };
+}
+function run(command, args) {
+    const result = spawnSync(command, args, { encoding: 'utf8', timeout: PROBE_TIMEOUT_MS, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+    return result.status === 0 ? result.stdout : undefined;
+}
+function probeNvidia() {
+    const rows = run('nvidia-smi', ['--query-gpu=name,driver_version,memory.total', '--format=csv,noheader,nounits']);
+    if (rows === undefined)
+        return undefined;
+    // Older drivers reject the field, which leaves the capability unknown.
+    const capabilities = run('nvidia-smi', ['--query-gpu=compute_cap', '--format=csv,noheader'])?.split(/\r?\n/).filter(Boolean);
+    return parseNvidiaRows(rows, capabilities);
+}
+/** Parse `name,driver_version,memory.total` rows (memory in MiB) and optional `compute_cap` rows. */
+export function parseNvidiaRows(rows, capabilities) {
+    return rows.split(/\r?\n/).filter(line => line.trim() !== '').map((line, index) => {
+        const [name = '', driver, memory] = line.split(',').map(field => field.trim());
+        const mib = Number(memory);
+        const capability = capabilities?.[index]?.trim();
+        return {
+            name,
+            vendor: 'nvidia',
+            ...driver ? { driver } : {},
+            ...Number.isFinite(mib) && mib > 0 ? { memoryBytes: mib * 1024 ** 2 } : {},
+            ...capability !== undefined && /^\d+\.\d+$/.test(capability) ? { computeCapability: capability } : {},
+        };
+    });
+}
+function windowsDevices(cimClass, field, filter = '') {
+    const output = run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-CimInstance ${cimClass}${filter}).${field}`]);
+    return output === undefined ? [] : output.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+}
+/** NPUs: Windows lists them in the `ComputeAccelerator` device class (Intel AI Boost, AMD IPU, Qualcomm Hexagon). */
+function windowsNpus() {
+    return windowsDevices('Win32_PnPEntity', 'Name', ` -Filter "PNPClass='ComputeAccelerator'"`);
+}
+/** Linux exposes accelerators under `/sys/class/accel` (Intel `intel_vpu`, AMD `amdxdna`). */
+function linuxNpus() {
+    if (process.platform !== 'linux')
+        return [];
+    try {
+        return fs.readdirSync('/sys/class/accel').map(device => {
+            try {
+                const driver = fs.readlinkSync(`/sys/class/accel/${device}/device/driver`).split('/').at(-1) ?? device;
+                return driver === 'intel_vpu' ? 'Intel NPU' : driver === 'amdxdna' ? 'AMD NPU' : driver;
+            }
+            catch {
+                return device;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function linuxAdapters() {
+    if (process.platform !== 'linux')
+        return [];
+    const output = run('lspci', []);
+    if (output === undefined)
+        return [];
+    return output.split(/\r?\n/).filter(line => /VGA compatible controller|3D controller|Display controller/.test(line))
+        .map(line => line.replace(/^.*?controller:\s*/, '').trim());
+}

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

@@ -0,0 +1,26 @@
+/** Overrides the default data directory of the command line; used by tests and isolated setups. */
+export declare const HOME_ENV = "VULCAN_DECISION_HOME";
+/**
+ * One data directory: installed runtime packs, installed models, partial downloads and, for the
+ * command line, its account file and settings. A host passes its own directory (dsh uses
+ * `$DSH_HOME/vulcan-decision`); the command line uses {@link defaultHome}.
+ */
+export declare class DecisionHome {
+    readonly root: string;
+    constructor(root: string);
+    /** `<root>/packs/<pack id>/`, one installed runtime pack each. */
+    get packs(): string;
+    /** `<root>/models/<install id>/`, one installed model package each. */
+    get models(): string;
+    /** Partial downloads, kept between attempts so an interrupted download resumes. */
+    get downloads(): string;
+    /** A file directly in the data directory, which is created first. */
+    file(name: string): string;
+    private dir;
+}
+/** The command line's data directory: `VULCAN_DECISION_HOME`, else `~/.vulcan-decision`. */
+export declare function defaultHome(): DecisionHome;
+/** Create `dir` and its parents with owner-only access. */
+export declare function createPrivateDir(dir: string): void;
+/** Write `text` to `file` through a temporary file, so readers never see a partial file. */
+export declare function writeFileAtomic(file: string, text: string): void;

package/node_modules/@openvulcan/vulcan-decision/lib/home.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** Overrides the default data directory of the command line; used by tests and isolated setups. */
+export const HOME_ENV = 'VULCAN_DECISION_HOME';
+/**
+ * One data directory: installed runtime packs, installed models, partial downloads and, for the
+ * command line, its account file and settings. A host passes its own directory (dsh uses
+ * `$DSH_HOME/vulcan-decision`); the command line uses {@link defaultHome}.
+ */
+export class DecisionHome {
+    root;
+    constructor(root) {
+        this.root = path.resolve(root);
+    }
+    /** `<root>/packs/<pack id>/`, one installed runtime pack each. */
+    get packs() {
+        return this.dir('packs');
+    }
+    /** `<root>/models/<install id>/`, one installed model package each. */
+    get models() {
+        return this.dir('models');
+    }
+    /** Partial downloads, kept between attempts so an interrupted download resumes. */
+    get downloads() {
+        return this.dir('downloads');
+    }
+    /** A file directly in the data directory, which is created first. */
+    file(name) {
+        createPrivateDir(this.root);
+        return path.join(this.root, name);
+    }
+    dir(name) {
+        const dir = path.join(this.root, name);
+        createPrivateDir(dir);
+        return dir;
+    }
+}
+/** The command line's data directory: `VULCAN_DECISION_HOME`, else `~/.vulcan-decision`. */
+export function defaultHome() {
+    return new DecisionHome(process.env[HOME_ENV] || path.join(os.homedir(), '.vulcan-decision'));
+}
+/** Create `dir` and its parents with owner-only access. */
+export function createPrivateDir(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32')
+        fs.chmodSync(dir, 0o700);
+}
+/** Write `text` to `file` through a temporary file, so readers never see a partial file. */
+export function writeFileAtomic(file, text) {
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, text, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Vulcan Decision: judges AI coding tool calls before they run, with OpenVulcan's cloud endpoints
+ * or a locally installed `vulcan-decision-shell` model.
+ */
+export * from '@openvulcan/openvulcan-account';
+export * from './cloud/edge.js';
+export * from './download.js';
+export * from './engine.js';
+export * from './hardware.js';
+export * from './home.js';
+export * from './local/engine.js';
+export * from './local/models.js';
+export * from './local/packs.js';
+export { WORKER_SCRIPT, WorkerProcess, type LoadResult, type ModelFormat, type ProbeResult as WorkerProbe } from './local/worker.js';
+export * from './protocol.js';
+export { renderCall } from './render.js';
+export { VERSION } from './version.js';

package/node_modules/@openvulcan/vulcan-decision/lib/index.js

@@ -0,0 +1,17 @@
+/**
+ * Vulcan Decision: judges AI coding tool calls before they run, with OpenVulcan's cloud endpoints
+ * or a locally installed `vulcan-decision-shell` model.
+ */
+export * from '@openvulcan/openvulcan-account';
+export * from './cloud/edge.js';
+export * from './download.js';
+export * from './engine.js';
+export * from './hardware.js';
+export * from './home.js';
+export * from './local/engine.js';
+export * from './local/models.js';
+export * from './local/packs.js';
+export { WORKER_SCRIPT, WorkerProcess } from './local/worker.js';
+export * from './protocol.js';
+export { renderCall } from './render.js';
+export { VERSION } from './version.js';

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

@@ -0,0 +1,54 @@
+/**
+ * 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 { type JudgeInput, type ModelResult } from '../protocol.js';
+import type { DecisionHome } from '../home.js';
+import { type PackId } from './packs.js';
+import { type LoadResult } from './worker.js';
+/** Which installed pack runs which installed model. */
+export interface LocalSelection {
+    readonly pack: PackId;
+    readonly model: string;
+}
+/** Split `inputs` into requests of at most `limit` inputs, in order; no limit means one request. */
+export declare function mergeRequests<T>(inputs: readonly T[], limit: number | undefined): T[][];
+/** Hand each caller back its own slice of the merged results. */
+export declare function splitResults<T>(groups: readonly (readonly unknown[])[], results: readonly T[]): T[][];
+/** Stop the process after this long without a judgement, to give its memory back. */
+export declare const LOCAL_IDLE_MS: number;
+export interface LocalStatus {
+    readonly running: boolean;
+    readonly selection?: LocalSelection;
+    readonly loaded?: LoadResult;
+}
+export declare class LocalEngine {
+    private readonly home;
+    private readonly idleMs;
+    private worker;
+    private current;
+    private idleTimer;
+    /** Loads and merged judgements run one at a time, in arrival order. */
+    private queue;
+    /** Callers waiting for the next merged judgement. */
+    private waiting;
+    /** Whether a drain of `waiting` is already queued behind the running work. */
+    private drainQueued;
+    constructor(home: DecisionHome, idleMs?: number);
+    status(): LocalStatus;
+    /**
+     * 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: LocalSelection, inputs: readonly JudgeInput[]): Promise<ModelResult[]>;
+    /** Load `selection` ahead of the first judgement. */
+    warm(selection: LocalSelection): Promise<LoadResult>;
+    stop(): void;
+    /** Answer every waiting caller, one selection at a time in arrival order. */
+    private drain;
+    /** Judge several callers' inputs with `selection` in merged requests; answers per caller. */
+    private run;
+    private ensure;
+    private armIdle;
+}