@the-inclusionist/engine 9.0.0 → 10.0.0

package/dist-pkg/platform/reading-model.d.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** What the engine asks of a language: which catalogue files, and what the encoder eats. */
+export interface ReadingModelPlan {
+    readonly language: string;
+    /** Whisper eats a log-mel spectrogram; Moonshine eats the samples. */
+    readonly input: 'log-mel' | 'waveform';
+    readonly encoder: string;
+    readonly decoder: string;
+    /** The second decoder graph, where the model has one: the first pass builds the cache, this one uses it. */
+    readonly decoderPast?: string;
+    readonly tokenizer: string;
+    readonly generation: string;
+    /** How many heads the caches hold and how wide each is — what a merged decoder needs to be handed empty ones. */
+    readonly config: string;
+    /** Only the mel front end needs one. */
+    readonly preprocessor?: string;
+}
+/** 16 kHz mono, for every one of them: it is what all three were trained on, and resampling is the caller's job. */
+export declare const READING_RATE = 16000;
+/** Whisper reads a 30 s window at a time, always: shorter is padded with silence, longer is cut. */
+export declare const WHISPER_SAMPLES: number;
+export declare const WHISPER_FRAMES = 3000;
+export declare const WHISPER_BANDS = 80;
+export declare const READING_MODELS: readonly ReadingModelPlan[];
+/** The model of a language tag (`pt-BR` → pt), or `null` where the project has none — which the caller must SAY, not hide. */
+export declare function readingModelFor(language: string): ReadingModelPlan | null;
+/**
+ * WHAT WHISPER'S ENCODER EATS: a log-mel spectrogram of 80 bands by 3000 frames, from a 30 s window at 16 kHz.
+ *
+ * The steps are `WhisperFeatureExtractor`'s, in its order, and each one matters: the window is a PERIODIC Hann (a symmetric one
+ * moves every value); the signal is reflected at both ends by half a window, so frame 0 is centred on sample 0; the power
+ * spectrum is the magnitude SQUARED; the last frame is dropped, which is why 480 000 samples give 3000 and not 3001; the floor is
+ * eight decades below the LOUDEST point of this window, not a constant; and the scale ends in (x + 4) / 4.
+ */
+export declare function logMel(samples: Float32Array, melFilters: readonly (readonly number[])[]): Float32Array;
+/** A `tokenizer.json`, in the parts a reading reads: the vocabulary, the added tokens, and which decoder undoes them. */
+export interface TokenizerFile {
+    readonly model?: {
+        readonly vocab?: Readonly<Record<string, number>>;
+    };
+    readonly added_tokens?: readonly {
+        readonly id: number;
+        readonly content: string;
+        readonly special?: boolean;
+    }[];
+    readonly decoder?: {
+        readonly type?: string;
+    };
+}
+/**
+ * WHAT THE CHILD ACTUALLY SAID, from the ids the decoder answered.
+ *
+ * The two families undo themselves differently and the file says which: Whisper writes every byte as a printable character
+ * (`ByteLevel`), Moonshine writes a space as `▁` and a rare byte as `<0x..>` (`Replace` + `ByteFallback` + `Fuse` + `Strip`).
+ * Both end in ONE decode of UTF-8, which is what keeps an accent that spans two tokens from becoming two broken characters.
+ */
+export declare function readingTextOf(tokenizer: TokenizerFile, ids: readonly number[]): string;
+/** What a `generation_config.json` says must never be answered — Whisper's list of tokens that are not speech. */
+export interface GenerationConfig {
+    readonly suppress_tokens?: readonly number[];
+    readonly begin_suppress_tokens?: readonly number[];
+    readonly eos_token_id?: number;
+    readonly decoder_start_token_id?: number;
+}
+/**
+ * The tokens refused at this step. `atStart` is the first answered token, where Whisper also refuses the ones that would make it
+ * open with a silence or a punctuation mark — without this it answers «.» to a child who read a whole sentence.
+ */
+export declare function suppressedTokens(config: GenerationConfig, atStart: boolean): ReadonlySet<number>;
+/** The id of a named token (`<|pt|>`, `<|transcribe|>`), or `null` — a model that does not have it must be SAID, not guessed. */
+export declare function tokenIdOf(tokenizer: TokenizerFile, content: string): number | null;
+/** The next token: the biggest logit that is not refused. Greedy, because a child reading a known text needs no imagination. */
+export declare function nextToken(logits: ArrayLike<number>, suppressed?: ReadonlySet<number>): number;

package/dist-pkg/platform/reading-model.js

@@ -0,0 +1,247 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/reading-model — WHAT A READING MODEL NEEDS DONE TO SOUND AND TO TOKENS, in its pure half (ADR-0216 §2; issues #185, #200).
+//
+// The engine hears a child read aloud with one model per language (ADR-0201 erratum): Whisper small for Portuguese, Moonshine
+// streaming small for English and Spanish. Around the graphs there is arithmetic that has nothing to do with a browser — turning
+// sound into what the encoder eats, and turning the numbers the decoder answers back into words — and it lives here, where it can
+// be measured. `platform/reading-runtime` is the half that opens sessions and fetches files.
+//
+// 🎯 MEASURED AGAINST THE ORIGINALS, not against my idea of them: `tests/fixtures/reading-ground-truth.json` is what
+// `WhisperFeatureExtractor` and the three tokenizers answer for one deterministic signal and three phrases, written by
+// `scratchpad/verdade-da-leitura.py`. A front end that is subtly wrong still runs and still returns text — the wrong text — so
+// «it produced something» is not a check.
+//
+// · THE MEL FILTERS ARE NOT COMPUTED HERE. Whisper's own `preprocessor_config.json` carries them (80 × 201), which is most of its
+//   185 KB, and the catalogue already fetches it: a filterbank rebuilt from a formula is a second opinion about the model's input.
+// · Moonshine takes the WAVEFORM. No spectrogram, no padding to 30 s — it is a different front end, not a variant of this one.
+/** 16 kHz mono, for every one of them: it is what all three were trained on, and resampling is the caller's job. */
+export const READING_RATE = 16_000;
+/** Whisper reads a 30 s window at a time, always: shorter is padded with silence, longer is cut. */
+export const WHISPER_SAMPLES = 30 * READING_RATE;
+export const WHISPER_FRAMES = 3000;
+export const WHISPER_BANDS = 80;
+const N_FFT = 400;
+const HOP = 160;
+const HALF = N_FFT / 2;
+const BINS = HALF + 1;
+/** What a band is when its power is clipped: the original clips at 1e-10 before the log. */
+const CLIPPED = Math.log10(1e-10);
+export const READING_MODELS = Object.freeze([
+    {
+        language: 'pt', input: 'log-mel',
+        encoder: 'reading:pt:encoder', decoder: 'reading:pt:decoder', decoderPast: 'reading:pt:decoder:past',
+        tokenizer: 'reading:pt:tokenizer', generation: 'reading:pt:generation', config: 'reading:pt:config',
+        preprocessor: 'reading:pt:preprocessor',
+    },
+    {
+        language: 'en', input: 'waveform',
+        encoder: 'reading:en:encoder', decoder: 'reading:en:decoder',
+        tokenizer: 'reading:en:tokenizer', generation: 'reading:en:generation', config: 'reading:en:config',
+    },
+    {
+        language: 'es', input: 'waveform',
+        encoder: 'reading:es:encoder', decoder: 'reading:es:decoder', decoderPast: 'reading:es:decoder:past',
+        tokenizer: 'reading:es:tokenizer', generation: 'reading:es:generation', config: 'reading:es:config',
+    },
+]);
+/** The model of a language tag (`pt-BR` → pt), or `null` where the project has none — which the caller must SAY, not hide. */
+export function readingModelFor(language) {
+    const tag = language.split('-')[0].toLowerCase();
+    return READING_MODELS.find((m) => m.language === tag) ?? null;
+}
+/**
+ * WHAT WHISPER'S ENCODER EATS: a log-mel spectrogram of 80 bands by 3000 frames, from a 30 s window at 16 kHz.
+ *
+ * The steps are `WhisperFeatureExtractor`'s, in its order, and each one matters: the window is a PERIODIC Hann (a symmetric one
+ * moves every value); the signal is reflected at both ends by half a window, so frame 0 is centred on sample 0; the power
+ * spectrum is the magnitude SQUARED; the last frame is dropped, which is why 480 000 samples give 3000 and not 3001; the floor is
+ * eight decades below the LOUDEST point of this window, not a constant; and the scale ends in (x + 4) / 4.
+ */
+export function logMel(samples, melFilters) {
+    const audio = new Float32Array(WHISPER_SAMPLES);
+    audio.set(samples.subarray(0, WHISPER_SAMPLES));
+    // the reflected padding, written once: `at(i)` is the padded signal, so no copy of 480 000 samples is made
+    const at = (i) => {
+        const j = i - HALF;
+        if (j < 0)
+            return audio[-j];
+        if (j >= WHISPER_SAMPLES)
+            return audio[2 * WHISPER_SAMPLES - j - 2];
+        return audio[j];
+    };
+    const turns = dftTurns();
+    const out = new Float32Array(WHISPER_BANDS * WHISPER_FRAMES);
+    const power = new Float64Array(BINS);
+    let loudest = -Infinity;
+    for (let frame = 0; frame < WHISPER_FRAMES; frame++) {
+        const start = frame * HOP;
+        // 🎯 A WINDOW OF PURE SILENCE IS ANSWERED, NOT COMPUTED, and it is EXACT: every bin of a window of zeros is zero, so every
+        // band is the clipped value. A child reads for a few seconds into a 30 s window, so most frames are this one. It never
+        // raises the loudest point: no computed band is ever below the clip, and an all-silent window floors at −∞.
+        let quiet = true;
+        for (let n = 0; n < N_FFT && quiet; n++)
+            quiet = at(start + n) === 0;
+        if (quiet) {
+            for (let band = 0; band < WHISPER_BANDS; band++)
+                out[band * WHISPER_FRAMES + frame] = CLIPPED;
+            continue;
+        }
+        powerOf(at, start, turns, power);
+        loudest = Math.max(loudest, melOf(power, melFilters, out, frame));
+    }
+    // the floor is eight decades below the LOUDEST point of this window, not a constant, and the scale ends in (x + 4) / 4
+    const floor = loudest - 8;
+    for (let i = 0; i < out.length; i++)
+        out[i] = (Math.max(out[i], floor) + 4) / 4;
+    return out;
+}
+/** A PERIODIC Hann window: a symmetric one moves every value. 400 numbers, computed once. */
+const HANN = Float64Array.from({ length: N_FFT }, (_, i) => 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / N_FFT));
+/**
+ * ⚠️ THE TURNS ARE COMPUTED ONCE. A 400-point real DFT for 201 bins is 80 400 sines and cosines per frame, and there are 3000
+ * frames: asking `Math.cos` for them each time is a quarter of a billion calls, which on a school machine is not «slower», it is
+ * a child waiting half a minute to be told what they read.
+ */
+function dftTurns() {
+    const cos = new Float64Array(BINS * N_FFT);
+    const sin = new Float64Array(BINS * N_FFT);
+    for (let k = 0; k < BINS; k++) {
+        for (let n = 0; n < N_FFT; n++) {
+            const angle = (-2 * Math.PI * k * n) / N_FFT;
+            cos[k * N_FFT + n] = Math.cos(angle);
+            sin[k * N_FFT + n] = Math.sin(angle);
+        }
+    }
+    return { cos, sin };
+}
+/** One frame's power spectrum: the windowed DFT's magnitude SQUARED, one value per bin. */
+function powerOf(at, start, turns, power) {
+    for (let k = 0; k < BINS; k++) {
+        let re = 0, im = 0;
+        const row = k * N_FFT;
+        for (let n = 0; n < N_FFT; n++) {
+            const x = at(start + n) * HANN[n];
+            re += x * turns.cos[row + n];
+            im += x * turns.sin[row + n];
+        }
+        power[k] = re * re + im * im;
+    }
+}
+/** One frame's 80 bands, each the power through its mel filter, clipped at 1e-10 BEFORE the log. Answers the frame's loudest. */
+function melOf(power, melFilters, out, frame) {
+    let loudest = -Infinity;
+    for (let band = 0; band < WHISPER_BANDS; band++) {
+        const filter = melFilters[band];
+        let sum = 0;
+        for (let k = 0; k < BINS; k++)
+            sum += power[k] * filter[k];
+        const value = Math.log10(Math.max(sum, 1e-10));
+        out[band * WHISPER_FRAMES + frame] = value;
+        if (value > loudest)
+            loudest = value;
+    }
+    return loudest;
+}
+/** id → the piece of text that token stands for, with the special ones (`<|pt|>`, `</s>`…) marked so they never reach a child. */
+function piecesOf(tokenizer) {
+    const text = new Map();
+    for (const [piece, id] of Object.entries(tokenizer.model?.vocab ?? {}))
+        text.set(id, piece);
+    const special = new Set();
+    for (const added of tokenizer.added_tokens ?? []) {
+        text.set(added.id, added.content);
+        // ⚠️ `special` is absent on some files and the mark is what keeps `<|startoftranscript|>` out of a child's sentence, so the
+        // shape of the content decides when the flag does not: every one of them is bracketed.
+        if (added.special ?? /^<.*>$/.test(added.content))
+            special.add(added.id);
+    }
+    return { text, special };
+}
+/** The bytes GPT-2 writes as themselves: its three printable ranges, inclusive (`bytes_to_unicode`, openai/gpt-2 `encoder.py`). */
+const PRINTABLE_RANGES = [[33, 126], [161, 172], [174, 255]];
+// GPT-2's byte alphabet: the printable character each byte is written as, so a tokenizer file stays text. Whisper's decoder is
+// this one (`ByteLevel`), and reversing it is the whole of it.
+const byteOfChar = (() => {
+    const map = new Map();
+    const printable = [];
+    for (const [lo, hi] of PRINTABLE_RANGES)
+        for (let b = lo; b <= hi; b++)
+            printable.push(b);
+    for (const b of printable)
+        map.set(String.fromCharCode(b), b);
+    let next = 0;
+    for (let b = 0; b < 256; b++) {
+        if (printable.includes(b))
+            continue;
+        map.set(String.fromCharCode(256 + next), b);
+        next++;
+    }
+    return map;
+})();
+const BYTE_FALLBACK = /^<0x([0-9A-Fa-f]{2})>$/;
+/**
+ * WHAT THE CHILD ACTUALLY SAID, from the ids the decoder answered.
+ *
+ * The two families undo themselves differently and the file says which: Whisper writes every byte as a printable character
+ * (`ByteLevel`), Moonshine writes a space as `▁` and a rare byte as `<0x..>` (`Replace` + `ByteFallback` + `Fuse` + `Strip`).
+ * Both end in ONE decode of UTF-8, which is what keeps an accent that spans two tokens from becoming two broken characters.
+ */
+export function readingTextOf(tokenizer, ids) {
+    const { text, special } = piecesOf(tokenizer);
+    const byteLevel = tokenizer.decoder?.type === 'ByteLevel';
+    const bytes = [];
+    for (const id of ids) {
+        if (special.has(id))
+            continue;
+        const piece = text.get(id);
+        if (piece === undefined)
+            continue; // an id the vocabulary does not have is not a character: it is dropped, never guessed
+        if (byteLevel) {
+            for (const ch of piece)
+                bytes.push(byteOfChar.get(ch) ?? ch.charCodeAt(0));
+            continue;
+        }
+        const fallback = BYTE_FALLBACK.exec(piece);
+        if (fallback) {
+            bytes.push(parseInt(fallback[1], 16));
+            continue;
+        }
+        for (const b of new TextEncoder().encode(piece.replaceAll('▁', ' ')))
+            bytes.push(b);
+    }
+    const whole = new TextDecoder().decode(Uint8Array.from(bytes));
+    return byteLevel ? whole : whole.replace(/^ /, '');
+}
+/**
+ * The tokens refused at this step. `atStart` is the first answered token, where Whisper also refuses the ones that would make it
+ * open with a silence or a punctuation mark — without this it answers «.» to a child who read a whole sentence.
+ */
+export function suppressedTokens(config, atStart) {
+    const out = new Set(config.suppress_tokens ?? []);
+    if (atStart)
+        for (const id of config.begin_suppress_tokens ?? [])
+            out.add(id);
+    return out;
+}
+/** The id of a named token (`<|pt|>`, `<|transcribe|>`), or `null` — a model that does not have it must be SAID, not guessed. */
+export function tokenIdOf(tokenizer, content) {
+    for (const added of tokenizer.added_tokens ?? [])
+        if (added.content === content)
+            return added.id;
+    const fromVocab = tokenizer.model?.vocab?.[content];
+    return fromVocab ?? null;
+}
+/** The next token: the biggest logit that is not refused. Greedy, because a child reading a known text needs no imagination. */
+export function nextToken(logits, suppressed) {
+    let best = -1, bestValue = -Infinity;
+    for (let id = 0; id < logits.length; id++) {
+        if (suppressed?.has(id))
+            continue;
+        const value = logits[id];
+        if (value > bestValue) {
+            bestValue = value;
+            best = id;
+        }
+    }
+    return best;
+}

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

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type OnnxRuntime } from './onnx-runtime.js';
+/** What the engine gets back: something that turns samples into words. */
+export interface ReadingTranscriber {
+    /** 16 kHz mono samples in, the child's words out. Empty when the model answered nothing. */
+    transcribe(samples: Float32Array): Promise<string>;
+}
+export interface ReadingRuntimeDeps {
+    /** The page's address, which `heavy/` is resolved against. */
+    readonly base: string;
+    /** The child's language tag (`pt-BR`). A language the project has no model for is refused BY NAME. */
+    readonly language: string;
+    /**
+     * The `fetch` of the realm this runs in, lent by whoever opens the reading (ADR-0232 D4): the root's window where there is
+     * no worker, the worker's own scope inside `platform/reading-worker`. REQUIRED — this module reaches no global.
+     */
+    readonly fetch: (url: string) => Promise<Response>;
+    /** Injected so a case can replay a real model's numbers without its 378 MiB; the default is the delivery's runtime. */
+    readonly ort?: OnnxRuntime;
+    readonly importModule?: (url: string) => Promise<unknown>;
+    /** A ceiling on the answer, so a model that loops does not hold the microphone for ever. */
+    readonly maxTokens?: number;
+}
+export declare function loadReadingRuntime(d: ReadingRuntimeDeps): Promise<ReadingTranscriber>;

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

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/reading-runtime — THE READING, RUN (ADR-0216 §2; issues #185, #200): sound in, the child's words out.
+//
+// The model of the child's language is opened from the delivery (`heavy/` on the page's own origin, ADR-0177) and run here:
+// the encoder once, then the decoder token by token until it says it is done. What each graph is called, what it takes and what
+// comes back is not guessed — `scratchpad/leitura-de-referencia-3.py` ran the real files and its trace is what
+// `tests/reading-runtime.node.test.js` replays.
+//
+// THREE FAMILIES, and they differ in ways that matter:
+// · Whisper (pt) eats a log-mel spectrogram and opens with four tokens — «transcribe, in Portuguese, without timestamps» — and
+//   refuses 88 tokens that are not speech. Without that opening it answers in whatever language it feels like.
+// · Moonshine (es) eats the waveform and opens with one token, in two decoder graphs like Whisper's.
+// · Moonshine (en) is the same model with ONE MERGED decoder graph, told which pass it is on by `use_cache_branch` and fed empty
+//   caches on the first. It is the shape most easily written wrong from a guess, which is why it is traced too.
+//
+// ⚠️ THE CROSS-ATTENTION CACHE IS COMPUTED ONCE AND NEVER AGAIN. The first pass answers a `present.*.encoder.*` per layer that
+// depends only on the sound; feeding back the new one each step is how a loop gets slower with every token AND drifts.
+import { atDelivery, loadOnnxRuntime } from './onnx-runtime.js';
+import { logMel, nextToken, readingModelFor, readingTextOf, suppressedTokens, tokenIdOf, WHISPER_BANDS, WHISPER_FRAMES, } from './reading-model.js';
+const MAX_TOKENS = 200;
+export async function loadReadingRuntime(d) {
+    const plan = readingModelFor(d.language);
+    if (!plan)
+        throw new Error(`reading: the project has no model for ${d.language}`);
+    const get = d.fetch;
+    const ort = d.ort ?? await loadOnnxRuntime({ base: d.base, importModule: d.importModule });
+    const asJson = async (id) => {
+        const r = await get(atDelivery(id, d.base));
+        if (!r.ok)
+            throw new Error(`reading: HTTP ${r.status} for ${id} — the delivery does not carry this language's model`);
+        return await r.json();
+    };
+    const asSession = async (id) => {
+        const r = await get(atDelivery(id, d.base));
+        if (!r.ok)
+            throw new Error(`reading: HTTP ${r.status} for ${id} — the delivery does not carry this language's model`);
+        return ort.InferenceSession.create(new Uint8Array(await r.arrayBuffer()), { executionProviders: ['wasm'] });
+    };
+    const [tokenizer, generation, config] = await Promise.all([
+        asJson(plan.tokenizer),
+        asJson(plan.generation),
+        asJson(plan.config),
+    ]);
+    const melFilters = plan.input === 'log-mel' && plan.preprocessor
+        ? (await asJson(plan.preprocessor)).mel_filters
+        : null;
+    const [encoder, decoder, decoderPast] = await Promise.all([
+        asSession(plan.encoder),
+        asSession(plan.decoder),
+        plan.decoderPast ? asSession(plan.decoderPast) : Promise.resolve(null),
+    ]);
+    const start = openingOf(plan, tokenizer, generation);
+    const eos = generation.eos_token_id ?? -1;
+    const { heads, width } = cacheSizeOf(config);
+    const ceiling = d.maxTokens ?? MAX_TOKENS;
+    return {
+        async transcribe(samples) {
+            const encoded = await encoder.run(soundFor(ort, plan, samples, melFilters));
+            const hidden = encoded[encoder.outputNames[0]];
+            const shape = {
+                ort, start, hidden, heads, width,
+                frames: hidden.dims?.[1] ?? 0,
+                // the merged graph wants the caches present and EMPTY on the first pass, and the flag that says which pass this is
+                merged: !decoderPast,
+            };
+            const past = {};
+            const ids = [];
+            for (let step = 0; step < ceiling; step++) {
+                const first = step === 0;
+                const session = first || shape.merged ? decoder : decoderPast;
+                const answered = await session.run(stepInputs(shape, session, first, ids, past));
+                keepPast(past, session, answered, first);
+                const chosen = nextToken(lastLogits(answered[session.outputNames[0]]), suppressedTokens(generation, first));
+                // no token at all (a row of NaN) is an end, like the end-of-text: pushing it would ask for a word the vocabulary lacks
+                if (chosen < 0 || chosen === eos)
+                    break;
+                ids.push(chosen);
+            }
+            return readingTextOf(tokenizer, ids).trim();
+        },
+    };
+}
+/**
+ * WHAT THE ENCODER HEARS. Whisper a log-mel picture of 30 s drawn with the model's own filters (80 bands × 3000 frames), Moonshine
+ * the wave itself, every sample. The names are the graphs' own: a real session refuses any other.
+ */
+function soundFor(ort, plan, samples, melFilters) {
+    return plan.input === 'log-mel'
+        ? { input_features: new ort.Tensor('float32', logMel(samples, melFilters ?? []), [1, WHISPER_BANDS, WHISPER_FRAMES]) }
+        : { input_values: new ort.Tensor('float32', samples, [1, samples.length]) };
+}
+/** What one decoder step is handed: the opening on the first, then only the newest token, and the caches so far. */
+function stepInputs(shape, session, first, ids, past) {
+    const { ort } = shape;
+    const inputIds = first ? shape.start : [ids[ids.length - 1]];
+    const inputs = {
+        input_ids: new ort.Tensor('int64', BigInt64Array.from(inputIds, BigInt), [1, inputIds.length]),
+        encoder_hidden_states: shape.hidden,
+        ...(first && shape.merged ? emptyCaches(ort, session, shape.heads, shape.width, shape.frames) : past),
+    };
+    if (shape.merged)
+        inputs.use_cache_branch = new ort.Tensor('bool', Uint8Array.of(first ? 0 : 1), [1]);
+    return inputs;
+}
+/**
+ * The caches carried to the next step: each `present.*` the decoder answered, renamed to the `past_key_values.*` it takes. The
+ * `logits` beside them are the answer, never a cache.
+ * ⚠️ ONLY the self-attention half grows. The cross-attention half is the sound, and the sound does not change.
+ */
+function keepPast(past, session, answered, first) {
+    for (const name of session.outputNames) {
+        if (!name.startsWith('present.'))
+            continue;
+        if (first || name.includes('.decoder.'))
+            past[name.replace('present.', 'past_key_values.')] = answered[name];
+    }
+}
+/**
+ * HOW THE DECODER IS TOLD WHAT TO DO. Moonshine opens with one token and reads what it hears. Whisper opens with four, and they
+ * are an instruction: transcribe (not translate), in THIS language, without timestamps. 📏 Measured: without them it answers in
+ * whatever language it decides, and with `<|translate|>` it answers in English — a child reading Portuguese would be corrected
+ * against an English transcript.
+ */
+function openingOf(plan, tokenizer, generation) {
+    const first = generation.decoder_start_token_id ?? 0;
+    if (plan.input !== 'log-mel')
+        return [first];
+    const named = [`<|${plan.language}|>`, '<|transcribe|>', '<|notimestamps|>'].map((c) => tokenIdOf(tokenizer, c));
+    if (named.some((id) => id === null))
+        throw new Error(`reading: this model has no token for ${plan.language} transcription`);
+    return [first, ...named];
+}
+/**
+ * How big one cache is, from `config.json`: the KEY-VALUE heads (a model with grouped attention keeps fewer than it attends with),
+ * and a width of `hidden_size / heads`, 64 where the config does not say.
+ */
+function cacheSizeOf(config) {
+    return {
+        heads: config.num_key_value_heads ?? config.num_attention_heads ?? 0,
+        width: config.hidden_size && config.num_attention_heads ? config.hidden_size / config.num_attention_heads : 64,
+    };
+}
+/** The caches a merged decoder wants on its first pass: the self-attention halves empty, the cross-attention ones the sound's. */
+function emptyCaches(ort, session, heads, width, frames) {
+    const out = {};
+    for (const name of session.inputNames ?? []) {
+        if (!name.startsWith('past_key_values.'))
+            continue;
+        const length = name.includes('.decoder.') ? 0 : frames;
+        out[name] = new ort.Tensor('float32', new Float32Array(heads * length * width), [1, heads, length, width]);
+    }
+    return out;
+}
+/** The logits of the LAST position: the decoder answers one row per token it was given, and only the newest one is a choice. */
+function lastLogits(tensor) {
+    const t = tensor;
+    const vocab = t.dims?.[2] ?? t.data.length;
+    return t.data.subarray(t.data.length - vocab);
+}

package/dist-pkg/platform/reading-worker.d.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { loadReadingRuntime } from './reading-runtime.js';
+/** What the client asks for. */
+export type ReadingRequest = {
+    readonly kind: 'load';
+    readonly base: string;
+    readonly language: string;
+} | {
+    readonly kind: 'transcribe';
+    readonly id: number;
+    readonly samples: Float32Array;
+};
+/** What the worker answers. `id` is absent only on the answer to `load`, which nobody can ask twice. */
+export type ReadingAnswer = {
+    readonly kind: 'ready';
+} | {
+    readonly kind: 'text';
+    readonly id: number;
+    readonly text: string;
+} | {
+    readonly kind: 'failed';
+    readonly id?: number;
+    readonly message: string;
+};
+/** The side of the conversation this file needs, so a gate can run the whole protocol without a thread. */
+export interface WorkerScope {
+    onmessage: ((event: {
+        data: ReadingRequest;
+    }) => void) | null;
+    postMessage(answer: ReadingAnswer): void;
+    /**
+     * The worker realm's own `fetch`, which the model's files are fetched with (ADR-0232 D4): the runtime receives it from the
+     * scope, so the worker's entry reaches no bare global either.
+     */
+    fetch(url: string): Promise<Response>;
+}
+/**
+ * Wires the protocol onto a scope. Exported — and not only run at import — so the gate exercises the REAL handler instead of a
+ * copy of it written in the test, which is the difference between measuring the protocol and measuring a description of it.
+ */
+export declare function serveReading(scope: WorkerScope, load?: typeof loadReadingRuntime): void;

package/dist-pkg/platform/reading-worker.js

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// platform/reading-worker — THE TRANSCRIPTION, OFF THE MAIN THREAD (ADR-0216 §2; issue #185).
+//
+// 🔴 WHY A THREAD OF ITS OWN, and it is measured and not hygiene: `platform/reading-runtime` runs an encoder and then a decoder
+// token by token, each one a wasm call of tens of milliseconds. On the main thread that is the thread that also draws the game
+// and feeds the microphone — 📏 measured in the lab, Whisper transcribing on the main thread CUT THE AUDIO IN GAPS OF 4 s; the
+// same work in a worker left a biggest gap of 264 ms. A child who reads aloud while the page transcribes loses the words she
+// said during the pause, and nothing anywhere says so.
+//
+// The protocol is three messages and no state the caller cannot see:
+//   · `{ kind: 'load', base, language }`      → `{ kind: 'ready' }` or `{ kind: 'failed', message }`
+//   · `{ kind: 'transcribe', id, samples }`   → `{ kind: 'text', id, text }` or `{ kind: 'failed', id, message }`
+// Every answer carries the `id` of the question, because a second reading may be asked for while the first is still running and
+// an answer that cannot be matched to its question is an answer given to the wrong child.
+//
+// ⚠️ THE MODEL IS OPENED HERE, INSIDE THE WORKER, and that is the whole point: `loadReadingRuntime` fetches the graphs from the
+// delivery and the ONNX runtime compiles them. Doing that on the main thread freezes the game for as long as it takes to open
+// 378 MiB of model, which is the other half of the defect this file exists to remove.
+import { loadReadingRuntime } from './reading-runtime.js';
+const reason = (e) => (e instanceof Error ? e.message : String(e));
+/**
+ * Wires the protocol onto a scope. Exported — and not only run at import — so the gate exercises the REAL handler instead of a
+ * copy of it written in the test, which is the difference between measuring the protocol and measuring a description of it.
+ */
+export function serveReading(scope, load = loadReadingRuntime) {
+    let transcriber = null;
+    scope.onmessage = (event) => {
+        const msg = event.data;
+        if (msg.kind === 'load') {
+            void (async () => {
+                try {
+                    // a METHOD call on the scope: `fetch` detached from its realm throws «Illegal invocation»
+                    transcriber = await load({ base: msg.base, language: msg.language, fetch: (url) => scope.fetch(url) });
+                    scope.postMessage({ kind: 'ready' });
+                }
+                catch (e) {
+                    scope.postMessage({ kind: 'failed', message: reason(e) });
+                }
+            })();
+            return;
+        }
+        // ⚠️ A REQUEST BEFORE THE MODEL IS OPEN IS ANSWERED, not dropped: a dropped message leaves the caller's promise pending for
+        // ever, and a child waiting for words that will never come has no way to know she should try again.
+        void (async () => {
+            try {
+                if (!transcriber)
+                    throw new Error('reading worker: asked to transcribe before the model was opened');
+                scope.postMessage({ kind: 'text', id: msg.id, text: await transcriber.transcribe(msg.samples) });
+            }
+            catch (e) {
+                scope.postMessage({ kind: 'failed', id: msg.id, message: reason(e) });
+            }
+        })();
+    };
+}
+if (typeof WorkerGlobalScope !== 'undefined' && typeof self !== 'undefined' && self instanceof WorkerGlobalScope) {
+    serveReading(self);
+}