@atomic-chat/core 0.5.1

package/dist/backend/optimal/optimal-cache.js

@@ -0,0 +1,198 @@
+/**
+ * The optimal-backend cache record and the recheck / refresh decisions around it. Port of
+ * `getCachedOptimalBackend`, `persistOptimalBackendCache`, `resolveConcreteOptimalBackend`,
+ * `refreshOptimalBackendCache` and `recheckOptimalBackend` from
+ * `extensions/llamacpp-upstream-extension/src/index.ts`, without the storage, events and timeouts.
+ *
+ * The app keeps the record in `localStorage[OPTIMAL_BACKEND_CACHE_KEY]`; the core keeps it in
+ * `<data>/atomic-core/optimal-backend.json` (`DataLayout.core.optimalBackend`). Same JSON either way.
+ *
+ * What the caller does around these functions (the entangled halves left in the app):
+ *   - skips both flows entirely on macOS (there are no GPU tiers to recommend);
+ *   - runs `detectIdealBackendType` under a 20 s timeout, mapping a timeout to `detection-failed`;
+ *   - on `detection_failed` throws the `BACKEND_DETECTION_FAILED` sentinel (the UI matches its
+ *     message) and leaves the record and any prior recommendation untouched;
+ *   - persists `record`, and for `recheckOptimalBackend` writes / removes
+ *     `BETTER_BACKEND_RECOMMENDATION_KEY` and emits `onBetterBackendDetected` with `payload`.
+ */
+import { resolveLatestVersionBackend } from '../catalog/index.js';
+import { backendCategoryToLabel, findLatestVersionForBackend, getBackendCategory } from '../select/index.js';
+import { isConcreteVersionBackend, stripBom } from '../version.js';
+export const OPTIMAL_BACKEND_CACHE_KEY = 'atomic_llamacpp_upstream_optimal_backend_v1';
+export const OPTIMAL_BACKEND_PROVIDER = 'llamacpp-upstream';
+/** Legacy recommendation key the `useBackendUpdater` mount path still reads. */
+export const BETTER_BACKEND_RECOMMENDATION_KEY = 'llama_cpp_better_backend_recommendation';
+/**
+ * Sentinel `Error.message` for "detection could not complete — keep the current backend"
+ * (ATO-161). The web-app handler matches the literal value; keep the two in sync.
+ */
+export const BACKEND_DETECTION_FAILED = 'BACKEND_DETECTION_FAILED';
+/**
+ * Validate a stored record. Anything with the wrong schema, provider, a non-finite or negative
+ * `detectedAt`, missing strings, a `gpu` record whose `recommendedBackend` is not a concrete
+ * `<tag>/<idealBackendId>`, or a `cpu-optimal` record carrying GPU fields is `null` (ignored).
+ */
+export function parseOptimalBackendCache(raw, provider = OPTIMAL_BACKEND_PROVIDER) {
+    if (!raw)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        if (value === null ||
+            typeof value !== 'object' ||
+            value.schemaVersion !== 1 ||
+            value.provider !== provider ||
+            !Number.isFinite(value.detectedAt) ||
+            value.detectedAt < 0 ||
+            typeof value.currentBackend !== 'string' ||
+            typeof value.recommendedCategory !== 'string' ||
+            !value.recommendedCategory) {
+            return null;
+        }
+        if (value.detectionKind === 'gpu') {
+            const recommendedType = typeof value.recommendedBackend === 'string'
+                ? stripBom(value.recommendedBackend).split('/')[1]
+                : undefined;
+            if (typeof value.idealBackendId !== 'string' ||
+                !value.idealBackendId ||
+                (value.recommendedBackend !== undefined &&
+                    (typeof value.recommendedBackend !== 'string' ||
+                        // TurboQuant's validator (`llamacpp-extension` index.ts) only asks for `<tag>/<id>`: the
+                        // fork has no `latest/` sentinel to exclude.
+                        (provider === 'llamacpp'
+                            ? stripBom(value.recommendedBackend).split('/').length !== 2
+                            : !isConcreteVersionBackend(value.recommendedBackend)) ||
+                        recommendedType !== stripBom(value.idealBackendId)))) {
+                return null;
+            }
+            return value;
+        }
+        if (value.detectionKind === 'cpu-optimal') {
+            if (value.idealBackendId !== undefined || value.recommendedBackend !== undefined)
+                return null;
+            return value;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The record to persist for a completed detection (`persistOptimalBackendCache` minus the write). */
+export function buildOptimalBackendCacheRecord(detection, currentBackend, recommendedBackend, now) {
+    if (detection.kind === 'cpu-optimal') {
+        return {
+            schemaVersion: 1,
+            provider: OPTIMAL_BACKEND_PROVIDER,
+            detectedAt: now,
+            detectionKind: 'cpu-optimal',
+            currentBackend,
+            recommendedCategory: 'CPU',
+        };
+    }
+    return {
+        schemaVersion: 1,
+        provider: OPTIMAL_BACKEND_PROVIDER,
+        detectedAt: now,
+        detectionKind: 'gpu',
+        currentBackend,
+        idealBackendId: detection.backend,
+        ...(recommendedBackend ? { recommendedBackend } : {}),
+        recommendedCategory: backendCategoryToLabel(getBackendCategory(detection.backend) ?? 'unknown'),
+    };
+}
+/**
+ * Concrete `<tag>/<backend>` for the detected ideal type: newest catalog entry of that type, else the
+ * newest remote asset (exact or family match), else the current backend's tag with the ideal type
+ * (so an in-family migration such as CUDA 13.1 → 13.3 still gets a target), else `null` when there is
+ * no current tag to borrow.
+ */
+export async function resolveConcreteOptimalBackend(idealType, currentBackend, deps, operation = 'resolveConcreteOptimalBackend') {
+    const warn = deps.onWarn ?? (() => { });
+    let recommended = null;
+    try {
+        recommended = findLatestVersionForBackend(await deps.listSupportedBackends(), idealType);
+    }
+    catch (err) {
+        warn(`${operation}: failed to resolve latest backend for ${idealType}, falling back to current version: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (recommended)
+        return recommended;
+    try {
+        recommended = resolveLatestVersionBackend(idealType, await deps.fetchRemoteBackends());
+    }
+    catch (err) {
+        warn(`${operation}: failed to fetch latest release for '${idealType}': ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (recommended)
+        return recommended;
+    const fallbackVersion = currentBackend.split('/')[0];
+    if (!fallbackVersion) {
+        warn(`${operation}: could not resolve a concrete tag for ${idealType} and no current backend tag to fall back to`);
+        return null;
+    }
+    return `${fallbackVersion}/${idealType}`;
+}
+/**
+ * Silent cache refresh (startup coordinator, once per launch). Never emits a recommendation. A
+ * failed concrete resolution still caches the `gpu` verdict, just without `recommendedBackend`.
+ */
+export async function refreshOptimalBackendCache(detection, currentBackend, resolveConcrete, now) {
+    if (detection.kind === 'detection-failed')
+        return { outcome: 'detection_failed' };
+    const current = stripBom(currentBackend);
+    if (detection.kind === 'cpu-optimal') {
+        return { outcome: 'cached', record: buildOptimalBackendCacheRecord(detection, current, null, now) };
+    }
+    let recommended = null;
+    try {
+        recommended = await resolveConcrete(detection.backend, current);
+    }
+    catch {
+        recommended = null;
+    }
+    return { outcome: 'cached', record: buildOptimalBackendCacheRecord(detection, current, recommended, now) };
+}
+/**
+ * Manual "Find optimal backend" / onboarding recheck. Same category *and* same backend type as the
+ * current build is `already_optimal` without resolving anything; otherwise the concrete target is
+ * resolved and compared — equal to current is `already_optimal`, nothing resolvable is
+ * `no_catalog_entry`, else `recommend` with the event payload.
+ */
+export async function recheckOptimalBackend(detection, currentBackend, resolveConcrete, now) {
+    if (detection.kind === 'detection-failed')
+        return { outcome: 'detection_failed' };
+    const current = stripBom(currentBackend);
+    if (detection.kind === 'cpu-optimal') {
+        return { outcome: 'cpu_optimal', record: buildOptimalBackendCacheRecord(detection, current, null, now) };
+    }
+    const idealType = detection.backend;
+    const idealCategory = getBackendCategory(idealType);
+    const currentType = current.split('/')[1] || '';
+    const currentCategory = getBackendCategory(currentType);
+    if (idealCategory === currentCategory && currentType === idealType) {
+        return {
+            outcome: 'already_optimal',
+            record: buildOptimalBackendCacheRecord(detection, current, current, now),
+        };
+    }
+    const recommended = await resolveConcrete(idealType, current);
+    const record = buildOptimalBackendCacheRecord(detection, current, recommended, now);
+    if (!recommended)
+        return { outcome: 'no_catalog_entry', record };
+    if (recommended === current)
+        return { outcome: 'already_optimal', record };
+    const [version, backendId] = recommended.split('/');
+    return {
+        outcome: 'recommend',
+        record,
+        payload: {
+            currentBackend: current,
+            recommendedBackend: recommended,
+            recommendedCategory: backendCategoryToLabel(idealCategory ?? 'unknown'),
+            provider: OPTIMAL_BACKEND_PROVIDER,
+            version: version ?? '',
+            backendId: backendId ?? '',
+        },
+    };
+}
+//# sourceMappingURL=optimal-cache.js.map

package/dist/backend/optimal/optimal-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimal-cache.js","sourceRoot":"","sources":["../../../src/backend/optimal/optimal-cache.ts"],"names":[],"mappings":"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"}

package/dist/backend/optimal/optimal-store.d.ts

@@ -0,0 +1,24 @@
+import type { LocalProviderId } from '../../contracts/index.js';
+import type { OptimalBackendCacheRecord } from '../types.js';
+export interface OptimalState {
+    revision: number;
+    optimal: OptimalBackendCacheRecord | null;
+}
+export type OptimalUpdate = {
+    status: 'updated';
+    current: OptimalState;
+} | {
+    status: 'conflict';
+    current: OptimalState;
+};
+export declare class OptimalBackendStore {
+    private readonly path;
+    private readonly onChange;
+    private readonly entries;
+    private pending;
+    private constructor();
+    static open(path: string, onChange?: (provider: LocalProviderId, state: OptimalState) => void): Promise<OptimalBackendStore>;
+    get(provider: LocalProviderId): OptimalState;
+    snapshot(): Record<string, OptimalState>;
+    set(provider: LocalProviderId, optimal: OptimalBackendCacheRecord | null, expectedRevision: number): Promise<OptimalUpdate>;
+}

package/dist/backend/optimal/optimal-store.js

@@ -0,0 +1,103 @@
+/** Durable, revisioned owner of optimal-backend recommendations. */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { parseOptimalBackendCache } from './optimal-cache.js';
+export class OptimalBackendStore {
+    path;
+    onChange;
+    entries = new Map();
+    pending = Promise.resolve();
+    constructor(path, onChange) {
+        this.path = path;
+        this.onChange = onChange;
+    }
+    static async open(path, onChange = () => { }) {
+        const store = new OptimalBackendStore(path, onChange);
+        const text = await readFile(path, 'utf8').catch(() => '');
+        if (!text.trim())
+            return store;
+        try {
+            const raw = JSON.parse(text);
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                return store;
+            const document = raw;
+            const entries = document['schemaVersion'] === 2 &&
+                document['providers'] &&
+                typeof document['providers'] === 'object' &&
+                !Array.isArray(document['providers'])
+                ? document['providers']
+                : document;
+            for (const [provider, value] of Object.entries(entries)) {
+                if (document['schemaVersion'] === 2) {
+                    if (!value || typeof value !== 'object' || Array.isArray(value))
+                        continue;
+                    const entry = value;
+                    if (!Number.isSafeInteger(entry['revision']) || entry['revision'] < 0)
+                        continue;
+                    const record = entry['optimal'] === null ? null : parseRecord(entry['optimal'], provider);
+                    if (entry['optimal'] !== null && !record)
+                        continue;
+                    store.entries.set(provider, { revision: entry['revision'], optimal: record });
+                }
+                else {
+                    // Stage 3c initially wrote `{provider: record}` without a revision.
+                    const record = parseRecord(value, provider);
+                    if (record)
+                        store.entries.set(provider, { revision: 0, optimal: record });
+                }
+            }
+        }
+        catch {
+            // One corrupt cache must not keep the core from starting.
+        }
+        return store;
+    }
+    get(provider) {
+        const state = this.entries.get(provider);
+        return state ? { ...state } : { revision: 0, optimal: null };
+    }
+    snapshot() {
+        return Object.fromEntries([...this.entries].map(([provider, state]) => [provider, { ...state }]));
+    }
+    async set(provider, optimal, expectedRevision) {
+        if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+            throw new AtomicCoreError('INVALID_ARGUMENT', 'expected_revision must be a non-negative integer');
+        }
+        if (optimal && !parseRecord(optimal, provider)) {
+            throw new AtomicCoreError('INVALID_ARGUMENT', 'Invalid optimal-backend record for provider');
+        }
+        const action = this.pending.then(async () => {
+            const previous = this.get(provider);
+            if (previous.revision !== expectedRevision)
+                return { status: 'conflict', current: previous };
+            const current = { revision: previous.revision + 1, optimal };
+            const next = Object.fromEntries(this.entries);
+            next[provider] = current;
+            const temporary = `${this.path}.tmp-${randomUUID()}`;
+            await mkdir(dirname(this.path), { recursive: true });
+            try {
+                await writeFile(temporary, `${JSON.stringify({ schemaVersion: 2, providers: next }, null, 2)}\n`, 'utf8');
+                await rename(temporary, this.path);
+            }
+            catch (error) {
+                await rm(temporary, { force: true }).catch(() => { });
+                throw error;
+            }
+            this.entries.set(provider, current);
+            this.onChange(provider, current);
+            return { status: 'updated', current };
+        });
+        this.pending = action.catch(() => { });
+        return action;
+    }
+}
+function parseRecord(value, provider) {
+    if (!value || typeof value !== 'object')
+        return null;
+    if (provider !== 'llamacpp-upstream' && provider !== 'llamacpp')
+        return null;
+    return parseOptimalBackendCache(JSON.stringify(value), provider);
+}
+//# sourceMappingURL=optimal-store.js.map

package/dist/backend/optimal/optimal-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimal-store.js","sourceRoot":"","sources":["../../../src/backend/optimal/optimal-store.ts"],"names":[],"mappings":"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"}

package/dist/backend/select/amd-rocm-pci-ids.d.ts

@@ -0,0 +1,3 @@
+export declare const AMD_ROCM_WINDOWS_PCI_IDS: ReadonlyArray<readonly [number, string]>;
+/** True when `deviceId` is a PCI id the upstream Windows HIP archive is compiled for. */
+export declare function isRocmSupportedPciId(deviceId: number): boolean;

package/dist/backend/select/amd-rocm-pci-ids.js

@@ -0,0 +1,57 @@
+// Port of src-tauri/plugins/tauri-plugin-llamacpp-upstream/src/amd_rocm_pci_ids.rs, which is
+// GENERATED there by scripts/gen-amd-rocm-pci-ids.mjs — re-sync by hand when the app's copy moves.
+//
+// AMD PCI device id -> LLVM gfx target, for GPUs that BOTH AMD supports on
+// Windows and the upstream `windows-rocm` archive is compiled for. Windows has
+// no `/sys/class/kfd`, so the PCI device id from Vulkan is the only gfx signal
+// available before the binary runs.
+//
+// Sources:
+//   https://rocm.docs.amd.com/projects/install-on-windows/en/latest/reference/system-requirements.html
+//   https://pci-ids.ucw.cz/v2.2/pci.ids
+//
+// Not covered, because pci.ids carries no board name matching AMD's row:
+//   - AMD Radeon RX 9060
+//   - AMD Radeon RX 7650 GRE
+//   - AMD Ryzen AI Max+ Pro 395
+//   - AMD Ryzen AI Max+ 395
+//   - AMD Ryzen AI Max Pro 390
+//   - AMD Ryzen AI Max 390
+//   - AMD Ryzen AI Max Pro 385
+//   - AMD Ryzen AI Max 385
+//   - AMD Ryzen AI Max Pro 380
+//   - AMD Ryzen AI 300 Series
+//   - AMD Ryzen AI 9 400 Series
+//   - AMD Ryzen AI MAX+ 495
+//   - AMD Ryzen AI MAX+ 492
+//   - AMD Ryzen AII MAX PRO 490
+// These reach ROCm only through the manual backend picker.
+export const AMD_ROCM_WINDOWS_PCI_IDS = [
+    [0x73f0, 'gfx1102'], // Navi 33 [Radeon RX 7600M XT]
+    [0x7448, 'gfx1100'], // Navi 31 [Radeon Pro W7900]
+    [0x7449, 'gfx1100'], // Navi 31 [Radeon Pro W7800 48GB]
+    [0x744a, 'gfx1100'], // Navi 31 [Radeon Pro W7900 Dual Slot]
+    [0x744b, 'gfx1100'], // Navi 31 [Radeon Pro W7900D]
+    [0x744c, 'gfx1100'], // Navi 31 [Radeon RX 7900 XT/7900 XTX/7900 GRE/7900M]
+    [0x745e, 'gfx1100'], // Navi 31 [Radeon Pro W7800]
+    [0x7460, 'gfx1101'], // Navi 32 GL-XL [AMD Radeon PRO V710]
+    [0x7461, 'gfx1101'], // Navi 32 [AMD Radeon PRO V710]
+    [0x7470, 'gfx1101'], // Navi 32 [Radeon PRO W7700]
+    [0x747e, 'gfx1101'], // Navi 32 [Radeon RX 7700 XT / 7800 XT]
+    [0x7480, 'gfx1102'], // Navi 33 [Radeon RX 7600/7600 XT/7600M XT/7600S/7700S / PRO W7600]
+    [0x7481, 'gfx1102'], // Navi 33 [Radeon Graphics]
+    [0x7483, 'gfx1102'], // Navi 33 [Radeon RX 7600M/7600M XT]
+    [0x7487, 'gfx1102'], // Navi 33 [Radeon Graphics]
+    [0x7489, 'gfx1102'], // Navi 33 [Radeon Pro W7500]
+    [0x748b, 'gfx1102'], // Navi 33 [Radeon Graphics]
+    [0x7499, 'gfx1102'], // Navi 33 [Radeon RX 7400/7300/Pro W7400]
+    [0x749f, 'gfx1102'], // Navi 33 [Radeon RX 7500]
+    [0x7550, 'gfx1201'], // Navi 48 [Radeon RX 9070/9070 XT/9070 GRE]
+    [0x7551, 'gfx1201'], // Navi 48 [Radeon AI PRO R9700]
+    [0x7590, 'gfx1200'], // Navi 44 [Radeon RX 9050 / 9060 XT]
+];
+/** True when `deviceId` is a PCI id the upstream Windows HIP archive is compiled for. */
+export function isRocmSupportedPciId(deviceId) {
+    return AMD_ROCM_WINDOWS_PCI_IDS.some(([supported]) => supported === deviceId);
+}
+//# sourceMappingURL=amd-rocm-pci-ids.js.map

package/dist/backend/select/amd-rocm-pci-ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amd-rocm-pci-ids.js","sourceRoot":"","sources":["../../../src/backend/select/amd-rocm-pci-ids.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,mGAAmG;AACnG,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAC/E,+EAA+E;AAC/E,oCAAoC;AACpC,EAAE;AACF,WAAW;AACX,uGAAuG;AACvG,wCAAwC;AACxC,EAAE;AACF,yEAAyE;AACzE,yBAAyB;AACzB,6BAA6B;AAC7B,gCAAgC;AAChC,4BAA4B;AAC5B,+BAA+B;AAC/B,2BAA2B;AAC3B,+BAA+B;AAC/B,2BAA2B;AAC3B,+BAA+B;AAC/B,8BAA8B;AAC9B,gCAAgC;AAChC,4BAA4B;AAC5B,4BAA4B;AAC5B,gCAAgC;AAChC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,wBAAwB,GAA6C;IAChF,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,+BAA+B;IACpD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,6BAA6B;IAClD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,kCAAkC;IACvD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,uCAAuC;IAC5D,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,8BAA8B;IACnD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,sDAAsD;IAC3E,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,6BAA6B;IAClD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,sCAAsC;IAC3D,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,gCAAgC;IACrD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,6BAA6B;IAClD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,wCAAwC;IAC7D,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,oEAAoE;IACzF,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,4BAA4B;IACjD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,qCAAqC;IAC1D,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,4BAA4B;IACjD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,6BAA6B;IAClD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,4BAA4B;IACjD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,0CAA0C;IAC/D,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,2BAA2B;IAChD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,4CAA4C;IACjE,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,gCAAgC;IACrD,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,qCAAqC;CAC3D,CAAA;AAED,yFAAyF;AACzF,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,OAAO,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAA;AAC/E,CAAC"}

package/dist/backend/select/categories.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Backend categories, priority and update checks. Port of the pure policy in
+ * `src-tauri/plugins/tauri-plugin-llamacpp-upstream/src/backend.rs` (`get_backend_category`,
+ * `prioritize_backends`, `find_latest_version_for_backend`, `check_backend_for_updates`) and of the
+ * decision half of `determineBestBackend` in `extensions/llamacpp-upstream-extension/src/index.ts`.
+ *
+ * Nothing here reads hardware, disk or network: the probe result (`GpuProbeInfo[]`) and the catalog
+ * are parameters.
+ */
+import type { BackendVersion, BestBackendResult, GpuProbeInfo, UpdateCheckResult } from '../types.js';
+/**
+ * Coarse category of a backend id for priority ranking and the "already optimal" comparison.
+ * ggml-org Windows names first (`cuda-13.` → `cuda-cu13`, `cuda-12.4`), then legacy janhq /
+ * TurboQuant names, `rocm`/`hip` before `vulkan` (a host holding both keeps the ROCm tier), the
+ * native CPU name, the legacy CPU buckets, and finally the bare arch. `null` for nothing matching.
+ * Verbatim quirk: `avx` is tested before `noavx`, so a `noavx` id categorises as `avx`.
+ *
+ * The app's `index.ts` carries a second, slightly narrower copy of this function (no `rocm`,
+ * `arm64`, `x64` buckets → `'unknown'`); this port keeps only the Rust one, so a ROCm
+ * recommendation is labelled `rocm` in the cache record where the app wrote `unknown`.
+ */
+export declare function getBackendCategory(backend: string): string | null;
+/** UI label of a category (app `backendCategoryToLabel`); unknown categories pass through. */
+export declare function backendCategoryToLabel(category: string): string;
+/**
+ * Best backend by category priority. CUDA tiers always lead (they carry no VRAM gate); with enough
+ * GPU memory ROCm and Vulkan come next, otherwise they rank below every CPU bucket. Within a
+ * category the newest build wins. No category matching → the first entry. Empty → `INVALID_ARGUMENT`.
+ */
+export declare function prioritizeBackends(versionBackends: readonly BackendVersion[], hasEnoughGpuMemory: boolean): BestBackendResult;
+/**
+ * Newest `<version>/<backend>` whose normalised id equals `backendType` (so a legacy id and its
+ * current equivalent both match), or `null`. The original backend spelling is kept in the result.
+ */
+export declare function findLatestVersionForBackend(versionBackends: readonly BackendVersion[], backendType: string): string | null;
+/**
+ * Whether a newer build of the current backend's (normalised) type exists. `new_version` is `"0"`
+ * and `target_backend` `null` when nothing newer or nothing at all is listed.
+ */
+export declare function checkBackendForUpdates(currentBackendString: string, versionBackends: readonly BackendVersion[]): UpdateCheckResult;
+/**
+ * Smallest GPU worth moving a host off the CPU build for (MiB). Platform-neutral on purpose: ATO-464
+ * lowered Linux to 2 GiB with reasoning that is a property of the backend, and Windows kept an
+ * inline 6 GiB that told a 4 GB Radeon owner "CPU is optimal" while a 4 GB GeForce got CUDA.
+ */
+export declare const GPU_BACKEND_MIN_VRAM_MIB: number;
+export declare function hasEnoughGpuMemory(gpus: readonly GpuProbeInfo[]): boolean;
+/** `prioritizeBackends` under the VRAM gate; `''` for an empty catalog (app `determineBestBackend`). */
+export declare function determineBestBackend(versionBackends: readonly BackendVersion[], gpus: readonly GpuProbeInfo[]): string;

package/dist/backend/select/categories.js

@@ -0,0 +1,178 @@
+/**
+ * Backend categories, priority and update checks. Port of the pure policy in
+ * `src-tauri/plugins/tauri-plugin-llamacpp-upstream/src/backend.rs` (`get_backend_category`,
+ * `prioritize_backends`, `find_latest_version_for_backend`, `check_backend_for_updates`) and of the
+ * decision half of `determineBestBackend` in `extensions/llamacpp-upstream-extension/src/index.ts`.
+ *
+ * Nothing here reads hardware, disk or network: the probe result (`GpuProbeInfo[]`) and the catalog
+ * are parameters.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+import { mapOldBackendToNew } from '../catalog/index.js';
+import { compareBackendVersionsForSort } from '../version.js';
+// ---------------------------------------------------------------------------------------------
+// Categories, priority, updates
+// ---------------------------------------------------------------------------------------------
+/**
+ * Coarse category of a backend id for priority ranking and the "already optimal" comparison.
+ * ggml-org Windows names first (`cuda-13.` → `cuda-cu13`, `cuda-12.4`), then legacy janhq /
+ * TurboQuant names, `rocm`/`hip` before `vulkan` (a host holding both keeps the ROCm tier), the
+ * native CPU name, the legacy CPU buckets, and finally the bare arch. `null` for nothing matching.
+ * Verbatim quirk: `avx` is tested before `noavx`, so a `noavx` id categorises as `avx`.
+ *
+ * The app's `index.ts` carries a second, slightly narrower copy of this function (no `rocm`,
+ * `arm64`, `x64` buckets → `'unknown'`); this port keeps only the Rust one, so a ROCm
+ * recommendation is labelled `rocm` in the cache record where the app wrote `unknown`.
+ */
+export function getBackendCategory(backend) {
+    if (backend.includes('cuda-13.'))
+        return 'cuda-cu13';
+    if (backend.includes('cuda-12.4'))
+        return 'cuda-cu12.4';
+    if (backend.includes('cuda-13-common_cpus') || backend.includes('cu13.0'))
+        return 'cuda-cu13.0';
+    if (backend.includes('cuda-12-common_cpus') || backend.includes('cu12.0'))
+        return 'cuda-cu12.0';
+    if (backend.includes('cuda-11-common_cpus') || backend.includes('cu11.7'))
+        return 'cuda-cu11.7';
+    if (backend.includes('rocm') || backend.includes('hip'))
+        return 'rocm';
+    if (backend.includes('vulkan'))
+        return 'vulkan';
+    if (backend.startsWith('win-cpu-'))
+        return 'cpu';
+    if (backend.includes('common_cpus'))
+        return 'common_cpus';
+    if (backend.includes('avx512'))
+        return 'avx512';
+    if (backend.includes('avx2'))
+        return 'avx2';
+    if (backend.includes('avx') && !backend.includes('avx2') && !backend.includes('avx512'))
+        return 'avx';
+    if (backend.includes('noavx'))
+        return 'noavx';
+    if (backend.endsWith('arm64'))
+        return 'arm64';
+    if (backend.endsWith('x64'))
+        return 'x64';
+    return null;
+}
+/** UI label of a category (app `backendCategoryToLabel`); unknown categories pass through. */
+export function backendCategoryToLabel(category) {
+    switch (category) {
+        case 'cuda-cu13':
+        case 'cuda-cu13.0':
+            return 'CUDA 13';
+        case 'cuda-cu12.4':
+        case 'cuda-cu12.0':
+            return 'CUDA 12';
+        case 'cuda-cu11.7':
+            return 'CUDA 11';
+        case 'vulkan':
+            return 'Vulkan';
+        default:
+            return category;
+    }
+}
+const GPU_FIRST_PRIORITIES = [
+    'cuda-cu13',
+    'cuda-cu13.0',
+    'cuda-cu12.4',
+    'cuda-cu12.0',
+    'cuda-cu11.7',
+    'rocm',
+    'vulkan',
+    'common_cpus',
+    'cpu',
+    'avx512',
+    'avx2',
+    'avx',
+    'noavx',
+    'arm64',
+    'x64',
+];
+const LOW_VRAM_PRIORITIES = [
+    'cuda-cu13',
+    'cuda-cu13.0',
+    'cuda-cu12.4',
+    'cuda-cu12.0',
+    'cuda-cu11.7',
+    'common_cpus',
+    'cpu',
+    'avx512',
+    'avx2',
+    'avx',
+    'noavx',
+    'arm64',
+    'x64',
+    'rocm',
+    'vulkan',
+];
+/**
+ * Best backend by category priority. CUDA tiers always lead (they carry no VRAM gate); with enough
+ * GPU memory ROCm and Vulkan come next, otherwise they rank below every CPU bucket. Within a
+ * category the newest build wins. No category matching → the first entry. Empty → `INVALID_ARGUMENT`.
+ */
+export function prioritizeBackends(versionBackends, hasEnoughGpuMemory) {
+    if (versionBackends.length === 0)
+        throw new AtomicCoreError('INVALID_ARGUMENT', 'No backends available');
+    const priorities = hasEnoughGpuMemory ? GPU_FIRST_PRIORITIES : LOW_VRAM_PRIORITIES;
+    for (const category of priorities) {
+        const matching = versionBackends.filter((vb) => getBackendCategory(vb.backend) === category);
+        const best = matching.sort(compareBackendVersionsForSort)[0];
+        if (best) {
+            return {
+                backend_string: `${best.version}/${best.backend}`,
+                version: best.version,
+                backend_type: best.backend,
+            };
+        }
+    }
+    const fallback = versionBackends[0];
+    return {
+        backend_string: `${fallback.version}/${fallback.backend}`,
+        version: fallback.version,
+        backend_type: fallback.backend,
+    };
+}
+/**
+ * Newest `<version>/<backend>` whose normalised id equals `backendType` (so a legacy id and its
+ * current equivalent both match), or `null`. The original backend spelling is kept in the result.
+ */
+export function findLatestVersionForBackend(versionBackends, backendType) {
+    const matching = versionBackends.filter((vb) => mapOldBackendToNew(vb.backend) === backendType);
+    const best = matching.sort(compareBackendVersionsForSort)[0];
+    return best ? `${best.version}/${best.backend}` : null;
+}
+/**
+ * Whether a newer build of the current backend's (normalised) type exists. `new_version` is `"0"`
+ * and `target_backend` `null` when nothing newer or nothing at all is listed.
+ */
+export function checkBackendForUpdates(currentBackendString, versionBackends) {
+    const parts = currentBackendString.split('/');
+    if (parts.length !== 2) {
+        throw new AtomicCoreError('INVALID_ARGUMENT', `Invalid current backend format: ${currentBackendString}`);
+    }
+    const effectiveType = mapOldBackendToNew(parts[1] ?? '');
+    const target = findLatestVersionForBackend(versionBackends, effectiveType);
+    if (target === null || target === currentBackendString) {
+        return { update_needed: false, new_version: '0', target_backend: null };
+    }
+    return { update_needed: true, new_version: target.split('/')[0] ?? '', target_backend: target };
+}
+/**
+ * Smallest GPU worth moving a host off the CPU build for (MiB). Platform-neutral on purpose: ATO-464
+ * lowered Linux to 2 GiB with reasoning that is a property of the backend, and Windows kept an
+ * inline 6 GiB that told a 4 GB Radeon owner "CPU is optimal" while a 4 GB GeForce got CUDA.
+ */
+export const GPU_BACKEND_MIN_VRAM_MIB = 2 * 1024;
+export function hasEnoughGpuMemory(gpus) {
+    return gpus.some((g) => (g.total_memory ?? 0) >= GPU_BACKEND_MIN_VRAM_MIB);
+}
+/** `prioritizeBackends` under the VRAM gate; `''` for an empty catalog (app `determineBestBackend`). */
+export function determineBestBackend(versionBackends, gpus) {
+    if (versionBackends.length === 0)
+        return '';
+    return prioritizeBackends(versionBackends, hasEnoughGpuMemory(gpus)).backend_string;
+}
+//# sourceMappingURL=categories.js.map