diff --git a/docs/decisions/2026-11-19-reuse-strata-profiles-from-the-model-catalog.md b/docs/decisions/2026-11-19-reuse-strata-profiles-from-the-model-catalog.md new file mode 100644 index 00000000..0979314f --- /dev/null +++ b/docs/decisions/2026-11-19-reuse-strata-profiles-from-the-model-catalog.md @@ -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. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index ff0f2403..1293c669 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -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) diff --git a/src/client/model-catalog.ts b/src/client/model-catalog.ts index 1e033f31..7c98d7d6 100644 --- a/src/client/model-catalog.ts +++ b/src/client/model-catalog.ts @@ -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)) diff --git a/src/client/strata-contracts.ts b/src/client/strata-contracts.ts index 86a88315..b9daf38f 100644 --- a/src/client/strata-contracts.ts +++ b/src/client/strata-contracts.ts @@ -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', @@ -136,6 +149,7 @@ export function parseStrataDescriptor(value: unknown): StrataModelDescriptor { keys(d, [ 'family', 'variant_id', + 'profile_id', 'name', 'license', 'gated', @@ -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 @@ -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( @@ -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) && @@ -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 @@ -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) } } diff --git a/src/contracts/strata.ts b/src/contracts/strata.ts index a8cfef8d..19802d7c 100644 --- a/src/contracts/strata.ts +++ b/src/contracts/strata.ts @@ -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 diff --git a/src/models/strata.ts b/src/models/strata.ts index 4c3b6519..73861f68 100644 --- a/src/models/strata.ts +++ b/src/models/strata.ts @@ -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' @@ -118,7 +118,7 @@ export class StrataRegistry { async verify(id: string, signal?: AbortSignal): Promise { 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() diff --git a/src/runtime/strata/strata-check.ts b/src/runtime/strata/strata-check.ts index d24eda65..72ecf795 100644 --- a/src/runtime/strata/strata-check.ts +++ b/src/runtime/strata/strata-check.ts @@ -1,4 +1,4 @@ -import { strataCudaProfile } from '../../client/strata-contracts.js' +import { strataCudaProfile, strataProfileId } from '../../client/strata-contracts.js' import type { StrataBackend, StrataMemoryMode, @@ -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) @@ -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' @@ -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 @@ -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) @@ -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) @@ -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 diff --git a/src/runtime/strata/strata-deepseek-prepare.test.ts b/src/runtime/strata/strata-deepseek-prepare.test.ts index 1e26d2d4..c9ee11b9 100644 --- a/src/runtime/strata/strata-deepseek-prepare.test.ts +++ b/src/runtime/strata/strata-deepseek-prepare.test.ts @@ -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/) +}) diff --git a/src/runtime/strata/strata-launch-settings.ts b/src/runtime/strata/strata-launch-settings.ts index fc3f0ae5..23974af9 100644 --- a/src/runtime/strata/strata-launch-settings.ts +++ b/src/runtime/strata/strata-launch-settings.ts @@ -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' @@ -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 @@ -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)) diff --git a/src/runtime/strata/strata-prepare-plan.ts b/src/runtime/strata/strata-prepare-plan.ts index 106ac2b7..e6503a7f 100644 --- a/src/runtime/strata/strata-prepare-plan.ts +++ b/src/runtime/strata/strata-prepare-plan.ts @@ -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' @@ -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, @@ -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, @@ -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, @@ -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 =