@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/engines/native-manifest.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Source-pinned root of trust for runtime engine downloads.
+ *
+ * The daemon can download native engine binaries (`llama-server`, …) on
+ * demand from the `native-v<version>` GitHub release (see
+ * `resolver.ts`). To make the *published gezel package* the trust anchor
+ * — rather than blindly trusting whatever the release happens to contain
+ * — we bake in:
+ *
+ *   - `NATIVE_ENGINE_RELEASE`  the release version this build resolves
+ *     against (the `native-v<X>` tag, minus the prefix).
+ *   - `SHA256SUMS_DIGEST`      the sha256 of that release's `SHA256SUMS`
+ *     asset. The resolver verifies the downloaded `SHA256SUMS` file
+ *     against this digest.
+ *   - `NATIVE_ENGINE_ARCHIVE_SHA256` every engine archive hash from that same
+ *     manifest. The resolver requires the requested archive to appear in
+ *     this source-bundled map, checks that the remote manifest agrees, and
+ *     hashes the downloaded archive against the bundled value.
+ *   - `NATIVE_ENGINE_MACOS_NOTARIZED` whether the pinned native release
+ *     was independently submitted to Apple's notary service. This is
+ *     release provenance, separate from notarizing an Electron app that
+ *     later embeds it. Bare command-line binaries cannot carry a stapled
+ *     ticket or pass app-bundle `spctl` assessment; runtime trust is the
+ *     accepted release workflow plus these source-pinned hashes and the
+ *     Developer ID signature.
+ *
+ * This mirrors the `NODE_SHA256` pin in
+ * [node-version.ts](../../../app/src/node-version.ts): a placeholder of
+ * all-zeros means "no public release pinned yet" and the resolver
+ * refuses to download (rather than trusting an unverifiable release).
+ *
+ * Bumping: use `scripts/pin-native-release.mjs`; it rewrites the release,
+ * manifest digest, and complete archive map together. Never hand-edit a
+ * digest to match a download — that defeats the point.
+ *
+ * Dev/integration override: set `GEZEL_NATIVE_ENGINE_VERSION` to point at
+ * a real dev release before the public pin exists. With the digest still
+ * a placeholder the resolver runs in "unpinned" mode — it verifies each
+ * archive against the release's own `SHA256SUMS` (catching corruption)
+ * but logs that it could not anchor to a baked-in digest.
+ */
+/** Native release version this build pins. Placeholder until first public release. */
+export declare const NATIVE_ENGINE_RELEASE = "0.1.49";
+/** sha256 of the pinned release's `SHA256SUMS` asset. All-zeros = unpinned. */
+export declare const SHA256SUMS_DIGEST = "51e9d1fcd18174967fed451d11a7401035076330dfedadd6a0ce396ab636cff7";
+/** Exact SHA256 values for every engine archive published by native-v0.1.49. */
+export declare const NATIVE_ENGINE_ARCHIVE_SHA256: Readonly<Record<string, string>>;
+/**
+ * True only when the pinned release's standalone macOS archives were
+ * Developer ID signed and accepted by Apple's notary service before
+ * packaging. Electron notarization is a separate distribution contract.
+ */
+export declare const NATIVE_ENGINE_MACOS_NOTARIZED = true;
+/** True when a sha256 hex string is the all-zeros placeholder. */
+export declare function isPlaceholderDigest(digest: string): boolean;
+/**
+ * Whether engine auto-download is even possible in this build: a real
+ * release is pinned, or a dev override points at one. When false, the
+ * lazy on-device hook stays dormant and the daemon shows the existing
+ * "install / point at an external engine" guidance instead of kicking a
+ * download that can't succeed.
+ */
+export declare function isEnginePinned(): boolean;
+/**
+ * Effective release version: the dev override env var wins over the
+ * source pin so integration tests can target a real dev release without
+ * editing source. Returns the version with any `native-v`/`v` prefix
+ * stripped (the resolver re-adds `native-v`).
+ */
+export declare function effectiveEngineRelease(): string;

package/dist/engines/native-manifest.js

@@ -0,0 +1,98 @@
+/**
+ * Source-pinned root of trust for runtime engine downloads.
+ *
+ * The daemon can download native engine binaries (`llama-server`, …) on
+ * demand from the `native-v<version>` GitHub release (see
+ * `resolver.ts`). To make the *published gezel package* the trust anchor
+ * — rather than blindly trusting whatever the release happens to contain
+ * — we bake in:
+ *
+ *   - `NATIVE_ENGINE_RELEASE`  the release version this build resolves
+ *     against (the `native-v<X>` tag, minus the prefix).
+ *   - `SHA256SUMS_DIGEST`      the sha256 of that release's `SHA256SUMS`
+ *     asset. The resolver verifies the downloaded `SHA256SUMS` file
+ *     against this digest.
+ *   - `NATIVE_ENGINE_ARCHIVE_SHA256` every engine archive hash from that same
+ *     manifest. The resolver requires the requested archive to appear in
+ *     this source-bundled map, checks that the remote manifest agrees, and
+ *     hashes the downloaded archive against the bundled value.
+ *   - `NATIVE_ENGINE_MACOS_NOTARIZED` whether the pinned native release
+ *     was independently submitted to Apple's notary service. This is
+ *     release provenance, separate from notarizing an Electron app that
+ *     later embeds it. Bare command-line binaries cannot carry a stapled
+ *     ticket or pass app-bundle `spctl` assessment; runtime trust is the
+ *     accepted release workflow plus these source-pinned hashes and the
+ *     Developer ID signature.
+ *
+ * This mirrors the `NODE_SHA256` pin in
+ * [node-version.ts](../../../app/src/node-version.ts): a placeholder of
+ * all-zeros means "no public release pinned yet" and the resolver
+ * refuses to download (rather than trusting an unverifiable release).
+ *
+ * Bumping: use `scripts/pin-native-release.mjs`; it rewrites the release,
+ * manifest digest, and complete archive map together. Never hand-edit a
+ * digest to match a download — that defeats the point.
+ *
+ * Dev/integration override: set `GEZEL_NATIVE_ENGINE_VERSION` to point at
+ * a real dev release before the public pin exists. With the digest still
+ * a placeholder the resolver runs in "unpinned" mode — it verifies each
+ * archive against the release's own `SHA256SUMS` (catching corruption)
+ * but logs that it could not anchor to a baked-in digest.
+ */
+/** Native release version this build pins. Placeholder until first public release. */
+export const NATIVE_ENGINE_RELEASE = '0.1.49';
+/** sha256 of the pinned release's `SHA256SUMS` asset. All-zeros = unpinned. */
+export const SHA256SUMS_DIGEST = '51e9d1fcd18174967fed451d11a7401035076330dfedadd6a0ce396ab636cff7';
+// BEGIN PINNED NATIVE ARCHIVE HASHES
+/** Exact SHA256 values for every engine archive published by native-v0.1.49. */
+export const NATIVE_ENGINE_ARCHIVE_SHA256 = Object.freeze({
+    'gezel-native-0.1.49-darwin-arm64-metal.tar.gz': 'a484487893151fdbe1ba5b3ea9d4dff3692efe8735e0a681d8f4ab84d5ffb09d',
+    'gezel-native-0.1.49-darwin-arm64.tar.gz': '7dc049ffd09dfb51befbf5c955e569556de6024991478eeb6900646e4672c723',
+    'gezel-native-0.1.49-linux-arm64-cpu.tar.gz': '19490ce26e843c2cab7321b91f9fac781ab3bab9ade6e3945543b312bf1a29e8',
+    'gezel-native-0.1.49-linux-arm64-cuda.tar.gz': '6802852803b0748d7ced99805a8aac281637f8816d02937460e64fbcd8da0637',
+    'gezel-native-0.1.49-linux-arm64.tar.gz': '8d3cd77b5c029fc0c4b4ae83000a72450008973eaf69168c4a21c58bfb75bf33',
+    'gezel-native-0.1.49-linux-x64-cpu.tar.gz': '030eaf798727ab13dcd7e7f4b3124c0f02e6f638e58f81c5d9a399c57d1c0a0a',
+    'gezel-native-0.1.49-linux-x64-cuda.tar.gz': 'd31d21d0c4c5504c9f29eaed32b500b26676bec0fd5ed23fdfd598baecafd748',
+    'gezel-native-0.1.49-linux-x64-vulkan.tar.gz': '114956cb94d174f00105f86b97ba932e1583cac80d9d0ab6b0edf396ea410506',
+    'gezel-native-0.1.49-linux-x64.tar.gz': 'd6a711c2be9329b00ad6bb20e4c16062677ef4d5804a2033d579b2347f5e2802',
+    'gezel-native-0.1.49-win32-arm64-cpu.zip': 'c2e8f10a45bae6cee4801845b605588c5b8b7b3c2e81a512e89296a2f9b7afce',
+    'gezel-native-0.1.49-win32-arm64.zip': '23173db21533dfe3f3189f5582cde9a0550859515b2c94688fb34d342d97e3e5',
+    'gezel-native-0.1.49-win32-x64-cpu.zip': 'cf6a8806e2c2b0a964804169cfb3d9283032536a6c262dc70b65a37b45451f3e',
+    'gezel-native-0.1.49-win32-x64-cuda.zip': '9a1e090829cf2f16389e1a01506853d8ac3ed151a32994831000c1c3658cef08',
+    'gezel-native-0.1.49-win32-x64-vulkan.zip': '0b7fe1cab3b881ac4a5cc24f08b0206c38edab30940ea79888a70776925a8bfb',
+    'gezel-native-0.1.49-win32-x64.zip': 'e8996f82ea358903010e050d6b8b93beec683286af512b11cd8eeefdea50aa6d',
+});
+// END PINNED NATIVE ARCHIVE HASHES
+/**
+ * True only when the pinned release's standalone macOS archives were
+ * Developer ID signed and accepted by Apple's notary service before
+ * packaging. Electron notarization is a separate distribution contract.
+ */
+export const NATIVE_ENGINE_MACOS_NOTARIZED = true;
+/** True when a sha256 hex string is the all-zeros placeholder. */
+export function isPlaceholderDigest(digest) {
+    return /^0{64}$/.test(digest.trim().toLowerCase());
+}
+/**
+ * Whether engine auto-download is even possible in this build: a real
+ * release is pinned, or a dev override points at one. When false, the
+ * lazy on-device hook stays dormant and the daemon shows the existing
+ * "install / point at an external engine" guidance instead of kicking a
+ * download that can't succeed.
+ */
+export function isEnginePinned() {
+    return ((!isPlaceholderDigest(SHA256SUMS_DIGEST) &&
+        Object.keys(NATIVE_ENGINE_ARCHIVE_SHA256).length > 0) ||
+        !!process.env.GEZEL_NATIVE_ENGINE_VERSION);
+}
+/**
+ * Effective release version: the dev override env var wins over the
+ * source pin so integration tests can target a real dev release without
+ * editing source. Returns the version with any `native-v`/`v` prefix
+ * stripped (the resolver re-adds `native-v`).
+ */
+export function effectiveEngineRelease() {
+    const override = process.env.GEZEL_NATIVE_ENGINE_VERSION;
+    const raw = override?.trim() ? override.trim() : NATIVE_ENGINE_RELEASE;
+    return raw.replace(/^native-v/, '').replace(/^v/, '');
+}

package/dist/engines/registry.d.ts

@@ -0,0 +1,88 @@
+import { type NativeEngineName } from '@bendyline/gezel';
+import { type EngineResolveEvent, resolveEngine } from './resolver.js';
+import type { SignaturePolicy } from './signature.js';
+/** Resolver entrypoint, injectable for tests. */
+type ResolveImpl = typeof resolveEngine;
+export declare const KNOWN_ENGINES: readonly NativeEngineName[];
+export declare function isKnownEngine(name: string): name is NativeEngineName;
+/**
+ * Snapshot of one in-flight (or recently-finished) engine resolve. Exposed
+ * via `GET /api/engines/binaries` so a client that mounted after the
+ * download started still renders an accurate progress bar.
+ */
+export interface EngineBinarySnapshot {
+    key: string;
+    engine: NativeEngineName;
+    variant?: string;
+    startedAt: string;
+    bytesWritten: number;
+    totalBytes: number;
+    phase: 'downloading' | 'verifying' | 'extracting';
+    /** Unpacking progress; `totalBytes` is 0 when the archive format reports none. */
+    extracted?: {
+        bytesWritten: number;
+        totalBytes: number;
+    };
+    retrying?: {
+        attempt: number;
+        maxAttempts: number;
+        delayMs: number;
+        reason: string;
+    };
+    finished: boolean;
+    error?: string;
+    binPath?: string;
+}
+/** What an engine install is doing right now, in words a person can read. */
+export declare function engineInstallPhase(snapshot: Pick<EngineBinarySnapshot, 'phase' | 'bytesWritten' | 'totalBytes' | 'extracted'>): string;
+type Listener = (event: EngineResolveEvent) => void;
+/**
+ * Owns the lifecycle of every in-flight engine-binary resolve, decoupled
+ * from the HTTP request that triggered it — a direct port of
+ * {@link import('../providers/image/pull-registry.js').ImageModelPullRegistry}
+ * for native engines. The resolve runs in a detached background task;
+ * HTTP requests (and the lazy on-device-chat hook) are just consumers that
+ * subscribe to the live events + cached snapshot. Disconnect detaches the
+ * consumer; the download keeps going. Cancel is the explicit `DELETE`.
+ */
+export declare class EngineBinaryRegistry {
+    private readonly entries;
+    private readonly controllers;
+    private readonly home;
+    private readonly signaturePolicy;
+    private readonly fetchImpl?;
+    private readonly resolveImpl;
+    constructor(opts: {
+        home: string;
+        signaturePolicy?: SignaturePolicy;
+        fetchImpl?: typeof fetch;
+        /** Test seam — defaults to the real {@link resolveEngine}. */
+        resolveImpl?: ResolveImpl;
+    });
+    key(engine: NativeEngineName, variant?: string): string;
+    /**
+     * Start (or attach to) a resolve for `engine`[`@variant`]. Idempotent —
+     * a second call while one is in flight returns the existing snapshot and
+     * does not start a parallel download. Returns synchronously-claimed state
+     * so the caller can immediately subscribe without racing the first event.
+     */
+    ensure(engine: NativeEngineName, variant?: string): {
+        key: string;
+        snapshot: EngineBinarySnapshot;
+        alreadyRunning: boolean;
+    };
+    list(): EngineBinarySnapshot[];
+    get(key: string): EngineBinarySnapshot | null;
+    /** Subscribe to live events; replays the latest snapshot immediately so a
+     *  late subscriber's progress bar isn't blank. Returns null if no entry. */
+    subscribe(key: string, listener: Listener): (() => void) | null;
+    /** Cancel an in-flight resolve (leaves the `.partial` for resume). */
+    cancel(key: string): boolean;
+    /** Test-only: abort + drop everything. */
+    clear(): void;
+    private replaySnapshot;
+    private consume;
+    private applyEvent;
+    private broadcast;
+}
+export {};

package/dist/engines/registry.js

@@ -0,0 +1,217 @@
+import { createLogger } from '@bendyline/gezel';
+import { resolveEngine } from './resolver.js';
+const log = createLogger('engine-registry');
+/** How long a finished resolve (done OR error) lingers so a reconnecting
+ *  client still sees the terminal state. Same rationale as the image-pull
+ *  registry's TTL. */
+const FINISHED_TTL_MS = 8_000;
+export const KNOWN_ENGINES = [
+    'llama-server',
+    'ds4-server',
+    'sd-server',
+    'whisper-server',
+    'uv',
+    'duckdb',
+];
+export function isKnownEngine(name) {
+    return KNOWN_ENGINES.includes(name);
+}
+/** What an engine install is doing right now, in words a person can read. */
+export function engineInstallPhase(snapshot) {
+    const pct = (done, total) => total > 0 ? ` (${Math.floor((done / total) * 100)}%)` : '';
+    if (snapshot.phase === 'extracting') {
+        const { bytesWritten = 0, totalBytes = 0 } = snapshot.extracted ?? {};
+        return `is unpacking${pct(bytesWritten, totalBytes)}`;
+    }
+    if (snapshot.phase === 'verifying')
+        return 'is being checked';
+    return `is downloading${pct(snapshot.bytesWritten, snapshot.totalBytes)}`;
+}
+/**
+ * Owns the lifecycle of every in-flight engine-binary resolve, decoupled
+ * from the HTTP request that triggered it — a direct port of
+ * {@link import('../providers/image/pull-registry.js').ImageModelPullRegistry}
+ * for native engines. The resolve runs in a detached background task;
+ * HTTP requests (and the lazy on-device-chat hook) are just consumers that
+ * subscribe to the live events + cached snapshot. Disconnect detaches the
+ * consumer; the download keeps going. Cancel is the explicit `DELETE`.
+ */
+export class EngineBinaryRegistry {
+    entries = new Map();
+    controllers = new Map();
+    home;
+    signaturePolicy;
+    fetchImpl;
+    resolveImpl;
+    constructor(opts) {
+        this.home = opts.home;
+        this.signaturePolicy = opts.signaturePolicy ?? 'require';
+        if (opts.fetchImpl)
+            this.fetchImpl = opts.fetchImpl;
+        this.resolveImpl = opts.resolveImpl ?? resolveEngine;
+    }
+    key(engine, variant) {
+        return `${engine}:${variant ?? 'default'}`;
+    }
+    /**
+     * Start (or attach to) a resolve for `engine`[`@variant`]. Idempotent —
+     * a second call while one is in flight returns the existing snapshot and
+     * does not start a parallel download. Returns synchronously-claimed state
+     * so the caller can immediately subscribe without racing the first event.
+     */
+    ensure(engine, variant) {
+        const key = this.key(engine, variant);
+        const existing = this.entries.get(key);
+        if (existing && !existing.snapshot.finished) {
+            return { key, snapshot: { ...existing.snapshot }, alreadyRunning: true };
+        }
+        const snapshot = {
+            key,
+            engine,
+            ...(variant ? { variant } : {}),
+            startedAt: new Date().toISOString(),
+            bytesWritten: 0,
+            totalBytes: 0,
+            phase: 'downloading',
+            finished: false,
+        };
+        const entry = { snapshot, listeners: new Set() };
+        this.entries.set(key, entry);
+        const controller = new AbortController();
+        this.controllers.set(key, controller);
+        void this.consume(key, engine, variant, controller.signal);
+        return { key, snapshot: { ...snapshot }, alreadyRunning: false };
+    }
+    list() {
+        return Array.from(this.entries.values()).map((e) => ({ ...e.snapshot }));
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        return entry ? { ...entry.snapshot } : null;
+    }
+    /** Subscribe to live events; replays the latest snapshot immediately so a
+     *  late subscriber's progress bar isn't blank. Returns null if no entry. */
+    subscribe(key, listener) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return null;
+        entry.listeners.add(listener);
+        this.replaySnapshot(entry.snapshot, listener);
+        return () => {
+            entry.listeners.delete(listener);
+        };
+    }
+    /** Cancel an in-flight resolve (leaves the `.partial` for resume). */
+    cancel(key) {
+        const controller = this.controllers.get(key);
+        const entry = this.entries.get(key);
+        if (!controller || !entry || entry.snapshot.finished)
+            return false;
+        controller.abort();
+        return true;
+    }
+    /** Test-only: abort + drop everything. */
+    clear() {
+        for (const controller of this.controllers.values())
+            controller.abort();
+        this.controllers.clear();
+        this.entries.clear();
+    }
+    replaySnapshot(snapshot, listener) {
+        listener({
+            type: 'progress',
+            bytesWritten: snapshot.bytesWritten,
+            totalBytes: snapshot.totalBytes,
+        });
+        if (snapshot.retrying)
+            listener({ type: 'retrying', ...snapshot.retrying });
+        if (snapshot.error)
+            listener({ type: 'error', error: snapshot.error });
+        else if (snapshot.finished && snapshot.binPath) {
+            listener({ type: 'done', binPath: snapshot.binPath, cached: false });
+        }
+    }
+    async consume(key, engine, variant, signal) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        try {
+            const gen = this.resolveImpl({
+                engine,
+                home: this.home,
+                signaturePolicy: this.signaturePolicy,
+                signal,
+                ...(variant ? { variant } : {}),
+                ...(this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}),
+            });
+            for await (const event of gen) {
+                this.applyEvent(entry, event);
+                this.broadcast(entry, event);
+                // Break on terminal: this calls gen.return(), which converts the
+                // resolver's pending post-error throw into a clean return (no
+                // unhandled rejection, no double error event).
+                if (event.type === 'done' || event.type === 'error')
+                    break;
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const errorEvent = { type: 'error', error: message };
+            this.applyEvent(entry, errorEvent);
+            this.broadcast(entry, errorEvent);
+            log.warn(`[engine-registry] ${key} crashed: ${message}`);
+        }
+        finally {
+            entry.snapshot.finished = true;
+            this.controllers.delete(key);
+            const timer = setTimeout(() => {
+                if (this.entries.get(key) === entry)
+                    this.entries.delete(key);
+            }, FINISHED_TTL_MS);
+            timer.unref?.();
+        }
+    }
+    applyEvent(entry, event) {
+        const s = entry.snapshot;
+        if (event.type === 'progress') {
+            s.bytesWritten = event.bytesWritten;
+            s.totalBytes = event.totalBytes;
+            s.phase = 'downloading';
+            delete s.retrying;
+        }
+        else if (event.type === 'retrying') {
+            s.retrying = {
+                attempt: event.attempt,
+                maxAttempts: event.maxAttempts,
+                delayMs: event.delayMs,
+                reason: event.reason,
+            };
+        }
+        else if (event.type === 'verifying') {
+            s.phase = 'verifying';
+            delete s.retrying;
+        }
+        else if (event.type === 'extracting') {
+            s.phase = 'extracting';
+            s.extracted = { bytesWritten: event.bytesWritten, totalBytes: event.totalBytes };
+        }
+        else if (event.type === 'done') {
+            s.binPath = event.binPath;
+            delete s.retrying;
+        }
+        else if (event.type === 'error') {
+            s.error = event.error;
+            delete s.retrying;
+        }
+    }
+    broadcast(entry, event) {
+        for (const listener of entry.listeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                log.warn(`[engine-registry] listener threw: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+    }
+}

package/dist/engines/resolver.d.ts

@@ -0,0 +1,121 @@
+import { type NativeEngineResolveEvent } from '@bendyline/gezel';
+import { type MxcArch, type NativeBinaryName } from '@bendyline/gezel/native';
+import { type SignaturePolicy, type SignatureResult, verifyCodeSignature } from './signature.js';
+/**
+ * Thrown for the "can't resolve, and that's expected/actionable" cases:
+ * no pinned release, asset missing, verification failed. Callers surface
+ * the message; they don't retry blindly.
+ */
+export declare class EngineUnavailableError extends Error {
+    constructor(message: string);
+}
+/**
+ * Unpacking progress. Deliberately not in NativeEngineResolveEventSchema: the
+ * install stream's clients parse that schema strictly, so a new event type on
+ * the wire would fail an older CLI mid-install. The registry snapshot carries
+ * it instead, and the stream route sends only a heartbeat for it.
+ */
+export interface EngineExtractingEvent {
+    type: 'extracting';
+    bytesWritten: number;
+    totalBytes: number;
+}
+export type EngineResolveEvent = NativeEngineResolveEvent | EngineExtractingEvent;
+export interface ResolveEngineOptions {
+    engine: NativeBinaryName;
+    home: string;
+    /** GPU backend for llama-server (`cuda`/`vulkan`/`metal`/`cpu`); omit for single-variant engines. */
+    variant?: string;
+    /** Native release version; defaults to the source pin / `GEZEL_NATIVE_ENGINE_VERSION`. */
+    version?: string;
+    /** Signature enforcement; defaults to `require` for first-party binaries. */
+    signaturePolicy?: SignaturePolicy;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+    /** Pre-resolved token: `undefined` = auto-resolve; `null` = explicitly none. */
+    token?: string | null;
+    /** Override the source-pinned SHA256SUMS digest (tests). */
+    expectedSha256sumsDigest?: string;
+    /** Override the source-bundled per-archive hashes (tests). */
+    expectedArchiveSha256?: Readonly<Record<string, string>>;
+    /** Override the pinned executable digest for a vendored engine (tests). */
+    expectedBinarySha256?: string;
+    /** Override the vendored engine's download URL (tests). */
+    vendoredUrlOverride?: string;
+    /** Override the GitHub API base (tests point this at a local fixture). */
+    githubApiBase?: string;
+    /** Override signature verification (tests — avoids spawning powershell/codesign). */
+    verifyOverride?: typeof verifyCodeSignature;
+}
+export interface EngineResolveResult {
+    binPath: string;
+    cached: boolean;
+    signature: SignatureResult;
+    version: string;
+    assetPlatformKey: string;
+}
+export interface ResolveVendoredMxcOptions {
+    /**
+     * `false` returns only an install that is already verified and never touches
+     * the network — what a caller passes when the security policy forbids app
+     * network access. Defaults to `true`.
+     */
+    allowDownload?: boolean;
+    signal?: AbortSignal;
+    platform?: NodeJS.Platform;
+    arch?: MxcArch | null;
+    fetchImpl?: typeof fetch;
+    tarballUrl?: string;
+    expectedIntegrity?: string;
+    expectedTarballSha256?: string;
+    expectedExecutorSha256?: string;
+    expectedLicenseSha256?: string;
+    verifyOverride?: typeof verifyCodeSignature;
+}
+/**
+ * Resolve Microsoft's MXC launcher (`wxc-exec.exe`) for an npm / CLI install,
+ * which has no Electron bundle to install it from. Windows only.
+ *
+ * Returns the verified launcher path, or `null` when there is none: another
+ * platform, an arch MXC ships nothing for, a store build, `allowDownload:
+ * false` with nothing installed, or any failed check. Never throws — without a
+ * launcher, sandboxed scripts run uncontained and the sandbox status says so.
+ *
+ * Unlike {@link resolveVendoredDuckdb} it does not stamp an environment
+ * variable: whether the launcher is used is the caller's decision, and the
+ * sandbox's lookup finds a verified install through `readVerifiedMxcExecutor`.
+ *
+ * The chain is entirely pinned in this build (`core/src/native/mxc-pin.ts`):
+ * npm's sha512 integrity and the sha256 of the tarball, the per-arch
+ * executable digest, the license digest, and Microsoft's Authenticode
+ * signature under policy `require`. Only the launcher and the license leave
+ * the tarball. The result lands in the directory the Electron installer also
+ * uses, with the same sentinel, so either installer satisfies the other.
+ */
+export declare function resolveVendoredMxc(home: string, opts?: ResolveVendoredMxcOptions): Promise<string | null>;
+export declare function resolveEngine(opts: ResolveEngineOptions): AsyncGenerator<EngineResolveEvent, EngineResolveResult, void>;
+/**
+ * Drain {@link resolveEngine} to its terminal result. Forwards each event
+ * to `onEvent`; throws {@link EngineUnavailableError} on a handled failure.
+ */
+export declare function resolveEngineToCompletion(opts: ResolveEngineOptions, onEvent?: (e: EngineResolveEvent) => void): Promise<EngineResolveResult>;
+/**
+ * The archive variant an engine lives in when the caller names none.
+ *
+ * These are facts about *where the archive is*, not backend choices:
+ *
+ *  - **ds4-server on Linux** ships only in the `-cuda` archive, sharing one
+ *    copy of the NVIDIA redistributables with llama-server's CUDA build
+ *    instead of shipping them twice (see scripts/native-payload.mjs).
+ *  - **llama-server on macOS** ships only in the `-metal` archive; there is no
+ *    `darwin-arm64-cpu` asset, and the bare `darwin-arm64` key holds
+ *    ds4/sd/whisper/uv but no llama-server. Omitting the variant there fails
+ *    the extract with "none of [gezel-llama-server, llama-server] were inside
+ *    it" — a loud error, but an avoidable one.
+ *
+ * Deriving both here is the point: every call site would otherwise have to
+ * remember, and one eventually won't. Where the variant is a genuine choice
+ * (llama-server on Linux/Windows: cuda / vulkan / cpu) this returns undefined
+ * and the decision stays with the caller.
+ */
+export declare function impliedEngineVariant(engine: NativeBinaryName, platform: NodeJS.Platform): string | undefined;