mlx-bun 0.0.13 → 0.2.0

package/src/model/generated/gemma4-e4b.ts

@@ -12,6 +12,7 @@
 import { MlxArray } from "../../mlx/array";
 import * as ops from "../../mlx/ops";
 import {
+  cacheSignature,
   disposing,
   fusedSdpaRuntimeOk,
   KVCache,
@@ -529,83 +530,34 @@ function sharerFullQuantG64B4VPliScal(layer: DecoderLayer, x: MlxArray, mask: Ma
 }
 
 export class GeneratedGemma4 extends Gemma4Model {
-  /** Per-layer cache classes must match what this file was generated
-   *  for; anything else runs the monolith path. */
+  /** Per-layer cache signatures must match what this file was generated for. */
   #matches(cache: Cache[]): boolean {
     return (
       cache.length === 24 &&
-      cache[0] instanceof RotatingQuantizedKVCache &&
-      cache[0].bits === 4 &&
-      cache[0].groupSize === 64 &&
-      cache[1] instanceof RotatingQuantizedKVCache &&
-      cache[1].bits === 4 &&
-      cache[1].groupSize === 64 &&
-      cache[2] instanceof RotatingQuantizedKVCache &&
-      cache[2].bits === 4 &&
-      cache[2].groupSize === 64 &&
-      cache[3] instanceof RotatingQuantizedKVCache &&
-      cache[3].bits === 8 &&
-      cache[3].groupSize === 64 &&
-      cache[4] instanceof RotatingQuantizedKVCache &&
-      cache[4].bits === 8 &&
-      cache[4].groupSize === 64 &&
-      cache[5] instanceof QuantizedKVCache &&
-      cache[5].bits === 4 &&
-      cache[5].groupSize === 64 &&
-      cache[6] instanceof RotatingQuantizedKVCache &&
-      cache[6].bits === 4 &&
-      cache[6].groupSize === 64 &&
-      cache[7] instanceof RotatingQuantizedKVCache &&
-      cache[7].bits === 4 &&
-      cache[7].groupSize === 64 &&
-      cache[8] instanceof RotatingQuantizedKVCache &&
-      cache[8].bits === 4 &&
-      cache[8].groupSize === 64 &&
-      cache[9] instanceof RotatingQuantizedKVCache &&
-      cache[9].bits === 8 &&
-      cache[9].groupSize === 64 &&
-      cache[10] instanceof RotatingQuantizedKVCache &&
-      cache[10].bits === 8 &&
-      cache[10].groupSize === 64 &&
-      cache[11] instanceof QuantizedKVCache &&
-      cache[11].bits === 8 &&
-      cache[11].groupSize === 64 &&
-      cache[12] instanceof RotatingQuantizedKVCache &&
-      cache[12].bits === 4 &&
-      cache[12].groupSize === 64 &&
-      cache[13] instanceof RotatingQuantizedKVCache &&
-      cache[13].bits === 4 &&
-      cache[13].groupSize === 64 &&
-      cache[14] instanceof RotatingQuantizedKVCache &&
-      cache[14].bits === 8 &&
-      cache[14].groupSize === 64 &&
-      cache[15] instanceof RotatingQuantizedKVCache &&
-      cache[15].bits === 4 &&
-      cache[15].groupSize === 64 &&
-      cache[16] instanceof RotatingQuantizedKVCache &&
-      cache[16].bits === 4 &&
-      cache[16].groupSize === 64 &&
-      cache[17] instanceof QuantizedKVCache &&
-      cache[17].bits === 4 &&
-      cache[17].groupSize === 64 &&
-      cache[18] instanceof RotatingQuantizedKVCache &&
-      cache[18].bits === 4 &&
-      cache[18].groupSize === 64 &&
-      cache[19] instanceof RotatingQuantizedKVCache &&
-      cache[19].bits === 4 &&
-      cache[19].groupSize === 64 &&
-      cache[20] instanceof RotatingQuantizedKVCache &&
-      cache[20].bits === 4 &&
-      cache[20].groupSize === 64 &&
-      cache[21] instanceof RotatingQuantizedKVCache &&
-      cache[21].bits === 4 &&
-      cache[21].groupSize === 64 &&
-      cache[22] instanceof RotatingQuantizedKVCache &&
-      cache[22].bits === 4 &&
-      cache[22].groupSize === 64 &&
-      cache[23] instanceof QuantizedKVCache &&
-      cache[23].bits === 4 &&
-      cache[23].groupSize === 64
+      cacheSignature(cache[0]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[1]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[2]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[3]) === "kv:rotating-quant:8:64" &&
+      cacheSignature(cache[4]) === "kv:rotating-quant:8:64" &&
+      cacheSignature(cache[5]) === "kv:quant:4:64" &&
+      cacheSignature(cache[6]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[7]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[8]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[9]) === "kv:rotating-quant:8:64" &&
+      cacheSignature(cache[10]) === "kv:rotating-quant:8:64" &&
+      cacheSignature(cache[11]) === "kv:quant:8:64" &&
+      cacheSignature(cache[12]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[13]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[14]) === "kv:rotating-quant:8:64" &&
+      cacheSignature(cache[15]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[16]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[17]) === "kv:quant:4:64" &&
+      cacheSignature(cache[18]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[19]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[20]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[21]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[22]) === "kv:rotating-quant:4:64" &&
+      cacheSignature(cache[23]) === "kv:quant:4:64"
     );
   }
 

package/src/model/glm52-cache.ts

@@ -88,7 +88,7 @@ function trimToTokens(array: MlxArray, tokens: number): MlxArray {
   const stop = [...array.shape];
   stop[1] = tokens;
   const view = array.slice(start, stop);
-  const exact = ops.contiguous(view);
+  const exact = ops.copyOf(view); // TRUE copy: see 2026-08-20 contiguous-view pin class
   view.dispose();
   return exact;
 }
@@ -225,6 +225,15 @@ export class Glm52Cache implements BatchableCache {
       throw new Error("native MTP cache cannot contain target DSA state");
   }
 
+  signature(): string {
+    if (this.role === "mtp") return "kv:mla:mtp";
+    return this.dsa ? "kv:mla:target:dsa" : "kv:mla:target";
+  }
+
+  bytesPerToken(): number {
+    return (this.kvLoraRank + this.ropeHeadDim + (this.dsa?.headDim ?? 0)) * 4;
+  }
+
   /** Append one equal-width row block without expanding it to per-head K/V. */
   append(latent: MlxArray, rope: MlxArray, dsa: MlxArray | null = null): void {
     const latentShape = latent.shape;
@@ -620,15 +629,16 @@ export class Glm52Cache implements BatchableCache {
     const nextWidth = this.offset - removablePad;
     const indices = ops.fromInt32([...keep], [keep.length]);
     const filterFamily = (array: MlxArray): MlxArray => {
-      const selected = ops.takeAxis(array, indices, 0);
-      if (removablePad === 0) return selected;
-      const view = selected.slice(
-        [0, removablePad, 0],
-        [keep.length, this.offset, array.shape[2]!],
-      );
-      const exact = ops.contiguous(view);
+      const trimmed = removablePad === 0
+        ? array
+        : array.slice(
+            [0, removablePad, 0],
+            [this.batchSize!, this.offset, array.shape[2]!],
+          );
+      const selected = ops.takeAxis(trimmed, indices, 0);
+      const exact = ops.copyOf(selected); // TRUE copy: see 2026-08-20 contiguous-view pin class
       selected.dispose();
-      view.dispose();
+      if (trimmed !== array) trimmed.dispose();
       return exact;
     };
 

package/src/model/glm52-memory.ts

@@ -4,6 +4,7 @@ import {
   type Glm52Config,
 } from "./glm52-config";
 import { ColibriGlm52Container } from "./glm52-container";
+import type { MemoryPlan } from "../memory-plan";
 
 export const GLM52_G5_GIB = 1024 ** 3;
 export const GLM52_G5_DEFAULT_MACHINE_BYTES = 32 * GLM52_G5_GIB;
@@ -73,8 +74,9 @@ export interface Glm52MemoryLineItems {
   readonly safetyMarginBytes: number;
 }
 
-export interface Glm52MemoryPlan {
+export interface Glm52MemoryPlan extends MemoryPlan {
   readonly schemaVersion: 1;
+  readonly strategy: "glm52-colibri";
   readonly preset: "g5-32gb-quality";
   readonly machineBytes: number;
   readonly processLimitBytes: number;
@@ -374,11 +376,14 @@ export function planGlm52Memory(
 
   return {
     schemaVersion: 1,
+    strategy: "glm52-colibri",
+    fits: true,
     preset: "g5-32gb-quality",
     machineBytes,
     processLimitBytes,
     osReserveBytes,
     contextTokens,
+    maxSafeContext: contextTokens,
     maxGenerationTokens,
     batchSize,
     enableMtp,
@@ -392,6 +397,28 @@ export function planGlm52Memory(
     mtpResidentSlots,
     mtpTotalSlots,
     lineItems,
+    weightsBytes: sum("GLM planned weights", [
+      lineItems.residentWeightsBytes,
+      lineItems.mainExpertSlabBytes,
+      lineItems.mtpExpertSlabBytes,
+    ]),
+    kvBytes: sum("GLM planned KV", [
+      lineItems.targetKvBytes,
+      lineItems.mtpKvBytes,
+    ]),
+    transientBytes: sum("GLM planned transient", [
+      lineItems.reconstructedKvTransientBytes,
+      lineItems.verifyBatchTransientBytes,
+    ]),
+    reserveBytes: sum("GLM planned reserves", [
+      lineItems.allocatorReserveBytes,
+      lineItems.bunNativeReserveBytes,
+      lineItems.safetyMarginBytes,
+    ]),
+    totalBytes: plannedProcessBytes,
+    usableBytes: processLimitBytes,
+    predictedDecodeTps: null,
+    allocatorLimitBytes: lineItems.allocatorReserveBytes,
     runtimeReserveBytes,
     plannedProcessBytes,
     processHeadroomBytes: processLimitBytes - plannedProcessBytes,

package/src/model/minicpm5.ts

@@ -24,6 +24,7 @@ import {
   type Mask,
 } from "./gemma4-base";
 import { CompiledFunction } from "../mlx/compile";
+import { runtimeValue } from "../runtime-config";
 
 /** Verbatim port of mlx_lm/models/activations.py:
  *    `@partial(mx.compile, shapeless=True) def swiglu(gate, x): return nn.silu(gate) * x`
@@ -207,7 +208,7 @@ export class LlamaMLP {
     // Plain sigmoid+mul+mul otherwise (M>1 prefill/training, or inside a compile
     // trace) — identical math either way. MLX_BUN_COMPILED_SWIGLU=0 disables.
     let hidden: MlxArray;
-    if (M === 1 && !isCompiledTrace() && process.env.MLX_BUN_COMPILED_SWIGLU !== "0") {
+    if (M === 1 && !isCompiledTrace() && runtimeValue("MLX_BUN_COMPILED_SWIGLU") !== "0") {
       hidden = compiledSwiglu(gate, up);
       gate.dispose();
       up.dispose();

package/src/model/profile.ts

@@ -0,0 +1,433 @@
+import type { ModelConfig } from "../config";
+import { configFingerprint } from "./fingerprint";
+import {
+  isDiffusionGemmaConfig,
+  isGlm52Config,
+  isMiniCPM5Config,
+  isQwen35Config,
+  isQwen3Config,
+  isQwen3MoeConfig,
+} from "./support";
+import { GENERATED } from "./generated";
+import { GENERIC_MODEL_TYPES, genericArgsFor, remapModelType } from "./universal/archs";
+
+export const ENGINE_CAPABILITIES = Object.freeze([
+  "autoregressive",
+  "colibri-container",
+  "diffusion",
+  "diffusion-gemma-graph",
+  "gemma4-graph",
+  "generated-graph",
+  "glm5.2-graph",
+  "minicpm5-graph",
+  "mixed-precision-kv",
+  "native-mtp",
+  "qwen3-graph",
+  "qwen3-moe-graph",
+  "qwen3.5-graph",
+  "recurrent-state",
+  "safetensors",
+  "streamed-experts",
+  "universal-dense-graph",
+  "vision-sidecar",
+] as const);
+
+export type EngineCapability = typeof ENGINE_CAPABILITIES[number];
+export type FidelityTier = "l1" | "l2" | "l3";
+
+export type FidelityTarget =
+  | Readonly<{ tier: "l1"; oracle: "mlx-lm"; claim: "bit-exact" }>
+  | Readonly<{ tier: "l2"; oracle: "mlx-optiq"; claim: "bit-exact" }>
+  | Readonly<{ tier: "l3"; oracle: null; claim: "measured" }>;
+
+export type ModelLoader = "safetensors" | "colibri";
+export type ModelGraph =
+  | "gemma4"
+  | "minicpm5"
+  | "qwen3.5"
+  | "qwen3"
+  | "qwen3-moe"
+  | "diffusion-gemma"
+  | "glm5.2"
+  | "universal-dense";
+export type GenerationLoop = "autoregressive" | "diffusion";
+export type ModelSpecialization = "artifact" | "dedicated" | "generated" | "generic";
+
+export interface ModelExecutionComposition {
+  readonly loader: ModelLoader;
+  readonly graph: ModelGraph;
+  readonly loop: GenerationLoop;
+  readonly specialization: ModelSpecialization;
+}
+
+/** A profile declares construction only. Request methods such as MTP, KV
+ * schemes, adapters, grammar, and sampling are resolved independently and
+ * cannot be rewritten by profile selection. */
+export interface ModelProfile {
+  readonly id: string;
+  /** Exact external identity. Family profiles omit this field. */
+  readonly artifactFingerprint?: string;
+  /** Structural guard for an exact artifact declaration. */
+  readonly configFingerprint?: string;
+  readonly fidelity: FidelityTarget;
+  readonly requiredCapabilities: readonly EngineCapability[];
+  readonly execution: ModelExecutionComposition;
+}
+
+export interface ArtifactModelProfile extends ModelProfile {
+  readonly artifactFingerprint: string;
+  readonly configFingerprint: string;
+}
+
+export interface ModelArtifactIdentity {
+  readonly fingerprint: string | null;
+  readonly configFingerprint: string;
+}
+
+export interface ResolvedModelProfile {
+  readonly profile: ModelProfile;
+  readonly artifact: ModelArtifactIdentity;
+  readonly exactArtifact: boolean;
+}
+
+export interface ResolveModelProfileOptions {
+  /** Explicit identity for a non-Hugging-Face artifact. The caller owns its
+   * provenance; mlx-bun never mistakes a local path for a content identity. */
+  readonly artifactFingerprint?: string | null;
+  /** Additional exact declarations composed with the shipped profiles. */
+  readonly artifactProfiles?: readonly ArtifactModelProfile[];
+  readonly engineCapabilities?: readonly EngineCapability[];
+}
+
+const L1: FidelityTarget = Object.freeze({
+  tier: "l1", oracle: "mlx-lm", claim: "bit-exact",
+});
+const L2: FidelityTarget = Object.freeze({
+  tier: "l2", oracle: "mlx-optiq", claim: "bit-exact",
+});
+const L3: FidelityTarget = Object.freeze({
+  tier: "l3", oracle: null, claim: "measured",
+});
+
+function freezeProfile<T extends ModelProfile>(profile: T): T {
+  Object.freeze(profile.fidelity);
+  Object.freeze(profile.requiredCapabilities);
+  Object.freeze(profile.execution);
+  return Object.freeze(profile);
+}
+
+function snapshotProfile(profile: ModelProfile): ModelProfile {
+  return freezeProfile({
+    ...profile,
+    fidelity: { ...profile.fidelity },
+    requiredCapabilities: [...profile.requiredCapabilities],
+    execution: { ...profile.execution },
+  });
+}
+
+/** Exact artifact declarations already backed by this repository's parity or
+ * measured evidence. A new revision gets the family profile until it earns a
+ * declaration of its own. */
+export const BUILTIN_ARTIFACT_PROFILES: readonly ArtifactModelProfile[] = Object.freeze([
+  freezeProfile({
+    id: "qwen3.8-27b-optiq-4bit",
+    artifactFingerprint:
+      "hf:mlx-community/Qwen3.8-27B-OptiQ-4bit@b04599de95d7a9bfbd7f208d347c0f10d9432a42",
+    configFingerprint: "50117975cb405944",
+    fidelity: L1,
+    requiredCapabilities: Object.freeze([
+      "safetensors", "autoregressive", "qwen3.5-graph", "recurrent-state", "vision-sidecar",
+    ]),
+    execution: Object.freeze({
+      loader: "safetensors",
+      graph: "qwen3.5",
+      loop: "autoregressive",
+      specialization: "artifact",
+    }),
+  }),
+  freezeProfile({
+    id: "glm5.2-colibri-int4-int8-mtp",
+    artifactFingerprint:
+      "hf:mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp@3cc8db99b1b13fc79325d987ba3c1c430766b3b8",
+    configFingerprint: "8b49d0941e18f1b9",
+    fidelity: L3,
+    requiredCapabilities: Object.freeze([
+      "colibri-container", "autoregressive", "glm5.2-graph", "streamed-experts",
+    ]),
+    execution: Object.freeze({
+      loader: "colibri",
+      graph: "glm5.2",
+      loop: "autoregressive",
+      specialization: "artifact",
+    }),
+  }),
+]);
+
+const FAMILY_PROFILES = {
+  gemma4Generated: freezeProfile({
+    id: "gemma4-generated",
+    fidelity: L1,
+    requiredCapabilities: ["safetensors", "autoregressive", "gemma4-graph", "generated-graph"],
+    execution: {
+      loader: "safetensors", graph: "gemma4", loop: "autoregressive", specialization: "generated",
+    },
+  }),
+  gemma4: freezeProfile({
+    id: "gemma4-dedicated",
+    fidelity: L1,
+    requiredCapabilities: ["safetensors", "autoregressive", "gemma4-graph"],
+    execution: {
+      loader: "safetensors", graph: "gemma4", loop: "autoregressive", specialization: "dedicated",
+    },
+  }),
+  minicpm5: freezeProfile({
+    id: "minicpm5-dedicated",
+    fidelity: L1,
+    requiredCapabilities: ["safetensors", "autoregressive", "minicpm5-graph"],
+    execution: {
+      loader: "safetensors", graph: "minicpm5", loop: "autoregressive", specialization: "dedicated",
+    },
+  }),
+  qwen35: freezeProfile({
+    id: "qwen3.5-dedicated",
+    fidelity: L1,
+    requiredCapabilities: ["safetensors", "autoregressive", "qwen3.5-graph", "recurrent-state"],
+    execution: {
+      loader: "safetensors", graph: "qwen3.5", loop: "autoregressive", specialization: "dedicated",
+    },
+  }),
+  qwen3: freezeProfile({
+    id: "qwen3-dedicated",
+    fidelity: L1,
+    requiredCapabilities: ["safetensors", "autoregressive", "qwen3-graph"],
+    execution: {
+      loader: "safetensors", graph: "qwen3", loop: "autoregressive", specialization: "dedicated",
+    },
+  }),
+  qwen3Moe: freezeProfile({
+    id: "qwen3-moe-dedicated",
+    fidelity: L1,
+    requiredCapabilities: ["safetensors", "autoregressive", "qwen3-moe-graph"],
+    execution: {
+      loader: "safetensors", graph: "qwen3-moe", loop: "autoregressive", specialization: "dedicated",
+    },
+  }),
+  diffusionGemma: freezeProfile({
+    id: "diffusion-gemma-dedicated",
+    fidelity: L2,
+    requiredCapabilities: ["safetensors", "diffusion", "diffusion-gemma-graph"],
+    execution: {
+      loader: "safetensors", graph: "diffusion-gemma", loop: "diffusion", specialization: "dedicated",
+    },
+  }),
+  glm52: freezeProfile({
+    id: "glm5.2-colibri",
+    fidelity: L3,
+    requiredCapabilities: ["colibri-container", "autoregressive", "glm5.2-graph", "streamed-experts"],
+    execution: {
+      loader: "colibri", graph: "glm5.2", loop: "autoregressive", specialization: "dedicated",
+    },
+  }),
+  universal: freezeProfile({
+    id: "universal-dense",
+    fidelity: L1,
+    requiredCapabilities: ["safetensors", "autoregressive", "universal-dense-graph"],
+    execution: {
+      loader: "safetensors", graph: "universal-dense", loop: "autoregressive", specialization: "generic",
+    },
+  }),
+} satisfies Record<string, ModelProfile>;
+
+/** Return a stable external fingerprint only when the directory is an exact HF
+ * snapshot revision. Relocation does not change the identity. Arbitrary local
+ * directories and mutable aliases intentionally return null. */
+export function externalArtifactFingerprint(modelDir: string): string | null {
+  const match = modelDir.replaceAll("\\", "/").match(
+    /(?:^|\/)models--([^/]+)\/snapshots\/([0-9a-f]{40,64})(?:\/|$)/i,
+  );
+  if (!match) return null;
+  const encodedRepo = match[1]!;
+  const separator = encodedRepo.indexOf("--");
+  if (separator <= 0 || separator === encodedRepo.length - 2) return null;
+  const repo = `${encodedRepo.slice(0, separator)}/${encodedRepo.slice(separator + 2)}`;
+  return `hf:${repo}@${match[2]!.toLowerCase()}`;
+}
+
+function familyProfile(config: ModelConfig, fingerprint: string): ModelProfile {
+  if (isGlm52Config(config)) return FAMILY_PROFILES.glm52;
+  if (isDiffusionGemmaConfig(config)) return FAMILY_PROFILES.diffusionGemma;
+  if (isMiniCPM5Config(config)) return FAMILY_PROFILES.minicpm5;
+  if (isQwen35Config(config)) return FAMILY_PROFILES.qwen35;
+  if (isQwen3MoeConfig(config)) return FAMILY_PROFILES.qwen3Moe;
+  if (isQwen3Config(config)) return FAMILY_PROFILES.qwen3;
+  if (config.modelType.startsWith("gemma4"))
+    return GENERATED.has(fingerprint) ? FAMILY_PROFILES.gemma4Generated : FAMILY_PROFILES.gemma4;
+  if (genericArgsFor(config)) return FAMILY_PROFILES.universal;
+
+  const arch = remapModelType(config.modelType);
+  throw new Error(
+    `unsupported model_type "${config.modelType}"` +
+    (arch !== config.modelType ? ` (mlx-lm remaps it to "${arch}")` : "") +
+    ` — targeted: gemma4*, diffusion_gemma, glm_moe_dsa, qwen3_5, qwen3, qwen3_moe, MiniCPM5;` +
+    ` generic (Tier-0): ${[...GENERIC_MODEL_TYPES].sort().join(", ")}`,
+  );
+}
+
+interface GraphMetadata {
+  readonly accepts: (config: ModelConfig) => boolean;
+  readonly capabilities: readonly EngineCapability[];
+}
+
+const GRAPH_METADATA: Readonly<Record<ModelGraph, GraphMetadata>> = Object.freeze({
+  "gemma4": {
+    accepts: (config) => config.modelType.startsWith("gemma4"),
+    capabilities: ["gemma4-graph"],
+  },
+  "minicpm5": { accepts: isMiniCPM5Config, capabilities: ["minicpm5-graph"] },
+  "qwen3.5": {
+    accepts: isQwen35Config,
+    capabilities: ["qwen3.5-graph", "recurrent-state"],
+  },
+  "qwen3": { accepts: isQwen3Config, capabilities: ["qwen3-graph"] },
+  "qwen3-moe": { accepts: isQwen3MoeConfig, capabilities: ["qwen3-moe-graph"] },
+  "diffusion-gemma": {
+    accepts: isDiffusionGemmaConfig,
+    capabilities: ["diffusion-gemma-graph"],
+  },
+  "glm5.2": {
+    accepts: isGlm52Config,
+    capabilities: ["glm5.2-graph", "streamed-experts"],
+  },
+  "universal-dense": {
+    accepts: (config) => {
+      try { return genericArgsFor(config) !== null; } catch { return false; }
+    },
+    capabilities: ["universal-dense-graph"],
+  },
+});
+
+function graphAccepts(profile: ModelProfile, config: ModelConfig): boolean {
+  return GRAPH_METADATA[profile.execution.graph].accepts(config);
+}
+
+function executionCapabilities(profile: ModelProfile): EngineCapability[] {
+  const required: EngineCapability[] = [profile.execution.loader === "colibri"
+    ? "colibri-container"
+    : "safetensors"];
+  if (profile.execution.loop === "diffusion") required.push("diffusion");
+  else required.push("autoregressive");
+  required.push(...GRAPH_METADATA[profile.execution.graph].capabilities);
+  if (profile.execution.specialization === "generated") required.push("generated-graph");
+  return required;
+}
+
+function validateProfile(profile: ModelProfile): void {
+  if (!profile.id) throw new Error("model profile id must not be empty");
+  if ((profile.artifactFingerprint === undefined) !== (profile.configFingerprint === undefined))
+    throw new Error(
+      `model profile ${profile.id} must declare artifactFingerprint and configFingerprint together`,
+    );
+  const fidelityOk =
+    (profile.fidelity.tier === "l1" && profile.fidelity.oracle === "mlx-lm" &&
+      profile.fidelity.claim === "bit-exact") ||
+    (profile.fidelity.tier === "l2" && profile.fidelity.oracle === "mlx-optiq" &&
+      profile.fidelity.claim === "bit-exact") ||
+    (profile.fidelity.tier === "l3" && profile.fidelity.oracle === null &&
+      profile.fidelity.claim === "measured");
+  if (!fidelityOk) throw new Error(`model profile ${profile.id} has an invalid fidelity contract`);
+  const expectedLoader = profile.execution.graph === "glm5.2" ? "colibri" : "safetensors";
+  const expectedLoop = profile.execution.graph === "diffusion-gemma"
+    ? "diffusion"
+    : "autoregressive";
+  if (profile.execution.loader !== expectedLoader || profile.execution.loop !== expectedLoop)
+    throw new Error(
+      `model profile ${profile.id} has an invalid execution composition for ` +
+      `${profile.execution.graph}`,
+    );
+  const declared = new Set(profile.requiredCapabilities);
+  const underdeclared = executionCapabilities(profile).filter((capability) => !declared.has(capability));
+  if (underdeclared.length)
+    throw new Error(
+      `model profile ${profile.id} does not declare execution capabilities: ` +
+      `${underdeclared.join(", ")}`,
+    );
+}
+
+export function resolveModelProfile(
+  config: ModelConfig,
+  options: ResolveModelProfileOptions = {},
+): ResolvedModelProfile {
+  const fingerprint = configFingerprint(config);
+  const artifactFingerprint = options.artifactFingerprint === undefined
+    ? externalArtifactFingerprint(config.modelDir)
+    : options.artifactFingerprint;
+  const artifactProfiles = options.artifactProfiles
+    ? [...BUILTIN_ARTIFACT_PROFILES, ...options.artifactProfiles]
+    : BUILTIN_ARTIFACT_PROFILES;
+  const capabilities = new Set(options.engineCapabilities ?? ENGINE_CAPABILITIES);
+
+  let profile: ModelProfile | undefined;
+  let exactArtifact = false;
+  if (artifactFingerprint) {
+    const matches = artifactProfiles.filter((entry) => {
+      validateProfile(entry);
+      return entry.artifactFingerprint === artifactFingerprint;
+    });
+    if (matches.length > 1)
+      throw new Error(`multiple model profiles declare artifact ${artifactFingerprint}`);
+    profile = matches[0];
+    if (profile) {
+      exactArtifact = true;
+      if (profile.configFingerprint !== fingerprint)
+        throw new Error(
+          `model profile ${profile.id} matched artifact ${artifactFingerprint}, but config fingerprint ` +
+          `${fingerprint} != declared ${profile.configFingerprint}; refusing to fall back`,
+        );
+      if (!graphAccepts(profile, config))
+        throw new Error(
+          `model profile ${profile.id} selects ${profile.execution.graph}, which is incompatible with ` +
+          `${config.modelType}; refusing to fall back`,
+        );
+    }
+  }
+  profile ??= familyProfile(config, fingerprint);
+  validateProfile(profile);
+  profile = snapshotProfile(profile);
+
+  const missing = profile.requiredCapabilities.filter((capability) => !capabilities.has(capability));
+  if (missing.length)
+    throw new Error(
+      `model profile ${profile.id} requires missing engine capabilities: ${missing.join(", ")}; ` +
+      `refusing to fall back`,
+    );
+
+  return Object.freeze({
+    profile,
+    artifact: Object.freeze({ fingerprint: artifactFingerprint, configFingerprint: fingerprint }),
+    exactArtifact,
+  });
+}
+
+/** Guard the factory seam when a caller passes a previously resolved profile. */
+export function assertResolvedModelProfile(
+  config: ModelConfig,
+  resolved: ResolvedModelProfile,
+): void {
+  const fingerprint = configFingerprint(config);
+  if (resolved.artifact.configFingerprint !== fingerprint)
+    throw new Error(
+      `model profile ${resolved.profile.id} was resolved for config ` +
+      `${resolved.artifact.configFingerprint}, not ${fingerprint}`,
+    );
+  if (!graphAccepts(resolved.profile, config))
+    throw new Error(
+      `model profile ${resolved.profile.id} selects ${resolved.profile.execution.graph}, ` +
+      `which is incompatible with ${config.modelType}`,
+    );
+  if (resolved.exactArtifact &&
+      resolved.profile.artifactFingerprint !== resolved.artifact.fingerprint)
+    throw new Error(
+      `model profile ${resolved.profile.id} does not match artifact ` +
+      `${resolved.artifact.fingerprint ?? "<unidentified>"}`,
+    );
+}