@intellectif/lk-core 0.12.0 → 0.13.0

package/dist/schemas.d.cts

@@ -1,3 +1,3 @@
-import './activity-B2QxK15j.cjs';
-export { B as BlankConfigSchema, F as FeedbackSchema, a as FillInTheBlanksDataSchema, G as GapSelectBankSchema, b as GapSelectChoiceSchema, c as GapSelectDataSchema, d as GapSelectGapSchema, e as ItemGroupSchema, M as MediaPlaybackSchema, f as MediaSchema, g as MediaUrlSchema, h as MultipleChoiceDataSchema, i as MultipleChoiceOptionMediaSchema, j as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as RedactedActivity, k as RedactedBlankConfig, l as RedactedBlankConfigSchema, m as RedactedFillInTheBlanksData, n as RedactedFillInTheBlanksDataSchema, o as RedactedGapSelectBank, p as RedactedGapSelectBankSchema, q as RedactedGapSelectChoice, r as RedactedGapSelectChoiceSchema, s as RedactedGapSelectData, t as RedactedGapSelectDataSchema, u as RedactedGapSelectGap, v as RedactedGapSelectGapSchema, w as RedactedItemGroupSchema, x as RedactedMediaSchema, y as RedactedMultipleChoiceData, z as RedactedMultipleChoiceDataSchema, A as RedactedMultipleChoiceOption, C as RedactedMultipleChoiceOptionMedia, D as RedactedMultipleChoiceOptionMediaSchema, E as RedactedMultipleChoiceOptionSchema, H as RedactedStimulus, J as RedactedStimulusSchema, K as RedactedWrittenResponseData, L as RedactedWrittenResponseDataSchema, U as StimulusSchema, V as TextMatchPolicySchema, W as WrittenResponseDataSchema, X as WrittenResponseRubricCriterionSchema, Y as WrittenResponseRubricSchema, Z as fillInTheBlanksJsonSchema, _ as gapSelectJsonSchema, $ as itemGroupJsonSchema, a0 as jsonSchemaFor, a1 as multipleChoiceJsonSchema, a2 as stimulusJsonSchema, a3 as validateActivity, a4 as validateItemGroup, a5 as writtenResponseJsonSchema } from './index-B_scInLM.cjs';
+import './activity-DfAmJ1sl.cjs';
+export { B as BlankConfigSchema, D as DictationDataSchema, a as DictationEquivalenceSchema, b as DictationSlowMediaSchema, c as DictationToleranceSchema, F as FeedbackSchema, d as FillInTheBlanksDataSchema, G as GapSelectBankSchema, e as GapSelectChoiceSchema, f as GapSelectDataSchema, g as GapSelectGapSchema, h as ItemGroupSchema, M as MediaPlaybackSchema, i as MediaSchema, j as MediaUrlSchema, k as MultipleChoiceDataSchema, l as MultipleChoiceOptionMediaSchema, m as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as RedactedActivity, n as RedactedBlankConfig, o as RedactedBlankConfigSchema, p as RedactedDictationData, q as RedactedDictationDataSchema, r as RedactedDictationSlowMedia, s as RedactedDictationSlowMediaSchema, t as RedactedFillInTheBlanksData, u as RedactedFillInTheBlanksDataSchema, v as RedactedGapSelectBank, w as RedactedGapSelectBankSchema, x as RedactedGapSelectChoice, y as RedactedGapSelectChoiceSchema, z as RedactedGapSelectData, A as RedactedGapSelectDataSchema, C as RedactedGapSelectGap, E as RedactedGapSelectGapSchema, H as RedactedItemGroupSchema, J as RedactedMediaSchema, K as RedactedMultipleChoiceData, L as RedactedMultipleChoiceDataSchema, O as RedactedMultipleChoiceOption, P as RedactedMultipleChoiceOptionMedia, Q as RedactedMultipleChoiceOptionMediaSchema, S as RedactedMultipleChoiceOptionSchema, T as RedactedStimulus, U as RedactedStimulusSchema, V as RedactedWrittenResponseData, W as RedactedWrittenResponseDataSchema, a0 as StimulusSchema, a1 as TextMatchPolicySchema, a2 as WrittenResponseDataSchema, a3 as WrittenResponseRubricCriterionSchema, a4 as WrittenResponseRubricSchema, a5 as dictationJsonSchema, a6 as fillInTheBlanksJsonSchema, a7 as gapSelectJsonSchema, a8 as itemGroupJsonSchema, a9 as jsonSchemaFor, aa as multipleChoiceJsonSchema, ab as stimulusJsonSchema, ac as validateActivity, ad as validateItemGroup, ae as writtenResponseJsonSchema } from './index-Bz9wUigA.cjs';
 import 'zod/v4';

package/dist/schemas.d.ts

@@ -1,3 +1,3 @@
-import './activity-B2QxK15j.js';
-export { B as BlankConfigSchema, F as FeedbackSchema, a as FillInTheBlanksDataSchema, G as GapSelectBankSchema, b as GapSelectChoiceSchema, c as GapSelectDataSchema, d as GapSelectGapSchema, e as ItemGroupSchema, M as MediaPlaybackSchema, f as MediaSchema, g as MediaUrlSchema, h as MultipleChoiceDataSchema, i as MultipleChoiceOptionMediaSchema, j as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as RedactedActivity, k as RedactedBlankConfig, l as RedactedBlankConfigSchema, m as RedactedFillInTheBlanksData, n as RedactedFillInTheBlanksDataSchema, o as RedactedGapSelectBank, p as RedactedGapSelectBankSchema, q as RedactedGapSelectChoice, r as RedactedGapSelectChoiceSchema, s as RedactedGapSelectData, t as RedactedGapSelectDataSchema, u as RedactedGapSelectGap, v as RedactedGapSelectGapSchema, w as RedactedItemGroupSchema, x as RedactedMediaSchema, y as RedactedMultipleChoiceData, z as RedactedMultipleChoiceDataSchema, A as RedactedMultipleChoiceOption, C as RedactedMultipleChoiceOptionMedia, D as RedactedMultipleChoiceOptionMediaSchema, E as RedactedMultipleChoiceOptionSchema, H as RedactedStimulus, J as RedactedStimulusSchema, K as RedactedWrittenResponseData, L as RedactedWrittenResponseDataSchema, U as StimulusSchema, V as TextMatchPolicySchema, W as WrittenResponseDataSchema, X as WrittenResponseRubricCriterionSchema, Y as WrittenResponseRubricSchema, Z as fillInTheBlanksJsonSchema, _ as gapSelectJsonSchema, $ as itemGroupJsonSchema, a0 as jsonSchemaFor, a1 as multipleChoiceJsonSchema, a2 as stimulusJsonSchema, a3 as validateActivity, a4 as validateItemGroup, a5 as writtenResponseJsonSchema } from './index-CRKtWP5G.js';
+import './activity-DfAmJ1sl.js';
+export { B as BlankConfigSchema, D as DictationDataSchema, a as DictationEquivalenceSchema, b as DictationSlowMediaSchema, c as DictationToleranceSchema, F as FeedbackSchema, d as FillInTheBlanksDataSchema, G as GapSelectBankSchema, e as GapSelectChoiceSchema, f as GapSelectDataSchema, g as GapSelectGapSchema, h as ItemGroupSchema, M as MediaPlaybackSchema, i as MediaSchema, j as MediaUrlSchema, k as MultipleChoiceDataSchema, l as MultipleChoiceOptionMediaSchema, m as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as RedactedActivity, n as RedactedBlankConfig, o as RedactedBlankConfigSchema, p as RedactedDictationData, q as RedactedDictationDataSchema, r as RedactedDictationSlowMedia, s as RedactedDictationSlowMediaSchema, t as RedactedFillInTheBlanksData, u as RedactedFillInTheBlanksDataSchema, v as RedactedGapSelectBank, w as RedactedGapSelectBankSchema, x as RedactedGapSelectChoice, y as RedactedGapSelectChoiceSchema, z as RedactedGapSelectData, A as RedactedGapSelectDataSchema, C as RedactedGapSelectGap, E as RedactedGapSelectGapSchema, H as RedactedItemGroupSchema, J as RedactedMediaSchema, K as RedactedMultipleChoiceData, L as RedactedMultipleChoiceDataSchema, O as RedactedMultipleChoiceOption, P as RedactedMultipleChoiceOptionMedia, Q as RedactedMultipleChoiceOptionMediaSchema, S as RedactedMultipleChoiceOptionSchema, T as RedactedStimulus, U as RedactedStimulusSchema, V as RedactedWrittenResponseData, W as RedactedWrittenResponseDataSchema, a0 as StimulusSchema, a1 as TextMatchPolicySchema, a2 as WrittenResponseDataSchema, a3 as WrittenResponseRubricCriterionSchema, a4 as WrittenResponseRubricSchema, a5 as dictationJsonSchema, a6 as fillInTheBlanksJsonSchema, a7 as gapSelectJsonSchema, a8 as itemGroupJsonSchema, a9 as jsonSchemaFor, aa as multipleChoiceJsonSchema, ab as stimulusJsonSchema, ac as validateActivity, ad as validateItemGroup, ae as writtenResponseJsonSchema } from './index-CJbbVE9o.js';
 import 'zod/v4';

package/dist/schemas.js

@@ -3,6 +3,7 @@ import {
   RedactedItemGroupSchema,
   RedactedStimulusSchema,
   StimulusSchema,
+  dictationJsonSchema,
   fillInTheBlanksJsonSchema,
   gapSelectJsonSchema,
   itemGroupJsonSchema,
@@ -12,9 +13,13 @@ import {
   validateActivity,
   validateItemGroup,
   writtenResponseJsonSchema
-} from "./chunk-7JMMPE7O.js";
+} from "./chunk-Y36S3X3L.js";
 import {
   BlankConfigSchema,
+  DictationDataSchema,
+  DictationEquivalenceSchema,
+  DictationSlowMediaSchema,
+  DictationToleranceSchema,
   FeedbackSchema,
   FillInTheBlanksDataSchema,
   GapSelectBankSchema,
@@ -29,6 +34,8 @@ import {
   MultipleChoiceOptionSchema,
   NativeControlHintSchema,
   RedactedBlankConfigSchema,
+  RedactedDictationDataSchema,
+  RedactedDictationSlowMediaSchema,
   RedactedFillInTheBlanksDataSchema,
   RedactedGapSelectBankSchema,
   RedactedGapSelectChoiceSchema,
@@ -43,9 +50,13 @@ import {
   WrittenResponseDataSchema,
   WrittenResponseRubricCriterionSchema,
   WrittenResponseRubricSchema
-} from "./chunk-FVN37GIH.js";
+} from "./chunk-XKKKWKRH.js";
 export {
   BlankConfigSchema,
+  DictationDataSchema,
+  DictationEquivalenceSchema,
+  DictationSlowMediaSchema,
+  DictationToleranceSchema,
   FeedbackSchema,
   FillInTheBlanksDataSchema,
   GapSelectBankSchema,
@@ -61,6 +72,8 @@ export {
   MultipleChoiceOptionSchema,
   NativeControlHintSchema,
   RedactedBlankConfigSchema,
+  RedactedDictationDataSchema,
+  RedactedDictationSlowMediaSchema,
   RedactedFillInTheBlanksDataSchema,
   RedactedGapSelectBankSchema,
   RedactedGapSelectChoiceSchema,
@@ -78,6 +91,7 @@ export {
   WrittenResponseDataSchema,
   WrittenResponseRubricCriterionSchema,
   WrittenResponseRubricSchema,
+  dictationJsonSchema,
   fillInTheBlanksJsonSchema,
   gapSelectJsonSchema,
   itemGroupJsonSchema,

package/dist/scoring.cjs

@@ -7,11 +7,10 @@
 
 
 
-var _chunk4OHWLCI6cjs = require('./chunk-4OHWLCI6.cjs');
 
+var _chunkUHQVIC3Pcjs = require('./chunk-UHQVIC3P.cjs');
 
 
-var _chunkJ6POE4HLcjs = require('./chunk-J6POE4HL.cjs');
 
 
 
@@ -20,8 +19,25 @@ var _chunkJ6POE4HLcjs = require('./chunk-J6POE4HL.cjs');
 
 
 
+var _chunkXONKWL6Dcjs = require('./chunk-XONKWL6D.cjs');
 
 
 
-exports.DEFAULT_PASS_THRESHOLD = _chunk4OHWLCI6cjs.DEFAULT_PASS_THRESHOLD; exports.classifyBand = _chunk4OHWLCI6cjs.classifyBand; exports.composeAssessmentScore = _chunk4OHWLCI6cjs.composeAssessmentScore; exports.computePassThreshold = _chunk4OHWLCI6cjs.computePassThreshold; exports.evaluate = _chunk4OHWLCI6cjs.evaluate; exports.gte = _chunk4OHWLCI6cjs.gte; exports.levenshteinDistance = _chunkJ6POE4HLcjs.levenshteinDistance; exports.matchText = _chunkJ6POE4HLcjs.matchText; exports.roundGrade = _chunk4OHWLCI6cjs.roundGrade; exports.score = _chunk4OHWLCI6cjs.score;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.DEFAULT_PASS_THRESHOLD = _chunkUHQVIC3Pcjs.DEFAULT_PASS_THRESHOLD; exports.DICTATION_MAX_ACCEPTED_TRANSCRIPTS = _chunkXONKWL6Dcjs.DICTATION_MAX_ACCEPTED_TRANSCRIPTS; exports.DICTATION_MAX_EQUIVALENCES = _chunkXONKWL6Dcjs.DICTATION_MAX_EQUIVALENCES; exports.DICTATION_MAX_EQUIVALENCE_LENGTH = _chunkXONKWL6Dcjs.DICTATION_MAX_EQUIVALENCE_LENGTH; exports.DICTATION_MAX_TEXT_LENGTH = _chunkXONKWL6Dcjs.DICTATION_MAX_TEXT_LENGTH; exports.DICTATION_MAX_TRANSCRIPT_LENGTH = _chunkXONKWL6Dcjs.DICTATION_MAX_TRANSCRIPT_LENGTH; exports.alignDictation = _chunkXONKWL6Dcjs.alignDictation; exports.classifyBand = _chunkUHQVIC3Pcjs.classifyBand; exports.composeAssessmentScore = _chunkUHQVIC3Pcjs.composeAssessmentScore; exports.computePassThreshold = _chunkUHQVIC3Pcjs.computePassThreshold; exports.dictationReferenceWords = _chunkXONKWL6Dcjs.dictationReferenceWords; exports.diffDictationChars = _chunkUHQVIC3Pcjs.diffDictationChars; exports.evaluate = _chunkUHQVIC3Pcjs.evaluate; exports.gte = _chunkUHQVIC3Pcjs.gte; exports.levenshteinDistance = _chunkXONKWL6Dcjs.levenshteinDistance; exports.matchText = _chunkXONKWL6Dcjs.matchText; exports.roundGrade = _chunkUHQVIC3Pcjs.roundGrade; exports.score = _chunkUHQVIC3Pcjs.score;
 //# sourceMappingURL=scoring.cjs.map

package/dist/scoring.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/learning-kit/learning-kit/packages/lk-core/dist/scoring.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yjBAAC","file":"/home/runner/work/learning-kit/learning-kit/packages/lk-core/dist/scoring.cjs"}
+{"version":3,"sources":["/home/runner/work/learning-kit/learning-kit/packages/lk-core/dist/scoring.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,usCAAC","file":"/home/runner/work/learning-kit/learning-kit/packages/lk-core/dist/scoring.cjs"}

package/dist/scoring.d.cts

@@ -1,5 +1,5 @@
-import { r as ItemOutcome, A as ActivityData, L as LearnerResponse, e as ActivityType, x as ScoringResult } from './activity-B2QxK15j.cjs';
-export { T as TextMatchPolicy, y as TextMatchResult, $ as levenshteinDistance, a0 as matchText } from './activity-B2QxK15j.cjs';
+import { w as ItemOutcome, f as DictationData, A as ActivityData, L as LearnerResponse, e as ActivityType, K as ScoringResult } from './activity-DfAmJ1sl.cjs';
+export { T as TextMatchPolicy, O as TextMatchResult, a5 as levenshteinDistance, a6 as matchText } from './activity-DfAmJ1sl.cjs';
 
 /**
  * Rounding for assessment scores.
@@ -188,8 +188,153 @@ interface AssessmentScore {
  */
 declare function composeAssessmentScore(sections: readonly AssessmentSectionInput[], policy: CompositionPolicy): AssessmentScore;
 
+/** 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. */
+    itemId?: string;
+    /** The transcript word, normalised; `''` for an extra word. */
+    reference: string;
+    /** The word the learner typed for it, normalised; `''` for a missing word. */
+    attempt: string;
+    /** How alike the two words are, in [0, 1]; `0` for a missing or an extra word. */
+    similarity: number;
+    status: 'correct' | 'incorrect' | 'missing' | 'extra';
+}
+/**
+ * The comparison a dictation grade is made of: the normalised strings, which
+ * candidate transcript the attempt was scored against, and the word pairings.
+ * The same data the scorer reads, so a marked display and the grade cannot
+ * disagree.
+ */
+interface DictationAlignment {
+    /**
+     * Which candidate the attempt was scored against, by ORIGINAL position:
+     * `0` is `transcript`, `n` is `acceptedTranscripts[n − 1]`; `-1` when no
+     * candidate survives normalisation (stale or transcript-less data).
+     */
+    candidateIndex: number;
+    /** The chosen candidate, normalised; `''` when `candidateIndex` is `-1`. */
+    reference: string;
+    /** The attempt, normalised and possibly truncated. */
+    attempt: string;
+    /**
+     * Whether the learner's text was cut: at `DICTATION_MAX_TEXT_LENGTH` before or
+     * after normalisation, or while equivalence rules were growing it.
+     */
+    truncated: boolean;
+    /** The similarity of `attempt` to `reference` — the score. */
+    similarity: number;
+    /** Transcript words and extra words, in the order they align. */
+    words: DictationWordAlignment[];
+}
+/**
+ * What `alignDictation` reads. Every field optional, and read defensively: full
+ * data, a practice payload, a `redact(data, { reveal: 'after-submit' })`
+ * projection, or a plain redacted projection with no transcript at all — which
+ * yields `candidateIndex: -1`, never a throw.
+ */
+type DictationReference = Partial<Pick<DictationData, 'transcript' | 'acceptedTranscripts' | 'tolerance'>>;
+/**
+ * The words the scorer can emit a detail for, one list per candidate — index 0
+ * is the transcript, index n is `acceptedTranscripts[n − 1]` — each word in the
+ * normalised form `correctResponse` carries. A candidate that normalises to
+ * nothing gives an empty list. Derivable from the activity alone, which is what
+ * a validator of stored details joins against: by id AND by word, because
+ * positional ids alone cannot tell an edited transcript of the same length.
+ */
+declare function dictationReferenceWords(data: DictationReference): readonly (readonly {
+    itemId: string;
+    word: string;
+}[])[];
+/**
+ * Compares a learner's text with a dictation's transcript(s). Pure and
+ * deterministic: no locale, no `Intl`, integer alignment costs, one pinned
+ * tie order.
+ *
+ * The attempt is cut at `DICTATION_MAX_TEXT_LENGTH` code points before and
+ * after normalisation — a cut that ends on a space leaves no empty word after
+ * it — and `truncated` is also set when the rules grew its
+ * working text past the normaliser's bound (see `normalizeDictationText`).
+ * Every candidate — the transcript and at most
+ * `DICTATION_MAX_ACCEPTED_TRANSCRIPTS` accepted transcripts — is normalised
+ * with the same tolerance and cut at `DICTATION_MAX_TRANSCRIPT_LENGTH`; the
+ * attempt is scored against each surviving candidate and the first best wins.
+ * Words are then paired by a word-level edit distance with exact-equality
+ * costs, backtracked from the end preferring a pairing, then a missing
+ * transcript word, then an extra typed word; a paired word's similarity is its
+ * own character similarity.
+ */
+declare function alignDictation(data: DictationReference, text: string): DictationAlignment;
+
+/** One code-point edit between a reference string and an attempt. */
+interface DictationCharOp {
+    op: 'equal' | 'substitute' | 'missing' | 'extra';
+    /** One code point of the reference, or `''` for an extra character. */
+    reference: string;
+    /** One code point of the attempt, or `''` for a missing character. */
+    attempt: string;
+}
+/**
+ * The code-point edit operations between two NORMALISED strings — the
+ * `reference` and `attempt` of a `DictationAlignment`, or one word pair from
+ * it — for a marked display: a character the learner typed right, typed
+ * wrong, left out, or added. Ties are broken preferring an equal or substituted
+ * pair, then a missing character, then an extra one, from the end of both
+ * strings; the number of non-`equal` ops is the edit distance.
+ *
+ * Decoration, never grading: it needs O(|reference|·|attempt|) memory, so the
+ * scorer does not call it, and a display computes it once per result.
+ */
+declare function diffDictationChars(reference: string, attempt: string): DictationCharOp[];
+
+/**
+ * The longest transcript a dictation accepts, in code points, before and after
+ * its equivalences are applied — and its rules may not grow it past twice
+ * `DICTATION_MAX_TEXT_LENGTH` on the way. A dictation is a sentence or two; the
+ * cap keeps the scorer's quadratic step bounded on the server that grades an
+ * exam.
+ */
+declare const DICTATION_MAX_TRANSCRIPT_LENGTH = 2000;
+/**
+ * The longest learner text the scorer compares, in code points. Text beyond it
+ * is cut off — before normalisation, and again after it, because a rewrite rule
+ * or a folded character can lengthen text — and the alignment says so.
+ */
+declare const DICTATION_MAX_TEXT_LENGTH = 8000;
+/** The longest `from` and `to` of an equivalence rule, in code points. */
+declare const DICTATION_MAX_EQUIVALENCE_LENGTH = 200;
+/**
+ * The most equivalence rules a dictation carries. The scorer reads no rule
+ * past this many, so stale data with more cannot slow a grading run.
+ */
+declare const DICTATION_MAX_EQUIVALENCES = 100;
+/**
+ * The most accepted transcripts a dictation carries. The scorer reads no more
+ * than this many, for the same reason.
+ */
+declare const DICTATION_MAX_ACCEPTED_TRANSCRIPTS = 10;
+
 /** Default minimum scaled score required to pass when `passThreshold` is absent. */
 declare const DEFAULT_PASS_THRESHOLD = 0.7;
+/**
+ * Options for {@link score} and {@link evaluate}. Additive: with none, both
+ * behave exactly as they always have.
+ */
+interface ScoringOptions {
+    /**
+     * Compare the pass line the way the score is displayed — both sides rounded,
+     * via {@link computePassThreshold} — so an item shown as "70%" is not
+     * recorded as a fail at 69.995. `passed` AND the authored feedback selected by
+     * it follow the rounded comparison. Opt-in, for the reason
+     * {@link computePassThreshold} gives: switching it on moves item-level
+     * pass/fail for scores in the rounding band.
+     *
+     * Checked at the call: `null` reads as no policy, and a policy that cannot be
+     * applied — an unknown `mode`, or a `dp` that is not a whole number from 0 to
+     * 15 — throws a `RangeError` instead of quietly failing every comparison.
+     */
+    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.
@@ -216,7 +361,7 @@ declare function computePassThreshold(activityData: ActivityData, score: number,
  * `written-response`) throws {@link DeferredScoringError} — use
  * {@link evaluate}, which can express "not graded yet".
  */
-declare function score(activityType: ActivityType, activityData: ActivityData, learnerResponse: LearnerResponse): ScoringResult;
+declare function score(activityType: ActivityType, activityData: ActivityData, learnerResponse: LearnerResponse, options?: ScoringOptions): ScoringResult;
 /**
  * Evaluates a learner response against an activity and returns an
  * {@link ItemOutcome} — the resilient, forward-compatible alternative to
@@ -234,6 +379,6 @@ declare function score(activityType: ActivityType, activityData: ActivityData, l
  * The activity type is read from `data.type` — there is no separate type
  * parameter to disagree with the payload.
  */
-declare function evaluate(data: ActivityData, response: LearnerResponse): ItemOutcome;
+declare function evaluate(data: ActivityData, response: LearnerResponse, options?: ScoringOptions): ItemOutcome;
 
-export { type AssessmentScore, type AssessmentSectionInput, type Band, type CompositionPolicy, DEFAULT_PASS_THRESHOLD, type PassFailureReason, type RoundingMode, type RoundingPolicy, type ScoredItem, type SectionScore, classifyBand, composeAssessmentScore, computePassThreshold, 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 PassFailureReason, type RoundingMode, type RoundingPolicy, type ScoredItem, type ScoringOptions, type SectionScore, alignDictation, classifyBand, composeAssessmentScore, computePassThreshold, dictationReferenceWords, diffDictationChars, evaluate, gte, roundGrade, score };

package/dist/scoring.d.ts

@@ -1,5 +1,5 @@
-import { r as ItemOutcome, A as ActivityData, L as LearnerResponse, e as ActivityType, x as ScoringResult } from './activity-B2QxK15j.js';
-export { T as TextMatchPolicy, y as TextMatchResult, $ as levenshteinDistance, a0 as matchText } from './activity-B2QxK15j.js';
+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';
 
 /**
  * Rounding for assessment scores.
@@ -188,8 +188,153 @@ interface AssessmentScore {
  */
 declare function composeAssessmentScore(sections: readonly AssessmentSectionInput[], policy: CompositionPolicy): AssessmentScore;
 
+/** 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. */
+    itemId?: string;
+    /** The transcript word, normalised; `''` for an extra word. */
+    reference: string;
+    /** The word the learner typed for it, normalised; `''` for a missing word. */
+    attempt: string;
+    /** How alike the two words are, in [0, 1]; `0` for a missing or an extra word. */
+    similarity: number;
+    status: 'correct' | 'incorrect' | 'missing' | 'extra';
+}
+/**
+ * The comparison a dictation grade is made of: the normalised strings, which
+ * candidate transcript the attempt was scored against, and the word pairings.
+ * The same data the scorer reads, so a marked display and the grade cannot
+ * disagree.
+ */
+interface DictationAlignment {
+    /**
+     * Which candidate the attempt was scored against, by ORIGINAL position:
+     * `0` is `transcript`, `n` is `acceptedTranscripts[n − 1]`; `-1` when no
+     * candidate survives normalisation (stale or transcript-less data).
+     */
+    candidateIndex: number;
+    /** The chosen candidate, normalised; `''` when `candidateIndex` is `-1`. */
+    reference: string;
+    /** The attempt, normalised and possibly truncated. */
+    attempt: string;
+    /**
+     * Whether the learner's text was cut: at `DICTATION_MAX_TEXT_LENGTH` before or
+     * after normalisation, or while equivalence rules were growing it.
+     */
+    truncated: boolean;
+    /** The similarity of `attempt` to `reference` — the score. */
+    similarity: number;
+    /** Transcript words and extra words, in the order they align. */
+    words: DictationWordAlignment[];
+}
+/**
+ * What `alignDictation` reads. Every field optional, and read defensively: full
+ * data, a practice payload, a `redact(data, { reveal: 'after-submit' })`
+ * projection, or a plain redacted projection with no transcript at all — which
+ * yields `candidateIndex: -1`, never a throw.
+ */
+type DictationReference = Partial<Pick<DictationData, 'transcript' | 'acceptedTranscripts' | 'tolerance'>>;
+/**
+ * The words the scorer can emit a detail for, one list per candidate — index 0
+ * is the transcript, index n is `acceptedTranscripts[n − 1]` — each word in the
+ * normalised form `correctResponse` carries. A candidate that normalises to
+ * nothing gives an empty list. Derivable from the activity alone, which is what
+ * a validator of stored details joins against: by id AND by word, because
+ * positional ids alone cannot tell an edited transcript of the same length.
+ */
+declare function dictationReferenceWords(data: DictationReference): readonly (readonly {
+    itemId: string;
+    word: string;
+}[])[];
+/**
+ * Compares a learner's text with a dictation's transcript(s). Pure and
+ * deterministic: no locale, no `Intl`, integer alignment costs, one pinned
+ * tie order.
+ *
+ * The attempt is cut at `DICTATION_MAX_TEXT_LENGTH` code points before and
+ * after normalisation — a cut that ends on a space leaves no empty word after
+ * it — and `truncated` is also set when the rules grew its
+ * working text past the normaliser's bound (see `normalizeDictationText`).
+ * Every candidate — the transcript and at most
+ * `DICTATION_MAX_ACCEPTED_TRANSCRIPTS` accepted transcripts — is normalised
+ * with the same tolerance and cut at `DICTATION_MAX_TRANSCRIPT_LENGTH`; the
+ * attempt is scored against each surviving candidate and the first best wins.
+ * Words are then paired by a word-level edit distance with exact-equality
+ * costs, backtracked from the end preferring a pairing, then a missing
+ * transcript word, then an extra typed word; a paired word's similarity is its
+ * own character similarity.
+ */
+declare function alignDictation(data: DictationReference, text: string): DictationAlignment;
+
+/** One code-point edit between a reference string and an attempt. */
+interface DictationCharOp {
+    op: 'equal' | 'substitute' | 'missing' | 'extra';
+    /** One code point of the reference, or `''` for an extra character. */
+    reference: string;
+    /** One code point of the attempt, or `''` for a missing character. */
+    attempt: string;
+}
+/**
+ * The code-point edit operations between two NORMALISED strings — the
+ * `reference` and `attempt` of a `DictationAlignment`, or one word pair from
+ * it — for a marked display: a character the learner typed right, typed
+ * wrong, left out, or added. Ties are broken preferring an equal or substituted
+ * pair, then a missing character, then an extra one, from the end of both
+ * strings; the number of non-`equal` ops is the edit distance.
+ *
+ * Decoration, never grading: it needs O(|reference|·|attempt|) memory, so the
+ * scorer does not call it, and a display computes it once per result.
+ */
+declare function diffDictationChars(reference: string, attempt: string): DictationCharOp[];
+
+/**
+ * The longest transcript a dictation accepts, in code points, before and after
+ * its equivalences are applied — and its rules may not grow it past twice
+ * `DICTATION_MAX_TEXT_LENGTH` on the way. A dictation is a sentence or two; the
+ * cap keeps the scorer's quadratic step bounded on the server that grades an
+ * exam.
+ */
+declare const DICTATION_MAX_TRANSCRIPT_LENGTH = 2000;
+/**
+ * The longest learner text the scorer compares, in code points. Text beyond it
+ * is cut off — before normalisation, and again after it, because a rewrite rule
+ * or a folded character can lengthen text — and the alignment says so.
+ */
+declare const DICTATION_MAX_TEXT_LENGTH = 8000;
+/** The longest `from` and `to` of an equivalence rule, in code points. */
+declare const DICTATION_MAX_EQUIVALENCE_LENGTH = 200;
+/**
+ * The most equivalence rules a dictation carries. The scorer reads no rule
+ * past this many, so stale data with more cannot slow a grading run.
+ */
+declare const DICTATION_MAX_EQUIVALENCES = 100;
+/**
+ * The most accepted transcripts a dictation carries. The scorer reads no more
+ * than this many, for the same reason.
+ */
+declare const DICTATION_MAX_ACCEPTED_TRANSCRIPTS = 10;
+
 /** Default minimum scaled score required to pass when `passThreshold` is absent. */
 declare const DEFAULT_PASS_THRESHOLD = 0.7;
+/**
+ * Options for {@link score} and {@link evaluate}. Additive: with none, both
+ * behave exactly as they always have.
+ */
+interface ScoringOptions {
+    /**
+     * Compare the pass line the way the score is displayed — both sides rounded,
+     * via {@link computePassThreshold} — so an item shown as "70%" is not
+     * recorded as a fail at 69.995. `passed` AND the authored feedback selected by
+     * it follow the rounded comparison. Opt-in, for the reason
+     * {@link computePassThreshold} gives: switching it on moves item-level
+     * pass/fail for scores in the rounding band.
+     *
+     * Checked at the call: `null` reads as no policy, and a policy that cannot be
+     * applied — an unknown `mode`, or a `dp` that is not a whole number from 0 to
+     * 15 — throws a `RangeError` instead of quietly failing every comparison.
+     */
+    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.
@@ -216,7 +361,7 @@ declare function computePassThreshold(activityData: ActivityData, score: number,
  * `written-response`) throws {@link DeferredScoringError} — use
  * {@link evaluate}, which can express "not graded yet".
  */
-declare function score(activityType: ActivityType, activityData: ActivityData, learnerResponse: LearnerResponse): ScoringResult;
+declare function score(activityType: ActivityType, activityData: ActivityData, learnerResponse: LearnerResponse, options?: ScoringOptions): ScoringResult;
 /**
  * Evaluates a learner response against an activity and returns an
  * {@link ItemOutcome} — the resilient, forward-compatible alternative to
@@ -234,6 +379,6 @@ declare function score(activityType: ActivityType, activityData: ActivityData, l
  * The activity type is read from `data.type` — there is no separate type
  * parameter to disagree with the payload.
  */
-declare function evaluate(data: ActivityData, response: LearnerResponse): ItemOutcome;
+declare function evaluate(data: ActivityData, response: LearnerResponse, options?: ScoringOptions): ItemOutcome;
 
-export { type AssessmentScore, type AssessmentSectionInput, type Band, type CompositionPolicy, DEFAULT_PASS_THRESHOLD, type PassFailureReason, type RoundingMode, type RoundingPolicy, type ScoredItem, type SectionScore, classifyBand, composeAssessmentScore, computePassThreshold, 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 PassFailureReason, type RoundingMode, type RoundingPolicy, type ScoredItem, type ScoringOptions, type SectionScore, alignDictation, classifyBand, composeAssessmentScore, computePassThreshold, dictationReferenceWords, diffDictationChars, evaluate, gte, roundGrade, score };

package/dist/scoring.js

@@ -3,20 +3,36 @@ import {
   classifyBand,
   composeAssessmentScore,
   computePassThreshold,
+  diffDictationChars,
   evaluate,
   gte,
   roundGrade,
   score
-} from "./chunk-RK2NVTHZ.js";
+} from "./chunk-FGN4LLSP.js";
 import {
+  DICTATION_MAX_ACCEPTED_TRANSCRIPTS,
+  DICTATION_MAX_EQUIVALENCES,
+  DICTATION_MAX_EQUIVALENCE_LENGTH,
+  DICTATION_MAX_TEXT_LENGTH,
+  DICTATION_MAX_TRANSCRIPT_LENGTH,
+  alignDictation,
+  dictationReferenceWords,
   levenshteinDistance,
   matchText
-} from "./chunk-FVN37GIH.js";
+} from "./chunk-XKKKWKRH.js";
 export {
   DEFAULT_PASS_THRESHOLD,
+  DICTATION_MAX_ACCEPTED_TRANSCRIPTS,
+  DICTATION_MAX_EQUIVALENCES,
+  DICTATION_MAX_EQUIVALENCE_LENGTH,
+  DICTATION_MAX_TEXT_LENGTH,
+  DICTATION_MAX_TRANSCRIPT_LENGTH,
+  alignDictation,
   classifyBand,
   composeAssessmentScore,
   computePassThreshold,
+  dictationReferenceWords,
+  diffDictationChars,
   evaluate,
   gte,
   levenshteinDistance,

package/dist/xapi.cjs

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

package/dist/xapi.d.cts

@@ -1,4 +1,4 @@
-import { X as XAPIActor, x as ScoringResult, O as XAPIContext, U as XAPIResult, Z as XAPIStatement } from './activity-B2QxK15j.cjs';
+import { X as XAPIActor, K as ScoringResult, Z as XAPIContext, a1 as XAPIResult, a3 as XAPIStatement } from './activity-DfAmJ1sl.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, x as ScoringResult, O as XAPIContext, U as XAPIResult, Z as XAPIStatement } from './activity-B2QxK15j.js';
+import { X as XAPIActor, K as ScoringResult, Z as XAPIContext, a1 as XAPIResult, a3 as XAPIStatement } from './activity-DfAmJ1sl.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-UQPNJP2O.js";
-import "./chunk-FVN37GIH.js";
+} from "./chunk-PYP3HCRQ.js";
+import "./chunk-XKKKWKRH.js";
 export {
   XAPIVerb,
   XAPI_VERB_DISPLAY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intellectif/lk-core",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "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",

package/vectors/README.md

@@ -56,8 +56,16 @@ a known hazard carry a `note` saying why they exist.
 - **Written-response word counts**, recomputed from the text rather than taken
   from the client's `wordCount`, with inclusive `minWords` / `maxWords` bounds.
 - **`matchText` and `levenshteinDistance`** across every authored policy.
+- **`alignDictation`, `diffDictationChars` and `dictationReferenceWords`**, with
+  the five **`DICTATION_MAX_*`** limits: how a dictation reads the learner's text
+  and each transcript — punctuation, compatibility forms, joiners and other
+  invisible characters, lone surrogates — how equivalence rules rewrite them,
+  which transcript an attempt is compared with when several are accepted and how
+  a tie breaks, the words a transcript is split into, how words and characters
+  are paired, and where each limit cuts.
 - **`computePassThreshold` and `DEFAULT_PASS_THRESHOLD`**, including an authored
-  threshold of `0`.
+  threshold of `0`, and the opt-in `rounding` option of `score`, both where it
+  turns a raw fail in the rounding band into a pass and where it changes nothing.
 - **`roundGrade`, `gte` and `classifyBand`** in every mode, including float
   edges, negative zero, half-even ties and near-ties, and bands that share a
   minimum.