@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/platform/guide-intensity.js

@@ -1,73 +1,71 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/guide-intensity — QUÃO PERTO SOA, sem bipe (#84 item 2).
+// platform/guide-intensity — HOW NEAR IT SOUNDS, without a beep (#84 item 2).
 //
-// ========================= O QUE ISTO SUBSTITUI =========================
-// O guia tocava um `triangle` de 0,12 s a cada 0,8 s, PARA SEMPRE, sem depender de movimento nem de nada ter
-// mudado. O veredicto do Dev: «um ping é a pior escolha possível, tenebroso para quem tem TEA». Não era a
-// frequência que estava errada — era o bipe. Reduzi-lo a «só andando» deixaria a mesma coisa a doer menos
-// vezes.
+// ========================= WHAT THIS REPLACES =========================
+// The guide used to play a beep at a fixed interval, FOREVER, whether or not anything moved. The Dev's verdict: «um ping
+// é a pior escolha possível, tenebroso para quem tem TEA». It was not the frequency that was wrong — it was the beep.
+// Playing it "only while walking" would have left the same thing hurting less often.
 //
-// O que entra é uma presença CONTÍNUA que fica mais intensa conforme a criança se aproxima, ao longo da rota
-// mapeada (`core/route`). Nada dispara; a coisa apenas fica mais presente.
+// What replaces it is a CONTINUOUS presence that grows more intense as the child approaches, along the mapped route
+// (`core/route`). Nothing fires; the sound simply becomes more present.
 //
-// ========================= O EIXO É O BRILHO, E A DECISÃO É DO DEV =========================
-// Quatro eixos foram postos na mesa — volume, brilho (corte de filtro), camadas e andamento — e a escolha foi
-// **brilho como principal, com uma parcela pequena de volume como secundário**. As razões, para quem reabrir:
+// ========================= THE AXIS IS BRIGHTNESS, AND THE DECISION IS THE DEV'S =========================
+// Four axes were put on the table — volume, brightness (filter cutoff), layers and tempo — and the choice was
+// **brightness as the main one, with a small share of volume as secondary**. The reasons, for whoever reopens it:
 //
-//   · VOLUME SOZINHO colide com o cursor do mixer: a criança que baixou a categoria `guide` perderia o sinal
-//     inteiro, e variação de volume é a mais cansativa das quatro.
-//   · ANDAMENTO lê-se como PRESSA, que é o oposto do que o modo TEA existe para proteger.
-//   · CAMADAS precisa de material composto, e esta engine sintetiza.
-//   · BRILHO é contínuo, sai de um `BiquadFilter` que o Web Audio já tem, e não disputa o cursor.
+//   · VOLUME ALONE collides with the mixer's slider: a child who turned the `guide` category down would lose the whole
+//     signal, and volume change is the most tiring of the four.
+//   · TEMPO reads as HURRY, the opposite of what autism-support mode exists to protect.
+//   · LAYERS needs composed material, and this engine synthesises.
+//   · BRIGHTNESS is continuous, comes from a `BiquadFilter` Web Audio already has, and does not fight the slider.
 //
-// ⚠️ E A PARCELA DE VOLUME NÃO É ENFEITE: para uma criança com perda auditiva o brilho pode cair exatamente na
-// banda que ela não alcança. Dois eixos redundantes significam que nenhum deles sozinho decide.
+// ⚠️ AND THE SHARE OF VOLUME IS NOT DECORATION: for a child with hearing loss the brightness may fall exactly in the band
+// they cannot reach. Two redundant axes mean neither decides alone.
 //
-// ========================= O QUE ESTE MÓDULO NÃO FAZ =========================
-// Não toca nada. Devolve dois números a partir de UM: quantos passos faltam ao longo da rota. Quem monta o
-// grafo é o `platform/audio-sonar`, e quem calcula a rota é o `core/route` — que já sabe contornar parede, e é
-// isso que torna a intensidade honesta: ela cresce com a distância que a criança REALMENTE vai andar.
+// ========================= WHAT THIS MODULE DOES NOT DO =========================
+// It plays nothing. It returns two numbers from ONE: how many steps remain along the route. Whoever builds the graph
+// plays them, and `core/route` computes the route — it already knows how to go round a wall, and that is what makes the
+// intensity honest: it grows with the distance the child will REALLY walk.
 //
-// Módulo-folha: não importa nada.
+// A leaf module: it imports nothing.
 /**
- * A partir de quantos passos o guia deixa de escurecer mais.
+ * From how many steps on the guide stops getting darker.
  *
- * Doze, e o número não é novo: o `chaveDeDistancia` do sonar corta «muito perto» em 4 passos e «perto» em 9,
- * e o `PAN_PACES` satura o estéreo em 11. O guia satura logo depois — a informação fina serve para quem já
- * está a chegar, e mais longe do que isso «longe» basta.
+ * Twelve, and the number is not new: the sonar's distance words cut "very near" at 4 steps and "near" at 9, and its pan
+ * saturates the stereo at 11. The guide saturates just after — fine detail serves whoever is arriving, and beyond that
+ * "far" is enough.
  */
-export const PASSOS_ATE_O_FUNDO = 12;
-/** O corte no fundo da escala: abafado, presente, sem ser um som de alarme. */
-export const CORTE_LONGE = 320;
-/** O corte no alvo: aberto. Acima disto o timbre passa a sibilar, e sibilar chama atenção como um bipe. */
-export const CORTE_PERTO = 3200;
+export const STEPS_TO_FLOOR = 12;
+/** The cutoff at the bottom of the scale: muffled, present, never an alarm sound. */
+export const FAR_CUT = 320;
+/** The cutoff at the target: open. Above this the timbre starts to hiss, and a hiss draws attention like a beep. */
+export const NEAR_CUT = 3200;
 /**
- * O fator de volume mais baixo.
+ * The lowest volume factor.
  *
- * ⚠️ NUNCA ZERO, E É A ASSERÇÃO MAIS IMPORTANTE DESTE FICHEIRO. Se o guia emudecesse ao longe, «longe» ficaria
- * indistinguível de «não há alvo» — e a criança que depende dele concluiria que não há nada para achar,
- * exatamente quando há e está distante. Silêncio é uma afirmação, e aqui seria uma afirmação falsa.
+ * ⚠️ NEVER ZERO, AND IT IS THE MOST IMPORTANT ASSERTION IN THIS FILE. If the guide went mute far away, "far" would be
+ * indistinguishable from "there is no target" — and the child who depends on it would conclude there is nothing to find,
+ * exactly when there is and it is distant. Silence is a statement, and here it would be a false one.
  */
-export const VOL_LONGE = 0.55;
+export const FAR_VOL = 0.55;
 /**
- * A intensidade para `passos` de distância ao longo da rota.
+ * The intensity for `stepsAway` steps along the route.
  *
- * ⚠️ A INTERPOLAÇÃO DO CORTE É EXPONENCIAL, e não linear, pelo mesmo motivo do earcon da #124: o ouvido
- * percebe altura e brilho em RAZÃO, não em diferença. Uma rampa linear de 320 a 3200 abriria quase tudo no
- * primeiro terço do caminho e depois pareceria parada — a criança sentiria que chegou quando ainda faltava
- * metade.
+ * ⚠️ THE CUTOFF INTERPOLATES EXPONENTIALLY, not linearly, for the reason of #124's earcon: the ear perceives pitch and
+ * brightness as a RATIO, not a difference. A linear ramp from 320 to 3200 would open almost everything in the first third
+ * of the way and then seem to stand still — the child would feel they had arrived with half the way to go.
  *
- * O volume interpola LINEARMENTE, e a assimetria é deliberada: ele é o eixo secundário, e uma curva também
- * exponencial ali faria os dois acelerarem no mesmo ponto, que é o oposto de ter dois eixos.
+ * The volume interpolates LINEARLY, and the asymmetry is deliberate: it is the secondary axis, and an exponential curve
+ * there too would make both accelerate at the same point, the opposite of having two axes.
  */
-export function intensidadeDoGuia(passos) {
-    if (!Number.isFinite(passos) || passos < 0)
-        return { corte: CORTE_LONGE, volume: VOL_LONGE };
-    // 0 = em cima do alvo; 1 = no fundo da escala ou além.
-    const longe = Math.min(1, passos / PASSOS_ATE_O_FUNDO);
-    const perto = 1 - longe;
+export function guideIntensity(stepsAway) {
+    if (!Number.isFinite(stepsAway) || stepsAway < 0)
+        return { cutoff: FAR_CUT, volume: FAR_VOL };
+    // 0 = right on the target; 1 = at the bottom of the scale or beyond.
+    const far = Math.min(1, stepsAway / STEPS_TO_FLOOR);
+    const near = 1 - far;
     return {
-        corte: CORTE_LONGE * Math.pow(CORTE_PERTO / CORTE_LONGE, perto),
-        volume: VOL_LONGE + (1 - VOL_LONGE) * perto,
+        cutoff: FAR_CUT * Math.pow(NEAR_CUT / FAR_CUT, near),
+        volume: FAR_VOL + (1 - FAR_VOL) * near,
     };
 }

package/dist-pkg/platform/heavy-catalogue.d.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** A heavy thing the engine promises that does not fit in the package. */
+export interface HeavyFile {
+    readonly id: string;
+    /** `null` = decided that it exists, but there is nowhere to fetch it from yet. See `whyNoSource`. */
+    readonly url: string | null;
+    /** Measured, not estimated — the number an honest sentence uses before the download starts. */
+    readonly bytes?: number;
+    /**
+     * The SHA-256 of the bytes, MEASURED (issue #168): what the fetcher compares before keeping anything. A pinned URL is
+     * not pinned content — a CDN or a mirror can serve other bytes at the same address, and these run in the child's page.
+     */
+    readonly sha256?: string;
+    /** Required when `url` is `null`: an absence without a written reason becomes a forgotten absence. */
+    readonly whyNoSource?: string;
+}
+/** The Cache Storage name. Versioned: changing the catalogue's content must not serve old bytes. */
+export declare const CACHE_HEAVY = "incl-pesados-v2";
+/** The language a reading id serves, or `null` where the id is not a reading model's. */
+export declare function readingLanguageOf(id: string): string | null;
+/**
+ * The language a command MODEL serves, or `null` for anything else — including the runtime, which serves every language.
+ * ⚠️ The middle word is read on purpose: `id.split(':')[1]` would call the runtime a language of its own and leave the three
+ * models behind it out of the start of every delivery.
+ */
+export declare function commandsLanguageOf(id: string): string | null;
+/**
+ * 📌 Every entry with an address needs its licence group in `scripts/licences/third-party.mjs`: the delivery writes that group's
+ * `LICENSE` and `NOTICE` beside the file, and refuses a file whose licence nobody recorded (ADR-0177).
+ */
+export declare const HEAVY_FILES: readonly HeavyFile[];

package/dist-pkg/platform/heavy-catalogue.js

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/heavy-catalogue.ts — WHAT IS HEAVY, WHERE IT COMES FROM, AND HOW MUCH IT WEIGHS.
+//
+// 📌 APART FROM THE FETCHER on purpose: the list is DATA and changes by recorded decision; the fetcher is a rule and
+// changes by defect found. Together, every URL fix would touch the file that decides the download order, and every
+// order fix would touch the list a record governs.
+//
+// 📌 Every address is written ONCE, where its module owns it: Kokoro's in `platform/kokoro`, the vision runtime's here.
+import { KOKORO_VOICES, KOKORO_MODEL_URL, URL_DO_TOKENIZADOR_KOKORO, kokoroVoiceUrl, KOKORO_VOICES_SHA256, KOKORO_VOICE_BYTES, KOKORO_MODEL_SHA256, KOKORO_MODEL_BYTES, SHA256_DO_TOKENIZADOR_KOKORO, BYTES_DO_TOKENIZADOR_KOKORO, } from './kokoro.js';
+/** The Cache Storage name. Versioned: changing the catalogue's content must not serve old bytes. */
+// v2 since issue #168: what v1 kept was never checked against a hash, so it is not trusted — it is fetched again, checked.
+export const CACHE_HEAVY = 'incl-pesados-v2';
+/**
+ * THE VISION RUNTIME — **MediaPipe**, decided by the Dev (ADR-0124): «… mediapipe (webgazer não), e LPCP: devem
+ * acompanhar a engine». WebGazer, brought back by ADR-0132, left again (ADR-0214).
+ *
+ * 📏 MEASURED 2026-09-09: the three files answer 200 on jsDelivr with `Access-Control-Allow-Origin: *`, at the PINNED
+ * version — 155 439 + 323 377 + 11 756 954 bytes.
+ *
+ * ⚠️ A PINNED CDN IS ALLOWED AND ADR-0116 SAYS WHY: what pillar 8 forbids is depending on the network AFTER the first day.
+ * This comes down at INSTALL, with the rest. 📌 The version goes in the URL, which is what `check:precache` requires of
+ * any external entry: different bytes arrive by a different address, and a pinned entry never freezes.
+ *
+ * 🎯 IT IS THE THREE FILES AND NOT ONLY THE `.wasm`: `vision_bundle.mjs` is what loads it and `vision_wasm_internal.js` is
+ * the Emscripten glue. The wasm alone is a «downloaded» thing that does not run.
+ */
+const MP = 'https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@1.0.1';
+const MP_MODELS = 'https://storage.googleapis.com/mediapipe-models';
+/**
+ * 🔴 THE MODELS, without which the runtime recognises nothing: 11.7 MB of WebAssembly without a `.task` is a download
+ * that does no work. The Dev caught the first version of this list, which carried the runtime and no model.
+ *
+ * 📏 MEASURED, all 200 with open CORS. `float16` and not `float32`: half the weight, and the precision lost is irrelevant
+ * to saying where an iris is on a 320×180 screen.
+ */
+const MEDIAPIPE = Object.freeze([
+    { id: 'visao:runtime', url: `${MP}/vision_bundle.mjs`, bytes: 155_439,
+        sha256: 'd885630c297c0b20b1fe86096cb06291c4c8080876f27852e724f24ac603713f' },
+    { id: 'visao:runtime:cola', url: `${MP}/wasm/vision_wasm_internal.js`, bytes: 323_377,
+        sha256: 'e170ee67dd4e16c1a6fcd8840a206687e5a59b22c20e4a902bc445b095454d73' },
+    { id: 'visao:runtime:wasm', url: `${MP}/wasm/vision_wasm_internal.wasm`, bytes: 11_756_954,
+        sha256: '8da277a733926eacd0474b8704b36742d6ec3231c57a860c5b889dff8f1df886' },
+    { id: 'visao:modelo:rosto', url: `${MP_MODELS}/face_landmarker/face_landmarker/float16/1/face_landmarker.task`, bytes: 3_758_596,
+        sha256: '64184e229b263107bc2b804c6625db1341ff2bb731874b0bcc2fe6544e0bc9ff' },
+    { id: 'visao:modelo:gestos', url: `${MP_MODELS}/gesture_recognizer/gesture_recognizer/float16/1/gesture_recognizer.task`, bytes: 8_373_440,
+        sha256: '97952348cf6a6a4915c2ea1496b4b37ebabc50cbbf80571435643c455f2b0482' },
+    { id: 'visao:modelo:maos', url: `${MP_MODELS}/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task`, bytes: 7_819_105,
+        sha256: 'fbc2a30080c3c557093b5ddfc334698132eb341044ccee322ccf8bcf3607cde1' },
+]);
+/**
+ * THE VOICE RUNTIME (ADR-0216 and its erratum; issue #200): what SPEAKS a neural voice, fetched like the vision runtime and for the
+ * same reason — the engine imports nothing from npm at run time, so a game that never asks for this voice carries none of it, and
+ * the published package stays free of a bundler-only import.
+ *
+ * · espeak-ng turns a sentence into phonemes, in every language the project speaks. GPL-3.0-or-later, compatible with the engine's
+ *   AGPL-3.0 (LICENSES.md); the source travels beside the mirror (ADR-0203 erratum).
+ * · onnxruntime-web runs Kokoro's graph. The `jsep` pair is what its own threads load, which is why both are here: a worker that
+ *   cannot find them answers nothing, and the child hears silence (measured in the quiz demo, #181).
+ *
+ * ⚠️ sha256 MEASURED on the files the dev dependency already put on the build machine, not taken from a page; the first delivery run
+ * is what proves jsDelivr serves the same bytes, because it refuses to write anything else.
+ */
+const ESPEAK = 'https://cdn.jsdelivr.net/npm/espeak-ng@1.0.2';
+const ORT = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.27.0';
+const VOICE_RUNTIME = Object.freeze([
+    { id: 'voz:runtime:fonemas', url: `${ESPEAK}/dist/espeak-ng.js`, bytes: 178_386,
+        sha256: '406c6655a6cacf34d84fc69dc4478c81b71518809080ce2d05df1b706d76429d' },
+    { id: 'voz:runtime:fonemas:wasm', url: `${ESPEAK}/dist/espeak-ng.wasm`, bytes: 18_485_010,
+        sha256: '10d24bb7e4124e983aa9cd8cd96c52c8ea4b607d81956ec70846684e2827d532' },
+    { id: 'voz:runtime:onnx', url: `${ORT}/dist/ort.webgpu.bundle.min.mjs`, bytes: 113_035,
+        sha256: '3a18c7f261e05d44a15b2eef18a28e5f53c044d5d140bcea6066baf1f09c8b53' },
+    { id: 'voz:runtime:onnx:cola', url: `${ORT}/dist/ort-wasm-simd-threaded.jsep.mjs`, bytes: 46_614,
+        sha256: '3ee381d20a80f51a788a1c4a5872f6f1d047538dd4342f4af00062de5f9ea4c6' },
+    { id: 'voz:runtime:onnx:wasm', url: `${ORT}/dist/ort-wasm-simd-threaded.jsep.wasm`, bytes: 26_827_543,
+        sha256: '78feeeb3d08f6bcee94d938ed322f69073bb8076b5f9d34697a574ffba8deb48' },
+]);
+/**
+ * THE READING MODELS (ADR-0201 erratum, ADR-0203; issues #185, #200): what hears a child read aloud, ONE MODEL PER LANGUAGE —
+ * Whisper small for Portuguese, Moonshine streaming small for English and Spanish, the three the lab measured (pt 7.7 % WER,
+ * en 19.3 %, es 7.2 %).
+ *
+ * 🎯 THE ADDRESS IS THE PROJECT'S OWN, and it has to be: these two exports do not exist anywhere else. The Whisper one was made
+ * here (`scripts/models/export-whisper-small.py`) because the ready-made export states no licence, and the Spanish Moonshine was
+ * exported here from weights that ship no ONNX. The project mirrors them under ADR-0203 — «hospedar na Cloudflare do projeto» —
+ * with the licence of each beside it in `the-inclusionist-lfs`.
+ *
+ * ⚠️ AND THEY ARE BIG: 378 MiB for pt, 162 for en, 310 for es. Nobody downloads all three — the start asks only for the child's
+ * language (`heavyAtBoot`), and a game that does not declare `uses: { reading: true }` asks for none of them.
+ *
+ * 📌 The ids are in English while their neighbours are not: what is here stays until the renaming of the whole catalogue (the
+ * English plan, phase 2, a single BREAKING release), and nothing new arrives in Portuguese meanwhile.
+ *
+ * ⚠️ sha256 MEASURED on the mirror's own files, each checked against the `SHA256SUMS` its folder publishes.
+ */
+const READING_MIRROR = 'https://lfs-oinclusionista.jrocha.dev.br';
+const READING = Object.freeze([
+    // pt — Whisper small, exported and quantized by this project
+    { id: 'reading:pt:encoder', url: `${READING_MIRROR}/whisper-small-onnx/onnx/encoder_model_quantized.onnx`, bytes: 95_131_296,
+        sha256: '25eae0fce49960d460d800c53a9df788afdf54baceee16ab6a6333869e2fc78f' },
+    { id: 'reading:pt:decoder', url: `${READING_MIRROR}/whisper-small-onnx/onnx/decoder_model_quantized.onnx`, bytes: 156_551_161,
+        sha256: '63e48cd0bef0f3367f4611728f38bf8f123af545212a2e744fe2ec28e0e887a3' },
+    { id: 'reading:pt:decoder:past', url: `${READING_MIRROR}/whisper-small-onnx/onnx/decoder_with_past_model_quantized.onnx`, bytes: 142_305_767,
+        sha256: '670b3e8b846f4e86dd3c26930bb671dec2df476b81c138c1864db37aa8bc92c0' },
+    { id: 'reading:pt:tokenizer', url: `${READING_MIRROR}/whisper-small-onnx/tokenizer.json`, bytes: 2_480_466,
+        sha256: '27fc476bfe7f17299480be2273fc0608e4d5a99aba2ab5dec5374b4482d1a566' },
+    { id: 'reading:pt:config', url: `${READING_MIRROR}/whisper-small-onnx/config.json`, bytes: 1_967,
+        sha256: 'e6a2b489da1b5aed65a8eb8d1e7466fa867ad5643a8bc138ba708bd56b2875c4' },
+    // what the reading must NOT invent: the tokens Whisper suppresses, and the mel filterbank its features are built with
+    { id: 'reading:pt:generation', url: `${READING_MIRROR}/whisper-small-onnx/generation_config.json`, bytes: 3_868,
+        sha256: '71565b8ef50d0bf7a1193ed4bbed195b94e70c18894d81bba2f1233dcec3ab53' },
+    { id: 'reading:pt:preprocessor', url: `${READING_MIRROR}/whisper-small-onnx/preprocessor_config.json`, bytes: 184_990,
+        sha256: '9b5cd03a36fbb8a627c64d98a5b5b126ead95a77720723944487311f0110b666' },
+    // en — Moonshine streaming small, the Workmind ONNX export, copied unchanged (MIT)
+    { id: 'reading:en:encoder', url: `${READING_MIRROR}/moonshine-streaming-small-onnx/onnx/encoder_model_quantized.onnx`, bytes: 74_923_158,
+        sha256: '69c786908794eb9e2e50d7137c4e755abdde7b4bdebffd68fe0c292eee5ffc55' },
+    { id: 'reading:en:decoder', url: `${READING_MIRROR}/moonshine-streaming-small-onnx/onnx/decoder_model_merged_quantized.onnx`, bytes: 90_830_447,
+        sha256: '3bd2e7a7e94c608b1988fa035be1f1b1f2acdbe059f7fe5cc70d85201c2835f5' },
+    { id: 'reading:en:tokenizer', url: `${READING_MIRROR}/moonshine-streaming-small-onnx/tokenizer.json`, bytes: 3_761_754,
+        sha256: '7b913404bdd039af4756783218af4440bc07fb7d6d8258d677e34f95b3ec416f' },
+    { id: 'reading:en:config', url: `${READING_MIRROR}/moonshine-streaming-small-onnx/config.json`, bytes: 1_745,
+        sha256: '849ca79b5af5603b1e7b8eeebf67265f931c70117434446fca6f35a26fc03df1' },
+    { id: 'reading:en:generation', url: `${READING_MIRROR}/moonshine-streaming-small-onnx/generation_config.json`, bytes: 163,
+        sha256: 'fd54ad15ad0a14f68db3c58a8d8e5e8f3791ef95e1ea92ee46cd71b4a5d7528c' },
+    // es — Moonshine streaming small, exported here from the upstream weights. ⚠️ Its encoder is fp32 and the biggest file of the
+    // three: quantized to q8 it drifted in the lab, and a reading that mis-hears a child is worse than a bigger download.
+    { id: 'reading:es:encoder', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/onnx/encoder_model.onnx`, bytes: 205_951_994,
+        sha256: 'e675a5cf070ed40da516f1648bea62eb21f77421f1c490cedfe0d16bdc77a090' },
+    { id: 'reading:es:decoder', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/onnx/decoder_model_quantized.onnx`, bytes: 63_639_862,
+        sha256: '6775c2b74f429ae202e5a11cc0db7e291a0e593641364ddf416613d130528fcf' },
+    { id: 'reading:es:decoder:past', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/onnx/decoder_with_past_model_quantized.onnx`, bytes: 55_504_894,
+        sha256: '9cddfa057c8b5d65d3e5057b748b6f6b58753306846dd0fa4d0e8639cb22bfd9' },
+    { id: 'reading:es:tokenizer', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/tokenizer.json`, bytes: 476_245,
+        sha256: 'e8dae7af9c2b6e5a1f413819db1eb70837ff4cf53b5a482a37f2ffc608b8b977' },
+    { id: 'reading:es:config', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/config.json`, bytes: 1_653,
+        sha256: 'bfd932c804df9cde662468a8f933763cd5174bfed2c043b2440b4daaa702efbd' },
+    { id: 'reading:es:generation', url: `${READING_MIRROR}/moonshine-streaming-small-es-onnx/generation_config.json`, bytes: 246,
+        sha256: '3e5f0aa2b32615a4023d0a08cccb7c1ec292aba9a8d8f6f4886df2a769af31b0' },
+]);
+/** The language a reading id serves, or `null` where the id is not a reading model's. */
+export function readingLanguageOf(id) {
+    const parts = id.split(':');
+    return parts[0] === 'reading' && parts[1] ? parts[1] : null;
+}
+/**
+ * THE COMMAND MODELS (ADR-0189, ADR-0193, ADR-0194; issue #184): what hears a child SAY A WORD OF THE GAME. Not the same job as
+ * the reading above, and not the same tool: a command is heard against a CLOSED GRAMMAR — the names the menu is showing right
+ * now — which is why 32 MiB answer in 0.25 s what 378 MiB of Whisper answered in seconds and, on single words, wrongly (📏 lab:
+ * Vosk 7/7 commands, Whisper base 1/7).
+ *
+ * 🎯 THE RUNTIME IS THE PROJECT'S OWN BUILD, and that is the whole reason it exists: every published `vosk-browser` evaluates
+ * text as code, which this engine's Content-Security-Policy refuses (ADR-0193 — never `'unsafe-eval'`, never a patch). It was
+ * rebuilt from lichess-org/vosk-browser with `-s DYNAMIC_EXECUTION=0` and runs under the policy as it is (`models.md`).
+ * The models are alphacephei's small ones, repacked deterministically as the `.tar.gz` that build loads.
+ *
+ * ⚠️ ONE MODEL PER LANGUAGE, like the reading: pt 30.9 MiB, en 39.2, es 37.9. The start asks for the child's, and a delivery
+ * carries the ones it was built with (`inclusionist-heavy --commands pt`). 📌 Unlike the reading, NO GAME DECLARES THIS: a
+ * child who speaks instead of pressing is using a transport, and a cartridge does not get to deny her one (ADR-0111).
+ *
+ * ⚠️ sha256 MEASURED on the mirror's own files (2026-09-21), each checked against the `SHA256SUMS` its folder publishes.
+ */
+const COMMANDS = Object.freeze([
+    { id: 'commands:runtime', url: `${READING_MIRROR}/vosk-browser-dynamic-execution-0/vosk.wasm.js`, bytes: 10_288,
+        sha256: 'a7ab48dcf72660ec79a493c37b9fd1d0b3c09c46968c6a1ebd06adb4d9a35ca6' },
+    { id: 'commands:runtime:worker', url: `${READING_MIRROR}/vosk-browser-dynamic-execution-0/vosk.worker.js`, bytes: 194_710,
+        sha256: 'cf84a33820a1634d6a8d11194f2bd04f871901bf630ba1423c24f6be13086b6a' },
+    { id: 'commands:runtime:wasm', url: `${READING_MIRROR}/vosk-browser-dynamic-execution-0/vosk.wasm`, bytes: 2_992_690,
+        sha256: 'e2a33196eacd6cd7d863392f877b9360664d7614ce97cddf9de5b5e637e2ccf9' },
+    { id: 'commands:model:pt', url: `${READING_MIRROR}/vosk-models/vosk-model-small-pt-0.3.tar.gz`, bytes: 32_358_733,
+        sha256: '4885a09d9cd3063bf991e2ae280f24eeee789410aaa05277a2e082cff0cf837d' },
+    { id: 'commands:model:en', url: `${READING_MIRROR}/vosk-models/vosk-model-small-en-us-0.15.tar.gz`, bytes: 41_116_539,
+        sha256: '61cf40721d255cccb9fe29bb059c6b3376b164c31f449d8143455ffbb86018cc' },
+    { id: 'commands:model:es', url: `${READING_MIRROR}/vosk-models/vosk-model-small-es-0.42.tar.gz`, bytes: 39_748_927,
+        sha256: '4ed16b681698db764ecb11996b1b4f74dd68f602213b36c17806a1398b26b162' },
+]);
+/**
+ * The language a command MODEL serves, or `null` for anything else — including the runtime, which serves every language.
+ * ⚠️ The middle word is read on purpose: `id.split(':')[1]` would call the runtime a language of its own and leave the three
+ * models behind it out of the start of every delivery.
+ */
+export function commandsLanguageOf(id) {
+    const parts = id.split(':');
+    return parts[0] === 'commands' && parts[1] === 'model' && parts[2] ? parts[2] : null;
+}
+/**
+ * KOKORO (ADR-0186, ADR-0198; the Dev: «Faça»): the fp32 model, its tokenizer vocabulary and a style table per voice of the engine's
+ * languages. The engine loads them itself when a game declares `uses.neuralVoice` (ADR-0216); the phonemizer and the runtime that
+ * speak them are `VOICE_RUNTIME`, above.
+ */
+const KOKORO = Object.freeze([
+    { id: 'voz:kokoro:modelo', url: KOKORO_MODEL_URL, bytes: KOKORO_MODEL_BYTES, sha256: KOKORO_MODEL_SHA256 },
+    { id: 'voz:kokoro:tokenizador', url: URL_DO_TOKENIZADOR_KOKORO, bytes: BYTES_DO_TOKENIZADOR_KOKORO, sha256: SHA256_DO_TOKENIZADOR_KOKORO },
+    ...KOKORO_VOICES.map((v) => ({ id: `voz:kokoro:${v.voice}`, url: kokoroVoiceUrl(v.voice), bytes: KOKORO_VOICE_BYTES, sha256: KOKORO_VOICES_SHA256[v.voice] })),
+]);
+/**
+ * 📌 Every entry with an address needs its licence group in `scripts/licences/third-party.mjs`: the delivery writes that group's
+ * `LICENSE` and `NOTICE` beside the file, and refuses a file whose licence nobody recorded (ADR-0177).
+ */
+export const HEAVY_FILES = Object.freeze([
+    ...VOICE_RUNTIME,
+    ...KOKORO,
+    // what hears a child read aloud, one model per language (ADR-0216 §2); the runtime that runs them is the voice's, above
+    ...READING,
+    // what hears a child SAY a word of the game, one model per language, with a runtime of its own (issue #184)
+    ...COMMANDS,
+    // the vision runtime and its models: eye control reads the face (ADR-0213); WebGazer left (ADR-0214)
+    ...MEDIAPIPE,
+    /*
+     * 🔴 THE ART COLLECTION — the fourth heavy thing of ADR-0119, and the only one WITHOUT A SOURCE. Measured: `art/` has
+     * TWO files — a README and a 40-byte `ATTRIBUTION.csv`, the header only. No art.
+     *
+     * 📌 The reason is simple: no collection has been chosen. Art enters under CC0, CC BY 3.0, CC BY 4.0 or OGA-BY, with a
+     * ledger line per asset and its source URL — and none of that is one URL a fetcher can ask for. (The Liberated Pixel
+     * Cup was refused by ADR-0133: both its arms are share-alike or GPL, outside the closed list of four licences.) This
+     * line's source is the day there is a collection.
+     */
+    {
+        id: 'arte:acervo',
+        url: null,
+        whyNoSource: 'não há acervo escolhido: `art/` tem só README e cabeçalho do CSV. O ADR-0133 fechou '
+            + 'a lista em CC0, CC BY 3.0/4.0 e OGA-BY, e a arte entra recurso a recurso com autoria e URL de '
+            + 'origem — não por uma URL solta que este buscador possa pedir.',
+    },
+]);

package/dist-pkg/platform/heavy-mirror.d.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Upstream prefix → the path the mirror serves it under. Measured against the staging tree on 2026-09-21. */
+export declare const MIRROR_FOLDERS: ReadonlyArray<readonly [string, string]>;
+/**
+ * Addresses the project does NOT mirror, each with why — they go on being fetched upstream even when a base is set.
+ *
+ * 🔴 AND THE ENTRY BELOW CAME BACK THE SAME DAY IT LEFT, which is worth writing rather than hiding. The Dev decided to mirror
+ * both of the last two third-party addresses («Ok, vamos espelhar»), so this list was emptied — and 📏 measuring the bucket
+ * after the upload showed `espeak-ng` answering **404** while the three `onnxruntime-web` files answer 200 with exactly the
+ * catalogued byte counts. Nothing failed: the staging folder is marked «🔴 ON HOLD» and `upload-to-r2.ps1` skips it, because
+ * espeak-ng is GPL-3.0-or-later and serving the binary obliges publishing the matching SOURCE beside it (ADR-0203 erratum,
+ * issue #192). Emptying the list without checking what the bucket serves would have pointed every school at a 404.
+ *
+ * ⚠️ So it stays upstream until `espeak-ng-1.0.2/source/` exists. The decision to mirror it is unchanged; what is missing is
+ * the obligation that decision carries, and a mirror is distribution.
+ */
+export declare const NOT_MIRRORED: ReadonlyArray<readonly [string, string]>;
+/** The path a mirror serves this upstream address under, or `null` when no mirror of this project holds it. */
+export declare function mirrorPathOf(url: string): string | null;
+/**
+ * Where to fetch this file from: the base's copy when there is a base and the file is mirrored, upstream otherwise.
+ * A base may be an address (`https://…`) or a folder on this machine — the caller knows how to open each.
+ */
+export declare function heavySourceOf(url: string, base?: string | null): string;
+/** Is this base an address, or a folder on the machine running the build? */
+export declare const baseIsRemote: (base: string) => boolean;

package/dist-pkg/platform/heavy-mirror.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/heavy-mirror — WHERE A HEAVY FILE IS FETCHED FROM, WHEN IT IS NOT FETCHED FROM UPSTREAM.
+//
+// The Dev, 2026-09-21: «Precisamos de um .env que aponte para local quando estivermos testando em local e em
+// <a conta R2> quando estivermos usando estes recursos na minha conta. Isso facilitaria quando tivermos que hospedar em
+// outros servidores.»
+//
+// The catalogue pins an upstream address AND the sha256 of the bytes (ADR-0177, issue #168). A mirror serves those same
+// bytes somewhere else — the project's Cloudflare, a school's own server, a folder on the build machine — so the only thing
+// that changes is the BASE. Everything else, including the check, stays: a base that serves other bytes fails the sha256 and
+// nothing is written. That is what makes pointing elsewhere safe, and it is why this module does not need to be trusted.
+//
+// The staging tree (`the-inclusionist-lfs`) lays each artefact out as its future Hugging Face repository, so the path under
+// the base is NOT the upstream host and path — it is the folder the mirror uses. That mapping is here, once.
+/** Upstream prefix → the path the mirror serves it under. Measured against the staging tree on 2026-09-21. */
+// ⚠️ Written WITHOUT a trailing slash, exactly as the network inventory (`tests/nothing-comes-from-outside`) already declares each of
+// them: an address that differs by one character reads as a new supplier entering without a decision.
+export const MIRROR_FOLDERS = [
+    ['https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX/resolve/main', 'kokoro-82m-v1.0-onnx'],
+    ['https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@1.0.1', 'mediapipe-tasks-vision-1.0.1/tasks-vision@1.0.1'],
+    ['https://storage.googleapis.com/mediapipe-models', 'mediapipe-tasks-vision-1.0.1/models'],
+    // 📌 The reading models have NO upstream: both exports were made by this project (ADR-0201 erratum, ADR-0203), so the address
+    // the catalogue pins is already the mirror's. They are listed all the same, and that is what lets a build read them from the
+    // staging tree on disk — 850 MiB that nobody should download twice.
+    ['https://lfs-oinclusionista.jrocha.dev.br/whisper-small-onnx', 'whisper-small-onnx'],
+    ['https://lfs-oinclusionista.jrocha.dev.br/moonshine-streaming-small-onnx', 'moonshine-streaming-small-onnx'],
+    ['https://lfs-oinclusionista.jrocha.dev.br/moonshine-streaming-small-es-onnx', 'moonshine-streaming-small-es-onnx'],
+    // The command models and the runtime that loads them (issue #184). The runtime has no upstream either — every published
+    // `vosk-browser` evaluates text as code, so this one was rebuilt with `-s DYNAMIC_EXECUTION=0` to run under the policy.
+    ['https://lfs-oinclusionista.jrocha.dev.br/vosk-browser-dynamic-execution-0', 'vosk-browser-dynamic-execution-0'],
+    ['https://lfs-oinclusionista.jrocha.dev.br/vosk-models', 'vosk-models'],
+    // The neural voice's phonemizer and the graph runtime it shares with the reading models (issue #192, the Dev on 2026-09-22).
+    // ⚠️ espeak-ng is GPL-3.0-or-later: the folder must carry the matching SOURCE beside the binary, and `docs/CREDITS.md` says
+    // where. The version is in the folder name on purpose — a mirror that drops it cannot serve two versions during an upgrade.
+    ['https://cdn.jsdelivr.net/npm/espeak-ng@1.0.2', 'espeak-ng-1.0.2'],
+    ['https://cdn.jsdelivr.net/npm/onnxruntime-web@1.27.0', 'onnxruntime-web-1.27.0'],
+];
+/**
+ * Addresses the project does NOT mirror, each with why — they go on being fetched upstream even when a base is set.
+ *
+ * 🔴 AND THE ENTRY BELOW CAME BACK THE SAME DAY IT LEFT, which is worth writing rather than hiding. The Dev decided to mirror
+ * both of the last two third-party addresses («Ok, vamos espelhar»), so this list was emptied — and 📏 measuring the bucket
+ * after the upload showed `espeak-ng` answering **404** while the three `onnxruntime-web` files answer 200 with exactly the
+ * catalogued byte counts. Nothing failed: the staging folder is marked «🔴 ON HOLD» and `upload-to-r2.ps1` skips it, because
+ * espeak-ng is GPL-3.0-or-later and serving the binary obliges publishing the matching SOURCE beside it (ADR-0203 erratum,
+ * issue #192). Emptying the list without checking what the bucket serves would have pointed every school at a 404.
+ *
+ * ⚠️ So it stays upstream until `espeak-ng-1.0.2/source/` exists. The decision to mirror it is unchanged; what is missing is
+ * the obligation that decision carries, and a mirror is distribution.
+ */
+export const NOT_MIRRORED = [
+    ['https://cdn.jsdelivr.net/npm/espeak-ng@1.0.2',
+        'GPL: the mirror folder is ON HOLD until the matching source is published beside the build (issue #192)'],
+];
+/** The path a mirror serves this upstream address under, or `null` when no mirror of this project holds it. */
+export function mirrorPathOf(url) {
+    if (NOT_MIRRORED.some(([prefix]) => url.startsWith(prefix)))
+        return null;
+    for (const [upstream, folder] of MIRROR_FOLDERS)
+        if (url.startsWith(`${upstream}/`))
+            return folder + url.slice(upstream.length);
+    return null;
+}
+/**
+ * Where to fetch this file from: the base's copy when there is a base and the file is mirrored, upstream otherwise.
+ * A base may be an address (`https://…`) or a folder on this machine — the caller knows how to open each.
+ */
+export function heavySourceOf(url, base) {
+    const path = base ? mirrorPathOf(url) : null;
+    if (!path)
+        return url;
+    return `${base.replace(/[/\\]+$/, '')}/${path}`;
+}
+/** Is this base an address, or a folder on the machine running the build? */
+// ⚠️ `\/{2}` and not `\/\/`: a gate reads the tree as text, and two slashes in a row are how a line comment starts.
+export const baseIsRemote = (base) => /^https?:\/{2}/i.test(base);

package/dist-pkg/platform/heavy.d.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { CACHE_HEAVY, HEAVY_FILES, type HeavyFile } from './heavy-catalogue.js';
+export { CACHE_HEAVY, HEAVY_FILES };
+export type { HeavyFile };
+/** What happened to each entry, so the caller can tell a person. */
+export interface HeavyReport {
+    readonly id: string;
+    readonly outcome: 'ja-tinha' | 'baixado' | 'falhou' | 'sem-fonte';
+    readonly bytes?: number;
+    readonly error?: string;
+}
+/**
+ * 🔴 WHAT THE DOWNLOAD USES OF THE BROWSER, RECEIVED AND NEVER REACHED (ADR-0232 point 2): the root reads each from the host's
+ * window. Required, because a port that falls back to the global is a global reached one step later (ADR-0224/0227).
+ */
+export interface HeavyOptions {
+    /**
+     * The host's `caches`, as its window answers it: `undefined` where it has none (an insecure context), and then every file
+     * is reported and none fetched. Required all the same — the key is the root's statement of what it lent.
+     */
+    readonly cacheStorage: CacheStorage | undefined;
+    /** The host's `fetch`, `undefined` where it has none, with the same answer. */
+    readonly fetch: typeof fetch | undefined;
+    /** Called on each resolved entry — what lets the interface say what is happening. */
+    readonly onProgress?: (r: HeavyReport) => void;
+    /**
+     * The SHA-256 of a body, as lowercase hex (issue #168) — `sha256With(crypto.subtle)`. `null` (a host without
+     * `crypto.subtle`, which is an insecure context) keeps NOTHING: unverifiable is not verified.
+     */
+    readonly digest: ((payload: ArrayBuffer) => Promise<string>) | null;
+    /** Only these ids, when given. For a consumer that wants the voices and not the rest. */
+    readonly only?: readonly string[];
+    /** The page's address the delivery's `heavy/` folder is resolved against (`document.baseURI`). */
+    readonly base: string;
+}
+/**
+ * WHAT A GAME'S START FETCHES (ADR-0216 §3): the catalogue, less what this game did not ask for.
+ *
+ * · The neural voice — its model, its voices AND the runtime that speaks them: without that answer they are 372 MB taken from a
+ *   school's link and a child's device for nothing.
+ * · The reading models: 850 MiB for the three languages, so `reading` is not a yes or no but a LANGUAGE — the child's, known at
+ *   boot. A delivery may carry more than one; a device downloads the one being read in. A game that never listens gets none.
+ * · 🔴 THE GRAPH RUNTIME IS NOT THE VOICE'S, and its `voz:` name said otherwise. `platform/onnx-runtime` runs Kokoro AND the
+ *   reading models, so a game that only LISTENS needs it: without this line its delivery carried a 378 MiB model and nothing
+ *   able to open it, and the first `listen()` asked for a file the build never wrote. Measured on 2026-09-21, building the
+ *   very delivery this exists to serve. The PHONEMIZER (`voz:runtime:fonemas`, 18.7 MiB) stays the voice's — nothing else
+ *   turns letters into sounds.
+ * · The command models (issue #184): one per language too, 112 MiB for the three, and the runtime that loads them. Nothing in
+ *   the game decides this — speaking instead of pressing is a way INTO the controller, and a cartridge does not get to close
+ *   one (ADR-0111). What decides is the delivery: `inclusionist-heavy --commands pt` puts Portuguese in it.
+ */
+export declare function heavyAtBoot(declared: {
+    readonly kokoro: boolean;
+    readonly reading?: string | null;
+    readonly commands?: string | null;
+}): readonly string[];
+/**
+ * WHERE THE DELIVERY SERVES A HEAVY FILE (ADR-0177, issue #173): `heavy/<host><path>` beside the page. The child's device
+ * reads it from the game's own origin; the upstream address is only where the build fetched it from.
+ * 📌 The upstream address stays the CACHE KEY: it is what the voice and vision libraries ask for, and the service worker answers
+ * them from the checked cache without a network request.
+ *
+ * 🔴 THE FOLDER WAS CALLED «pesados» UNTIL 2026-09-21 (ADR-0219). 📏 What that costs a school was measured before it changed:
+ * the entries are kept under the UPSTREAM address, so nothing is re-downloaded — what breaks is a delivery built by the old
+ * `bin` under a new engine, which asks for `heavy/…` and gets a 404 until the delivery is built again.
+ */
+export declare function deliveryPath(url: string): string;
+/**
+ * The inverse, for the service worker: a request for `…/heavy/<host><path>` is answered from the entry kept under
+ * `https://<host><path>`; any other address has no key (`null`). It is the route's `cacheKeyWillBeUsed` itself, so it also
+ * takes Workbox's `{ request }`. Self-contained on purpose — the PWA plugin copies this function's SOURCE into `sw.js`, where
+ * nothing else from this module exists.
+ *
+ * ⚠️ THE OFFSET COMES FROM THE FOLDER'S OWN LENGTH, and it is written this way because of what a blind rename would have done
+ * here: the old code advanced by 9, the length of the old folder's name with its slashes, and `/heavy/` is 7 — a text
+ * replacement of the name alone would
+ * have left every cache key with two characters of the host eaten, and the only symptom would be a cache that never hits.
+ */
+export declare function deliveryCacheKey(urlOrRequest: string | {
+    readonly request: {
+        readonly url: string;
+    };
+}): string | null;
+/**
+ * DOWNLOADS WHAT IS MISSING, ONE AT A TIME, AND RETURNS WHAT HAPPENED TO EACH.
+ *
+ * ⚠️ ENTRIES WITHOUT A `url` ARE NOT SKIPPED IN SILENCE — they return `sem-fonte`. It is the difference between "this
+ * subsystem has nowhere to come from yet" and "this subsystem is handled", exactly the distinction ADR-0119 measured as
+ * missing: the engine PROMISED four things and delivered one, with nothing saying so.
+ */
+export declare function downloadHeavy(options: HeavyOptions): Promise<HeavyReport[]>;
+/**
+ * THE SHA-256 OF A BODY AS LOWERCASE HEX, by the `crypto.subtle` it is handed (issue #168) — or `null` when there is none,
+ * which is a host outside a secure context: the answer `HeavyOptions.digest` reads as «cannot hash, so keep nothing».
+ */
+export declare function sha256With(subtle: Pick<SubtleCrypto, 'digest'> | null | undefined): ((payload: ArrayBuffer) => Promise<string>) | null;
+/**
+ * WHETHER A CATALOGUE FILE IS IN THE CHECKED CACHE, by its upstream address — what `platform/vision` and
+ * `platform/vosk-runtime` ask before loading anything. The host's `caches` is handed in; `undefined` (an insecure context)
+ * holds nothing, so every file is missing and the loader names them.
+ */
+export declare function checkedCacheHas(cacheStorage: CacheStorage | undefined): (upstreamUrl: string) => Promise<boolean>;
+/** The size of what is still missing, in bytes — so a notice can say how much is left before it starts. */
+export declare function bytesLeftToDownload(soFar: readonly HeavyReport[]): number;