@tryhamster/gerbil 1.0.0-rc.8 → 1.0.0

package/dist/types-DQBe2lFo.d.mts

@@ -0,0 +1,165 @@
+//#region src/memory/types.d.ts
+/**
+ * Type definitions for Gerbil's memory / RAG module.
+ *
+ * The module is engine-agnostic: it stores text + embeddings behind a
+ * pluggable {@link MemoryStore} and embeds text via an injected
+ * {@link Embedder}. Gerbil's native embeddings are wired in via a tiny
+ * adapter (see `gerbil-embedder.ts`).
+ */
+/** Arbitrary JSON-serializable metadata attached to a memory record. */
+type MemoryMetadata = Record<string, unknown>;
+/**
+ * A single stored memory.
+ *
+ * Vectors are stored L2-normalized so that cosine similarity reduces to a
+ * dot product. `embedding` may be omitted for records awaiting embedding.
+ */
+type MemoryRecord = {
+  /** Stable unique id (generated on insert if not supplied). */
+  id: string;
+  /** The raw text content of this memory. */
+  text: string;
+  /** L2-normalized embedding vector. Omitted only before embedding. */
+  embedding?: Float32Array;
+  /** Arbitrary metadata for filtering and provenance. */
+  metadata: MemoryMetadata;
+  /** Epoch milliseconds when the record was created. */
+  createdAt: number;
+};
+/**
+ * Embeds one or more texts into vectors.
+ *
+ * Implementations should return one vector per input text, in order.
+ * Gerbil's native embeddings satisfy this via {@link createGerbilEmbedder}.
+ */
+type Embedder = (texts: string[]) => Promise<Float32Array[]>;
+/**
+ * Predicate or transform applied to text on write to redact sensitive data.
+ *
+ * - A {@link RegExp} replaces all matches with `[REDACTED]`.
+ * - A function returns the redacted string.
+ */
+type Redactor = RegExp | ((text: string) => string);
+/** A hit returned from a vector search. */
+type MemorySearchResult = {
+  /** The matched record. */
+  record: MemoryRecord;
+  /** Cosine similarity score in [-1, 1] (typically [0, 1]). */
+  score: number;
+};
+/** Filter applied to record metadata. Each key must match exactly. */
+type MetadataFilter = Record<string, unknown>;
+/** Options for {@link MemoryStore.search}. */
+type StoreSearchOptions = {
+  /** Maximum number of results (default 5). */
+  k?: number;
+  /** Exact-match metadata filter applied before ranking. */
+  filter?: MetadataFilter;
+  /** Minimum score to include (default: no minimum). */
+  minScore?: number;
+};
+/**
+ * Pluggable persistence + retrieval backend.
+ *
+ * Backends are engine-agnostic and store pre-normalized embeddings. The
+ * default in-memory store works in Node and the browser; an IndexedDB store
+ * adds browser durability and a file store adds Node durability.
+ */
+type MemoryStore = {
+  /** Insert or replace a record by id. */
+  add(record: MemoryRecord): Promise<void>;
+  /** Insert or replace many records (may be faster than per-record adds). */
+  addMany(records: MemoryRecord[]): Promise<void>;
+  /** Fetch a record by id, or `undefined` if absent. */
+  get(id: string): Promise<MemoryRecord | undefined>;
+  /** Cosine top-k search over a query vector. */
+  search(queryVector: Float32Array, options?: StoreSearchOptions): Promise<MemorySearchResult[]>;
+  /** Delete a record by id. Returns `true` if it existed. */
+  delete(id: string): Promise<boolean>;
+  /** List all records (optionally filtered by metadata). */
+  list(filter?: MetadataFilter): Promise<MemoryRecord[]>;
+  /** Remove all records. */
+  clear(): Promise<void>;
+  /** Total number of stored records. */
+  size(): Promise<number>;
+};
+/** Serializable snapshot of a store for import/export. */
+type MemoryExport = {
+  /** Schema version for forward compatibility. */
+  version: 1;
+  /** Exported records (embeddings serialized as plain number arrays). */
+  records: SerializedRecord[];
+};
+/** A record with its embedding serialized as a plain array for JSON. */
+type SerializedRecord = {
+  id: string;
+  text: string;
+  embedding?: number[];
+  metadata: MemoryMetadata;
+  createdAt: number;
+};
+/** Options controlling document chunking before embedding. */
+type ChunkOptions = {
+  /** Target chunk size in characters (default 1000). */
+  chunkSize?: number;
+  /** Overlap between consecutive chunks in characters (default 200). */
+  overlap?: number;
+};
+/** Options for {@link Memory.add}. */
+type AddOptions = {
+  /** Metadata to attach to every resulting record. */
+  metadata?: MemoryMetadata;
+  /** Explicit id (single-chunk adds only). Auto-generated otherwise. */
+  id?: string;
+  /**
+   * Split long text into overlapping chunks before embedding.
+   * Pass `true` for defaults or an object to configure. Default: no chunking.
+   */
+  chunk?: boolean | ChunkOptions;
+};
+/** Options for {@link Memory.search}. */
+type SearchOptions = {
+  /** Maximum number of results (default 5). */
+  k?: number;
+  /** Exact-match metadata filter. */
+  filter?: MetadataFilter;
+  /** Minimum cosine score to include. */
+  minScore?: number;
+};
+/** Options for {@link Memory.recall} (token-budgeted context packing). */
+type RecallOptions = {
+  /** Maximum tokens of context to pack (default 1024). */
+  tokenBudget?: number;
+  /** Candidate pool size to retrieve before packing (default 20). */
+  k?: number;
+  /** Exact-match metadata filter. */
+  filter?: MetadataFilter;
+  /** Minimum cosine score for a candidate to be considered. */
+  minScore?: number;
+  /** Separator placed between packed memories (default "\n\n"). */
+  separator?: string;
+};
+/** Result of {@link Memory.recall}: a packed context block plus provenance. */
+type RecallResult = {
+  /** The token-budgeted context block, ready to prepend to a prompt. */
+  context: string;
+  /** The records included in the context, in packed order. */
+  records: MemoryRecord[];
+  /** Approximate token count of {@link RecallResult.context}. */
+  tokensUsed: number;
+};
+/** Configuration for {@link createMemory}. */
+type MemoryOptions = {
+  /** Embedder used to vectorize text. Required. */
+  embed: Embedder;
+  /** Persistence backend. Defaults to an in-memory store. */
+  store?: MemoryStore;
+  /** Redaction applied to text on write. */
+  redact?: Redactor;
+  /** Default chunking applied to {@link Memory.add} when `chunk` is true. */
+  chunk?: ChunkOptions;
+};
+//#endregion
+export { MemoryMetadata as a, MemorySearchResult as c, RecallOptions as d, RecallResult as f, StoreSearchOptions as g, SerializedRecord as h, MemoryExport as i, MemoryStore as l, SearchOptions as m, ChunkOptions as n, MemoryOptions as o, Redactor as p, Embedder as r, MemoryRecord as s, AddOptions as t, MetadataFilter as u };
+//# sourceMappingURL=types-DQBe2lFo.d.mts.map

package/dist/types-DQBe2lFo.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-DQBe2lFo.d.mts","names":[],"sources":["../src/memory/types.ts"],"sourcesContent":[],"mappings":";;AAUA;AAQA;AAmBA;AAQA;AAGA;AAQA;AAGA;AAgBA;AAEc,KAnEF,cAAA,GAAiB,MAmEf,CAAA,MAAA,EAAA,OAAA,CAAA;;;;;;;AAMgC,KAjElC,YAAA,GAiEkC;EAA6B;EAAR,EAAA,EAAA,MAAA;EAE7C;EAEN,IAAA,EAAA,MAAA;EAAyB;EAAR,SAAA,CAAA,EA/DnB,YA+DmB;EAEtB;EAED,QAAA,EAjEE,cAiEF;EAAO;EAIL,SAAA,EAAA,MAAY;AAQxB,CAAA;AASA;AAQA;AAaA;AAUA;AAcA;AAUA;AAES,KApIG,QAAA,GAoIH,CAAA,KAAA,EAAA,MAAA,EAAA,EAAA,GApImC,OAoInC,CApI2C,YAoI3C,EAAA,CAAA;;;;;;;KA5HG,QAAA,GAAW;;KAGX,kBAAA;;UAEF;;;;;KAME,cAAA,GAAiB;;KAGjB,kBAAA;;;;WAID;;;;;;;;;;;KAYC,WAAA;;cAEE,eAAe;;mBAEV,iBAAiB;;mBAEjB,QAAQ;;sBAEL,wBAAwB,qBAAqB,QAAQ;;sBAErD;;gBAEN,iBAAiB,QAAQ;;WAE9B;;UAED;;;KAIE,YAAA;;;;WAID;;;KAIC,gBAAA;;;;YAIA;;;;KAKA,YAAA;;;;;;;KAQA,UAAA;;aAEC;;;;;;;oBAOO;;;KAIR,aAAA;;;;WAID;;;;;KAMC,aAAA;;;;;;WAMD;;;;;;;KAQC,YAAA;;;;WAID;;;;;KAMC,aAAA;;SAEH;;UAEC;;WAEC;;UAED"}

package/dist/{utils-CZBZ8dgR.mjs → utils-DKO55ZmZ.mjs}

@@ -60,4 +60,4 @@ function extractJson(text) {
 
 //#endregion
 export { zodToJsonSchema as n, extractJson as t };
-//# sourceMappingURL=utils-CZBZ8dgR.mjs.map
+//# sourceMappingURL=utils-DKO55ZmZ.mjs.map

package/dist/{utils-CZBZ8dgR.mjs.map → utils-DKO55ZmZ.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"utils-CZBZ8dgR.mjs","names":["properties: Record<string, any>","required: string[]"],"sources":["../src/core/utils.ts"],"sourcesContent":["/**\n * Shared utility functions for Gerbil core\n */\n\nimport type { z } from \"zod\";\n\n/**\n * Convert Zod schema to JSON Schema (simplified)\n * Handles objects, arrays, primitives, enums, optionals, and defaults\n */\nexport function zodToJsonSchema(schema: z.ZodType<any>): object {\n  try {\n    if (\"_def\" in schema) {\n      const def = (schema as any)._def;\n\n      if (def.typeName === \"ZodObject\") {\n        const shape = def.shape();\n        const properties: Record<string, any> = {};\n        const required: string[] = [];\n\n        for (const [key, value] of Object.entries(shape)) {\n          properties[key] = zodToJsonSchema(value as z.ZodType<any>);\n          // Check if required (not optional)\n          if (!(value as any)._def?.typeName?.includes(\"Optional\")) {\n            required.push(key);\n          }\n        }\n\n        return { type: \"object\", properties, required };\n      }\n      if (def.typeName === \"ZodString\") {\n        return { type: \"string\", description: def.description };\n      }\n      if (def.typeName === \"ZodNumber\") {\n        return { type: \"number\", description: def.description };\n      }\n      if (def.typeName === \"ZodBoolean\") {\n        return { type: \"boolean\" };\n      }\n      if (def.typeName === \"ZodArray\") {\n        return { type: \"array\", items: zodToJsonSchema(def.type) };\n      }\n      if (def.typeName === \"ZodEnum\") {\n        return { type: \"string\", enum: def.values };\n      }\n      if (def.typeName === \"ZodOptional\") {\n        return zodToJsonSchema(def.innerType);\n      }\n      if (def.typeName === \"ZodDefault\") {\n        const inner = zodToJsonSchema(def.innerType);\n        return { ...inner, default: def.defaultValue() };\n      }\n    }\n  } catch {}\n\n  return { type: \"string\" };\n}\n\n/**\n * Extract JSON from text (finds first { } or [ ] block)\n */\nexport function extractJson(text: string): string {\n  const jsonMatch = text.match(/\\{[\\s\\S]*\\}/);\n  if (jsonMatch) {\n    return jsonMatch[0];\n  }\n\n  const arrayMatch = text.match(/\\[[\\s\\S]*\\]/);\n  if (arrayMatch) {\n    return arrayMatch[0];\n  }\n\n  return text;\n}\n"],"mappings":";;;;;AAUA,SAAgB,gBAAgB,QAAgC;AAC9D,KAAI;AACF,MAAI,UAAU,QAAQ;GACpB,MAAM,MAAO,OAAe;AAE5B,OAAI,IAAI,aAAa,aAAa;IAChC,MAAM,QAAQ,IAAI,OAAO;IACzB,MAAMA,aAAkC,EAAE;IAC1C,MAAMC,WAAqB,EAAE;AAE7B,SAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,EAAE;AAChD,gBAAW,OAAO,gBAAgB,MAAwB;AAE1D,SAAI,CAAE,MAAc,MAAM,UAAU,SAAS,WAAW,CACtD,UAAS,KAAK,IAAI;;AAItB,WAAO;KAAE,MAAM;KAAU;KAAY;KAAU;;AAEjD,OAAI,IAAI,aAAa,YACnB,QAAO;IAAE,MAAM;IAAU,aAAa,IAAI;IAAa;AAEzD,OAAI,IAAI,aAAa,YACnB,QAAO;IAAE,MAAM;IAAU,aAAa,IAAI;IAAa;AAEzD,OAAI,IAAI,aAAa,aACnB,QAAO,EAAE,MAAM,WAAW;AAE5B,OAAI,IAAI,aAAa,WACnB,QAAO;IAAE,MAAM;IAAS,OAAO,gBAAgB,IAAI,KAAK;IAAE;AAE5D,OAAI,IAAI,aAAa,UACnB,QAAO;IAAE,MAAM;IAAU,MAAM,IAAI;IAAQ;AAE7C,OAAI,IAAI,aAAa,cACnB,QAAO,gBAAgB,IAAI,UAAU;AAEvC,OAAI,IAAI,aAAa,aAEnB,QAAO;IAAE,GADK,gBAAgB,IAAI,UAAU;IACzB,SAAS,IAAI,cAAc;IAAE;;SAG9C;AAER,QAAO,EAAE,MAAM,UAAU;;;;;AAM3B,SAAgB,YAAY,MAAsB;CAChD,MAAM,YAAY,KAAK,MAAM,cAAc;AAC3C,KAAI,UACF,QAAO,UAAU;CAGnB,MAAM,aAAa,KAAK,MAAM,cAAc;AAC5C,KAAI,WACF,QAAO,WAAW;AAGpB,QAAO"}
+{"version":3,"file":"utils-DKO55ZmZ.mjs","names":["properties: Record<string, any>","required: string[]"],"sources":["../src/core/utils.ts"],"sourcesContent":["/**\n * Shared utility functions for Gerbil core\n */\n\nimport type { z } from \"zod\";\n\n/**\n * Convert Zod schema to JSON Schema (simplified)\n * Handles objects, arrays, primitives, enums, optionals, and defaults\n */\nexport function zodToJsonSchema(schema: z.ZodType<any>): object {\n  try {\n    if (\"_def\" in schema) {\n      const def = (schema as any)._def;\n\n      if (def.typeName === \"ZodObject\") {\n        const shape = def.shape();\n        const properties: Record<string, any> = {};\n        const required: string[] = [];\n\n        for (const [key, value] of Object.entries(shape)) {\n          properties[key] = zodToJsonSchema(value as z.ZodType<any>);\n          // Check if required (not optional)\n          if (!(value as any)._def?.typeName?.includes(\"Optional\")) {\n            required.push(key);\n          }\n        }\n\n        return { type: \"object\", properties, required };\n      }\n      if (def.typeName === \"ZodString\") {\n        return { type: \"string\", description: def.description };\n      }\n      if (def.typeName === \"ZodNumber\") {\n        return { type: \"number\", description: def.description };\n      }\n      if (def.typeName === \"ZodBoolean\") {\n        return { type: \"boolean\" };\n      }\n      if (def.typeName === \"ZodArray\") {\n        return { type: \"array\", items: zodToJsonSchema(def.type) };\n      }\n      if (def.typeName === \"ZodEnum\") {\n        return { type: \"string\", enum: def.values };\n      }\n      if (def.typeName === \"ZodOptional\") {\n        return zodToJsonSchema(def.innerType);\n      }\n      if (def.typeName === \"ZodDefault\") {\n        const inner = zodToJsonSchema(def.innerType);\n        return { ...inner, default: def.defaultValue() };\n      }\n    }\n  } catch {}\n\n  return { type: \"string\" };\n}\n\n/**\n * Extract JSON from text (finds first { } or [ ] block)\n */\nexport function extractJson(text: string): string {\n  const jsonMatch = text.match(/\\{[\\s\\S]*\\}/);\n  if (jsonMatch) {\n    return jsonMatch[0];\n  }\n\n  const arrayMatch = text.match(/\\[[\\s\\S]*\\]/);\n  if (arrayMatch) {\n    return arrayMatch[0];\n  }\n\n  return text;\n}\n"],"mappings":";;;;;AAUA,SAAgB,gBAAgB,QAAgC;AAC9D,KAAI;AACF,MAAI,UAAU,QAAQ;GACpB,MAAM,MAAO,OAAe;AAE5B,OAAI,IAAI,aAAa,aAAa;IAChC,MAAM,QAAQ,IAAI,OAAO;IACzB,MAAMA,aAAkC,EAAE;IAC1C,MAAMC,WAAqB,EAAE;AAE7B,SAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,EAAE;AAChD,gBAAW,OAAO,gBAAgB,MAAwB;AAE1D,SAAI,CAAE,MAAc,MAAM,UAAU,SAAS,WAAW,CACtD,UAAS,KAAK,IAAI;;AAItB,WAAO;KAAE,MAAM;KAAU;KAAY;KAAU;;AAEjD,OAAI,IAAI,aAAa,YACnB,QAAO;IAAE,MAAM;IAAU,aAAa,IAAI;IAAa;AAEzD,OAAI,IAAI,aAAa,YACnB,QAAO;IAAE,MAAM;IAAU,aAAa,IAAI;IAAa;AAEzD,OAAI,IAAI,aAAa,aACnB,QAAO,EAAE,MAAM,WAAW;AAE5B,OAAI,IAAI,aAAa,WACnB,QAAO;IAAE,MAAM;IAAS,OAAO,gBAAgB,IAAI,KAAK;IAAE;AAE5D,OAAI,IAAI,aAAa,UACnB,QAAO;IAAE,MAAM;IAAU,MAAM,IAAI;IAAQ;AAE7C,OAAI,IAAI,aAAa,cACnB,QAAO,gBAAgB,IAAI,UAAU;AAEvC,OAAI,IAAI,aAAa,aAEnB,QAAO;IAAE,GADK,gBAAgB,IAAI,UAAU;IACzB,SAAS,IAAI,cAAc;IAAE;;SAG9C;AAER,QAAO,EAAE,MAAM,UAAU;;;;;AAM3B,SAAgB,YAAY,MAAsB;CAChD,MAAM,YAAY,KAAK,MAAM,cAAc;AAC3C,KAAI,UACF,QAAO,UAAU;CAGnB,MAAM,aAAa,KAAK,MAAM,cAAc;AAC5C,KAAI,WACF,QAAO,WAAW;AAGpB,QAAO"}

package/dist/vector-B0panuy6.mjs

@@ -0,0 +1,95 @@
+//#region src/memory/serialize.ts
+/** Convert a runtime record to its JSON-safe form. */
+function serializeRecord(record) {
+	return {
+		id: record.id,
+		text: record.text,
+		embedding: record.embedding ? Array.from(record.embedding) : void 0,
+		metadata: record.metadata,
+		createdAt: record.createdAt
+	};
+}
+/** Rebuild a runtime record (with a {@link Float32Array}) from JSON form. */
+function deserializeRecord(record) {
+	return {
+		id: record.id,
+		text: record.text,
+		embedding: record.embedding ? Float32Array.from(record.embedding) : void 0,
+		metadata: record.metadata ?? {},
+		createdAt: record.createdAt
+	};
+}
+/**
+* True when every key in `filter` is present on `metadata` with an equal
+* (strict ===) value. An empty/undefined filter matches everything.
+*/
+function matchesFilter(metadata, filter) {
+	if (!filter) return true;
+	for (const key of Object.keys(filter)) if (metadata[key] !== filter[key]) return false;
+	return true;
+}
+
+//#endregion
+//#region src/memory/vector.ts
+/**
+* Vector math for cosine similarity search.
+*
+* Vectors are stored L2-normalized so cosine similarity is a plain dot
+* product. Normalization happens once on insert via {@link normalize}.
+*/
+/**
+* Return an L2-normalized copy of `vector`.
+*
+* A zero vector is returned unchanged (its norm is 0).
+*/
+function normalize(vector) {
+	let sumSquares = 0;
+	for (let i = 0; i < vector.length; i++) sumSquares += vector[i] * vector[i];
+	const norm = Math.sqrt(sumSquares);
+	if (norm === 0) return vector;
+	const out = new Float32Array(vector.length);
+	for (let i = 0; i < vector.length; i++) out[i] = vector[i] / norm;
+	return out;
+}
+/**
+* Dot product of two equal-length vectors.
+*
+* For L2-normalized inputs this equals cosine similarity.
+*/
+function dot(a, b) {
+	const length = Math.min(a.length, b.length);
+	let sum = 0;
+	for (let i = 0; i < length; i++) sum += a[i] * b[i];
+	return sum;
+}
+/**
+* Cosine similarity of two vectors, normalizing on the fly.
+*
+* Prefer {@link dot} when both inputs are already normalized.
+*/
+function cosine(a, b) {
+	return dot(normalize(a), normalize(b));
+}
+/**
+* Score every candidate against `query` (dot product) and return the top `k`
+* by descending score, optionally filtering by a minimum score.
+*
+* Inputs are assumed normalized; this keeps the hot path branch-free.
+*/
+function topK(query, candidates, k, minScore) {
+	const scored = [];
+	for (const candidate of candidates) {
+		const score = dot(query, candidate.vector);
+		if (minScore !== void 0 && score < minScore) continue;
+		scored.push({
+			item: candidate.item,
+			score
+		});
+	}
+	scored.sort((a, b) => b.score - a.score);
+	return scored.slice(0, k);
+}
+
+//#endregion
+export { deserializeRecord as a, topK as i, dot as n, matchesFilter as o, normalize as r, serializeRecord as s, cosine as t };
+//# sourceMappingURL=vector-B0panuy6.mjs.map

package/dist/vector-B0panuy6.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-B0panuy6.mjs","names":["scored: Scored<T>[]"],"sources":["../src/memory/serialize.ts","../src/memory/vector.ts"],"sourcesContent":["/**\n * (De)serialization helpers shared by stores and import/export.\n *\n * Embeddings are stored at runtime as {@link Float32Array} but serialized as\n * plain number arrays so records survive `JSON.stringify` and IndexedDB\n * structured clone round-trips.\n */\n\nimport type { MemoryRecord, SerializedRecord } from \"./types.js\";\n\n/** Convert a runtime record to its JSON-safe form. */\nexport function serializeRecord(record: MemoryRecord): SerializedRecord {\n  return {\n    id: record.id,\n    text: record.text,\n    embedding: record.embedding ? Array.from(record.embedding) : undefined,\n    metadata: record.metadata,\n    createdAt: record.createdAt,\n  };\n}\n\n/** Rebuild a runtime record (with a {@link Float32Array}) from JSON form. */\nexport function deserializeRecord(record: SerializedRecord): MemoryRecord {\n  return {\n    id: record.id,\n    text: record.text,\n    embedding: record.embedding ? Float32Array.from(record.embedding) : undefined,\n    metadata: record.metadata ?? {},\n    createdAt: record.createdAt,\n  };\n}\n\n/**\n * True when every key in `filter` is present on `metadata` with an equal\n * (strict ===) value. An empty/undefined filter matches everything.\n */\nexport function matchesFilter(\n  metadata: Record<string, unknown>,\n  filter?: Record<string, unknown>,\n): boolean {\n  if (!filter) {\n    return true;\n  }\n  for (const key of Object.keys(filter)) {\n    if (metadata[key] !== filter[key]) {\n      return false;\n    }\n  }\n  return true;\n}\n","/**\n * Vector math for cosine similarity search.\n *\n * Vectors are stored L2-normalized so cosine similarity is a plain dot\n * product. Normalization happens once on insert via {@link normalize}.\n */\n\n/**\n * Return an L2-normalized copy of `vector`.\n *\n * A zero vector is returned unchanged (its norm is 0).\n */\nexport function normalize(vector: Float32Array): Float32Array {\n  let sumSquares = 0;\n  for (let i = 0; i < vector.length; i++) {\n    sumSquares += vector[i] * vector[i];\n  }\n  const norm = Math.sqrt(sumSquares);\n  if (norm === 0) {\n    return vector;\n  }\n  const out = new Float32Array(vector.length);\n  for (let i = 0; i < vector.length; i++) {\n    out[i] = vector[i] / norm;\n  }\n  return out;\n}\n\n/**\n * Dot product of two equal-length vectors.\n *\n * For L2-normalized inputs this equals cosine similarity.\n */\nexport function dot(a: Float32Array, b: Float32Array): number {\n  const length = Math.min(a.length, b.length);\n  let sum = 0;\n  for (let i = 0; i < length; i++) {\n    sum += a[i] * b[i];\n  }\n  return sum;\n}\n\n/**\n * Cosine similarity of two vectors, normalizing on the fly.\n *\n * Prefer {@link dot} when both inputs are already normalized.\n */\nexport function cosine(a: Float32Array, b: Float32Array): number {\n  return dot(normalize(a), normalize(b));\n}\n\n/** A scored item used by {@link topK}. */\nexport type Scored<T> = { item: T; score: number };\n\n/**\n * Score every candidate against `query` (dot product) and return the top `k`\n * by descending score, optionally filtering by a minimum score.\n *\n * Inputs are assumed normalized; this keeps the hot path branch-free.\n */\nexport function topK<T>(\n  query: Float32Array,\n  candidates: { item: T; vector: Float32Array }[],\n  k: number,\n  minScore?: number,\n): Scored<T>[] {\n  const scored: Scored<T>[] = [];\n  for (const candidate of candidates) {\n    const score = dot(query, candidate.vector);\n    if (minScore !== undefined && score < minScore) {\n      continue;\n    }\n    scored.push({ item: candidate.item, score });\n  }\n  scored.sort((a, b) => b.score - a.score);\n  return scored.slice(0, k);\n}\n"],"mappings":";;AAWA,SAAgB,gBAAgB,QAAwC;AACtE,QAAO;EACL,IAAI,OAAO;EACX,MAAM,OAAO;EACb,WAAW,OAAO,YAAY,MAAM,KAAK,OAAO,UAAU,GAAG;EAC7D,UAAU,OAAO;EACjB,WAAW,OAAO;EACnB;;;AAIH,SAAgB,kBAAkB,QAAwC;AACxE,QAAO;EACL,IAAI,OAAO;EACX,MAAM,OAAO;EACb,WAAW,OAAO,YAAY,aAAa,KAAK,OAAO,UAAU,GAAG;EACpE,UAAU,OAAO,YAAY,EAAE;EAC/B,WAAW,OAAO;EACnB;;;;;;AAOH,SAAgB,cACd,UACA,QACS;AACT,KAAI,CAAC,OACH,QAAO;AAET,MAAK,MAAM,OAAO,OAAO,KAAK,OAAO,CACnC,KAAI,SAAS,SAAS,OAAO,KAC3B,QAAO;AAGX,QAAO;;;;;;;;;;;;;;;;ACpCT,SAAgB,UAAU,QAAoC;CAC5D,IAAI,aAAa;AACjB,MAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,IACjC,eAAc,OAAO,KAAK,OAAO;CAEnC,MAAM,OAAO,KAAK,KAAK,WAAW;AAClC,KAAI,SAAS,EACX,QAAO;CAET,MAAM,MAAM,IAAI,aAAa,OAAO,OAAO;AAC3C,MAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,IACjC,KAAI,KAAK,OAAO,KAAK;AAEvB,QAAO;;;;;;;AAQT,SAAgB,IAAI,GAAiB,GAAyB;CAC5D,MAAM,SAAS,KAAK,IAAI,EAAE,QAAQ,EAAE,OAAO;CAC3C,IAAI,MAAM;AACV,MAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,IAC1B,QAAO,EAAE,KAAK,EAAE;AAElB,QAAO;;;;;;;AAQT,SAAgB,OAAO,GAAiB,GAAyB;AAC/D,QAAO,IAAI,UAAU,EAAE,EAAE,UAAU,EAAE,CAAC;;;;;;;;AAYxC,SAAgB,KACd,OACA,YACA,GACA,UACa;CACb,MAAMA,SAAsB,EAAE;AAC9B,MAAK,MAAM,aAAa,YAAY;EAClC,MAAM,QAAQ,IAAI,OAAO,UAAU,OAAO;AAC1C,MAAI,aAAa,UAAa,QAAQ,SACpC;AAEF,SAAO,KAAK;GAAE,MAAM,UAAU;GAAM;GAAO,CAAC;;AAE9C,QAAO,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM;AACxC,QAAO,OAAO,MAAM,GAAG,EAAE"}

package/docs/PROJECT-STATE.md

@@ -0,0 +1,321 @@
+# Gerbil — Project State & Architecture Decision
+
+**As of 2026-06-14.** The single authoritative snapshot. When something here conflicts
+with an older doc, this wins. Supersedes scattered findings in `docs/research/*` and
+the paper's roadmap. **Newest material is §12** (native audio begins — Moonshine STT
++ Kani-TTS-2 NanoCodec decoder; Gemma 4 E2B text decode; on-device memory/RAG; the
+text+ViT autoresearch campaign; gerbil-site live on the native engine). §11 captured
+EmbeddingGemma on-device, LFM2.5, the SPM tokenizer fix, MLX/DWQ loader, progress fix.
+
+---
+
+## 1. What Gerbil is
+
+A local LLM inference library that runs models in the browser and Node on a
+**single native WebGPU engine** behind one task API (no fallback lane — §2). The
+headline achievements this cycle: the from-scratch native engine **works on mobile**
+(iPad/iOS Safari 26.5+, WebKit) — previously it crashed — a desktop optimization
+pass roughly doubled its throughput, and the engine went **multimodal natively**:
+text embeddings ship (Qwen3-Embedding-0.6B) and the Qwen3.5 vision encoder is built
+**bit-exact vs HuggingFace** (vision LM-integration is phase 2).
+
+## 2. The decided architecture — NATIVE-ONLY (owner decision, overrides the panel)
+
+**Decision (owner, 2026-06-13):** Gerbil is a single native WebGPU engine. **No
+tfjs fallback lane** — a permanent fallback "assumes defeat to begin with." The
+panel proposed keeping tfjs as a breadth lane; the owner rejected that. Instead:
+
+- **Launch set = text + vision + embeddings, ALL native.** One model per modality
+  by default, expandable to other families via the add-model-family process.
+- **Audio (TTS/STT) is deferred, not delegated to tfjs** — it ships later as
+  small *native* models (candidates under eval: VibeVoice-1.5B, OmniVoice,
+  dots.tts-soar for TTS — IF they publish safetensors; Moonshine for STT). "What's
+  the big deal" — launching without audio is fine; a permanent second engine is not.
+- **tfjs is at most temporary dev scaffolding, not a destination.** It may stay
+  briefly to keep desktop demos working during the native build, but it is being
+  removed, not kept as a lane. `chrome-backend.ts` is deleted outright.
+- **Vision uses Qwen3.5's OWN built-in ViT** (we currently skip its 192MB tower) —
+  one multimodal model, not a separate vision model. Stop dropping it "like idiots."
+- **A thin onnxruntime-web bridge is a break-glass option only** — used solely if
+  a needed model has no extractable weights AND no native alternative. Not a lane.
+
+**Status update (2026-06-13):** both next modalities have landed natively.
+**Embeddings ship** (Qwen3-Embedding-0.6B, validated). The **vision encoder is
+DONE** — the Qwen3.5 ViT runs natively and is **bit-exact vs HF transformers 5.12**
+(per-token cosine 1.000000). The earlier "parallel attention kernel first" gate was
+based on a misread of dead code (§5): the attention kernel was already parallel, and
+non-causal was a one-line `is_causal` flag, not a rewrite. The remaining vision work
+is **LM-side integration** (M-RoPE, token splice, image preprocessing) — phase 2,
+plumbing over a verified core. Audio follows once a native small model is validated.
+
+## 3. Capability matrix (what's true today)
+
+Native-only. The "tfjs lane" is gone — tfjs is temporary dev scaffolding being
+removed (§2), not a capability path.
+
+| Modality | Native status |
+|---|---|
+| Text | ✅ ~51 tok/s mobile (sustained 200-tok), ~207 desktop, bit-correct |
+| Text (alt family) | ✅ **LFM2.5-350M LANDED** (`Lfm2ForCausalLM`, hybrid conv/attn): ~600 tok/s desktop (2.8× Qwen), ~46 tok/s mobile, ~199MB q4, no new kernels |
+| Embeddings | ✅ **DONE + ON iPad** — **EmbeddingGemma-300M** (bidirectional Gemma3 encoder, 173MB MLX-4bit) runs on iPad Safari; cos=1.00000 vs NumPy ref, Mars/bread margin >0.1, dim 768. First non-Qwen embedder. (Qwen3-Embedding-0.6B still works on desktop but OOMs iPad at 1.2GB BF16.) |
+| Vision (image) | ✅ **END-TO-END DONE** — Qwen3.5 ViT, bit-exact vs HF (cosine 1.000000); `describeImage()` word-identical to HF; runs on iPad |
+| Text model families (Llama/Mistral/Gemma) | 🟢 cheap — now usually **Tier-1, generator-only, NO new kernels** (kernel library saturated for standard transformers) |
+| Text (Gemma 4 E2B) | ✅ **COHERENT on q4** (`gemma4.ts`): "capital of France"→"Paris", ~83 tok/s, all 35 layers cos≥0.998 vs MLX-LM. PLE, KV-share (20 layers), proportional/dual-theta RoPE, GeGLU, `Softcap`, double-wide MLP, V-norm, per-node `attn_scale`, head_dim-512 attention. **PLE CPU-streamed (0 MB GPU)** — not GPU-sharded |
+| STT | 🟢 **Moonshine native LANDED** (`moonshine.ts`, `moonshine-executor.ts`, `moonshine-stt.ts`): raw-waveform Conv1d front-end (no FFT/log-mel), bit-exact `CrossAttention` kernel (max|err|<2e-4, cos≥0.9999), dual-graph encode-once/frozen-K-V/AR-decode, interleaved RoPE. Encoder cos≈0.990 vs HF; transcript substring-matches HF refs. **Whisper(ONNX) stays as multilingual / no-GPU fallback** (`src/core/stt.ts`) |
+| TTS | 🟡 **Kani-TTS-2 partial** (`kani_tts.ts`): NanoCodec decoder (FSQ + causal HiFi-GAN) **LANDED + validated bit-exact** (`test-nanocodec-decode.mjs`, gate err<1e-3, measured ~4.2e-6). LFM2-350M codec-LM backbone scaffolded; **AR-loop glue remaining** (frame positions + learnable RoPE + 4-token-frame decode). License: kani-tts-2-en = LFM1.0/other; 450m variant = Apache |
+| Memory / RAG | ✅ **SHIPPED** (`src/memory/`, `@tryhamster/gerbil/memory`): vector store (in-memory/IndexedDB/file), token-budgeted `recall()`, chunking, redaction, native EmbeddingGemma adapter. 12/12 tests. No new kernels |
+| No-WebGPU / old devices | not targeted — engine throws a clear error rather than degrading |
+
+## 4. Performance baselines (re-confirm before quoting)
+
+| Platform | Config | Decode tok/s | Note |
+|---|---|---|---|
+| M4 Max, node-dawn | optimized | ~207 | re-confirm on a cooled run; numbers between commit 2f0cabc and the isMetalBackend fix are invalid |
+| iPad (iOS 26.5) native | batch-all | ~41 (cooled, consistent) | NOT thermal — confirmed; Dawn-tuned autoresearch wins did NOT transfer to Metal (was ~51 pre-optimization) |
+| iPad native, submit floor | group=1 awaited | 6–8 | proven-correct floor |
+| iPad transformers.js (same model) | WebGPU | 7–12 | ~5× slower than native |
+
+## 5. Vision — DONE at the encoder level (bit-exact vs HF)
+
+The native Qwen3.5 vision encoder is **built and validated bit-exact** against HF
+transformers 5.12: **per-token cosine = 1.000000, max abs err ~5e-6**. Exposed as
+`engine.encodeImage(patches, gridTHW)` → merged image tokens `[rows, 1024]`. See
+paper §22 and `src/gpu/architectures/qwen3_5_vision.ts`, `src/gpu/vision-executor.ts`,
+`src/gpu/vision-preprocess.ts`.
+
+The earlier strategy panel claimed native vision was blocked on a single-threaded
+attention kernel. **That was wrong** — it read `src/gpu/kernels/wgsl/attention.wgsl`,
+a STALE reference file **not imported anywhere** (kernels are embedded strings in
+`registry.ts`; the dead `.wgsl` files have been deleted). What actually shipped:
+
+1. **The live attention kernel was already parallel** — `WGSL_ATTENTION` is a
+   tiled, online-softmax (flash-attention-style) kernel. No thread-0 serialization,
+   no rewrite needed.
+2. **Non-causal was a one-line flag.** An `is_causal` uniform
+   (`S_eff = is_causal ? min(S, causal_limit) : S`) makes it bidirectional for the
+   ViT; text stays causal by default. Done.
+3. **Patch-embed was NOT a new Conv3d kernel.** Patches arrive pre-flattened to
+   `[N, 1536]` from the host image processor, so the 5-D unfold/Conv3d collapses to
+   a plain `MatMul` + `AddBias`. New ops added were small: `AddBias`, `GeluErf`
+   (exact-erf merger GELU), `ApplyRotaryEmb` (2D rotary), `SliceCols` (fused-QKV
+   split) — plus host-side pos-embed/rotary precompute (grid-only, bit-exact).
+4. **A real bug surfaced during validation:** `WGSL_GELU` returned NaN for large
+   args on Metal/Dawn (`x³` overflow into fast-math `tanh`); fixed by clamping the
+   inner arg to ±15.
+
+**Net: vision is done at the encoder level.** Remaining work is **LM-side
+integration** (M-RoPE, image-token splice into the text stream, pixel→patch
+preprocessing) — phase 2, bounded plumbing over a verified numerical core. The
+ViT prefill runs through the same parallel attention as text, so there is no
+separate mobile attention risk; on-device ViT speed is a measure-when-integrated
+item, not a feasibility gate.
+
+## 6. Build sequence (ordered)
+
+1. ~~**Native embeddings**~~ — **DONE.** Qwen3-Embedding-0.6B (`Qwen3ForCausalLM`): last-token EOS pooling + `L2Norm` tail. Validated: dim 1024, unit norm, cos(similar)=0.81 > cos(unrelated)=0.56. Confirmed causal-LM-pooling. `engine.embed()`.
+2. ~~**OPFS model cache**~~ — **resolved differently: OPFS removed.** Main-thread OPFS `createWritable` is broken on iOS (leaves unclearable junk that fills the quota). The loader is now **Cache-API-only**. Durable iOS caching needs a PWA (§ paper 24, `docs/research/ios-safari-model-caching.md`), not OPFS.
+3. ~~**Native vision encoder**~~ — **DONE, bit-exact vs HF** (§5). Remaining: LM-side integration (M-RoPE, token splice, image preprocessing) — phase 2.
+4. **Vision LM integration (phase 2)** — splice `encodeImage()` tokens into the text stream: M-RoPE position assignment, placeholder-token splice, host pixel→patch preprocessing. Plumbing over a verified encoder.
+5. **Close the mobile WebKit correctness/perf sweep** — `?group=N` + Test-R bisect on real iOS 26.5 for a stable fast-and-correct submit config above the group=1 floor; re-measure desktop.
+6. **Llama/Mistral/Gemma graph generator** — ~90% is the existing qwen2 generator; unlocks most of the HF text zoo. Low risk, high ROI.
+7. **Remove tfjs scaffolding** — delete `chrome-backend.ts`. The engine is native-only; tfjs was temporary dev scaffolding, not a kept lane.
+8. **Audio, native (deferred, not delegated)** — TTS: **OmniVoice** (Qwen3 backbone + codec decoder — mostly the existing text path + a decoder). STT: **Moonshine** (lean encoder-decoder; raw-waveform Conv1d frontend, no log-mel Conv2d; needs a parallel CrossAttention kernel). Ship once a native small model clears the mobile bar.
+
+## 7. What NOT to build
+
+- **A second permanent engine / kept tfjs lane** — the architecture is native-only across text + vision + embeddings. tfjs is temporary scaffolding being removed, not a breadth lane.
+- **A Conv3d/unfold patch-embed kernel for the ViT** — not needed; patches arrive pre-flattened, so patch-embed is a plain MatMul + AddBias (§5).
+- **A heavyweight native TTS pipeline with custom vocoder kernels now** — audio is deferred; when it lands, OmniVoice's Qwen3 backbone reuses the text path. A thin onnxruntime-web bridge stays break-glass-only.
+- **A general Conv2d kernel / Whisper-on-native** — Moonshine's raw-waveform Conv1d avoids the log-mel Conv2d.
+- **An OPFS write path on iOS** — main-thread `createWritable` is broken; durable caching is a PWA concern, not an OPFS one.
+- **Trusting stale tok/s numbers** between 2f0cabc and the isMetalBackend fix.
+
+## 8. Open spikes (measure before committing)
+
+- ~~**Embedder pooling direction**~~ — RESOLVED: causal-LM last-token (EOS) pooling, validated.
+- ~~**Parallel non-causal attention feasibility for the ViT**~~ — RESOLVED: the live attention kernel was already parallel; non-causal is a one-line `is_causal` flag; the encoder is bit-exact. Remaining ViT spike: **on-device ViT prefill speed on a real iPad** (measure when LM-integration lands; not a feasibility gate).
+- **Mobile WebKit submit config** — does `?group=N`/Test-R land a stable fast config above the group=1 floor on iOS 26.5? The critical path.
+- **Vision LM-integration correctness** — M-RoPE + token splice must stay bit-exact end-to-end (image+text), not just at the encoder boundary.
+- **Native audio on mobile** — OmniVoice (codec-decoder) and Moonshine (CrossAttention kernel) latency/correctness once a candidate is validated.
+- **Autoresearch on-device tax** — desktop kernel wins did NOT transfer to mobile (41 vs 51); the loop needs a mobile-validation leg, possibly per-backend tunings.
+
+## 9. Decision log (this cycle)
+
+- Mobile native inference fixed (four-bug diagnosis: jetsam memory, WebKit visibility, attention race, detection predicate). See `docs/mobile-failure-diagnosis.md`, paper §17–19.
+- Desktop 145→~207 via autoresearch (paper §20).
+- **Architecture decision: NATIVE-ONLY** across text + vision + embeddings; no tfjs fallback lane; `chrome-backend.ts` to be deleted (paper §23).
+- **Native embeddings shipped** — Qwen3-Embedding-0.6B, last-token EOS pool + L2Norm, validated (paper §21).
+- **Native vision encoder shipped** — Qwen3.5 ViT, bit-exact vs HF transformers 5.12 (cosine 1.000000); LM-integration is phase 2 (paper §22). Supersedes the earlier "skip the ViT" stance (`docs/research/qwen35-multimodal.md`).
+- **Vision feasibility corrected** — attention was already parallel (panel read a dead `.wgsl` file); non-causal is a one-line flag (paper §22–23, §5 above).
+- **OPFS removed** — main-thread `createWritable` broken on iOS; Cache-API-only loader; durable caching needs a PWA (`docs/research/ios-safari-model-caching.md`, paper §24).
+- Modality model picks (`docs/research/sota-modality-models.md`); chromium decision (`docs/research/native-vs-chromium-decision.md`); site update plan (`docs/site-update-plan.md`).
+
+---
+
+## 10. 2026-06-13 evening — multimodal milestone + in-flight work (CAPTURE)
+
+**Major wins this session (all committed to `feat/webgpu-engine-mobile`):**
+
+- **Native VISION end-to-end DONE & validated bit-exact** (commit `5fed12b`). `engine.describeImage({pixels,width,height})` → coherent description. Validated vs HF transformers 5.12 on `examples/skelly.png`: 7/7 checks — encoder cosine 1.000000, M-RoPE 3D position ids EXACT, spliced embeds cosine 1.0, first-token exact, full greedy description WORD-IDENTICAL to HF for 201 chars ("This is a detailed black-and-white line drawing of the skeleton of a fox…"). New ops: `MRoPE`, `EmbedSplice`, host image preprocessing (smart-resize/normalize/patchify in `vision-preprocess.ts`). Text path unchanged (M-RoPE on linear positions reduces to 1D RoPE).
+- **Native EMBEDDINGS** (earlier commit): Qwen3-Embedding-0.6B works on DESKTOP (cosine 0.81>0.56). BUT **not iPad-viable** — only BF16 (~1.2GB, OOMs on-device) or a broken MLX-DWQ. → Pivot below.
+- **`is_causal` flag** on f32 attention (from vision) now unlocks **bidirectional encoders**.
+
+**The 51-vs-41 mobile throughput question — RESOLVED: NOT a regression.** t15 hit 51.7 on a 200-token sustained run; the 38-41 readings were 60-token runs (more warmup overhead/token). A fresh 200-token sustained run on the CURRENT (post-autoresearch-optimization) engine **hit ~51 again**. So the Dawn-tuned wins did NOT regress mobile; sustained mobile decode is ~51 tok/s. Lesson: benchmark with enough tokens (≥200) to be representative.
+
+**IN-FLIGHT / NOT YET MERGED (future-me: merge these):**
+- **LFM2.5-350M** — ✅ **LANDED** on `feat/webgpu-engine-mobile` (commit `3c4bac8`). Tier-1, no new kernels. **~600 tok/s desktop (2.8× Qwen3.5's ~213), ~199MB q4 (half Qwen), coherent, bit-exact vs NumPy ref.** Files: new `src/gpu/architectures/lfm2.ts` (824 lines), registered `Lfm2ForCausalLM`, LFM2 CANONICAL_KEYS, loader key-mapper. TWO GENERAL FIXES worth keeping: (1) effective FF dim is 4608 not config's 6656 (`block_auto_adjust_ff_dim` rounding — `multiple_of(⌊2/3·6656⌋)`); (2) **the "garbage output" was the CHAT TEMPLATE, not the graph** — LFM2.5 ships its template as a `chat_template.jinja` sidecar (absent from tokenizer_config.json), so the engine fell back to Qwen ChatML which auto-injects an empty `<think>` → newline loop. Fix: fetch the `.jinja` sidecar + gate think-injection on the template actually emitting `<think>`. This fix helps ANY model with a jinja sidecar. Verdict: LFM2.5 is a viable faster/smaller text-default alternative to Qwen — user picks.
+- **EmbeddingGemma-300M** — ✅ **LANDED + CONFIRMED ON iPad** (commit `4874d01`, see §11). The iPad-ready embedding model (~173MB q4, MTEB 68.36, standard MLX-4bit). Bidirectional Gemma3 encoder — needs the new generator + a MeanPool kernel + dual-theta RoPE + 2 Dense head layers + the MLX-detection loader fix (research found: detector requires `mode:"affine"` but standard MLX converts omit it → silently fall to F32; and DWQ vs standard MLX are config-indistinguishable → the DWQ-garbage trap). See `docs/research/sota-embedding-models.md`.
+
+**iPad harness:** dashboard at `https://<lan-ip>:8766/` with Text/Vision/transformers.js/Storage-probe/Clear-cache/Stop-queue buttons, live results table, `/results` + `/enqueue` + `/clear-queue` endpoints. Embeddings button removed until EmbeddingGemma lands. TODO: show generated text in the results + default Text benchmark to 200 tokens (representative); wire the Vision button to `describeImage` (needs browser ImageBitmap/Canvas→pixels decode).
+
+**iOS caching:** OPFS removed (main-thread createWritable broken on iOS, left unclearable junk). Durable cache needs a PWA (persist() only granted when installed). See `docs/research/ios-safari-model-caching.md`. Deferred.
+
+**Native modality scorecard (as of §10):** text ✅, vision ✅ (end-to-end bit-exact), embeddings ✅ desktop / iPad-pending (EmbeddingGemma building), LFM2.5 text-alt ✅ (pending merge). Audio (TTS/STT) deferred to native OmniVoice/Moonshine. **The native-only multimodal engine is real.** **→ All "pending/building" items above have since landed; see §11.**
+
+---
+
+## 11. 2026-06-14 — EmbeddingGemma on-device, LFM2.5 landed, loader hardening (CAPTURE)
+
+The §10 in-flight items all landed on `feat/webgpu-engine-mobile`. New wins this session
+(paper §25–§30 document each in depth):
+
+- **EmbeddingGemma-300M LANDED and CONFIRMED RUNNING ON iPad Safari** (commit `4874d01`).
+  First **non-Qwen** embedding family — a real **bidirectional Gemma3 encoder**
+  (`src/gpu/architectures/gemma3_encoder.ts`, `generateGemma3EncoderGraph`): 24 pre-norm
+  blocks, GQA 3q/1kv head_dim 256, per-head q/k-norm, **dual-theta RoPE** (sliding θ=10000
+  / full θ=1e6 selected per layer from `layer_types`), GeGLU MLP, Gemma's **four-norm
+  sandwich**, embed ×√768, tail **MeanPool → Dense0(768→3072) → Dense1(3072→768) → L2Norm**.
+  **173 MB at MLX-4bit** (vs the abandoned 1.2 GB Qwen3-Embedding that OOM'd iPad).
+  Two new kernels only: **MeanPool**, **Scale** (`kernels/registry.ts`). Validated
+  **cos=1.00000 vs an independent NumPy reference** (`scripts/engine/test-embedding-gemma-reference.py`),
+  reference gate `cos>0.95`; semantic test asserts a Red-Planet query is closer to two
+  Mars docs than to a bread doc by **>0.1 cosine margin**, unit-norm dim-768, no NaN. The
+  engine **generalizes across embedding families**, not just Qwen.
+
+- **SPM tokenizer fix (load-bearing, cross-family)** (`src/gpu/tokenizer.ts`). Gemma's
+  `tokenizer.json` is `type:"BPE"` but **SentencePiece-flavored** (▁/U+2581 spaces, raw
+  UTF-8 tokens, array-form merges, `<0xHH>` byte-fallback). The byte-level (`Ġ`) BPE path
+  was char-splitting every word → semantically dead embeddings that still passed norm/NaN
+  checks. Auto-detected `spmMode` (structural: `" "→"▁"` Replace normalizer **or**
+  `byte_fallback && "▁the" in vocab`) now drives encode/decode/merges; **Qwen/LFM2 stay
+  byte-level** (no model-name list — they just don't match). Lesson: `type:"BPE"` ≠
+  byte-level BPE; any SentencePiece-lineage family (Gemma/Llama/Mistral) needs this path.
+
+- **MLX-4bit loader hardened** (`src/gpu/model-loader.ts`). (1) Detection broadened to
+  accept mode-less `{bits:4, group_size}` configs (standard mlx-lm omits `mode`). (2) A
+  `VERIFIED_MLX_REPOS` allowlist (currently `mlx-community/embeddinggemma-300m-4bit`) gates
+  mode-less configs. (3) **Explicit DWQ reject** — DWQ repos carry an identical
+  `{bits:4,group_size}` config but pack weights that dequant to garbage, so they're rejected
+  by repo-name substring (`includes("dwq")`). Codifies the MLX-DWQ-garbage trap. (4) Gemma's
+  `(1+weight)` RMSNorm absorption is **baked by the loader even for MLX** (mlx-lm pre-absorbs
+  +1 for Qwen3.5 but NOT for Gemma — the Gemma branch deliberately omits `&& !isMLX`).
+
+- **Progress-reporting fix** (commit `682a09b`, `model-loader.ts`). The bar froze at
+  "10% discovering weight files" because the gap between that emit and the first download
+  chunk (index probe + 2 header range-requests + first-byte latency) emitted nothing. Now
+  emits "Reading {file} header" + "Downloading {file} (0/{N} MB)" up front. **Affected every
+  model**; fixed universally.
+
+- **LFM2.5-350M landed** (commit `3c4bac8`) — Tier-1, no new kernels, ~600 tok/s desktop /
+  ~46 tok/s mobile, ~199 MB q4. The general jinja-sidecar chat-template fix from it helps any
+  model shipping `chat_template.jinja`.
+
+- **Cross-device multi-modal parity.** Text (Qwen3.5 ~51 tok/s, LFM2.5 ~46 tok/s), vision
+  (Qwen3.5 ViT `describeImage`), and embeddings (EmbeddingGemma) **all now run natively on
+  iPad Safari** — the native engine reaches transformers.js-path modality coverage on the
+  modalities that matter, without the mobile crashes and ~5× faster. **Remaining native gap:
+  audio** — TTS via OmniVoice (in progress), STT via Moonshine (not started).
+
+- **Effort-tier shift.** Adding a new TEXT family is now usually **Tier-1: generator only, no
+  new kernels** — the kernel library has saturated for standard transformers (Llama/Mistral/
+  Gemma-text reuse existing ops). New kernels are needed only for genuinely novel ops (SSM,
+  PLE, new norms, cross-attention). See `docs/adding-a-model-family.md`.
+
+- **Site migration assessment** written: `docs/gerbil-site-native-migration.md` (how the
+  marketing/docs site can move its in-browser inference from the transformers.js/ONNX worker
+  to the native engine, modality-by-modality, with the no-fallback device-coverage tradeoff
+  stated plainly). Assessment only — the site repo was not modified.
+
+---
+
+## 12. 2026-06-14 — native audio begins, Gemma 4, memory/RAG, autoresearch campaign (CAPTURE)
+
+This session pushed past the §11 "multimodal parity minus audio" milestone. Paper
+**§31–§35** document each in depth. The decided order from §6 (audio last, native not
+delegated) held — and audio is now *under way natively*, not deferred to tfjs.
+
+- **Native STT — Moonshine LANDED** (`src/gpu/architectures/moonshine.ts`,
+  `moonshine-executor.ts`, `moonshine-stt.ts`; paper §31). Chosen over Whisper to avoid
+  a log-mel/Conv2d front-end: it consumes **16 kHz PCM directly** through three strided
+  `Conv1d`s (downsample 384×, ~41.6 frames/s) — new kernels `Conv1dFull`, `GroupNorm`,
+  `Tanh`, `Transpose`. The real new attention primitive is **`CrossAttention`**
+  (`WGSL_CROSS_ATTENTION`, tiled online-softmax), validated **bit-exact vs NumPy**
+  (`test-crossattention.mjs`: max|err|<2e-4, cos≥0.9999). Runtime is a **dual graph**:
+  `MoonshineEncoderExecutor.encode()` runs the front-end + bidirectional encoder once and
+  freezes per-decoder-layer K/V; `MoonshineSTT.transcribe()` runs greedy AR decode with
+  self- + cross-attention into that frozen K/V. **Interleaved RoPE** (`ROPE_INTERLEAVED_SPEC`,
+  adjacent-dim pairing) vs the default split-half. Validation: encoder cos≈0.990 vs HF
+  (source comment); `test-moonshine-transcribe.mjs` asserts transcript contains HF-ref
+  substrings; RTF/4-bit size are computed-and-reported, not hardcoded-asserted.
+  **Whisper(ONNX) stays the multilingual / no-WebGPU fallback** (`src/core/stt.ts`,
+  `WhisperSTT`) — separate, untouched.
+
+- **Native TTS — Kani-TTS-2 (partial)** (`src/gpu/architectures/kani_tts.ts`; paper §32).
+  The hard novel piece — the **NanoCodec decoder** (FSQ 4×4 levels `[9,8,8,7]`, mixed-radix
+  base `[1,9,72,576]` + causal HiFi-GAN, rates `[7,7,6,3,2]`, hop 1764 @ 22050 Hz) — is
+  **implemented and validated bit-exact** (`test-nanocodec-decode.mjs`, gate `err<1e-3`,
+  measured ~4.2e-6 vs MLX). New kernels: `FSQDequant`, `HalfSnake1d`,
+  `ConvTranspose1dDepthwise`. The backbone is **LFM2-350M** (`KaniTTS2ForCausalLM`, audio
+  tokens above the text vocab, 4/frame); `generateKaniTtsGraph` **deliberately throws** —
+  remaining is the frame-position + learnable-RoPE + 4-token-frame AR-decode glue (most
+  block math reused from `lfm2.ts`). License: **kani-tts-2-en = LFM1.0 (other)**, NanoCodec
+  = NVIDIA OML; the **450m variant is Apache** (same arch).
+
+- **Gemma 4 E2B — text decode COHERENT on real q4 weights** (`src/gpu/architectures/gemma4.ts`;
+  paper §33). **Tier-2**, no MatFormer/AltUp/LAuReL. **PLE** (2nd embedding gathered per
+  token, per-layer gate+GELU+multiply+project+norm+residual), **KV-cache sharing** (E2B: 35
+  layers, last **20** shared via graph-rewire, no kernel change), **proportional RoPE**
+  (rotate 0.25·head_dim=64 dims but inv_freq over full head_dim denom; dual-theta 1e6/1e4),
+  **GeGLU**, and a new **`Softcap`** kernel (`cap·tanh(x/cap)`, cap=30) on final logits.
+  Generates coherently ("The capital of France is" → "Paris") at ~83 tok/s; all 35 layers
+  match an MLX-LM reference cos≥0.998 with identical argmax (`test-gemma4-perlayer.mjs`).
+  Structural validation **67/67** (`test-gemma4-graph.mjs`; 942 nodes); softcap kernel
+  separately validated (`test-gemma4-softcap.mjs`, max err<1e-4). **PLE is CPU-streamed, not
+  GPU-sharded**: the ~1.17 GB q4 PLE table stays CPU-resident (**0 MB GPU**) and the executor
+  streams per-token rows each step — Gemma 4's intended flash design, mobile-viable, and it
+  sidesteps the per-binding cap. Coherence required four fixes: per-node `attn_scale`=1.0
+  (HF scaling=1.0; default 1/√head_dim keeps other models byte-identical), parameter-free
+  V-norm, double-wide MLP on the KV-shared layers, and head_dim-512 support in the flash
+  attention kernel (second per-thread accumulator + smem-capped tiling, 16 KB invariant kept).
+
+- **On-device Memory / RAG SHIPPED** (`src/memory/`, `@tryhamster/gerbil/memory`; paper §34).
+  Pluggable vector store (`InMemoryStore` / `IndexedDBStore` / `FileStore`), token-budgeted
+  `recall()` (default 1024-token greedy pack, ~4-chars/token, returns `{context, records,
+  tokensUsed}`), overlapping-window chunking (1000/200), write-time redaction (regex →
+  `[REDACTED]` or fn), and a `createGerbilEmbedder()` adapter over **native EmbeddingGemma**.
+  **12/12 tests** (`src/memory/memory.test.ts`). No new kernels — a clean consumer of the
+  embedding modality.
+
+- **Autoresearch TPS campaign — 3 more batches** (`scripts/engine/results.jsonl`,
+  `scripts/engine/chart.html`; paper §35), M4 Max / node-dawn. Verified peaks:
+  **Qwen3.5-0.8B 219→~234 tok/s**, **LFM2.5-350M 624→~672 tok/s**, **ViT encode
+  581.8→~502 ms (−~14%)**, **`describeImage` 37.0→42.0 tok/s (+13.5%)** — all kept changes
+  bit-exact (merged cos 1.0, e2e 7/7). **The winning lesson (sharpened):** desktop wins come
+  only from eliminating **large wide reads on poorly-occupied kernels** (fused conv+activation,
+  vec4 + register-blocked + f16-mixed ViT matmul, `MatMul+AddBias→MatMulBias`); **pure
+  dispatch-count cuts on already-tuned kernels are noise** (butterfly reduce, subgroup
+  shuffle, bigger N-tiles all reverted). The INT4 matmuls and Mamba SSM sit at the
+  **bandwidth floor** — the remaining headroom is **mobile**, not desktop (several
+  reverted-on-desktop fusions are *predicted mobile wins*; the loop's next leg is a
+  mobile-validation pass).
+
+- **gerbil-site is LIVE on the native engine.** The marketing/docs site's in-browser
+  inference now runs on the native WGSL engine (no longer the transformers.js/ONNX worker)
+  for the migrated modalities — see `docs/gerbil-site-native-migration.md`. (The §11 entry
+  was an assessment-only; this cycle it went live.)
+
+**Native modality scorecard (as of §12):** text ✅ (Qwen3.5, LFM2.5), text-alt families 🟢
+Tier-1, Gemma 4 E2B 🟡 (decode validated, sharding gates real weights), vision ✅ (Qwen3.5
+ViT, on iPad), embeddings ✅ (EmbeddingGemma, on iPad), **STT ✅ native (Moonshine) + Whisper
+fallback**, **TTS 🟡 (Kani NanoCodec decoder validated, backbone AR loop pending)**, memory/RAG
+✅ shipped. **Audio is no longer the deferred gap — STT is native; TTS is one AR-loop away.**