@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/platform/voice-plan.js

@@ -1,156 +1,69 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/voice-plan.ts — O PLANO DAS VOZES NEURAIS (ADR-0110), na metade PURA.
+// platform/voice-plan.ts — the shape of a voice a child may pick, and which of them speak a language (ADR-0185).
 //
-// ========================= O QUE ESTE MÓDULO É =========================
-// O catálogo das quatro vozes que a engine GARANTE, a ordem por que se buscam, e — a parte que mais importa —
-// a resposta honesta a «o que é que esta criança está a ouvir AGORA». Sem rede, sem cache, sem tempo. Quem
-// busca de facto é a outra metade; quem decide O QUE buscar e o que DIZER é esta.
-//
-// ⚠️ POR QUE O CATÁLOGO VIVE AQUI E NÃO NO `TTS_SOURCES`. A tabela do `platform/tts` é indexada por idioma e
-// tem UMA voz por idioma; este catálogo tem QUATRO vozes para TRÊS idiomas, porque o en-US tem duas. Ligá-las
-// hoje mudaria comportamento: o `loadTTS` passaria a pedir `en_US-ryan-medium` à PORTA DO CARTUCHO
-// (ADR-0094), que pode não ter essa voz. A tabela liga-se a isto quando o buscador existir, e nem um dia
-// antes — uma lista ligada a um fornecedor que não a conhece é pior do que uma lista à espera.
-//
-// ⚠️ E QUAL DAS DUAS VOZES EN-US A CRIANÇA OUVE POR PADRÃO NÃO SE DECIDE AQUI. O ADR-0110 deixa-o
-// explicitamente em aberto, e a ORDEM DESTE ARRAY NÃO É UMA PREFERÊNCIA — é a ordem em que o Dev as nomeou.
-// Ler ordem como escolha seria decidir por omissão, que é o defeito que este projeto persegue.
+// 📌 The engine owns no neural voice catalogue of its own (ADR-0207) and Kokoro's voices come through the
+// game's port (`platform/kokoro`, ADR-0198). What stays here is the rule every list obeys — the browser's and Kokoro's.
 /**
- * AS QUATRO QUE A ENGINE GARANTE (ADR-0110), decididas pelo Dev em 2026-09-08.
- *
- * ⚠️ TODAS `vits-piper` E NENHUMA `ncnn`, que o ADR-0065 §5 já proibia: `ncnn` é outro MOTOR DE INFERÊNCIA —
- * modelos `.param`/`.bin` e não `.onnx` — e este projeto corre sherpa-onnx. Dois dos links que chegaram em
- * 2026-09-08 apontavam para os espelhos `ncnn`, e é por isso que a proibição tem gate e não só um comentário.
- * ⚠️ E NENHUMA `int8`, pela razão MEDIDA do mesmo §5: no backend WASM o int8 corre ~3× MAIS LENTO que o fp32
- * (RTF 5,6 contra 2,5, do log do próprio Dev) e produz saída incorrecta ou muda. Quantizar não encurta a
- * espera aqui — alonga-a.
+ * The voices a child may pick for a language (ADR-0185): matched on the LANGUAGE of the tag, not the region — a Mexican
+ * voice reads Spanish from Spain, and a Brazilian game tagged `pt` is still Portuguese. A voice reading another language
+ * is not offered: Portuguese text through English phonemes is noise.
  */
-export const VOZES_NEURAIS = Object.freeze([
-    Object.freeze({ locale: 'pt-BR', engine: 'piper', voice: 'pt_BR-faber-medium' }),
-    Object.freeze({ locale: 'en-US', engine: 'piper', voice: 'en_US-ryan-medium' }),
-    Object.freeze({ locale: 'en-US', engine: 'piper', voice: 'en_US-amy-medium' }),
-    Object.freeze({ locale: 'es-MX', engine: 'piper', voice: 'es_MX-claude-high' }),
-]);
-/**
- * DE ONDE VÊM OS MODELOS (ADR-0114), num sítio só.
- *
- * 📏 MEDIDO EM 2026-09-08, e não escolhido: o `piper.ttstool.com` — que o Dev nomeou ao perguntar — serve o
- * próprio runtime da própria origem e busca os modelos aqui. As quatro vozes deste catálogo respondem 200
- * neste endereço, com `Access-Control-Allow-Origin: *`, logo um PWA pode buscá-las de outra origem.
- *
- * ⚠️ UM SÍTIO SÓ É A METADE QUE O REGISTO PEDE. Um endereço repetido no ponto de uso é como o CDN do
- * WebGazer chegou ao `ui/webcam` — escrito à mão, sem política, e sem ninguém a poder mudá-lo de uma vez.
- *
- * ========================= 🔴 MUDOU DE ESPELHO EM 2026-09-09, E A REGRA É «BUSCAR DE ONDE O LEITOR LÊ» ====
- * Era `rhasspy/piper-voices`, medido a 08/09 como o espelho que o `piper.ttstool.com` usa. Depois de o
- * `platform/pesados` passar a descer os modelos no primeiro carregamento, mediu-se o outro lado — o
- * `@mintplex-labs/piper-tts-web@1.0.4` INSTALADO, lido do bundle e não do README — e ele busca em
- * `diffusionstudio/piper-voices`, com uma guarda que recusa qualquer URL fora de `huggingface.co`.
- *
- * 🎯 ENDEREÇOS DIFERENTES SIGNIFICAM CACHE DIFERENTE: a Cache Storage é indexada pela URL do pedido, logo os
- * 241 MB que desciam no primeiro dia NÃO ERAM LIDOS POR NINGUÉM, e a biblioteca descarregava tudo outra vez
- * no dia em que a voz fosse pedida. Até 482 MB num link de escola para uma voz.
- *
- * 📏 E OS DOIS ESPELHOS SERVEM OS MESMOS BYTES — 63 201 294 para o `pt_BR-faber-medium`, caminhos idênticos,
- * `Access-Control-Allow-Origin: *` nos dois. Medido nos dois no mesmo minuto, o que torna esta troca uma
- * correcção de facto e não uma preferência entre fornecedores.
- *
- * ⚠️ A CLÁUSULA DO ADR-0114 NÃO SE MEXE: o host continua nomeado num ponto só. O que mudou foi QUAL, e a
- * regra que decide isso passa a estar escrita para não voltar a divergir — **busca-se de onde o LEITOR lê**.
- * No dia em que a engine for dona do runtime (ADR-0124 cláusula 2), o leitor passa a ser ela e é ela que
- * escolhe; até lá, o único leitor é a porta do cartucho.
- */
-export const HOST_DOS_MODELOS = 'https://huggingface.co/diffusionstudio/piper-voices/resolve/main/';
-/**
- * O CAMINHO DO MODELO, DERIVADO DO IDENTIFICADOR — e não uma segunda tabela.
- *
- * `pt_BR-faber-medium` diz tudo o que o caminho precisa: `pt/pt_BR/faber/medium/pt_BR-faber-medium.onnx`.
- * 🎯 DERIVAR EM VEZ DE TABELAR é a decisão inteira desta função: uma tabela de caminhos ao lado da tabela
- * de vozes seria o mesmo facto escrito duas vezes, e este repositório já pagou isso três vezes — o
- * `DomQuery`, os rótulos de movimento reduzido, as chaves de armazenamento. Duas listas divergem, e
- * divergem uma entrada de cada vez.
- *
- * ⚠️ Devolve `null` para um identificador que não tenha a forma esperada, em vez de montar um caminho
- * torto: uma URL inventada dá 404 na escola, e um `null` dá para reportar antes de sair de casa.
- */
-export function caminhoDoModelo(v) {
-    const partes = v.voice.split('-');
-    if (partes.length !== 3)
-        return null;
-    const [locale, nome, qualidade] = partes;
-    const idioma = locale.split('_')[0];
-    if (!idioma || !nome || !qualidade || idioma === locale)
-        return null;
-    return `${idioma}/${locale}/${nome}/${qualidade}/${v.voice}.onnx`;
-}
-/** O endereço completo do modelo. `null` quando o identificador não se deixa ler. */
-export function urlDoModelo(v) {
-    const caminho = caminhoDoModelo(v);
-    return caminho === null ? null : HOST_DOS_MODELOS + caminho;
+export function voicesForLocale(tag, catalogue) {
+    return catalogue.filter((v) => speaksLanguageOf(v.locale, tag));
 }
+/** The primary language of a BCP-47 tag, lower case: `pt` of `pt-BR`. A browser's `en_US` is normalised by whoever reads it. */
+const primaryLanguage = (tag) => (tag.split('-')[0] ?? '').toLowerCase();
 /**
- * A CONFIGURAÇÃO da voz, que o motor lê junto com o modelo.
- *
- * 📌 `.onnx.json` e não um segundo caminho: é o mesmo ficheiro com outro sufixo, medido a responder 200 no
- * mesmo sítio. Escrevê-lo como derivação mantém a regra de que o identificador é a única fonte.
+ * A language's name, written in another language: `languageName('en-GB', 'pt-BR')` is «inglês» — the primary language, because a
+ * voice of the same language would have read the part (ADR-0243 §3). Where the platform cannot name it, the tag's language code.
  */
-export function urlDaConfig(v) {
-    const url = urlDoModelo(v);
-    return url === null ? null : url + '.json';
+export function languageName(tag, inLanguage) {
+    const code = primaryLanguage(tag);
+    try {
+        return new Intl.DisplayNames([inLanguage], { type: 'language' }).of(code) ?? code;
+    }
+    catch {
+        return code;
+    }
 }
-export const estadoDe = (estados, v) => estados[v.voice] ?? 'ausente';
+/** Does a voice tagged `locale` speak the language of `tag`? By the primary language, as `voicesForLocale` matches. */
+export function speaksLanguageOf(locale, tag) {
+    return primaryLanguage(locale) === primaryLanguage(tag);
+}
+/** The engine of a browser (Web Speech) voice in a list; every other engine is neural (ADR-0200). */
+const BROWSER_ENGINE = 'webspeech';
+const browser = (v) => v.engine === BROWSER_ENGINE;
+const exactTag = (v, tag) => v.locale.toLowerCase() === tag.toLowerCase();
 /**
- * A ORDEM POR QUE SE BUSCAM: primeiro as do idioma corrente, depois as outras, cada grupo na ordem do
- * catálogo. Só entram as que ainda não estão prontas nem em curso.
- *
- * ⚠️ O IDIOMA CORRENTE PRIMEIRO É A REGRA INTEIRA, e ela é sobre uma criança e não sobre eficiência: as
- * outras são para «conforme interesse do jogador», mas a dela é a que ela precisa AGORA. Buscar em ordem de
- * catálogo faria uma criança brasileira esperar por duas vozes inglesas na rede de uma escola.
- *
- * 📌 `falhou` VOLTA À FILA. Uma escola perde a rede a meio da manhã e recupera-a; uma voz marcada como
- * falhada para sempre seria uma criança sem voz até alguém recarregar a página. Quem chama decide QUANDO
- * tentar de novo — este módulo só diz que ainda há o que buscar.
+ * THE VOICE ORDER (ADR-0243 §2, the two errata of 2026-09-26), after the child's chosen voice. A BROWSER voice before a NEURAL one
+ * (the Dev: «Se a do navegador (mais leve) pode ser usada, a do navegador, senão ganha a voz neural (backup)»), but the exact tag
+ * before the region: asked whether a pt-PT browser voice reads a pt-BR part or the neural pt-BR voice does, the Dev: «Rede neural
+ * pt-BR.» So a voice of the same language and another region reads only where no voice of the exact tag exists, browser first.
+ * Every step is tried over the whole list, in order; within a step the list's own order decides. The interface's own voice
+ * follows the same order (`platform/tts`'s `voiceInUse`).
  */
-export function ordemDeBusca(estados, localeCorrente, catalogo = VOZES_NEURAIS) {
-    const porBuscar = catalogo.filter((v) => {
-        const e = estadoDe(estados, v);
-        return e === 'ausente' || e === 'falhou';
-    });
-    return [
-        ...porBuscar.filter((v) => v.locale === localeCorrente),
-        ...porBuscar.filter((v) => v.locale !== localeCorrente),
-    ];
-}
+const VOICE_ORDER = [
+    (v, tag) => browser(v) && exactTag(v, tag),
+    (v, tag) => !browser(v) && exactTag(v, tag),
+    (v) => browser(v),
+    (v) => !browser(v),
+];
 /**
- * QUEM ESTÁ A FALAR, E POR QUE — e esta função é o gate 3 do ADR-0110 em forma de código.
- *
- * ⚠️ O DEFEITO QUE ELA IMPEDE TEM NOME NESTE REPOSITÓRIO: «um recuo que se apresenta como a coisa real é a
- * família do `reflectTTS`». Uma engine que dissesse «voz neural» enquanto o modelo ainda desce faria um adulto
- * concluir que a qualidade que ouve É a qualidade final — e desistir de esperar por uma coisa que já vinha a
- * caminho. Dizer `recuo` e dizer PORQUÊ custa uma linha e é a diferença entre informar e enganar.
- *
- * 📌 A PRIMEIRA VOZ PRONTA DO IDIOMA, e nada mais: onde há duas prontas, esta função NÃO escolhe entre elas —
- * devolve a primeira do catálogo porque tem de devolver alguma, e qual delas a criança prefere é a pergunta
- * que o ADR-0110 deixou em aberto. Ver o cabeçalho.
+ * THE VOICE OF A LANGUAGE (ADR-0243 §2): the child's chosen voice when it speaks that language; else the first voice `VOICE_ORDER`
+ * reaches — the exact tag before the region, a browser voice before a neural one. `chosen` comes in order of precedence.
+ * 🔴 No voice of another language is ever returned: `null` means the list has none for it, and the part is not spoken (§3).
  */
-export function vozEmUso(estados, localeCorrente, catalogo = VOZES_NEURAIS) {
-    const doIdioma = catalogo.filter((v) => v.locale === localeCorrente);
-    if (doIdioma.length === 0)
-        return { tipo: 'recuo', porque: 'sem-voz-para-o-idioma' };
-    const pronta = doIdioma.find((v) => estadoDe(estados, v) === 'pronta');
-    if (pronta)
-        return { tipo: 'neural', voice: pronta.voice };
-    // A PRECEDÊNCIA DOS TRÊS RECUOS, e cada degrau tem a sua razão:
-    //
-    // ⚠️ «A BUSCAR» GANHA DE «FALHOU» quando as duas coexistem: enquanto alguma ainda vem a caminho, dizer
-    //    «falhou» seria anunciar uma derrota que ainda não aconteceu, e um adulto desligaria a espera cedo.
-    // ⚠️ E «AUSENTE» NÃO SE DISFARÇA DE «A BUSCAR», que era como esta função estava escrita à primeira. Nada
-    //    começou é diferente de está a caminho: o primeiro é uma engine que ainda não pediu — possivelmente
-    //    porque ninguém a mandou —, e chamar-lhe «a buscar» esconderia um buscador que nunca arrancou atrás de
-    //    uma frase tranquilizadora. É o mesmo defeito de forma que o `neuralDisponivel` já custou à #91.
-    if (doIdioma.some((v) => estadoDe(estados, v) === 'a-buscar'))
-        return { tipo: 'recuo', porque: 'a-buscar' };
-    if (doIdioma.some((v) => estadoDe(estados, v) === 'falhou'))
-        return { tipo: 'recuo', porque: 'falhou' };
-    return { tipo: 'recuo', porque: 'ausente' };
+export function voiceOfLanguage(tag, voices, chosen = []) {
+    const own = voicesForLocale(tag, voices);
+    for (const id of chosen) {
+        const picked = id ? own.find((v) => v.voice === id) : undefined;
+        if (picked)
+            return picked;
+    }
+    for (const step of VOICE_ORDER) {
+        const found = own.find((v) => step(v, tag));
+        if (found)
+            return found;
+    }
+    return null;
 }

package/dist-pkg/platform/vosk-runtime.d.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The three files of the runtime. The model is chosen by language, below. */
+export declare const VOICE_RUNTIME_FILES: readonly ["commands:runtime", "commands:runtime:worker", "commands:runtime:wasm"];
+/** The catalogue id of the model that hears THIS language, or `null` where the project has none. */
+export declare function commandModelId(language: string): string | null;
+/** What the recogniser answers with. `partial` grows during one utterance; `text` is the sentence once it ends. */
+export interface VoskHeard {
+    readonly result: {
+        readonly partial?: string;
+        readonly text?: string;
+    };
+}
+export interface VoskRecognizer {
+    on(event: 'partialresult' | 'result', cb: (heard: VoskHeard) => void): void;
+    /** One block of sound, as the audio graph delivers it. */
+    acceptWaveform(buffer: AudioBuffer): void;
+    remove(): void;
+}
+export interface VoskModel {
+    KaldiRecognizer: new (sampleRate: number, grammar: string) => VoskRecognizer;
+    terminate?(): void;
+}
+/**
+ * What the bundle exports. `resolve` is how it asks US for the two files it needs beside the model — the worker it spawns and
+ * the wasm that worker loads — so nothing is ever guessed from the bundle's own address.
+ */
+export interface VoskApi {
+    createModel(url: string, resolve: (logicalPath: string) => string, logLevel?: number): Promise<VoskModel>;
+}
+export interface VoskDeps {
+    /** The page's address, to make the delivery paths absolute. */
+    readonly base: string;
+    /** The child's language (`core/i18n.bcp47`): it chooses the model. */
+    readonly language: string;
+    /**
+     * Whether a catalogue file (by its upstream address) is in the checked cache — `platform/heavy`'s `checkedCacheHas`, over the
+     * host's `caches`. REQUIRED (ADR-0232 D4): the root lends the cache; this module reaches none.
+     */
+    readonly hasFile: (upstreamUrl: string) => Promise<boolean>;
+    /**
+     * Imports the bundle and answers with what it exports — `createBundleLoader` below, built ONCE by the root, so the bundle is
+     * put in the page once per address. REQUIRED, and injected so a gate never imports 3 MiB of wasm loader.
+     */
+    readonly loadBundle: (absoluteUrl: string) => Promise<VoskApi>;
+    /**
+     * The host's `fetch`, lent by the root, to read the MODEL'S VOCABULARY from the archive the recogniser opens
+     * (`platform/vosk-vocabulary`, ADR-0194 §4): the runtime keeps it inside its worker and tells the page nothing. Optional; without
+     * it the load carries no `vocabulary`, and a name with a word the model lacks goes unreported.
+     */
+    readonly fetch?: (absoluteUrl: string) => Promise<{
+        readonly ok: boolean;
+        readonly body: ReadableStream<BufferSource> | null;
+    }>;
+}
+export type VoskLoad = {
+    readonly ok: true;
+    readonly model: VoskModel;
+    /**
+     * The words the loaded model knows, read from its archive once asked — `null` when they cannot be read. Present only when the
+     * deps lent a `fetch`.
+     */
+    readonly vocabulary?: () => Promise<ReadonlySet<string> | null>;
+}
+/** The catalogue ids that are not in the checked cache — `language` when the project has no model for it. */
+ | {
+    readonly ok: false;
+    readonly missing: readonly string[];
+};
+/**
+ * PUTS THE BUNDLE IN THE PAGE ONCE PER ADDRESS, and answers with what it exports. A second call answers the same one: the
+ * bundle registers a worker and a wasm module, and loading it twice would pay for both again on a machine that has little of
+ * either. A rejection is forgotten, so a load that failed on a bad minute can be retried.
+ *
+ * 🔴 THE MEMO IS THE LOADER'S, AND THE LOADER IS BUILT ONCE BY THE ROOT (ADR-0232 D4), which hands it to every start of the
+ * recogniser. A memo built inside `loadVoskRuntime` was a new memo every call, so «once» only ever held within one call; a
+ * memo at module level was one per PAGE, shared by roots that share nothing else. `load` is the root's `import(url)`.
+ */
+export declare function createBundleLoader(load: (absoluteUrl: string) => Promise<unknown>): (absoluteUrl: string) => Promise<VoskApi>;
+/**
+ * ONE MODEL PER LANGUAGE, LOADED ONCE AND KEPT (ADR-0256): the 👄 and a choice by voice ask the same `load`, and a listener that
+ * stops no longer ends the model — the one handed out has a `terminate` that does nothing; the real one is ended when it is
+ * pushed out (more than `keep` languages, the oldest first) or by `closeAll()`, the root's end.
+ * 📏 Why: every start used to spawn a worker and unpack ~40 MiB of model, and every choice started two — the Dev's machine froze
+ * on 2026-09-27. A load that failed is forgotten, so a model that comes down later is found.
+ */
+export declare function keepVoskModels(load: (d: VoskDeps) => Promise<VoskLoad>, keep?: number): {
+    load(d: VoskDeps): Promise<VoskLoad>;
+    closeAll(): void;
+};
+/**
+ * Opens the recogniser for the child's language, or says what is missing.
+ *
+ * ⚠️ THE MODEL IS A `.tar.gz` THE BUNDLE FETCHES ITSELF, so what it is given is the DELIVERY path: the service worker answers it
+ * from the checked cache, and a school with no network after the first day still hears the child (pillar 8).
+ */
+export declare function loadVoskRuntime(d: VoskDeps): Promise<VoskLoad>;

package/dist-pkg/platform/vosk-runtime.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/vosk-runtime — THE RECOGNISER THAT HEARS COMMANDS, FROM THE GAME'S OWN ORIGIN (ADR-0189, ADR-0193; issue #184).
+//
+// The same shape as `platform/vision`, and for the same reasons: the runtime and the model are the files the install already
+// fetched and checked by sha256 (`platform/heavy`), they are asked for at `heavy/<host><path>` beside the page, and a file
+// that is not in the checked cache is never loaded — the loader answers WHICH ones are missing, so the child hears why speaking
+// does not work instead of meeting a button that does nothing.
+//
+// 🎯 AND THIS RUNTIME EXISTS BECAUSE NO PUBLISHED ONE COULD BE USED: every `vosk-browser` build evaluates text as code, which
+// this engine's policy refuses (ADR-0193 — never `'unsafe-eval'`, never a patch). It was rebuilt with `-s DYNAMIC_EXECUTION=0`
+// and runs under the policy as it is (`docs/6-DevOps-SRE/models.md`).
+//
+// 🔴 IT IS AN ES MODULE THAT RESOLVES ITS OWN FILES THROUGH US, and this was MEASURED in a browser on 2026-09-21 after the
+// first version of this loader assumed the opposite. The real bundle of `vosk-browser-dynamic-execution-0` ends in
+// `export { createModel, Model, … }` and asks for the other two files by logical name:
+//     new Worker(resolver("npm/vosk/vosk.worker.js"), { type: "module" })   ·   wasmUrl: this.resolver("npm/vosk/vosk.wasm")
+// So it is loaded with `import()` (the same way `platform/vision` loads `tasks-vision`), and the resolver answers with the
+// DELIVERY path of each file — which is how the service worker gets to serve all three from the checked cache.
+//
+// ⚠️ THE LESSON IS ABOUT THE GATE AND NOT ABOUT THE FILE: the old shape («a classic script that defines a global and finds its
+// neighbours by itself») had seven red mutations against a double built in the image of that belief. A double can only measure
+// the contract you think you have; the one that exists was three lines of the served file away.
+import { HEAVY_FILES, deliveryPath } from './heavy.js';
+import { commandsLanguageOf } from './heavy-catalogue.js';
+import { readModelVocabulary } from './vosk-vocabulary.js';
+/** The three files of the runtime. The model is chosen by language, below. */
+export const VOICE_RUNTIME_FILES = ['commands:runtime', 'commands:runtime:worker', 'commands:runtime:wasm'];
+/** The catalogue id of the model that hears THIS language, or `null` where the project has none. */
+export function commandModelId(language) {
+    const wanted = language.split('-')[0].toLowerCase();
+    const found = HEAVY_FILES.find((p) => commandsLanguageOf(p.id) === wanted);
+    return found ? found.id : null;
+}
+const urlOf = (id) => HEAVY_FILES.find((x) => x.id === id)?.url ?? null;
+/**
+ * PUTS THE BUNDLE IN THE PAGE ONCE PER ADDRESS, and answers with what it exports. A second call answers the same one: the
+ * bundle registers a worker and a wasm module, and loading it twice would pay for both again on a machine that has little of
+ * either. A rejection is forgotten, so a load that failed on a bad minute can be retried.
+ *
+ * 🔴 THE MEMO IS THE LOADER'S, AND THE LOADER IS BUILT ONCE BY THE ROOT (ADR-0232 D4), which hands it to every start of the
+ * recogniser. A memo built inside `loadVoskRuntime` was a new memo every call, so «once» only ever held within one call; a
+ * memo at module level was one per PAGE, shared by roots that share nothing else. `load` is the root's `import(url)`.
+ */
+export function createBundleLoader(load) {
+    const asked = new Map();
+    return (absoluteUrl) => {
+        const already = asked.get(absoluteUrl);
+        if (already)
+            return already;
+        const pending = load(absoluteUrl);
+        asked.set(absoluteUrl, pending);
+        pending.catch(() => { asked.delete(absoluteUrl); });
+        return pending;
+    };
+}
+/**
+ * ONE MODEL PER LANGUAGE, LOADED ONCE AND KEPT (ADR-0256): the 👄 and a choice by voice ask the same `load`, and a listener that
+ * stops no longer ends the model — the one handed out has a `terminate` that does nothing; the real one is ended when it is
+ * pushed out (more than `keep` languages, the oldest first) or by `closeAll()`, the root's end.
+ * 📏 Why: every start used to spawn a worker and unpack ~40 MiB of model, and every choice started two — the Dev's machine froze
+ * on 2026-09-27. A load that failed is forgotten, so a model that comes down later is found.
+ */
+export function keepVoskModels(load, keep = 2) {
+    /** Per language: the load as it came (whose model is the one to end) and the one handed out. */
+    const kept = new Map();
+    const end = (entry) => {
+        void entry.real.then((l) => { if (l.ok)
+            l.model.terminate?.(); }, () => { });
+    };
+    return {
+        load(d) {
+            const key = d.language.split('-')[0].toLowerCase();
+            const found = kept.get(key);
+            if (found) {
+                kept.delete(key);
+                kept.set(key, found);
+                return found.lent;
+            } // the most recent last
+            const real = load(d);
+            const lent = real.then((l) => (l.ok ? { ...l, model: { get KaldiRecognizer() { return l.model.KaldiRecognizer; }, terminate: () => { } } } : l));
+            const entry = { real, lent };
+            kept.set(key, entry);
+            const forget = () => { if (kept.get(key) === entry)
+                kept.delete(key); };
+            real.then((l) => { if (!l.ok)
+                forget(); }, forget);
+            while (kept.size > keep) {
+                const [oldest, q] = kept.entries().next().value;
+                kept.delete(oldest);
+                end(q);
+            }
+            return lent;
+        },
+        closeAll() { for (const entry of kept.values())
+            end(entry); kept.clear(); },
+    };
+}
+/**
+ * Opens the recogniser for the child's language, or says what is missing.
+ *
+ * ⚠️ THE MODEL IS A `.tar.gz` THE BUNDLE FETCHES ITSELF, so what it is given is the DELIVERY path: the service worker answers it
+ * from the checked cache, and a school with no network after the first day still hears the child (pillar 8).
+ */
+export async function loadVoskRuntime(d) {
+    const modelId = commandModelId(d.language);
+    if (!modelId)
+        return { ok: false, missing: ['language'] };
+    const missing = [];
+    for (const id of [...VOICE_RUNTIME_FILES, modelId]) {
+        const url = urlOf(id);
+        if (!url || !(await d.hasFile(url)))
+            missing.push(id);
+    }
+    if (missing.length)
+        return { ok: false, missing };
+    const at = (id) => new URL(deliveryPath(urlOf(id)), d.base).href;
+    const api = await d.loadBundle(at('commands:runtime'));
+    // the loader answers whatever the address held; a file that is not the recogniser says so here, not as a TypeError below
+    if (typeof api?.createModel !== 'function') {
+        throw new Error('vosk-runtime: the bundle exported no `createModel` — the delivery has the wrong file');
+    }
+    /*
+     * WHERE THE BUNDLE'S TWO NEIGHBOURS LIVE, answered by us and never guessed. The logical names are the bundle's own
+     * (`npm/vosk/…`), and an unknown one THROWS instead of falling back to a file that happens to be handy: a worker fed the
+     * wasm, or the other way round, fails deep inside a thread with no way back to the child.
+     */
+    const beside = (logicalPath) => {
+        if (logicalPath.endsWith('.worker.js'))
+            return at('commands:runtime:worker');
+        if (logicalPath.endsWith('.wasm'))
+            return at('commands:runtime:wasm');
+        throw new Error(`vosk-runtime: the bundle asked for a file this delivery does not carry: ${logicalPath}`);
+    };
+    // 📌 `-1` is the bundle's «say nothing»: a recogniser that logs every frame fills a school machine's console with noise.
+    const model = await api.createModel(at(modelId), beside, -1);
+    const { fetch } = d;
+    if (!fetch)
+        return { ok: true, model };
+    // the SAME address the worker was given: the service worker answers both from the checked cache, and the words read are the
+    // words of the model that was loaded, never another language's
+    const vocabulary = async () => {
+        try {
+            const r = await fetch(at(modelId));
+            return r.ok && r.body ? await readModelVocabulary(r.body) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    return { ok: true, model, vocabulary };
+}

package/dist-pkg/platform/vosk-vocabulary.d.ts

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * The words the model in this `.tar.gz` knows — the output symbol table of its `Gr.fst` — or `null` when that cannot be read
+ * (no word graph, a header that is not OpenFst's, a stream that ends early). Stops reading the archive once the table is read.
+ */
+export declare function readModelVocabulary(archive: ReadableStream<BufferSource>): Promise<ReadonlySet<string> | null>;