From 9280e23e83d08f0680cd5b705ac9f47edfca82f2 Mon Sep 17 00:00:00 2001
From: Worph <worph@users.noreply.github.com>
Date: Mon, 14 Sep 2026 22:30:13 +0200
Subject: [PATCH] improve search and fix languages

---
 .../src/lib/metadata-type/LanguagesMeta.ts    | 19 +++++++++++++++++--
 .../lib/metadata-type/basic/LanguageData.ts   | 18 +++++++++++++++---
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/packages/shared/meta-interface/src/lib/metadata-type/LanguagesMeta.ts b/packages/shared/meta-interface/src/lib/metadata-type/LanguagesMeta.ts
index caab411..0eb6788 100644
--- a/packages/shared/meta-interface/src/lib/metadata-type/LanguagesMeta.ts
+++ b/packages/shared/meta-interface/src/lib/metadata-type/LanguagesMeta.ts
@@ -1,10 +1,25 @@
 import {TypedRecordSet} from "./basic/RecordSet.js";
-import {ISO639_1_CODE} from "./basic/LanguageData.js";
+import {LANG3_CODE} from "./basic/LanguageData.js";
 
+/**
+ * The language triad (METADATA_KEYS.md §9).
+ *
+ * `languages` is the **union** — every language the record offers by any route
+ * — and the only one a query filters on. The two splits refine it and are
+ * optional. Rule #7: a writer that adds a member to a split MUST add the same
+ * member to the union in the same write; nothing reconciles them afterwards.
+ */
 export interface LanguagesMeta{
-    languages?: TypedRecordSet<ISO639_1_CODE>;
+    /** The union: audio ∪ subtitles ∪ bare language statements. Filterable. */
+    languages?: TypedRecordSet<LANG3_CODE>;
+    /** Spoken/audio-track languages only. Refinement, never filtered on. */
+    audioLanguages?: TypedRecordSet<LANG3_CODE>;
+    /** Subtitle languages only (§8). Refinement, never filtered on. */
+    subtitleLanguages?: TypedRecordSet<LANG3_CODE>;
 }
 
 export const LanguagesMetaFields = [
     "languages",
+    "audioLanguages",
+    "subtitleLanguages",
 ];
\ No newline at end of file
diff --git a/packages/shared/meta-interface/src/lib/metadata-type/basic/LanguageData.ts b/packages/shared/meta-interface/src/lib/metadata-type/basic/LanguageData.ts
index 5f44425..3019a93 100644
--- a/packages/shared/meta-interface/src/lib/metadata-type/basic/LanguageData.ts
+++ b/packages/shared/meta-interface/src/lib/metadata-type/basic/LanguageData.ts
@@ -1,9 +1,21 @@
 /**
- * key is language ISO 639-3 code
- * https://en.wikipedia.org/wiki/List_of_ISO_639-3_codes
+ * key is a `lang3` code: ISO 639-2/**B** — `eng`, `jpn`, `fre`/`ger`/`chi`,
+ * NOT the 639-2/T (= 639-3) spellings `fra`/`deu`/`zho`.
+ *
+ * This is the vocabulary the stack compares against: `languages:` query filters
+ * match it literally, and `meta_feeder_sdk::lang::normalize_lang_code` folds
+ * incoming codes onto it. See METADATA_KEYS.md §"Value formats" and §14.3 —
+ * the card tier (`titles/*`, `posters/*`) is still on /T and has not converged.
+ * https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
  */
 export type LanguageData<T> = Record<string, T>;
-export type ISO639_1_CODE = string;
+export type LANG3_CODE = string;
+
+/**
+ * @deprecated Misnamed: no writer has ever emitted 2-letter ISO 639-1 codes
+ * here. Use {@link LANG3_CODE}. Kept as an alias so existing imports compile.
+ */
+export type ISO639_1_CODE = LANG3_CODE;
 
 /**
  * jpn, jpr and jpa already exist. Creating jpl is for japan-latin. Used for japanese romaji NON ISO 639-3 standard.