advertise over beacon v2 as metamesh.enrich/<id> so meta-sort's Plugins page can find it (Scan -> Add)

.gitattributes

@@ -0,0 +1,6 @@
+# FIX CRLF always when developer has not set
+# Linux/Mac: git config --global core.autocrlf input
+# Windows: git config --global core.autocrlf true
+# Auto detect text files and perform LF normalization
+* text=auto
+* eol=lf

README.md

@@ -8,7 +8,8 @@ This plugin enriches video metadata by querying the TMDB API:
 
 - **Search by IMDB ID**: Uses existing IMDB ID for precise matching
 - **Search by title**: Falls back to title/year search
-- **Image download**: Downloads poster and backdrop images to `/files/poster/`
+- **Image download**: Downloads poster and backdrop images to `/files/plugin/tmdb/`
+- **Alternative posters**: Lists up to 10 posters (the primary plus the best-voted alternatives, as `url` locator CIDs — nothing extra is downloaded)
 - **Rich metadata**: Fetches plot, rating, genres, studios
 
 **Note**: This runs on the background queue as it makes external API calls.
@@ -26,9 +27,8 @@ This plugin enriches video metadata by querying the TMDB API:
 | `rating` | Vote average |
 | `plot/eng` | English plot synopsis |
 | `poster` | Poster image CID |
-| `posterPath` | Poster file path |
+| `posters/{lang3}/{cid}` | Alternative posters key-set, `poster` among them (METADATA_KEYS.md §6) |
 | `backdrop` | Backdrop image CID |
-| `backdropPath` | Backdrop file path |
 | `genres` | Genre set |
 | `studio` | Production company set |
 

package.json

@@ -5,7 +5,7 @@
   "description": "MetaMesh plugin: Fetches metadata from TMDB API",
   "type": "module",
   "main": "dist/index.js",
-  "scripts": { "build": "tsc", "start": "node dist/index.js" },
+  "scripts": { "build": "tsc", "start": "node dist/index.js", "test": "vitest run", "test:watch": "vitest" },
   "dependencies": { "fastify": "^5.0.0", "axios": "^1.6.0" },
-  "devDependencies": { "@types/node": "^20.0.0", "typescript": "^5.3.0" }
+  "devDependencies": { "@types/node": "^20.0.0", "typescript": "^5.3.0", "vitest": "^1.6.1" }
 }

src/beacon-advertise.ts

@@ -0,0 +1,188 @@
+/**
+ * Beacon v2 advertiser — makes this plugin findable by meta-sort's Plugins
+ * page (Scan → Add) without anyone typing its URL.
+ *
+ * Advertises one resource, cap `metamesh.enrich/<manifest id>`, on the beacon
+ * group (239.255.99.1:9099): unsolicited every 10 s, and unicast in reply to
+ * any probe whose `want` matches. Says `bye` on shutdown. It keeps no view of
+ * other nodes — a plugin only needs to be found. Spec:
+ * meta-root docs/project-architecture/beacon-v2.md.
+ *
+ * Env:
+ *   ENABLE_UDP_DISCOVERY  false/0/no/off disables
+ *   BEACON_ADVERTISE_URL  endpoints.http (default http://$HOSTNAME:$PORT)
+ *   BEACON_BINDS          the one meta-sort instance allowed to list it
+ *                         (meta-sort sets this on containers it spawns)
+ *   BEACON_GROUP / BEACON_PORT / BEACON_INTERVAL_MS
+ *
+ * ⚠ MIRRORED FILE. Byte-identical copies live in every TypeScript
+ * metamesh-plugin-*; see meta-root `scripts/check-mirrors.sh`. Never fatal: a
+ * host that blocks multicast logs a warning and the plugin serves on.
+ */
+
+import dgram from 'dgram';
+import { hostname, networkInterfaces } from 'os';
+
+const PROTO = 'beacon';
+const VERSION = 2;
+
+interface Resource {
+    id: string;
+    caps: string[];
+    endpoints: Record<string, string>;
+    binds?: string;
+}
+
+interface NodeInfo {
+    name: string;
+    instance: string;
+    version?: string;
+}
+
+function envNum(key: string): number | undefined {
+    const n = Number(process.env[key]);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+function enabled(): boolean {
+    const v = (process.env.ENABLE_UDP_DISCOVERY ?? '').trim().toLowerCase();
+    return !['false', '0', 'no', 'off'].includes(v);
+}
+
+/** IPv4 addresses of every up, non-internal interface. */
+function interfaceAddresses(): string[] {
+    const out: string[] = [];
+    for (const list of Object.values(networkInterfaces())) {
+        for (const ni of list ?? []) {
+            const v4 = (ni as { family: string | number }).family === 'IPv4' || (ni as { family: string | number }).family === 4;
+            if (v4 && !ni.internal && ni.address) out.push(ni.address);
+        }
+    }
+    return out;
+}
+
+/** Same matching rules as the spec: `*`, `x/*`, optional `@contract`. */
+function capMatches(pattern: string, cap: string): boolean {
+    if (pattern === '*') return true;
+    const split = (s: string): [string, string | null] => {
+        const i = s.lastIndexOf('@');
+        return i >= 0 ? [s.slice(0, i), s.slice(i + 1)] : [s, null];
+    };
+    const [pb, pc] = split(pattern);
+    const [cb, cc] = split(cap);
+    if (pc !== null && cc !== pc) return false;
+    if (pb.endsWith('/*')) {
+        const prefix = pb.slice(0, -2);
+        const rest = cb.startsWith(prefix) ? cb.slice(prefix.length) : '';
+        return rest.startsWith('/') && rest.length > 1;
+    }
+    return pb === cb;
+}
+
+let socket: dgram.Socket | null = null;
+let timer: NodeJS.Timeout | null = null;
+let node: NodeInfo | null = null;
+let resource: Resource | null = null;
+let ifaces: string[] = [];
+let group = '239.255.99.1';
+let udpPort = 9099;
+
+function send(msg: object, dest?: { address: string; port: number }): void {
+    const s = socket;
+    if (!s) return;
+    const body = Buffer.from(JSON.stringify(msg));
+    if (dest) {
+        s.send(body, dest.port, dest.address, () => {});
+        return;
+    }
+    // Once per interface: the default route alone reaches one network.
+    for (const addr of ifaces) {
+        try {
+            s.setMulticastInterface(addr);
+            s.send(body, udpPort, group, () => {});
+        } catch (e) {
+            console.warn(`[beacon] send on ${addr} failed:`, e);
+        }
+    }
+}
+
+function advertise(dest?: { address: string; port: number }): void {
+    if (!node || !resource) return;
+    send({ proto: PROTO, v: VERSION, type: 'advertise', node, resources: [resource] }, dest);
+}
+
+/**
+ * Start advertising this plugin. Call once the HTTP server is listening, so a
+ * consumer that hears it can reach it. Idempotent.
+ */
+export function startBeacon(pluginId: string, version: string, httpPort: number): void {
+    if (socket || !enabled()) return;
+    group = process.env.BEACON_GROUP || group;
+    udpPort = envNum('BEACON_PORT') ?? udpPort;
+    const intervalMs = envNum('BEACON_INTERVAL_MS') ?? 10_000;
+    const instance = process.env.HOSTNAME || hostname();
+    const url = (process.env.BEACON_ADVERTISE_URL || `http://${instance}:${httpPort}`).replace(/\/+$/, '');
+    const binds = (process.env.BEACON_BINDS || '').trim();
+
+    node = { name: `metamesh-plugin-${pluginId}`, instance, ...(version ? { version } : {}) };
+    resource = {
+        id: pluginId,
+        caps: [`metamesh.enrich/${pluginId}`],
+        endpoints: { http: url, manifest: '/manifest' },
+        ...(binds ? { binds } : {}),
+    };
+
+    const s = dgram.createSocket({ type: 'udp4', reuseAddr: true });
+    socket = s;
+    s.on('error', (err) => console.warn('[beacon] socket error:', err.message));
+    s.on('message', (buf, rinfo) => {
+        let m: { proto?: string; v?: number; type?: string; from?: string; want?: string[] };
+        try {
+            m = JSON.parse(buf.toString('utf8'));
+        } catch {
+            return; // foreign traffic on the shared group
+        }
+        if (m?.proto !== PROTO || m.v !== VERSION || m.type !== 'probe' || m.from === instance) return;
+        const want = Array.isArray(m.want) ? m.want : [];
+        if (want.length === 0 || resource!.caps.some((c) => want.some((p) => capMatches(p, c)))) {
+            advertise({ address: rinfo.address, port: rinfo.port });
+        }
+    });
+    s.bind(udpPort, '0.0.0.0', () => {
+        try {
+            s.setMulticastTTL(1);
+        } catch {
+            /* best effort */
+        }
+        ifaces = interfaceAddresses();
+        for (const addr of ifaces) {
+            try {
+                s.addMembership(group, addr);
+            } catch (e) {
+                console.warn(`[beacon] join ${group} on ${addr} failed:`, e);
+            }
+        }
+        console.log(`[beacon] advertising metamesh.enrich/${pluginId} at ${url} on ${group}:${udpPort}`);
+        advertise();
+        timer = setInterval(() => advertise(), intervalMs);
+        timer.unref?.();
+    });
+}
+
+/** Say `bye` so consumers drop this plugin at once. */
+export async function stopBeacon(): Promise<void> {
+    if (!socket || !node) return;
+    if (timer) clearInterval(timer);
+    send({ proto: PROTO, v: VERSION, type: 'bye', node });
+    // Let the bye datagrams leave before the socket closes under them.
+    await new Promise((r) => setTimeout(r, 50));
+    const s = socket;
+    socket = null;
+    await new Promise<void>((resolve) => {
+        try {
+            s.close(() => resolve());
+        } catch {
+            resolve();
+        }
+    });
+}

src/cid.ts

@@ -0,0 +1,58 @@
+/**
+ * CID encoding helpers (METADATA_KEYS.md §2).
+ */
+
+const BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+
+/** RFC 4648 base32, lowercase, no padding, with the `b` multibase prefix. */
+export function base32LowerMultibase(bytes: Uint8Array): string {
+    let out = 'b';
+    let bits = 0;
+    let value = 0;
+    for (const byte of bytes) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            out += BASE32_ALPHABET[(value >> bits) & 0x1f];
+        }
+    }
+    if (bits > 0) {
+        out += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f];
+    }
+    return out;
+}
+
+/** Unsigned LEB128 varint, as multiformats encodes codecs and lengths. */
+function varint(value: number): number[] {
+    const out: number[] = [];
+    let n = value;
+    while (n >= 0x80) {
+        out.push((n & 0x7f) | 0x80);
+        n = Math.floor(n / 0x80);
+    }
+    out.push(n);
+    return out;
+}
+
+/** Custom multicodec of the `url` locator (METADATA_KEYS.md §2.1). */
+export const URL_LOCATOR_CODEC = 0x1006;
+
+/**
+ * Encode an absolute http(s) URL as a `0x1006` identity-multihash CIDv1:
+ * `[0x01][varint codec][0x00][varint len][utf-8 url]`, base32lower. The digest
+ * is the URL itself, so minting one costs no I/O. `null` for anything that is
+ * not an absolute http(s) URL.
+ *
+ * CROSS-BINARY CONTRACT: byte-identical to meta-feeder-sdk's `compute_url_cid`
+ * (`hash.rs`); both test suites pin the same vectors.
+ */
+export function encodeUrlCid(url: string): string | null {
+    const trimmed = url.trim();
+    if (!trimmed.startsWith('http://') && !trimmed.startsWith('https://')) {
+        return null;
+    }
+    const digest = Buffer.from(trimmed, 'utf8');
+    const header = Buffer.from([0x01, ...varint(URL_LOCATOR_CODEC), 0x00, ...varint(digest.length)]);
+    return base32LowerMultibase(Buffer.concat([header, digest]));
+}

src/index.ts

@@ -27,6 +27,7 @@
 import Fastify from 'fastify';
 import type { HealthResponse, ProcessRequest, ProcessResponse, CallbackPayload, ConfigureRequest, ConfigureResponse } from './types.js';
 import { manifest, process as processFile, configure } from './plugin.js';
+import { startBeacon, stopBeacon } from './beacon-advertise.js';
 
 const app = Fastify({ logger: true });
 let ready = false;
@@ -64,5 +65,5 @@ app.post<{ Body: ProcessRequest }>('/process', async (request, reply) => {
 });
 
 const port = parseInt(process.env.PORT || '8080', 10);
-app.listen({ port, host: '0.0.0.0' }).then(() => { ready = true; console.log(`[${manifest.id}] Listening on port ${port}`); });
+app.listen({ port, host: '0.0.0.0' }).then(() => { startBeacon(manifest.id, manifest.version, port); ready = true; console.log(`[${manifest.id}] Listening on port ${port}`); });
-process.on('SIGTERM', async () => { ready = false; await app.close(); process.exit(0); });
+process.on('SIGTERM', async () => { await stopBeacon(); ready = false; await app.close(); process.exit(0); });

src/plugin.ts

@@ -9,7 +9,8 @@
  * PLUGIN FILE ACCESS ARCHITECTURE
  * ============================================================================
  *
- * File access via WebDAV (WEBDAV_URL environment variable):
+ * File access via WebDAV, on the meta-core named by each /process request
+ * (its /urls -> webdavUrlInternal; WEBDAV_URL overrides):
  *   - Read media files:  GET  /webdav/watch/...  or /webdav/test/...
  *   - Write output:      PUT  /webdav/plugin/tmdb/...
  *   - Cache:             Local /cache mount (for JSON cache files)
@@ -18,33 +19,29 @@
  *   - No output mount needed on plugin containers
  *   - Consistent read/write architecture via HTTP
  *   - Works in any orchestration environment
+ *   - Posters land in the same core the CIDs are written to, always
  *
  * ============================================================================
  *
  * Matches old TMDBProcessor output:
  * - tmdbid, imdbid
- * - originalTitle, movieYear, releasedate
+ * - title, originalTitle, movieYear, releasedate
+ * - titles/<lang3>/<name> key-set: localized + original title + every AKA
  * - plot/eng, rating
  * - genres (add), studio (add), tags (add)
  * - poster, backdrop (CID hashes of downloaded images)
+ * - posters/{lang3}/{cid} (alternative posters as url locators, `poster` among them)
  */
 
 import axios from 'axios';
-import { statSync, openSync, readSync, closeSync } from 'fs';
 import { createHash } from 'crypto';
 import * as path from 'path';
 import type { PluginManifest, ProcessRequest, CallbackPayload } from './types.js';
 import { MetaCoreClient } from './meta-core-client.js';
 import { readJson, writeJson } from './cache.js';
-import { createWebDAVClient, WebDAVClient } from './webdav-client.js';
+import { getWebDAVClient, WebDAVClient } from './webdav-client.js';
-
+import { base32LowerMultibase } from './cid.js';
-// Initialize WebDAV client - required for plugin operation
+import { posterMembers } from './posters.js';
-const webdavClient = createWebDAVClient();
-if (webdavClient) {
-    console.log('[tmdb] WebDAV client initialized for file access');
-} else {
-    console.warn('[tmdb] WARNING: WEBDAV_URL not set - plugin will not be able to write output files');
-}
 
 const IMAGE_BASE_URL = 'https://image.tmdb.org/t/p/original';
 
@@ -52,54 +49,14 @@ const IMAGE_BASE_URL = 'https://image.tmdb.org/t/p/original';
  * ============================================================================
  * PLUGIN OUTPUT PATH - Written via WebDAV
  * ============================================================================
- * Output files (posters, backdrops) are written via WebDAV PUT requests.
+ * Output files (posters, backdrops) are written via WebDAV PUT requests, to the
- * Path: /files/plugin/tmdb/<filename> (accessible at WEBDAV_URL/plugin/tmdb/)
+ * WebDAV of the meta-core that issued the /process call.
+ * Path: /files/plugin/tmdb/<filename>
  * CACHE_PATH (/cache) - Local mount for plugin cache (handled by cache.ts)
  * ============================================================================
  */
 const PLUGIN_OUTPUT_WEBDAV_PATH = '/files/plugin/tmdb';
 
-/**
- * Compute midhash256 CID for a file (matches meta-hash algorithm)
- *
- * Algorithm:
- * - For files <= 1MB: Hashes entire file content + 8-byte size prefix
- * - For files > 1MB: Hashes middle 1MB + 8-byte size prefix
- * - Returns CIDv1 with custom codec 0x1000
- */
-function computeMidHash256Sync(filePath: string): string {
-    const SAMPLE_SIZE = 1024 * 1024; // 1MB
-    // varint encoding of 0x1000 (4096) for both codec and hash function code
-    const MIDHASH_VARINT = Buffer.from([0x80, 0x20]);
-
-    // Get file size
-    const stats = statSync(filePath);
-    const fileSize = stats.size;
-
-    // Create size buffer (64-bit big-endian)
-    const sizeBuffer = Buffer.allocUnsafe(8);
-    sizeBuffer.writeBigUInt64BE(BigInt(fileSize), 0);
-
-    // Extract sample data
-    let sampleData: Buffer;
-    if (fileSize <= SAMPLE_SIZE) {
-        // Small file: read entire content
-        const fd = openSync(filePath, 'r');
-        sampleData = Buffer.allocUnsafe(fileSize);
-        readSync(fd, sampleData, 0, fileSize, 0);
-        closeSync(fd);
-    } else {
-        // Large file: read middle 1MB
-        const middleOffset = Math.floor((fileSize - SAMPLE_SIZE) / 2);
-        const fd = openSync(filePath, 'r');
-        sampleData = Buffer.allocUnsafe(SAMPLE_SIZE);
-        readSync(fd, sampleData, 0, SAMPLE_SIZE, middleOffset);
-        closeSync(fd);
-    }
-
-    return computeMidHash256FromData(fileSize, sampleData);
-}
-
 /**
  * Compute midhash256 CID via WebDAV
  */
@@ -151,33 +108,7 @@ function computeMidHash256FromData(fileSize: number, sampleData: Buffer): string
     ]);
 
     // Encode as base32lower with 'b' prefix (multibase)
-    const base32Chars = 'abcdefghijklmnopqrstuvwxyz234567';
+    return base32LowerMultibase(cidBytes);
-    let cid = 'b';
-    let bits = 0;
-    let value = 0;
-    for (const byte of cidBytes) {
-        value = (value << 8) | byte;
-        bits += 8;
-        while (bits >= 5) {
-            bits -= 5;
-            cid += base32Chars[(value >> bits) & 0x1f];
-        }
-    }
-    if (bits > 0) {
-        cid += base32Chars[(value << (5 - bits)) & 0x1f];
-    }
-
-    return cid;
-}
-
-/**
- * Compute midhash256 CID for a file (auto-selects WebDAV or filesystem)
- */
-async function computeMidHash256(filePath: string): Promise<string> {
-    if (webdavClient) {
-        return computeMidHash256WebDAV(webdavClient, filePath);
-    }
-    return computeMidHash256Sync(filePath);
 }
 
 export const manifest: PluginManifest = {
@@ -225,6 +156,51 @@ let forceRecompute = false;
 
 const BASE_URL = 'https://api.themoviedb.org/3';
 
+// ISO 639-1 → ISO 639-3 (`lang3`, the 639-2/T form where B/T differ) for the
+// languages TMDB commonly returns. Unknown codes map to nothing.
+const ISO639_1_TO_3: Record<string, string> = {
+    en: 'eng', ja: 'jpn', fr: 'fra', de: 'deu', es: 'spa', it: 'ita', ru: 'rus',
+    ko: 'kor', zh: 'zho', pt: 'por', nl: 'nld', sv: 'swe', no: 'nor', da: 'dan',
+    fi: 'fin', pl: 'pol', tr: 'tur', cs: 'ces', hu: 'hun', el: 'ell', he: 'heb',
+    th: 'tha', vi: 'vie', id: 'ind', uk: 'ukr', ro: 'ron', ar: 'ara', fa: 'fas',
+    hi: 'hin', ta: 'tam', te: 'tel', ms: 'msa', tl: 'tgl', ca: 'cat', bg: 'bul',
+    hr: 'hrv', sr: 'srp', sk: 'slk', sl: 'slv', et: 'est', lv: 'lav', lt: 'lit',
+    is: 'isl', ga: 'gle', cn: 'zho',
+};
+
+function iso639_1to3(code: string | undefined | null): string | undefined {
+    return code ? ISO639_1_TO_3[code.trim().toLowerCase()] : undefined;
+}
+
+// TMDB keys AKAs by MARKET (`iso_3166_1`), not language. Only markets that
+// clearly imply one language are mapped; a multilingual or unknown market
+// (CA, CH, BE, IN, HK, SG, …, or empty) files its AKA under `und` rather than
+// guessing (METADATA_KEYS.md §3).
+const MARKET_TO_LANG3: Record<string, string> = {
+    US: 'eng', GB: 'eng', AU: 'eng', NZ: 'eng', IE: 'eng',
+    FR: 'fra', DE: 'deu', AT: 'deu', ES: 'spa', MX: 'spa', AR: 'spa', CO: 'spa',
+    CL: 'spa', PE: 'spa', VE: 'spa', IT: 'ita', BR: 'por', PT: 'por', JP: 'jpn',
+    KR: 'kor', CN: 'zho', TW: 'zho', RU: 'rus', NL: 'nld', SE: 'swe', NO: 'nor',
+    DK: 'dan', FI: 'fin', PL: 'pol', TR: 'tur', CZ: 'ces', HU: 'hun', GR: 'ell',
+    IL: 'heb', TH: 'tha', VN: 'vie', ID: 'ind', UA: 'ukr', RO: 'ron', IR: 'fas',
+    SA: 'ara', EG: 'ara', AE: 'ara', BG: 'bul', HR: 'hrv', RS: 'srp', SK: 'slk',
+    SI: 'slv', EE: 'est', LV: 'lav', LT: 'lit', IS: 'isl',
+};
+
+function marketToLang3(market: string | undefined | null): string {
+    return (market && MARKET_TO_LANG3[market.trim().toUpperCase()]) || 'und';
+}
+
+/**
+ * `titles/<lang3>/<name>` key-set member key (METADATA_KEYS.md §3): trimmed,
+ * whitespace collapsed, `/` (the key-set separator) written as U+2215 `∕`.
+ * `undefined` when nothing is left to name.
+ */
+function titleMemberKey(lang3: string, name: string | undefined | null): string | undefined {
+    const clean = (name ?? '').trim().replace(/\s+/g, ' ').replace(/\//g, '\u2215');
+    return clean ? `titles/${lang3}/${clean}` : undefined;
+}
+
 let apiKey: string | null = null;
 let isV4Token = false;
 let metadataLanguage = 'en-US';
@@ -275,7 +251,17 @@ async function findByImdbId(imdbId: string): Promise<any> {
 
 async function getByTmdbId(tmdbId: string, mediaType: string): Promise<any> {
     try {
-        const config = getAxiosConfig({ language: metadataLanguage });
+        // `alternative_titles` rides along so the AKAs land in `titles/*` (§3).
+        // `images` rides the same call too: the poster candidates for the
+        // `posters/{lang3}/{cid}` key-set (§6). `language` would otherwise filter
+        // them to one language, so widen it to the configured one, English and
+        // textless (`null`).
+        const lang1 = metadataLanguage.split('-')[0];
+        const config = getAxiosConfig({
+            language: metadataLanguage,
+            append_to_response: 'alternative_titles,images',
+            include_image_language: [...new Set([lang1, 'en'])].join(',') + ',null',
+        });
         const response = await axios.get(`${BASE_URL}/${mediaType}/${tmdbId}`, config);
         return response.data;
     } catch {
@@ -352,6 +338,7 @@ async function downloadImageToWebDAV(
  * no need to store any path in the parent file's metadata.
  */
 async function downloadAndHashImage(
+    webdavClient: WebDAVClient | null,
     imagePath: string,
     imageType: string,
     title: string,
@@ -409,6 +396,9 @@ export async function process(
 ): Promise<void> {
     const startTime = Date.now();
     const metaCore = new MetaCoreClient(request.metaCoreUrl);
+    // WebDAV of the very core we're enriching, so poster blobs and the poster
+    // CIDs we write can never point at different cores. Cached per core URL.
+    const webdavClient = await getWebDAVClient(request.metaCoreUrl);
 
     try {
         const { cid, existingMeta } = request;
@@ -451,15 +441,26 @@ export async function process(
             console.log(`[tmdb] Force recompute enabled for ${request.filePath ?? existingMeta?.fileName ?? cid}`);
         }
 
-        // Get midhash for caching
+        const label = request.filePath ?? existingMeta?.fileName ?? cid;
-        const midhash = existingMeta?.['cid_midhash256'];
 
-        // Check cache (skip if forceRecompute)
+        // Exact-file cache, keyed by the file's byte-hash. Only records carrying
+        // real file bytes have `cid_midhash256`; gateway/usenet records don't —
+        // which is exactly why the per-tmdbid cache below exists. Stores a full
+        // entry now, but tolerates the legacy raw-payload format from older builds.
+        const midhash = existingMeta?.['cid_midhash256'];
         if (midhash && !forceRecompute) {
-            const cachedData = await readJson<any>(`${midhash}_tmdb.json`);
+            const cached = await readJson<any>(`${midhash}_aka_tmdb.json`);
-            if (cachedData) {
+            if (cached) {
-                console.log(`[tmdb] Using cached TMDB data for ${request.filePath ?? existingMeta?.fileName ?? cid}`);
+                console.log(`[tmdb] Using byte-hash cached TMDB data for ${label}`);
-                await applyTmdbData(metaCore, cid, cachedData);
+                const isEntry = cached.data !== undefined;
+                await applyTmdbData(
+                    metaCore,
+                    webdavClient,
+                    cid,
+                    isEntry ? cached.data : cached,
+                    // Legacy raw payloads carry no image CIDs → let applyTmdbData recompute.
+                    isEntry ? { posterCid: cached.posterCid, backdropCid: cached.backdropCid } : undefined
+                );
                 await sendCallback({
                     taskId: request.taskId,
                     status: 'completed',
@@ -469,54 +470,69 @@ export async function process(
             }
         }
 
-        let tmdbData = null;
+        // Resolve the show/movie entry, deduped per tmdbid. A record that already
-
+        // carries a tmdbid anchor (every gateway torrent/usenet hit does) takes
-        // Resolve by a known TMDB id first (authoritative — e.g. a gateway
+        // the cached + single-flighted fast path, so N releases of one show share
-        // anchor or jellyfin-nfo). Completes the full cycle (poster + plot +
+        // ONE TMDB fetch + poster seed instead of N.
-        // genres) from an id alone, with no fuzzy re-search.
+        let entry: TmdbCacheEntry | null = null;
         const knownTmdbId = existingMeta?.tmdbid;
         if (knownTmdbId) {
             const mediaType =
                 existingMeta?.videoType === 'tvshow' || existingMeta?.videoType === 'tv'
                     ? 'tv'
                     : 'movie';
-            tmdbData = await getByTmdbId(knownTmdbId, mediaType);
+            entry = await resolveEntryById(webdavClient, knownTmdbId, mediaType);
         }
 
-        // Try by IMDB ID
+        // Fallback: no usable id → resolve by IMDB id or fuzzy title, then cache
-        const imdbId = existingMeta?.imdbid;
+        // the result by its resolved tmdbid so later releases of the same show
-        if (!tmdbData && imdbId) {
+        // take the fast path above.
-            tmdbData = await findByImdbId(imdbId);
+        if (!entry) {
-        }
+            let tmdbData: any = null;
 
-        // Try by title search
+            const imdbId = existingMeta?.imdbid;
-        if (!tmdbData) {
+            if (imdbId) {
-            let title = existingMeta?.originalTitle || existingMeta?.fileName;
+                tmdbData = await findByImdbId(imdbId);
-            const year = existingMeta?.movieYear;
-            const videoType = existingMeta?.videoType;
-
-            // Strip trailing year from title if present (e.g., "Sintel 2010" -> "Sintel")
-            if (title && year) {
-                const yearRegex = new RegExp(`\\s*[\\(\\[]?${year}[\\)\\]]?\\s*$`);
-                title = title.replace(yearRegex, '').trim();
             }
 
-            if (title) {
+            if (!tmdbData) {
-                tmdbData = await searchByTitle(title, year, videoType);
+                let title = existingMeta?.originalTitle || existingMeta?.fileName;
+                const year = existingMeta?.movieYear;
+                const videoType = existingMeta?.videoType;
+
+                // Strip trailing year from title if present ("Sintel 2010" -> "Sintel").
+                if (title && year) {
+                    const yearRegex = new RegExp(`\\s*[\\(\\[]?${year}[\\)\\]]?\\s*$`);
+                    title = title.replace(yearRegex, '').trim();
+                }
+
+                if (title) {
+                    tmdbData = await searchByTitle(title, year, videoType);
+                }
+            }
+
+            if (tmdbData) {
+                const images = await computeImageCids(webdavClient, tmdbData);
+                entry = { data: tmdbData, ...images };
+                if (tmdbData.id) {
+                    await writeJson(tmdbCacheKey(String(tmdbData.id), mediaTypeOf(tmdbData)), entry);
+                }
             }
         }
 
-        if (tmdbData) {
+        if (entry) {
-            await applyTmdbData(metaCore, cid, tmdbData);
+            await applyTmdbData(metaCore, webdavClient, cid, entry.data, {
-
+                posterCid: entry.posterCid,
-            // Cache TMDB data for future use
+                backdropCid: entry.backdropCid,
+            });
+            // Keep the exact-file cache warm too, so a future re-enrichment of
+            // this same file skips straight to the byte-hash hit.
             if (midhash) {
-                await writeJson(`${midhash}_tmdb.json`, tmdbData);
+                await writeJson(`${midhash}_aka_tmdb.json`, entry);
             }
-
+            console.log(`[tmdb] Enriched ${label} (tmdbid=${entry.data.id})`);
-            console.log(`[tmdb] Fetched TMDB data for ${request.filePath ?? existingMeta?.fileName ?? cid}`);
         } else {
-            console.log(`[tmdb] No TMDB match found for ${request.filePath ?? existingMeta?.fileName ?? cid}`);
+            console.log(`[tmdb] No TMDB match found for ${label}`);
         }
 
         await sendCallback({
@@ -534,14 +550,111 @@ export async function process(
     }
 }
 
+/** Resolved TMDB payload plus the seeded poster/backdrop CIDs, cached per
+ *  tmdbid. Every torrent/usenet release of an episode carries the same
+ *  `tmdbid`, and TMDB only gives us show/movie-level fields (poster, plot,
+ *  genres — no per-episode data), so N releases can share ONE fetch + seed. */
+interface TmdbCacheEntry {
+    data: any;
+    posterCid: string | null;
+    backdropCid: string | null;
+}
+
+// In-process single-flight: collapses concurrent resolves of the same key onto
+// one promise, so a burst of same-tmdbid records that all miss the cold cache
+// triggers a single TMDB fetch (no thundering herd) — the rest await it.
+const tmdbEntryInflight = new Map<string, Promise<TmdbCacheEntry | null>>();
+
+// Persistent cache filename for a resolved show/movie. Includes mediaType +
+// language so a tv/movie id clash or a language switch can't return stale text.
+function tmdbCacheKey(tmdbId: string, mediaType: string): string {
+    // `_aka`: entries written before `alternative_titles` was appended carry no
+    // AKAs, so the name moved to make them refetch once.
+    return `tmdbid_${mediaType}_${tmdbId}_${metadataLanguage}_aka_tmdb.json`;
+}
+
+// Media type from a raw TMDB payload's own shape (tv payloads carry
+// name/first_air_date). Mirrors the check in applyTmdbData.
+function mediaTypeOf(data: any): string {
+    return data?.first_air_date !== undefined ||
+        data?.name !== undefined ||
+        data?.original_name !== undefined
+        ? 'tv'
+        : 'movie';
+}
+
+// Download + hash the poster/backdrop for a resolved payload. Record-independent
+// (the image filename is keyed by tmdbId, so the blob dedups across records), so
+// the CIDs can be computed once per show and reused for every release.
+async function computeImageCids(
+    webdavClient: WebDAVClient | null,
+    data: any
+): Promise<{ posterCid: string | null; backdropCid: string | null }> {
+    const tmdbId = data?.id ? String(data.id) : '';
+    const displayTitle =
+        data?.title || data?.name || data?.original_title || data?.original_name || 'Unknown';
+    const releaseDate = data?.release_date || data?.first_air_date;
+    const year = releaseDate ? releaseDate.split('-')[0] : undefined;
+    const posterCid =
+        data?.poster_path && tmdbId
+            ? await downloadAndHashImage(webdavClient, data.poster_path, 'poster', displayTitle, year, tmdbId)
+            : null;
+    const backdropCid =
+        data?.backdrop_path && tmdbId
+            ? await downloadAndHashImage(webdavClient, data.backdrop_path, 'backdrop', displayTitle, year, tmdbId)
+            : null;
+    return { posterCid, backdropCid };
+}
+
+// Resolve the full entry (payload + image CIDs) for a KNOWN tmdbid, served from
+// the persistent per-tmdbid cache when possible and single-flighted otherwise.
+// This is the hot path for gateway records (torrent + usenet), which always
+// carry a `tmdbid` anchor — so N releases of one show share one TMDB fetch.
+async function resolveEntryById(
+    webdavClient: WebDAVClient | null,
+    tmdbId: string,
+    mediaType: string
+): Promise<TmdbCacheEntry | null> {
+    const key = tmdbCacheKey(tmdbId, mediaType);
+    if (!forceRecompute) {
+        const cached = await readJson<TmdbCacheEntry>(key);
+        if (cached?.data) {
+            return cached;
+        }
+    }
+    const inflight = tmdbEntryInflight.get(key);
+    if (inflight) {
+        return inflight;
+    }
+    const pending = (async (): Promise<TmdbCacheEntry | null> => {
+        console.log(`[tmdb] Resolving TMDB ${mediaType}/${tmdbId} (cache miss)`);
+        const data = await getByTmdbId(tmdbId, mediaType);
+        if (!data) {
+            return null;
+        }
+        const images = await computeImageCids(webdavClient, data);
+        const entry: TmdbCacheEntry = { data, ...images };
+        await writeJson(key, entry);
+        return entry;
+    })();
+    tmdbEntryInflight.set(key, pending);
+    try {
+        return await pending;
+    } finally {
+        tmdbEntryInflight.delete(key);
+    }
+}
+
 /**
  * Apply TMDB data to KV store using same keys as old TMDBProcessor
  */
 async function applyTmdbData(
     metaCore: MetaCoreClient,
+    webdavClient: WebDAVClient | null,
     cid: string,
-    data: any
+    data: any,
-): Promise<void> {
+    images?: { posterCid: string | null; backdropCid: string | null }
+): Promise<{ posterCid: string | null; backdropCid: string | null }> {
     const metadata: Record<string, string> = {};
 
     // Basic IDs
@@ -564,6 +677,10 @@ async function applyTmdbData(
         data.original_name !== undefined;
     metadata.videoType = isTv ? 'tvshow' : 'movie';
     metadata.contentKind = isTv ? 'episode' : 'movie';
+    // `domain` is written in the same breath as `contentKind`
+    // (METADATA_KEYS.md §1) — it is the key meta-watch filters its wall on,
+    // and TMDB is precisely the identity graph that decides film vs tv here.
+    metadata.domain = isTv ? 'tv' : 'film';
 
     // Title - store both original and localized
     const originalTitle = data.original_title || data.original_name;
@@ -580,6 +697,23 @@ async function applyTmdbData(
         metadata.originalTitle = originalTitle;
     }
 
+    // Every clean name as a `titles/<lang3>/<name>` key-set member
+    // (METADATA_KEYS.md §3): the localized title under the configured metadata
+    // language, the original title under TMDB's `original_language`, and each
+    // AKA under the language its market implies (`und` when it doesn't).
+    const addTitleMember = (lang3: string, name: string | undefined) => {
+        const key = titleMemberKey(lang3, name);
+        if (key) metadata[key] = 'true';
+    };
+    addTitleMember(iso639_1to3(metadataLanguage.split('-')[0]) ?? 'und', localizedTitle);
+    addTitleMember(iso639_1to3(data.original_language) ?? 'und', originalTitle);
+    const akas = data.alternative_titles?.titles ?? data.alternative_titles?.results;
+    if (Array.isArray(akas)) {
+        for (const aka of akas) {
+            addTitleMember(marketToLang3(aka?.iso_3166_1), aka?.title);
+        }
+    }
+
     // Dates
     const releaseDate = data.release_date || data.first_air_date;
     let year: string | undefined;
@@ -594,9 +728,8 @@ async function applyTmdbData(
     // Plot (in configured language)
     if (data.overview) {
         // Extract language code from metadataLanguage (e.g., 'en-US' -> 'eng')
-        const langCode = metadataLanguage.split('-')[0];
+        const langKey = iso639_1to3(metadataLanguage.split('-')[0]);
-        const langKey = langCode === 'en' ? 'eng' : langCode;
+        if (langKey) metadata[`plot/${langKey}`] = data.overview;
-        metadata[`plot/${langKey}`] = data.overview;
         // Also set as primary plot for compatibility
         metadata['plot/eng'] = data.overview;
     }
@@ -625,35 +758,37 @@ async function applyTmdbData(
     // Add tmdb-verified tag (same as old processor)
     await metaCore.addToSet(cid, 'tags', 'tmdb-verified');
 
-    // Download poster and backdrop images to plugin output folder. The
+    // Poster/backdrop CIDs. Reuse the precomputed values when the caller already
-    // watcher picks them up as first-class file entries, so all we need to
+    // seeded them (a per-tmdbid cache hit — so we don't re-download + re-hash the
-    // store is the CID — `/api/file/{cid}` resolves through the standard
+    // same image for every release of a show); otherwise download + hash now.
-    // reverse index, no path companion needed.
+    // The image filename is keyed by tmdbId, so the blob is deduped either way —
-    if (data.poster_path && tmdbId) {
+    // this just also skips the WebDAV round-trips. The watcher picks the images
-        const posterCid = await downloadAndHashImage(
+    // up as first-class file entries, so storing the CID is all that's needed.
-            data.poster_path,
+    let posterCid = images ? images.posterCid : null;
-            'poster',
+    if (!images && data.poster_path && tmdbId) {
-            displayTitle,
+        posterCid = await downloadAndHashImage(webdavClient, data.poster_path, 'poster', displayTitle, year, tmdbId);
-            year,
+    }
-            tmdbId
+    if (posterCid) {
-        );
+        await metaCore.setProperty(cid, 'poster', posterCid);
-        if (posterCid) {
+        console.log(`[tmdb] Set poster CID: ${posterCid}`);
-            await metaCore.setProperty(cid, 'poster', posterCid);
+        // The alternatives, as the `posters/{lang3}/{cid}` key-set with `poster`
-            console.log(`[tmdb] Set poster CID: ${posterCid}`);
+        // among them (METADATA_KEYS.md §6). Leaf keys through PATCH — never
+        // addToSet, which writes the legacy comma-joined csv-set. Empty for a
+        // cached payload from before the `images` append: no backfill by design.
+        const members = posterMembers(data, posterCid);
+        if (Object.keys(members).length > 0) {
+            await metaCore.mergeMetadata(cid, members);
         }
     }
 
-    if (data.backdrop_path && tmdbId) {
+    let backdropCid = images ? images.backdropCid : null;
-        const backdropCid = await downloadAndHashImage(
+    if (!images && data.backdrop_path && tmdbId) {
-            data.backdrop_path,
+        backdropCid = await downloadAndHashImage(webdavClient, data.backdrop_path, 'backdrop', displayTitle, year, tmdbId);
-            'backdrop',
-            displayTitle,
-            year,
-            tmdbId
-        );
-        if (backdropCid) {
-            await metaCore.setProperty(cid, 'backdrop', backdropCid);
-            console.log(`[tmdb] Set backdrop CID: ${backdropCid}`);
-        }
     }
+    if (backdropCid) {
+        await metaCore.setProperty(cid, 'backdrop', backdropCid);
+        console.log(`[tmdb] Set backdrop CID: ${backdropCid}`);
+    }
+
+    return { posterCid, backdropCid };
 }

src/posters.ts

@@ -0,0 +1,102 @@
+/**
+ * The `posters/{lang3}/{cid}` key-set for a TMDB-enriched video record
+ * (METADATA_KEYS.md §6): the primary poster plus the best-voted alternatives.
+ *
+ * CROSS-BINARY CONTRACT: same ranking, cap, CDN size and language rule as the
+ * tmdb card feeder's `poster_member_keys`
+ * (`meta-feeder-tmdb/feeder-plugin/card-feeder/src/card.rs`).
+ */
+
+import { encodeUrlCid } from './cid.js';
+
+/** Most members a record's `posters/*` key-set may carry, the primary included. */
+export const MAX_POSTER_MEMBERS = 10;
+
+/**
+ * CDN root + size the alternatives are referenced at. `w500`, as the card
+ * feeder's `poster_url`, so both writers mint the same locator for one image.
+ */
+export const ALT_POSTER_BASE_URL = 'https://image.tmdb.org/t/p/w500';
+
+/** One entry of a TMDB details payload's `images.posters` (`append_to_response=images`). */
+export interface TmdbImage {
+    file_path?: string;
+    iso_639_1?: string | null;
+    vote_average?: number;
+    vote_count?: number;
+}
+
+/**
+ * ISO 639-1 → ISO 639-3 (`lang3`), the 639-2/T form where B and T differ
+ * (`fra`, `deu`, `zho` — never `fre`/`ger`/`chi`). Mirrors the card feeder's
+ * `iso639_1_to_3` table.
+ */
+const ISO639_1_TO_3: Record<string, string> = {
+    en: 'eng', ja: 'jpn', fr: 'fra', de: 'deu', es: 'spa', it: 'ita', ru: 'rus',
+    ko: 'kor', zh: 'zho', pt: 'por', nl: 'nld', sv: 'swe', no: 'nor', da: 'dan',
+    fi: 'fin', pl: 'pol', tr: 'tur', ar: 'ara', hi: 'hin', th: 'tha', vi: 'vie',
+    id: 'ind', cs: 'ces', el: 'ell', he: 'heb', hu: 'hun', ro: 'ron', uk: 'ukr',
+    fa: 'fas', ms: 'msa', tl: 'tgl', ca: 'cat', nb: 'nob',
+};
+
+/**
+ * The language segment for a poster: that of the text printed on it. `zxx`
+ * (no linguistic content) when TMDB gives none — a textless poster — and
+ * `und` for a code outside the table.
+ */
+export function posterLang3(code: string | null | undefined): string {
+    const trimmed = (code ?? '').trim().toLowerCase();
+    if (!trimmed) return 'zxx';
+    return ISO639_1_TO_3[trimmed] ?? 'und';
+}
+
+function compareCandidates(a: TmdbImage, b: TmdbImage): number {
+    const byAverage = (b.vote_average ?? 0) - (a.vote_average ?? 0);
+    if (byAverage !== 0) return byAverage;
+    const byCount = (b.vote_count ?? 0) - (a.vote_count ?? 0);
+    if (byCount !== 0) return byCount;
+    const pa = a.file_path ?? '';
+    const pb = b.file_path ?? '';
+    return pa < pb ? -1 : pa > pb ? 1 : 0;
+}
+
+/**
+ * The `posters/{lang3}/{cid}` members to merge onto a record whose `poster` is
+ * `primaryPosterCid`. The primary is always a member, filed under the language
+ * of its own `images.posters` entry (`und` if TMDB did not list it); the
+ * alternatives follow as `url` locators, ranked by `vote_average`, then
+ * `vote_count`, then `file_path` (so equal payloads give equal keys), capped at
+ * {@link MAX_POSTER_MEMBERS} in total.
+ *
+ * Returns `{}` when the payload has no image list — a cached entry from before
+ * the `images` append. Without one the primary's language is unknown, and a set
+ * is better absent than mislabelled.
+ */
+export function posterMembers(data: any, primaryPosterCid: string): Record<string, 'true'> {
+    const candidates: TmdbImage[] = Array.isArray(data?.images?.posters) ? data.images.posters : [];
+    if (candidates.length === 0 || !primaryPosterCid) {
+        return {};
+    }
+    const primaryPath: string | undefined = data?.poster_path;
+    const members: Record<string, 'true'> = {};
+
+    const primary = candidates.find((img) => !!img.file_path && img.file_path === primaryPath);
+    const primaryLang = primary ? posterLang3(primary.iso_639_1) : 'und';
+    members[`posters/${primaryLang}/${primaryPosterCid}`] = 'true';
+    let count = 1;
+
+    const ranked = candidates
+        .filter((img) => typeof img.file_path === 'string' && img.file_path.trim() !== '' && img.file_path !== primaryPath)
+        .sort(compareCandidates);
+    for (const img of ranked) {
+        if (count >= MAX_POSTER_MEMBERS) break;
+        const cid = encodeUrlCid(`${ALT_POSTER_BASE_URL}/${img.file_path!.replace(/^\/+/, '')}`);
+        if (!cid) continue;
+        const key = `posters/${posterLang3(img.iso_639_1)}/${cid}`;
+        if (!(key in members)) {
+            members[key] = 'true';
+            count++;
+        }
+    }
+    return members;
+}

src/webdav-client.ts

@@ -136,15 +136,64 @@ export class WebDAVClient {
 }
 
 /**
- * Create a WebDAV client from environment variables
+ * WebDAV client for the meta-core that drove a /process call.
+ *
+ * The endpoint is read from that core's own /urls (`webdavUrlInternal`),
+ * so blobs always land in the /files of the core we write metadata to. A feeder
+ * whose plugins run beside it but enrich a remote hub core needs no per-stack
+ * wiring, and it is impossible to write posters into one core while pointing
+ * CIDs at another.
+ *
+ * WEBDAV_URL still wins when set — an explicit override for tests and for
+ * topologies where the core's advertised internal URL isn't reachable from here.
+ *
+ * Resolutions are cached per meta-core URL; failures are not, so a core that is
+ * still starting up is retried on the next task.
  */
-export function createWebDAVClient(): WebDAVClient | null {
+const clientCache = new Map<string, Promise<WebDAVClient | null>>();
-    const webdavUrl = process.env.WEBDAV_URL;
 
-    if (!webdavUrl) {
+async function resolveWebDAVUrl(metaCoreUrl: string): Promise<string | null> {
-        console.warn('[webdav-client] WEBDAV_URL not set, WebDAV client unavailable');
+    // /urls, not /api/urls — metaCoreUrl points at the meta-core backend, whose
-        return null;
+    // discovery routes are unprefixed (same base the /meta/* writes use).
+    const base = metaCoreUrl.replace(/\/$/, '');
+    const response = await fetch(`${base}/urls`, { signal: AbortSignal.timeout(5000) });
+
+    if (!response.ok) {
+        throw new Error(`GET ${base}/urls failed: ${response.status} ${response.statusText}`);
     }
 
-    return new WebDAVClient(webdavUrl);
+    const urls = await response.json() as { webdavUrlInternal?: string; webdavUrl?: string };
+    return urls.webdavUrlInternal ?? urls.webdavUrl ?? null;
+}
+
+export async function getWebDAVClient(metaCoreUrl: string): Promise<WebDAVClient | null> {
+    const override = process.env.WEBDAV_URL;
+    if (override) {
+        return new WebDAVClient(override);
+    }
+
+    let pending = clientCache.get(metaCoreUrl);
+    if (!pending) {
+        pending = resolveWebDAVUrl(metaCoreUrl).then((webdavUrl) => {
+            if (!webdavUrl) {
+                console.warn(`[webdav-client] meta-core ${metaCoreUrl} advertises no WebDAV URL`);
+                return null;
+            }
+            console.log(`[webdav-client] Using WebDAV endpoint ${webdavUrl} (from ${metaCoreUrl})`);
+            return new WebDAVClient(webdavUrl);
+        });
+        clientCache.set(metaCoreUrl, pending);
+    }
+
+    try {
+        const client = await pending;
+        if (!client) {
+            clientCache.delete(metaCoreUrl);
+        }
+        return client;
+    } catch (error) {
+        clientCache.delete(metaCoreUrl);
+        console.warn(`[webdav-client] Failed to resolve WebDAV URL from ${metaCoreUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
 }

test/posters.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { encodeUrlCid } from '../src/cid.js';
+import { ALT_POSTER_BASE_URL, MAX_POSTER_MEMBERS, posterLang3, posterMembers, type TmdbImage } from '../src/posters.js';
+
+const alt = (path: string) => encodeUrlCid(`${ALT_POSTER_BASE_URL}${path}`)!;
+const img = (file_path: string, iso_639_1: string | null, vote_average = 0, vote_count = 0): TmdbImage => ({
+    file_path,
+    iso_639_1,
+    vote_average,
+    vote_count,
+});
+
+describe('encodeUrlCid', () => {
+    // Same vectors as meta-feeder-tmdb's vendored `hash.rs::url_cid_matches_pinned_vectors`.
+    it('matches the pinned Rust vectors', () => {
+        expect(encodeUrlCid('https://image.tmdb.org/t/p/w500/dqZENchTd7lp5zit1Q7Bkjzcxpi.jpg')).toBe(
+            'bagdcaab7nb2hi4dthixs62lnmftwkltunvsgeltpojts65bpoaxxonjqgaxwi4k2ivhgg2cumq3wy4bvpjuximkrg5bgw2t2mn4ha2jonjygo',
+        );
+    });
+
+    it('uses a two-byte length varint past 127 bytes', () => {
+        const long = `https://image.tmdb.org/t/p/w500/${'a'.repeat(100)}.jpg`;
+        expect(long.length).toBe(136);
+        expect(encodeUrlCid(long)).toBe(
+            'bagdcaaeiafuhi5dqom5c6l3jnvqwozjoorwwiyron5zgol3uf5yc65zvgayc6ylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcylbmfqwcltkobtq',
+        );
+    });
+
+    it('rejects anything but an absolute http(s) URL', () => {
+        expect(encodeUrlCid('/relative.jpg')).toBeNull();
+        expect(encodeUrlCid('ftp://example.com/x.jpg')).toBeNull();
+        expect(encodeUrlCid('')).toBeNull();
+    });
+});
+
+describe('posterLang3', () => {
+    it('maps to ISO 639-3, never 639-2/B', () => {
+        expect(posterLang3('fr')).toBe('fra');
+        expect(posterLang3('de')).toBe('deu');
+        expect(posterLang3('EN')).toBe('eng');
+    });
+
+    it('files a textless poster under zxx and an unknown code under und', () => {
+        expect(posterLang3(null)).toBe('zxx');
+        expect(posterLang3(undefined)).toBe('zxx');
+        expect(posterLang3('xx')).toBe('und');
+    });
+});
+
+describe('posterMembers', () => {
+    const PRIMARY_CID = 'bagacbabaecontentcid';
+
+    it('lists the primary under its own language, once, beside the alternatives', () => {
+        const data = {
+            poster_path: '/primary.jpg',
+            images: {
+                posters: [img('/alt-fr.jpg', 'fr', 5.5, 10), img('/primary.jpg', 'ja', 5, 3), img('/textless.jpg', null, 6, 1)],
+            },
+        };
+        expect(posterMembers(data, PRIMARY_CID)).toEqual({
+            [`posters/jpn/${PRIMARY_CID}`]: 'true',
+            [`posters/zxx/${alt('/textless.jpg')}`]: 'true',
+            [`posters/fra/${alt('/alt-fr.jpg')}`]: 'true',
+        });
+    });
+
+    it('ranks by vote_average then vote_count, and caps at ten including the primary', () => {
+        const posters = Array.from({ length: 15 }, (_, i) => img(`/p${String(i).padStart(2, '0')}.jpg`, 'en', i, 1));
+        const keys = Object.keys(posterMembers({ poster_path: '/primary.jpg', images: { posters } }, PRIMARY_CID));
+        expect(keys).toHaveLength(MAX_POSTER_MEMBERS);
+        expect(keys[0]).toBe(`posters/und/${PRIMARY_CID}`);
+        expect(keys[1]).toBe(`posters/eng/${alt('/p14.jpg')}`);
+        expect(keys).not.toContain(`posters/eng/${alt('/p05.jpg')}`);
+
+        const tie = Object.keys(
+            posterMembers(
+                { poster_path: '/primary.jpg', images: { posters: [img('/few.jpg', null, 5, 1), img('/many.jpg', null, 5, 9)] } },
+                PRIMARY_CID,
+            ),
+        );
+        expect(tie[1]).toBe(`posters/zxx/${alt('/many.jpg')}`);
+    });
+
+    it('writes no set when the payload has no image list', () => {
+        expect(posterMembers({ poster_path: '/primary.jpg' }, PRIMARY_CID)).toEqual({});
+        expect(posterMembers({ poster_path: '/primary.jpg', images: { posters: [] } }, PRIMARY_CID)).toEqual({});
+    });
+});

vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: 'node',
+        include: ['test/**/*.test.ts'],
+    },
+});