@mlx-bun/inference 0.0.0-stage → 1.0.0

package/src/artifacts/glm52/container.ts

@@ -0,0 +1,305 @@
+// Header-only reader and validator for Colibri's converted GLM-5.2 artifact.
+//
+// Colibri emits ordinary safetensors shards named out-*, out-mtp-* and
+// optionally out-idx-*. There is no model.safetensors.index.json. Tensor byte
+// geometry is authoritative: converted 2-D tensors are flattened U8 payloads
+// with companion F32 `<name>.qs` scales. Reading only the headers avoids
+// mapping hundreds of GiB merely to validate the artifact.
+
+import { closeSync, fstatSync, openSync, readSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Glm52Config } from "../glm52-config";
+
+export type ColibriShardFamily = "main" | "mtp" | "indexer";
+export type ColibriDtype =
+  | "BOOL" | "U8" | "I8" | "U16" | "I16" | "U32" | "I32" | "U64" | "I64"
+  | "F16" | "BF16" | "F32" | "F64";
+
+const DTYPE_BYTES: Record<ColibriDtype, number> = {
+  BOOL: 1, U8: 1, I8: 1, U16: 2, I16: 2, U32: 4, I32: 4,
+  U64: 8, I64: 8, F16: 2, BF16: 2, F32: 4, F64: 8,
+};
+
+const GROUP_SIZES = [16, 32, 48, 64, 96, 128, 192, 256] as const;
+// Match safetensors' own defensive ceiling: headers are metadata, never model
+// payload. This prevents a corrupt multi-GiB shard from becoming a matching
+// multi-GiB Bun allocation before JSON validation.
+const MAX_SAFETENSORS_HEADER_BYTES = 100_000_000n;
+
+interface HeaderTensor {
+  dtype: ColibriDtype;
+  shape: number[];
+  data_offsets: [number, number];
+}
+
+export interface ColibriTensorInfo {
+  readonly name: string;
+  readonly dtype: ColibriDtype;
+  readonly shape: number[];
+  readonly file: string;
+  readonly family: ColibriShardFamily;
+  readonly begin: number;
+  readonly end: number;
+  readonly absoluteBegin: number;
+  readonly absoluteEnd: number;
+  readonly byteLength: number;
+}
+
+export interface ColibriQuantTensorInfo {
+  readonly name: string;
+  readonly outputRows: number;
+  readonly inputColumns: number;
+  readonly bits: 4 | 8;
+  readonly groupSize: number | null;
+  readonly weight: ColibriTensorInfo;
+  readonly scales: ColibriTensorInfo;
+  readonly coalescedNextWeight: string | null;
+}
+
+export interface Glm52ContainerCapabilities {
+  readonly hasMtp: boolean;
+  readonly hasDsa: boolean;
+  readonly missingMtpTensors: string[];
+  readonly missingDsaTensors: string[];
+}
+
+function product(shape: number[], label: string): number {
+  let value = 1;
+  for (const dim of shape) {
+    if (!Number.isSafeInteger(dim) || dim < 0)
+      throw new Error(`${label}: invalid shape ${JSON.stringify(shape)}`);
+    value *= dim;
+    if (!Number.isSafeInteger(value))
+      throw new Error(`${label}: shape product exceeds safe integer range`);
+  }
+  return value;
+}
+
+function readFully(fd: number, buffer: Uint8Array, position: number, label: string): void {
+  let offset = 0;
+  while (offset < buffer.byteLength) {
+    const got = readSync(fd, buffer, offset, buffer.byteLength - offset, position + offset);
+    if (got === 0)
+      throw new Error(`${label}: short read at ${position + offset}`);
+    offset += got;
+  }
+}
+
+function familyFor(filename: string): ColibriShardFamily | null {
+  if (/^out-mtp-\d+\.safetensors$/.test(filename)) return "mtp";
+  if (/^out-idx-\d+\.safetensors$/.test(filename)) return "indexer";
+  if (/^out-\d+\.safetensors$/.test(filename)) return "main";
+  return null;
+}
+
+function parseHeader(path: string, family: ColibriShardFamily): ColibriTensorInfo[] {
+  const fd = openSync(path, "r");
+  try {
+    const stat = fstatSync(fd);
+    if (stat.size < 8) throw new Error(`${path}: too small for safetensors`);
+    const prefix = Buffer.allocUnsafe(8);
+    readFully(fd, prefix, 0, path);
+    const headerBig = prefix.readBigUInt64LE(0);
+    if (headerBig > MAX_SAFETENSORS_HEADER_BYTES) {
+      throw new Error(
+        `${path}: safetensors header ${headerBig} exceeds ` +
+        `${MAX_SAFETENSORS_HEADER_BYTES} byte limit`,
+      );
+    }
+    if (headerBig > BigInt(Number.MAX_SAFE_INTEGER))
+      throw new Error(`${path}: safetensors header is too large`);
+    const headerLength = Number(headerBig);
+    const dataStart = 8 + headerLength;
+    if (headerLength < 2 || dataStart > stat.size)
+      throw new Error(`${path}: invalid safetensors header length ${headerLength}`);
+    const bytes = Buffer.allocUnsafe(headerLength);
+    readFully(fd, bytes, 8, path);
+    let parsed: Record<string, HeaderTensor | Record<string, string>>;
+    try {
+      parsed = JSON.parse(bytes.toString("utf8"));
+    } catch (error) {
+      throw new Error(`${path}: invalid safetensors JSON: ${String(error)}`);
+    }
+
+    const out: ColibriTensorInfo[] = [];
+    for (const [name, raw] of Object.entries(parsed)) {
+      if (name === "__metadata__") continue;
+      const entry = raw as HeaderTensor;
+      if (!entry || !(entry.dtype in DTYPE_BYTES) || !Array.isArray(entry.shape) ||
+          !Array.isArray(entry.data_offsets) || entry.data_offsets.length !== 2)
+        throw new Error(`${path}: malformed tensor entry ${name}`);
+      const [begin, end] = entry.data_offsets;
+      if (!Number.isSafeInteger(begin) || !Number.isSafeInteger(end) || begin < 0 || end < begin)
+        throw new Error(`${path}: tensor ${name} has invalid offsets ${String(entry.data_offsets)}`);
+      const elements = product(entry.shape, `${path}:${name}`);
+      const expected = elements * DTYPE_BYTES[entry.dtype];
+      if (end - begin !== expected)
+        throw new Error(
+          `${path}: tensor ${name} byte range ${end - begin} != ` +
+          `${JSON.stringify(entry.shape)} × ${entry.dtype}`,
+        );
+      if (dataStart + end > stat.size)
+        throw new Error(`${path}: tensor ${name} extends past end of shard`);
+      out.push({
+        name,
+        dtype: entry.dtype,
+        shape: [...entry.shape],
+        file: path,
+        family,
+        begin,
+        end,
+        absoluteBegin: dataStart + begin,
+        absoluteEnd: dataStart + end,
+        byteLength: end - begin,
+      });
+    }
+    return out;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export class ColibriGlm52Container {
+  readonly tensors = new Map<string, ColibriTensorInfo>();
+  readonly files: ReadonlyArray<{ path: string; family: ColibriShardFamily }>;
+
+  private constructor(files: Array<{ path: string; family: ColibriShardFamily }>) {
+    this.files = files;
+    for (const { path, family } of files) {
+      for (const tensor of parseHeader(path, family)) {
+        const prior = this.tensors.get(tensor.name);
+        if (prior)
+          throw new Error(
+            `duplicate Colibri tensor ${tensor.name} in ${basename(prior.file)} ` +
+            `and ${basename(tensor.file)}`,
+          );
+        this.tensors.set(tensor.name, tensor);
+      }
+    }
+    if (this.tensors.size === 0)
+      throw new Error("Colibri container has no tensors");
+  }
+
+  static open(modelDir: string): ColibriGlm52Container {
+    const files = readdirSync(modelDir)
+      .map((name) => ({ name, family: familyFor(name) }))
+      .filter((entry): entry is { name: string; family: ColibriShardFamily } =>
+        entry.family !== null)
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map(({ name, family }) => ({ path: join(modelDir, name), family }));
+    if (!files.some((entry) => entry.family === "main"))
+      throw new Error(`${modelDir}: no out-NNNNN.safetensors Colibri shards`);
+    return new ColibriGlm52Container(files);
+  }
+
+  has(name: string): boolean {
+    return this.tensors.has(name);
+  }
+
+  info(name: string): ColibriTensorInfo {
+    const info = this.tensors.get(name);
+    if (!info) throw new Error(`Colibri container: missing tensor ${name}`);
+    return info;
+  }
+
+  /** Validate a converted 2-D tensor and infer int4 group geometry from scales. */
+  quantized(name: string, outputRows: number, inputColumns: number): ColibriQuantTensorInfo {
+    if (!Number.isSafeInteger(outputRows) || outputRows <= 0 ||
+        !Number.isSafeInteger(inputColumns) || inputColumns <= 0)
+      throw new Error(`${name}: invalid logical shape [${outputRows},${inputColumns}]`);
+    const weight = this.info(name);
+    const scales = this.info(`${name}.qs`);
+    if (weight.dtype !== "U8")
+      throw new Error(`${name}: converted weight must be U8 (got ${weight.dtype})`);
+    if (scales.dtype !== "F32")
+      throw new Error(`${name}.qs: scales must be F32 (got ${scales.dtype})`);
+
+    const int8Bytes = outputRows * inputColumns;
+    const int4Bytes = outputRows * Math.ceil(inputColumns / 2);
+    let bits: 4 | 8;
+    if (weight.byteLength === int8Bytes) bits = 8;
+    else if (weight.byteLength === int4Bytes) bits = 4;
+    else {
+      throw new Error(
+        `${name}: ${weight.byteLength} bytes do not encode logical ` +
+        `[${outputRows},${inputColumns}] as int8 (${int8Bytes}) or int4 (${int4Bytes})`,
+      );
+    }
+
+    const scaleCount = scales.byteLength / 4;
+    let groupSize: number | null = null;
+    if (scaleCount !== outputRows) {
+      if (bits !== 4)
+        throw new Error(`${name}.qs: grouped scales are only valid for int4`);
+      groupSize = GROUP_SIZES.find(
+        (candidate) => scaleCount === outputRows * Math.ceil(inputColumns / candidate),
+      ) ?? null;
+      if (groupSize === null)
+        throw new Error(
+          `${name}.qs: ${scaleCount} scales do not match per-row or a supported ` +
+          `group size for [${outputRows},${inputColumns}]`,
+        );
+    }
+
+    let coalescedNextWeight: string | null = null;
+    for (const other of this.tensors.values()) {
+      if (other.dtype === "U8" && other.file === weight.file &&
+          other.absoluteBegin === weight.absoluteEnd) {
+        coalescedNextWeight = other.name;
+        break;
+      }
+    }
+    return {
+      name,
+      outputRows,
+      inputColumns,
+      bits,
+      groupSize,
+      weight,
+      scales,
+      coalescedNextWeight,
+    };
+  }
+
+  capabilities(config: Glm52Config): Glm52ContainerCapabilities {
+    const mtpLayer = config.numHiddenLayers;
+    const mtpPrefix = `model.layers.${mtpLayer}`;
+    // G4 validates the full MTP family before enabling drafting. G2 records the
+    // architectural sentinels so a partial sidecar cannot masquerade as MTP.
+    const mtpRequired = config.numNextnPredictLayers > 0 ? [
+      `${mtpPrefix}.eh_proj.weight`,
+      `${mtpPrefix}.enorm.weight`,
+      `${mtpPrefix}.hnorm.weight`,
+      `${mtpPrefix}.shared_head.norm.weight`,
+      `${mtpPrefix}.input_layernorm.weight`,
+      `${mtpPrefix}.post_attention_layernorm.weight`,
+      `${mtpPrefix}.self_attn.q_a_proj.weight`,
+      `${mtpPrefix}.self_attn.kv_a_proj_with_mqa.weight`,
+      `${mtpPrefix}.mlp.gate.weight`,
+      `${mtpPrefix}.mlp.gate.e_score_correction_bias`,
+    ] : [];
+    const missingMtpTensors = mtpRequired.filter((name) => !this.has(name));
+
+    const dsaRequired: string[] = [];
+    if (config.indexTopk > 0) {
+      for (let layer = 0; layer < config.numHiddenLayers; layer++) {
+        if (config.indexerTypes[layer] !== "full") continue;
+        const prefix = `model.layers.${layer}.self_attn.indexer`;
+        dsaRequired.push(
+          `${prefix}.wq_b.weight`,
+          `${prefix}.wk.weight`,
+          `${prefix}.weights_proj.weight`,
+          `${prefix}.k_norm.weight`,
+          `${prefix}.k_norm.bias`,
+        );
+      }
+    }
+    const missingDsaTensors = dsaRequired.filter((name) => !this.has(name));
+    return {
+      hasMtp: mtpRequired.length > 0 && missingMtpTensors.length === 0,
+      hasDsa: dsaRequired.length > 0 && missingDsaTensors.length === 0,
+      missingMtpTensors,
+      missingDsaTensors,
+    };
+  }
+}

package/src/artifacts/glm52/expert-layout.ts

@@ -0,0 +1,249 @@
+import type {
+  ColibriGlm52Container,
+  ColibriQuantTensorInfo,
+  ColibriTensorInfo,
+} from "./container";
+import type { Glm52Config } from "../glm52-config";
+import { positiveInteger } from "../../runtime/integers";
+
+import { GLM52_EXPERT_SLOT_ALIGNMENT } from "../../kernels/glm52/layout";
+export { GLM52_EXPERT_SLOT_ALIGNMENT };
+export const GLM52_EXPERT_MAX_READ_SEGMENTS = 8;
+
+export type Glm52ExpertProjection = "down" | "gate" | "up";
+
+export interface Glm52ExpertProjectionLayout {
+  readonly projection: Glm52ExpertProjection;
+  readonly tensor: ColibriQuantTensorInfo;
+  readonly weightOffset: number;
+  readonly scaleOffset: number;
+}
+
+export interface Glm52ExpertReadSegment {
+  readonly file: string;
+  readonly sourceOffset: number;
+  readonly destinationOffset: number;
+  readonly length: number;
+}
+
+export interface Glm52ExpertSlotLayout {
+  readonly layer: number;
+  readonly expertId: number;
+  readonly bits: 4 | 8;
+  readonly groupSize: number | null;
+  readonly alignment: number;
+  readonly weightBytes: number;
+  readonly scaleBytes: number;
+  readonly scaleOffset: number;
+  readonly payloadBytes: number;
+  readonly slotBytes: number;
+  readonly projections: Readonly<Record<
+    Glm52ExpertProjection,
+    Glm52ExpertProjectionLayout
+  >>;
+  /**
+   * Positioned reads in canonical slot order. Adjacent tensor reads are
+   * coalesced only when both their source and destination ranges are adjacent
+   * in the same shard.
+   */
+  readonly segments: readonly Glm52ExpertReadSegment[];
+}
+
+type ExpertGeometry = Pick<
+  Glm52Config,
+  "hiddenSize" | "moeIntermediateSize" | "numRoutedExperts"
+>;
+
+interface PrimitiveRead {
+  readonly tensor: ColibriTensorInfo;
+  readonly destinationOffset: number;
+}
+
+function alignUp(value: number, alignment: number): number {
+  const result = Math.ceil(value / alignment) * alignment;
+  if (!Number.isSafeInteger(result))
+    throw new Error("expert slot size exceeds the safe integer range");
+  return result;
+}
+
+function coalesceReads(
+  reads: readonly PrimitiveRead[],
+): Glm52ExpertReadSegment[] {
+  const segments: Glm52ExpertReadSegment[] = [];
+  for (const read of reads) {
+    const next: Glm52ExpertReadSegment = {
+      file: read.tensor.file,
+      sourceOffset: read.tensor.absoluteBegin,
+      destinationOffset: read.destinationOffset,
+      length: read.tensor.byteLength,
+    };
+    const prior = segments.at(-1);
+    if (
+      prior &&
+      prior.file === next.file &&
+      prior.sourceOffset + prior.length === next.sourceOffset &&
+      prior.destinationOffset + prior.length === next.destinationOffset
+    ) {
+      segments[segments.length - 1] = {
+        ...prior,
+        length: prior.length + next.length,
+      };
+    } else {
+      segments.push(next);
+    }
+  }
+  return segments;
+}
+
+/**
+ * Describe one routed expert as a fixed aligned native slot without opening or
+ * mapping any tensor payload.
+ *
+ * The slot order is deliberately independent of safetensors header order:
+ * down/gate/up packed weights followed by down/gate/up F32 scales. Every
+ * pointer-addressed component begins at a 16 KiB boundary: MLX/Metal cannot
+ * safely no-copy-wrap a merely sub-page-aligned host pointer. Source-adjacent
+ * components still coalesce when the required padding is zero.
+ */
+export function buildGlm52ExpertSlotLayout(
+  container: ColibriGlm52Container,
+  config: ExpertGeometry,
+  layer: number,
+  expertId: number,
+  alignment = GLM52_EXPERT_SLOT_ALIGNMENT,
+): Glm52ExpertSlotLayout {
+  positiveInteger(config.hiddenSize, "hidden size");
+  positiveInteger(config.moeIntermediateSize, "MoE intermediate size");
+  positiveInteger(config.numRoutedExperts, "routed expert count");
+  if (!Number.isSafeInteger(layer) || layer < 0)
+    throw new Error("expert layer must be a non-negative safe integer");
+  if (
+    !Number.isSafeInteger(expertId) ||
+    expertId < 0 ||
+    expertId >= config.numRoutedExperts
+  ) {
+    throw new Error(
+      `expert ID ${expertId} is outside [0,${config.numRoutedExperts})`,
+    );
+  }
+  if (
+    !Number.isSafeInteger(alignment) ||
+    alignment < 1 ||
+    (alignment & (alignment - 1)) !== 0
+  ) {
+    throw new Error("expert slot alignment must be a positive power of two");
+  }
+
+  const prefix = `model.layers.${layer}.mlp.experts.${expertId}`;
+  const dimensions: Record<
+    Glm52ExpertProjection,
+    readonly [outputRows: number, inputColumns: number]
+  > = {
+    down: [config.hiddenSize, config.moeIntermediateSize],
+    gate: [config.moeIntermediateSize, config.hiddenSize],
+    up: [config.moeIntermediateSize, config.hiddenSize],
+  };
+  const suffix: Record<Glm52ExpertProjection, string> = {
+    down: "down_proj",
+    gate: "gate_proj",
+    up: "up_proj",
+  };
+  const order: readonly Glm52ExpertProjection[] = ["down", "gate", "up"];
+
+  const tensors = {} as Record<
+    Glm52ExpertProjection,
+    ColibriQuantTensorInfo
+  >;
+  for (const projection of order) {
+    const [outputRows, inputColumns] = dimensions[projection];
+    tensors[projection] = container.quantized(
+      `${prefix}.${suffix[projection]}.weight`,
+      outputRows,
+      inputColumns,
+    );
+  }
+
+  const bits = tensors.down.bits;
+  const groupSize = tensors.down.groupSize;
+  for (const projection of order) {
+    const tensor = tensors[projection];
+    if (tensor.bits !== bits || tensor.groupSize !== groupSize) {
+      throw new Error(
+        `${prefix}: routed expert projections must use one quantization layout`,
+      );
+    }
+  }
+
+  let weightBytes = 0;
+  let cursor = 0;
+  const weightOffsets = {} as Record<Glm52ExpertProjection, number>;
+  for (const projection of order) {
+    cursor = alignUp(cursor, alignment);
+    weightOffsets[projection] = cursor;
+    weightBytes += tensors[projection].weight.byteLength;
+    cursor += tensors[projection].weight.byteLength;
+  }
+  if (!Number.isSafeInteger(weightBytes))
+    throw new Error(`${prefix}: expert weight bytes exceed the safe integer range`);
+
+  const scaleOffset = alignUp(cursor, alignment);
+  cursor = scaleOffset;
+  let scaleBytes = 0;
+  const scaleOffsets = {} as Record<Glm52ExpertProjection, number>;
+  for (const projection of order) {
+    cursor = alignUp(cursor, alignment);
+    scaleOffsets[projection] = cursor;
+    scaleBytes += tensors[projection].scales.byteLength;
+    cursor += tensors[projection].scales.byteLength;
+  }
+  const payloadBytes = cursor;
+  if (!Number.isSafeInteger(payloadBytes))
+    throw new Error(`${prefix}: expert payload bytes exceed the safe integer range`);
+  const slotBytes = alignUp(payloadBytes, alignment);
+
+  const primitiveReads: PrimitiveRead[] = [
+    ...order.map((projection) => ({
+      tensor: tensors[projection].weight,
+      destinationOffset: weightOffsets[projection],
+    })),
+    ...order.map((projection) => ({
+      tensor: tensors[projection].scales,
+      destinationOffset: scaleOffsets[projection],
+    })),
+  ];
+  const segments = coalesceReads(primitiveReads);
+  if (segments.length > GLM52_EXPERT_MAX_READ_SEGMENTS) {
+    throw new Error(
+      `${prefix}: expert requires ${segments.length} read segments; maximum is ` +
+      `${GLM52_EXPERT_MAX_READ_SEGMENTS}`,
+    );
+  }
+
+  const projections = {} as Record<
+    Glm52ExpertProjection,
+    Glm52ExpertProjectionLayout
+  >;
+  for (const projection of order) {
+    projections[projection] = {
+      projection,
+      tensor: tensors[projection],
+      weightOffset: weightOffsets[projection],
+      scaleOffset: scaleOffsets[projection],
+    };
+  }
+
+  return {
+    layer,
+    expertId,
+    bits,
+    groupSize,
+    alignment,
+    weightBytes,
+    scaleBytes,
+    scaleOffset,
+    payloadBytes,
+    slotBytes,
+    projections,
+    segments,
+  };
+}

package/src/artifacts/glm52/index.ts

@@ -0,0 +1,7 @@
+export * from "./container";
+export * from "./weights";
+export * from "./resident-weights";
+export * from "./expert-layout";
+export * from "./layout";
+export * from "./kernel-layout";
+export * from "./memory";

package/src/artifacts/glm52/kernel-layout.ts

@@ -0,0 +1,124 @@
+import { positiveInteger } from "../../runtime/integers";
+import { validateRange, type Glm52CanonicalMetalLayout, type Glm52CanonicalQ4MetalLayout, type Glm52CanonicalQ8MetalLayout } from "../../kernels/glm52/layout";
+import { type Glm52ExpertSlotLayout } from "./expert-layout";
+
+/** What differs between the canonical Q4 and Q8 slot layouts: the slot's bit
+ *  width, the `Glm52ExpertSlotLayout` rejections' wording, and the element
+ *  packing (Q4 packs two weights per byte in uint32 words and checks weight
+ *  alignment; Q8 stores one signed int8 per weight). */
+interface CanonicalSlotSpec {
+  readonly bits: 4 | 8;
+  readonly label: "Q4" | "Q8";
+  readonly bitsError: string;
+  readonly perRowError: string;
+  readonly weightsPerByte: 1 | 2;
+  readonly weightsMustBeWordAligned: boolean;
+}
+
+function resolveCanonicalMetalLayout(
+  layout: Glm52ExpertSlotLayout,
+  spec: CanonicalSlotSpec,
+): Glm52CanonicalMetalLayout {
+  if (layout.bits !== spec.bits) throw new Error(spec.bitsError);
+  if (layout.groupSize !== null) throw new Error(spec.perRowError);
+
+  const down = layout.projections.down;
+  const gate = layout.projections.gate;
+  const up = layout.projections.up;
+  const hiddenSize = positiveInteger(down.tensor.outputRows, "hidden size");
+  const intermediateSize = positiveInteger(
+    down.tensor.inputColumns,
+    "intermediate size",
+  );
+  const expected = [
+    [gate.tensor.outputRows, intermediateSize, "gate output rows"],
+    [gate.tensor.inputColumns, hiddenSize, "gate input columns"],
+    [up.tensor.outputRows, intermediateSize, "up output rows"],
+    [up.tensor.inputColumns, hiddenSize, "up input columns"],
+  ] as const;
+  for (const [actual, wanted, label] of expected) {
+    if (actual !== wanted)
+      throw new Error(`${label} must be ${wanted}, got ${actual}`);
+  }
+
+  const slotBytes = positiveInteger(layout.slotBytes, "expert slot bytes");
+  for (const [projection, outputRows, inputColumns] of [
+    [down, hiddenSize, intermediateSize],
+    [gate, intermediateSize, hiddenSize],
+    [up, intermediateSize, hiddenSize],
+  ] as const) {
+    const weightBytes = outputRows * inputColumns / spec.weightsPerByte;
+    const scaleBytes = outputRows * 4;
+    if (projection.tensor.weight.byteLength !== weightBytes) {
+      throw new Error(
+        `${projection.projection} ${spec.label} weight bytes must be ${weightBytes}`,
+      );
+    }
+    if (projection.tensor.scales.byteLength !== scaleBytes) {
+      throw new Error(
+        `${projection.projection} ${spec.label} scale bytes must be ${scaleBytes}`,
+      );
+    }
+    validateRange(
+      projection.weightOffset,
+      weightBytes,
+      slotBytes,
+      `${projection.projection} weights`,
+    );
+    validateRange(
+      projection.scaleOffset,
+      scaleBytes,
+      slotBytes,
+      `${projection.projection} scales`,
+    );
+    if (spec.weightsMustBeWordAligned && (projection.weightOffset & 3) !== 0)
+      throw new Error(`${projection.projection} weights must be uint32-aligned`);
+    if ((projection.scaleOffset & 3) !== 0)
+      throw new Error(`${projection.projection} scales must be F32-aligned`);
+  }
+
+  return {
+    hiddenSize,
+    intermediateSize,
+    slotBytes,
+    downWeightOffset: down.weightOffset,
+    gateWeightOffset: gate.weightOffset,
+    upWeightOffset: up.weightOffset,
+    downScaleOffset: down.scaleOffset,
+    gateScaleOffset: gate.scaleOffset,
+    upScaleOffset: up.scaleOffset,
+  };
+}
+
+/**
+ * Resolve and validate a production-compatible Q4 descriptor from the
+ * artifact-driven slot catalog. Colibri's main routed experts use one F32
+ * scale per output row (`groupSize === null`) and affine zero-point 8.
+ */
+export function glm52CanonicalQ4MetalLayout(
+  layout: Glm52ExpertSlotLayout,
+): Glm52CanonicalQ4MetalLayout {
+  return resolveCanonicalMetalLayout(layout, {
+    bits: 4,
+    label: "Q4",
+    bitsError: "GLM Metal streamed experts require a Q4 slot",
+    perRowError: "GLM Metal streamed experts currently require per-row Q4 scales",
+    weightsPerByte: 2,
+    weightsMustBeWordAligned: true,
+  });
+}
+
+/** Resolve the signed two's-complement, per-output-row int8 layout used by
+ * GLM-5.2's native MTP routed experts. */
+export function glm52CanonicalQ8MetalLayout(
+  layout: Glm52ExpertSlotLayout,
+): Glm52CanonicalQ8MetalLayout {
+  return resolveCanonicalMetalLayout(layout, {
+    bits: 8,
+    label: "Q8",
+    bitsError: "GLM MTP Metal streamed experts require a Q8 slot",
+    perRowError: "GLM MTP Metal streamed experts require per-row Q8 scales",
+    weightsPerByte: 1,
+    weightsMustBeWordAligned: false,
+  });
+}