@intellectif/lk-core 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @intellectif/lk-core
 
+## 0.18.0
+
+### Minor Changes
+
+- 71de78d: The grade return trip now checks its numbers. A returned grade that cannot be a grade — `NaN`, `Infinity`, a negative, 85 "out of 1", any score out of 0 — no longer composes to a final result. **This can change a recorded grade**, for exactly that population, and for nothing else.
+
+  **What was wrong.** `evaluate` refuses a non-finite score and `gradeFromRubric` refuses one outside `[0,1]`, but the path a deferred grade comes back on took any number on trust. `outcomeFromGrade` mirrored whatever `GradeRecord` it was handed, and `composeAssessmentScore` divided by it, reading a `maxScore` of 0 or less as 1. Composed beside one full-marks item:
+
+  - a grader that returned raw points (`score: 85, maxScore: 1`) gave a **final** result, score 43, passed;
+  - `score: NaN` gave a final `NaN` score — `null` once stored as JSON — beside a section marked passed;
+  - `score: Infinity` gave a final pass;
+  - `score: 0.5, maxScore: 0` was counted as 0.5 out of 1.
+
+  **What changes.**
+
+  - **`outcomeFromGrade`** lifts a record only when `maxScore` is a positive, finite number and `score` a finite number from 0 to it. A score up to one part in a billion above `maxScore` is float noise (`1.0000000000000002` from summing weighted parts) and passes as it is, unclamped. The tolerance is relative, and it is the bound lk-react's grade reader already applies before it shows a grade, so the two packages agree on what a grade is. There is no tolerance below 0: nothing the SDK produces is negative. A record that fails comes back as `{ status: 'deferred', reason: 'grade_rejected', maxScore: 1, rejectedGrade }`. The record is kept verbatim for audit, and nothing on it is mirrored, so its `passed` is never read as a verdict. `hasGrade` is `false` for it. A valid record lifts exactly as before.
+  - **`composeAssessmentScore`** applies the same check to every `scored` and `graded` outcome, including ones an earlier release stored. It treats a failing outcome, and a `grade_rejected` one, as still owed a grade: out of the denominator, listed in `pendingSlotIds`, and also in a new **`rejectedSlotIds`** on the result and on its section. The result stays `provisional` with `passed: null`.
+  - **`aiExplanationRequest`** returns `null` for a `scored` grade of record that fails the same check. In 0.17.0 it handed the numbers to the model as they were: 85 "out of 1" on a wrong multiple-choice answer went as `category: 'correct'`, passed; `NaN` went as a `null` score. Grading locally instead would speak to a grade the screen does not show, so there is no explanation at all, and lk-react's "Explain my answer" reads "No explanation is available right now." without calling the port.
+  - **`gradeFromRubric`** refuses a criterion weight below 0 as `unscorable`, and likewise a weight sum that overflows to Infinity. It checked only that the weights summed to a positive number, so `[0 ×2, 1 ×−1]` came back as a real 0 and `[1 ×2, 0 ×−1]` as a perfect 1, the clamp meant for float noise hiding both. Only criteria that enter the arithmetic are read, as for `score` and `maxScore`. A rubric already refused for its weight sum keeps the reason it always had. `[1 ×1e308, 0 ×1e308]` used to grade 0: its sum is Infinity, and every criterion divided into it.
+
+  **Why deferred, and not unscorable.** `unscorable` means a grade is never coming. `composeAssessmentScore` leaves such a slot out of the denominator and still lets the attempt go `final` with a verdict. A failing grade on the wrong scale would vanish, and the rest of the paper would be recorded as a pass. `deferred` is what the slot is: a real grade is still owed. Every reader that already treats `deferred` as not yet, lk-react's components included, stays safe without knowing the new reason. `rejectedSlotIds` tells a host to re-grade rather than wait. A rejected slot is also listed in `pendingSlotIds`, so `status` is `provisional` exactly when `pendingSlotIds` is non-empty, the rule it has always followed.
+
+  **One deliberate reversal.** A `maxScore` of 0 or less used to be read as 1 rather than divided by. A unit test and one grade-stability vector pinned that on purpose, to stop a division by zero. Dividing is not the only alternative: nothing is out of 0, so reading 0.5 against a denominator nobody declared invents a grade. Such an outcome is now rejected like any other score that cannot be a grade. The test is rewritten to say so, and the vector `composeAssessmentScore/item-max-score-zero` is re-frozen.
+
+  **What stays the same.** Of the 564 vectors in the grade-stability corpus, 563 replay byte for byte against this build, both ESM and CJS, and the one that moves is the reversal above. Every input that was a grade composes exactly as before. `rejectedSlotIds` is present only when something was rejected, so a result without one is identical to what earlier releases returned. 28 new vectors cover each refused kind of number, the accepted float noise up to its exact edge, and the new rubric refusals.
+
+  **Before you upgrade.** Search stored outcomes for a `score` or `maxScore` that is not a finite number (in JSON, `null`), a `maxScore` of 0 or less, or a `score` below 0 or above its `maxScore`. Re-composing an attempt that holds one now returns `provisional` rather than the final result you recorded. Re-grade those slots. `DeferredReason` gains `'grade_rejected'`, so an exhaustive `switch` over it needs a case. The new fields are optional.
+
+  lk-react needs no code change. A record `outcomeFromGrade` now refuses renders as "Not graded yet.", like any deferred outcome. With lk-react 17, `<WrittenResponse>` showed such a record's numbers ("Score 8500%. Passed." for 85 out of 1). A `graded` outcome stored by an earlier release is not re-read, and still renders as before.
+
+## 0.17.0
+
+### Minor Changes
+
+- 15a3435: The contract for AI help a learner reads — an explanation of a graded answer, and hints before one —
+  between an activity and a model the host runs. The SDK never calls a model and holds no key or prompt;
+  it builds what the model is given and checks what comes back.
+
+  - **Facts:** `buildAiFacts(data, response, details)` describes an item as the learner saw it, their
+    answer, and the SDK's own verdict part by part. It covers multiple choice (every option), fill in the
+    blanks and gap select (each blank or gap in passage order, the passage written with `[1]`, `[2]`…),
+    and dictation (the word-by-word alignment). On a redacted item the key is absent, except where a
+    server's outcome supplies it.
+  - **Requests:**
+    - `aiExplanationRequest({ data, response, outcome?, learnerLocale? })` carries the facts and the
+      `grade`, with its `category` (`correct`, `partly-correct` or `incorrect`). A scored `outcome` wins
+      over grading locally, so an explanation speaks to the grade of record.
+    - `aiHintRequest({ data, response, previousHints, learnerLocale? })` carries the key and the answer
+      so far, marked part by part. It gives none for a dictation, which has hints of its own, or for a
+      redacted item.
+  - **Checks:**
+    - `readAiTextResult` refuses anything but plain text of up to 2,000 characters (`malformed`,
+      `empty`, `too-long`), with control characters removed.
+    - `checkAiExplanation` also refuses an explanation stating a verdict other than the SDK's
+      (`contradicts-grade`).
+    - `checkAiHint` also refuses a hint that contains an answer (`reveals-answer`).
+  - **The guard:** `hintRevealsAnswer(facts, text)` finds an answer written out, ignoring case,
+    accents and punctuation. An answer of one short word counts only where the hint writes it beside a
+    neighbour it has in the passage, so a hint can still say "the verb is…".
+  - **Permissions:** `aiSupports(type, feature)`, `aiAllowedByContent(data, feature)`, `aiGradeOf`, and
+    the types `AiItemFacts`, `AiExplanationRequest`, `AiHintRequest`, `AiTextResult`, `AiProvenance`,
+    `ActivityAiPermissions` and more. Two new interaction kinds: `ai-hint-shown` and
+    `ai-explanation-shown`.
+
+  **The author's switch, and one tightened rule.** Every built-in type now defines an optional
+  `ai: { hints?: boolean, explanations?: boolean }`: `false` switches that help off for the item,
+  wherever it is delivered, and an author can only switch help off. `redact()` keeps both flags, as
+  public, and drops any other key inside `ai`; the strict redacted schemas accept them.
+
+  A field named `ai` was until now an unknown key the loose schemas kept, whatever it held. A sidecar
+  such as `ai: 'generated'`, or a flag that is not a boolean, now fails `validateActivity`: check stored
+  content before upgrading.
+
+  See `docs/ai.md`.
+
 ## 0.16.0
 
 ### Minor Changes

package/README.md

@@ -23,8 +23,8 @@ npm install @intellectif/lk-core
 - **Scoring engine** — `score(activityType, data, response)` returning `{ score ∈ [0,1], maxScore: 1, passed, feedback, details }`. Pure, deterministic, 100 % test coverage enforced. It **throws** rather than inventing a number: `DeferredScoringError` for a deferred-graded type (`written-response`), and `RedactedScoringError` when handed a `redact()` projection, which has no answer key. Both are on the documented exam path — use `evaluate()` there, which returns `deferred` / `unscorable` instead of throwing.
 - **Dictation marking as data** — a dictation is graded by the character-level similarity of the typed text to the transcript, with one `ScoringDetail` per word carrying its own `score`. `alignDictation(data, text)` returns the same comparison the grade was made of (normalised strings, word pairings, which accepted transcript won), `diffDictationChars(reference, attempt)` the character-level edits for a marked display, and `dictationReferenceWords(data)` the ids and words a stored result can be checked against — so a review screen or an analytics job never re-implements the arithmetic. `score()` and `evaluate()` take an optional `{ rounding }` to compare the pass line as displayed.
 - **`evaluate(data, response)` → `ItemOutcome`** — the resilient result: `scored`, `deferred` (graded later by an AI or a human), `graded` (the grade came back), or `unscorable`. "Not graded yet" is expressible in the type system and is never conflated with a zero.
-- **Deferred grading, both directions** — `GradeRecord`, `gradeFromRubric()` (the weighted total as a pure function of the grader's judgements — never the model's arithmetic; declare `maxScore` per criterion if your grader works out of 100 or out of 9), `outcomeFromGrade()`, `hasGrade()`.
-- **Assessment composition** — `composeAssessmentScore()` for weighted, sectioned totals, with a `provisional` status so an unmarked essay never deflates a grade, and `RoundingPolicy` / `roundGrade` / `gte` / `classifyBand` keeping grade rounding and band classification as the two distinct operations they are.
+- **Deferred grading, both directions** — `GradeRecord`, `gradeFromRubric()` (the weighted total as a pure function of the grader's judgements — never the model's arithmetic; declare `maxScore` per criterion if your grader works out of 100 or out of 9), `outcomeFromGrade()` (which refuses a record whose numbers cannot be a grade instead of mirroring them), `hasGrade()`.
+- **Assessment composition** — `composeAssessmentScore()` for weighted, sectioned totals, with a `provisional` status so an unmarked essay never deflates a grade — and a grade out of contract (`NaN`, 85 "out of 1") never finalises one — and `RoundingPolicy` / `roundGrade` / `gte` / `classifyBand` keeping grade rounding and band classification as the two distinct operations they are.
 - **Item groups** — `Stimulus` + `ItemGroup` (one passage or recording serving several questions), `flattenSequence()` for seeded, shuffle-atomic presentation order with stable slot identity. Slot ids are positional by default (`"3"`, `"1.0"`); author a `slotKey` on an entry and its id survives an insert, so a stored response cannot slide onto a different question.
 - **Attempt plans** — `planAttempt(entries, { seed, shuffleEntries, points })` freezes the exact paper a learner sat: slot order, per-slot points, a content hash of each item, and a `planHash` over the lot. `verifyAttemptPlan(plan, current)` reports the drift when that content is later edited (`changedSlotIds`, `changedStimulusSlotIds`, `changedPointsSlotIds`, `missingSlotIds`, …) — the thing you need during a remark or an appeal. `scoredItemsFromPlan(plan, outcomes)` turns collected outcomes into the `ScoredItem[]` composition wants, and defaults a slot with **no** outcome to `deferred` rather than silently shrinking the denominator.
 - **Attempt state** — `serializeAttemptState(plan, progress)` / `restoreAttemptState(plan, snapshot)` round-trip an interrupted attempt (responses, submitted slots, position) and are **bound to the plan**: restoring answers onto a paper the learner never sat throws instead of succeeding quietly. `diffResponses(before, after)` reports what moved between two snapshots, including an answer the learner *cleared*.

package/dist/{activity-DcxtpX7Z.d.cts → activity-HH8dxN1v.d.cts}

@@ -63,6 +63,197 @@ declare function levenshteinDistance(a: string, b: string, max: number): number;
  */
 declare function matchText(input: string, accepted: string | readonly string[], policy?: TextMatchPolicy): TextMatchResult;
 
+/**
+ * The contract between an activity and a model the HOST runs, for help a
+ * learner reads: an explanation of a graded answer, and hints before one.
+ *
+ * The SDK never calls a model and holds no key, prompt or provider. It builds
+ * the facts a model is given — from the item, the learner's answer and the
+ * SDK's own scorer — and checks what comes back. The model explains a verdict
+ * the SDK reached; it never reaches one.
+ */
+/**
+ * What an author allows AI to do for one item. Absent, or a feature left out,
+ * leaves the choice to the deployment. `false` switches a feature off for this
+ * item wherever it is delivered; an author can only switch a feature off,
+ * never force one on.
+ *
+ * Switch hints off where any hint would give the answer away — a
+ * one-word vocabulary item, say.
+ */
+interface ActivityAiPermissions {
+    /** An explanation of the learner's graded answer. */
+    explanations?: boolean;
+    /** Hints before the learner submits. */
+    hints?: boolean;
+}
+/**
+ * An activity as a renderer holds it: full data or a `redact()` projection.
+ * Structural rather than the data union, so a renderer's own view of an item —
+ * whose answer-key fields may be absent — is accepted as it is. The AI
+ * functions read every field defensively.
+ */
+interface AiActivityInput {
+    readonly type: string;
+    readonly id: string;
+    readonly title: string;
+    readonly locale?: unknown;
+    readonly redacted?: unknown;
+    readonly ai?: unknown;
+}
+/** The two kinds of help a learner can be given. */
+type AiFeature = 'explanation' | 'hint';
+/** The activity types the SDK builds facts for. */
+type AiSupportedActivityType = 'multiple-choice' | 'fill-in-the-blanks' | 'gap-select' | 'dictation';
+/**
+ * A whole answer's grade, from the SDK's scorer. `category` is the verdict an
+ * explanation must agree with: all marks, some, or none.
+ */
+interface AiGrade {
+    score: number;
+    maxScore: number;
+    passed: boolean;
+    category: AiVerdict;
+}
+/** The three verdicts an explanation can speak to. */
+type AiVerdict = 'correct' | 'partly-correct' | 'incorrect';
+interface AiFactsBase {
+    activityId: string;
+    title: string;
+    /** The language the item is written in, when the author gave one. */
+    locale?: string;
+}
+/** One option of a multiple-choice question, and what the learner did with it. */
+interface AiOptionFact {
+    id: string;
+    text: string;
+    chosen: boolean;
+    /** Whether this option is part of the answer; `null` when the key is not available. */
+    correct: boolean | null;
+    /** The author's feedback on this option. */
+    feedback?: string;
+}
+interface AiMultipleChoiceFacts extends AiFactsBase {
+    activityType: 'multiple-choice';
+    question: string;
+    mode: 'single' | 'multi';
+    options: AiOptionFact[];
+}
+/** One blank, in the order it appears in the passage. */
+interface AiBlankFact {
+    id: string;
+    /** 1-based, in passage order. */
+    position: number;
+    /** What the learner typed, or `''`. */
+    typed: string;
+    /** The answers that count; `null` when the key is not available. */
+    accepted: string[] | null;
+    /** The SDK's verdict on this blank; `null` before it is graded or without a key. */
+    correct: boolean | null;
+    /** The author's hint for this blank. */
+    hint?: string;
+    /** The author's feedback for this blank. */
+    feedback?: string;
+}
+interface AiFillInTheBlanksFacts extends AiFactsBase {
+    activityType: 'fill-in-the-blanks';
+    /** The passage, each blank written as `[1]`, `[2]`… in passage order. */
+    passage: string;
+    blanks: AiBlankFact[];
+}
+/** One gap, in the order it appears in the passage. */
+interface AiGapFact {
+    id: string;
+    /** 1-based, in passage order. */
+    position: number;
+    /** The words offered at this gap. */
+    choices: string[];
+    /** The word the learner chose, or `null`. */
+    chosen: string | null;
+    /** The right word; `null` when the key is not available. */
+    answer: string | null;
+    /** The SDK's verdict on this gap; `null` before it is graded or without a key. */
+    correct: boolean | null;
+    /** The author's feedback for this gap. */
+    feedback?: string;
+}
+interface AiGapSelectFacts extends AiFactsBase {
+    activityType: 'gap-select';
+    /** The passage, each gap written as `[1]`, `[2]`… in passage order. */
+    passage: string;
+    gaps: AiGapFact[];
+}
+/** One word of a dictation, as the SDK's alignment paired it. */
+interface AiWordFact {
+    /** The word the recording says; `''` for an extra word the learner added. */
+    expected: string;
+    /** The word the learner typed; `''` for a word they left out. */
+    typed: string;
+    status: 'correct' | 'incorrect' | 'missing' | 'extra';
+}
+interface AiDictationFacts extends AiFactsBase {
+    activityType: 'dictation';
+    /** What the recording says; `null` when the key is not available. */
+    transcript: string | null;
+    /** What the learner typed. */
+    typed: string;
+    /** The alignment word by word; `null` when the key is not available. */
+    words: AiWordFact[] | null;
+}
+/**
+ * What a model is told about one item and one answer: the question as the
+ * learner saw it, what they answered, and — part by part — the SDK's verdict.
+ */
+type AiItemFacts = AiMultipleChoiceFacts | AiFillInTheBlanksFacts | AiGapSelectFacts | AiDictationFacts;
+/**
+ * Asks for an explanation of a graded answer. Sent after the SDK has graded
+ * it, so `grade` is always present, and an explanation that contradicts
+ * `grade.category` is refused.
+ */
+interface AiExplanationRequest {
+    feature: 'explanation';
+    facts: AiItemFacts;
+    grade: AiGrade;
+    /** The language to answer in: the learner's interface language, when known. */
+    learnerLocale?: string;
+}
+/**
+ * Asks for the next hint before the learner submits. `facts` carries the key
+ * so a model can hint toward the answer; the SDK refuses any hint that
+ * contains it.
+ */
+interface AiHintRequest {
+    feature: 'hint';
+    facts: AiItemFacts;
+    /** 1-based: the hint being asked for. */
+    hintNumber: number;
+    /** The hints already shown for this item, oldest first. */
+    previousHints: string[];
+    learnerLocale?: string;
+}
+/** What produced an AI text, for the record a host keeps. */
+interface AiProvenance {
+    /** The model's identifier, e.g. a name and version. */
+    model?: string;
+    /** A hash or id of the prompt revision. */
+    promptHash?: string;
+    /** ISO 8601. */
+    generatedAt?: string;
+}
+/**
+ * What a host's port returns. Plain text: the SDK renders it as text, never
+ * as HTML. An explanation may state the verdict it assumed; one that
+ * disagrees with the SDK's is refused.
+ */
+interface AiTextResult {
+    text: string;
+    /** For an explanation: the verdict the model explained. */
+    verdict?: AiVerdict;
+    provenance?: AiProvenance;
+}
+/** Why a result was not shown. */
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer';
+
 /**
  * The return trip for deferred grading.
  *
@@ -139,7 +330,11 @@ interface CriterionScore {
     band?: string;
     /** The grader's comment for this criterion, addressed to the learner. */
     comment?: string;
-    /** Weight actually applied, echoed from the rubric so the total is checkable. */
+    /**
+     * Weight actually applied, echoed from the rubric so the total is checkable.
+     * Defaults to `1`. Zero or more: `gradeFromRubric` refuses a negative weight
+     * rather than let it carry the total outside [0,1].
+     */
     weight?: number;
     /** Not applicable to this submission (e.g. interaction on a monologue task). */
     notApplicable?: boolean;
@@ -165,6 +360,10 @@ interface InlineCorrection {
  * that works in points does not have to normalise by hand: declare
  * `maxScore` on each {@link CriterionScore} and let `gradeFromRubric` do the
  * arithmetic, which is the whole point of handing it the judgements.
+ *
+ * `maxScore` is a positive, finite number and `score` a finite number from 0
+ * to it. `outcomeFromGrade` refuses a record that is not, rather than mirror
+ * numbers nobody can defend onto an outcome.
  */
 interface GradeRecord {
     score: number;
@@ -590,6 +789,8 @@ interface MultipleChoiceData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /** Configuration for a single fill-in-the-blank slot. */
 interface BlankConfig {
@@ -724,6 +925,8 @@ interface GapSelectData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 interface FillInTheBlanksData {
     schemaVersion: '1.0';
@@ -756,6 +959,8 @@ interface FillInTheBlanksData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /** A single criterion within a written-response grading rubric. */
 interface WrittenResponseRubricCriterion {
@@ -818,6 +1023,8 @@ interface WrittenResponseData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /**
  * A second, slower recording of a dictation — a separate file (a text-to-speech
@@ -920,6 +1127,8 @@ interface DictationData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /** A dimension of speech a pronunciation assessor scores, on a 0–100 scale. */
 type ReadAloudDimension = 'accuracy' | 'fluency' | 'completeness' | 'prosody';
@@ -1010,6 +1219,8 @@ interface ReadAloudData {
     learningObjectives?: string[];
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+    /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+    ai?: ActivityAiPermissions;
 }
 /**
  * Maps each ActivityType string to its learner-response shape. Open for
@@ -1185,8 +1396,13 @@ interface DeferredScoringPartial {
  *   a grade has not landed, or the attempt is still open has earned nothing
  *   yet, and recording it as zero is how an incomplete attempt becomes a
  *   plausible-looking fail.
+ * - `grade_rejected` — a grade came back, and `outcomeFromGrade` refused it
+ *   because its numbers cannot be a grade (a `score` or `maxScore` that is not
+ *   a finite number, a `maxScore` of 0 or less, or a score outside 0 to
+ *   `maxScore`). The record is kept on `rejectedGrade`. A real grade is still
+ *   owed, so re-grade the slot: waiting will not bring one.
  */
-type DeferredReason = 'requires_async_grading' | 'no_response_recorded';
+type DeferredReason = 'requires_async_grading' | 'no_response_recorded' | 'grade_rejected';
 /**
  * The outcome of evaluating a learner response against an activity — the
  * union `evaluate()` returns. Unlike {@link ScoringResult}, it can express
@@ -1213,6 +1429,12 @@ type ItemOutcome = {
     maxScore: number;
     /** Synchronously computable progress facts (word bounds, counts). */
     partial?: DeferredScoringPartial;
+    /**
+     * The record `outcomeFromGrade` refused, verbatim, when `reason` is
+     * `grade_rejected` — kept for audit and for the re-grade. Nothing on it
+     * is mirrored onto the outcome, and nothing reads it as a grade.
+     */
+    rejectedGrade?: GradeRecord;
 } | {
     status: 'graded';
     /**
@@ -1320,7 +1542,15 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
  * primary line's language, or `null` with captions off; `payload.secondary` is
  * the second line's, or `null` with none showing. Fires when either changes.
  */
- | 'video-captions-changed' | 'video-fullscreen-changed' | 'video-pip-changed' | (string & {});
+ | 'video-captions-changed' | 'video-fullscreen-changed' | 'video-pip-changed'
+/**
+ * An AI hint was shown to the learner (`hintNumber`, and the port's
+ * `provenance` when it sent one). Only a hint the SDK accepted: a refused one
+ * is never shown and never reported here.
+ */
+ | 'ai-hint-shown'
+/** An AI explanation of the graded answer was shown (`provenance` when sent). */
+ | 'ai-explanation-shown' | (string & {});
 /** Fired by activity components on every discrete learner interaction. */
 interface InteractionEvent {
     /** The kind of interaction that occurred. */
@@ -1333,4 +1563,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type ValidationResult as $, type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredReason as D, type MultipleChoiceData as E, type FillInTheBlanksData as F, type GapSelectBank as G, type MultipleChoiceLearnerResponse as H, type InlineCorrection as I, type MultipleChoiceOption as J, type MultipleChoiceOptionMedia as K, type LearnerResponse as L, type MediaPlaybackPolicy as M, type NativeControlHint as N, type ReadAloudDimension as O, type ReadAloudDimensionWeight as P, type ReadAloudLearnerResponse as Q, type ReadAloudData as R, type ReadAloudSlowMedia as S, type RecordingBounds as T, type RecordingRef as U, type ScoringDetail as V, type ScoringOutcome as W, type ScoringResult as X, type TextMatchPolicy as Y, type TextMatchResult as Z, type ValidationError as _, type ActivityDataMap as a, type WrittenResponseData as a0, type WrittenResponseLearnerResponse as a1, type WrittenResponseRubric as a2, type WrittenResponseRubricCriterion as a3, type XAPIActor as a4, type XAPIConfig as a5, type XAPIContext as a6, type XAPIContextActivities as a7, type XAPIError as a8, type XAPIObject as a9, type XAPIResult as aa, type XAPIScore as ab, type XAPIStatement as ac, type XAPIVerbObject as ad, levenshteinDistance as ae, matchText as af, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type DeferredScoringPartial as f, type DictationData as g, type DictationEquivalence as h, type DictationLearnerResponse as i, type DictationSlowMedia as j, type DictationTolerance as k, type FillInTheBlanksLearnerResponse as l, type GapSelectChoice as m, type GapSelectData as n, type GapSelectGap as o, type GapSelectLearnerResponse as p, type GradeRecord as q, type Grader as r, type GraderKind as s, type GraderUsage as t, type GradingState as u, type InteractionEvent as v, type InteractionKind as w, type ItemOutcome as x, type LearnerResponseMap as y, type MediaTrack as z };
+export { type MediaPlaybackPolicy as $, type ActivityAiPermissions as A, type BlankConfig as B, type CriterionScore as C, type DeferredReason as D, type DictationData as E, type DictationEquivalence as F, type DictationLearnerResponse as G, type DictationSlowMedia as H, type DictationTolerance as I, type FillInTheBlanksData as J, type FillInTheBlanksLearnerResponse as K, type GapSelectBank as L, type GapSelectChoice as M, type GapSelectData as N, type GapSelectGap as O, type GapSelectLearnerResponse as P, type GradeRecord as Q, type Grader as R, type GraderKind as S, type GraderUsage as T, type GradingState as U, type InlineCorrection as V, type InteractionEvent as W, type InteractionKind as X, type ItemOutcome as Y, type LearnerResponse as Z, type LearnerResponseMap as _, type ActivityData as a, type MediaTrack as a0, type MultipleChoiceData as a1, type MultipleChoiceLearnerResponse as a2, type MultipleChoiceOption as a3, type MultipleChoiceOptionMedia as a4, type NativeControlHint as a5, type ReadAloudData as a6, type ReadAloudDimension as a7, type ReadAloudDimensionWeight as a8, type ReadAloudLearnerResponse as a9, type ReadAloudSlowMedia as aa, type RecordingBounds as ab, type RecordingRef as ac, type ScoringDetail as ad, type ScoringOutcome as ae, type ScoringResult as af, type TextMatchPolicy as ag, type TextMatchResult as ah, type ValidationError as ai, type ValidationResult as aj, type WrittenResponseData as ak, type WrittenResponseLearnerResponse as al, type WrittenResponseRubric as am, type WrittenResponseRubricCriterion as an, type XAPIActor as ao, type XAPIConfig as ap, type XAPIContext as aq, type XAPIContextActivities as ar, type XAPIError as as, type XAPIObject as at, type XAPIResult as au, type XAPIScore as av, type XAPIStatement as aw, type XAPIVerbObject as ax, levenshteinDistance as ay, matchText as az, type ActivityDataMap as b, type ActivityFeedback as c, type ActivityMedia as d, type ActivityResult as e, type ActivityType as f, type AiActivityInput as g, type AiBlankFact as h, type AiDictationFacts as i, type AiExplanationRequest as j, type AiFeature as k, type AiFillInTheBlanksFacts as l, type AiGapFact as m, type AiGapSelectFacts as n, type AiGrade as o, type AiHintRequest as p, type AiItemFacts as q, type AiMultipleChoiceFacts as r, type AiOptionFact as s, type AiProvenance as t, type AiRefusal as u, type AiSupportedActivityType as v, type AiTextResult as w, type AiVerdict as x, type AiWordFact as y, type DeferredScoringPartial as z };