docs(WO87): the naming reference — generated + human + the law

CLAUDE.md

@@ -32,6 +32,14 @@ Project purpose and direction live in README.md.
 
 ## Hard rules
 
+- **Model naming (WO87, 2026-10-24)**: `{lang}-{target}[-{tier}]-{major.minor}`;
+  the target tag is one of four MECE conventions — `vocalized`
+  (native script + diacritics), `ipa` (narrow), `phonemic` (broad),
+  `latn` (romanization) — assigned from decode evidence
+  (`docs/naming/`), never by analogy. Renaming a published id requires
+  the evidence, the `renames:` entry in models.yaml, and index aliases
+  at the next index tag. Reference: `docs/naming/naming-reference.md`.
+
 - PRs only, never commit to main. Versions are owner decisions — never
   pick a number.
 - NEVER use an LLM as a label teacher for diacritization — they

TODO.sota/87-target-accurate-naming.md

@@ -1,7 +1,13 @@
 # WO87 — target-accurate model naming: document, then rename
 
-Status: PLANNED · Phase 1 DONE (tha-phonemic-1.0, models#357); Phase 2
-= the legacy 33
+Status: DONE (2026-10-24) — Phase 1 (tha-phonemic-1.0, models#357);
+Phase 2 executed: all 33 legacy ids decoded for evidence
+(docs/naming/target-documentation.json), the final MECE taxonomy
+adopted (vocalized/ipa/phonemic/latn), 31 renames applied zoo-wide
+with the authoritative renames: map (models#362); the reference
+generated (docs/naming/naming-reference.{md,json}); the naming law in
+CLAUDE.md. Three defects found by the sweep recorded below. Index
+aliases land at the next index tag (owner).
 
 Owner decision (2026-10-24): model names target the output convention.
 Phase 1 renamed the release candidate (tha-g2p-lex-1.0 ->

docs/naming/naming-reference.json

@@ -0,0 +1,324 @@
+{
+  "_generated": "from models.yaml + target-documentation.json — regenerate, never edit",
+  "taxonomy": {
+    "vocalized": "native script + full diacritics",
+    "ipa": "narrow IPA (stress, diacritics)",
+    "phonemic": "broad phoneme-level transcription",
+    "latn": "orthographic romanization"
+  },
+  "rules": [
+    "name shape: {lang}-{target}[-{tier}]-{major.minor}; lang = ISO 639-3",
+    "the target tag is one of the four MECE conventions above — assign from decode evidence, never by analogy",
+    "tiers are orthogonal accurate dimensions (quantization / architecture / register / size)",
+    "renaming a published id requires: (a) decode evidence, (b) the old->new entry in models.yaml renames:, (c) index aliases at the next index tag — old ids resolve forever",
+    "withdrawn ids stay frozen under their historical name"
+  ],
+  "models": [
+    {
+      "id": "ara-diac-news-1.1",
+      "target": null,
+      "tier": "news",
+      "precision": "fp32",
+      "status": "withdrawn",
+      "evidence_output": "—",
+      "was": null
+    },
+    {
+      "id": "ara-vocalized-1.0",
+      "target": "vocalized",
+      "tier": "—",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-1.0"
+    },
+    {
+      "id": "ara-vocalized-2.0",
+      "target": "vocalized",
+      "tier": "—",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-2.0"
+    },
+    {
+      "id": "ara-vocalized-2.0-int8",
+      "target": "vocalized",
+      "tier": "int8",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-2.0-int8"
+    },
+    {
+      "id": "ara-vocalized-layerdrop-1.0",
+      "target": "vocalized",
+      "tier": "layerdrop",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-layerdrop-1.0"
+    },
+    {
+      "id": "ara-vocalized-layerdrop-1.0-int4",
+      "target": "vocalized",
+      "tier": "int4",
+      "precision": "int4",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-layerdrop-1.0-int4"
+    },
+    {
+      "id": "ara-vocalized-layerdrop-1.0-int8",
+      "target": "vocalized",
+      "tier": "int8",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-layerdrop-1.0-int8"
+    },
+    {
+      "id": "ara-vocalized-news-1.0",
+      "target": "vocalized",
+      "tier": "news",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-news-1.0"
+    },
+    {
+      "id": "ara-vocalized-plane-1.0",
+      "target": "vocalized",
+      "tier": "plane",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-plane-1.0"
+    },
+    {
+      "id": "ara-vocalized-plane-large-1.0",
+      "target": "vocalized",
+      "tier": "plane",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-plane-large-1.0"
+    },
+    {
+      "id": "ara-vocalized-small-1.0",
+      "target": "vocalized",
+      "tier": "small",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-small-1.0"
+    },
+    {
+      "id": "ara-vocalized-small-1.0-int8",
+      "target": "vocalized",
+      "tier": "int8",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-small-1.0-int8"
+    },
+    {
+      "id": "ara-vocalized-small-2.0",
+      "target": "vocalized",
+      "tier": "small",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-small-2.0"
+    },
+    {
+      "id": "ara-vocalized-small-2.0-int8",
+      "target": "vocalized",
+      "tier": "int8",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-small-2.0-int8"
+    },
+    {
+      "id": "ara-vocalized-small-2.1",
+      "target": "vocalized",
+      "tier": "small",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-small-2.1"
+    },
+    {
+      "id": "ara-vocalized-small-2.1-fp16",
+      "target": "vocalized",
+      "tier": "fp16",
+      "precision": "fp16",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-small-2.1-fp16"
+    },
+    {
+      "id": "ara-vocalized-small-2.1-int8",
+      "target": "vocalized",
+      "tier": "int8",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-small-2.1-int8"
+    },
+    {
+      "id": "ara-vocalized-small-int8static-2.1",
+      "target": "vocalized",
+      "tier": "int8-static",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "ara-diac-small-int8static-2.1"
+    },
+    {
+      "id": "fas-phonemic-1.0",
+      "target": "phonemic",
+      "tier": "—",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "fas-g2p-1.0"
+    },
+    {
+      "id": "fas-vocalized-base-1.0",
+      "target": "vocalized",
+      "tier": "base",
+      "precision": "fp16",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "fas-diac-base-1.0"
+    },
+    {
+      "id": "heb-vocalized-1.0",
+      "target": "vocalized",
+      "tier": "—",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "heb-diac-1.0"
+    },
+    {
+      "id": "heb-vocalized-1.1",
+      "target": "vocalized",
+      "tier": "—",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "heb-diac-1.1"
+    },
+    {
+      "id": "heb-vocalized-plane-1.0",
+      "target": "vocalized",
+      "tier": "plane",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "heb-diac-plane-1.0"
+    },
+    {
+      "id": "heb-vocalized-plane-2.0",
+      "target": "vocalized",
+      "tier": "plane",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "heb-diac-plane-2.0"
+    },
+    {
+      "id": "heb-vocalized-small-1.0",
+      "target": "vocalized",
+      "tier": "small",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "heb-diac-small-1.0"
+    },
+    {
+      "id": "khm-latn-1.0",
+      "target": "latn",
+      "tier": "—",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "suostei",
+      "was": null
+    },
+    {
+      "id": "tha-phonemic-1.0",
+      "target": "phonemic",
+      "tier": "—",
+      "precision": "fp32",
+      "status": "release-candidate",
+      "evidence_output": "—",
+      "was": null
+    },
+    {
+      "id": "tha-phonemic-base-1.0",
+      "target": "phonemic",
+      "tier": "base",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "tha-g2p-base-1.0"
+    },
+    {
+      "id": "tha-phonemic-small-1.0",
+      "target": "phonemic",
+      "tier": "small",
+      "precision": "int8",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "tha-g2p-small-1.0"
+    },
+    {
+      "id": "tha-phonemic-small-1.0-int4",
+      "target": "phonemic",
+      "tier": "int4",
+      "precision": "int4",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "tha-g2p-small-1.0-int4"
+    },
+    {
+      "id": "urd-ipa-1.0",
+      "target": "ipa",
+      "tier": "—",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "urd-g2p-1.0"
+    },
+    {
+      "id": "urd-ipa-base-1.0",
+      "target": "ipa",
+      "tier": "base",
+      "precision": "fp32",
+      "status": "research-only",
+      "evidence_output": "—",
+      "was": "urd-g2p-base-1.0"
+    },
+    {
+      "id": "urd-vocalized-1.0",
+      "target": "vocalized",
+      "tier": "—",
+      "precision": "fp32",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "urd-diac-1.0"
+    },
+    {
+      "id": "urd-vocalized-base-1.0",
+      "target": "vocalized",
+      "tier": "base",
+      "precision": "fp16",
+      "status": "shipped",
+      "evidence_output": "—",
+      "was": "urd-diac-base-1.0"
+    }
+  ]
+}

docs/naming/naming-reference.md

@@ -0,0 +1,41 @@
+# Naming reference — all models (generated)
+
+Regenerate from models.yaml + target-documentation.json; never edit by hand.
+Machine-readable twin: `naming-reference.json`.
+
+| id | target | tier | precision | status | evidence output | was |
+|---|---|---|---|---|---|---|
+| `ara-diac-news-1.1` | — | news | fp32 | withdrawn | `—` | — |
+| `ara-vocalized-1.0` | vocalized | — | fp32 | shipped | `—` | ← ara-diac-1.0 |
+| `ara-vocalized-2.0` | vocalized | — | fp32 | shipped | `—` | ← ara-diac-2.0 |
+| `ara-vocalized-2.0-int8` | vocalized | int8 | int8 | shipped | `—` | ← ara-diac-2.0-int8 |
+| `ara-vocalized-layerdrop-1.0` | vocalized | layerdrop | fp32 | shipped | `—` | ← ara-diac-layerdrop-1.0 |
+| `ara-vocalized-layerdrop-1.0-int4` | vocalized | int4 | int4 | shipped | `—` | ← ara-diac-layerdrop-1.0-int4 |
+| `ara-vocalized-layerdrop-1.0-int8` | vocalized | int8 | int8 | shipped | `—` | ← ara-diac-layerdrop-1.0-int8 |
+| `ara-vocalized-news-1.0` | vocalized | news | int8 | shipped | `—` | ← ara-diac-news-1.0 |
+| `ara-vocalized-plane-1.0` | vocalized | plane | int8 | shipped | `—` | ← ara-diac-plane-1.0 |
+| `ara-vocalized-plane-large-1.0` | vocalized | plane | int8 | shipped | `—` | ← ara-diac-plane-large-1.0 |
+| `ara-vocalized-small-1.0` | vocalized | small | fp32 | shipped | `—` | ← ara-diac-small-1.0 |
+| `ara-vocalized-small-1.0-int8` | vocalized | int8 | int8 | shipped | `—` | ← ara-diac-small-1.0-int8 |
+| `ara-vocalized-small-2.0` | vocalized | small | fp32 | shipped | `—` | ← ara-diac-small-2.0 |
+| `ara-vocalized-small-2.0-int8` | vocalized | int8 | int8 | shipped | `—` | ← ara-diac-small-2.0-int8 |
+| `ara-vocalized-small-2.1` | vocalized | small | fp32 | shipped | `—` | ← ara-diac-small-2.1 |
+| `ara-vocalized-small-2.1-fp16` | vocalized | fp16 | fp16 | shipped | `—` | ← ara-diac-small-2.1-fp16 |
+| `ara-vocalized-small-2.1-int8` | vocalized | int8 | int8 | shipped | `—` | ← ara-diac-small-2.1-int8 |
+| `ara-vocalized-small-int8static-2.1` | vocalized | int8-static | int8 | shipped | `—` | ← ara-diac-small-int8static-2.1 |
+| `fas-phonemic-1.0` | phonemic | — | fp32 | shipped | `—` | ← fas-g2p-1.0 |
+| `fas-vocalized-base-1.0` | vocalized | base | fp16 | shipped | `—` | ← fas-diac-base-1.0 |
+| `heb-vocalized-1.0` | vocalized | — | fp32 | shipped | `—` | ← heb-diac-1.0 |
+| `heb-vocalized-1.1` | vocalized | — | fp32 | shipped | `—` | ← heb-diac-1.1 |
+| `heb-vocalized-plane-1.0` | vocalized | plane | int8 | shipped | `—` | ← heb-diac-plane-1.0 |
+| `heb-vocalized-plane-2.0` | vocalized | plane | int8 | shipped | `—` | ← heb-diac-plane-2.0 |
+| `heb-vocalized-small-1.0` | vocalized | small | fp32 | shipped | `—` | ← heb-diac-small-1.0 |
+| `khm-latn-1.0` | latn | — | fp32 | shipped | `suostei` | — |
+| `tha-phonemic-1.0` | phonemic | — | fp32 | release-candidate | `—` | — |
+| `tha-phonemic-base-1.0` | phonemic | base | fp32 | shipped | `—` | ← tha-g2p-base-1.0 |
+| `tha-phonemic-small-1.0` | phonemic | small | int8 | shipped | `—` | ← tha-g2p-small-1.0 |
+| `tha-phonemic-small-1.0-int4` | phonemic | int4 | int4 | shipped | `—` | ← tha-g2p-small-1.0-int4 |
+| `urd-ipa-1.0` | ipa | — | fp32 | shipped | `—` | ← urd-g2p-1.0 |
+| `urd-ipa-base-1.0` | ipa | base | fp32 | research-only | `—` | ← urd-g2p-base-1.0 |
+| `urd-vocalized-1.0` | vocalized | — | fp32 | shipped | `—` | ← urd-diac-1.0 |
+| `urd-vocalized-base-1.0` | vocalized | base | fp16 | shipped | `—` | ← urd-diac-base-1.0 |