Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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 <variant>" 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 `<version>/<backend>` 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 `<version>/<variant>` 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.
1 change: 1 addition & 0 deletions docs/decisions/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
62 changes: 62 additions & 0 deletions src/engines/llamacpp-family-target.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
import { expect, it } from 'vitest'
import { LlamacppEngine } from './llamacpp.js'
import type { LlamacppEngineDeps } from './llamacpp.js'

/**
* The "Latest <variant>" 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<unknown>) =>
fn({ kind: _kind }),
exclusive: (fn: () => Promise<unknown>) => 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'])
})
13 changes: 10 additions & 3 deletions src/engines/llamacpp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -193,6 +194,12 @@ export class LlamacppEngine implements EngineHandle {
/**
* The build to move to: the offer of the update check; an explicit `<version>/<variant>` (no family
* check: the client chose); or only a variant — the newest of it in the provider's catalog.
*
* The "Latest <variant>" 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<EngineBuildKey | null> {
const current = this.deps.currentVersionBackend().trim()
Expand All @@ -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
}

/**
Expand Down
Loading