@seanhogg/builderforce-memory-engine 2026.6.31 → 2026.6.35

package/src/export/protobuf.ts

@@ -0,0 +1,86 @@
+/**
+ * export/protobuf.ts — a minimal, dependency-free protobuf (proto3) wire writer.
+ *
+ * Just enough of the encoding to emit an ONNX `ModelProto` (see {@link ./onnx}):
+ * varint, fixed32 (for float tensors), and length-delimited (string / bytes /
+ * nested message) fields. Keeping it tiny and self-contained preserves the
+ * engine's zero-runtime-dependency guarantee — no `protobufjs`, no `onnx` proto.
+ *
+ * Only non-negative integers are emitted (all ONNX ids here are ≥ 0), so the
+ * varint path uses plain division and stays correct up to 2^53.
+ */
+
+const WIRE_VARINT = 0;
+const WIRE_FIXED32 = 5;
+const WIRE_LEN = 2;
+
+/** Accumulates protobuf-encoded bytes for one message. */
+export class ProtoWriter {
+  private readonly parts: number[] = [];
+
+  private byte(b: number): void {
+    this.parts.push(b & 0xff);
+  }
+
+  private rawVarint(value: number): void {
+    if (value < 0 || !Number.isFinite(value)) throw new Error(`ProtoWriter: bad varint ${value}`);
+    let v = value;
+    while (v >= 0x80) {
+      this.byte((v % 0x80) | 0x80);
+      v = Math.floor(v / 0x80);
+    }
+    this.byte(v);
+  }
+
+  private tag(field: number, wire: number): void {
+    this.rawVarint(field * 8 + wire);
+  }
+
+  private rawBytes(bytes: Uint8Array): void {
+    for (let i = 0; i < bytes.length; i++) this.byte(bytes[i]!);
+  }
+
+  /** A varint field (int32 / int64 / bool / enum). */
+  varint(field: number, value: number): void {
+    this.tag(field, WIRE_VARINT);
+    this.rawVarint(value);
+  }
+
+  /** A 32-bit IEEE-754 float field (wire type fixed32, little-endian). */
+  float(field: number, value: number): void {
+    this.tag(field, WIRE_FIXED32);
+    const buf = new ArrayBuffer(4);
+    new DataView(buf).setFloat32(0, value, true);
+    this.rawBytes(new Uint8Array(buf));
+  }
+
+  /** A length-delimited raw-bytes field. */
+  bytes(field: number, data: Uint8Array): void {
+    this.tag(field, WIRE_LEN);
+    this.rawVarint(data.length);
+    this.rawBytes(data);
+  }
+
+  /** A length-delimited UTF-8 string field. */
+  string(field: number, value: string): void {
+    this.bytes(field, new TextEncoder().encode(value));
+  }
+
+  /** A nested-message field (the sub-message encoded as length-delimited bytes). */
+  message(field: number, sub: ProtoWriter): void {
+    this.bytes(field, sub.finish());
+  }
+
+  /** The encoded bytes of this message. */
+  finish(): Uint8Array {
+    return Uint8Array.from(this.parts);
+  }
+}
+
+/** Pack a Float32Array into little-endian raw bytes (for TensorProto.raw_data). */
+export function float32ToBytes(data: Float32Array): Uint8Array {
+  const out = new Uint8Array(data.length * 4);
+  const dv = new DataView(out.buffer);
+  for (let i = 0; i < data.length; i++) dv.setFloat32(i * 4, data[i]!, true);
+  return out;
+}

package/src/export/safetensors.ts

@@ -0,0 +1,77 @@
+/**
+ * export/safetensors.ts — export weights to the HF-native `.safetensors` format.
+ *
+ * Layout (the safetensors spec): an 8-byte little-endian u64 header length, then a
+ * JSON header mapping each tensor name → {dtype, shape, data_offsets:[start,end]}
+ * (offsets relative to the start of the byte buffer that follows the header), then
+ * the concatenated raw tensor bytes. Round-trips losslessly in F32; F16 halves the
+ * size. Loadable by `safetensors`, `transformers`, and transformers.js.
+ */
+
+import type { EvermindLM } from "../lm/evermind_lm.js";
+import { namedTensors, type NamedTensor } from "./tensors.js";
+import { floatToFp16 } from "../utils/quantization.js";
+
+export interface SafetensorsOptions {
+  /** Store tensors as float16 (half the size). Default false (float32). */
+  fp16?: boolean;
+  /** Extra `__metadata__` string entries (e.g. format provenance). */
+  metadata?: Record<string, string>;
+}
+
+function tensorBytes(data: Float32Array, fp16: boolean): Uint8Array {
+  if (!fp16) {
+    const out = new Uint8Array(data.length * 4);
+    const dv = new DataView(out.buffer);
+    for (let i = 0; i < data.length; i++) dv.setFloat32(i * 4, data[i]!, true);
+    return out;
+  }
+  const out = new Uint8Array(data.length * 2);
+  const dv = new DataView(out.buffer);
+  for (let i = 0; i < data.length; i++) dv.setUint16(i * 2, floatToFp16(data[i]!), true);
+  return out;
+}
+
+/** Serialise the given named tensors to a `.safetensors` byte buffer. */
+export function tensorsToSafetensors(tensors: NamedTensor[], opts: SafetensorsOptions = {}): Uint8Array {
+  const fp16 = opts.fp16 ?? false;
+  const dtype = fp16 ? "F16" : "F32";
+  const bytesPer = fp16 ? 2 : 4;
+
+  const header: Record<string, unknown> = {};
+  if (opts.metadata) header.__metadata__ = opts.metadata;
+
+  const chunks: Uint8Array[] = [];
+  let offset = 0;
+  for (const t of tensors) {
+    const nbytes = t.data.length * bytesPer;
+    header[t.name] = { dtype, shape: t.shape, data_offsets: [offset, offset + nbytes] };
+    chunks.push(tensorBytes(t.data, fp16));
+    offset += nbytes;
+  }
+
+  let headerJson = JSON.stringify(header);
+  // safetensors requires the header be padded to an 8-byte boundary (with spaces).
+  const headerBytesRaw = new TextEncoder().encode(headerJson);
+  const pad = (8 - (headerBytesRaw.length % 8)) % 8;
+  if (pad > 0) headerJson += " ".repeat(pad);
+  const headerBytes = new TextEncoder().encode(headerJson);
+
+  const out = new Uint8Array(8 + headerBytes.length + offset);
+  new DataView(out.buffer).setBigUint64(0, BigInt(headerBytes.length), true);
+  out.set(headerBytes, 8);
+  let p = 8 + headerBytes.length;
+  for (const c of chunks) {
+    out.set(c, p);
+    p += c.length;
+  }
+  return out;
+}
+
+/** Export a trained LM's weights to `.safetensors`. */
+export function exportSafetensors(lm: EvermindLM, opts: SafetensorsOptions = {}): Uint8Array {
+  return tensorsToSafetensors(namedTensors(lm), {
+    ...opts,
+    metadata: { format: "pt", producer: "builderforce-memory-engine", ...(opts.metadata ?? {}) },
+  });
+}

package/src/export/tensors.ts

@@ -0,0 +1,107 @@
+/**
+ * export/tensors.ts — the canonical named-tensor view of an EvermindLM.
+ *
+ * Every export format (safetensors / ONNX / GGUF / HF) consumes the SAME named,
+ * shaped tensor list — defined ONCE here so the formats never disagree about a
+ * weight's name, shape, or order. The runtime is left untouched: we read the
+ * model purely through its public {@link EvermindLM.config} and
+ * {@link EvermindLM.parameters} (the AdamW-ordered flat buffers), and re-attach
+ * the names/shapes that order implies.
+ *
+ * Parameter order (must mirror EvermindLM.parameters / SharedExpertMoE.parameters):
+ *   emb,
+ *   per layer l: conv[l], normConv[l], normMoe[l],
+ *                moe: router, shared.{w1,b1,w2,b2}, expert{e}.{w1,b1,w2,b2}…
+ */
+
+import type { EvermindLM } from "../lm/evermind_lm.js";
+
+/** A named, shaped weight tensor (row-major, flat f32). */
+export interface NamedTensor {
+  name: string;
+  /** Row-major dimensions, e.g. [vocab, dModel]. */
+  shape: number[];
+  data: Float32Array;
+}
+
+/** The flat numeric architecture an export needs (a superset of the LM config). */
+export interface EvermindArch {
+  vocabSize: number;
+  dModel: number;
+  numLayers: number;
+  convKernel: number;
+  hiddenDim: number;
+  numExperts: number;
+  topK: number;
+}
+
+/** Pull the architecture out of a live LM (or any config-shaped object). */
+export function archOf(lm: EvermindLM): EvermindArch {
+  const c = lm.config;
+  return {
+    vocabSize: c.vocabSize,
+    dModel: c.dModel,
+    numLayers: c.numLayers,
+    convKernel: c.convKernel,
+    hiddenDim: c.hiddenDim,
+    numExperts: c.numExperts,
+    topK: c.topK,
+  };
+}
+
+/** A weight name + its expected shape, in canonical parameter order. */
+export interface TensorSpec {
+  name: string;
+  shape: number[];
+}
+
+/** The name+shape of every parameter, in EvermindLM.parameters() order. */
+export function evermindTensorSpec(a: EvermindArch): TensorSpec[] {
+  const { vocabSize: V, dModel: D, numLayers: L, convKernel: K, hiddenDim: H, numExperts: E } = a;
+  const specs: TensorSpec[] = [{ name: "token_embedding.weight", shape: [V, D] }];
+  const ffn = (prefix: string): TensorSpec[] => [
+    { name: `${prefix}.w1`, shape: [H, D] },
+    { name: `${prefix}.b1`, shape: [H] },
+    { name: `${prefix}.w2`, shape: [D, H] },
+    { name: `${prefix}.b2`, shape: [D] },
+  ];
+  for (let l = 0; l < L; l++) {
+    const p = `layers.${l}`;
+    specs.push({ name: `${p}.conv.weight`, shape: [D, K] });
+    specs.push({ name: `${p}.norm_conv.weight`, shape: [D] });
+    specs.push({ name: `${p}.norm_moe.weight`, shape: [D] });
+    specs.push({ name: `${p}.moe.router.weight`, shape: [E, D] });
+    specs.push(...ffn(`${p}.moe.shared`));
+    for (let e = 0; e < E; e++) specs.push(...ffn(`${p}.moe.experts.${e}`));
+  }
+  return specs;
+}
+
+/**
+ * The full named/shaped tensor list of a trained LM, zipping the deterministic
+ * {@link evermindTensorSpec} against the live {@link EvermindLM.parameters}. The
+ * data buffers are the model's own (no copy) — treat them as read-only.
+ */
+export function namedTensors(lm: EvermindLM): NamedTensor[] {
+  const specs = evermindTensorSpec(archOf(lm));
+  const params = lm.parameters();
+  if (specs.length !== params.length) {
+    throw new Error(
+      `export/tensors: parameter-count drift (spec ${specs.length} vs model ${params.length}) — ` +
+        `EvermindLM.parameters() order changed; update evermindTensorSpec`,
+    );
+  }
+  return specs.map((s, i) => {
+    const numel = s.shape.reduce((n, d) => n * d, 1);
+    const data = params[i]!.data;
+    if (data.length !== numel) {
+      throw new Error(`export/tensors: shape mismatch for ${s.name} (expected ${numel}, got ${data.length})`);
+    }
+    return { name: s.name, shape: s.shape, data };
+  });
+}
+
+/** Total trainable scalar parameters (for sizing / model-card display). */
+export function paramCount(lm: EvermindLM): number {
+  return lm.parameters().reduce((n, p) => n + p.data.length, 0);
+}

package/src/index.ts

@@ -61,6 +61,75 @@ export {
 
 export { BPETokenizer } from './tokenizer/bpe.js';
 
+// ── Model export (the publishing step: ONNX / safetensors / GGUF / HF repo) ─────
+
+export {
+    exportEvermind,
+    EXPORT_FORMATS,
+    exportSafetensors,
+    tensorsToSafetensors,
+    exportOnnx,
+    exportGguf,
+    configJson,
+    generationConfigJson,
+    tokenizerJson,
+    modelCardMarkdown,
+    namedTensors,
+    evermindTensorSpec,
+    archOf,
+    paramCount,
+} from './export/index.js';
+export type {
+    ExportFormat,
+    ExportFile,
+    ExportResult,
+    ExportOptions,
+    HfMeta,
+    NamedTensor,
+    EvermindArch,
+    TensorSpec,
+} from './export/index.js';
+
+// ── Benchmarking (held-out perplexity / accuracy / throughput + A/B) ──────────
+
+export {
+    benchmarkModel,
+    benchmarkModelAsync,
+    benchmarkText,
+    compareModels,
+    compareReports,
+    corpusToSequences,
+    trainAndBenchmark,
+    argmax as benchArgmax,
+    topKIndices,
+    perplexity,
+    bitsPerToken,
+    LN2,
+} from './bench/index.js';
+export type {
+    LogitsModel,
+    AsyncLogitsModel,
+    BenchmarkOptions,
+    BenchmarkReport,
+    ComparisonReport,
+    TrainAndBenchmarkOptions,
+    TrainAndBenchmarkResult,
+} from './bench/index.js';
+
+// ── Checkpoint integrity (CRC-32 + trailer) ───────────────────────────────────
+
+export { crc32, appendCrcTrailer, verifyCrcTrailer, CRC_TRAILER_MAGIC } from './utils/crc32.js';
+export type { CrcCheck } from './utils/crc32.js';
+export {
+    computeRowDelta,
+    applyRowDelta,
+    serializeRowDelta,
+    deserializeRowDelta,
+    diffCheckpoints,
+    applyCheckpointDiff,
+} from './utils/delta.js';
+export type { RowDelta } from './utils/delta.js';
+
 // ── Seeded RNG (reproducible weight init) ─────────────────────────────────────
 
 export { SeededRng, setInitSeed, randn, gaussianArray } from './utils/rng.js';
@@ -94,6 +163,7 @@ export {
     readBuffer,
     uploadBuffer,
     cdiv,
+    BufferPool,
 } from './utils/gpu_utils.js';
 
 // ── Quantization ──────────────────────────────────────────────────────────────

package/src/kernels/selective_scan.ts

@@ -48,9 +48,11 @@ var<workgroup> wg_bu : array<f32, 256>;   // B*u values
 
 // ---- Helpers ----
 
-// Softplus: numerically stable log(1 + exp(x))
+// Softplus: numerically stable softplus(x) = log(1 + exp(x))
 fn softplus(x: f32) -> f32 {
-    return log(1.0 + exp(x));
+    // Numerically stable: max(x,0) + log1p(exp(-|x|)). The naive log(1+exp(x))
+    // overflows to +Inf for x ≳ 88 (f32 exp range); this form never does. (EVM-8)
+    return max(x, 0.0) + log(1.0 + exp(-abs(x)));
 }
 
 // ZerO-Order Hold discretisation of continuous A, Δ:
@@ -251,7 +253,9 @@ struct ScanParams {
 @group(0) @binding(12) var<storage, read_write> du       : array<f32>;
 
 fn softplus(x: f32) -> f32 {
-    return log(1.0 + exp(x));
+    // Numerically stable: max(x,0) + log1p(exp(-|x|)). The naive log(1+exp(x))
+    // overflows to +Inf for x ≳ 88 (f32 exp range); this form never does. (EVM-8)
+    return max(x, 0.0) + log(1.0 + exp(-abs(x)));
 }
 
 fn softplus_grad(x: f32) -> f32 {

package/src/lm/evermind_lm.ts

@@ -26,6 +26,8 @@ import { crossEntropyLoss, crossEntropyGrad } from "../training/autograd.js";
 import { AdamW, type AdamWOptions } from "../optim/adamw.js";
 import { SeededRng } from "../utils/rng.js";
 import { quantizeFp16, dequantizeFp16 } from "../utils/quantization.js";
+import { appendCrcTrailer, verifyCrcTrailer } from "../utils/crc32.js";
+import { computeRowDelta, applyRowDelta, serializeRowDelta, deserializeRowDelta } from "../utils/delta.js";
 
 export interface EvermindLMConfig {
   /** Vocabulary size (the only required field; everything else has a default). */
@@ -434,11 +436,22 @@ export class EvermindLM {
     }
     if (fp16) new Uint16Array(buf, headerBytes, total).set(quantizeFp16(flat));
     else new Float32Array(buf, headerBytes, total).set(flat);
-    return buf;
+    // Append a CRC-32 trailer so a corrupt/truncated checkpoint is caught on load
+    // (backward-compatible: pre-CRC readers ignore the trailing bytes). (EVM-7)
+    return appendCrcTrailer(buf);
   }
 
-  /** Load weights from an "EVL0" binary. Validates magic + dims. */
+  /** Load weights from an "EVL0" binary. Validates CRC (when present), magic + dims. */
   loadWeights(buffer: ArrayBuffer): void {
+    this._setFlat(this._readFlat(buffer));
+  }
+
+  /** Parse + validate an EVL0 checkpoint to a flat f32 param vector (no mutation). */
+  private _readFlat(buffer: ArrayBuffer): Float32Array {
+    const crc = verifyCrcTrailer(buffer);
+    if (crc.hasTrailer && !crc.ok) {
+      throw new Error("EvermindLM.loadWeights: checkpoint failed CRC integrity check (corrupt or truncated)");
+    }
     const head = new Uint32Array(buffer, 0, 9);
     if (head[0] !== MAGIC) throw new Error("EvermindLM.loadWeights: bad magic (not an EVL0 checkpoint)");
     const version = head[1]!;
@@ -453,19 +466,51 @@ export class EvermindLM {
     ) {
       throw new Error("EvermindLM.loadWeights: config mismatch with checkpoint");
     }
+    const total = this.parameters().reduce((n, p) => n + p.data.length, 0);
+    const headerBytes = 36;
+    return version === 2
+      ? dequantizeFp16(new Uint16Array(buffer, headerBytes, total))
+      : new Float32Array(buffer.slice(headerBytes, headerBytes + total * 4));
+  }
+
+  /** Flat concatenation of all params, canonical order (matches checkpoint layout). */
+  private _flat(): Float32Array {
     const params = this.parameters();
     const total = params.reduce((n, p) => n + p.data.length, 0);
-    const headerBytes = 36;
-    const flat =
-      version === 2
-        ? dequantizeFp16(new Uint16Array(buffer, headerBytes, total))
-        : new Float32Array(buffer.slice(headerBytes, headerBytes + total * 4));
+    const flat = new Float32Array(total);
     let o = 0;
-    for (const p of params) {
+    for (const p of params) { flat.set(p.data, o); o += p.data.length; }
+    return flat;
+  }
+
+  /** Distribute a flat param vector back into the model's parameters. */
+  private _setFlat(flat: Float32Array): void {
+    let o = 0;
+    for (const p of this.parameters()) {
       p.data.set(flat.subarray(o, o + p.data.length));
       o += p.data.length;
     }
   }
+
+  /**
+   * Export a SPARSE DELTA of the current weights against a base EVL0 checkpoint
+   * (EVM-6). Online WSLA updates only a few rows, so a delta persists kilobytes
+   * instead of rewriting the whole model. Reconstruct with {@link loadDelta}.
+   */
+  exportDelta(baseCheckpoint: ArrayBuffer, opts: { eps?: number } = {}): ArrayBuffer {
+    const base = this._readFlat(baseCheckpoint);
+    const current = this._flat();
+    // Row-granular when the param vector tiles evenly by the model width (the
+    // embedding dominates and is dModel-wide); else fall back to per-element.
+    const rowSize = current.length % this.config.dModel === 0 ? this.config.dModel : 1;
+    return serializeRowDelta(computeRowDelta(base, current, rowSize, opts.eps ?? 0));
+  }
+
+  /** Reconstruct weights from a base EVL0 checkpoint + a delta (EVM-6). */
+  loadDelta(baseCheckpoint: ArrayBuffer, delta: ArrayBuffer): void {
+    const base = this._readFlat(baseCheckpoint);
+    this._setFlat(applyRowDelta(base, deserializeRowDelta(delta)));
+  }
 }
 
 /** Minimal sequence trainer: AdamW over next-token cross-entropy. */

package/src/model/mamba_model.ts

@@ -36,6 +36,7 @@ import { LINEAR_FORWARD_WGSL } from '../kernels/linear_projection.js';
 import { ACTIVATIONS_WGSL }    from '../kernels/activations.js';
 import { gaussianArray, setInitSeed } from '../utils/rng.js';
 import { quantizeFp16, dequantizeFp16 } from '../utils/quantization.js';
+import { appendCrcTrailer, verifyCrcTrailer } from '../utils/crc32.js';
 
 // ── Public types ──────────────────────────────────────────────────────────────
 
@@ -485,7 +486,9 @@ export class HybridMambaModel {
             }
         }
 
-        return out;
+        // Append a CRC-32 trailer for integrity-on-load (backward compatible —
+        // length-bounded readers ignore the trailing bytes). (EVM-7)
+        return appendCrcTrailer(out);
     }
 
     /**
@@ -496,6 +499,11 @@ export class HybridMambaModel {
      * v3: identical layout to v2 but the data section is fp16 (dequantised on load).
      */
     async loadWeights(buffer: ArrayBuffer): Promise<void> {
+        // Verify the CRC trailer when present (corrupt/truncated guard, EVM-7).
+        const crc = verifyCrcTrailer(buffer);
+        if (crc.hasTrailer && !crc.ok) {
+            throw new Error('Invalid weight file: failed CRC integrity check (corrupt or truncated).');
+        }
         const view = new DataView(buffer);
         let off    = 0;
 

package/src/utils/crc32.ts

@@ -0,0 +1,82 @@
+/**
+ * utils/crc32.ts — checkpoint integrity (CRC-32) + a backward-compatible trailer.
+ *
+ * Checkpoints had no integrity check: a truncated or bit-rotted `.bin` would
+ * either throw deep in the parser or, worse, load corrupt weights silently. This
+ * adds a standard IEEE CRC-32 and a self-describing trailer that callers append
+ * on export and verify on load.
+ *
+ * The trailer is appended AFTER the existing payload as `[magic u32][crc u32]`
+ * (8 bytes, little-endian). Because every checkpoint reader consumes a
+ * length-bounded payload (header declares element counts) and ignores trailing
+ * bytes, an old reader still loads a trailer-bearing file — the trailer is
+ * purely additive. The CRC covers the payload bytes only (everything before the
+ * trailer).
+ */
+
+/** Trailer sentinel: 'EVCR' (Evermind CRc), little-endian uint32. */
+export const CRC_TRAILER_MAGIC = 0x52435645; // bytes 45 56 43 52 = "EVCR"
+const TRAILER_BYTES = 8;
+
+/** Precomputed CRC-32 (IEEE 802.3, reflected) lookup table. */
+const CRC_TABLE: Uint32Array = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+
+/** IEEE CRC-32 of a byte buffer, returned as an unsigned 32-bit number. */
+export function crc32(bytes: Uint8Array): number {
+    let crc = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++) {
+        crc = CRC_TABLE[(crc ^ bytes[i]!) & 0xff]! ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** Return a new ArrayBuffer = `payload` followed by the CRC trailer. */
+export function appendCrcTrailer(payload: ArrayBuffer): ArrayBuffer {
+    const body = new Uint8Array(payload);
+    const out = new ArrayBuffer(body.length + TRAILER_BYTES);
+    const u8 = new Uint8Array(out);
+    u8.set(body, 0);
+    const view = new DataView(out);
+    view.setUint32(body.length, CRC_TRAILER_MAGIC, true);
+    view.setUint32(body.length + 4, crc32(body), true);
+    return out;
+}
+
+export interface CrcCheck {
+    /** True when a recognised CRC trailer is present. */
+    hasTrailer: boolean;
+    /** True when no trailer is present, or the trailer's CRC matches the payload. */
+    ok: boolean;
+    /** The payload with any trailer stripped (safe to parse). */
+    body: ArrayBuffer;
+}
+
+/**
+ * Inspect a buffer for a CRC trailer. When present, verifies the CRC over the
+ * preceding payload. When absent (legacy file), reports `ok: true` and returns
+ * the buffer unchanged — so verification is opt-in by the writer, never a
+ * hard requirement that would reject pre-CRC checkpoints.
+ */
+export function verifyCrcTrailer(buffer: ArrayBuffer): CrcCheck {
+    if (buffer.byteLength < TRAILER_BYTES) {
+        return { hasTrailer: false, ok: true, body: buffer };
+    }
+    const view = new DataView(buffer);
+    const bodyLen = buffer.byteLength - TRAILER_BYTES;
+    const magic = view.getUint32(bodyLen, true);
+    if (magic !== CRC_TRAILER_MAGIC) {
+        return { hasTrailer: false, ok: true, body: buffer };
+    }
+    const stored = view.getUint32(bodyLen + 4, true);
+    const body = buffer.slice(0, bodyLen);
+    const ok = crc32(new Uint8Array(body)) === stored;
+    return { hasTrailer: true, ok, body };
+}