mlx-bun 0.0.8 → 0.0.10

package/src/model/qwen3-delta.ts

@@ -192,7 +192,10 @@ export class SSMCache implements Cache {
   }
 
   makeMask(_N: number, _windowSize: number | null): Mask {
-    // B=1 single-stream: ssm_mask is None (no left-pad / variable lengths).
+    // ssm_mask is None both single-stream and in the batch lane: rows
+    // solo-prefill UNPADDED at B=1 (state never sees pad tokens), and
+    // batched decode feeds one real token per row — so unlike mlx-lm's
+    // left-padded batch-prefill there is never a pad position to mask.
     return { mode: "", arr: null };
   }
 
@@ -221,4 +224,48 @@ export class SSMCache implements Cache {
     this.conv = null;
     this.recurrent = null;
   }
+
+  // --- batch-lane dynamic-B ops (BatchScheduler only) ----------------------
+  // Both state slots are plain [B, ...] tensors with no temporal axis and no
+  // left-padding, so the batched twins of mergeKVRows/filterKVRows collapse
+  // to B-axis concat/take. `offset` is bookkeeping only for SSM layers (RoPE
+  // reads the FULL-attention caches; the linear-attn forward never reads it),
+  // so merged rows carrying different token counts share the max.
+
+  /** Merge a fully-prefilled solo row into a running batched cache (`prev`
+   *  null ⇒ the solo row becomes the batch). The returned cache owns fresh
+   *  arrays — or, when there is nothing to concat, arrays STOLEN from `solo`
+   *  (nulled there so the scheduler's unconditional dispose of the solo
+   *  caches stays safe). `prev`/`solo` disposal remains the caller's job. */
+  static mergeRows(prev: SSMCache | null, solo: SSMCache): SSMCache {
+    if (!solo.conv || !solo.recurrent)
+      throw new Error("SSMCache.mergeRows: solo row has no state (prefill first)");
+    const out = new SSMCache();
+    if (prev) {
+      if (!prev.conv || !prev.recurrent)
+        throw new Error("SSMCache.mergeRows: batched cache has no state");
+      out.conv = ops.concatAxis([prev.conv, solo.conv], 0);
+      out.recurrent = ops.concatAxis([prev.recurrent, solo.recurrent], 0);
+    } else {
+      out.conv = solo.conv;
+      out.recurrent = solo.recurrent;
+      solo.conv = null;
+      solo.recurrent = null;
+    }
+    out.offset = Math.max(prev?.offset ?? 0, solo.offset);
+    return out;
+  }
+
+  /** Evict rows not in `keep` (ascending row indices), in place. */
+  filter(keep: number[]): void {
+    if (!this.conv || !this.recurrent) return;
+    const idx = ops.fromInt32(keep, [keep.length]);
+    const conv = ops.takeAxis(this.conv, idx, 0);
+    const recurrent = ops.takeAxis(this.recurrent, idx, 0);
+    idx.dispose();
+    this.conv.dispose();
+    this.recurrent.dispose();
+    this.conv = conv;
+    this.recurrent = recurrent;
+  }
 }

package/src/model/qwen3.ts

@@ -0,0 +1,276 @@
+// Concrete model graph for plain Qwen3 (Qwen3ForCausalLM).
+// Port target: mlx_lm.models.qwen3. A standard dense decoder — GQA softmax
+// attention with per-head q/k RMSNorm (applied over head_dim BEFORE RoPE),
+// full-head RoPE (theta 1e6), SwiGLU MLP, RMSNorm, tied embeddings.
+//
+// Primary use here is as a TEXT-EMBEDDING backbone (mlx-community Qwen3-Embedding-*):
+// `embedPooled` returns the last-token hidden, L2-normalized — the pooling
+// Qwen3-Embedding was trained with (an <|endoftext|> token is appended by the
+// caller; its hidden is the sentence vector). The full causal-LM surface
+// (forward/generate via the tied head) is wired too so it conforms to RuntimeModel.
+
+import type { ModelConfig } from "../config";
+import type { Weights } from "../weights";
+import { MlxArray } from "../mlx/array";
+import * as ops from "../mlx/ops";
+import {
+  argmaxLastPosition,
+  disposing,
+  KVCache,
+  LoraState,
+  QuantizedEmbedding,
+  QuantizedLinear,
+  RMSNorm,
+  type Cache,
+  type Mask,
+} from "./gemma4-base";
+
+class Qwen3Attention {
+  readonly qProj: QuantizedLinear;
+  readonly kProj: QuantizedLinear;
+  readonly vProj: QuantizedLinear;
+  readonly oProj: QuantizedLinear;
+  readonly qNorm: RMSNorm;
+  readonly kNorm: RMSNorm;
+  readonly nHeads: number;
+  readonly nKvHeads: number;
+  readonly headDim: number;
+  readonly scale: number;
+  readonly ropeBase: number;
+
+  constructor(weights: Weights, config: ModelConfig, prefix: string) {
+    const t = config.text;
+    this.nHeads = t.numAttentionHeads;
+    this.nKvHeads = t.numKeyValueHeads;
+    this.headDim = t.headDim;
+    this.scale = Math.pow(this.headDim, -0.5);
+    this.ropeBase = t.ropeParameters.full_attention?.ropeTheta ?? 1000000;
+    this.qProj = QuantizedLinear.load(weights, `${prefix}.q_proj`, config);
+    this.kProj = QuantizedLinear.load(weights, `${prefix}.k_proj`, config);
+    this.vProj = QuantizedLinear.load(weights, `${prefix}.v_proj`, config);
+    this.oProj = QuantizedLinear.load(weights, `${prefix}.o_proj`, config);
+    this.qNorm = new RMSNorm(weights.tensor(`${prefix}.q_norm.weight`), t.rmsNormEps);
+    this.kNorm = new RMSNorm(weights.tensor(`${prefix}.k_norm.weight`), t.rmsNormEps);
+  }
+
+  forward(x: MlxArray, mask: Mask, cache: Cache): MlxArray {
+    const [B, L] = x.shape as [number, number, number];
+    let q = this.qProj.forward(x);
+    let k = this.kProj.forward(x);
+    let v = this.vProj.forward(x);
+
+    // Reshape to heads, then q/k RMSNorm over head_dim BEFORE transpose+RoPE
+    // (mlx-lm qwen3 reference order).
+    q = disposing(q, ops.reshape(q, [B, L, this.nHeads, this.headDim]));
+    k = disposing(k, ops.reshape(k, [B, L, this.nKvHeads, this.headDim]));
+    v = disposing(v, ops.reshape(v, [B, L, this.nKvHeads, this.headDim]));
+    q = disposing(q, this.qNorm.forward(q));
+    k = disposing(k, this.kNorm.forward(k));
+
+    q = disposing(q, ops.transposeAxes(q, [0, 2, 1, 3]));
+    k = disposing(k, ops.transposeAxes(k, [0, 2, 1, 3]));
+    v = disposing(v, ops.transposeAxes(v, [0, 2, 1, 3]));
+
+    q = disposing(q, ops.rope(q, this.headDim, this.ropeBase, cache.offset, null));
+    k = disposing(k, ops.rope(k, this.headDim, this.ropeBase, cache.offset, null));
+
+    const [keys, values] = cache.updateAndFetch(k, v);
+    k.dispose();
+    v.dispose();
+    const attn = ops.sdpa(q, keys, values, this.scale, mask.mode, mask.arr);
+    keys.dispose();
+    values.dispose();
+    q.dispose();
+
+    const attnT = ops.transposeAxes(attn, [0, 2, 1, 3]);
+    attn.dispose();
+    const merged = ops.reshape(attnT, [B, L, -1]);
+    attnT.dispose();
+    const out = this.oProj.forward(merged);
+    merged.dispose();
+    return out;
+  }
+}
+
+class Qwen3MLP {
+  readonly gate: QuantizedLinear;
+  readonly up: QuantizedLinear;
+  readonly down: QuantizedLinear;
+
+  constructor(weights: Weights, config: ModelConfig, prefix: string) {
+    this.gate = QuantizedLinear.load(weights, `${prefix}.gate_proj`, config);
+    this.up = QuantizedLinear.load(weights, `${prefix}.up_proj`, config);
+    this.down = QuantizedLinear.load(weights, `${prefix}.down_proj`, config);
+  }
+
+  forward(x: MlxArray): MlxArray {
+    const gate = this.gate.forward(x);
+    const up = this.up.forward(x);
+    const sig = ops.sigmoid(gate);
+    const silu = ops.mul(gate, sig);
+    gate.dispose();
+    sig.dispose();
+    const hidden = ops.mul(silu, up);
+    silu.dispose();
+    up.dispose();
+    const out = this.down.forward(hidden);
+    hidden.dispose();
+    return out;
+  }
+}
+
+class Qwen3Layer {
+  readonly attn: Qwen3Attention;
+  readonly mlp: Qwen3MLP;
+  readonly inputNorm: RMSNorm;
+  readonly postAttnNorm: RMSNorm;
+
+  constructor(weights: Weights, config: ModelConfig, prefix: string) {
+    this.attn = new Qwen3Attention(weights, config, `${prefix}.self_attn`);
+    this.mlp = new Qwen3MLP(weights, config, `${prefix}.mlp`);
+    this.inputNorm = new RMSNorm(weights.tensor(`${prefix}.input_layernorm.weight`), config.text.rmsNormEps);
+    this.postAttnNorm = new RMSNorm(weights.tensor(`${prefix}.post_attention_layernorm.weight`), config.text.rmsNormEps);
+  }
+
+  forward(x: MlxArray, mask: Mask, cache: Cache): MlxArray {
+    const xn = this.inputNorm.forward(x);
+    const a = this.attn.forward(xn, mask, cache);
+    xn.dispose();
+    const h = ops.add(x, a);
+    a.dispose();
+    const hn = this.postAttnNorm.forward(h);
+    const m = this.mlp.forward(hn);
+    hn.dispose();
+    const out = ops.add(h, m);
+    h.dispose();
+    m.dispose();
+    return out;
+  }
+}
+
+export class Qwen3Model {
+  readonly config: ModelConfig;
+  readonly weightsBytes: number;
+  readonly prefixBase = "model";
+  readonly loraState = new LoraState();
+  readonly embed: QuantizedEmbedding;
+  readonly layers: Qwen3Layer[];
+  readonly finalNorm: RMSNorm;
+  /** Separate lm_head when NOT tied; otherwise the tied embedding's asLinear. */
+  readonly lmHead: QuantizedLinear | null;
+
+  constructor(weights: Weights, config: ModelConfig) {
+    this.config = config;
+    this.weightsBytes = [...weights.shards.files.values()]
+      .reduce((a, f) => a + f.mmap.size, 0);
+    this.embed = QuantizedEmbedding.load(weights, "model.embed_tokens", config);
+    this.layers = Array.from(
+      { length: config.text.numHiddenLayers },
+      (_, i) => new Qwen3Layer(weights, config, `model.layers.${i}`),
+    );
+    this.finalNorm = new RMSNorm(weights.tensor("model.norm.weight"), config.text.rmsNormEps);
+    this.lmHead = config.text.tieWordEmbeddings
+      ? null
+      : QuantizedLinear.load(weights, "lm_head", config);
+  }
+
+  loraTargets(): Map<string, QuantizedLinear> {
+    const out = new Map<string, QuantizedLinear>();
+    for (let i = 0; i < this.layers.length; i++) {
+      const l = this.layers[i]!;
+      const p = `model.layers.${i}`;
+      out.set(`${p}.self_attn.q_proj`, l.attn.qProj);
+      out.set(`${p}.self_attn.k_proj`, l.attn.kProj);
+      out.set(`${p}.self_attn.v_proj`, l.attn.vProj);
+      out.set(`${p}.self_attn.o_proj`, l.attn.oProj);
+      out.set(`${p}.mlp.gate_proj`, l.mlp.gate);
+      out.set(`${p}.mlp.up_proj`, l.mlp.up);
+      out.set(`${p}.mlp.down_proj`, l.mlp.down);
+    }
+    return out;
+  }
+
+  makeCache(): Cache[] {
+    return this.layers.map(() => new KVCache());
+  }
+
+  forwardHidden(ids: MlxArray, cache: Cache[]): MlxArray {
+    const h = this.embed.encode(ids);
+    return this.forwardLayers(h, cache);
+  }
+
+  forwardEmbeddings(_embeds: MlxArray, _cache: Cache[], _bidir: MlxArray | null): MlxArray {
+    throw new Error("qwen3 input-embedding path is not supported");
+  }
+
+  protected forwardLayers(h0: MlxArray, cache: Cache[]): MlxArray {
+    const L = h0.shape[1]!;
+    const mask = cache[0]!.makeMask(L, null);
+    let cur = h0;
+    for (let i = 0; i < this.layers.length; i++) {
+      const next = this.layers[i]!.forward(cur, mask, cache[i]!);
+      cur.dispose();
+      cur = next;
+    }
+    mask.arr?.dispose();
+    return disposing(cur, this.finalNorm.forward(cur));
+  }
+
+  /** Last-token pooled, L2-normalized sentence embedding for one sequence.
+   *  ids [1, L] → vector [1, hidden]. The caller appends the EOS/eod token
+   *  (Qwen3-Embedding's pooling token) to `ids`. */
+  embedPooled(ids: MlxArray): MlxArray {
+    const cache = this.makeCache();
+    try {
+      const h = this.forwardHidden(ids, cache); // [1, L, hidden]
+      const [B, L, H] = h.shape as [number, number, number];
+      const last = h.slice([0, L - 1, 0], [B, L, H]); // [1, 1, hidden]
+      h.dispose();
+      const vec = disposing(last, ops.reshape(last, [B, H])); // [1, hidden]
+      // L2 normalize: x / max(||x||_2, eps)
+      const sq = ops.square(vec);
+      const ss = disposing(sq, ops.sumAxis(sq, -1, true));
+      const norm = disposing(ss, ops.sqrt(ss));
+      const out = ops.div(vec, norm);
+      vec.dispose();
+      norm.dispose();
+      return out;
+    } finally {
+      for (const c of cache) c.dispose();
+    }
+  }
+
+  logitsFromHidden(h: MlxArray): MlxArray {
+    return this.lmHead ? this.lmHead.forward(h) : this.embed.asLinear(h);
+  }
+
+  forward(tokens: number[] | MlxArray, cache: Cache[]): MlxArray {
+    const ids = Array.isArray(tokens)
+      ? ops.fromInt32(tokens, [1, tokens.length])
+      : tokens;
+    const h = this.forwardHidden(ids, cache);
+    if (Array.isArray(tokens)) ids.dispose();
+    const logits = this.logitsFromHidden(h);
+    h.dispose();
+    return logits;
+  }
+
+  generate(promptTokens: number[], maxTokens: number, eosIds: number[] = []): number[] {
+    const cache = this.makeCache();
+    const out: number[] = [];
+    try {
+      let tokens = promptTokens;
+      for (let step = 0; step < maxTokens; step++) {
+        const logits = this.forward(tokens, cache);
+        const next = argmaxLastPosition(logits);
+        logits.dispose();
+        if (eosIds.includes(next)) break;
+        out.push(next);
+        tokens = [next];
+      }
+    } finally {
+      for (const c of cache) c.dispose();
+    }
+    return out;
+  }
+}

package/src/model/qwen3_5.ts

@@ -212,8 +212,17 @@ class Qwen3Attention {
     v = disposing(v, ops.reshape(v, [B, L, this.nKvHeads, this.headDim]));
     v = disposing(v, ops.transposeAxes(v, [0, 2, 1, 3]));
 
-    q = disposing(q, ops.rope(q, this.ropeDims, this.ropeBase, cache.offset, null));
-    k = disposing(k, ops.rope(k, this.ropeDims, this.ropeBase, cache.offset, null));
+    // Batched decode: the scheduler's mask wrapper exposes each row's REAL
+    // position as ropeOffsetArr (rows have different prompt lengths); the
+    // dynamic-offset kernel is the same fast::rope, bit-exact vs the static
+    // form (tests/compile.test.ts). Serial lane: scalar offset, unchanged.
+    const offArr = (cache as { ropeOffsetArr?: MlxArray }).ropeOffsetArr;
+    q = disposing(q, offArr
+      ? ops.ropeDynamic(q, this.ropeDims, this.ropeBase, offArr, null)
+      : ops.rope(q, this.ropeDims, this.ropeBase, cache.offset, null));
+    k = disposing(k, offArr
+      ? ops.ropeDynamic(k, this.ropeDims, this.ropeBase, offArr, null)
+      : ops.rope(k, this.ropeDims, this.ropeBase, cache.offset, null));
 
     let attn: MlxArray;
     if (cache instanceof QuantizedKVCache) {

package/src/model/steel-linear-kernel.ts

@@ -0,0 +1,96 @@
+// Plain quantized linear y = x @ Wᵀ as OUR dispatch, composed from the steel
+// building blocks already in src/train/steel-qmm-header.ts (BlockMMA + Block/
+// QuantizedBlockLoader — MLX's verbatim GEMM, the same code qmm_t_impl wraps).
+// This is the projection primitive for the controlled forward (q/k/v/o/down):
+// we own the dispatch and the eval boundary instead of emitting an ops.* node
+// into MLX's lazy graph. N (out) and H (in/K) are baked as template literals;
+// M comes from the x_shape helper. Output bit-matches the BlockMMA store epilogue
+// (TransformNone → cast to T), the same store qmm_t_impl uses.
+
+import { MlxArray } from "../mlx/array";
+import { MetalKernel } from "../mlx/metal-kernel";
+import { STEEL_QMM_HEADER } from "../train/steel-qmm-header";
+import * as ops from "../mlx/ops";
+import type { QuantSpec } from "../mlx/ops";
+
+const BM = 32, BN = 32, BK = 32, WM = 2, WN = 2;
+const TGN = WM * WN * 32;
+
+// One BM×BN output tile per threadgroup (grid.y = N-tiles, grid.z = M-tiles), the
+// K=H reduction looped inside — the qmm_t_impl body, dims via templateInts.
+const SOURCE = String.raw`
+  const uint M=x_shape[0]; constexpr int N=N_T, H=H_T;
+  constexpr int gs=GS_T, bts=BITS_T;
+  constexpr int pf=get_pack_factor<bts,8>(), bpp=get_bytes_per_pack<bts>();
+  constexpr int BKp=BK_T+16/sizeof(T);
+  threadgroup T Xs[BM_T*BKp];
+  threadgroup T Ws[BN_T*BKp];
+  using mma_t=mlx::steel::BlockMMA<T,T,BM_T,BN_T,BK_T,WM_T,WN_T,false,true,BKp,BKp>;
+  using lx_t=mlx::steel::BlockLoader<T,BM_T,BK_T,BKp,1,WM_T*WN_T*SIMD_SIZE>;
+  using lw_t=QuantizedBlockLoader<T,BN_T,BK_T,BKp,1,WM_T*WN_T*SIMD_SIZE,gs,bts>;
+  const uint sg=simdgroup_index_in_threadgroup, sl=thread_index_in_simdgroup;
+  const int Hh=(int)H, K_w=Hh*bpp/pf, K_g=Hh/gs;
+  const int m0=(int)threadgroup_position_in_grid.z*BM_T;
+  const int n0=(int)threadgroup_position_in_grid.y*BN_T;
+  const short num_els=(short)min(BM_T,(int)M-m0);
+  const short num_outs=(short)min(BN_T,(int)N-n0);
+
+  mma_t mma_op(sg,sl);
+  lx_t  lx(x + (int64_t)m0*Hh, Hh, Xs, sg, sl);
+  lw_t  lw((const device uint8_t*)w + (int64_t)n0*K_w, scales + (int64_t)n0*K_g, biases + (int64_t)n0*K_g, Hh, Ws, sg, sl);
+
+  for (int k=0; k<Hh; k+=BK_T){
+    threadgroup_barrier(mem_flags::mem_threadgroup);
+    if (num_els<BM_T) lx.load_safe(short2(BK_T,num_els)); else lx.load_unsafe();
+    if (num_outs<BN_T) lw.load_safe(short2(BK_T,num_outs)); else lw.load_unsafe();
+    threadgroup_barrier(mem_flags::mem_threadgroup);
+    mma_op.mma(Xs,Ws);
+    lx.next(); lw.next();
+  }
+  threadgroup_barrier(mem_flags::mem_threadgroup);
+  // Store straight to device y[m0.., n0..] via the BlockMMA epilogue (float accum
+  // → T, the SAME rounding MLX's quantized_matmul applies).
+  device T* yp = y + (int64_t)m0*(int64_t)N + n0;
+  if (num_els<BM_T || num_outs<BN_T) mma_op.store_result_safe(yp, N, short2(num_outs,num_els));
+  else mma_op.store_result(yp, N);
+`;
+
+const _kernels = new Map<string, MetalKernel>();
+function getKernel(gs: number, bits: number): MetalKernel {
+  const key = `${gs}:${bits}`;
+  let k = _kernels.get(key);
+  if (!k) {
+    k = new MetalKernel({
+      name: "mlx_bun_steel_linear",
+      inputNames: ["x", "w", "scales", "biases"],
+      outputNames: ["y"],
+      source: SOURCE,
+      header:
+        `${STEEL_QMM_HEADER}\n` +
+        `#define GS_T ${gs}\n#define BITS_T ${bits}\n` +
+        `#define BM_T ${BM}\n#define BN_T ${BN}\n#define BK_T ${BK}\n` +
+        `#define WM_T ${WM}\n#define WN_T ${WN}\n#define TGN_T ${TGN}\n`,
+      ensureRowContiguous: true,
+    });
+    _kernels.set(key, k);
+  }
+  return k;
+}
+
+/** y = x @ Wᵀ, quantized, as our own dispatch. `x` is [M, H] (bf16/f16); `w` is
+ *  the packed weight [N, H*bits/32] with per-group scales/biases [N, H/groupSize].
+ *  Returns [M, N] in x.dtype. H % BK == 0 and groupSize % BK == 0 required. */
+export function steelLinear(
+  x: MlxArray, w: MlxArray, scales: MlxArray, biases: MlxArray, spec: QuantSpec,
+): MlxArray {
+  const M = x.shape[0]!, H = x.shape[1]!, N = w.shape[0]!;
+  const [y] = getKernel(spec.groupSize, spec.bits).apply([x, w, scales, biases], {
+    outputShapeFn: (ins) => [{ shape: [ins[0]!.shape[0]!, N], dtype: x.dtype }],
+    grid: (ins) => [TGN, Math.ceil(N / BN), Math.ceil(ins[0]!.shape[0]! / BM)],
+    threadGroup: [TGN, 1, 1],
+    templateInts: { N_T: N, H_T: H },
+    templateDtypes: { T: x.dtype },
+  });
+  void M;
+  return y!;
+}

package/src/model/support.ts

@@ -1,4 +1,5 @@
 import type { ModelConfig } from "../config";
+import { GENERIC_MODEL_TYPES, genericArgsFor, remapModelType } from "./universal/archs";
 
 export function isMiniCPM5Config(config: ModelConfig): boolean {
   const t = config.text;
@@ -22,6 +23,13 @@ export function isQwen35Config(config: ModelConfig): boolean {
     config.text.fullAttentionInterval > 0;
 }
 
+/** Plain Qwen3 (model_type `qwen3`, Qwen3ForCausalLM) — a standard dense decoder
+ *  with per-head q/k norm and tied embeddings. Used here as the text-embedding
+ *  backbone (mlx-community Qwen3-Embedding-*). Distinct from the qwen3_5 hybrid. */
+export function isQwen3Config(config: ModelConfig): boolean {
+  return config.modelType === "qwen3";
+}
+
 /** Speculative-decoding drafters (e.g. `gemma4_assistant`) are companion
  *  artifacts to a target model — Q-only, centroid-head, no standalone LM
  *  head. They are never servable/selectable on their own (the spec path
@@ -38,17 +46,39 @@ export function isDiffusionGemmaConfig(config: ModelConfig): boolean {
   return config.modelType === "diffusion_gemma";
 }
 
-export function isSupportedModelRecord(modelType: string, repoId = ""): boolean {
-  if (isDrafterModelType(modelType)) return false;
-  if (modelType.startsWith("gemma4")) return true;
-  if (modelType === "diffusion_gemma") return true;
+/** Support tier for a registry record (docs/design/generic-model-support.md):
+ *  "targeted" = dedicated/generated forward + L2/L3 paths;
+ *  "generic"  = the Tier-0 universal module (L1 monolith only);
+ *  null       = unsupported. Generic never shadows targeted. */
+export function supportTier(modelType: string, repoId = ""): "targeted" | "generic" | null {
+  if (isDrafterModelType(modelType)) return null;
+  if (modelType.startsWith("gemma4")) return "targeted";
+  if (modelType === "diffusion_gemma") return "targeted";
   // qwen3_5 / qwen3_5_text (dense hybrid). The MoE variant is a separate type.
-  if (modelType === "qwen3_5" || modelType === "qwen3_5_text") return true;
-  return modelType === "llama" && repoId.toLowerCase().includes("minicpm5-1b-optiq-4bit");
+  if (modelType === "qwen3_5" || modelType === "qwen3_5_text") return "targeted";
+  if (modelType === "qwen3") return "targeted"; // plain Qwen3 (embedding backbone)
+  if (modelType === "llama" && repoId.toLowerCase().includes("minicpm5-1b-optiq-4bit"))
+    return "targeted";
+  // Tier-0 generic fallback: the universal-dense descriptor table.
+  if (GENERIC_MODEL_TYPES.has(remapModelType(modelType))) return "generic";
+  return null;
+}
+
+export function isSupportedModelRecord(modelType: string, repoId = ""): boolean {
+  return supportTier(modelType, repoId) !== null;
 }
 
 export function isSupportedModelConfig(config: ModelConfig): boolean {
   if (isDrafterModelType(config.modelType)) return false;
-  return config.modelType.startsWith("gemma4") || isMiniCPM5Config(config) ||
-    isQwen35Config(config) || isDiffusionGemmaConfig(config);
+  if (
+    config.modelType.startsWith("gemma4") || isMiniCPM5Config(config) ||
+    isQwen35Config(config) || isQwen3Config(config) || isDiffusionGemmaConfig(config)
+  ) return true;
+  // Generic tier: an arch descriptor exists for this model_type (and its
+  // config parses — a malformed config is unsupported, not a crash).
+  try {
+    return genericArgsFor(config) !== null;
+  } catch {
+    return false;
+  }
 }