@intellectif/lk-core 0.13.1 → 0.14.1

package/dist/scoring.d.ts

@@ -1,5 +1,5 @@
-import { w as ItemOutcome, f as DictationData, A as ActivityData, L as LearnerResponse, e as ActivityType, K as ScoringResult } from './activity-DfAmJ1sl.js';
-export { T as TextMatchPolicy, O as TextMatchResult, a5 as levenshteinDistance, a6 as matchText } from './activity-DfAmJ1sl.js';
+import { x as ItemOutcome, r as Grader, g as DictationData, A as ActivityData, R as ReadAloudData, _ as ValidationResult, P as ReadAloudLearnerResponse, q as GradeRecord, L as LearnerResponse, e as ActivityType, W as ScoringResult } from './activity-BVkg9VDo.js';
+export { T as RecordingRef, X as TextMatchPolicy, Y as TextMatchResult, ad as levenshteinDistance, ae as matchText } from './activity-BVkg9VDo.js';
 
 /**
  * Rounding for assessment scores.
@@ -188,6 +188,246 @@ interface AssessmentScore {
  */
 declare function composeAssessmentScore(sections: readonly AssessmentSectionInput[], policy: CompositionPolicy): AssessmentScore;
 
+/**
+ * Speech assessment: the neutral shape a pronunciation assessor's result is
+ * mapped into, and the types a read-aloud grade reads and writes.
+ *
+ * The SDK calls no assessor and holds no key. The application maps its
+ * provider's response into a {@link SpeechAssessment}; the SDK validates that
+ * evidence, checks that it belongs to the item and to the learner's recording,
+ * and does the arithmetic.
+ */
+
+/**
+ * How the assessor classified a word against the reference text: `none`, read
+ * as written; `mispronunciation`, read but not well enough; `omission`, in the
+ * reference but not heard; `insertion`, heard but not in the reference.
+ */
+type SpeechWordError = 'none' | 'mispronunciation' | 'omission' | 'insertion';
+/** A phoneme the assessor heard instead of the expected one, and its score. */
+interface SpeechPhonemeCandidate {
+    /** The phoneme, in the assessment's `phonemeAlphabet`. */
+    symbol: string;
+    /** 0..100. */
+    score: number;
+}
+/** One phoneme of a word, as the assessor measured it. Assessors report different subsets. */
+interface SpeechPhoneme {
+    /** The phoneme, in the assessment's `phonemeAlphabet`. Absent when the assessor does not name it. */
+    symbol?: string;
+    /** 0..100. Absent means not assessed, never 0. */
+    accuracy?: number;
+    /** Milliseconds from the start of the recording. */
+    startMs?: number;
+    /** Milliseconds. */
+    durationMs?: number;
+    /** The phonemes the assessor heard instead, in the order it reported them. */
+    heardAs?: SpeechPhonemeCandidate[];
+}
+/** One syllable of a word, as the assessor measured it. */
+interface SpeechSyllable {
+    /** The syllable as the assessor reports it. */
+    text: string;
+    /** The letters of the word the syllable is written with, when the assessor reports them. */
+    grapheme?: string;
+    /** 0..100. Absent means not assessed, never 0. */
+    accuracy?: number;
+    /** Milliseconds from the start of the recording. */
+    startMs?: number;
+    /** Milliseconds. */
+    durationMs?: number;
+}
+/** One word of a {@link SpeechAssessment}. */
+interface SpeechWord {
+    /** The word as the assessor reports it. */
+    text: string;
+    /** 0..100. Absent means not assessed — never read as 0. */
+    accuracy?: number;
+    /** The assessor's classification of the word. */
+    error: SpeechWordError;
+    /** The provider's own error label, verbatim, for audit. No grade reads it. */
+    vendorError?: string;
+    /** Milliseconds from the start of the recording. */
+    startMs?: number;
+    /** Milliseconds. */
+    durationMs?: number;
+    syllables?: SpeechSyllable[];
+    phonemes?: SpeechPhoneme[];
+    /**
+     * Confidences (0..1) that an unexpected pause came before the word, or that
+     * an expected one is missing. Display only: no grade reads them.
+     */
+    breaks?: {
+        unexpected?: number;
+        missing?: number;
+    };
+}
+/**
+ * A pronunciation assessor's result, in the SDK's neutral shape. Every score in
+ * it is on a 0..100 scale. Check one with `validateSpeechAssessment`.
+ */
+interface SpeechAssessment {
+    assessmentVersion: '1.0';
+    /** `no_speech`: the assessor heard nothing to assess — which is never a score of 0. */
+    status: 'assessed' | 'no_speech';
+    /** `scripted`: measured against a known text. Only a scripted assessment grades a read-aloud item. */
+    task: 'scripted' | 'unscripted';
+    /** The locale the assessment was made for: canonical, with a region — the rule `ReadAloudData.locale` follows. */
+    locale: string;
+    /**
+     * The text the assessment was made against: the authored reference text,
+     * verbatim. Required when scripted, so a grade can refuse evidence made
+     * against another text.
+     */
+    referenceText?: string;
+    /**
+     * The `RecordingRef.key` of the recording that was assessed. Required when
+     * scripted, so a grade can refuse evidence made for another recording.
+     */
+    recordingKey?: string;
+    /** Who measured. Evidence from `'ai'` grades only when the caller opts in. */
+    assessor: Grader;
+    /** What every score is out of. Stated, so an adapter never leaves it to be assumed. */
+    scale: 100;
+    /** Utterance-level scores, 0..100. An absent score was not assessed; it is never read as 0. */
+    scores: {
+        accuracy?: number;
+        fluency?: number;
+        completeness?: number;
+        prosody?: number;
+        overall?: number;
+    };
+    /** What the assessor recognised, as text. */
+    recognizedText?: string;
+    /**
+     * Who judged omissions, insertions and mispronunciations. `assessor`: the
+     * assessor did, and its word `error` labels are trusted. `none`: it did not,
+     * so a heard word that differs from its reference word is marked
+     * mispronounced.
+     */
+    miscue: 'assessor' | 'none';
+    /** The alphabet phoneme symbols are written in. Required whenever a phoneme names a `symbol` or `heardAs`. */
+    phonemeAlphabet?: 'ipa' | 'sapi';
+    /** The words, in the order the assessor reported them. */
+    words: SpeechWord[];
+    /** Utterance-level prosody: `monotoneConfidence` is 0..1, display only. */
+    prosody?: {
+        monotoneConfidence?: number;
+    };
+    /** Recording quality. Informational only: no grade reads it. */
+    signal?: {
+        snrDb?: number;
+    };
+}
+/**
+ * The server's own measurement of a recording, from `inspectWav`. It is what
+ * decides whether a take is plausible speech; a duration the client reported
+ * never is.
+ */
+interface SpeechMeasurement {
+    /** Length of the recording, in milliseconds. */
+    durationMs: number;
+    /** Milliseconds of the recording at or above the silence floor. At most `durationMs`. */
+    voicedMs: number;
+}
+/**
+ * When a take is too little speech to grade. Both fields are required: the SDK
+ * holds no default for either, because each is a decision about an
+ * application's learners and its assessor.
+ */
+interface SpeechPlausibilityPolicy {
+    /** The most words per second of voiced time a genuine reading can reach. Finite and above 0. */
+    maxWordsPerSecond: number;
+    /** The least voiced time, in milliseconds, a gradable take contains. Finite and at least 0. */
+    minVoicedMs: number;
+}
+/**
+ * Why a read-aloud take cannot be graded:
+ * - `invalid_assessment` — the assessment fails `validateSpeechAssessment`;
+ * - `task_mismatch` — it is not a scripted assessment;
+ * - `locale_mismatch` — it was made for another locale than the item's;
+ * - `reference_mismatch` — it was made against another text than the item's;
+ * - `recording_mismatch` — it was made for another recording than the response's;
+ * - `assessor_not_accepted` — its assessor is `'ai'`, and the caller did not opt in;
+ * - `no_speech` — the assessor heard no speech;
+ * - `insufficient_voiced_time` — the recording holds less voiced time than the policy requires;
+ * - `implausible_speech_rate` — more words were recognised than the voiced time can hold;
+ * - `missing_dimension` — a weighted dimension has no score in the assessment.
+ */
+type SpeechUnscorableCode = 'invalid_assessment' | 'task_mismatch' | 'locale_mismatch' | 'reference_mismatch' | 'recording_mismatch' | 'assessor_not_accepted' | 'no_speech' | 'insufficient_voiced_time' | 'implausible_speech_rate' | 'missing_dimension';
+/** A read-aloud take that cannot be graded. Never a zero: see `outcomeFromUnscorable`. */
+interface SpeechUnscorable {
+    unscorable: true;
+    /** Machine-readable. See {@link SpeechUnscorableCode}. */
+    code: SpeechUnscorableCode;
+    /** A developer-facing English sentence. */
+    reason: string;
+}
+/**
+ * Options for `gradeReadAloud`. The plausibility policy is required: the SDK
+ * holds no default for a threshold that decides whether a take is graded.
+ */
+interface GradeReadAloudOptions {
+    /** The server's measurement of the recording (inspectWav). `null` only for a blank response. */
+    measured: SpeechMeasurement | null;
+    /** When a take is too little speech to grade. */
+    plausibility: SpeechPlausibilityPolicy;
+    /** Accept `assessor.kind: 'ai'` evidence. Off unless set. */
+    allowAiAssessor?: boolean;
+    /** Compare the pass line with both sides rounded, as `gradeFromRubric` does. The score stays unrounded. */
+    rounding?: RoundingPolicy;
+}
+/** How a word of a read-aloud attempt is marked. */
+type ReadAloudWordState = 'correct' | 'mispronounced' | 'omitted' | 'inserted';
+/**
+ * One entry of `alignReadAloud`: a reference word and what was heard for it,
+ * or a heard word that is not in the reference.
+ */
+interface ReadAloudWordAlignment {
+    /** `w<n>` for a reference word, as `dictationReferenceWords` numbers them; absent for an `inserted` word. */
+    itemId?: string;
+    /** The normalised reference word; `''` for an `inserted` word. */
+    reference: string;
+    /**
+     * The normalised heard word: `''` for an `omitted` word, and also for an
+     * `inserted` word whose text normalises to nothing — an assessor can tag a
+     * dash as an insertion, and every insertion gets an entry. Branch on `state`,
+     * never on the empty string.
+     */
+    heard: string;
+    state: ReadAloudWordState;
+    /** The assessor word's accuracy (0..100), when it has one. */
+    accuracy?: number;
+    /** Index into `assessment.words` of the word this entry came from. */
+    wordIndex?: number;
+}
+/**
+ * What `inspectWav` found in a recording's bytes: the duration, format, peak
+ * level and voiced time of a 16-bit PCM WAV, or why it could not read one.
+ */
+type WavInspection = {
+    valid: true;
+    /** Length of the audio, in milliseconds. */
+    durationMs: number;
+    sampleRate: number;
+    channels: number;
+    bitsPerSample: 16;
+    /** The loudest sample across every channel, in dBFS; `-Infinity` for digital silence or no samples. */
+    peakDbfs: number;
+    /** Milliseconds of the windows at or above the policy's silence floor. */
+    voicedMs: number;
+} | {
+    valid: false;
+    reason: 'not_wav' | 'unsupported_encoding' | 'truncated';
+};
+/** How `inspectWav` decides which parts of a recording are voiced. Both fields are required. */
+interface WavInspectionPolicy {
+    /** A window whose RMS level is at or above this many dBFS is voiced. Finite, and at most 0. */
+    silenceDbfs: number;
+    /** The window length, in milliseconds. Finite, and above 0. */
+    frameMs: number;
+}
+
 /** One transcript word, or one extra word the learner typed, after alignment. */
 interface DictationWordAlignment {
     /** `w<n>`, the 1-based position of a transcript word; absent for an extra word. */
@@ -314,8 +554,236 @@ declare const DICTATION_MAX_EQUIVALENCES = 100;
  */
 declare const DICTATION_MAX_ACCEPTED_TRANSCRIPTS = 10;
 
+/**
+ * The pass line, and the authored feedback it selects.
+ *
+ * A module of its own so grade-producing code outside the scoring barrel can
+ * import it without importing the barrel: `gradeReadAloud`, under
+ * `scoring/speech/`, calls `gradeFromRubric`, so if `grading.ts` imported the
+ * barrel the barrel would import itself through them. `scoring/index.ts`
+ * re-exports the pass line and its default by name; the feedback selector
+ * beside them stays internal.
+ */
+
 /** Default minimum scaled score required to pass when `passThreshold` is absent. */
 declare const DEFAULT_PASS_THRESHOLD = 0.7;
+/**
+ * Returns `true` iff `score` meets or exceeds the activity's `passThreshold`,
+ * defaulting to {@link DEFAULT_PASS_THRESHOLD} (0.7) when the field is absent.
+ *
+ * Pass a {@link RoundingPolicy} to compare the way an assessment total is
+ * compared — both sides rounded, via {@link gte} — so an item shown as "70%"
+ * cannot be recorded as a fail at 69.6. It is **opt-in** rather than the
+ * default because switching it on changes item-level pass/fail for scores in
+ * the rounding band, and this SDK does not alter historical grades without an
+ * explicit decision. Absent, the comparison is the exact raw `>=` it has
+ * always been.
+ */
+declare function computePassThreshold(activityData: ActivityData, score: number, rounding?: RoundingPolicy): boolean;
+
+/**
+ * Marking a read-aloud take word by word: the item's own reference words,
+ * paired with the words an assessor heard.
+ *
+ * The assessor's word list is never taken as the item's. Providers disagree
+ * about what a word is, and a provider can be changed; `w<n>` is the position
+ * of a REFERENCE word, exactly as `dictationReferenceWords` numbers it, so a
+ * mark stored today still names the same word tomorrow. The pairing is the
+ * dictation aligner's, run over the dictation normaliser's tokens, so a
+ * read-aloud mark and a dictation mark are made the same way.
+ */
+
+/**
+ * Pairs the words of `assessment` with the words of `data.referenceText`, in
+ * reading order: what was read as written, what was mispronounced, what was
+ * left out, and what was said that the text does not contain.
+ *
+ * Reference words are the dictation tokeniser's, so `itemId` is the `w<n>`
+ * `dictationReferenceWords` gives, and both `reference` and `heard` are
+ * normalised — lowercased, with punctuation and spacing folded away. One
+ * assessor word can normalise to no token at all (a dash), or to several (a
+ * compatibility form), and two can merge into one (`rock&roll`); tokens are
+ * what is aligned, and each remembers the word it came from.
+ *
+ * A word the assessor tagged `insertion` is never aligned — the reference has
+ * nothing for it — so it is placed by the position of its own word, after the
+ * last token that came from an earlier word.
+ *
+ * Whether a paired word counts as read correctly follows `assessment.miscue`:
+ * an assessor that judges miscues is trusted, and one that does not
+ * (`miscue: 'none'`) has its recognised word compared with the reference word.
+ *
+ * `heard` is `''` for an omitted word, and also for an inserted word whose text
+ * normalises to nothing. Branch on `state`, never on the empty string.
+ *
+ * The heard tokens are bounded: they are taken in reading order until what the
+ * assessment's words spell would pass `DICTATION_MAX_TEXT_LENGTH` code points —
+ * the cap the dictation aligner reads a learner's text under — and always on a
+ * whole token, because half a token pairs with the wrong word. Every word is
+ * charged, an inserted one included, so that total is the whole of the text
+ * this function can answer with. Words past the budget contribute no token, so
+ * each reference word left with nothing read for it is `omitted`.
+ * `validateSpeechAssessment` refuses an assessment whose words spell more than
+ * that, measured by the same walk and against the same number, so a validated
+ * assessment never reaches the budget: it is a backstop, kept because this
+ * function is public and can be handed evidence this build did not check.
+ *
+ * **`data` is not validated.** Only the assessment is. A `referenceText` longer
+ * than `READ_ALOUD_MAX_REFERENCE_LENGTH` code points is cut by the tokeniser
+ * with no signal, and one that is absent or is not a string yields no reference
+ * word at all, so every heard token comes back `inserted` rather than refused.
+ * Validate the item with `validateActivity('read-aloud', data)` first.
+ * `gradeReadAloud` is safe without that because it runs the schema itself.
+ *
+ * Pure and deterministic: no locale, no `Intl`, no clock.
+ *
+ * @throws TypeError when `assessment` is not a well-formed
+ * {@link SpeechAssessment}; check it with `validateSpeechAssessment` first.
+ */
+declare function alignReadAloud(data: Pick<ReadAloudData, 'referenceText'>, assessment: SpeechAssessment): ReadAloudWordAlignment[];
+
+/**
+ * Checks that `value` is a well-formed {@link SpeechAssessment}. It answers
+ * rather than throwing: anything that is not one — a non-object, an unknown key
+ * at any depth, a score off the 0..100 scale, a time that is negative or not
+ * finite — comes back as `{ success: false, errors }`, one error per problem,
+ * each with the path, message and code `validateActivity` gives a schema
+ * failure. An object that throws when it is read is the one exception, and the
+ * throw is its own: an own property getter, or a `Proxy` trap.
+ *
+ * Three rules span fields:
+ * - `scripted_binding_required` — a `scripted` assessment without
+ *   `referenceText`, or without `recordingKey`, reported at each missing path;
+ * - `phoneme_alphabet_required` — a phoneme names a `symbol` or `heardAs` while
+ *   `phonemeAlphabet` is absent, reported once, at `phonemeAlphabet`;
+ * - `too_big` at `words` — the words carry more text between them, written or
+ *   normalised, than can be aligned against an item's text. Per-word caps bound
+ *   no total, and the aligner pairs tokens, of which one word holds as many as
+ *   its text spells. Every word counts towards both totals, an insertion
+ *   included: the aligner carries one into its answer, so its text is text the
+ *   call must hold.
+ *
+ * The total is measured on the words every field rule accepted, so it says
+ * nothing about an assessment that is going back to its adapter anyway.
+ *
+ * It checks the evidence alone. Whether an assessment belongs to an item and
+ * to a learner's recording is decided when it is graded.
+ */
+declare function validateSpeechAssessment(value: unknown): ValidationResult<SpeechAssessment>;
+
+/**
+ * Grades a read-aloud take from a {@link SpeechAssessment} the application
+ * obtained, the response that was submitted, and the server's own measurement
+ * of the recording.
+ *
+ * The weighted total is computed by `gradeFromRubric` from the authored
+ * dimensions that carry a weight above 0, each out of 100. The per-word marks
+ * in `details` are for display and review: **they never feed the score**, which
+ * is the assessor's utterance-level judgement, weighted as the item authored it.
+ *
+ * Evidence is refused, never scored 0, when it cannot be tied to this item and
+ * this recording, when the assessor heard nothing, when the recording holds too
+ * little voiced time for the words claimed, or when a weighted dimension has no
+ * score — see {@link SpeechUnscorableCode}. Store a refusal with
+ * `outcomeFromUnscorable`.
+ *
+ * A blank (`response.recording === null`) is a grade of 0 with a mark per
+ * reference word: the learner submitted, and read nothing. The assessment and
+ * the measurement are not read for it.
+ *
+ * @throws RangeError when `options.plausibility` or `options.rounding` cannot be
+ * applied, or when `options.measured` is not a pair of non-negative, finite
+ * millisecond counts with `voicedMs` inside `durationMs`.
+ * @throws TypeError when `response` is not a read-aloud response, or when a
+ * non-blank response is graded without an assessment or without a measurement.
+ * @throws ActivitySchemaError when `data` is not valid read-aloud data.
+ * @throws RedactedScoringError when `data` is a `redact()` projection. A
+ * read-aloud projection is a valid activity, so the authored feedback would
+ * simply be missing from the grade; grade against the full data server-side.
+ */
+declare function gradeReadAloud(data: ReadAloudData, response: ReadAloudLearnerResponse, assessment: SpeechAssessment | null, options: GradeReadAloudOptions): GradeRecord | SpeechUnscorable;
+
+/**
+ * The longest reference text a read-aloud item accepts, in code points, before
+ * and after normalisation. It is the dictation transcript cap on purpose: the
+ * reference is tokenised as a dictation transcript is, and the dictation
+ * normaliser cuts a transcript at that many code points without saying so, so
+ * a longer text would be graded against words it had silently lost.
+ */
+declare const READ_ALOUD_MAX_REFERENCE_LENGTH = 2000;
+/** The longest take a read-aloud item may allow, in seconds: the most `recording.maxSeconds` may be. */
+declare const READ_ALOUD_MAX_SECONDS = 300;
+/** The most takes a read-aloud item may allow: the most `recording.maxTakes` may be. */
+declare const READ_ALOUD_MAX_TAKES = 20;
+/**
+ * The largest weight a read-aloud dimension may carry. Weights are relative, so
+ * no rubric needs more, and the cap keeps a mistyped weight from overflowing
+ * the weighted total into a grade that cannot be computed.
+ */
+declare const READ_ALOUD_MAX_DIMENSION_WEIGHT = 1000;
+/**
+ * The most words a speech assessment may carry. It bounds one side of the
+ * alignment, and one side alone bounds nothing: the aligner pairs TOKENS, and
+ * one word normalises to as many as its text holds. What bounds the quadratic
+ * work is this cap, the 200-unit cap on a single word's text, and the two rules
+ * `validateSpeechAssessment` states over the total of them — what the words are
+ * written with, and what they spell once normalised.
+ */
+declare const SPEECH_ASSESSMENT_MAX_WORDS = 1000;
+
+/**
+ * Measuring a recording from its bytes: how long it is, how loud it gets, and
+ * how much of it is voiced.
+ *
+ * This is the server's own evidence about a take. A duration a browser reported
+ * is a claim, and a claim decides nothing: whether a recording holds enough
+ * speech to grade is answered from the samples. Only 16-bit PCM WAV is read —
+ * the one encoding an application can produce without a decoder — and anything
+ * else is reported as unread rather than guessed at.
+ *
+ * Isomorphic: a `DataView` over the caller's bytes, no `Buffer`, no `node:`
+ * imports, and no allocation proportional to the audio.
+ */
+
+/**
+ * Reads a 16-bit PCM WAV and measures it: `durationMs`, `sampleRate`,
+ * `channels`, the loudest sample as `peakDbfs`, and `voicedMs`, the time in
+ * windows whose RMS level reaches the policy's silence floor.
+ *
+ * Anything it cannot measure comes back as `{ valid: false, reason }` rather
+ * than a guess: `not_wav` for bytes that are not a RIFF/WAVE file, or whose
+ * chunks do not describe the audio before the audio arrives;
+ * `unsupported_encoding` for a WAV this reader does not read (compressed, or
+ * samples that are not 16-bit); `truncated` when the data chunk is missing or
+ * shorter than it declares.
+ *
+ * Both policy fields are required, because neither has an answer that is right
+ * for every microphone: `silenceDbfs` is where an application draws the line
+ * between silence and speech, and `frameMs` is how finely it looks.
+ *
+ * Pure and deterministic. It never throws on the bytes themselves — only on
+ * arguments it cannot use.
+ *
+ * @throws TypeError when `bytes` is not a `Uint8Array`.
+ * @throws RangeError when `silenceDbfs` is not a finite number at or below 0,
+ * or `frameMs` is not a finite number above 0.
+ */
+declare function inspectWav(bytes: Uint8Array, policy: WavInspectionPolicy): WavInspection;
+
+/**
+ * Lifts a result that cannot be graded — a `SpeechUnscorable` from
+ * `gradeReadAloud`, or anything else carrying a `code` and a `reason` — into
+ * the `unscorable` arm of {@link ItemOutcome}, keeping its code.
+ *
+ * The code is what an application branches on; the reason is a developer-facing
+ * sentence. Stored this way, the result composes exactly as the unscorable
+ * outcomes `evaluate` returns do. `evaluate` never writes a code itself.
+ */
+declare function outcomeFromUnscorable(result: {
+    code: string;
+    reason: string;
+}): ItemOutcome;
+
 /**
  * Options for {@link score} and {@link evaluate}. Additive: with none, both
  * behave exactly as they always have.
@@ -335,19 +803,6 @@ interface ScoringOptions {
      */
     rounding?: RoundingPolicy;
 }
-/**
- * Returns `true` iff `score` meets or exceeds the activity's `passThreshold`,
- * defaulting to {@link DEFAULT_PASS_THRESHOLD} (0.7) when the field is absent.
- *
- * Pass a {@link RoundingPolicy} to compare the way an assessment total is
- * compared — both sides rounded, via {@link gte} — so an item shown as "70%"
- * cannot be recorded as a fail at 69.6. It is **opt-in** rather than the
- * default because switching it on changes item-level pass/fail for scores in
- * the rounding band, and this SDK does not alter historical grades without an
- * explicit decision. Absent, the comparison is the exact raw `>=` it has
- * always been.
- */
-declare function computePassThreshold(activityData: ActivityData, score: number, rounding?: RoundingPolicy): boolean;
 /**
  * Scores a learner response against activity data and returns a full
  * {@link ScoringResult}.
@@ -381,4 +836,4 @@ declare function score(activityType: ActivityType, activityData: ActivityData, l
  */
 declare function evaluate(data: ActivityData, response: LearnerResponse, options?: ScoringOptions): ItemOutcome;
 
-export { type AssessmentScore, type AssessmentSectionInput, type Band, type CompositionPolicy, DEFAULT_PASS_THRESHOLD, DICTATION_MAX_ACCEPTED_TRANSCRIPTS, DICTATION_MAX_EQUIVALENCES, DICTATION_MAX_EQUIVALENCE_LENGTH, DICTATION_MAX_TEXT_LENGTH, DICTATION_MAX_TRANSCRIPT_LENGTH, type DictationAlignment, type DictationCharOp, type DictationReference, type DictationWordAlignment, type PassFailureReason, type RoundingMode, type RoundingPolicy, type ScoredItem, type ScoringOptions, type SectionScore, alignDictation, classifyBand, composeAssessmentScore, computePassThreshold, dictationReferenceWords, diffDictationChars, evaluate, gte, roundGrade, score };
+export { type AssessmentScore, type AssessmentSectionInput, type Band, type CompositionPolicy, DEFAULT_PASS_THRESHOLD, DICTATION_MAX_ACCEPTED_TRANSCRIPTS, DICTATION_MAX_EQUIVALENCES, DICTATION_MAX_EQUIVALENCE_LENGTH, DICTATION_MAX_TEXT_LENGTH, DICTATION_MAX_TRANSCRIPT_LENGTH, type DictationAlignment, type DictationCharOp, type DictationReference, type DictationWordAlignment, type GradeReadAloudOptions, GradeRecord, ItemOutcome, type PassFailureReason, READ_ALOUD_MAX_DIMENSION_WEIGHT, READ_ALOUD_MAX_REFERENCE_LENGTH, READ_ALOUD_MAX_SECONDS, READ_ALOUD_MAX_TAKES, ReadAloudData, ReadAloudLearnerResponse, type ReadAloudWordAlignment, type ReadAloudWordState, type RoundingMode, type RoundingPolicy, SPEECH_ASSESSMENT_MAX_WORDS, type ScoredItem, type ScoringOptions, type SectionScore, type SpeechAssessment, type SpeechMeasurement, type SpeechPhoneme, type SpeechPhonemeCandidate, type SpeechPlausibilityPolicy, type SpeechSyllable, type SpeechUnscorable, type SpeechUnscorableCode, type SpeechWord, type SpeechWordError, type WavInspection, type WavInspectionPolicy, alignDictation, alignReadAloud, classifyBand, composeAssessmentScore, computePassThreshold, dictationReferenceWords, diffDictationChars, evaluate, gradeReadAloud, gte, inspectWav, outcomeFromUnscorable, roundGrade, score, validateSpeechAssessment };

package/dist/scoring.js

@@ -1,25 +1,35 @@
 import {
   DEFAULT_PASS_THRESHOLD,
+  alignReadAloud,
   classifyBand,
   composeAssessmentScore,
   computePassThreshold,
   diffDictationChars,
   evaluate,
+  gradeReadAloud,
   gte,
+  inspectWav,
+  outcomeFromUnscorable,
   roundGrade,
-  score
-} from "./chunk-FGN4LLSP.js";
+  score,
+  validateSpeechAssessment
+} from "./chunk-RTIR6R2U.js";
 import {
   DICTATION_MAX_ACCEPTED_TRANSCRIPTS,
   DICTATION_MAX_EQUIVALENCES,
   DICTATION_MAX_EQUIVALENCE_LENGTH,
   DICTATION_MAX_TEXT_LENGTH,
   DICTATION_MAX_TRANSCRIPT_LENGTH,
+  READ_ALOUD_MAX_DIMENSION_WEIGHT,
+  READ_ALOUD_MAX_REFERENCE_LENGTH,
+  READ_ALOUD_MAX_SECONDS,
+  READ_ALOUD_MAX_TAKES,
+  SPEECH_ASSESSMENT_MAX_WORDS,
   alignDictation,
   dictationReferenceWords,
   levenshteinDistance,
   matchText
-} from "./chunk-XKKKWKRH.js";
+} from "./chunk-6RND47QE.js";
 export {
   DEFAULT_PASS_THRESHOLD,
   DICTATION_MAX_ACCEPTED_TRANSCRIPTS,
@@ -27,17 +37,27 @@ export {
   DICTATION_MAX_EQUIVALENCE_LENGTH,
   DICTATION_MAX_TEXT_LENGTH,
   DICTATION_MAX_TRANSCRIPT_LENGTH,
+  READ_ALOUD_MAX_DIMENSION_WEIGHT,
+  READ_ALOUD_MAX_REFERENCE_LENGTH,
+  READ_ALOUD_MAX_SECONDS,
+  READ_ALOUD_MAX_TAKES,
+  SPEECH_ASSESSMENT_MAX_WORDS,
   alignDictation,
+  alignReadAloud,
   classifyBand,
   composeAssessmentScore,
   computePassThreshold,
   dictationReferenceWords,
   diffDictationChars,
   evaluate,
+  gradeReadAloud,
   gte,
+  inspectWav,
   levenshteinDistance,
   matchText,
+  outcomeFromUnscorable,
   roundGrade,
-  score
+  score,
+  validateSpeechAssessment
 };
 //# sourceMappingURL=scoring.js.map

package/dist/xapi.cjs

@@ -4,13 +4,13 @@
 
 
 
-var _chunkFT7SAC3Xcjs = require('./chunk-FT7SAC3X.cjs');
-require('./chunk-XONKWL6D.cjs');
+var _chunkE7LPIZXIcjs = require('./chunk-E7LPIZXI.cjs');
+require('./chunk-VCXIPLEW.cjs');
 
 
 
 
 
 
-exports.XAPIVerb = _chunkFT7SAC3Xcjs.XAPIVerb; exports.XAPI_VERB_DISPLAY = _chunkFT7SAC3Xcjs.XAPI_VERB_DISPLAY; exports.validateXAPIStatement = _chunkFT7SAC3Xcjs.validateXAPIStatement; exports.xAPIBuilder = _chunkFT7SAC3Xcjs.xAPIBuilder; exports.xapiDefinitionFor = _chunkFT7SAC3Xcjs.xapiDefinitionFor;
+exports.XAPIVerb = _chunkE7LPIZXIcjs.XAPIVerb; exports.XAPI_VERB_DISPLAY = _chunkE7LPIZXIcjs.XAPI_VERB_DISPLAY; exports.validateXAPIStatement = _chunkE7LPIZXIcjs.validateXAPIStatement; exports.xAPIBuilder = _chunkE7LPIZXIcjs.xAPIBuilder; exports.xapiDefinitionFor = _chunkE7LPIZXIcjs.xapiDefinitionFor;
 //# sourceMappingURL=xapi.cjs.map

package/dist/xapi.d.cts

@@ -1,4 +1,4 @@
-import { X as XAPIActor, K as ScoringResult, Z as XAPIContext, a1 as XAPIResult, a3 as XAPIStatement } from './activity-DfAmJ1sl.cjs';
+import { a3 as XAPIActor, W as ScoringResult, a5 as XAPIContext, a9 as XAPIResult, ab as XAPIStatement } from './activity-BVkg9VDo.cjs';
 
 /**
  * The set of xAPI verbs emitted by SDK activities, keyed by a stable

package/dist/xapi.d.ts

@@ -1,4 +1,4 @@
-import { X as XAPIActor, K as ScoringResult, Z as XAPIContext, a1 as XAPIResult, a3 as XAPIStatement } from './activity-DfAmJ1sl.js';
+import { a3 as XAPIActor, W as ScoringResult, a5 as XAPIContext, a9 as XAPIResult, ab as XAPIStatement } from './activity-BVkg9VDo.js';
 
 /**
  * The set of xAPI verbs emitted by SDK activities, keyed by a stable

package/dist/xapi.js

@@ -4,8 +4,8 @@ import {
   validateXAPIStatement,
   xAPIBuilder,
   xapiDefinitionFor
-} from "./chunk-PYP3HCRQ.js";
-import "./chunk-XKKKWKRH.js";
+} from "./chunk-KTDOZR7Y.js";
+import "./chunk-6RND47QE.js";
 export {
   XAPIVerb,
   XAPI_VERB_DISPLAY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intellectif/lk-core",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "Framework-free assessment core: Zod activity schemas, pure scoring, rubric & deferred grading, weighted assessment composition, exam attempt plans, and xAPI 1.0.3.",
   "keywords": [
     "assessment",