@intellectif/lk-core 0.17.0 → 0.19.0

package/dist/chunk-BIJCO2HM.js

@@ -0,0 +1,443 @@
+import {
+  isGradeInRange,
+  score
+} from "./chunk-MMEQKFFQ.js";
+import {
+  PLACEHOLDER_RE,
+  alignDictation
+} from "./chunk-D3GP5MET.js";
+
+// src/ai.ts
+var AI_EXPLANATION_TYPES = [
+  "multiple-choice",
+  "fill-in-the-blanks",
+  "gap-select",
+  "dictation"
+];
+var AI_HINT_TYPES = [
+  "multiple-choice",
+  "fill-in-the-blanks",
+  "gap-select"
+];
+var AI_TEXT_MAX_LENGTH = 2e3;
+function aiSupports(activityType, feature) {
+  const types = feature === "hint" ? AI_HINT_TYPES : AI_EXPLANATION_TYPES;
+  return types.includes(activityType);
+}
+function aiAllowedByContent(data, feature) {
+  const permissions = data.ai;
+  if (typeof permissions !== "object" || permissions === null) {
+    return true;
+  }
+  const key = feature === "hint" ? "hints" : "explanations";
+  return permissions[key] !== false;
+}
+function aiGradeOf(result) {
+  const ratio = result.maxScore > 0 ? result.score / result.maxScore : 0;
+  let category = "partly-correct";
+  if (ratio >= 1 - 1e-9) {
+    category = "correct";
+  } else if (ratio <= 1e-9) {
+    category = "incorrect";
+  }
+  return { score: result.score, maxScore: result.maxScore, passed: result.passed, category };
+}
+function placeholderOrder(passage) {
+  return [...passage.matchAll(PLACEHOLDER_RE)].map((match) => match[1]);
+}
+function numberedPassage(passage) {
+  let position = 0;
+  return passage.replace(PLACEHOLDER_RE, () => {
+    position += 1;
+    return `[${position}]`;
+  });
+}
+function isAnswerOption(detail, chosen) {
+  switch (detail.outcome) {
+    case "correct":
+    case "incorrect-omission":
+      return true;
+    case "incorrect":
+    case "correct-omission":
+      return false;
+    default:
+      return chosen ? detail.correct : !detail.correct;
+  }
+}
+var firstString = (value) => Array.isArray(value) ? value[0] : value;
+var listOf = (value) => value === void 0 ? null : Array.isArray(value) ? [...value] : [value];
+function emptyResponse(type) {
+  switch (type) {
+    case "multiple-choice":
+      return { type: "multiple-choice", selectedOptionIds: [] };
+    case "fill-in-the-blanks":
+      return { type: "fill-in-the-blanks", answers: {} };
+    case "gap-select":
+      return { type: "gap-select", selections: {} };
+    case "dictation":
+      return { type: "dictation", text: "" };
+    default:
+      return null;
+  }
+}
+var base = (data) => ({
+  activityId: data.id,
+  title: data.title,
+  ...typeof data.locale === "string" ? { locale: data.locale } : {}
+});
+function buildAiFacts(data, response, details) {
+  const byId = new Map((details ?? []).map((detail) => [detail.itemId, detail]));
+  const full = data.redacted !== true;
+  switch (data.type) {
+    case "multiple-choice": {
+      const item = data;
+      const chosen = new Set(
+        response?.type === "multiple-choice" ? response.selectedOptionIds : []
+      );
+      return {
+        ...base(data),
+        activityType: "multiple-choice",
+        question: item.question,
+        mode: item.mode,
+        options: item.options.map((option) => {
+          const detail = byId.get(option.id);
+          const wasChosen = chosen.has(option.id);
+          let correct = null;
+          if (full && typeof option.isCorrect === "boolean") {
+            correct = option.isCorrect;
+          } else if (detail !== void 0) {
+            correct = isAnswerOption(detail, wasChosen);
+          }
+          return {
+            id: option.id,
+            text: option.text,
+            chosen: wasChosen,
+            correct,
+            ...typeof option.feedback === "string" ? { feedback: option.feedback } : {}
+          };
+        })
+      };
+    }
+    case "fill-in-the-blanks": {
+      const item = data;
+      const answers = response?.type === "fill-in-the-blanks" ? response.answers : {};
+      const blanks = new Map(item.blanks.map((blank) => [blank.id, blank]));
+      return {
+        ...base(data),
+        activityType: "fill-in-the-blanks",
+        passage: numberedPassage(item.passage),
+        blanks: placeholderOrder(item.passage).map((id, index) => {
+          const blank = blanks.get(id);
+          const detail = byId.get(id);
+          const accepted = full && Array.isArray(blank?.acceptedAnswers) ? [...blank.acceptedAnswers] : listOf(detail?.correctResponse);
+          return {
+            id,
+            position: index + 1,
+            typed: typeof answers[id] === "string" ? answers[id] : "",
+            accepted,
+            correct: detail === void 0 ? null : detail.correct,
+            ...typeof blank?.hint === "string" ? { hint: blank.hint } : {},
+            ...typeof blank?.feedback === "string" ? { feedback: blank.feedback } : {}
+          };
+        })
+      };
+    }
+    case "gap-select": {
+      const item = data;
+      const selections = response?.type === "gap-select" ? response.selections : {};
+      const gaps = new Map(item.gaps.map((gap) => [gap.id, gap]));
+      const banks = new Map((item.banks ?? []).map((bank) => [bank.id, bank]));
+      return {
+        ...base(data),
+        activityType: "gap-select",
+        passage: numberedPassage(item.passage),
+        gaps: placeholderOrder(item.passage).map((id, index) => {
+          const gap = gaps.get(id);
+          const choices = gap?.choices ?? (gap?.bankId === void 0 ? [] : banks.get(gap.bankId)?.choices ?? []);
+          const textOf = (choiceId) => choiceId === void 0 ? null : choices.find((choice) => choice.id === choiceId)?.text ?? null;
+          const detail = byId.get(id);
+          const answerId = full && typeof gap?.correctChoiceId === "string" ? gap.correctChoiceId : firstString(detail?.correctResponse);
+          return {
+            id,
+            position: index + 1,
+            choices: choices.map((choice) => choice.text),
+            chosen: textOf(selections[id]),
+            answer: textOf(answerId),
+            correct: detail === void 0 ? null : detail.correct,
+            ...typeof gap?.feedback === "string" ? { feedback: gap.feedback } : {}
+          };
+        })
+      };
+    }
+    case "dictation": {
+      const item = data;
+      const typed = response?.type === "dictation" ? response.text : "";
+      const hasKey = full && typeof item.transcript === "string";
+      let words = null;
+      if (hasKey) {
+        words = alignDictation(item, typed).words.map((word) => ({
+          expected: word.reference,
+          typed: word.attempt,
+          status: word.status
+        }));
+      } else if (details !== null && details.length > 0) {
+        words = details.map((detail) => {
+          const expected = firstString(detail.correctResponse) ?? "";
+          const attempt = firstString(detail.learnerResponse) ?? "";
+          let status = "incorrect";
+          if (detail.correct) {
+            status = "correct";
+          } else if (attempt === "") {
+            status = "missing";
+          } else if (expected === "") {
+            status = "extra";
+          }
+          return { expected, typed: attempt, status };
+        });
+      }
+      return {
+        ...base(data),
+        activityType: "dictation",
+        transcript: hasKey ? item.transcript : null,
+        typed,
+        words
+      };
+    }
+    default:
+      return null;
+  }
+}
+function gradeLocally(data, response) {
+  if (data.redacted === true) {
+    return null;
+  }
+  try {
+    const result = score(data.type, data, response);
+    return { details: result.details, grade: aiGradeOf(result) };
+  } catch {
+    return null;
+  }
+}
+function aiExplanationRequest(input) {
+  const { data, response, outcome, learnerLocale } = input;
+  if (!aiSupports(data.type, "explanation") || !aiAllowedByContent(data, "explanation")) {
+    return null;
+  }
+  let details = null;
+  let grade = null;
+  if (outcome?.status === "scored") {
+    const { score: recorded, maxScore, passed } = outcome;
+    if (!isGradeInRange(recorded, maxScore)) {
+      return null;
+    }
+    details = outcome.details;
+    grade = aiGradeOf({ score: recorded, maxScore, passed });
+  } else if (response !== null) {
+    const local = gradeLocally(data, response);
+    if (local !== null) {
+      details = local.details;
+      grade = local.grade;
+    }
+  }
+  if (grade === null) {
+    return null;
+  }
+  const facts = buildAiFacts(data, response, details);
+  if (facts === null) {
+    return null;
+  }
+  return {
+    feature: "explanation",
+    facts,
+    grade,
+    ...learnerLocale !== void 0 ? { learnerLocale } : {}
+  };
+}
+function aiHintRequest(input) {
+  const { data, previousHints, learnerLocale } = input;
+  if (!aiSupports(data.type, "hint") || !aiAllowedByContent(data, "hint") || data.redacted === true) {
+    return null;
+  }
+  const response = input.response ?? emptyResponse(data.type);
+  const local = response === null ? null : gradeLocally(data, response);
+  const facts = buildAiFacts(data, response, local?.details ?? null);
+  if (facts === null) {
+    return null;
+  }
+  return {
+    feature: "hint",
+    facts,
+    hintNumber: previousHints.length + 1,
+    previousHints: [...previousHints],
+    ...learnerLocale !== void 0 ? { learnerLocale } : {}
+  };
+}
+var VERDICTS = ["correct", "partly-correct", "incorrect"];
+function provenanceOf(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return void 0;
+  }
+  const kept = {};
+  for (const key of ["model", "promptHash", "generatedAt"]) {
+    const value = raw[key];
+    if (typeof value === "string" && value.length > 0 && value.length <= 200) {
+      kept[key] = value;
+    }
+  }
+  return Object.keys(kept).length > 0 ? kept : void 0;
+}
+function usageOf(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return void 0;
+  }
+  const kept = {};
+  for (const key of ["promptTokens", "completionTokens", "costUsd"]) {
+    const value = raw[key];
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+      kept[key] = value;
+    }
+  }
+  return Object.keys(kept).length > 0 ? kept : void 0;
+}
+function cleanText(text) {
+  return text.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u2028\u2029]/g, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+function readAiTextResult(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, refusal: "malformed" };
+  }
+  const record = raw;
+  if (typeof record.text !== "string") {
+    return { ok: false, refusal: "malformed" };
+  }
+  if (record.verdict !== void 0 && !VERDICTS.includes(record.verdict)) {
+    return { ok: false, refusal: "malformed" };
+  }
+  const text = cleanText(record.text);
+  if (text === "") {
+    return { ok: false, refusal: "empty" };
+  }
+  if ([...text].length > AI_TEXT_MAX_LENGTH) {
+    return { ok: false, refusal: "too-long" };
+  }
+  const provenance = provenanceOf(record.provenance);
+  const usage = usageOf(record.usage);
+  return {
+    ok: true,
+    result: {
+      text,
+      ...record.verdict !== void 0 ? { verdict: record.verdict } : {},
+      ...provenance !== void 0 ? { provenance } : {},
+      ...usage !== void 0 ? { usage } : {}
+    }
+  };
+}
+function checkAiExplanation(raw, request) {
+  const read = readAiTextResult(raw);
+  if (!read.ok) {
+    return read;
+  }
+  if (read.result.verdict !== void 0 && read.result.verdict !== request.grade.category) {
+    return { ok: false, refusal: "contradicts-grade" };
+  }
+  return read;
+}
+function checkAiHint(raw, request) {
+  const read = readAiTextResult(raw);
+  if (!read.ok) {
+    return read;
+  }
+  if (hintRevealsAnswer(request.facts, read.result.text)) {
+    return { ok: false, refusal: "reveals-answer" };
+  }
+  return read;
+}
+function fold(text) {
+  const folded = text.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+  return folded === "" ? [] : folded.split(" ");
+}
+function containsWords(haystack, needle) {
+  if (needle.length === 0 || needle.length > haystack.length) {
+    return false;
+  }
+  for (let start = 0; start + needle.length <= haystack.length; start += 1) {
+    let match = true;
+    for (let offset = 0; offset < needle.length; offset += 1) {
+      if (haystack[start + offset] !== needle[offset]) {
+        match = false;
+        break;
+      }
+    }
+    if (match) {
+      return true;
+    }
+  }
+  return false;
+}
+var isShort = (words) => words.length === 1 && [...words[0]].length < 4;
+function neighbours(passage, position) {
+  const marker = `[${position}]`;
+  const at = passage.indexOf(marker);
+  if (at === -1) {
+    return {};
+  }
+  const strip = (text) => text.replace(/\[\d+\]/g, " ");
+  const left = fold(strip(passage.slice(0, at)));
+  const right = fold(strip(passage.slice(at + marker.length)));
+  const before = left[left.length - 1];
+  const after = right[0];
+  return {
+    ...before !== void 0 ? { before } : {},
+    ...after !== void 0 ? { after } : {}
+  };
+}
+function hintRevealsAnswer(facts, hint) {
+  const words = fold(hint);
+  const reveals = (answer, passage, position) => {
+    const needle = fold(answer);
+    if (needle.length === 0) {
+      return false;
+    }
+    if (!isShort(needle) || passage === void 0 || position === void 0) {
+      return containsWords(words, needle);
+    }
+    const { before, after } = neighbours(passage, position);
+    if (before === void 0 && after === void 0) {
+      return containsWords(words, needle);
+    }
+    return before !== void 0 && containsWords(words, [before, ...needle]) || after !== void 0 && containsWords(words, [...needle, after]);
+  };
+  switch (facts.activityType) {
+    case "multiple-choice":
+      return facts.options.some((option) => option.correct === true && reveals(option.text));
+    case "fill-in-the-blanks":
+      return facts.blanks.some(
+        (blank) => (blank.accepted ?? []).some((answer) => reveals(answer, facts.passage, blank.position))
+      );
+    case "gap-select":
+      return facts.gaps.some(
+        (gap) => gap.answer !== null && reveals(gap.answer, facts.passage, gap.position)
+      );
+    case "dictation":
+      return false;
+    default:
+      return false;
+  }
+}
+
+export {
+  AI_EXPLANATION_TYPES,
+  AI_HINT_TYPES,
+  AI_TEXT_MAX_LENGTH,
+  aiSupports,
+  aiAllowedByContent,
+  aiGradeOf,
+  buildAiFacts,
+  aiExplanationRequest,
+  aiHintRequest,
+  readAiTextResult,
+  checkAiExplanation,
+  checkAiHint,
+  hintRevealsAnswer
+};
+//# sourceMappingURL=chunk-BIJCO2HM.js.map

package/dist/chunk-BIJCO2HM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ai.ts"],"sourcesContent":["import { PLACEHOLDER_RE } from './schemas/fill-in-the-blanks.js';\nimport { alignDictation } from './scoring/dictation/align.js';\nimport { isGradeInRange } from './scoring/grade-numbers.js';\nimport { score } from './scoring/index.js';\nimport type {\n  ActivityData,\n  DictationData,\n  FillInTheBlanksData,\n  GapSelectData,\n  ItemOutcome,\n  LearnerResponse,\n  MultipleChoiceData,\n  ScoringDetail,\n} from './types/activity.js';\nimport type {\n  AiActivityInput,\n  AiExplanationRequest,\n  AiFeature,\n  AiGrade,\n  AiHintRequest,\n  AiItemFacts,\n  AiProvenance,\n  AiRefusal,\n  AiSupportedActivityType,\n  AiTextResult,\n  AiVerdict,\n  AiWordFact,\n} from './types/ai.js';\nimport type { GraderUsage } from './types/grading.js';\n\n/**\n * The activity types the SDK builds facts for, and which of them take hints.\n * A dictation takes none: its answer is the whole sentence, and it has\n * word-by-word hints of its own.\n */\nexport const AI_EXPLANATION_TYPES: readonly AiSupportedActivityType[] = [\n  'multiple-choice',\n  'fill-in-the-blanks',\n  'gap-select',\n  'dictation',\n];\nexport const AI_HINT_TYPES: readonly AiSupportedActivityType[] = [\n  'multiple-choice',\n  'fill-in-the-blanks',\n  'gap-select',\n];\n\n/** The longest AI text shown, in code points. Longer is refused, not cut. */\nexport const AI_TEXT_MAX_LENGTH = 2000;\n\n/**\n * Whether the SDK supports `feature` for this activity type. A type it builds\n * no facts for — a written response, a read-aloud, a consumer's own — has\n * neither.\n */\nexport function aiSupports(activityType: string, feature: AiFeature): boolean {\n  const types = feature === 'hint' ? AI_HINT_TYPES : AI_EXPLANATION_TYPES;\n  return (types as readonly string[]).includes(activityType);\n}\n\n/**\n * Whether the item's author allows `feature`. Only an explicit `false`\n * switches it off: an author can refuse a feature, never force one on.\n */\nexport function aiAllowedByContent(data: AiActivityInput, feature: AiFeature): boolean {\n  const permissions = (data as { ai?: unknown }).ai;\n  if (typeof permissions !== 'object' || permissions === null) {\n    return true;\n  }\n  const key = feature === 'hint' ? 'hints' : 'explanations';\n  return (permissions as Record<string, unknown>)[key] !== false;\n}\n\n/** A grade as an explanation must speak to it: all marks, some, or none. */\nexport function aiGradeOf(result: { score: number; maxScore: number; passed: boolean }): AiGrade {\n  const ratio = result.maxScore > 0 ? result.score / result.maxScore : 0;\n  let category: AiVerdict = 'partly-correct';\n  if (ratio >= 1 - 1e-9) {\n    category = 'correct';\n  } else if (ratio <= 1e-9) {\n    category = 'incorrect';\n  }\n  return { score: result.score, maxScore: result.maxScore, passed: result.passed, category };\n}\n\n// ── Facts ──────────────────────────────────────────────────────────────\n\n/**\n * The ids of a passage's placeholders, in the order they appear. Read with the\n * schema's own expression, so a passage means here what it means to validation.\n */\nfunction placeholderOrder(passage: string): string[] {\n  return [...passage.matchAll(PLACEHOLDER_RE)].map((match) => match[1] as string);\n}\n\n/** The passage with each placeholder written as `[n]`, in passage order. */\nfunction numberedPassage(passage: string): string {\n  let position = 0;\n  return passage.replace(PLACEHOLDER_RE, () => {\n    position += 1;\n    return `[${position}]`;\n  });\n}\n\n/** Whether an option is part of the answer, read from a server's detail (as the renderer reads it). */\nfunction isAnswerOption(detail: ScoringDetail, chosen: boolean): boolean {\n  switch (detail.outcome) {\n    case 'correct':\n    case 'incorrect-omission':\n      return true;\n    case 'incorrect':\n    case 'correct-omission':\n      return false;\n    default:\n      return chosen ? detail.correct : !detail.correct;\n  }\n}\n\nconst firstString = (value: string | string[] | undefined): string | undefined =>\n  Array.isArray(value) ? value[0] : value;\n\nconst listOf = (value: string | string[] | undefined): string[] | null =>\n  value === undefined ? null : Array.isArray(value) ? [...value] : [value];\n\n/** The response a learner has before touching anything. */\nfunction emptyResponse(type: string): LearnerResponse | null {\n  switch (type) {\n    case 'multiple-choice':\n      return { type: 'multiple-choice', selectedOptionIds: [] };\n    case 'fill-in-the-blanks':\n      return { type: 'fill-in-the-blanks', answers: {} };\n    case 'gap-select':\n      return { type: 'gap-select', selections: {} };\n    case 'dictation':\n      return { type: 'dictation', text: '' };\n    default:\n      return null;\n  }\n}\n\nconst base = (data: AiActivityInput) => ({\n  activityId: data.id,\n  title: data.title,\n  ...(typeof data.locale === 'string' ? { locale: data.locale } : {}),\n});\n\n/**\n * The facts a model is given about one item and one answer. `details` are the\n * SDK's per-part verdicts — from its own scorer, or from a server's outcome in\n * review — and every `correct` is `null` without them. A redacted item yields\n * facts without a key, which is what the learner's side holds; a port that\n * needs the key loads the item on its server.\n *\n * `null` for a type the SDK builds no facts for.\n */\nexport function buildAiFacts(\n  data: AiActivityInput,\n  response: LearnerResponse | null,\n  details: readonly ScoringDetail[] | null,\n): AiItemFacts | null {\n  const byId = new Map((details ?? []).map((detail) => [detail.itemId, detail]));\n  const full = (data as { redacted?: unknown }).redacted !== true;\n  switch (data.type) {\n    case 'multiple-choice': {\n      const item = data as unknown as MultipleChoiceData;\n      const chosen = new Set(\n        response?.type === 'multiple-choice' ? response.selectedOptionIds : [],\n      );\n      return {\n        ...base(data),\n        activityType: 'multiple-choice',\n        question: item.question,\n        mode: item.mode,\n        options: item.options.map((option) => {\n          const detail = byId.get(option.id);\n          const wasChosen = chosen.has(option.id);\n          let correct: boolean | null = null;\n          if (full && typeof option.isCorrect === 'boolean') {\n            correct = option.isCorrect;\n          } else if (detail !== undefined) {\n            correct = isAnswerOption(detail, wasChosen);\n          }\n          return {\n            id: option.id,\n            text: option.text,\n            chosen: wasChosen,\n            correct,\n            ...(typeof option.feedback === 'string' ? { feedback: option.feedback } : {}),\n          };\n        }),\n      };\n    }\n    case 'fill-in-the-blanks': {\n      const item = data as unknown as FillInTheBlanksData;\n      const answers = response?.type === 'fill-in-the-blanks' ? response.answers : {};\n      const blanks = new Map(item.blanks.map((blank) => [blank.id, blank]));\n      return {\n        ...base(data),\n        activityType: 'fill-in-the-blanks',\n        passage: numberedPassage(item.passage),\n        blanks: placeholderOrder(item.passage).map((id, index) => {\n          const blank = blanks.get(id);\n          const detail = byId.get(id);\n          const accepted =\n            full && Array.isArray(blank?.acceptedAnswers)\n              ? [...blank.acceptedAnswers]\n              : listOf(detail?.correctResponse);\n          return {\n            id,\n            position: index + 1,\n            typed: typeof answers[id] === 'string' ? (answers[id] as string) : '',\n            accepted,\n            correct: detail === undefined ? null : detail.correct,\n            ...(typeof blank?.hint === 'string' ? { hint: blank.hint } : {}),\n            ...(typeof blank?.feedback === 'string' ? { feedback: blank.feedback } : {}),\n          };\n        }),\n      };\n    }\n    case 'gap-select': {\n      const item = data as unknown as GapSelectData;\n      const selections = response?.type === 'gap-select' ? response.selections : {};\n      const gaps = new Map(item.gaps.map((gap) => [gap.id, gap]));\n      const banks = new Map((item.banks ?? []).map((bank) => [bank.id, bank]));\n      return {\n        ...base(data),\n        activityType: 'gap-select',\n        passage: numberedPassage(item.passage),\n        gaps: placeholderOrder(item.passage).map((id, index) => {\n          const gap = gaps.get(id);\n          const choices =\n            gap?.choices ??\n            (gap?.bankId === undefined ? [] : (banks.get(gap.bankId)?.choices ?? []));\n          const textOf = (choiceId: string | undefined): string | null =>\n            choiceId === undefined\n              ? null\n              : (choices.find((choice) => choice.id === choiceId)?.text ?? null);\n          const detail = byId.get(id);\n          const answerId =\n            full && typeof gap?.correctChoiceId === 'string'\n              ? gap.correctChoiceId\n              : firstString(detail?.correctResponse);\n          return {\n            id,\n            position: index + 1,\n            choices: choices.map((choice) => choice.text),\n            chosen: textOf(selections[id]),\n            answer: textOf(answerId),\n            correct: detail === undefined ? null : detail.correct,\n            ...(typeof gap?.feedback === 'string' ? { feedback: gap.feedback } : {}),\n          };\n        }),\n      };\n    }\n    case 'dictation': {\n      const item = data as unknown as DictationData;\n      const typed = response?.type === 'dictation' ? response.text : '';\n      const hasKey = full && typeof item.transcript === 'string';\n      let words: AiWordFact[] | null = null;\n      if (hasKey) {\n        words = alignDictation(item, typed).words.map((word) => ({\n          expected: word.reference,\n          typed: word.attempt,\n          status: word.status,\n        }));\n      } else if (details !== null && details.length > 0) {\n        words = details.map((detail) => {\n          const expected = firstString(detail.correctResponse) ?? '';\n          const attempt = firstString(detail.learnerResponse) ?? '';\n          let status: 'correct' | 'incorrect' | 'missing' | 'extra' = 'incorrect';\n          if (detail.correct) {\n            status = 'correct';\n          } else if (attempt === '') {\n            status = 'missing';\n          } else if (expected === '') {\n            status = 'extra';\n          }\n          return { expected, typed: attempt, status };\n        });\n      }\n      return {\n        ...base(data),\n        activityType: 'dictation',\n        transcript: hasKey ? item.transcript : null,\n        typed,\n        words,\n      };\n    }\n    default:\n      return null;\n  }\n}\n\n/** The SDK's own grade of `response`, with its per-part details; `null` when it cannot grade. */\nfunction gradeLocally(\n  data: AiActivityInput,\n  response: LearnerResponse,\n): { details: ScoringDetail[]; grade: AiGrade } | null {\n  if ((data as { redacted?: unknown }).redacted === true) {\n    return null;\n  }\n  try {\n    const result = score(data.type as never, data as unknown as ActivityData, response);\n    return { details: result.details, grade: aiGradeOf(result) };\n  } catch {\n    return null;\n  }\n}\n\n/**\n * The request for an explanation of `response`, or `null` when there is none\n * to give: an unsupported type, an author who switched explanations off,\n * nothing graded to explain, or a grade of record that cannot be a grade.\n *\n * A scored `outcome` — the grade of record a review shows — wins over grading\n * locally, so the explanation speaks to the grade on the screen. One whose\n * numbers cannot be a grade (the rule `outcomeFromGrade` applies: `maxScore`\n * positive and finite, `score` finite from 0 to it) gets no explanation at all:\n * explaining 85 \"out of 1\" would tell the model a wrong answer was correct, and\n * grading locally instead would speak to a grade the screen does not show.\n */\nexport function aiExplanationRequest(input: {\n  data: AiActivityInput;\n  response: LearnerResponse | null;\n  outcome?: ItemOutcome;\n  learnerLocale?: string;\n}): AiExplanationRequest | null {\n  const { data, response, outcome, learnerLocale } = input;\n  if (!aiSupports(data.type, 'explanation') || !aiAllowedByContent(data, 'explanation')) {\n    return null;\n  }\n  let details: ScoringDetail[] | null = null;\n  let grade: AiGrade | null = null;\n  if (outcome?.status === 'scored') {\n    // Read once, so the check and the grade handed on see the same numbers.\n    const { score: recorded, maxScore, passed } = outcome;\n    if (!isGradeInRange(recorded, maxScore)) {\n      return null;\n    }\n    details = outcome.details;\n    grade = aiGradeOf({ score: recorded, maxScore, passed });\n  } else if (response !== null) {\n    const local = gradeLocally(data, response);\n    if (local !== null) {\n      details = local.details;\n      grade = local.grade;\n    }\n  }\n  if (grade === null) {\n    return null;\n  }\n  const facts = buildAiFacts(data, response, details);\n  if (facts === null) {\n    return null;\n  }\n  return {\n    feature: 'explanation',\n    facts,\n    grade,\n    ...(learnerLocale !== undefined ? { learnerLocale } : {}),\n  };\n}\n\n/**\n * The request for the next hint on an unsubmitted answer, or `null` when\n * there is none to give: an unsupported type, an author who switched hints\n * off, or a redacted item — hints are for practice, where the item is whole.\n *\n * The facts carry the key, and which parts the learner has right so far, so a\n * model can hint where it helps. The learner never sees them; a hint that\n * contains an answer is refused by {@link checkAiHint}.\n */\nexport function aiHintRequest(input: {\n  data: AiActivityInput;\n  response: LearnerResponse | null;\n  previousHints: readonly string[];\n  learnerLocale?: string;\n}): AiHintRequest | null {\n  const { data, previousHints, learnerLocale } = input;\n  if (\n    !aiSupports(data.type, 'hint') ||\n    !aiAllowedByContent(data, 'hint') ||\n    (data as { redacted?: unknown }).redacted === true\n  ) {\n    return null;\n  }\n  const response = input.response ?? emptyResponse(data.type);\n  const local = response === null ? null : gradeLocally(data, response);\n  const facts = buildAiFacts(data, response, local?.details ?? null);\n  if (facts === null) {\n    return null;\n  }\n  return {\n    feature: 'hint',\n    facts,\n    hintNumber: previousHints.length + 1,\n    previousHints: [...previousHints],\n    ...(learnerLocale !== undefined ? { learnerLocale } : {}),\n  };\n}\n\n// ── Checking what comes back ───────────────────────────────────────────\n\nconst VERDICTS: readonly string[] = ['correct', 'partly-correct', 'incorrect'];\n\n/** A provenance field a host may send, kept only when it is a short string. */\nfunction provenanceOf(raw: unknown): AiProvenance | undefined {\n  if (typeof raw !== 'object' || raw === null) {\n    return undefined;\n  }\n  const kept: AiProvenance = {};\n  for (const key of ['model', 'promptHash', 'generatedAt'] as const) {\n    const value = (raw as Record<string, unknown>)[key];\n    if (typeof value === 'string' && value.length > 0 && value.length <= 200) {\n      kept[key] = value;\n    }\n  }\n  return Object.keys(kept).length > 0 ? kept : undefined;\n}\n\n/**\n * What the call cost, as a port reported it. Read on the same terms as the\n * provenance: a number that is not finite and zero or more says nothing about\n * a cost, so it is dropped rather than carried into a host's totals.\n */\nfunction usageOf(raw: unknown): GraderUsage | undefined {\n  if (typeof raw !== 'object' || raw === null) {\n    return undefined;\n  }\n  const kept: GraderUsage = {};\n  for (const key of ['promptTokens', 'completionTokens', 'costUsd'] as const) {\n    const value = (raw as Record<string, unknown>)[key];\n    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {\n      kept[key] = value;\n    }\n  }\n  return Object.keys(kept).length > 0 ? kept : undefined;\n}\n\n/**\n * Plain text as the learner will read it: line endings unified, control\n * characters other than line breaks and tabs removed, runs of blank lines\n * collapsed, the ends trimmed.\n */\nfunction cleanText(text: string): string {\n  return (\n    text\n      .replace(/\\r\\n?/g, '\\n')\n      // biome-ignore lint/suspicious/noControlCharactersInRegex: removing them is the point\n      .replace(/[\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F-\\u009F\\u2028\\u2029]/g, '')\n      .replace(/\\n{3,}/g, '\\n\\n')\n      .trim()\n  );\n}\n\n/**\n * Reads what a port returned. Anything but an object with a string `text` is\n * `malformed`; text that is empty once cleaned, or longer than\n * {@link AI_TEXT_MAX_LENGTH}, is refused rather than shown or cut.\n */\nexport function readAiTextResult(\n  raw: unknown,\n): { ok: true; result: AiTextResult } | { ok: false; refusal: AiRefusal } {\n  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {\n    return { ok: false, refusal: 'malformed' };\n  }\n  const record = raw as Record<string, unknown>;\n  if (typeof record.text !== 'string') {\n    return { ok: false, refusal: 'malformed' };\n  }\n  if (record.verdict !== undefined && !VERDICTS.includes(record.verdict as string)) {\n    return { ok: false, refusal: 'malformed' };\n  }\n  const text = cleanText(record.text);\n  if (text === '') {\n    return { ok: false, refusal: 'empty' };\n  }\n  if ([...text].length > AI_TEXT_MAX_LENGTH) {\n    return { ok: false, refusal: 'too-long' };\n  }\n  const provenance = provenanceOf(record.provenance);\n  const usage = usageOf(record.usage);\n  return {\n    ok: true,\n    result: {\n      text,\n      ...(record.verdict !== undefined ? { verdict: record.verdict as AiVerdict } : {}),\n      ...(provenance !== undefined ? { provenance } : {}),\n      ...(usage !== undefined ? { usage } : {}),\n    },\n  };\n}\n\n/**\n * Checks an explanation a port returned for `request`. On top of\n * {@link readAiTextResult}: an explanation that states a verdict other than\n * the SDK's grade is refused (`contradicts-grade`) — it explains an answer\n * the learner did not get.\n */\nexport function checkAiExplanation(\n  raw: unknown,\n  request: AiExplanationRequest,\n): { ok: true; result: AiTextResult } | { ok: false; refusal: AiRefusal } {\n  const read = readAiTextResult(raw);\n  if (!read.ok) {\n    return read;\n  }\n  if (read.result.verdict !== undefined && read.result.verdict !== request.grade.category) {\n    return { ok: false, refusal: 'contradicts-grade' };\n  }\n  return read;\n}\n\n/**\n * Checks a hint a port returned for `request`. On top of\n * {@link readAiTextResult}: a hint that contains an answer is refused\n * (`reveals-answer`) — see {@link hintRevealsAnswer}.\n */\nexport function checkAiHint(\n  raw: unknown,\n  request: AiHintRequest,\n): { ok: true; result: AiTextResult } | { ok: false; refusal: AiRefusal } {\n  const read = readAiTextResult(raw);\n  if (!read.ok) {\n    return read;\n  }\n  if (hintRevealsAnswer(request.facts, read.result.text)) {\n    return { ok: false, refusal: 'reveals-answer' };\n  }\n  return read;\n}\n\n// ── The answer-leak guard ──────────────────────────────────────────────\n\n/**\n * Text folded for searching: compatibility forms read as what they stand for,\n * accents and other marks removed, lower-cased, and every run of anything but\n * letters and digits turned into one space. \"Está,\" and \"esta\" fold alike.\n */\nfunction fold(text: string): string[] {\n  const folded = text\n    .normalize('NFKD')\n    .replace(/\\p{M}/gu, '')\n    .toLowerCase()\n    .replace(/[^\\p{L}\\p{N}]+/gu, ' ')\n    .trim();\n  return folded === '' ? [] : folded.split(' ');\n}\n\n/** Whether `needle` appears in `haystack` as a run of whole words. */\nfunction containsWords(haystack: readonly string[], needle: readonly string[]): boolean {\n  if (needle.length === 0 || needle.length > haystack.length) {\n    return false;\n  }\n  for (let start = 0; start + needle.length <= haystack.length; start += 1) {\n    let match = true;\n    for (let offset = 0; offset < needle.length; offset += 1) {\n      if (haystack[start + offset] !== needle[offset]) {\n        match = false;\n        break;\n      }\n    }\n    if (match) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * An answer too short to search for on its own: one word of fewer than four\n * characters — \"is\", \"the\", \"26\". A hint may use such a word freely; it\n * reveals the answer only when it writes it where the answer goes.\n */\nconst isShort = (words: readonly string[]): boolean =>\n  words.length === 1 && [...(words[0] as string)].length < 4;\n\n/**\n * The words either side of the gap numbered `position` in a numbered\n * passage, other gaps left out.\n */\nfunction neighbours(passage: string, position: number): { before?: string; after?: string } {\n  const marker = `[${position}]`;\n  const at = passage.indexOf(marker);\n  if (at === -1) {\n    return {};\n  }\n  const strip = (text: string): string => text.replace(/\\[\\d+\\]/g, ' ');\n  const left = fold(strip(passage.slice(0, at)));\n  const right = fold(strip(passage.slice(at + marker.length)));\n  const before = left[left.length - 1];\n  const after = right[0];\n  return {\n    ...(before !== undefined ? { before } : {}),\n    ...(after !== undefined ? { after } : {}),\n  };\n}\n\n/**\n * Whether a hint gives away an answer, judged against the facts it was asked\n * for. It is a floor, not a proof: it finds an answer written out, not one\n * spelled letter by letter or described.\n *\n * - **Multiple choice:** the text of any correct option, as whole words.\n * - **Fill-in-the-blanks and gap select:** any accepted answer, as whole words.\n *   An answer of one short word (\"is\", \"the\") counts only where the hint\n *   writes it beside a neighbour it has in the passage — \"name is\", \"is\n *   Rossi\" — so a hint may still use the word on its own.\n *\n * Case, accents and punctuation are ignored on both sides.\n */\nexport function hintRevealsAnswer(facts: AiItemFacts, hint: string): boolean {\n  const words = fold(hint);\n  const reveals = (answer: string, passage?: string, position?: number): boolean => {\n    const needle = fold(answer);\n    if (needle.length === 0) {\n      return false;\n    }\n    if (!isShort(needle) || passage === undefined || position === undefined) {\n      return containsWords(words, needle);\n    }\n    const { before, after } = neighbours(passage, position);\n    if (before === undefined && after === undefined) {\n      return containsWords(words, needle);\n    }\n    return (\n      (before !== undefined && containsWords(words, [before, ...needle])) ||\n      (after !== undefined && containsWords(words, [...needle, after]))\n    );\n  };\n  switch (facts.activityType) {\n    case 'multiple-choice':\n      return facts.options.some((option) => option.correct === true && reveals(option.text));\n    case 'fill-in-the-blanks':\n      return facts.blanks.some((blank) =>\n        (blank.accepted ?? []).some((answer) => reveals(answer, facts.passage, blank.position)),\n      );\n    case 'gap-select':\n      return facts.gaps.some(\n        (gap) => gap.answer !== null && reveals(gap.answer, facts.passage, gap.position),\n      );\n    case 'dictation':\n      // Never asked: a dictation takes no AI hints (AI_HINT_TYPES).\n      return false;\n    default:\n      return false;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-XNMKDFPW.cjs → chunk-COBK2RUX.cjs}

@@ -99,6 +99,12 @@ function selectFeedback(activityData, passed) {
   return _nullishCoalesce((passed ? feedback.correct : feedback.incorrect), () => ( null));
 }
 
+// src/scoring/grade-numbers.ts
+var OVERSHOOT = 1e-9;
+function isGradeInRange(score2, maxScore) {
+  return Number.isFinite(maxScore) && maxScore > 0 && Number.isFinite(score2) && score2 >= 0 && score2 - maxScore <= maxScore * OVERSHOOT;
+}
+
 // src/grading.ts
 function gradeFromRubric(criteria, activityData, options = {}) {
   const rounding = roundingPolicyOf(_optionalChain([options, 'optionalAccess', _ => _.rounding]));
@@ -147,12 +153,19 @@ function gradeFromRubric(criteria, activityData, options = {}) {
       reason: "Criterion weights do not sum to a positive number, so the weighted total is undefined."
     };
   }
+  const negativeWeight = scoreable.find((criterion) => (_nullishCoalesce(criterion.weight, () => ( 1))) < 0);
+  if (negativeWeight !== void 0) {
+    return {
+      unscorable: true,
+      reason: `Criterion "${negativeWeight.name}" has weight ${String(negativeWeight.weight)}; a weight must be zero or more.`
+    };
+  }
   const weighted = scoreable.reduce(
     (sum, criterion) => sum + ratioOf(criterion) * (_nullishCoalesce(criterion.weight, () => ( 1))),
     0
   );
   const rawScore = weighted / totalWeight;
-  if (!Number.isFinite(rawScore)) {
+  if (!Number.isFinite(totalWeight) || !Number.isFinite(rawScore)) {
     return {
       unscorable: true,
       reason: "The weighted total is not a finite number, so no grade can be produced."
@@ -170,11 +183,15 @@ function gradeFromRubric(criteria, activityData, options = {}) {
   };
 }
 function outcomeFromGrade(grade) {
+  const { score: score2, maxScore } = grade;
+  if (!isGradeInRange(score2, maxScore)) {
+    return { status: "deferred", reason: "grade_rejected", maxScore: 1, rejectedGrade: grade };
+  }
   return {
     status: "graded",
     grade,
-    score: grade.score,
-    maxScore: grade.maxScore,
+    score: score2,
+    maxScore,
     passed: grade.passed,
     feedback: grade.feedback
   };
@@ -187,29 +204,41 @@ function hasGrade(outcome) {
 function earned(item) {
   const { outcome } = item;
   if (hasGrade(outcome)) {
-    const max = outcome.maxScore > 0 ? outcome.maxScore : 1;
-    return { state: "graded", points: outcome.score / max * item.points };
+    const { score: score2, maxScore } = outcome;
+    if (!isGradeInRange(score2, maxScore)) {
+      return { state: "rejected" };
+    }
+    return { state: "graded", points: score2 / maxScore * item.points };
   }
   if (outcome.status === "deferred") {
-    return { state: "pending" };
+    return outcome.reason === "grade_rejected" ? { state: "rejected" } : { state: "pending" };
   }
   return { state: "unscorable" };
 }
+function rejectedField(slotIds) {
+  return slotIds.length > 0 ? { rejectedSlotIds: slotIds } : {};
+}
 function composeAssessmentScore(sections, policy) {
   const pendingAll = [];
+  const rejectedAll = [];
   const unscorableAll = [];
   const partials = sections.map((section) => {
     let earnedPoints = 0;
     let gradedMaxPoints = 0;
     let maxPoints = 0;
     const pendingSlotIds = [];
+    const rejectedSlotIds = [];
     const unscorableSlotIds = [];
     for (const item of section.items) {
       maxPoints += item.points;
       const contribution = earned(item);
-      if (contribution.state === "pending") {
+      if (contribution.state === "pending" || contribution.state === "rejected") {
         pendingSlotIds.push(item.slotId);
         pendingAll.push(item.slotId);
+        if (contribution.state === "rejected") {
+          rejectedSlotIds.push(item.slotId);
+          rejectedAll.push(item.slotId);
+        }
         continue;
       }
       if (contribution.state === "unscorable") {
@@ -230,6 +259,7 @@ function composeAssessmentScore(sections, policy) {
       score: roundGrade(raw, policy.rounding),
       appliedThreshold,
       pendingSlotIds,
+      rejectedSlotIds,
       unscorableSlotIds
     };
   });
@@ -250,6 +280,7 @@ function composeAssessmentScore(sections, policy) {
     passed: partial.appliedThreshold === null || partial.gradedMaxPoints === 0 ? true : gte(partial.score, partial.appliedThreshold, policy.rounding),
     appliedThreshold: partial.appliedThreshold,
     pendingSlotIds: partial.pendingSlotIds,
+    ...rejectedField(partial.rejectedSlotIds),
     unscorableSlotIds: partial.unscorableSlotIds
   }));
   const weightedRaw = scored.reduce(
@@ -266,6 +297,7 @@ function composeAssessmentScore(sections, policy) {
       passFailureReason: null,
       status,
       pendingSlotIds: pendingAll,
+      ...rejectedField(rejectedAll),
       unscorableSlotIds: unscorableAll
     };
   }
@@ -277,6 +309,7 @@ function composeAssessmentScore(sections, policy) {
       passFailureReason: null,
       status,
       pendingSlotIds: pendingAll,
+      ...rejectedField(rejectedAll),
       unscorableSlotIds: unscorableAll
     };
   }
@@ -291,6 +324,7 @@ function composeAssessmentScore(sections, policy) {
     passFailureReason,
     status,
     pendingSlotIds: pendingAll,
+    ...rejectedField(rejectedAll),
     unscorableSlotIds: unscorableAll
   };
 }
@@ -1030,5 +1064,6 @@ function evaluate(data, response, options) {
 
 
 
-exports.roundGrade = roundGrade; exports.gte = gte; exports.classifyBand = classifyBand; exports.DEFAULT_PASS_THRESHOLD = DEFAULT_PASS_THRESHOLD; exports.computePassThreshold = computePassThreshold; exports.gradeFromRubric = gradeFromRubric; exports.outcomeFromGrade = outcomeFromGrade; exports.hasGrade = hasGrade; exports.composeAssessmentScore = composeAssessmentScore; exports.diffDictationChars = diffDictationChars; exports.validateSpeechAssessment = validateSpeechAssessment; exports.alignReadAloud = alignReadAloud; exports.gradeReadAloud = gradeReadAloud; exports.inspectWav = inspectWav; exports.outcomeFromUnscorable = outcomeFromUnscorable; exports.score = score; exports.evaluate = evaluate;
-//# sourceMappingURL=chunk-XNMKDFPW.cjs.map
+
+exports.isGradeInRange = isGradeInRange; exports.roundGrade = roundGrade; exports.gte = gte; exports.classifyBand = classifyBand; exports.DEFAULT_PASS_THRESHOLD = DEFAULT_PASS_THRESHOLD; exports.computePassThreshold = computePassThreshold; exports.gradeFromRubric = gradeFromRubric; exports.outcomeFromGrade = outcomeFromGrade; exports.hasGrade = hasGrade; exports.composeAssessmentScore = composeAssessmentScore; exports.diffDictationChars = diffDictationChars; exports.validateSpeechAssessment = validateSpeechAssessment; exports.alignReadAloud = alignReadAloud; exports.gradeReadAloud = gradeReadAloud; exports.inspectWav = inspectWav; exports.outcomeFromUnscorable = outcomeFromUnscorable; exports.score = score; exports.evaluate = evaluate;
+//# sourceMappingURL=chunk-COBK2RUX.cjs.map