improve search and fix languages

src/plugin.ts

@@ -21,11 +21,17 @@
  * Matroska stream tags already carry. A `fra` member would be dropped by a
  * `languages:fre` filter.
  *
- * ⚠ Audio only. Consumers read `languages/*` as the AUDIO-language set
+ * ⚠ Audio only as a SOURCE — but it writes two keys, not one. This plugin reads
- * (meta-watch `cards::audio_languages`); subtitle-track languages belong to
+ * audio tracks, so the codes it finds are audio languages and land in
- * `subtitleLanguages/*` (subtitle-extractor). Title keys are not a source
+ * `audioLanguages/<lang3>`; every one of them is ALSO written to
- * either: `titles/<lang>` names the language of a TITLE (tmdb files
+ * `languages/<lang3>`, the union that queries filter on (METADATA_KEYS §9,
- * `originalTitle` under `original_language`), not of the file's audio.
+ * rule #7 — "a union field is written, never computed"). Nothing reconciles the
+ * two after the fact, so a record with the split set and the union unset is
+ * invisible to every language filter on every peer. Subtitle-track languages
+ * belong to `subtitleLanguages/*` (subtitle-extractor), which owes the union
+ * member for the same reason. Title keys are not a source either:
+ * `titles/<lang>` names the language of a TITLE (tmdb files `originalTitle`
+ * under `original_language`), not of the file's audio.
  *
  * ⚠ No `titles/*` write. The old `titles/{firstAudioLang || 'eng'}` =
  * `originalTitle` guess overwrote better identity (tmdb, jellyfin-nfo,
@@ -41,8 +47,8 @@ import { MetaCoreClient } from './meta-core-client.js';
 export const manifest: PluginManifest = {
     id: 'language',
     name: 'Language Aggregator',
-    version: '1.1.0',
+    version: '1.2.0',
-    description: 'Adds audio-track languages to the languages/<lang3> key-set',
+    description: 'Adds audio-track languages to the audioLanguages/<lang3> and languages/<lang3> key-sets',
     author: 'MetaMesh',
     dependencies: ['ffmpeg'],
     priority: 40,
@@ -50,6 +56,7 @@ export const manifest: PluginManifest = {
     defaultQueue: 'fast',
     timeout: 30000,
     schema: {
+        audioLanguages: { label: 'Audio languages', type: 'array', readonly: true },
         languages: { label: 'Languages', type: 'array', readonly: true },
     },
     config: {},
@@ -170,23 +177,41 @@ export function audioLanguagesFromMeta(existingMeta: Record<string, unknown> | u
 }
 
 /**
- * Whether the record already carries `languages/<code>`, in either shape: the
+ * Whether the record already carries `<field>/<code>`, in either shape: the flat
- * flat key, or the nested `languages: { <code>: ... }` object meta-sort's
+ * key, or the nested `<field>: { <code>: ... }` object meta-sort's reconstructed
- * reconstructed document holds.
+ * document holds.
  */
-function hasMember(existingMeta: Record<string, unknown> | undefined, code: string): boolean {
+function hasMember(
+    existingMeta: Record<string, unknown> | undefined,
+    field: string,
+    code: string,
+): boolean {
     if (!existingMeta) return false;
-    if (existingMeta[`languages/${code}`] !== undefined) return true;
+    if (existingMeta[`${field}/${code}`] !== undefined) return true;
-    const nested = existingMeta['languages'];
+    const nested = existingMeta[field];
     return !!nested && typeof nested === 'object' && !Array.isArray(nested)
         && (nested as Record<string, unknown>)[code] !== undefined;
 }
 
-/** The `languages/<code>` members to add — never one the record already has. */
+/**
+ * The members to add — never one the record already has.
+ *
+ * Each audio code is written TWICE: once to `audioLanguages/<code>` (what this
+ * plugin actually observed — a spoken track) and once to `languages/<code>`
+ * (the union every query filters on). METADATA_KEYS §9 rule #7 makes the second
+ * write mandatory, not a convenience: the union is stored, never computed, and
+ * a query cannot ask for `audioLanguages OR subtitleLanguages` — the gateway
+ * wire ANDs across keys, so an OR of the splits would return strictly less.
+ */
 export function languageWrites(existingMeta: Record<string, unknown> | undefined): Record<string, string> {
     const writes: Record<string, string> = {};
     for (const code of audioLanguagesFromMeta(existingMeta)) {
-        if (!hasMember(existingMeta, code)) writes[`languages/${code}`] = 'true';
+        if (!hasMember(existingMeta, 'audioLanguages', code)) {
+            writes[`audioLanguages/${code}`] = 'true';
+        }
+        if (!hasMember(existingMeta, 'languages', code)) {
+            writes[`languages/${code}`] = 'true';
+        }
     }
     return writes;
 }

test/language.test.ts

@@ -164,18 +164,47 @@ describe('audioLanguagesFromMeta', () => {
 });
 
 describe('languageWrites', () => {
-    it('skips members already present in the flat or nested form', () => {
+    it('writes each audio code to BOTH the split and the union (METADATA_KEYS §9 rule #7)', () => {
-        expect(languageWrites(nestedDoc({ 'languages/jpn': 'true' }))).toEqual({ 'languages/eng': 'true' });
+        expect(languageWrites(nestedDoc())).toEqual({
-        expect(languageWrites(nestedDoc({ languages: { eng: 'true', jpn: true } }))).toEqual({});
+            'audioLanguages/jpn': 'true',
+            'languages/jpn': 'true',
+            'audioLanguages/eng': 'true',
+            'languages/eng': 'true',
+        });
+    });
+
+    it('skips members already present in the flat or nested form, per field', () => {
+        // The union is already there; the split is not — the record still owes
+        // the split, and vice versa. The two are tracked independently.
+        expect(languageWrites(nestedDoc({ 'languages/jpn': 'true' }))).toEqual({
+            'audioLanguages/jpn': 'true',
+            'audioLanguages/eng': 'true',
+            'languages/eng': 'true',
+        });
+        expect(languageWrites(nestedDoc({ languages: { eng: 'true', jpn: true } }))).toEqual({
+            'audioLanguages/jpn': 'true',
+            'audioLanguages/eng': 'true',
+        });
+        expect(
+            languageWrites(nestedDoc({ audioLanguages: { eng: 'true', jpn: 'true' }, languages: { eng: 'true', jpn: 'true' } })),
+        ).toEqual({});
     });
 });
 
 describe('process', () => {
-    it('writes the audio languages/* key-set from the nested payload in one merge', async () => {
+    it('writes the audio split AND the union from the nested payload in one merge', async () => {
         const { callback, writer } = await run(nestedDoc());
         expect(callback?.status).toBe('completed');
         expect(writer.calls).toEqual([
-            { hashId: 'cid-1', metadata: { 'languages/jpn': 'true', 'languages/eng': 'true' } },
+            {
+                hashId: 'cid-1',
+                metadata: {
+                    'audioLanguages/jpn': 'true',
+                    'languages/jpn': 'true',
+                    'audioLanguages/eng': 'true',
+                    'languages/eng': 'true',
+                },
+            },
         ]);
     });
 
@@ -183,19 +212,32 @@ describe('process', () => {
         const flat = Object.fromEntries(REAL_STREAMS.map((s, i) => [`stream/${i}`, s]));
         const { callback, writer } = await run(flat);
         expect(callback?.status).toBe('completed');
-        expect(writer.calls[0].metadata).toEqual({ 'languages/jpn': 'true', 'languages/eng': 'true' });
+        expect(writer.calls[0].metadata).toEqual({
+            'audioLanguages/jpn': 'true',
+            'languages/jpn': 'true',
+            'audioLanguages/eng': 'true',
+            'languages/eng': 'true',
+        });
     });
 
-    it('never writes titles/* or any non-languages key, even with originalTitle and title keys', async () => {
+    it('every split member has a matching union member — the record is never left half-written', async () => {
-        const { writer } = await run(nestedDoc({ 'titles/eng': 'Better Title', titles: { jpn: '番組' } }));
+        const { writer } = await run(nestedDoc());
+        const keys = writer.calls.flatMap((c) => Object.keys(c.metadata));
+        for (const k of keys.filter((k) => k.startsWith('audioLanguages/'))) {
+            expect(keys).toContain(`languages/${k.slice('audioLanguages/'.length)}`);
+        }
+    });
+
+    it('never writes titles/* or any non-language key, even with originalTitle and title keys', async () => {
+        const { writer } = await run(nestedDoc({ 'titles/eng/Better Title': 'true', titles: { jpn: { '番組': 'true' } } }));
         const keys = writer.calls.flatMap((c) => Object.keys(c.metadata));
         expect(keys.length).toBeGreaterThan(0);
-        expect(keys.every((k) => k.startsWith('languages/'))).toBe(true);
+        expect(keys.every((k) => k.startsWith('languages/') || k.startsWith('audioLanguages/'))).toBe(true);
         expect(keys.some((k) => k.startsWith('titles'))).toBe(false);
     });
 
     it('does not derive languages from title keys', async () => {
-        const { callback, writer } = await run({ originalTitle: 'x', 'titles/jpn': 'y', 'titles/jpl': 'z' });
+        const { callback, writer } = await run({ originalTitle: 'x', 'titles/jpn/y': 'true', 'titles/jpl/z': 'true' });
         expect(callback?.status).toBe('completed');
         expect(writer.calls).toEqual([]);
     });
@@ -209,10 +251,23 @@ describe('process', () => {
     });
 
     it('is idempotent: a re-run over a record that already has the members writes nothing', async () => {
-        const { writer } = await run(nestedDoc({ 'languages/jpn': 'true', 'languages/eng': 'true' }));
+        const { writer } = await run(nestedDoc({
+            'audioLanguages/jpn': 'true', 'audioLanguages/eng': 'true',
+            'languages/jpn': 'true', 'languages/eng': 'true',
+        }));
         expect(writer.calls).toEqual([]);
     });
 
+    it('backfills the union on a record written before the split existed', async () => {
+        // Pre-1.2.0 records carry only `languages/*`. A re-run must add the
+        // split without disturbing the union that is already correct.
+        const { writer } = await run(nestedDoc({ 'languages/jpn': 'true', 'languages/eng': 'true' }));
+        expect(writer.calls[0].metadata).toEqual({
+            'audioLanguages/jpn': 'true',
+            'audioLanguages/eng': 'true',
+        });
+    });
+
     it('fails the task when the write is rejected', async () => {
         const { callback } = await run(nestedDoc(), new RecordingWriter(false));
         expect(callback?.status).toBe('failed');