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,16 @@
---
date: 2026-11-19
title: Reuse Strata engine profiles from the model catalog
---

# Reuse Strata engine profiles from the model catalog

A Strata installation is keyed by its variant ID. The optional `profile_id`
selects an existing family-specific engine profile for validation, preparation,
memory estimates and launch. The persisted descriptor and digest retain both
identities. Older installed descriptors default to their original variant ID.

Catalog authors place explicit profiles in the optional `strata-profile-models`
collection with kind `strata-profile`. Earlier readers ignore that kind and
collection. The installation ID must be unique across all Strata collections.
Changing a model source or profile changes its descriptor digest.
1 change: 1 addition & 0 deletions docs/decisions/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -282,3 +282,4 @@ add a new one that says which record it supersedes.

- [Report optimal-backend cache write failures as core IO_ERROR with their cause](2026-11-18-optimal-backend-write-failures-are-core-io-errors.md)
- [2026-11-17 — Account for staged Strata sources in compatibility checks](2026-11-17-credit-strata-staging-in-preflight.md)
- [2026-11-19 — Reuse Strata engine profiles from the model catalog](2026-11-19-reuse-strata-profiles-from-the-model-catalog.md)
2 changes: 1 addition & 1 deletion src/client/model-catalog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ export function parseAtomicModelCatalog(
if (flmVariants.has(variant_id)) throw new Error('Duplicate FastFlowLM variant')
flmVariants.add(variant_id)
}
if (entry.kind === 'strata' || entry.kind === 'strata-cuda')
if (entry.kind === 'strata' || entry.kind === 'strata-cuda' || entry.kind === 'strata-profile')
parseStrataDefinition(entry as unknown as AtomicCatalogEntry)
sources(entry.definition)
if (entry.kind === 'chat' && (!Array.isArray(entry.files) || entry.files.length === 0))
Expand Down
41 changes: 34 additions & 7 deletions src/client/strata-contracts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,19 @@ const cudaProfiles = {
}
>

const baseProfiles = {
'iq3-xxs-dflash2': 'qwen38',
'q2-0-dflash2': 'qwen38',
'iq3-s-dflash2': 'qwen38',
'iq2-xs-dflash2': 'qwen38',
'ud-q4-k-xl-mtp': 'qwen36',
'ista-2-00bpw-dspark': 'deepseek41',
} as const

export function strataProfileId(d: StrataModelDescriptor): string {
return d.profile_id ?? d.variant_id
}

const packFiles = [
'pack/dense.bin',
'pack/experts.bin',
Expand Down Expand Up @@ -136,6 +149,7 @@ export function parseStrataDescriptor(value: unknown): StrataModelDescriptor {
keys(d, [
'family',
'variant_id',
'profile_id',
'name',
'license',
'gated',
Expand All @@ -157,7 +171,17 @@ export function parseStrataDescriptor(value: unknown): StrataModelDescriptor {
const recipe = recipes[family]
check(id(d.variant_id) && safePath(d.variant_id), 'variant id')
// These profiles are qualified for the CUDA catalog of this release.
const profile = strataCudaProfile(d.variant_id)
const profileId = d.profile_id === undefined ? d.variant_id : d.profile_id
check(id(profileId), 'profile id')
const profile = strataCudaProfile(profileId)
if (d.profile_id !== undefined) {
const profileFamily =
profile?.family ??
(Object.hasOwn(baseProfiles, profileId)
? baseProfiles[profileId as keyof typeof baseProfiles]
: undefined)
check(profileFamily === family, 'unknown or incompatible profile')
}
check(!profile || profile.family === family, 'profile family')
const drafting = profile?.drafting ?? recipe.drafting
const weightCount = profile?.weights ?? recipe.weights
Expand Down Expand Up @@ -277,7 +301,7 @@ export function parseStrataDescriptor(value: unknown): StrataModelDescriptor {
const prefix = String(inputs.weights[0]).replace(/-00001-of-\d{5}\.gguf$/, '')
const final = String(splitCount).padStart(5, '0')
const engram =
d.variant_id === 'ista-coder-dspark'
profileId === 'ista-coder-dspark'
? 'DeepSeek-V4.1-Flash-Engram-IQ4_NL.gguf'
: `${prefix}-${final}-of-${final}.gguf`
check(
Expand Down Expand Up @@ -384,14 +408,16 @@ export function parseStrataDescriptor(value: unknown): StrataModelDescriptor {

export function parseStrataDefinition(entry: AtomicCatalogEntry): StrataModelDescriptor {
check(
(entry.kind === 'strata' || entry.kind === 'strata-cuda') &&
(entry.kind === 'strata' || entry.kind === 'strata-cuda' || entry.kind === 'strata-profile') &&
entry.format === 'strata' &&
entry.files === undefined &&
entry.omit_revisions === undefined,
'catalog format'
)
const d = parseStrataDescriptor(entry.definition)
check(Boolean(strataCudaProfile(d.variant_id)) === (entry.kind === 'strata-cuda'), 'entry kind')
check((d.profile_id !== undefined) === (entry.kind === 'strata-profile'), 'entry profile')
if (!d.profile_id)
check(Boolean(strataCudaProfile(d.variant_id)) === (entry.kind === 'strata-cuda'), 'entry kind')
check(
Object.keys(entry.variants).length === 1 &&
Object.hasOwn(entry.variants, d.variant_id) &&
Expand All @@ -408,6 +434,7 @@ export function projectStrataCollection(catalog: AtomicModelCatalog) {
for (const [name, kind] of [
['strata-models', 'strata'],
['strata-cuda-models', 'strata-cuda'],
['strata-profile-models', 'strata-profile'],
] as const) {
const collection = catalog.collections[name]
if (collection === undefined) continue
Expand All @@ -422,13 +449,13 @@ export function projectStrataCollection(catalog: AtomicModelCatalog) {
record(ref) &&
typeof ref.model === 'string' &&
Object.hasOwn(catalog.models, ref.model) &&
catalog.models[ref.model]?.kind === kind &&
!seen.has(ref.model),
catalog.models[ref.model]?.kind === kind,
'collection reference'
)
const d = parseStrataDefinition(catalog.models[ref.model]!)
check(ref.variant === d.variant_id, 'collection variant')
seen.add(ref.model)
check(!seen.has(d.variant_id), 'duplicate variant id')
seen.add(d.variant_id)
models.push(d)
}
}
Expand Down
2 changes: 2 additions & 0 deletions src/contracts/strata.ts
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,8 @@ export interface StrataRequirements {
export interface StrataModelDescriptor {
family: StrataFamily
variant_id: string
/** Existing engine profile used by a separately installable catalog variant. */
profile_id?: string
name: string
license: string
gated: boolean
Expand Down
4 changes: 2 additions & 2 deletions src/models/strata.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { strataCudaProfile } from '../client/strata-contracts.js'
import { strataCudaProfile, strataProfileId } from '../client/strata-contracts.js'
import { parseStrataDescriptor } from '../client/index.js'
import { AtomicCoreError } from '../contracts/index.js'
import type { ModelYmlStrata } from '../contracts/index.js'
Expand Down Expand Up @@ -118,7 +118,7 @@ export class StrataRegistry {
async verify(id: string, signal?: AbortSignal): Promise<StrataModelEntry> {
const entry = await this.get(id)
const descriptor = entry.strata.descriptor
const externalEngram = strataCudaProfile(descriptor.variant_id)?.externalEngram
const externalEngram = strataCudaProfile(strataProfileId(descriptor))?.externalEngram
? descriptor.inputs.engram
: undefined
const headers = new Map<string, GgufMetadata>()
Expand Down
18 changes: 9 additions & 9 deletions src/runtime/strata/strata-check.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { strataCudaProfile } from '../../client/strata-contracts.js'
import { strataCudaProfile, strataProfileId } from '../../client/strata-contracts.js'
import type {
StrataBackend,
StrataMemoryMode,
Expand Down Expand Up @@ -29,7 +29,7 @@ export function planStrataMemory(
gpuBytes: number,
settings: StrataSettings
): { settings: StrataSettings; minimumVramBytes?: number } {
if (backend !== 'cuda' || descriptor.variant_id !== 'ud-q4-k-xl-mtp') return { settings }
if (backend !== 'cuda' || strataProfileId(descriptor) !== 'ud-q4-k-xl-mtp') return { settings }
const compact = gpuBytes < QWEN36_CUDA_EXTENDED_VRAM
const autoContext = compact
? Math.min(descriptor.context_length, QWEN36_CUDA_TEXT_CONTEXT)
Expand All @@ -44,7 +44,7 @@ export function planStrataMemory(
}

export function strataRamModeBytes(d: StrataModelDescriptor): number {
const readyPack = strataCudaProfile(d.variant_id)?.readyPack
const readyPack = strataCudaProfile(strataProfileId(d))?.readyPack
const weights = d.files
.filter((file) =>
readyPack ? ['ple', 'embedding', 'pack'].includes(file.role) : file.role === 'weights'
Expand All @@ -55,6 +55,8 @@ export function strataRamModeBytes(d: StrataModelDescriptor): number {

/** Conservative planning estimates for the pinned recipes. Values are not hardware qualification. */
export function estimateStrata(d: StrataModelDescriptor, input: Inputs): StrataResourceEstimate {
const profileId = strataProfileId(d)
const readyPack = strataCudaProfile(profileId)?.readyPack
const weights = d.files.filter((f) => f.role === 'weights').reduce((total, file) => total + file.size, 0)
const download_bytes = input.installed ? 0 : d.requirements.download_bytes - (input.stagedBytes ?? 0)
let derivative_bytes = 0
Expand All @@ -64,7 +66,7 @@ export function estimateStrata(d: StrataModelDescriptor, input: Inputs): StrataR
case 'qwen38':
// Dense tensors can widen to F32. Non-Metal also packs experts from every shard.
derivative_bytes = 64 * 2 ** 20
if (!strataCudaProfile(d.variant_id)?.readyPack)
if (!readyPack)
derivative_bytes +=
(d.inputs.drafting === 'dflash2' ? 522_458_112 : 0) +
(input.backend === 'metal' ? 8 * GiB : weights + 8 * GiB)
Expand All @@ -82,10 +84,8 @@ export function estimateStrata(d: StrataModelDescriptor, input: Inputs): StrataR
}
// The pinned CUDA Q4 recipe keeps about 18.75 GiB of routed experts in host memory.
// Round up the arena plus 12 GiB for the OS and runtime (31 GiB).
const qwen36Q4Ram =
input.backend === 'cuda' && d.variant_id === 'ud-q4-k-xl-mtp' ? Math.ceil(18.75 + 12) : 32
const qwen36Ram = d.variant_id === 'q8-0-mtp' ? 52 : d.variant_id === 'ud-q6-k-xl-mtp' ? 44 : qwen36Q4Ram
const readyPack = strataCudaProfile(d.variant_id)?.readyPack
const qwen36Q4Ram = input.backend === 'cuda' && profileId === 'ud-q4-k-xl-mtp' ? Math.ceil(18.75 + 12) : 32
const qwen36Ram = profileId === 'q8-0-mtp' ? 52 : profileId === 'ud-q6-k-xl-mtp' ? 44 : qwen36Q4Ram
const ram =
readyPack && input.memoryMode === 'ram'
? strataRamModeBytes(d)
Expand All @@ -94,7 +94,7 @@ export function estimateStrata(d: StrataModelDescriptor, input: Inputs): StrataR
const qwen36Vram = input.backend === 'cuda' ? QWEN36_CUDA_TEXT_VRAM : 8 * GiB
// One card must hold the DeepSeek Q8 dense weights; the 2-bit variants use a smaller dense set.
const vram =
d.variant_id === 'unsloth-ud-q8-k-xl'
profileId === 'unsloth-ud-q8-k-xl'
? 16_000 * 2 ** 20
: d.family === 'deepseek41'
? 8 * GiB
Expand Down
14 changes: 14 additions & 0 deletions src/runtime/strata/strata-deepseek-prepare.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,17 @@ it('uses the full four-shard DeepSeek recipe with explicit Engram, DSpark and vi
expect(d.inputs.experts_per_token).toBe(6)
expect(() => strataPreparationPlan(d, 'sycl', sourceDir, stagingDir)).toThrow()
})

it('prepares a catalog-defined installation with its explicit profile and enforces the profile backend', () => {
const base = parseStrataDescriptor(Object.values(catalog.models)[2]!.definition)
const d = { ...base, variant_id: 'another-publisher-flash', profile_id: base.variant_id }
expect(strataPreparationPlan(d, 'metal', sourceDir, stagingDir)).toEqual(
strataPreparationPlan(base, 'metal', sourceDir, stagingDir)
)
expect(parseStrataDescriptor(d).variant_id).toBe('another-publisher-flash')
const cuda = { ...d, profile_id: 'ista-1-75bpw-dspark', compatible_variants: ['linux-x64-cuda13'] }
expect(strataPreparationPlan(cuda, 'cuda', sourceDir, stagingDir).steps[0]?.id).toBe('deepseek-pack')
expect(() => strataPreparationPlan(cuda, 'metal', sourceDir, stagingDir)).toThrow(/CUDA/)
expect(() => parseStrataDescriptor({ ...d, profile_id: 'unknown' })).toThrow(/profile/)
expect(() => parseStrataDescriptor({ ...d, profile_id: 'iq3-xxs-dflash2' })).toThrow(/profile/)
})
7 changes: 4 additions & 3 deletions src/runtime/strata/strata-launch-settings.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { strataCudaProfile } from '../../client/strata-contracts.js'
import { strataCudaProfile, strataProfileId } from '../../client/strata-contracts.js'
import { isAbsolute, join } from 'node:path'
import { AtomicCoreError } from '../../contracts/index.js'
import type { StrataModelDescriptor } from '../../contracts/index.js'
Expand Down Expand Up @@ -37,7 +37,8 @@ export function strataLaunchConfig(descriptor: StrataModelDescriptor, input: Lau
reject('The selected GPU could not be mapped to a verified Strata device.')
if (![input.bundle, input.source, input.prepared, input.state].every((path) => isAbsolute(path)))
reject('Strata launch requires absolute paths.')
const readyPack = strataCudaProfile(descriptor.variant_id)?.readyPack
const profileId = strataProfileId(descriptor)
const readyPack = strataCudaProfile(profileId)?.readyPack
const expertsBytes =
descriptor.files.find((file) => readyPack && file.path === 'pack/experts.bin')?.size ?? 0
const GiB = 2 ** 30
Expand Down Expand Up @@ -93,7 +94,7 @@ export function strataLaunchConfig(descriptor: StrataModelDescriptor, input: Lau
source(i.embedding!)
)
} else {
const pleIndex = i.weights.length === 1 || descriptor.variant_id.startsWith('swift-') ? 0 : 1
const pleIndex = i.weights.length === 1 || profileId.startsWith('swift-') ? 0 : 1
if (i.weights.length <= 2) args.push('--ple-gguf', source(i.weights[pleIndex]!))
}
if (i.expert_profile) args.push('--expert-profile', source(i.expert_profile))
Expand Down
17 changes: 9 additions & 8 deletions src/runtime/strata/strata-prepare-plan.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { strataCudaProfile } from '../../client/strata-contracts.js'
import { strataCudaProfile, strataProfileId } from '../../client/strata-contracts.js'
import { isAbsolute, join, relative, resolve } from 'node:path'
import { parseStrataDescriptor } from '../../client/index.js'
import { AtomicCoreError, type StrataBackend } from '../../contracts/index.js'
Expand Down Expand Up @@ -52,12 +52,13 @@ export function strataPreparationPlan(
'pack/tokenizer/tokenizer.json',
'pack/tokenizer/chat_template.jinja',
].map((path) => ({ path }))
const profile = strataCudaProfile(d.variant_id)
const profileId = strataProfileId(d)
const profile = strataCudaProfile(profileId)
if (profile && backend !== 'cuda')
throw new AtomicCoreError('MODEL_INCOMPATIBLE', 'The Strata preparation profile requires CUDA.')
if (profile?.readyPack) return { gpuRequired: false, steps: [], readyPack: true }
if (d.family === 'qwen36') {
if (!['cuda', 'hip'].includes(backend) || (!profile && d.variant_id !== 'ud-q4-k-xl-mtp'))
if (!['cuda', 'hip'].includes(backend) || (!profile && profileId !== 'ud-q4-k-xl-mtp'))
throw new AtomicCoreError('MODEL_INCOMPATIBLE', 'Unsupported Qwen3.6 preparation profile.')
return {
gpuRequired: false,
Expand All @@ -72,11 +73,11 @@ export function strataPreparationPlan(
}
}
if (d.family === 'qwen38') {
const sharedQuant = ['q2-0-dflash2', 'iq3-s-dflash2'].includes(d.variant_id)
const sharedQuant = ['q2-0-dflash2', 'iq3-s-dflash2'].includes(profileId)
const additionalQuant =
(backend === 'metal' && sharedQuant) ||
(backend === 'cuda' && (sharedQuant || d.variant_id === 'iq2-xs-dflash2'))
if (d.variant_id !== 'iq3-xxs-dflash2' && !additionalQuant && !profile)
(backend === 'cuda' && (sharedQuant || profileId === 'iq2-xs-dflash2'))
if (profileId !== 'iq3-xxs-dflash2' && !additionalQuant && !profile)
throw new AtomicCoreError('MODEL_INCOMPATIBLE', 'Unsupported Qwen3.8 preparation profile.')
return {
gpuRequired: false,
Expand All @@ -96,7 +97,7 @@ export function strataPreparationPlan(
'--out',
output('pack'),
...(backend === 'metal' ? [] : ['--experts-bin']),
...(/^(unsloth|gyro)-/.test(d.variant_id) ? ['--compat-bf16'] : []),
...(/^(unsloth|gyro)-/.test(profileId) ? ['--compat-bf16'] : []),
],
outputs: [
...tokenizer,
Expand Down Expand Up @@ -131,7 +132,7 @@ export function strataPreparationPlan(
],
}
}
if (backend === 'sycl' || (!profile && d.variant_id !== 'ista-2-00bpw-dspark'))
if (backend === 'sycl' || (!profile && profileId !== 'ista-2-00bpw-dspark'))
throw new AtomicCoreError('MODEL_INCOMPATIBLE', 'Unsupported DeepSeek preparation profile.')
const expertProfile = d.files.find((f) => f.path === d.inputs.expert_profile)
const draftArgs =
Expand Down
Loading