@dejadex/web 0.0.0-stage → 0.1.0

package/src/identify/preprocess.ts

@@ -0,0 +1,227 @@
+/**
+ * Crop → model input, identical to the Python reference that embedded the
+ * gallery (`ml/scripts/phase0_zero_shot.py`, `preprocess`):
+ *
+ *   RGB → stretch-resize to width × height with PIL's BILINEAR filter
+ *   (antialiased when shrinking) → x / 255 → (x − mean) / std → CHW float32.
+ *
+ * The resize is a port of Pillow's `Resample.c` for 8-bit images, fixed-point
+ * coefficients and all: a horizontal pass into an 8-bit intermediate, then a
+ * vertical one. A canvas `drawImage` would resample with whatever filter the
+ * browser picks, which differs between browsers and from the gallery's.
+ *
+ * Pure functions on typed arrays: they run the same in a Worker, on the main
+ * thread and in Node (the parity tests).
+ */
+
+/** Interleaved 8-bit pixels, row-major, top row first. */
+export interface PixelImage {
+  readonly width: number
+  readonly height: number
+  /** 3 (RGB) or 4 (RGBA, as `ImageData` has; alpha is ignored). */
+  readonly channels: 3 | 4
+  readonly data: Uint8Array | Uint8ClampedArray
+}
+
+export interface Normalisation {
+  readonly mean: readonly [number, number, number]
+  readonly std: readonly [number, number, number]
+}
+
+/** Pillow: `#define PRECISION_BITS (32 - 8 - 2)`. */
+const PRECISION_BITS = 22
+const ONE_HALF = 1 << (PRECISION_BITS - 1)
+const CLIP_MAX = (1 << PRECISION_BITS) << 8
+
+interface Coeffs {
+  readonly ksize: number
+  /** Per output pixel: first input index, then how many inputs. */
+  readonly bounds: Int32Array
+  /** outSize × ksize fixed-point weights. */
+  readonly kk: Int32Array
+}
+
+const bilinear = (x: number): number => {
+  const a = x < 0 ? -x : x
+  return a < 1 ? 1 - a : 0
+}
+
+/** Pillow's `precompute_coeffs` + `normalize_coeffs_8bpc`, for the bilinear filter (support 1). */
+function precomputeCoeffs(inSize: number, outSize: number): Coeffs {
+  const scale = inSize / outSize
+  const filterscale = scale < 1 ? 1 : scale
+  const support = 1 * filterscale
+  const ksize = Math.ceil(support) * 2 + 1
+  const bounds = new Int32Array(outSize * 2)
+  const pre = new Float64Array(outSize * ksize)
+  const ss = 1 / filterscale
+  for (let xx = 0; xx < outSize; xx++) {
+    const center = (xx + 0.5) * scale
+    // C's (int) truncates toward zero.
+    let xmin = Math.trunc(center - support + 0.5)
+    if (xmin < 0) xmin = 0
+    let xmax = Math.trunc(center + support + 0.5)
+    if (xmax > inSize) xmax = inSize
+    xmax -= xmin
+    let ww = 0
+    const base = xx * ksize
+    for (let x = 0; x < xmax; x++) {
+      const w = bilinear((x + xmin - center + 0.5) * ss)
+      pre[base + x] = w
+      ww += w
+    }
+    if (ww !== 0) for (let x = 0; x < xmax; x++) pre[base + x] = (pre[base + x] as number) / ww
+    bounds[xx * 2] = xmin
+    bounds[xx * 2 + 1] = xmax
+  }
+  const kk = new Int32Array(pre.length)
+  const one = 1 << PRECISION_BITS
+  for (let i = 0; i < pre.length; i++) {
+    const v = pre[i] as number
+    kk[i] = v < 0 ? Math.trunc(-0.5 + v * one) : Math.trunc(0.5 + v * one)
+  }
+  return { ksize, bounds, kk }
+}
+
+const clip8 = (v: number): number => (v >= CLIP_MAX ? 255 : v <= 0 ? 0 : v >> PRECISION_BITS)
+
+/**
+ * Resize to `outWidth × outHeight` RGB, bit-exact with Pillow's
+ * `Image.resize((w, h), Image.Resampling.BILINEAR)` on an RGB image (no box,
+ * no `reducing_gap`). Returns 3-channel pixels.
+ */
+export function resizeBilinear(src: PixelImage, outWidth: number, outHeight: number): PixelImage {
+  const { width: inW, height: inH, channels: c, data } = src
+  if (!Number.isInteger(outWidth) || !Number.isInteger(outHeight) || outWidth <= 0 || outHeight <= 0) {
+    throw new RangeError(`bad output size ${outWidth}x${outHeight}`)
+  }
+  if (data.length < inW * inH * c) throw new RangeError('pixel buffer is shorter than width × height × channels')
+
+  // Horizontal pass, over only the rows the vertical pass will read.
+  const vert = precomputeCoeffs(inH, outHeight)
+  const needH = outWidth !== inW
+  const needV = outHeight !== inH
+  let rows: Uint8Array
+  let rowOffset = 0
+  let rowsHeight = inH
+  if (needH) {
+    const horiz = precomputeCoeffs(inW, outWidth)
+    const first = vert.bounds[0] as number
+    const last = (vert.bounds[outHeight * 2 - 2] as number) + (vert.bounds[outHeight * 2 - 1] as number)
+    rowsHeight = needV ? last - first : inH
+    rowOffset = needV ? first : 0
+    rows = new Uint8Array(outWidth * rowsHeight * 3)
+    const { ksize, bounds, kk } = horiz
+    for (let y = 0; y < rowsHeight; y++) {
+      const inRow = (y + rowOffset) * inW * c
+      const outRow = y * outWidth * 3
+      for (let xx = 0; xx < outWidth; xx++) {
+        const xmin = bounds[xx * 2] as number
+        const xmax = bounds[xx * 2 + 1] as number
+        const k = xx * ksize
+        let s0 = ONE_HALF
+        let s1 = ONE_HALF
+        let s2 = ONE_HALF
+        for (let x = 0; x < xmax; x++) {
+          const w = kk[k + x] as number
+          const p = inRow + (x + xmin) * c
+          s0 += (data[p] as number) * w
+          s1 += (data[p + 1] as number) * w
+          s2 += (data[p + 2] as number) * w
+        }
+        const o = outRow + xx * 3
+        rows[o] = clip8(s0)
+        rows[o + 1] = clip8(s1)
+        rows[o + 2] = clip8(s2)
+      }
+    }
+  } else {
+    rows = toRgb(src)
+  }
+  if (!needV) return { width: outWidth, height: outHeight, channels: 3, data: rows }
+
+  // Vertical pass. Bounds were computed against the full input height; the
+  // intermediate starts at `rowOffset`.
+  const out = new Uint8Array(outWidth * outHeight * 3)
+  const { ksize, bounds, kk } = vert
+  const stride = outWidth * 3
+  for (let yy = 0; yy < outHeight; yy++) {
+    const ymin = (bounds[yy * 2] as number) - rowOffset
+    const ymax = bounds[yy * 2 + 1] as number
+    const k = yy * ksize
+    const outRow = yy * stride
+    for (let i = 0; i < stride; i++) {
+      let s = ONE_HALF
+      for (let y = 0; y < ymax; y++) s += (rows[(y + ymin) * stride + i] as number) * (kk[k + y] as number)
+      out[outRow + i] = clip8(s)
+    }
+  }
+  return { width: outWidth, height: outHeight, channels: 3, data: out }
+}
+
+function toRgb(src: PixelImage): Uint8Array {
+  const n = src.width * src.height
+  const out = new Uint8Array(n * 3)
+  for (let i = 0; i < n; i++) {
+    out[i * 3] = src.data[i * src.channels] as number
+    out[i * 3 + 1] = src.data[i * src.channels + 1] as number
+    out[i * 3 + 2] = src.data[i * src.channels + 2] as number
+  }
+  return out
+}
+
+/** The image turned 180°. Pillow's bilinear resize commutes with it, so the SDK turns the small resized crop. */
+export function rotate180(img: PixelImage): PixelImage {
+  const c = img.channels
+  const n = img.width * img.height
+  const out = new Uint8Array(n * c)
+  for (let i = 0; i < n; i++) {
+    const src = (n - 1 - i) * c
+    for (let k = 0; k < c; k++) out[i * c + k] = img.data[src + k] as number
+  }
+  return { width: img.width, height: img.height, channels: c, data: out }
+}
+
+/**
+ * Writes the normalised CHW tensor of an RGB image into `out` at `offset`
+ * (in floats). Float32 arithmetic step by step, as numpy does it, so the
+ * values are the reference's to the last bit.
+ */
+export function writeTensor(img: PixelImage, norm: Normalisation, out: Float32Array, offset = 0): void {
+  const plane = img.width * img.height
+  if (out.length < offset + plane * 3) throw new RangeError('tensor buffer too small')
+  const f = Math.fround
+  const inv255 = f(1 / 255)
+  const c = img.channels
+  for (let ch = 0; ch < 3; ch++) {
+    const mean = f(norm.mean[ch] as number)
+    const std = f(norm.std[ch] as number)
+    const base = offset + ch * plane
+    for (let i = 0; i < plane; i++) {
+      const x = f((img.data[i * c + ch] as number) * inv255)
+      out[base + i] = f(f(x - mean) / std)
+    }
+  }
+}
+
+/** 0 and/or 180: the orientations each crop is embedded at. */
+export type Orientation = 0 | 180
+
+/**
+ * One crop → `orientations.length` consecutive CHW tensors in `out` at
+ * `offset`, ready for an NCHW batch.
+ */
+export function preprocessCrop(
+  src: PixelImage,
+  size: { readonly width: number; readonly height: number },
+  norm: Normalisation,
+  orientations: readonly Orientation[],
+  out: Float32Array,
+  offset = 0,
+): void {
+  const resized = resizeBilinear(src, size.width, size.height)
+  const plane = size.width * size.height * 3
+  orientations.forEach((deg, i) => {
+    writeTensor(deg === 180 ? rotate180(resized) : resized, norm, out, offset + i * plane)
+  })
+}

package/src/identify/router.ts

@@ -0,0 +1,115 @@
+/**
+ * Where an identification runs, and when the server route is skipped. Pure:
+ * the clock and every input are passed in, so each rule has its own test.
+ *
+ * - `local`: the device, always; nothing is ever sent.
+ * - `server`: the server first, then the device.
+ * - `auto`: the device when it is loaded and fast enough (WebGPU, or a
+ *   measured per-crop time within the budget); otherwise the server first,
+ *   then the device. A device whose model is still downloading uses the
+ *   server meanwhile.
+ *
+ * The server is skipped, straight to the device, while the browser reports
+ * itself offline; for the rest of a lease the server refused (401/403/409);
+ * until a 429's `Retry-After`; and for 30 s after three consecutive failures
+ * (timeout, network, 5xx, malformed answer).
+ */
+import type { ServerAnswer } from './server.js'
+import type { IdentificationMode } from './types.js'
+
+/** Phase 0: a mid-range phone without WebGPU took ~326 ms per crop on 4 WASM threads. */
+export const DEFAULT_SLOW_DEVICE_BUDGET_MS = 300
+export const FALLBACK_FLOOR_MS = 300
+export const FALLBACK_CAP_MS = 3_000
+/** The server's deadline while the device has nothing to fall back on yet. */
+export const DEFAULT_SERVER_TIMEOUT_MS = 8_000
+export const BREAKER_FAILURES = 3
+export const BREAKER_PAUSE_MS = 30_000
+
+export interface DeviceState {
+  readonly ready: boolean
+  readonly backend: 'webgpu' | 'wasm' | null
+  /** NaN until measured. */
+  readonly perCropMs: number
+}
+
+export type Route = 'device' | 'server'
+
+export function chooseRoute(input: {
+  readonly mode: IdentificationMode
+  readonly device: DeviceState
+  /** Why the server can't be used now, or null when it can. */
+  readonly serverBlocked: string | null
+  readonly slowDeviceBudgetMs: number
+}): Route {
+  if (input.mode === 'local' || input.serverBlocked !== null) return 'device'
+  if (input.mode === 'server') return 'server'
+  const { ready, backend, perCropMs } = input.device
+  if (ready && (backend === 'webgpu' || perCropMs <= input.slowDeviceBudgetMs)) return 'device'
+  return 'server'
+}
+
+/**
+ * How long a server attempt may take before the device takes over: the
+ * device's own time for the same crops, within [300 ms, 3 s]. With no device
+ * engine yet there is nothing faster to fall back on, so the server gets
+ * `serverTimeoutMs`.
+ */
+export function serverDeadline(device: DeviceState, crops: number, serverTimeoutMs: number): number {
+  if (!device.ready || !Number.isFinite(device.perCropMs)) return serverTimeoutMs
+  return Math.min(FALLBACK_CAP_MS, Math.max(FALLBACK_FLOOR_MS, device.perCropMs * crops))
+}
+
+/** The server route's health, per identifier. */
+export class ServerHealth {
+  private refusedLease: string | null = null
+  private refusedWhy = ''
+  private pausedUntil = 0
+  private pausedWhy = ''
+  private failures = 0
+
+  /** Why the server is skipped for `leaseId` at `now`, or null when it may be tried. */
+  blocked(leaseId: string | null, now: number, online: boolean): string | null {
+    if (!online) return 'offline'
+    if (leaseId !== null && leaseId === this.refusedLease) return `refused for this lease (${this.refusedWhy})`
+    if (now < this.pausedUntil) return `${this.pausedWhy} until ${new Date(this.pausedUntil).toISOString()}`
+    return null
+  }
+
+  record(answer: ServerAnswer, leaseId: string | null, now: number): void {
+    if (answer.ok) {
+      this.failures = 0
+      return
+    }
+    switch (answer.kind) {
+      case 'refused':
+        this.refusedLease = leaseId
+        this.refusedWhy = answer.detail
+        return
+      case 'rate_limited':
+        this.pause(now + (answer.retryAfterMs ?? 10_000), 'rate limited')
+        return
+      case 'timeout':
+      case 'network':
+      case 'server_error':
+      case 'malformed':
+        this.failures++
+        if (this.failures >= BREAKER_FAILURES) {
+          this.failures = 0
+          this.pause(now + BREAKER_PAUSE_MS, `${BREAKER_FAILURES} failures in a row`)
+        }
+        return
+      case 'aborted':
+      case 'bad_request':
+        // Neither says anything about the server's health.
+        return
+    }
+  }
+
+  private pause(until: number, why: string): void {
+    if (until > this.pausedUntil) {
+      this.pausedUntil = until
+      this.pausedWhy = why
+    }
+  }
+}

package/src/identify/runtime.ts

@@ -0,0 +1,197 @@
+/**
+ * The embedder session: which execution provider, which file, and the call
+ * that turns a batch of preprocessed crops into L2-normalised CLS embeddings.
+ *
+ * Order (web-sdk-pipeline, "Execution providers are tried in a fixed order"):
+ * WebGPU through the `onnxruntime-web/webgpu` build when `requestAdapter()`
+ * returns an adapter and the model loads on it — the fp16 file, or fp32 when
+ * the adapter lacks `shader-f16`; otherwise WASM (SIMD), with threads only when
+ * the page is cross-origin isolated (SharedArrayBuffer). int8 and q4f16 files
+ * are never listed, so never loaded.
+ */
+import type * as Ort from 'onnxruntime-web'
+import { ScannerError } from '../errors.js'
+import type { Manifest, ManifestModel, ModelPrecision } from './manifest.js'
+import { l2NormaliseRows } from './search.js'
+
+export type OrtModule = typeof Ort
+export type OrtBuild = 'webgpu' | 'wasm'
+export type BackendChoice = 'auto' | 'webgpu' | 'wasm'
+
+export interface RuntimeOptions {
+  /** Force an execution provider. Default `auto` (WebGPU when it loads, else WASM). */
+  readonly backend?: BackendChoice
+  /** Model file for WASM. Default `fp16` (half the download; fp32 is faster on WASM). */
+  readonly wasmPrecision?: ModelPrecision
+  /** Where onnxruntime-web finds its `.wasm`/`.mjs` files, e.g. `https://cdn.example/ort/`. */
+  readonly wasmPaths?: string
+  /** WASM threads when cross-origin isolated. Default min(4, hardwareConcurrency). */
+  readonly threads?: number
+}
+
+/** Test seams: everything the runtime reads from its environment. */
+export interface RuntimeEnv {
+  readonly loadOrt: (build: OrtBuild) => Promise<OrtModule>
+  readonly gpu: GpuLike | undefined
+  readonly crossOriginIsolated: boolean
+  readonly hardwareConcurrency: number
+}
+
+export interface GpuLike {
+  requestAdapter(options?: { powerPreference?: 'low-power' | 'high-performance' }): Promise<{ readonly features: { has(name: string): boolean } } | null>
+}
+
+export interface EmbedBackend {
+  readonly backend: OrtBuild
+  readonly precision: ModelPrecision
+  readonly threads: number
+  /** `n` crops' CHW tensors back to back → n × dims, L2-normalised. */
+  embed(input: Float32Array, n: number): Promise<Float32Array>
+  release(): Promise<void>
+}
+
+const ADAPTER_TIMEOUT_MS = 5_000
+
+export interface GpuProbe {
+  readonly adapter: boolean
+  readonly shaderF16: boolean
+}
+
+export async function probeWebGpu(gpu: GpuLike | undefined): Promise<GpuProbe> {
+  if (!gpu || typeof gpu.requestAdapter !== 'function') return { adapter: false, shaderF16: false }
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    // Bounded: a driver that never answers counts as no adapter.
+    const adapter = await Promise.race([
+      gpu.requestAdapter({ powerPreference: 'high-performance' }),
+      new Promise<null>((resolve) => {
+        timer = setTimeout(() => resolve(null), ADAPTER_TIMEOUT_MS)
+      }),
+    ])
+    if (!adapter) return { adapter: false, shaderF16: false }
+    return { adapter: true, shaderF16: adapter.features.has('shader-f16') }
+  } catch {
+    return { adapter: false, shaderF16: false }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export interface Plan {
+  readonly backend: OrtBuild
+  readonly model: ManifestModel
+}
+
+/** The (backend, file) pairs to try, best first. Pure, so every path is testable. */
+export function planBackends(probe: GpuProbe, models: readonly ManifestModel[], options: RuntimeOptions = {}): Plan[] {
+  const by = (p: ModelPrecision) => models.find((m) => m.precision === p)
+  const plans: Plan[] = []
+  const choice = options.backend ?? 'auto'
+  if (choice !== 'wasm' && probe.adapter) {
+    const gpuModel = probe.shaderF16 ? (by('fp16') ?? by('fp32')) : by('fp32')
+    if (gpuModel) plans.push({ backend: 'webgpu', model: gpuModel })
+  }
+  if (choice !== 'webgpu') {
+    const wanted = options.wasmPrecision ?? 'fp16'
+    const wasmModel = by(wanted) ?? by(wanted === 'fp16' ? 'fp32' : 'fp16')
+    if (wasmModel) plans.push({ backend: 'wasm', model: wasmModel })
+  }
+  return plans
+}
+
+export function wasmThreads(env: Pick<RuntimeEnv, 'crossOriginIsolated' | 'hardwareConcurrency'>, options: RuntimeOptions = {}): number {
+  if (!env.crossOriginIsolated) return 1
+  const cap = options.threads ?? 4
+  return Math.max(1, Math.min(cap, env.hardwareConcurrency || 1))
+}
+
+export function defaultRuntimeEnv(): RuntimeEnv {
+  const nav = (globalThis as { navigator?: { gpu?: GpuLike; hardwareConcurrency?: number } }).navigator
+  return {
+    // Two builds, loaded only when used: the WebGPU one carries the larger WASM.
+    loadOrt: (build) => (build === 'webgpu' ? import('onnxruntime-web/webgpu') : import('onnxruntime-web/wasm')),
+    gpu: nav?.gpu,
+    crossOriginIsolated: (globalThis as { crossOriginIsolated?: boolean }).crossOriginIsolated === true,
+    hardwareConcurrency: nav?.hardwareConcurrency ?? 1,
+  }
+}
+
+/**
+ * Opens a session on the first plan that loads. `modelBytes` fetches (and
+ * verifies) a plan's file; it is called only for the plans actually tried.
+ */
+export async function createEmbedBackend(
+  manifest: Manifest,
+  modelBytes: (model: ManifestModel) => Promise<ArrayBuffer>,
+  options: RuntimeOptions,
+  env: RuntimeEnv,
+): Promise<EmbedBackend> {
+  const probe = await probeWebGpu(options.backend === 'wasm' ? undefined : env.gpu)
+  const plans = planBackends(probe, manifest.models, options)
+  if (plans.length === 0) throw new ScannerError('UNSUPPORTED_DEVICE', 'no model file fits this device')
+  const failures: string[] = []
+  for (const plan of plans) {
+    try {
+      return await openSession(plan, manifest, await modelBytes(plan.model), options, env)
+    } catch (err) {
+      // A download or checksum failure is not the device's fault: report it as is.
+      if (err instanceof ScannerError && (err.code === 'NETWORK' || err.code === 'MODEL_INTEGRITY')) throw err
+      failures.push(`${plan.backend}/${plan.model.precision}: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+  throw new ScannerError('UNSUPPORTED_DEVICE', `no execution provider loaded the model (${failures.join('; ')})`)
+}
+
+async function openSession(plan: Plan, manifest: Manifest, bytes: ArrayBuffer, options: RuntimeOptions, env: RuntimeEnv): Promise<EmbedBackend> {
+  const ort = await env.loadOrt(plan.backend)
+  const threads = plan.backend === 'wasm' ? wasmThreads(env, options) : 1
+  ort.env.wasm.numThreads = threads
+  ort.env.wasm.proxy = false
+  if (options.wasmPaths !== undefined) ort.env.wasm.wasmPaths = options.wasmPaths
+  ort.env.logLevel = 'error'
+  if (plan.backend === 'webgpu') ort.env.webgpu.powerPreference = 'high-performance'
+
+  const session = await ort.InferenceSession.create(new Uint8Array(bytes), {
+    executionProviders: [plan.backend],
+    graphOptimizationLevel: 'all',
+  })
+  const { input, output, token } = manifest.embedding
+  if (!session.inputNames.includes(input) || !session.outputNames.includes(output)) {
+    await session.release()
+    throw new ScannerError('MODEL_INTEGRITY', `model has no ${input} → ${output}`)
+  }
+  const { width, height } = manifest.preprocessing
+  const dims = manifest.dims
+  const plane = 3 * width * height
+
+  return {
+    backend: plan.backend,
+    precision: plan.model.precision,
+    threads,
+    async embed(data, n) {
+      if (data.length < n * plane) throw new RangeError('input is shorter than n crops')
+      const tensor = new ort.Tensor('float32', data.subarray(0, n * plane), [n, 3, height, width])
+      let hidden: Ort.Tensor | undefined
+      try {
+        const out = await session.run({ [input]: tensor })
+        hidden = out[output]
+        if (!hidden) throw new ScannerError('MODEL_INTEGRITY', `model returned no ${output}`)
+        const [bn, tokens, d] = hidden.dims as readonly number[]
+        if (bn !== n || d !== dims || tokens === undefined || token >= tokens) {
+          throw new ScannerError('MODEL_INTEGRITY', `model output ${hidden.dims.join('x')} does not match the manifest`)
+        }
+        const values = (await hidden.getData()) as Float32Array
+        const result = new Float32Array(n * dims)
+        for (let i = 0; i < n; i++) {
+          const from = (i * tokens + token) * dims
+          result.set(values.subarray(from, from + dims), i * dims)
+        }
+        return l2NormaliseRows(result, dims)
+      } finally {
+        tensor.dispose()
+        hidden?.dispose()
+      }
+    },
+    release: () => session.release(),
+  }
+}

package/src/identify/search.ts

@@ -0,0 +1,115 @@
+/**
+ * Brute-force cosine top-K over a shard, and the rules that turn the ranking
+ * into an answer. Plain loops over typed arrays: no DOM, no allocation per row,
+ * the same in a Worker as anywhere else.
+ *
+ * Rows and queries are L2-normalised, so a dot product is the cosine. A crop
+ * embedded at several orientations scores each row by the best of them (the
+ * max-pool the server does).
+ */
+import type { IdentifyCandidate, IdentifyResult } from './types.js'
+
+export interface Ranked {
+  /** Row indexes, best first. */
+  readonly rows: Int32Array
+  readonly scores: Float32Array
+}
+
+/**
+ * The `k` best rows for a set of query vectors (`queries.length / dim` of
+ * them), each row scored by its best dot product with any query. Ties keep the
+ * lower row first.
+ */
+export function topK(matrix: Float32Array, dim: number, queries: Float32Array, k: number): Ranked {
+  if (!Number.isInteger(dim) || dim <= 0 || matrix.length % dim !== 0) throw new RangeError('matrix is not rows × dim')
+  if (queries.length === 0 || queries.length % dim !== 0) throw new RangeError('queries are not n × dim')
+  const rowCount = matrix.length / dim
+  const q = queries.length / dim
+  const want = Math.min(Math.max(0, Math.floor(k)), rowCount)
+  const bestRows = new Int32Array(want)
+  const bestScores = new Float32Array(want).fill(Number.NEGATIVE_INFINITY)
+  if (want === 0) return { rows: bestRows, scores: bestScores }
+  let floor = Number.NEGATIVE_INFINITY
+  let filled = 0
+
+  for (let r = 0; r < rowCount; r++) {
+    const base = r * dim
+    let score: number
+    if (q === 2) {
+      let a = 0
+      let b = 0
+      for (let i = 0; i < dim; i++) {
+        const v = matrix[base + i] as number
+        a += v * (queries[i] as number)
+        b += v * (queries[dim + i] as number)
+      }
+      score = a > b ? a : b
+    } else {
+      score = Number.NEGATIVE_INFINITY
+      for (let j = 0; j < q; j++) {
+        let s = 0
+        const qb = j * dim
+        for (let i = 0; i < dim; i++) s += (matrix[base + i] as number) * (queries[qb + i] as number)
+        if (s > score) score = s
+      }
+    }
+    if (filled === want && score <= floor) continue
+    // Insert into the sorted list; strictly greater moves up, so ties keep the earlier row.
+    let at = filled === want ? want - 1 : filled
+    while (at > 0 && score > (bestScores[at - 1] as number)) {
+      bestScores[at] = bestScores[at - 1] as number
+      bestRows[at] = bestRows[at - 1] as number
+      at--
+    }
+    bestScores[at] = score
+    bestRows[at] = r
+    if (filled < want) filled++
+    floor = bestScores[want - 1] as number
+  }
+  return { rows: bestRows, scores: bestScores }
+}
+
+/** In place: scales each `dim`-wide row of `v` to unit length (a zero row stays zero). */
+export function l2NormaliseRows(v: Float32Array, dim: number): Float32Array {
+  for (let base = 0; base < v.length; base += dim) {
+    let s = 0
+    for (let i = 0; i < dim; i++) s += (v[base + i] as number) ** 2
+    const inv = 1 / Math.max(Math.sqrt(s), 1e-12)
+    for (let i = 0; i < dim; i++) v[base + i] = (v[base + i] as number) * inv
+  }
+  return v
+}
+
+export interface Thresholds {
+  /** `kind: 'not_a_card'` when the best score is below this. */
+  readonly notACardBelow: number
+  /** `confident` when top1 − top2 ≥ this. */
+  readonly confidentMargin: number
+}
+
+/** Scores in answers carry six decimals, as the server's do. */
+const round6 = (x: number): number => Math.round(x * 1e6) / 1e6
+
+/**
+ * The answer for one crop from its ranking. `ranked` holds at least
+ * `max(top, 2)` rows where the shard has them: the margin needs a second one.
+ */
+export function toResult(index: number, ranked: Ranked, ids: readonly string[], top: number, t: Thresholds): IdentifyResult {
+  const s0 = ranked.scores[0]
+  const s1 = ranked.scores[1]
+  const notACard = s0 === undefined || s0 < t.notACardBelow
+  const margin = s0 !== undefined && s1 !== undefined ? s0 - s1 : Number.POSITIVE_INFINITY
+  const candidates: IdentifyCandidate[] = []
+  const n = Math.min(top, ranked.rows.length)
+  for (let i = 0; i < n; i++) {
+    const id = ids[ranked.rows[i] as number]
+    if (id === undefined) throw new RangeError(`row ${ranked.rows[i]} has no id`)
+    candidates.push({ cardId: id, score: round6(ranked.scores[i] as number) })
+  }
+  return {
+    index,
+    kind: notACard ? 'not_a_card' : 'card',
+    confident: !notACard && margin >= t.confidentMargin,
+    candidates,
+  }
+}