@intellectif/lk-core 1.3.0 → 1.5.0

package/dist/{scoring-B2_HEhMT.cjs → scoring-lKQVYsxy.cjs}

@@ -1,4 +1,4 @@
-const require_registry = require("./registry-DVi0LR_i.cjs");
+const require_registry = require("./registry-Ce00A_OW.cjs");
 let zod_v4 = require("zod/v4");
 zod_v4 = require_registry.__toESM(zod_v4, 1);
 //#region src/scoring/grade-numbers.ts
@@ -359,6 +359,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 = require_registry.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) => require_registry.levelKey(one.name) === require_registry.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) => require_registry.levelKey(one.label) === require_registry.levelKey(band)) : -1;
+	if (level === -1) return null;
+	const probabilities = judged.levelProbabilities;
+	return {
+		level,
+		probabilities: Array.isArray(probabilities) ? require_registry.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
@@ -486,6 +886,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) => [require_registry.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(require_registry.levelKey(one.name));
+		if (criterion === void 0 || judged.has(require_registry.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(require_registry.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(require_registry.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;
@@ -1624,6 +2278,18 @@ Object.defineProperty(exports, "alignReadAloud", {
 		return alignReadAloud;
 	}
 });
+Object.defineProperty(exports, "calibrationReport", {
+	enumerable: true,
+	get: function() {
+		return calibrationReport;
+	}
+});
+Object.defineProperty(exports, "canonicalJson", {
+	enumerable: true,
+	get: function() {
+		return canonicalJson;
+	}
+});
 Object.defineProperty(exports, "classifyBand", {
 	enumerable: true,
 	get: function() {
@@ -1642,6 +2308,12 @@ Object.defineProperty(exports, "computePassThreshold", {
 		return computePassThreshold;
 	}
 });
+Object.defineProperty(exports, "contentHash", {
+	enumerable: true,
+	get: function() {
+		return contentHash;
+	}
+});
 Object.defineProperty(exports, "diffDictationChars", {
 	enumerable: true,
 	get: function() {
@@ -1660,6 +2332,18 @@ Object.defineProperty(exports, "evaluateTries", {
 		return evaluateTries;
 	}
 });
+Object.defineProperty(exports, "fingerprint", {
+	enumerable: true,
+	get: function() {
+		return fingerprint;
+	}
+});
+Object.defineProperty(exports, "gradeFromJudgement", {
+	enumerable: true,
+	get: function() {
+		return gradeFromJudgement;
+	}
+});
 Object.defineProperty(exports, "gradeFromRubric", {
 	enumerable: true,
 	get: function() {
@@ -1672,6 +2356,12 @@ Object.defineProperty(exports, "gradeReadAloud", {
 		return gradeReadAloud;
 	}
 });
+Object.defineProperty(exports, "graderConfiguration", {
+	enumerable: true,
+	get: function() {
+		return graderConfiguration;
+	}
+});
 Object.defineProperty(exports, "gte", {
 	enumerable: true,
 	get: function() {
@@ -1684,6 +2374,18 @@ Object.defineProperty(exports, "hasGrade", {
 		return hasGrade;
 	}
 });
+Object.defineProperty(exports, "hashSeed", {
+	enumerable: true,
+	get: function() {
+		return hashSeed;
+	}
+});
+Object.defineProperty(exports, "inAuditSample", {
+	enumerable: true,
+	get: function() {
+		return inAuditSample;
+	}
+});
 Object.defineProperty(exports, "inspectWav", {
 	enumerable: true,
 	get: function() {
@@ -1702,6 +2404,12 @@ Object.defineProperty(exports, "outcomeFromGrade", {
 		return outcomeFromGrade;
 	}
 });
+Object.defineProperty(exports, "outcomeFromRoutedGrade", {
+	enumerable: true,
+	get: function() {
+		return outcomeFromRoutedGrade;
+	}
+});
 Object.defineProperty(exports, "outcomeFromUnscorable", {
 	enumerable: true,
 	get: function() {
@@ -1720,6 +2428,12 @@ Object.defineProperty(exports, "roundGrade", {
 		return roundGrade;
 	}
 });
+Object.defineProperty(exports, "routeGrade", {
+	enumerable: true,
+	get: function() {
+		return routeGrade;
+	}
+});
 Object.defineProperty(exports, "score", {
 	enumerable: true,
 	get: function() {
@@ -1732,6 +2446,12 @@ Object.defineProperty(exports, "scoreTries", {
 		return scoreTries;
 	}
 });
+Object.defineProperty(exports, "seededShuffle", {
+	enumerable: true,
+	get: function() {
+		return seededShuffle;
+	}
+});
 Object.defineProperty(exports, "validateItemScoringPolicy", {
 	enumerable: true,
 	get: function() {
@@ -1745,4 +2465,4 @@ Object.defineProperty(exports, "validateSpeechAssessment", {
 	}
 });
 
-//# sourceMappingURL=scoring-B2_HEhMT.cjs.map
+//# sourceMappingURL=scoring-lKQVYsxy.cjs.map