@xylabs/aries 0.1.1

package/dist/actions/hash/compareHashes.mjs

@@ -0,0 +1,823 @@
+// src/actions/hash/algorithms/blockhash.ts
+import imghash from "imghash";
+
+// src/actions/hash/lib/hamming.ts
+function popcount8(byte) {
+  let count = 0;
+  let value = byte & 255;
+  while (value !== 0) {
+    count += value & 1;
+    value >>>= 1;
+  }
+  return count;
+}
+function hammingHex(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(`Hash length mismatch: ${a.length} vs ${b.length}`);
+  }
+  if (a.length % 2 !== 0) {
+    throw new Error(`Hash hex length must be even, got ${a.length}`);
+  }
+  let dist = 0;
+  for (let i = 0; i < a.length; i += 2) {
+    const xa = Number.parseInt(a.slice(i, i + 2), 16);
+    const xb = Number.parseInt(b.slice(i, i + 2), 16);
+    if (Number.isNaN(xa) || Number.isNaN(xb)) {
+      throw new TypeError(`Invalid hex at position ${i}: '${a.slice(i, i + 2)}' / '${b.slice(i, i + 2)}'`);
+    }
+    dist += popcount8(xa ^ xb);
+  }
+  return dist;
+}
+function popcount32(value) {
+  let v = Math.trunc(value);
+  v = v - (v >>> 1 & 1431655765);
+  v = (v & 858993459) + (v >>> 2 & 858993459);
+  v = v + (v >>> 4) & 252645135;
+  return v * 16843009 >>> 24 & 255;
+}
+
+// src/actions/hash/algorithms/blockhash.ts
+var { hash: imghashFn } = imghash;
+var blockhashAlgorithm = {
+  name: "blockhash",
+  family: "perceptual-image",
+  inputType: "image",
+  async hash(input) {
+    if (input.path !== void 0) {
+      return await imghashFn(input.path, 8, "hex");
+    }
+    if (input.bytes !== void 0) {
+      return await imghashFn(input.bytes, 8, "hex");
+    }
+    throw new Error("blockhash requires bytes or a path.");
+  },
+  async compare(a, b) {
+    const dist = hammingHex(a, b);
+    const bits = a.length / 2 * 8;
+    return {
+      distance: dist,
+      similarity: 1 - dist / bits,
+      metric: `hamming-${bits}`
+    };
+  }
+};
+
+// src/actions/hash/lib/runBinary.ts
+import { spawn } from "child_process";
+async function runBinary(options) {
+  const maxBytes = options.maxBytes ?? 64 * 1024 * 1024;
+  return await new Promise((resolve, reject) => {
+    const child = spawn(options.binary, [...options.args ?? []], { stdio: ["pipe", "pipe", "pipe"] });
+    const stdoutChunks = [];
+    let stdoutBytes = 0;
+    let stderr = "";
+    let killedForOverflow = false;
+    child.stdout.on("data", (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > maxBytes) {
+        if (!killedForOverflow) {
+          killedForOverflow = true;
+          child.kill("SIGKILL");
+        }
+        return;
+      }
+      stdoutChunks.push(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", (err) => reject(err));
+    child.on("close", (code) => {
+      if (killedForOverflow) {
+        reject(new Error(`${options.binary} stdout exceeded ${maxBytes} bytes`));
+        return;
+      }
+      const exitCode = code ?? -1;
+      const stdout = Buffer.concat(stdoutChunks);
+      if (exitCode !== 0) {
+        const tail = stderr.trim().split(/\r?\n/).slice(-3).join("\n");
+        reject(new Error(`${options.binary} exited ${exitCode}${tail.length > 0 ? `: ${tail}` : ""}`));
+        return;
+      }
+      resolve({
+        stdout,
+        stderr,
+        exitCode
+      });
+    });
+    if (options.stdin === void 0) {
+      child.stdin.end();
+    } else {
+      child.stdin.end(options.stdin);
+    }
+  });
+}
+
+// src/actions/hash/lib/which.ts
+import { spawn as spawn2 } from "child_process";
+async function which(binary) {
+  return await new Promise((resolve) => {
+    const cmd = process.platform === "win32" ? "where" : "command";
+    const args = process.platform === "win32" ? [binary] : ["-v", binary];
+    const child = spawn2(cmd, args, { shell: process.platform !== "win32" });
+    let stdout = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.on("error", () => resolve(null));
+    child.on("close", (code) => {
+      if (code === 0) {
+        const path = stdout.split(/\r?\n/).find((line) => line.trim().length > 0)?.trim() ?? null;
+        resolve(path);
+      } else {
+        resolve(null);
+      }
+    });
+  });
+}
+async function requireBinary(req) {
+  const path = await which(req.binary);
+  if (path !== null) return path;
+  const lines = [`${req.binary} binary not found on PATH. Install with:`];
+  if (req.install.brew !== void 0) lines.push(`  macOS:   brew install ${req.install.brew}`);
+  if (req.install.apt !== void 0) lines.push(`  Debian:  apt install ${req.install.apt}`);
+  if (req.install.choco !== void 0) lines.push(`  Windows: choco install ${req.install.choco}`);
+  throw new Error(lines.join("\n"));
+}
+
+// src/actions/hash/lib/withTempfile.ts
+import { randomBytes } from "crypto";
+import { rm, writeFile } from "fs/promises";
+import OS from "os";
+import PATH from "path";
+async function withTempfile(bytes, extension, fn) {
+  const ext = extension !== void 0 && extension.length > 0 ? `.${extension}` : "";
+  const path = PATH.join(OS.tmpdir(), `aries-hash-${randomBytes(8).toString("hex")}${ext}`);
+  await writeFile(path, bytes);
+  try {
+    return await fn(path);
+  } finally {
+    await rm(path, { force: true });
+  }
+}
+
+// src/actions/hash/algorithms/chromaprint.ts
+var FPCALC_BIN = {
+  binary: "fpcalc",
+  install: {
+    brew: "chromaprint",
+    apt: "libchromaprint-tools",
+    choco: "chromaprint"
+  }
+};
+async function runFpcalc(path) {
+  await requireBinary(FPCALC_BIN);
+  const { stdout } = await runBinary({ binary: "fpcalc", args: ["-raw", "-json", path] });
+  const parsed = JSON.parse(stdout.toString("utf8"));
+  if (typeof parsed.duration !== "number" || !Array.isArray(parsed.fingerprint)) {
+    throw new TypeError("fpcalc returned unexpected JSON shape.");
+  }
+  return {
+    algorithm: "chromaprint",
+    duration: parsed.duration,
+    fingerprint: parsed.fingerprint
+  };
+}
+function parseChromaprintHash(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("chromaprint hash must be a JSON document produced by `aries hash --algorithm chromaprint`.");
+  }
+  const obj = parsed;
+  if (obj.algorithm !== "chromaprint" || typeof obj.duration !== "number" || !Array.isArray(obj.fingerprint)) {
+    throw new Error("chromaprint hash JSON missing required fields (algorithm, duration, fingerprint).");
+  }
+  return obj;
+}
+function compareFingerprints(a, b) {
+  if (a.length === 0 || b.length === 0) {
+    return {
+      similarity: 0,
+      distance: Number.NaN,
+      offset: 0
+    };
+  }
+  const span = Math.min(a.length, b.length);
+  const maxOffset = Math.max(a.length, b.length) - span;
+  let best = {
+    similarity: 0,
+    distance: 32 * span,
+    offset: 0
+  };
+  for (let offset = -maxOffset; offset <= maxOffset; offset++) {
+    const aStart = Math.max(0, -offset);
+    const bStart = Math.max(0, offset);
+    const overlap = Math.min(a.length - aStart, b.length - bStart);
+    if (overlap < Math.max(8, span / 4)) continue;
+    let bits = 0;
+    for (let i = 0; i < overlap; i++) {
+      bits += popcount32(a[aStart + i] ^ b[bStart + i]);
+    }
+    const similarity = 1 - bits / (32 * overlap);
+    if (similarity > best.similarity) {
+      best = {
+        similarity,
+        distance: bits,
+        offset
+      };
+    }
+  }
+  return best;
+}
+var chromaprintAlgorithm = {
+  name: "chromaprint",
+  family: "audio",
+  inputType: "audio",
+  requires: [FPCALC_BIN],
+  async hash(input) {
+    const fp = input.path === void 0 ? input.bytes === void 0 ? null : await withTempfile(input.bytes, "audio.bin", async (path) => await runFpcalc(path)) : await runFpcalc(input.path);
+    if (fp === null) {
+      throw new Error("chromaprint requires bytes or a path.");
+    }
+    return JSON.stringify(fp);
+  },
+  async compare(a, b) {
+    const fpA = parseChromaprintHash(a);
+    const fpB = parseChromaprintHash(b);
+    const result = compareFingerprints(fpA.fingerprint, fpB.fingerprint);
+    return {
+      similarity: result.similarity,
+      distance: Number.isFinite(result.distance) ? result.distance : void 0,
+      metric: "chromaprint-windowed-hamming"
+    };
+  }
+};
+
+// src/actions/hash/algorithms/dhash.ts
+import { readFile } from "fs/promises";
+import sharp from "sharp";
+var dhashAlgorithm = {
+  name: "dhash",
+  family: "perceptual-image",
+  inputType: "image",
+  async hash(input) {
+    const source = input.bytes ?? (input.path === void 0 ? void 0 : await readFile(input.path));
+    if (source === void 0) {
+      throw new Error("dhash requires bytes or a path.");
+    }
+    const raw = await sharp(source).resize(9, 8, { fit: "fill" }).grayscale().raw().toBuffer();
+    if (raw.length !== 9 * 8) {
+      throw new Error(`dhash unexpected raw buffer length ${raw.length}`);
+    }
+    let bits = "";
+    for (let row = 0; row < 8; row++) {
+      for (let col = 0; col < 8; col++) {
+        const left = raw[row * 9 + col];
+        const right = raw[row * 9 + col + 1];
+        bits += left > right ? "1" : "0";
+      }
+    }
+    let hex = "";
+    for (let i = 0; i < bits.length; i += 4) {
+      hex += Number.parseInt(bits.slice(i, i + 4), 2).toString(16);
+    }
+    return hex;
+  },
+  async compare(a, b) {
+    const dist = hammingHex(a, b);
+    const bits = a.length / 2 * 8;
+    return {
+      distance: dist,
+      similarity: 1 - dist / bits,
+      metric: `hamming-${bits}`
+    };
+  }
+};
+
+// src/actions/hash/algorithms/nilsimsa.ts
+import { Nilsimsa } from "nilsimsa";
+var nilsimsaAlgorithm = {
+  name: "nilsimsa",
+  family: "fuzzy-byte",
+  inputType: "bytes",
+  async hash(input) {
+    if (input.bytes === void 0) {
+      throw new Error("nilsimsa requires loaded bytes.");
+    }
+    const n = new Nilsimsa(input.bytes);
+    return n.digest("hex");
+  },
+  async compare(a, b) {
+    const raw = Nilsimsa.compare(a, b, "hex");
+    const similarity = Math.max(0, Math.min(1, (raw + 128) / 256));
+    return {
+      distance: 128 - raw,
+      similarity,
+      metric: "nilsimsa-score"
+    };
+  }
+};
+
+// src/actions/hash/algorithms/pdq.ts
+import { createRequire } from "module";
+import sharp2 from "sharp";
+var require2 = createRequire(import.meta.url);
+var { PDQ } = require2("pdq-wasm");
+var initialized = false;
+async function ensureInit() {
+  if (initialized) return;
+  await PDQ.init();
+  initialized = true;
+}
+async function toRgbRaw(source) {
+  const { data, info } = await sharp2(source).removeAlpha().raw().toBuffer({ resolveWithObject: true });
+  return {
+    data: new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
+    width: info.width,
+    height: info.height
+  };
+}
+var pdqAlgorithm = {
+  name: "pdq",
+  family: "perceptual-image",
+  inputType: "image",
+  async hash(input) {
+    const source = input.path ?? input.bytes;
+    if (source === void 0) {
+      throw new Error("pdq requires bytes or a path.");
+    }
+    await ensureInit();
+    const rgb = await toRgbRaw(source);
+    const result = PDQ.hash({
+      data: rgb.data,
+      width: rgb.width,
+      height: rgb.height,
+      channels: 3
+    });
+    return PDQ.toHex(result.hash);
+  },
+  async compare(a, b) {
+    const dist = hammingHex(a, b);
+    const bits = a.length / 2 * 8;
+    return {
+      distance: dist,
+      similarity: 1 - dist / bits,
+      metric: `hamming-${bits}`
+    };
+  }
+};
+
+// src/actions/hash/algorithms/phash.ts
+import phashLib from "sharp-phash";
+var phash = phashLib;
+function binaryToHex(bin) {
+  if (!/^[01]+$/.test(bin)) {
+    throw new TypeError(`phash returned unexpected output: ${bin.slice(0, 20)}\u2026`);
+  }
+  const padded = bin.padStart(Math.ceil(bin.length / 4) * 4, "0");
+  let hex = "";
+  for (let i = 0; i < padded.length; i += 4) {
+    hex += Number.parseInt(padded.slice(i, i + 4), 2).toString(16);
+  }
+  return hex;
+}
+var phashAlgorithm = {
+  name: "phash",
+  family: "perceptual-image",
+  inputType: "image",
+  async hash(input) {
+    const source = input.path ?? input.bytes;
+    if (source === void 0) {
+      throw new Error("phash requires bytes or a path.");
+    }
+    const bin = await phash(source);
+    return binaryToHex(bin);
+  },
+  async compare(a, b) {
+    const dist = hammingHex(a, b);
+    const bits = a.length / 2 * 8;
+    return {
+      distance: dist,
+      similarity: 1 - dist / bits,
+      metric: `hamming-${bits}`
+    };
+  }
+};
+
+// src/actions/hash/algorithms/sha256.ts
+import { createHash } from "crypto";
+var sha256Algorithm = {
+  name: "sha256",
+  family: "strict",
+  inputType: "bytes",
+  async hash(input) {
+    if (input.bytes === void 0) {
+      throw new Error("sha256 requires loaded bytes.");
+    }
+    return createHash("sha256").update(input.bytes).digest("hex");
+  },
+  async compare(a, b) {
+    return {
+      similarity: a === b ? 1 : 0,
+      distance: a === b ? 0 : 1,
+      metric: "exact-match"
+    };
+  }
+};
+
+// src/actions/hash/lib/levenshtein.ts
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let s1 = a;
+  let s2 = b;
+  if (s1.length < s2.length) {
+    const tmp = s1;
+    s1 = s2;
+    s2 = tmp;
+  }
+  const m = s1.length;
+  const n = s2.length;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  let curr = Array.from({ length: n + 1 }, () => 0);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    const cp1 = s1.codePointAt(i - 1);
+    for (let j = 1; j <= n; j++) {
+      const cost = cp1 === s2.codePointAt(j - 1) ? 0 : 1;
+      const del = prev[j] + 1;
+      const ins = curr[j - 1] + 1;
+      const sub = prev[j - 1] + cost;
+      curr[j] = Math.min(del, ins, sub);
+    }
+    const tmp = prev;
+    prev = curr;
+    curr = tmp;
+  }
+  return prev[n];
+}
+
+// src/actions/hash/algorithms/ssdeep.ts
+var SSDEEP_BIN = {
+  binary: "ssdeep",
+  install: {
+    brew: "ssdeep",
+    apt: "ssdeep",
+    choco: "ssdeep"
+  }
+};
+function parseSsdeepHash(raw) {
+  const cleaned = raw.replace(/,.*$/u, "").trim();
+  const parts = cleaned.split(":");
+  if (parts.length < 3) {
+    throw new Error(`Invalid ssdeep hash: ${raw}`);
+  }
+  const blockSize = Number.parseInt(parts[0], 10);
+  if (!Number.isFinite(blockSize) || blockSize <= 0) {
+    throw new Error(`Invalid ssdeep block size: ${parts[0]}`);
+  }
+  return {
+    blockSize,
+    h1: parts[1],
+    h2: parts[2]
+  };
+}
+function levenshteinSimilarity(a, b) {
+  if (a.length === 0 && b.length === 0) return 1;
+  const dist = levenshtein(a, b);
+  const maxLen = Math.max(a.length, b.length, 1);
+  return Math.max(0, 1 - dist / maxLen);
+}
+function ssdeepSimilarity(rawA, rawB) {
+  const a = parseSsdeepHash(rawA);
+  const b = parseSsdeepHash(rawB);
+  if (a.blockSize === b.blockSize) {
+    const s1 = levenshteinSimilarity(a.h1, b.h1);
+    const s2 = levenshteinSimilarity(a.h2, b.h2);
+    const similarity = Math.max(s1, s2);
+    const distance = Math.round((1 - similarity) * Math.max(a.h1.length, b.h1.length, a.h2.length, b.h2.length));
+    return { similarity, distance };
+  }
+  if (a.blockSize === b.blockSize * 2) {
+    const similarity = levenshteinSimilarity(a.h2, b.h1);
+    return { similarity, distance: Math.round((1 - similarity) * Math.max(a.h2.length, b.h1.length)) };
+  }
+  if (b.blockSize === a.blockSize * 2) {
+    const similarity = levenshteinSimilarity(a.h1, b.h2);
+    return { similarity, distance: Math.round((1 - similarity) * Math.max(a.h1.length, b.h2.length)) };
+  }
+  return { similarity: 0, distance: Number.NaN };
+}
+var ssdeepAlgorithm = {
+  name: "ssdeep",
+  family: "fuzzy-byte",
+  inputType: "bytes",
+  requires: [SSDEEP_BIN],
+  async hash(input) {
+    if (input.bytes === void 0) {
+      throw new Error("ssdeep requires loaded bytes.");
+    }
+    await requireBinary(SSDEEP_BIN);
+    const { stdout } = await runBinary({
+      binary: "ssdeep",
+      args: ["-b", "-s"],
+      stdin: input.bytes
+    });
+    const text = stdout.toString("utf8");
+    const lines = text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
+    const hashLine = lines.find((l) => !l.startsWith("ssdeep,")) ?? lines.at(-1);
+    if (hashLine === void 0) {
+      throw new Error("ssdeep produced no output.");
+    }
+    return hashLine.replace(/,.*$/u, "");
+  },
+  async compare(a, b) {
+    const { similarity, distance } = ssdeepSimilarity(a, b);
+    return {
+      similarity,
+      distance: Number.isFinite(distance) ? distance : void 0,
+      metric: "ssdeep-levenshtein"
+    };
+  }
+};
+
+// src/actions/hash/algorithms/tlsh.ts
+import tlsh from "tlsh";
+var tlshAlgorithm = {
+  name: "tlsh",
+  family: "fuzzy-byte",
+  inputType: "bytes",
+  async hash(input) {
+    if (input.bytes === void 0) {
+      throw new Error("tlsh requires loaded bytes.");
+    }
+    if (input.bytes.length < 50) {
+      throw new Error(`tlsh requires at least 50 bytes of input (got ${input.bytes.length}).`);
+    }
+    return tlsh(input.bytes.toString("binary"));
+  },
+  async compare(a, b) {
+    if (a.length !== b.length) {
+      throw new Error(`tlsh hash length mismatch: ${a.length} vs ${b.length}`);
+    }
+    const skip = a.length >= 8 ? 4 : 0;
+    const aBody = a.slice(skip);
+    const bBody = b.slice(skip);
+    const distance = hammingHex(aBody, bBody);
+    const bits = aBody.length / 2 * 8;
+    return {
+      distance,
+      similarity: 1 - distance / bits,
+      metric: "tlsh-bit-hamming"
+    };
+  }
+};
+
+// src/actions/hash/algorithms/videoFrames.ts
+import { randomBytes as randomBytes2 } from "crypto";
+import {
+  mkdtemp,
+  readdir,
+  readFile as readFile2,
+  rm as rm2
+} from "fs/promises";
+import OS2 from "os";
+import PATH2 from "path";
+var FFMPEG_BIN = {
+  binary: "ffmpeg",
+  install: {
+    brew: "ffmpeg",
+    apt: "ffmpeg",
+    choco: "ffmpeg"
+  }
+};
+var SUPPORTED_FRAME_ALGORITHMS = ["phash", "pdq"];
+var DEFAULT_FPS = 1;
+var DEFAULT_FRAME_ALGORITHM = "phash";
+async function extractFrames(videoPath, fps) {
+  await requireBinary(FFMPEG_BIN);
+  const dir = await mkdtemp(PATH2.join(OS2.tmpdir(), `aries-vframes-${randomBytes2(6).toString("hex")}-`));
+  try {
+    await runBinary({
+      binary: "ffmpeg",
+      args: [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-i",
+        videoPath,
+        "-vf",
+        `fps=${fps},scale=128:128:force_original_aspect_ratio=disable`,
+        "-q:v",
+        "5",
+        PATH2.join(dir, "frame-%05d.jpg")
+      ]
+    });
+    const entries = (await readdir(dir)).filter((name) => name.endsWith(".jpg")).toSorted();
+    const frames = await Promise.all(entries.map(async (name) => await readFile2(PATH2.join(dir, name))));
+    return { frames };
+  } finally {
+    await rm2(dir, { recursive: true, force: true });
+  }
+}
+function frameHasher(name) {
+  switch (name) {
+    case "phash": {
+      return async (bytes) => await phashAlgorithm.hash({ bytes });
+    }
+    case "pdq": {
+      return async (bytes) => await pdqAlgorithm.hash({ bytes });
+    }
+  }
+}
+async function fingerprintVideo(videoPath, fps, frameAlgorithm) {
+  const { frames } = await extractFrames(videoPath, fps);
+  const hashFrame = frameHasher(frameAlgorithm);
+  const hashes = await Promise.all(frames.map(async (frame, idx) => ({
+    t: idx / fps,
+    hash: await hashFrame(frame)
+  })));
+  return {
+    algorithm: "video-frames",
+    fps,
+    frameAlgorithm,
+    duration: frames.length / fps,
+    frames: hashes
+  };
+}
+function parseVideoFramesHash(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("video-frames hash must be JSON produced by `aries hash --algorithm video-frames`.");
+  }
+  const obj = parsed;
+  if (obj.algorithm !== "video-frames" || typeof obj.fps !== "number" || typeof obj.duration !== "number" || !Array.isArray(obj.frames)) {
+    throw new Error("video-frames hash JSON missing required fields.");
+  }
+  if (obj.frameAlgorithm === void 0) {
+    return { ...obj, frameAlgorithm: "phash" };
+  }
+  return obj;
+}
+function compareFrameSequences(a, b) {
+  const fps = Math.min(a.fps, b.fps);
+  if (a.frames.length === 0 || b.frames.length === 0) {
+    return {
+      similarity: 0,
+      distance: Number.NaN,
+      bestOffsetSeconds: 0,
+      overlapSeconds: 0
+    };
+  }
+  const minLen = Math.min(a.frames.length, b.frames.length);
+  const maxOffset = Math.max(a.frames.length, b.frames.length) - 1;
+  let best = {
+    similarity: 0,
+    distance: Number.NaN,
+    bestOffsetSeconds: 0,
+    overlapSeconds: 0
+  };
+  const minOverlap = Math.max(2, Math.floor(minLen / 4));
+  for (let offset = -maxOffset; offset <= maxOffset; offset++) {
+    const aStart = Math.max(0, -offset);
+    const bStart = Math.max(0, offset);
+    const overlap = Math.min(a.frames.length - aStart, b.frames.length - bStart);
+    if (overlap < minOverlap) continue;
+    let totalBits = 0;
+    let bitWidth = 0;
+    for (let i = 0; i < overlap; i++) {
+      const ah = a.frames[aStart + i].hash;
+      const bh = b.frames[bStart + i].hash;
+      if (ah.length !== bh.length) continue;
+      totalBits += hammingHex(ah, bh);
+      bitWidth += ah.length / 2 * 8;
+    }
+    if (bitWidth === 0) continue;
+    const similarity = 1 - totalBits / bitWidth;
+    if (similarity > best.similarity) {
+      best = {
+        similarity,
+        distance: totalBits,
+        bestOffsetSeconds: offset / fps,
+        overlapSeconds: overlap / fps
+      };
+    }
+  }
+  return best;
+}
+function parseFps(options) {
+  const raw = options?.fps;
+  if (raw === void 0) return DEFAULT_FPS;
+  const value = typeof raw === "string" ? Number.parseFloat(raw) : Number(raw);
+  if (!Number.isFinite(value) || value <= 0 || value > 60) {
+    const display = typeof raw === "string" || typeof raw === "number" ? String(raw) : "<non-scalar>";
+    throw new RangeError(`Invalid --fps ${display}: expected a number in (0, 60].`);
+  }
+  return value;
+}
+function parseFrameAlgorithm(options) {
+  const raw = options?.frameAlgorithm;
+  if (raw === void 0) return DEFAULT_FRAME_ALGORITHM;
+  if (typeof raw !== "string" || !SUPPORTED_FRAME_ALGORITHMS.includes(raw)) {
+    const display = typeof raw === "string" ? raw : `<${typeof raw}>`;
+    throw new RangeError(`Invalid --frame-algorithm ${display}: expected one of ${SUPPORTED_FRAME_ALGORITHMS.join(", ")}.`);
+  }
+  return raw;
+}
+var videoFramesAlgorithm = {
+  name: "video-frames",
+  family: "video",
+  inputType: "video",
+  requires: [FFMPEG_BIN],
+  async hash(input) {
+    const fps = parseFps(input.options);
+    const frameAlgorithm = parseFrameAlgorithm(input.options);
+    const fp = input.path === void 0 ? input.bytes === void 0 ? null : await withTempfile(input.bytes, "video.bin", async (path) => await fingerprintVideo(path, fps, frameAlgorithm)) : await fingerprintVideo(input.path, fps, frameAlgorithm);
+    if (fp === null) {
+      throw new Error("video-frames requires bytes or a path.");
+    }
+    return JSON.stringify(fp);
+  },
+  async compare(a, b) {
+    const fpA = parseVideoFramesHash(a);
+    const fpB = parseVideoFramesHash(b);
+    if (fpA.frameAlgorithm !== fpB.frameAlgorithm) {
+      throw new Error(`Cannot compare video-frames hashes with different frame algorithms (${fpA.frameAlgorithm} vs ${fpB.frameAlgorithm}).`);
+    }
+    const result = compareFrameSequences(fpA, fpB);
+    return {
+      similarity: result.similarity,
+      distance: Number.isFinite(result.distance) ? result.distance : void 0,
+      metric: `frame-sequence-${fpA.frameAlgorithm}@${fpA.fps}fps`
+    };
+  }
+};
+
+// src/actions/hash/algorithms/xyo.ts
+import { ObjectHasher } from "@xyo-network/hash";
+var xyoAlgorithm = {
+  name: "xyo",
+  family: "strict",
+  inputType: "bytes",
+  async hash(input) {
+    if (input.bytes === void 0) {
+      throw new Error("xyo requires loaded bytes.");
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(input.bytes.toString("utf8"));
+    } catch {
+      throw new Error("xyo requires valid JSON input.");
+    }
+    return await ObjectHasher.hash(parsed);
+  },
+  async compare(a, b) {
+    return {
+      similarity: a === b ? 1 : 0,
+      distance: a === b ? 0 : 1,
+      metric: "exact-match"
+    };
+  }
+};
+
+// src/actions/hash/algorithms/index.ts
+var REGISTRY = new Map([
+  sha256Algorithm,
+  xyoAlgorithm,
+  tlshAlgorithm,
+  nilsimsaAlgorithm,
+  ssdeepAlgorithm,
+  phashAlgorithm,
+  dhashAlgorithm,
+  blockhashAlgorithm,
+  pdqAlgorithm,
+  chromaprintAlgorithm,
+  videoFramesAlgorithm
+].map((algo) => [algo.name, algo]));
+function getAlgorithm(name) {
+  const algo = REGISTRY.get(name);
+  if (algo === void 0) {
+    const known = [...REGISTRY.keys()].join(", ");
+    throw new Error(`Unknown algorithm '${name}'. Known: ${known}`);
+  }
+  return algo;
+}
+
+// src/actions/hash/compareHashes.ts
+async function compareHashes(options) {
+  const algo = getAlgorithm(options.algorithm);
+  if (algo.compare === void 0) {
+    throw new Error(`Algorithm '${algo.name}' does not support comparison.`);
+  }
+  return await algo.compare(options.hashA, options.hashB);
+}
+export {
+  compareHashes
+};
+//# sourceMappingURL=compareHashes.mjs.map