cursedbelt-core 2.0.0 → 2.1.0

package/dist/core/duplicates/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * "Are these two files the same thing?" — the fleet's ONE answer, with no I/O in it.
+ *
+ * ── Why this is here and not in an app ──────────────────────────────────────────────────
+ * `binary-server` wrote these rules first (2026-08-13, the owner: *"make strategy to always
+ * check for duplicate binaries in same app for same user … mark likely the duplicates for
+ * users to confirm"*), and they were measured against a real store: the copy-counter cap, the
+ * camera-generic stem list and the 5% size window each exist because a wider rule proposed
+ * thousands of pairs nobody could ever review. `music` then needed the same question asked of
+ * a 5,400-track library — *"I want to see a duplicate next to the file that it is a possible
+ * duplicate of … The 'binary-server' app (bs) already has this feature for checking duplicate
+ * files. We can reuse it and enhance the customizability if needed so the main strategy is
+ * shared."*
+ *
+ * So the strategy lives once, here, and both consume it. What each app keeps for itself is the
+ * evidence only it has: bs's perceptual frame hashes, music's artist/title key.
+ *
+ * ── What is NOT here, deliberately ──────────────────────────────────────────────────────
+ * Anything that needs a database, a filesystem, a fetch or a picture decoder. This module is
+ * pure so both consumers can prove their behaviour with `bun test` instead of against a live
+ * store, and so a browser bundle may import it (music renders the pair side by side).
+ */
+/**
+ * How far two sizes may differ and still be called the same thing.
+ *
+ * A re-encode at a different quality is the case this exists for, and those land within a few
+ * percent. Zero would make a name match a strict subset of "same name AND same size", which
+ * misses precisely the files worth asking about; much larger starts pairing a clip with its
+ * own trailer.
+ */
+export declare const SIZE_TOLERANCE = 0.05;
+/**
+ * How far two playing times may differ and still be the same recording.
+ *
+ * Wide enough for a re-encode (a trim of a trailing black frame, a container that rounds), far
+ * too narrow for the owner's 2026-08-14 report of a 3:56 video paired with a 1:52 one.
+ */
+export declare const DURATION_TOLERANCE = 0.05;
+/**
+ * The name to compare, reduced to what a human means by "the same file".
+ *
+ * Strips the directory, the extension, and the marks a copy picks up along the way —
+ * `Finder`'s ` copy`/` copy 2`, a browser's ` (1)`, a script's `_1`/`-1` — then collapses
+ * everything that is not a letter or a digit. `My Video (1).mp4`, `my_video.MP4` and
+ * `My-Video copy 2.mov` all reduce to `myvideo`.
+ *
+ * 🔴 The extension is stripped ON PURPOSE, so a re-encode (`.mov` → `.mp4`, `.wma` → `.mp3`)
+ * still pairs with its source. That is the single most common likely-duplicate in this fleet's
+ * stores and a rule that kept the extension would never see one.
+ *
+ * 🔴 **The copy-counter strip is capped at two digits**, and that cap is a measured bug fix
+ * (bs, 2026-08-14). It used to be `[-_]\d+$`, which eats a CAMERA SEQUENCE as readily as a copy
+ * marker: `IMG_4595` and `IMG_4646` both reduced to `img`, so every iPhone capture in a tenant
+ * shared one bucket and paired with every other one whose size was within 5%. `_1`…`_99` is
+ * what a copy marker actually looks like; four digits is a photo's identity, and it must
+ * survive.
+ */
+export declare function normalizeName(name: string | null | undefined): string;
+/**
+ * Stems that name a CAMERA, not a file.
+ *
+ * `IMG`, `DSC`, `PXL`, `VID` are what a device calls everything it produces; two files whose
+ * names reduce to one of these have told us nothing except that they came from a phone. Even
+ * with the counter cap above, `IMG_1.MOV` still reduces to `img`, and a bucket called "img" is
+ * every photo the owner has ever taken.
+ *
+ * 🔴 This rejects a MATCH, never a file. Both copies stay wherever they are, and an
+ * identical-bytes pair is unaffected — a checksum match never consults the name.
+ */
+export declare const GENERIC_STEMS: ReadonlySet<string>;
+/**
+ * A name that could belong to any file from that device tells us nothing about identity.
+ *
+ * 🔴 The trailing digit run is stripped BEFORE the lookup, and only here — never in
+ * {@link normalizeName}, where removing it is what made every camera capture one bucket. The
+ * two are asked at different moments: `normalizeName` decides whether two names are the SAME
+ * (so `img4595` and `img4646` must stay apart), and this decides whether a name that already
+ * matched is worth anything (so two files both called `Track01` have told us nothing, and a
+ * ripper names half a library that).
+ */
+export declare const isGenericName: (normalized: string) => boolean;
+/** Within {@link SIZE_TOLERANCE} of each other. Two zero-byte files are not "close" — they
+ *  are two files nothing is known about. */
+export declare function sizesClose(a: number, b: number, tolerance?: number): boolean;
+/**
+ * Within {@link DURATION_TOLERANCE} of each other.
+ *
+ * 🔴 A missing or zero duration answers `null`, never `false`: "nobody has measured this yet"
+ * and "these are different lengths" are opposite answers, and collapsing them makes an
+ * unprobed library look like a library with no duplicates in it.
+ */
+export declare function durationsClose(a: number | null | undefined, b: number | null | undefined, tolerance?: number): boolean | null;
+/** One file, reduced to what this module can reason about. Units are the caller's — pass
+ *  both durations in the same unit or not at all. */
+export interface NamedFileFacts {
+    /** The name a person would recognise: a display title, else the last path segment. */
+    name: string | null | undefined;
+    sizeBytes: number;
+    /** Playing time, in whatever unit the caller uses consistently. Null = never measured. */
+    duration?: number | null;
+}
+export interface NameMatchVerdict {
+    match: boolean;
+    /** Written for the owner reading a review queue, never for a log. Empty when `match` is
+     *  false — a non-match has nothing to explain. */
+    reason: string;
+}
+/**
+ * The shared "these look like the same thing" test: the NAME agrees after normalization, the
+ * sizes are close, and nothing about the length says otherwise.
+ *
+ * It is deliberately a QUESTION and never an action. Both consumers act only on a checksum,
+ * which is proof; this decides what is worth showing a person side by side.
+ */
+export declare function likelyTheSameFile(a: NamedFileFacts, b: NamedFileFacts): NameMatchVerdict;

package/dist/core/duplicates/index.js

@@ -0,0 +1,177 @@
+/**
+ * "Are these two files the same thing?" — the fleet's ONE answer, with no I/O in it.
+ *
+ * ── Why this is here and not in an app ──────────────────────────────────────────────────
+ * `binary-server` wrote these rules first (2026-08-13, the owner: *"make strategy to always
+ * check for duplicate binaries in same app for same user … mark likely the duplicates for
+ * users to confirm"*), and they were measured against a real store: the copy-counter cap, the
+ * camera-generic stem list and the 5% size window each exist because a wider rule proposed
+ * thousands of pairs nobody could ever review. `music` then needed the same question asked of
+ * a 5,400-track library — *"I want to see a duplicate next to the file that it is a possible
+ * duplicate of … The 'binary-server' app (bs) already has this feature for checking duplicate
+ * files. We can reuse it and enhance the customizability if needed so the main strategy is
+ * shared."*
+ *
+ * So the strategy lives once, here, and both consume it. What each app keeps for itself is the
+ * evidence only it has: bs's perceptual frame hashes, music's artist/title key.
+ *
+ * ── What is NOT here, deliberately ──────────────────────────────────────────────────────
+ * Anything that needs a database, a filesystem, a fetch or a picture decoder. This module is
+ * pure so both consumers can prove their behaviour with `bun test` instead of against a live
+ * store, and so a browser bundle may import it (music renders the pair side by side).
+ */
+/**
+ * How far two sizes may differ and still be called the same thing.
+ *
+ * A re-encode at a different quality is the case this exists for, and those land within a few
+ * percent. Zero would make a name match a strict subset of "same name AND same size", which
+ * misses precisely the files worth asking about; much larger starts pairing a clip with its
+ * own trailer.
+ */
+export const SIZE_TOLERANCE = 0.05;
+/**
+ * How far two playing times may differ and still be the same recording.
+ *
+ * Wide enough for a re-encode (a trim of a trailing black frame, a container that rounds), far
+ * too narrow for the owner's 2026-08-14 report of a 3:56 video paired with a 1:52 one.
+ */
+export const DURATION_TOLERANCE = 0.05;
+/**
+ * The name to compare, reduced to what a human means by "the same file".
+ *
+ * Strips the directory, the extension, and the marks a copy picks up along the way —
+ * `Finder`'s ` copy`/` copy 2`, a browser's ` (1)`, a script's `_1`/`-1` — then collapses
+ * everything that is not a letter or a digit. `My Video (1).mp4`, `my_video.MP4` and
+ * `My-Video copy 2.mov` all reduce to `myvideo`.
+ *
+ * 🔴 The extension is stripped ON PURPOSE, so a re-encode (`.mov` → `.mp4`, `.wma` → `.mp3`)
+ * still pairs with its source. That is the single most common likely-duplicate in this fleet's
+ * stores and a rule that kept the extension would never see one.
+ *
+ * 🔴 **The copy-counter strip is capped at two digits**, and that cap is a measured bug fix
+ * (bs, 2026-08-14). It used to be `[-_]\d+$`, which eats a CAMERA SEQUENCE as readily as a copy
+ * marker: `IMG_4595` and `IMG_4646` both reduced to `img`, so every iPhone capture in a tenant
+ * shared one bucket and paired with every other one whose size was within 5%. `_1`…`_99` is
+ * what a copy marker actually looks like; four digits is a photo's identity, and it must
+ * survive.
+ */
+export function normalizeName(name) {
+    if (!name)
+        return "";
+    const leaf = name.split(/[\\/]/).pop() ?? "";
+    const stem = leaf.replace(/\.[a-z0-9]{1,5}$/i, "");
+    return stem
+        .toLowerCase()
+        .replace(/\s*\(\d+\)\s*$/, "")
+        .replace(/\s+copy(\s+\d+)?\s*$/, "")
+        .replace(/[-_]\d{1,2}\s*$/, "")
+        .replace(/[^a-z0-9]+/g, "");
+}
+/**
+ * Stems that name a CAMERA, not a file.
+ *
+ * `IMG`, `DSC`, `PXL`, `VID` are what a device calls everything it produces; two files whose
+ * names reduce to one of these have told us nothing except that they came from a phone. Even
+ * with the counter cap above, `IMG_1.MOV` still reduces to `img`, and a bucket called "img" is
+ * every photo the owner has ever taken.
+ *
+ * 🔴 This rejects a MATCH, never a file. Both copies stay wherever they are, and an
+ * identical-bytes pair is unaffected — a checksum match never consults the name.
+ */
+export const GENERIC_STEMS = new Set([
+    "img",
+    "image",
+    "images",
+    "dsc",
+    "dscf",
+    "dscn",
+    "pxl",
+    "vid",
+    "video",
+    "movie",
+    "mov",
+    "photo",
+    "pic",
+    "picture",
+    "screenshot",
+    "screenrecording",
+    "untitled",
+    "unknown",
+    "file",
+    "download",
+    "scan",
+    "capture",
+    "copy",
+    "new",
+    "temp",
+    "tmp",
+    // Music's own version of the same problem: an untagged rip is called this by every ripper
+    // ever written, and `track01` from two albums is two different songs.
+    "track",
+    "audiotrack",
+    "unknownartist",
+]);
+/**
+ * A name that could belong to any file from that device tells us nothing about identity.
+ *
+ * 🔴 The trailing digit run is stripped BEFORE the lookup, and only here — never in
+ * {@link normalizeName}, where removing it is what made every camera capture one bucket. The
+ * two are asked at different moments: `normalizeName` decides whether two names are the SAME
+ * (so `img4595` and `img4646` must stay apart), and this decides whether a name that already
+ * matched is worth anything (so two files both called `Track01` have told us nothing, and a
+ * ripper names half a library that).
+ */
+export const isGenericName = (normalized) => normalized.length < 3 ||
+    GENERIC_STEMS.has(normalized) ||
+    GENERIC_STEMS.has(normalized.replace(/\d+$/, ""));
+/** Within {@link SIZE_TOLERANCE} of each other. Two zero-byte files are not "close" — they
+ *  are two files nothing is known about. */
+export function sizesClose(a, b, tolerance = SIZE_TOLERANCE) {
+    if (a === b && a > 0)
+        return true;
+    const larger = Math.max(a, b);
+    if (larger <= 0)
+        return false;
+    return Math.abs(a - b) / larger <= tolerance;
+}
+/**
+ * Within {@link DURATION_TOLERANCE} of each other.
+ *
+ * 🔴 A missing or zero duration answers `null`, never `false`: "nobody has measured this yet"
+ * and "these are different lengths" are opposite answers, and collapsing them makes an
+ * unprobed library look like a library with no duplicates in it.
+ */
+export function durationsClose(a, b, tolerance = DURATION_TOLERANCE) {
+    if (!a || !b || a <= 0 || b <= 0)
+        return null;
+    return Math.abs(a - b) / Math.max(a, b) <= tolerance;
+}
+/**
+ * The shared "these look like the same thing" test: the NAME agrees after normalization, the
+ * sizes are close, and nothing about the length says otherwise.
+ *
+ * It is deliberately a QUESTION and never an action. Both consumers act only on a checksum,
+ * which is proof; this decides what is worth showing a person side by side.
+ */
+export function likelyTheSameFile(a, b) {
+    const na = normalizeName(a.name);
+    const nb = normalizeName(b.name);
+    // Two empty names are not a match with each other — it means neither file has a name worth
+    // comparing (a bare digest key, an untitled upload), and pairing those proposes every
+    // unnamed object as a duplicate of every other.
+    if (!na || na !== nb)
+        return { match: false, reason: "" };
+    if (isGenericName(na))
+        return { match: false, reason: "" };
+    if (!sizesClose(a.sizeBytes, b.sizeBytes))
+        return { match: false, reason: "" };
+    if (durationsClose(a.duration, b.duration) === false)
+        return { match: false, reason: "" };
+    const pct = Math.round((Math.abs(a.sizeBytes - b.sizeBytes) / Math.max(a.sizeBytes, b.sizeBytes, 1)) * 100);
+    return {
+        match: true,
+        reason: a.sizeBytes === b.sizeBytes
+            ? "same name, same size, different bytes"
+            : `same name, size within ${pct}%, different bytes`,
+    };
+}

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.0.0",
+	"version": "2.1.0",
 	"license": "ISC",
 	"type": "module",
-	"description": "Framework-agnostic core of the cursedbelt split \u2014 isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",
+	"description": "Framework-agnostic core of the cursedbelt split — isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",
 	"cursed": {
 		"schemaVersion": 1,
 		"app": {
@@ -20,7 +20,7 @@
 		"typecheck": "tsc -p tsconfig.build.json --noEmit",
 		"test": "NODE_ENV=development bun test src",
 		"build": "bun run clean && tsc -p tsconfig.build.json",
-		"paths": "bun ../../tools/check-paths.ts .",
+		"paths": "bun run scripts/paths.ts",
 		"verify": "bun run paths && bun run typecheck && bun run build && bun run test",
 		"prepublishOnly": "bun run verify"
 	},
@@ -125,6 +125,12 @@
 			"source": "./src/core/download.ts",
 			"import": "./dist/core/download.js"
 		},
+		"./duplicates": {
+			"types": "./dist/core/duplicates/index.d.ts",
+			"bun": "./src/core/duplicates/index.ts",
+			"source": "./src/core/duplicates/index.ts",
+			"import": "./dist/core/duplicates/index.js"
+		},
 		"./errors": {
 			"types": "./dist/shared/errors.d.ts",
 			"bun": "./src/shared/errors.ts",

package/src/core/duplicates/index.spec.ts

@@ -0,0 +1,116 @@
+/**
+ * The shared duplicate rules, proved against the cases that produced them.
+ *
+ * Every assertion here is a measured incident from `binary-server` or `music`, not an
+ * invented example — see the module header for which.
+ */
+import { describe, expect, it } from "bun:test";
+import {
+	DURATION_TOLERANCE,
+	durationsClose,
+	isGenericName,
+	likelyTheSameFile,
+	normalizeName,
+	SIZE_TOLERANCE,
+	sizesClose,
+} from "./index";
+
+describe("normalizeName", () => {
+	it("reduces the marks a copy picks up to the same stem", () => {
+		expect(normalizeName("My Video (1).mp4")).toBe("myvideo");
+		expect(normalizeName("my_video.MP4")).toBe("myvideo");
+		expect(normalizeName("My-Video copy 2.mov")).toBe("myvideo");
+	});
+
+	it("strips the extension, so a re-encode still pairs with its source", () => {
+		expect(normalizeName("Song.wma")).toBe(normalizeName("Song.mp3"));
+	});
+
+	it("🔴 keeps a four-digit camera sequence — the 2026-08-14 flood", () => {
+		// `IMG_4595` and `IMG_4646` must NOT collapse onto each other.
+		expect(normalizeName("IMG_4595.MOV")).not.toBe(normalizeName("IMG_4646.MOV"));
+		// …while a two-digit copy marker still does.
+		expect(normalizeName("mix_2.mp3")).toBe(normalizeName("mix.mp3"));
+	});
+
+	it("drops the directory", () => {
+		expect(normalizeName("Main 1/rap/Song.mp3")).toBe("song");
+	});
+});
+
+describe("isGenericName", () => {
+	it("rejects the stems that name a device rather than a file", () => {
+		expect(isGenericName(normalizeName("IMG_1.MOV"))).toBe(true);
+		expect(isGenericName(normalizeName("Track01.mp3"))).toBe(true);
+		expect(isGenericName(normalizeName("Between U.mp3"))).toBe(false);
+	});
+});
+
+describe("sizesClose", () => {
+	it("accepts a re-encode and refuses a different file", () => {
+		expect(sizesClose(10_000_000, 10_400_000)).toBe(true);
+		expect(sizesClose(10_000_000, 20_000_000)).toBe(false);
+	});
+
+	it("🔴 two zero-byte files are not close — nothing is known about either", () => {
+		expect(sizesClose(0, 0)).toBe(false);
+	});
+
+	it("is bounded by the exported tolerance", () => {
+		expect(sizesClose(100, 100 * (1 + SIZE_TOLERANCE))).toBe(true);
+		expect(sizesClose(100, 100 * (1 + SIZE_TOLERANCE * 2))).toBe(false);
+	});
+});
+
+describe("durationsClose", () => {
+	it("🔴 answers null when nobody has measured, never false", () => {
+		expect(durationsClose(null, 200)).toBeNull();
+		expect(durationsClose(0, 200)).toBeNull();
+		expect(durationsClose(undefined, undefined)).toBeNull();
+	});
+
+	it("refuses the owner's 3:56-vs-1:52 pair", () => {
+		expect(durationsClose(236, 112)).toBe(false);
+		expect(durationsClose(236, 236 * (1 + DURATION_TOLERANCE / 2))).toBe(true);
+	});
+});
+
+describe("likelyTheSameFile", () => {
+	const facts = (name: string, sizeBytes: number, duration?: number | null) => ({
+		name,
+		sizeBytes,
+		...(duration === undefined ? {} : { duration }),
+	});
+
+	it("pairs a re-encode of the same song", () => {
+		const verdict = likelyTheSameFile(
+			facts("Between U.mp3", 8_000_000, 312),
+			facts("Between U.wma", 7_800_000, 312),
+		);
+		expect(verdict.match).toBe(true);
+		expect(verdict.reason).toContain("same name");
+	});
+
+	it("does not pair two different songs of a similar size", () => {
+		expect(likelyTheSameFile(facts("A.mp3", 8_000_000), facts("B.mp3", 8_010_000)).match).toBe(
+			false,
+		);
+	});
+
+	it("🔴 a length that disagrees kills a name+size match", () => {
+		expect(
+			likelyTheSameFile(facts("Set.mp3", 8_000_000, 236), facts("Set.mp3", 8_100_000, 112)).match,
+		).toBe(false);
+	});
+
+	it("🔴 an unmeasured length does not — that would find nothing in an unprobed library", () => {
+		expect(
+			likelyTheSameFile(facts("Set.mp3", 8_000_000, null), facts("Set.mp3", 8_100_000, null)).match,
+		).toBe(true);
+	});
+
+	it("refuses a generic stem, and refuses two nameless files", () => {
+		expect(likelyTheSameFile(facts("IMG_1.MOV", 500), facts("IMG_1.MOV", 500)).match).toBe(false);
+		expect(likelyTheSameFile(facts("", 500), facts("", 500)).match).toBe(false);
+	});
+});

package/src/core/duplicates/index.ts

@@ -0,0 +1,203 @@
+/**
+ * "Are these two files the same thing?" — the fleet's ONE answer, with no I/O in it.
+ *
+ * ── Why this is here and not in an app ──────────────────────────────────────────────────
+ * `binary-server` wrote these rules first (2026-08-13, the owner: *"make strategy to always
+ * check for duplicate binaries in same app for same user … mark likely the duplicates for
+ * users to confirm"*), and they were measured against a real store: the copy-counter cap, the
+ * camera-generic stem list and the 5% size window each exist because a wider rule proposed
+ * thousands of pairs nobody could ever review. `music` then needed the same question asked of
+ * a 5,400-track library — *"I want to see a duplicate next to the file that it is a possible
+ * duplicate of … The 'binary-server' app (bs) already has this feature for checking duplicate
+ * files. We can reuse it and enhance the customizability if needed so the main strategy is
+ * shared."*
+ *
+ * So the strategy lives once, here, and both consume it. What each app keeps for itself is the
+ * evidence only it has: bs's perceptual frame hashes, music's artist/title key.
+ *
+ * ── What is NOT here, deliberately ──────────────────────────────────────────────────────
+ * Anything that needs a database, a filesystem, a fetch or a picture decoder. This module is
+ * pure so both consumers can prove their behaviour with `bun test` instead of against a live
+ * store, and so a browser bundle may import it (music renders the pair side by side).
+ */
+
+/**
+ * How far two sizes may differ and still be called the same thing.
+ *
+ * A re-encode at a different quality is the case this exists for, and those land within a few
+ * percent. Zero would make a name match a strict subset of "same name AND same size", which
+ * misses precisely the files worth asking about; much larger starts pairing a clip with its
+ * own trailer.
+ */
+export const SIZE_TOLERANCE = 0.05;
+
+/**
+ * How far two playing times may differ and still be the same recording.
+ *
+ * Wide enough for a re-encode (a trim of a trailing black frame, a container that rounds), far
+ * too narrow for the owner's 2026-08-14 report of a 3:56 video paired with a 1:52 one.
+ */
+export const DURATION_TOLERANCE = 0.05;
+
+/**
+ * The name to compare, reduced to what a human means by "the same file".
+ *
+ * Strips the directory, the extension, and the marks a copy picks up along the way —
+ * `Finder`'s ` copy`/` copy 2`, a browser's ` (1)`, a script's `_1`/`-1` — then collapses
+ * everything that is not a letter or a digit. `My Video (1).mp4`, `my_video.MP4` and
+ * `My-Video copy 2.mov` all reduce to `myvideo`.
+ *
+ * 🔴 The extension is stripped ON PURPOSE, so a re-encode (`.mov` → `.mp4`, `.wma` → `.mp3`)
+ * still pairs with its source. That is the single most common likely-duplicate in this fleet's
+ * stores and a rule that kept the extension would never see one.
+ *
+ * 🔴 **The copy-counter strip is capped at two digits**, and that cap is a measured bug fix
+ * (bs, 2026-08-14). It used to be `[-_]\d+$`, which eats a CAMERA SEQUENCE as readily as a copy
+ * marker: `IMG_4595` and `IMG_4646` both reduced to `img`, so every iPhone capture in a tenant
+ * shared one bucket and paired with every other one whose size was within 5%. `_1`…`_99` is
+ * what a copy marker actually looks like; four digits is a photo's identity, and it must
+ * survive.
+ */
+export function normalizeName(name: string | null | undefined): string {
+	if (!name) return "";
+	const leaf = name.split(/[\\/]/).pop() ?? "";
+	const stem = leaf.replace(/\.[a-z0-9]{1,5}$/i, "");
+	return stem
+		.toLowerCase()
+		.replace(/\s*\(\d+\)\s*$/, "")
+		.replace(/\s+copy(\s+\d+)?\s*$/, "")
+		.replace(/[-_]\d{1,2}\s*$/, "")
+		.replace(/[^a-z0-9]+/g, "");
+}
+
+/**
+ * Stems that name a CAMERA, not a file.
+ *
+ * `IMG`, `DSC`, `PXL`, `VID` are what a device calls everything it produces; two files whose
+ * names reduce to one of these have told us nothing except that they came from a phone. Even
+ * with the counter cap above, `IMG_1.MOV` still reduces to `img`, and a bucket called "img" is
+ * every photo the owner has ever taken.
+ *
+ * 🔴 This rejects a MATCH, never a file. Both copies stay wherever they are, and an
+ * identical-bytes pair is unaffected — a checksum match never consults the name.
+ */
+export const GENERIC_STEMS: ReadonlySet<string> = new Set([
+	"img",
+	"image",
+	"images",
+	"dsc",
+	"dscf",
+	"dscn",
+	"pxl",
+	"vid",
+	"video",
+	"movie",
+	"mov",
+	"photo",
+	"pic",
+	"picture",
+	"screenshot",
+	"screenrecording",
+	"untitled",
+	"unknown",
+	"file",
+	"download",
+	"scan",
+	"capture",
+	"copy",
+	"new",
+	"temp",
+	"tmp",
+	// Music's own version of the same problem: an untagged rip is called this by every ripper
+	// ever written, and `track01` from two albums is two different songs.
+	"track",
+	"audiotrack",
+	"unknownartist",
+]);
+
+/**
+ * A name that could belong to any file from that device tells us nothing about identity.
+ *
+ * 🔴 The trailing digit run is stripped BEFORE the lookup, and only here — never in
+ * {@link normalizeName}, where removing it is what made every camera capture one bucket. The
+ * two are asked at different moments: `normalizeName` decides whether two names are the SAME
+ * (so `img4595` and `img4646` must stay apart), and this decides whether a name that already
+ * matched is worth anything (so two files both called `Track01` have told us nothing, and a
+ * ripper names half a library that).
+ */
+export const isGenericName = (normalized: string): boolean =>
+	normalized.length < 3 ||
+	GENERIC_STEMS.has(normalized) ||
+	GENERIC_STEMS.has(normalized.replace(/\d+$/, ""));
+
+/** Within {@link SIZE_TOLERANCE} of each other. Two zero-byte files are not "close" — they
+ *  are two files nothing is known about. */
+export function sizesClose(a: number, b: number, tolerance = SIZE_TOLERANCE): boolean {
+	if (a === b && a > 0) return true;
+	const larger = Math.max(a, b);
+	if (larger <= 0) return false;
+	return Math.abs(a - b) / larger <= tolerance;
+}
+
+/**
+ * Within {@link DURATION_TOLERANCE} of each other.
+ *
+ * 🔴 A missing or zero duration answers `null`, never `false`: "nobody has measured this yet"
+ * and "these are different lengths" are opposite answers, and collapsing them makes an
+ * unprobed library look like a library with no duplicates in it.
+ */
+export function durationsClose(
+	a: number | null | undefined,
+	b: number | null | undefined,
+	tolerance = DURATION_TOLERANCE,
+): boolean | null {
+	if (!a || !b || a <= 0 || b <= 0) return null;
+	return Math.abs(a - b) / Math.max(a, b) <= tolerance;
+}
+
+/** One file, reduced to what this module can reason about. Units are the caller's — pass
+ *  both durations in the same unit or not at all. */
+export interface NamedFileFacts {
+	/** The name a person would recognise: a display title, else the last path segment. */
+	name: string | null | undefined;
+	sizeBytes: number;
+	/** Playing time, in whatever unit the caller uses consistently. Null = never measured. */
+	duration?: number | null;
+}
+
+export interface NameMatchVerdict {
+	match: boolean;
+	/** Written for the owner reading a review queue, never for a log. Empty when `match` is
+	 *  false — a non-match has nothing to explain. */
+	reason: string;
+}
+
+/**
+ * The shared "these look like the same thing" test: the NAME agrees after normalization, the
+ * sizes are close, and nothing about the length says otherwise.
+ *
+ * It is deliberately a QUESTION and never an action. Both consumers act only on a checksum,
+ * which is proof; this decides what is worth showing a person side by side.
+ */
+export function likelyTheSameFile(a: NamedFileFacts, b: NamedFileFacts): NameMatchVerdict {
+	const na = normalizeName(a.name);
+	const nb = normalizeName(b.name);
+	// Two empty names are not a match with each other — it means neither file has a name worth
+	// comparing (a bare digest key, an untitled upload), and pairing those proposes every
+	// unnamed object as a duplicate of every other.
+	if (!na || na !== nb) return { match: false, reason: "" };
+	if (isGenericName(na)) return { match: false, reason: "" };
+	if (!sizesClose(a.sizeBytes, b.sizeBytes)) return { match: false, reason: "" };
+	if (durationsClose(a.duration, b.duration) === false) return { match: false, reason: "" };
+
+	const pct = Math.round(
+		(Math.abs(a.sizeBytes - b.sizeBytes) / Math.max(a.sizeBytes, b.sizeBytes, 1)) * 100,
+	);
+	return {
+		match: true,
+		reason:
+			a.sizeBytes === b.sizeBytes
+				? "same name, same size, different bytes"
+				: `same name, size within ${pct}%, different bytes`,
+	};
+}