diff --git a/docs/decisions/2026-11-20-engine-update-resolves-family-backend-ids.md b/docs/decisions/2026-11-20-engine-update-resolves-family-backend-ids.md new file mode 100644 index 00000000..5be20a2e --- /dev/null +++ b/docs/decisions/2026-11-20-engine-update-resolves-family-backend-ids.md @@ -0,0 +1,26 @@ +--- +date: 2026-11-20 +title: "Resolve a minor-less family id when an engine update targets only a variant" +--- + +# 2026-11-20 — Resolve a minor-less family id when an engine update targets only a variant + +- **Context:** The "Latest " dropdown and the persisted `version_backend` use minor-less GPU + family ids (`win-cuda-13-x64`, `linux-cuda-13-x64`, `win-rocm-x64`), because ggml-org bumps the + CUDA toolkit and HIP minors between releases. `LlamacppEngine.target` used to look a variant-only + `POST /engines/:engine/update` target up in `catalog.available` by strict string equality, so a + family id never matched the catalog's concrete asset (`win-cuda-13.5-x64`) and the update was + refused with `BACKEND_TAG_UNRESOLVED` (HTTP 500) for a build the catalog does publish. The rest of + the core already resolves this case: `resolveLatestVersionBackend` matches an exact id first and + then picks the newest concrete member of the family, as `UPSTREAM_POLICY.resolveSentinel` and the + app's `resolveLatestBackendString` do. +- **Decision:** A variant-only update target resolves through `resolveLatestVersionBackend(variant, + catalog.available)` and the resulting `/` is parsed by the existing `parseKey`. + A variant the catalog truly lacks still raises `BACKEND_TAG_UNRESOLVED` with the same code, + message shape and details. +- **Consequences:** Updates chosen from the "Latest CUDA/ROCm" entries install the newest concrete + family build instead of failing; an explicit `/` target keeps its exact meaning + and gets no family rewrite. The refusal for an unknown or hardware-ineligible variant is unchanged. +- **Owner:** team +- **Links:** `src/engines/llamacpp.ts`, `src/backend/catalog/cuda-family.ts`, + `src/engines/llamacpp-family-target.test.ts`, Sentry issue ATOMIC-CHAT-CORE-DM. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index 77a55ce8..cb8a6338 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -291,3 +291,4 @@ add a new one that says which record it supersedes. - [Select Strata releases compatible with the running core](2026-11-19-skip-incompatible-strata-releases.md) - [Start Windows DeepSeek from existing Strata packs](2026-11-19-start-windows-deepseek-from-existing-strata-packs.md) - [Retry Strata session health checks before unloading](2026-11-19-retry-strata-session-health-checks.md) +- [Resolve a minor-less family id when an engine update targets only a variant](2026-11-20-engine-update-resolves-family-backend-ids.md) diff --git a/src/engines/llamacpp-family-target.test.ts b/src/engines/llamacpp-family-target.test.ts new file mode 100644 index 00000000..444a3e52 --- /dev/null +++ b/src/engines/llamacpp-family-target.test.ts @@ -0,0 +1,62 @@ +import { expect, it } from 'vitest' +import { LlamacppEngine } from './llamacpp.js' +import type { LlamacppEngineDeps } from './llamacpp.js' + +/** + * The "Latest " dropdown uses minor-less family ids (`win-cuda-13-x64`) while the release + * catalog publishes concrete assets (`win-cuda-13.5-x64`). An update that names the family must + * resolve to the newest concrete build, as `resolveLatestVersionBackend` does everywhere else. + */ +const available = [ + { version: 'b12244', backend: 'win-cuda-13.5-x64' }, + { version: 'b12244', backend: 'win-cpu-x64' }, + { version: 'b12100', backend: 'win-cuda-13.3-x64' }, +] + +it('resolves a minor-less CUDA family variant to the newest concrete catalog build', async () => { + const installed: string[] = [] + const deps = { + engine: 'llamacpp-upstream', + backends: { + operate: async (_kind: string, fn: (operation: { kind: string }) => Promise) => + fn({ kind: _kind }), + exclusive: (fn: () => Promise) => fn(), + install: async (version: string, variant: string) => { + installed.push(`${version}/${variant}`) + return { version, backend: variant, installed: true, path: '' } + }, + listInstalled: async () => [], + bundledPack: async () => null, + busyChecker: async () => async () => false, + remove: async () => false, + }, + advisor: { + catalog: async () => ({ provider: 'llamacpp-upstream', available, source: 'live' }), + checkUpdates: async () => ({ + provider: 'llamacpp-upstream', + current: 'b12100/win-cuda-13.3-x64', + current_kind: 'concrete', + update_needed: true, + new_version: 'b12244', + target_backend: 'b12244/win-cuda-13.5-x64', + same_family: true, + offer: 'b12244/win-cuda-13.5-x64', + }), + }, + currentVersionBackend: () => 'b12100/win-cuda-13.3-x64', + selectVersionBackend: async () => {}, + unloadSessions: async () => {}, + emit: () => {}, + } as unknown as LlamacppEngineDeps + + const result = await new LlamacppEngine(deps).update({ + task_id: 'engine-update-llamacpp-upstream', + target: { variant: 'win-cuda-13-x64' }, + }) + + expect(result).toMatchObject({ + updated: true, + active: { version: 'b12244', variant: 'win-cuda-13.5-x64' }, + }) + expect(installed).toEqual(['b12244/win-cuda-13.5-x64']) +}) diff --git a/src/engines/llamacpp.ts b/src/engines/llamacpp.ts index 9b5840f4..c5c26c2e 100644 --- a/src/engines/llamacpp.ts +++ b/src/engines/llamacpp.ts @@ -32,6 +32,7 @@ import type { EngineVersionsRequest, LlamacppProviderId, } from '../contracts/index.js' +import { resolveLatestVersionBackend } from '../backend/index.js' import type { BackendAdvisor, BackendOperation, BackendService } from '../backend/index.js' import { DOWNLOAD_CANCELLED } from '../downloads/index.js' import type { EngineHandle } from './service.js' @@ -193,6 +194,12 @@ export class LlamacppEngine implements EngineHandle { /** * The build to move to: the offer of the update check; an explicit `/` (no family * check: the client chose); or only a variant — the newest of it in the provider's catalog. + * + * The "Latest " dropdown names *minor-less family ids* (`win-cuda-13-x64`) while the + * catalog lists *concrete assets* (`win-cuda-13.5-x64`), so a variant-only target resolves through + * `resolveLatestVersionBackend`: an exact id first, then the newest concrete member of its family — + * the same resolution `UPSTREAM_POLICY.resolveSentinel` and the app's `resolveLatestBackendString` + * use. A variant the catalog truly lacks is still `BACKEND_TAG_UNRESOLVED`. */ private async target(request: EngineSwapUpdateRequest): Promise { const current = this.deps.currentVersionBackend().trim() @@ -208,14 +215,14 @@ export class LlamacppEngine implements EngineHandle { const { version, variant } = request.target if (version !== undefined) return { version, variant } const catalog = await this.deps.advisor.catalog({ current_backend: current, ...common }) - const newest = catalog.available.find((entry) => entry.backend === variant) - if (newest === undefined) + const newest = parseKey(resolveLatestVersionBackend(variant, catalog.available) ?? '') + if (newest === null) throw new AtomicCoreError( 'BACKEND_TAG_UNRESOLVED', `The ${this.engine} catalog has no ${variant} build for this computer.`, variant ) - return { version: newest.version, variant } + return newest } /**