@intellectif/lk-core 1.4.0 → 1.5.0

package/dist/{scoring-BZqUkuDF.js → scoring-BKNNTz-s.js}

@@ -1,4 +1,4 @@
-import { $ as dictationReferenceWords, C as SPEECH_ASSESSMENT_MAX_TEXT_LENGTH, J as RedactedScoringError, K as ActivitySchemaError, Q as alignSequences, X as STEP, Y as UnknownActivityTypeError, _ as ReadAloudDataSchema, at as codePointLength, j as countWords, ot as normalizeDictationText, q as DeferredScoringError, t as getActivityTypeDescriptor, v as CANONICAL_LOCALE_RE, w as SPEECH_ASSESSMENT_MAX_WORDS, yt as maxUnits } from "./registry-Dsx9mNsS.js";
+import { $ as RedactedScoringError, F as readRubricLevels, I as countWords, N as levelDistribution, P as levelKey, Q as DeferredScoringError, T as SPEECH_ASSESSMENT_MAX_WORDS, Z as ActivitySchemaError, dt as normalizeDictationText, et as UnknownActivityTypeError, it as dictationReferenceWords, rt as alignSequences, t as getActivityTypeDescriptor, tt as STEP, ut as codePointLength, v as ReadAloudDataSchema, w as SPEECH_ASSESSMENT_MAX_TEXT_LENGTH, wt as maxUnits, y as CANONICAL_LOCALE_RE } from "./registry-DaZRpqjW.js";
 import * as z from "zod/v4";
 //#region src/scoring/grade-numbers.ts
 /**
@@ -358,6 +358,406 @@ function selectFeedback(activityData, passed) {
 	return (passed ? feedback.correct : feedback.incorrect) ?? null;
 }
 //#endregion
+//#region src/content-hash.ts
+/**
+* Content fingerprinting — "is this the same content the learner was served?"
+*
+* A recorded attempt outlives the content it was taken against. Papers get
+* corrected, a typo is fixed, an option is reworded — and six months later a
+* remark, an appeal, or a per-item analysis is run against content that is no
+* longer what the learner saw. Nothing warns anybody, because the ids all still
+* match. A fingerprint stored with the attempt turns that silent drift into a
+* question somebody can answer.
+*/
+/**
+* Deterministic JSON: object keys sorted, arrays left in order, `undefined`
+* omitted from objects (matching `JSON.stringify`) and rendered as `null`
+* inside arrays.
+*
+* Key order is the whole point. Two objects that differ only in the order
+* their keys happened to be written are the SAME content, and a fingerprint
+* that disagreed would raise a false alarm every time a payload made a
+* round-trip through a different serializer.
+*/
+function canonicalJson(value, seen = /* @__PURE__ */ new Set()) {
+	if (value === null) return "null";
+	if (typeof value === "number") return Number.isFinite(value) ? JSON.stringify(value === 0 ? 0 : value) : `"#${String(value)}"`;
+	if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+	if (typeof value === "bigint") return `"#${value.toString()}n"`;
+	if (typeof value === "object") {
+		if (seen.has(value)) throw new Error("canonicalJson: the value contains a circular reference and cannot be fingerprinted.");
+		seen.add(value);
+		try {
+			if (Array.isArray(value)) return `[${value.map((element) => element === void 0 ? "null" : canonicalJson(element, seen)).join(",")}]`;
+			const source = value;
+			const parts = [];
+			for (const key of Object.keys(source).sort()) {
+				const entry = source[key];
+				if (entry === void 0) continue;
+				parts.push(`${JSON.stringify(key)}:${canonicalJson(entry, seen)}`);
+			}
+			return `{${parts.join(",")}}`;
+		} finally {
+			seen.delete(value);
+		}
+	}
+	return "null";
+}
+const FNV_OFFSET = 14695981039346656037n;
+const FNV_PRIME = 1099511628211n;
+const MASK64 = (1n << 64n) - 1n;
+/**
+* FNV-1a over the UTF-8 bytes of `input`, as 16 lowercase hex digits.
+*
+* **This is a change-detection fingerprint, not a tamper-evident signature.**
+* It is deterministic across runtimes and dependency-free, which is what makes
+* it usable in a stored grade record — but an adversary who can edit content
+* can also, with effort, preserve the fingerprint. If you need the stronger
+* property, sign the plan with a key the content author does not hold; this
+* exists to catch honest edits, which is what actually happens.
+*/
+function fingerprint(input) {
+	const bytes = new TextEncoder().encode(input);
+	let hash = FNV_OFFSET;
+	for (const byte of bytes) hash = (hash ^ BigInt(byte)) * FNV_PRIME & MASK64;
+	return hash.toString(16).padStart(16, "0");
+}
+/**
+* Fingerprints any JSON-serialisable value through {@link canonicalJson}, so
+* the result depends on the content and not on how it was written.
+*/
+function contentHash(value) {
+	return fingerprint(canonicalJson(value));
+}
+//#endregion
+//#region src/scoring/assisted/calibration.ts
+const mean = (values) => values.reduce((sum, value) => sum + value, 0) / values.length;
+/** Population variance. */
+function variance(values) {
+	const m = mean(values);
+	return mean(values.map((value) => (value - m) ** 2));
+}
+/** Pearson's r; `null` with fewer than two pairs or no variance on a side. */
+function pearson(xs, ys) {
+	if (xs.length < 2) return null;
+	const mx = mean(xs);
+	const my = mean(ys);
+	let cov = 0;
+	let vx = 0;
+	let vy = 0;
+	for (let i = 0; i < xs.length; i += 1) {
+		const dx = xs[i] - mx;
+		const dy = ys[i] - my;
+		cov += dx * dy;
+		vx += dx * dx;
+		vy += dy * dy;
+	}
+	return vx === 0 || vy === 0 ? null : cov / Math.sqrt(vx * vy);
+}
+/** Model mean minus person mean, over the pooled population standard deviation. */
+function standardizedMeanDifference(model, person) {
+	if (model.length === 0) return null;
+	const pooled = Math.sqrt((variance(model) + variance(person)) / 2);
+	return pooled === 0 ? null : (mean(model) - mean(person)) / pooled;
+}
+/** Cohen's kappa with quadratic weights over `k` levels; `null` when undefined. */
+function quadraticKappa(rows, cols, k) {
+	const n = rows.length;
+	if (n === 0 || k < 2) return null;
+	const observed = Array.from({ length: k }, () => new Array(k).fill(0));
+	const rowTotals = new Array(k).fill(0);
+	const colTotals = new Array(k).fill(0);
+	for (let i = 0; i < n; i += 1) {
+		const r = rows[i];
+		const c = cols[i];
+		observed[r][c] = observed[r][c] + 1;
+		rowTotals[r] = rowTotals[r] + 1;
+		colTotals[c] = colTotals[c] + 1;
+	}
+	let disagreement = 0;
+	let chance = 0;
+	for (let r = 0; r < k; r += 1) for (let c = 0; c < k; c += 1) {
+		const weight = (r - c) ** 2 / (k - 1) ** 2;
+		disagreement += weight * observed[r][c];
+		chance += weight * rowTotals[r] * colTotals[c] / n;
+	}
+	return chance === 0 ? null : 1 - disagreement / chance;
+}
+/** Ten equal bins of confidence; the mean absolute gap between confidence and accuracy, weighted by bin size. */
+function expectedCalibrationError(confidence, correct) {
+	const bins = Array.from({ length: 10 }, () => ({
+		n: 0,
+		confidence: 0,
+		correct: 0
+	}));
+	for (let i = 0; i < confidence.length; i += 1) {
+		const c = confidence[i];
+		const bin = bins[Math.min(9, Math.floor(c * 10))];
+		bin.n += 1;
+		bin.confidence += c;
+		bin.correct += correct[i] ? 1 : 0;
+	}
+	return bins.reduce((sum, bin) => bin.n === 0 ? sum : sum + bin.n / confidence.length * Math.abs(bin.correct / bin.n - bin.confidence / bin.n), 0);
+}
+/** The grader configuration a model grade comes from, on items with this rubric and target; `null` when the grade does not name its model and prompt. */
+function graderConfiguration(grade, scope) {
+	const model = grade.grader?.model;
+	const promptHash = grade.grader?.promptHash;
+	if (typeof model !== "string" || model === "" || typeof promptHash !== "string" || promptHash === "") return null;
+	return {
+		model,
+		promptHash,
+		rubricHash: contentHash(scope.rubric ?? null),
+		languageTarget: typeof scope.languageTarget === "string" ? scope.languageTarget : null
+	};
+}
+/** Configurations as equal as a calibration requires: every field. */
+function sameConfiguration(a, b) {
+	return a.model === b.model && a.promptHash === b.promptHash && a.rubricHash === b.rubricHash && a.languageTarget === b.languageTarget;
+}
+/** Each rubric criterion's scale, or the name of the first whose levels cannot be read. */
+function rubricScales(rubric) {
+	const scales = [];
+	for (const criterion of rubric?.criteria ?? []) {
+		const read = readRubricLevels(criterion.levels);
+		if (!read.ok) return {
+			ok: false,
+			name: criterion.name
+		};
+		scales.push({
+			name: criterion.name,
+			levels: read.levels
+		});
+	}
+	return {
+		ok: true,
+		scales
+	};
+}
+/** A grade's judgement of the criterion named `name`, its name compared as labels are. */
+function criterionOf(grade, name) {
+	return (grade.criteria ?? []).find((one) => levelKey(one.name) === levelKey(name));
+}
+/**
+* A judgement on a criterion's levels: the index of the level its `band`
+* names, and its `levelProbabilities` when they are a distribution over the
+* levels whose likeliest is that level. `null` when it names no level the
+* criterion has.
+*/
+function levelOf(judged, levels) {
+	const band = judged.band;
+	const level = typeof band === "string" ? levels.findIndex((one) => levelKey(one.label) === levelKey(band)) : -1;
+	if (level === -1) return null;
+	const probabilities = judged.levelProbabilities;
+	return {
+		level,
+		probabilities: Array.isArray(probabilities) ? levelDistribution(probabilities, levels.length, level) : null
+	};
+}
+/**
+* A judgement on a score, as a fraction of its `maxScore`, read as
+* `gradeFromRubric` reads one: a positive, finite maximum, and a ratio within
+* 0 to 1, a hair outside it float noise and clamped. `null` when it has none.
+*/
+function scoreOf$1(judged) {
+	const score = judged.score;
+	const max = judged.maxScore ?? 1;
+	if (typeof score !== "number" || !Number.isFinite(score) || !(Number.isFinite(max) && max > 0)) return null;
+	const ratio = score / max;
+	return ratio < -1e-9 || ratio > 1.000000001 ? null : Math.min(1, Math.max(0, ratio));
+}
+/**
+* A grade's judgement of a criterion on its scale: its score from 0 to 1, and on
+* levels the level's index (-1 on a score) and any distribution. `null` when it
+* is not applicable or cannot be read.
+*/
+function reading(grade, scale) {
+	const judged = criterionOf(grade, scale.name);
+	if (judged === void 0 || judged.notApplicable === true) return null;
+	if (scale.levels === null) {
+		const score = scoreOf$1(judged);
+		return score === null ? null : {
+			score,
+			level: -1,
+			probabilities: null
+		};
+	}
+	const read = levelOf(judged, scale.levels);
+	return read === null ? null : {
+		score: read.level / (scale.levels.length - 1),
+		...read
+	};
+}
+function calibrateCriterion(scale, pairs) {
+	const model = [];
+	const person = [];
+	const modelLevels = [];
+	const personLevels = [];
+	const confidence = [];
+	const correct = [];
+	let brier = 0;
+	const human = {
+		first: [],
+		second: [],
+		firstLevels: [],
+		secondLevels: []
+	};
+	for (const pair of pairs) {
+		const m = reading(pair.model, scale);
+		const p = reading(pair.person, scale);
+		if (m === null || p === null) continue;
+		model.push(m.score);
+		person.push(p.score);
+		modelLevels.push(m.level);
+		personLevels.push(p.level);
+		if (m.probabilities !== null) {
+			confidence.push(m.probabilities[m.level]);
+			correct.push(m.level === p.level);
+			brier += m.probabilities.reduce((sum, probability, index) => sum + (probability - (index === p.level ? 1 : 0)) ** 2, 0);
+		}
+		const s = pair.secondPerson === void 0 ? null : reading(pair.secondPerson, scale);
+		if (s !== null) {
+			human.first.push(p.score);
+			human.second.push(s.score);
+			human.firstLevels.push(p.level);
+			human.secondLevels.push(s.level);
+		}
+	}
+	const n = model.length;
+	const shared = {
+		name: scale.name,
+		pairs: n,
+		pearson: pearson(model, person),
+		meanAbsoluteError: n === 0 ? null : mean(model.map((value, i) => Math.abs(value - person[i]))),
+		standardizedMeanDifference: standardizedMeanDifference(model, person)
+	};
+	const humanPairs = human.first.length;
+	const humanPearson = pearson(human.first, human.second);
+	if (scale.levels === null) return {
+		...shared,
+		scale: "score",
+		...humanPairs > 0 ? {
+			humanPairs,
+			humanPearson,
+			degradation: humanPearson === null || shared.pearson === null ? null : humanPearson - shared.pearson
+		} : {}
+	};
+	const k = scale.levels.length;
+	const kappa = quadraticKappa(personLevels, modelLevels, k);
+	const confusion = Array.from({ length: k }, () => new Array(k).fill(0));
+	personLevels.forEach((r, i) => {
+		confusion[r][modelLevels[i]] += 1;
+	});
+	const humanKappa = quadraticKappa(human.firstLevels, human.secondLevels, k);
+	return {
+		...shared,
+		scale: "levels",
+		levels: k,
+		exactAgreement: n === 0 ? null : modelLevels.filter((level, i) => level === personLevels[i]).length / n,
+		adjacentAgreement: n === 0 ? null : modelLevels.filter((level, i) => Math.abs(level - personLevels[i]) <= 1).length / n,
+		quadraticKappa: kappa,
+		confusion,
+		probabilityPairs: confidence.length,
+		calibrationError: confidence.length === 0 ? null : expectedCalibrationError(confidence, correct),
+		brierScore: confidence.length === 0 ? null : brier / confidence.length,
+		...humanPairs > 0 ? {
+			humanPairs,
+			humanQuadraticKappa: humanKappa,
+			humanPearson,
+			degradation: humanKappa === null || kappa === null ? null : humanKappa - kappa
+		} : {}
+	};
+}
+function calibrateTotal(pairs) {
+	const model = pairs.map((pair) => pair.model.score / pair.model.maxScore);
+	const person = pairs.map((pair) => pair.person.score / pair.person.maxScore);
+	const both = pairs.filter((pair) => pair.secondPerson !== void 0);
+	const humanPearson = pearson(both.map((pair) => pair.person.score / pair.person.maxScore), both.map((pair) => {
+		const second = pair.secondPerson;
+		return second.score / second.maxScore;
+	}));
+	const modelPearson = pearson(model, person);
+	return {
+		pairs: pairs.length,
+		pearson: modelPearson,
+		meanAbsoluteError: mean(model.map((value, i) => Math.abs(value - person[i]))),
+		standardizedMeanDifference: standardizedMeanDifference(model, person),
+		passAgreement: pairs.filter((pair) => pair.model.passed === pair.person.passed).length / pairs.length,
+		...both.length > 0 ? {
+			humanPairs: both.length,
+			humanPearson,
+			degradation: humanPearson === null || modelPearson === null ? null : humanPearson - modelPearson
+		} : {}
+	};
+}
+/**
+* How one grader configuration — a model, a prompt revision, a rubric and a
+* target language — agrees with people, measured on responses the host had
+* marked twice. Pure: the same pairs give the same report and the same
+* `reportHash`.
+*
+* Every model grade must come from one configuration (its `grader` names the
+* model and the prompt), and no person's grade may be a model's. A criterion
+* is measured over the pairs where both judged it on its scale — levels by
+* their labels, scores as fractions of their maximum — and every metric that
+* is undefined is `null`, never a number made up. It ships no threshold:
+* `routeGrade` applies the host's.
+*/
+function calibrationReport(pairs, scope) {
+	if (pairs.length === 0) return {
+		ok: false,
+		reason: "No pairs: a calibration needs responses marked by the model and by a person."
+	};
+	const read = rubricScales(scope.rubric);
+	if (!read.ok) return {
+		ok: false,
+		reason: `Criterion "${read.name}" has levels the grading functions cannot read.`
+	};
+	const scales = read.scales;
+	if (scales.length === 0) return {
+		ok: false,
+		reason: "No rubric: a calibration measures a grader criterion by criterion."
+	};
+	let configuration = null;
+	for (const [index, pair] of pairs.entries()) {
+		if ([
+			pair.model,
+			pair.person,
+			...pair.secondPerson ? [pair.secondPerson] : []
+		].some((grade) => !isGradeInRange(grade.score, grade.maxScore))) return {
+			ok: false,
+			reason: `Pair ${index + 1} has a grade whose numbers cannot be a grade.`
+		};
+		if ([pair.person, pair.secondPerson].some((grade) => grade?.grader !== void 0 && grade.grader.kind !== "human")) return {
+			ok: false,
+			reason: `Pair ${index + 1} has a person's grade that a grader other than a person gave.`
+		};
+		const own = graderConfiguration(pair.model, scope);
+		if (own === null) return {
+			ok: false,
+			reason: `Pair ${index + 1}'s model grade does not name its model and prompt (grader.model, grader.promptHash), so it cannot be calibrated.`
+		};
+		if (configuration !== null && !sameConfiguration(configuration, own)) return {
+			ok: false,
+			reason: `Pair ${index + 1}'s model grade comes from another configuration: a report measures one model, prompt, rubric and target.`
+		};
+		configuration = own;
+	}
+	const report = {
+		configuration,
+		pairs: pairs.length,
+		criteria: scales.map((scale) => calibrateCriterion(scale, pairs)),
+		total: calibrateTotal(pairs)
+	};
+	return {
+		ok: true,
+		report: {
+			...report,
+			reportHash: contentHash(report)
+		}
+	};
+}
+//#endregion
 //#region src/grading.ts
 /**
 * Computes the weighted total from per-criterion scores — the arithmetic that
@@ -485,6 +885,260 @@ function hasGrade(outcome) {
 	return outcome.status === "scored" || outcome.status === "graded";
 }
 //#endregion
+//#region src/scoring/assisted/grade-from-judgement.ts
+/**
+* The grade a checked model judgement gives a written response: the total
+* computed as `gradeFromRubric` computes every grade — never by the model — with
+* the item's own weights and pass line, and the record a host keeps.
+*
+* Each criterion scores what `checkAiGrading` read: a level's place on its
+* scale, or the model's score from 0 to 1. The level chosen is kept as `band`,
+* its probabilities as `levelProbabilities`, and the model's identity as
+* `grader` (`kind: 'ai'`, with its `model` and `promptHash`), so a routing rule
+* and a calibration can read them later.
+*
+* `data` must be the item the request was built from: a judgement that names a
+* criterion this rubric does not have, or leaves one of its criteria out, is
+* `unscorable` rather than a grade on another task's rubric.
+*/
+function gradeFromJudgement(judgement, data, options = {}) {
+	const authored = data.rubric?.criteria ?? [];
+	const byName = new Map(authored.map((criterion) => [levelKey(criterion.name), criterion]));
+	if (byName.size !== authored.length) return {
+		unscorable: true,
+		reason: "This item's rubric names a criterion twice, so a judgement cannot say which of the two it grades."
+	};
+	const judged = /* @__PURE__ */ new Set();
+	const criteria = [];
+	for (const one of judgement.criteria) {
+		const criterion = byName.get(levelKey(one.name));
+		if (criterion === void 0 || judged.has(levelKey(one.name))) return {
+			unscorable: true,
+			reason: `The judgement names criterion "${one.name}", which this item's rubric does not have once. Grade it with the item it was asked about.`
+		};
+		judged.add(levelKey(one.name));
+		criteria.push({
+			name: criterion.name,
+			score: one.score,
+			weight: criterion.weight,
+			...one.level !== void 0 ? { band: one.level } : {},
+			...one.probabilities !== void 0 ? { levelProbabilities: [...one.probabilities] } : {},
+			...one.comment !== void 0 ? { comment: one.comment } : {}
+		});
+	}
+	const unjudged = authored.find((criterion) => !judged.has(levelKey(criterion.name)));
+	if (unjudged !== void 0) return {
+		unscorable: true,
+		reason: `The judgement leaves out criterion "${unjudged.name}". A total over fewer criteria would grade a different task.`
+	};
+	const grade = gradeFromRubric(criteria, data, {
+		...options,
+		feedback: judgement.feedback
+	});
+	if ("unscorable" in grade) return grade;
+	const { provenance, usage } = judgement;
+	return {
+		...grade,
+		...judgement.corrections.length > 0 ? { corrections: [...judgement.corrections] } : {},
+		...judgement.rationale !== void 0 ? { rationale: judgement.rationale } : {},
+		requiresHumanReview: judgement.requiresHumanReview,
+		grader: {
+			kind: "ai",
+			...provenance?.model !== void 0 ? { model: provenance.model } : {},
+			...provenance?.promptHash !== void 0 ? { promptHash: provenance.promptHash } : {}
+		},
+		...usage !== void 0 ? { usage } : {},
+		...provenance?.generatedAt !== void 0 ? { gradedAt: provenance.generatedAt } : {}
+	};
+}
+//#endregion
+//#region src/shuffle.ts
+/**
+* Seeded, deterministic shuffling — the ONE algorithm every presentation-order
+* decision in the SDK goes through: option order in a multiple-choice item,
+* item order inside an item group, entry order in a sequence. A server and a
+* client holding the same seed derive the same order, and an order recorded
+* against an attempt can be rebuilt later from nothing but its seed.
+*
+* STABILITY: the hash and the generator are part of the wire contract. A
+* stored attempt may hold only a seed and rely on this function to reproduce
+* the order it presented; changing either would silently re-order every
+* recorded attempt. Any change here is a package major, and the pinned
+* permutation test exists so an accidental one fails loudly.
+*/
+/** FNV-1a hash of a string → unsigned 32-bit integer. */
+function hashSeed(input) {
+	let h = 2166136261;
+	for (let i = 0; i < input.length; i += 1) {
+		h ^= input.charCodeAt(i);
+		h = Math.imul(h, 16777619) >>> 0;
+	}
+	return h;
+}
+/** LCG-driven Fisher–Yates over a 32-bit seed; returns a permutation (no loss, no duplicate). */
+function shuffleWithSeed(items, seed, version) {
+	const out = [...items];
+	let s = seed >>> 0 || 1;
+	for (let i = out.length - 1; i > 0; i -= 1) {
+		s = Math.imul(s, 1664525) + 1013904223 >>> 0;
+		const j = version === 2 ? Math.floor(s / 4294967296 * (i + 1)) : s % (i + 1);
+		[out[i], out[j]] = [out[j], out[i]];
+	}
+	return out;
+}
+function seededShuffle(items, seed, options = {}) {
+	return shuffleWithSeed(items, hashSeed(seed), options.version ?? 1);
+}
+//#endregion
+//#region src/scoring/assisted/routing.ts
+/** A threshold the caller configured: a finite number, and a rate within 0 to 1 where it is one. */
+function checkThreshold(name, value, rate) {
+	if (value === void 0) return;
+	if (typeof value !== "number" || !Number.isFinite(value) || rate && (value < 0 || value > 1)) throw new RangeError(`routeGrade: policy ${name} must be a finite number${rate ? " from 0 to 1" : ""}; got ${String(value)}.`);
+}
+function checkPolicy(policy) {
+	const thresholds = policy.calibration ?? {};
+	checkThreshold("calibration.minPairs", thresholds.minPairs, false);
+	checkThreshold("calibration.minQuadraticKappa", thresholds.minQuadraticKappa, false);
+	checkThreshold("calibration.minExactAgreement", thresholds.minExactAgreement, true);
+	checkThreshold("calibration.minPearson", thresholds.minPearson, false);
+	checkThreshold("calibration.maxMeanAbsoluteError", thresholds.maxMeanAbsoluteError, true);
+	checkThreshold("calibration.maxAbsStandardizedMeanDifference", thresholds.maxAbsStandardizedMeanDifference, false);
+	checkThreshold("calibration.maxDegradation", thresholds.maxDegradation, false);
+	checkThreshold("calibration.maxCalibrationError", thresholds.maxCalibrationError, true);
+	checkThreshold("minLevelProbability", policy.minLevelProbability, true);
+	if (policy.audit !== void 0) {
+		checkThreshold("audit.rate", policy.audit.rate, true);
+		if (typeof policy.audit.seed !== "string") throw new RangeError("routeGrade: policy audit.seed must be a string.");
+	}
+}
+function checkContext(context, policy) {
+	if (context.mode !== "exam" && context.mode !== "practice") throw new RangeError(`routeGrade: mode must be 'exam' or 'practice'; got ${String(context.mode)}.`);
+	if (policy.audit !== void 0 && typeof context.sampleKey !== "string") throw new RangeError("routeGrade: a policy with an audit needs a sampleKey, the response's stable identity.");
+}
+/** At least `min`, when there is a minimum; a missing value fails it. */
+const atLeast = (value, min) => min === void 0 || typeof value === "number" && value >= min;
+/** At most `max`, when there is a maximum; a missing value fails it. */
+const atMost = (value, max) => max === void 0 || typeof value === "number" && value <= max;
+const absolute = (value) => value === null ? null : Math.abs(value);
+function criterionMeets(criterion, t) {
+	const shared = atLeast(criterion.pairs, t.minPairs) && atMost(criterion.meanAbsoluteError, t.maxMeanAbsoluteError) && atMost(absolute(criterion.standardizedMeanDifference), t.maxAbsStandardizedMeanDifference) && atMost(criterion.degradation, t.maxDegradation);
+	if (criterion.scale === "score") return shared && atLeast(criterion.pearson, t.minPearson);
+	return shared && atLeast(criterion.quadraticKappa, t.minQuadraticKappa) && atLeast(criterion.exactAgreement, t.minExactAgreement) && (criterion.probabilityPairs === 0 || atMost(criterion.calibrationError, t.maxCalibrationError));
+}
+/** Whether a report meets every threshold, on every criterion and on the total. */
+function reportMeets(report, t) {
+	const total = report.total;
+	return report.criteria.every((criterion) => criterionMeets(criterion, t)) && atLeast(total.pairs, t.minPairs) && atLeast(total.pearson, t.minPearson) && atMost(total.meanAbsoluteError, t.maxMeanAbsoluteError) && atMost(absolute(total.standardizedMeanDifference), t.maxAbsStandardizedMeanDifference) && atMost(total.degradation, t.maxDegradation);
+}
+/**
+* Whether a criterion judged on levels is less sure than `minimum`: the
+* grader gave its chosen level a lower probability, or the grade has no
+* distribution over the levels to read, or no level at all. A rubric whose
+* levels cannot be read is unsure throughout.
+*/
+function isUnsure(grade, item, minimum) {
+	const read = rubricScales(item.rubric);
+	if (!read.ok) return true;
+	return read.scales.some((scale) => {
+		const judged = criterionOf(grade, scale.name);
+		if (scale.levels === null || judged?.notApplicable === true) return false;
+		const level = judged === void 0 ? null : levelOf(judged, scale.levels);
+		return level === null || level.probabilities === null || level.probabilities[level.level] < minimum;
+	});
+}
+/**
+* Murmur3's 32-bit finaliser, so every bit of the hash moves every bit of the
+* result. FNV-1a alone barely moves its high bits for a change in a key's last
+* characters, and the sample reads the high bits: `attempt-1:slot-1` and
+* `attempt-1:slot-2` were drawn together 97 times in 100 at a rate of 0.25.
+*/
+function avalanche(hash) {
+	let mixed = hash ^ hash >>> 16;
+	mixed = Math.imul(mixed, 2246822507);
+	mixed ^= mixed >>> 13;
+	mixed = Math.imul(mixed, 3266489909);
+	mixed ^= mixed >>> 16;
+	return mixed >>> 0;
+}
+/**
+* Whether `key` is in the audit sample: a stable share `rate` of keys, chosen
+* by a hash of the seed and the key, so the same response is always in or
+* always out, two responses are drawn independently even when their keys
+* differ by one character, and changing the seed draws a new sample.
+*/
+function inAuditSample(key, rate, seed) {
+	checkThreshold("audit.rate", rate, true);
+	if (typeof key !== "string" || typeof seed !== "string") throw new RangeError("inAuditSample: the key and the seed must be strings.");
+	return avalanche(hashSeed(`${seed}\u0000${key}`)) / 2 ** 32 < rate;
+}
+/**
+* Where a model's grade goes: to count, or to a person first. Deterministic —
+* the same grade, context and policy always route the same way — and the
+* decision says every reason it rests on, in {@link GradeRoutingReason}'s
+* order, so an appeal can see why a person did or did not mark a response.
+*
+* - **In `exam`, a grade needs a calibration of its exact configuration**
+*   (`no-calibration`): the model and prompt its `grader` names, and the
+*   item's rubric and target. Fail closed: without a matching report, every
+*   grade goes to a person.
+* - A supplied report must meet the policy's thresholds (`calibration-below-policy`).
+* - A criterion on levels the grader was less sure of than
+*   `minLevelProbability`, or showed no probabilities for (`unsure`), a
+*   grader that asked for review (`model-asked`), a `low` confidence where
+*   the policy routes on it (`low-confidence`), and the audit sample
+*   (`audit-sample`) send it to a person too.
+*
+* A mode other than `exam` or `practice`, a policy threshold that is not a
+* finite number, a rate outside 0 to 1, or an audit without a `sampleKey`
+* throws a `RangeError`: it is the caller's configuration, not the grade's,
+* and a typo must not quietly make an exam a practice.
+*/
+function routeGrade(grade, context) {
+	const policy = context.policy ?? {};
+	checkPolicy(policy);
+	checkContext(context, policy);
+	const reasons = [];
+	const own = graderConfiguration(grade, context.item);
+	const report = context.calibration;
+	const matching = report !== void 0 && own !== null && sameConfiguration(own, report.configuration) ? report : void 0;
+	if (context.mode === "exam" && matching === void 0) reasons.push("no-calibration");
+	if (matching !== void 0 && !reportMeets(matching, policy.calibration ?? {})) reasons.push("calibration-below-policy");
+	const minimum = policy.minLevelProbability;
+	if (minimum !== void 0 && isUnsure(grade, context.item, minimum)) reasons.push("unsure");
+	if (grade.requiresHumanReview === true) reasons.push("model-asked");
+	if (policy.routeLowConfidence === true && grade.confidence === "low") reasons.push("low-confidence");
+	if (policy.audit !== void 0 && inAuditSample(context.sampleKey, policy.audit.rate, policy.audit.seed)) reasons.push("audit-sample");
+	return {
+		to: reasons.length === 0 ? "model" : "person",
+		reasons,
+		...matching !== void 0 ? { calibration: {
+			reportHash: matching.reportHash,
+			pairs: matching.pairs
+		} } : {}
+	};
+}
+/**
+* The outcome a routed grade gives its slot. To the model: the grade, with the
+* decision on its `routing`, lifted as `outcomeFromGrade` lifts any grade. To a
+* person: `{ status: 'deferred', reason: 'awaiting_human_review', pendingGrade }`
+* — not `graded`, so its `passed` is never read as a verdict, and a composed
+* attempt stays `provisional` until a person's grade replaces it.
+*/
+function outcomeFromRoutedGrade(grade, routing) {
+	const routed = {
+		...grade,
+		routing
+	};
+	if (routing.to === "model") return outcomeFromGrade(routed);
+	return {
+		status: "deferred",
+		reason: "awaiting_human_review",
+		maxScore: 1,
+		pendingGrade: routed
+	};
+}
+//#endregion
 //#region src/scoring/compose.ts
 function earned(item) {
 	const { outcome } = item;
@@ -1599,6 +2253,6 @@ function costed(data, opening, graded, rules, rounding) {
 	};
 }
 //#endregion
-export { validateItemScoringPolicy as C, scoreTries as S, gte as _, inspectWav as a, ITEM_SCORING_MAX_RETRIES as b, validateSpeechAssessment as c, gradeFromRubric as d, hasGrade as f, classifyBand as g, computePassThreshold as h, outcomeFromUnscorable as i, diffDictationChars as l, DEFAULT_PASS_THRESHOLD as m, evaluateTries as n, gradeReadAloud as o, outcomeFromGrade as p, score as r, alignReadAloud as s, evaluate as t, composeAssessmentScore as u, roundGrade as v, isGradeInRange as w, resolveItemScoringPolicy as x, DEFAULT_ITEM_SCORING_POLICY as y };
+export { DEFAULT_ITEM_SCORING_POLICY as A, contentHash as C, classifyBand as D, computePassThreshold as E, isGradeInRange as F, resolveItemScoringPolicy as M, scoreTries as N, gte as O, validateItemScoringPolicy as P, canonicalJson as S, DEFAULT_PASS_THRESHOLD as T, gradeFromRubric as _, inspectWav as a, calibrationReport as b, validateSpeechAssessment as c, inAuditSample as d, outcomeFromRoutedGrade as f, gradeFromJudgement as g, seededShuffle as h, outcomeFromUnscorable as i, ITEM_SCORING_MAX_RETRIES as j, roundGrade as k, diffDictationChars as l, hashSeed as m, evaluateTries as n, gradeReadAloud as o, routeGrade as p, score as r, alignReadAloud as s, evaluate as t, composeAssessmentScore as u, hasGrade as v, fingerprint as w, graderConfiguration as x, outcomeFromGrade as y };
 
-//# sourceMappingURL=scoring-BZqUkuDF.js.map
+//# sourceMappingURL=scoring-BKNNTz-s.js.map