@intellectif/lk-core 0.13.0 → 0.14.0

package/vectors/README.md

@@ -70,7 +70,31 @@ a known hazard carry a `note` saying why they exist.
   edges, negative zero, half-even ties and near-ties, and bands that share a
   minimum.
 - **`countWords`**, **`seededShuffle`** in both versions, **`gradeFromRubric`**
-  including its unscorable paths, and **`outcomeFromGrade`**.
+  including its unscorable paths, its opt-in `rounding` option on each of the
+  three ways a pass is decided, and **`outcomeFromGrade`**.
+- **`gradeReadAloud`**: every reason a pronunciation assessment is refused
+  rather than scored — each `unscorable` code — the weighted total over the
+  authored dimensions, a blank take, a dimension scored `0` against one that was
+  not scored at all, the pass line with and without rounding, and the per-word
+  marks in `details`, which are for review and never feed the score.
+- **`alignReadAloud`**, which decides the reference word each mark lands on:
+  omissions, insertions and mispronunciations, a repeated word, an assessor word
+  that normalises to no token or to two, punctuation that merges two words into
+  one, and both `miscue` settings. **`validateSpeechAssessment`** with the paths
+  and codes an adapter branches on — including the two totals that bound the
+  text of an assessment, at the bound and one character past it — and
+  **`outcomeFromUnscorable`**, which keeps a refusal's code in the stored
+  outcome.
+- **`validateActivity`**, for the one rule that decides whether an item can be
+  stored at all rather than how an answer scores: a read-aloud `referenceText`
+  that survives normalisation as nothing. An item that marks no word grades a
+  silent take at 0 with no omission recorded and a perfect reading as a run of
+  insertions, so loosening that refusal would move grades.
+- **`inspectWav`** and the **`READ_ALOUD_*`** and `SPEECH_ASSESSMENT_MAX_WORDS`
+  limits: what a recording's duration, peak level and voiced time are measured
+  as, across silence, a tone, two channels, two sample rates, a partial last
+  window, an odd chunk's pad byte and WAVE_FORMAT_EXTENSIBLE, and which files
+  are reported unread instead of guessed at.
 - **`scoredItemsFromPlan`**, which decides what a stored paper's denominator is
   when an outcome is missing, and **`composeAssessmentScore`** across weights,
   points, provisional and unscorable items, and section thresholds.
@@ -101,5 +125,41 @@ tagged: `{ "$number": "NaN" | "Infinity" | "-Infinity" | "-0" }` and
 `\uXXXX` escape, so a no-break space can never pass for an ordinary one.
 Comparison ignores object key order.
 
-`corpusVersion` changes only if this encoding does. Adding vectors does not
-change it, so always load the `replay.mjs` that sits beside the corpus.
+A recording is bytes, which JSON cannot express either, so a `Uint8Array` is
+tagged `{ "$bytes": "<base64>" }` and comes back from `decode` as a fresh one.
+Any other view of an `ArrayBuffer` is refused rather than tagged: JSON would
+store it as `{"0":82,"1":73}`, which replays as an ordinary object, and the call
+under test would be handed something that is not a byte array at all. The base64
+is computed in `replay.mjs` itself, so the file needs no `Buffer` and still runs
+wherever your tests run.
+
+`corpusVersion` changes only if this encoding does — it is **2** since the
+`$bytes` tag was added, and no expectation changed with it. Adding vectors does
+not change it, so always load the `replay.mjs` that sits beside the corpus: an
+older one throws rather than replaying a corpus it cannot read.
+
+## `frozenFrom`
+
+`frozenFrom` is **the version of `@intellectif/lk-core` the corpus was last
+regenerated at** — the package version in `package.json` when someone ran
+`node scripts/generate-vectors.mjs`. That is all it is.
+
+**It is not the version this corpus ships in, and it is not expected to match
+it.** `changeset version` bumps the package without regenerating the corpus, so
+a release almost always publishes a corpus whose `frozenFrom` names the previous
+version. That is correct and wanted: the string records when these expectations
+were last recomputed, and a release that changes no expectation should not
+rewrite them.
+
+It is deliberately not asserted anywhere. `replay()` never reads it — it walks
+`vectors` alone, comparing each frozen call with what your build returns — and
+the generator's own grade-change check compares only each vector's call and
+expectation, so a `frozenFrom` one version behind can never fail a grade gate.
+(`corpusVersion` is different: `replay()` does check that one, and throws when
+it does not recognise the encoding.) Read `frozenFrom` as a date stamp, not as a
+package label. The version that matters for "which build produced this grade" is
+the one you installed; record that yourself beside any grade you store.
+
+Adding a regenerate-after-version step to the release was considered and
+rejected: it would put a step that can fail *after* the version bump, which is
+strictly worse than a string that reads one version behind.

package/vectors/replay.d.mts

@@ -1,7 +1,12 @@
 /** Types for `replay.mjs`. See that file for the contract and the encoding. */
 
-/** The encoding version this replayer reads. */
-export declare const CORPUS_VERSION: 1;
+/**
+ * The encoding version this replayer reads. Version 2 added the `$bytes` tag:
+ * a `Uint8Array` is stored as `{ "$bytes": "<base64>" }` and decoded back into
+ * a fresh one, and any other view of an `ArrayBuffer` is refused rather than
+ * frozen as an object of indices.
+ */
+export declare const CORPUS_VERSION: 2;
 
 /** One frozen call. Exactly one of `fn` / `const` is present. */
 export interface ScoringVector {

package/vectors/replay.mjs

@@ -35,10 +35,83 @@
  * deliberately returns `0`, not `-0`, for a negative value that rounds to
  * zero, and JSON would erase the difference. A call that throws is recorded as
  * `{ "$throws": "<error.name>" }`.
+ *
+ * A recording is bytes, which JSON cannot express either, so a `Uint8Array` is
+ * tagged `{ "$bytes": "<base64>" }` and comes back as a fresh one. Any other
+ * view of an `ArrayBuffer` is refused rather than tagged: JSON would store it
+ * as `{"0":82,"1":73}`, which replays as an ordinary object, and a function
+ * that reads bytes would be handed something that is not a byte array at all —
+ * silently, and with a frozen expectation to match. The base64 is computed
+ * here, in plain JavaScript: `Buffer` is Node's alone, and this file runs
+ * wherever a consumer's tests run.
  */
 
 /** Bump only when the ENCODING changes. Adding vectors does not change it. */
-export const CORPUS_VERSION = 1;
+export const CORPUS_VERSION = 2;
+
+/** The base64 alphabet, RFC 4648 section 4, padded with `=`. */
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** Base64 of `bytes`, three bytes at a time, the last group padded. */
+function toBase64(bytes) {
+  let text = '';
+  for (let at = 0; at < bytes.length; at += 3) {
+    const first = bytes[at];
+    const second = bytes[at + 1];
+    const third = bytes[at + 2];
+    text += BASE64[first >> 2];
+    text += BASE64[((first & 0x03) << 4) | ((second ?? 0) >> 4)];
+    text += second === undefined ? '=' : BASE64[((second & 0x0f) << 2) | ((third ?? 0) >> 6)];
+    text += third === undefined ? '=' : BASE64[third & 0x3f];
+  }
+  return text;
+}
+
+/** The bytes of a base64 string, as a fresh `Uint8Array`. */
+function fromBase64(text) {
+  // Every refusal below is a plain `Error`, which no vector expects: a corpus
+  // whose bytes cannot be read must fail the gate, and a `TypeError` here would
+  // be indistinguishable from the one `inspectWav` throws for bytes that are not
+  // a `Uint8Array` — which seven vectors do expect.
+  if (typeof text !== 'string') {
+    // A tag that carries no string carried no bytes either. Substituting an
+    // empty array would replay green against every vector that expects a
+    // refusal, because an empty recording is refused too, with the bytes the
+    // vector froze gone.
+    throw new Error(
+      `A $bytes tag carries a base64 string, and this one is of type ${typeof text}.`,
+    );
+  }
+  const body = text.replace(/=+$/, '');
+  // Base64 spends four characters on three bytes, so a trailing group of one
+  // character encodes nothing: the string was cut short, and the bytes before
+  // the cut are not the bytes anybody froze.
+  if (body.length % 4 === 1) {
+    throw new Error(
+      `Invalid base64 in a $bytes tag: a body of ${body.length} characters ends in a group of one, which encodes no byte.`,
+    );
+  }
+  const bytes = new Uint8Array((body.length * 3) >> 2);
+  let held = 0;
+  let bits = 0;
+  let at = 0;
+  for (const character of body) {
+    const value = BASE64.indexOf(character);
+    if (value === -1) {
+      // A hand-edited corpus, or a file mangled in transit. Decoding it as far
+      // as it goes would hand the call under test bytes nobody froze.
+      throw new Error(`Invalid base64 in a $bytes tag: ${JSON.stringify(character)}.`);
+    }
+    held = (held << 6) | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes[at] = (held >> bits) & 0xff;
+      at += 1;
+    }
+  }
+  return bytes;
+}
 
 /** Turns a runtime value into the corpus's JSON-safe form. */
 export function encode(value) {
@@ -50,6 +123,14 @@ export function encode(value) {
     return value;
   }
   if (value === undefined) return { $undefined: true };
+  if (ArrayBuffer.isView(value)) {
+    if (value instanceof Uint8Array) return { $bytes: toBase64(value) };
+    // A DataView or a wider typed array has no agreed byte order in JSON, and
+    // the object branch below would freeze a `Float32Array` as its indices.
+    throw new TypeError(
+      'A vector can carry bytes as a Uint8Array only; convert any other view of an ArrayBuffer first.',
+    );
+  }
   if (Array.isArray(value)) return value.map(encode);
   if (value !== null && typeof value === 'object') {
     const out = {};
@@ -77,6 +158,7 @@ export function decode(value) {
       }[value.$number];
     }
     if (keys.length === 1 && keys[0] === '$undefined') return undefined;
+    if (keys.length === 1 && keys[0] === '$bytes') return fromBase64(value.$bytes);
     const out = {};
     for (const [key, entry] of Object.entries(value)) out[key] = decode(entry);
     return out;