@intellectif/lk-core 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @intellectif/lk-core
 
+## 0.19.0
+
+### Minor Changes
+
+- d576382: Groundwork under the AI line: what a call cost, what was refused, and a way to test a prompt.
+
+  - **`AiTextResult.usage`** — what the call cost, as your provider reported it to your port. It is the
+    same `GraderUsage` a returned grade already carries (`promptTokens`, `completionTokens`, `costUsd`),
+    so one shape covers help for a learner and marking by a grader. The SDK never estimates it and never
+    adds it up; it carries what you send, and drops a number that is not finite and zero or more rather
+    than let it into your totals.
+  - **`ai-help-refused`** joins the interaction kinds: a host can now see, in production, that its model
+    wrote a hint containing the answer or an explanation of a verdict the SDK did not reach. The
+    development console warning said it only to a developer. The event carries the feature and the
+    reason and **never the text** — the text of a refused hint is the answer.
+  - **`@intellectif/lk-core/ai-check`, a new entry point: a test kit for your prompts.** `runAiCheck`
+    makes the calls a learner's questions would make — on items whose answers the SDK knows — and runs
+    the same checks it runs before a learner sees anything, reporting what would have been shown and
+    what would have been refused, with the reason. `aiCheckCases` hands over the cases (every type it
+    explains, answered right, wrong and partly right; every type it hints for, before an answer and
+    after a wrong one), and takes cases of your own built on your own items. `formatAiCheckReport`
+    prints a run for a CI log.
+
+    It is a separate entry point because it is for your test run, not a learner's browser: nothing a
+    page renders imports it.
+
+  The empty `@intellectif/lk-ai` placeholder has been deleted — it never held code, and the ports it
+  was planned for live here, beside the scorers whose readings the checks are.
+
+  See `docs/ai.md`.
+
+## 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

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*.
@@ -115,6 +115,7 @@ result.passed;   // boolean, or null while provisional. Never record a provision
 | `@intellectif/lk-core/schemas` | Zod schemas + `validateActivity` + JSON Schema export |
 | `@intellectif/lk-core/scoring` | `score`, `evaluate`, `composeAssessmentScore`, rounding, text matching |
 | `@intellectif/lk-core/xapi` | `xAPIBuilder`, `XAPIVerb`, `validateXAPIStatement` |
+| `@intellectif/lk-core/ai-check` | `runAiCheck`, `aiCheckCases`, `formatAiCheckReport` — test your AI prompts in CI |
 
 The barrel re-exports everything, and it is the **only** entry point for attempt
 plans, attempt state, item groups, redaction, the type registry, authoring drafts

package/dist/{activity-BmjBjXVJ.d.cts → activity-f0bgZSTP.d.cts}

@@ -63,6 +63,147 @@ declare function levenshteinDistance(a: string, b: string, max: number): number;
  */
 declare function matchText(input: string, accepted: string | readonly string[], policy?: TextMatchPolicy): TextMatchResult;
 
+/**
+ * The return trip for deferred grading.
+ *
+ * `evaluate()` can say a submission is `deferred` — graded later by an AI or a
+ * human — but until now there was no type for the grade that comes BACK, so
+ * every consumer invented one. The shapes here are the intersection of two
+ * independent production graders (a rubric-based essay grader and a CEFR
+ * speaking grader) that converged on the same envelope: a normalised total,
+ * per-criterion scores with comments, grader-authored artefacts, a confidence
+ * signal, an explicit human-review flag, and provenance.
+ *
+ * The SDK models the SHAPE and the arithmetic. It never calls a model, never
+ * holds a key, and never decides what a rubric means — that stays yours.
+ */
+
+/**
+ * Lifecycle of a deferred grade. A grade exists only in the `graded` state;
+ * every other state means "no grade, and here is why" — which is precisely the
+ * distinction that stops an ungraded submission being rendered as a zero.
+ */
+type GradingState = 'queued' | 'running' | 'graded' | 'failed' | 'skipped';
+/**
+ * Who produced a grade.
+ *
+ * - `'auto'` — a non-generative measurement engine, for example a
+ *   pronunciation-assessment service.
+ * - `'ai'` — a generative model.
+ * - `'human'` — a person.
+ */
+type GraderKind = 'ai' | 'human' | 'auto';
+/** Provenance of a grade, so a re-grade two years later is explicable. */
+interface Grader {
+    kind: GraderKind;
+    /** Identifier of the human grader, when `kind` is `'human'`. */
+    id?: string;
+    /** Model identifier, when `kind` is `'ai'` (e.g. a model name and version). */
+    model?: string;
+    /** Hash or id of the prompt/rubric revision used, for auditability. */
+    promptHash?: string;
+}
+/** Optional cost/usage telemetry emitted by an AI grader. */
+interface GraderUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    costUsd?: number;
+}
+/** A grader's verdict on one rubric criterion. */
+interface CriterionScore {
+    /** Matches a `WrittenResponseRubricCriterion.name` when a rubric is known. */
+    name: string;
+    /**
+     * The grader's score for this criterion, out of {@link CriterionScore.maxScore}
+     * (which defaults to 1, the SDK's scaled convention). Absent when the
+     * criterion is judged on an ordinal `band`.
+     */
+    score?: number;
+    /**
+     * What `score` is out of. Defaults to `1`.
+     *
+     * Real graders rarely work in [0,1]: rubrics come back out of 100, out of 9
+     * (CEFR/IELTS bands), or out of a points total that differs between
+     * criteria. Before this field the only way to use {@link gradeFromRubric}
+     * was to normalise by hand first — and a grader that skipped that step got
+     * its scores REJECTED, which pushed integrators back to letting the model
+     * compute the weighted total itself. That is precisely the arithmetic this
+     * SDK exists to take away from a language model.
+     *
+     * Set it per criterion, so a rubric mixing a /100 criterion with a /9 band
+     * score still composes. `gradeFromRubric` normalises `score / maxScore`
+     * before weighting; the resulting ratio must land in [0,1].
+     */
+    maxScore?: number;
+    /** Ordinal verdict when the rubric is banded rather than numeric (e.g. `"B1"`). */
+    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.
+     * 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;
+}
+/** A suggested correction anchored in the learner's own text. */
+interface InlineCorrection {
+    /** Verbatim span from the submission. */
+    original: string;
+    /** Suggested replacement. */
+    corrected: string;
+    explanation?: string;
+    /** Character offsets into the submitted text, so a UI can anchor it inline. */
+    range?: {
+        start: number;
+        end: number;
+    };
+    /** Error-type tag (`"article"`, `"tense"`, `"register"`). */
+    category?: string;
+}
+/**
+ * A grade that came back from an asynchronous grader. `score` is scaled
+ * [0,1] against `maxScore`, matching every other score in the SDK. A grader
+ * 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;
+    maxScore: number;
+    passed: boolean;
+    /** Narrative feedback addressed to the learner. */
+    feedback: string | null;
+    /** Per-criterion breakdown, when the grader worked against a rubric. */
+    criteria?: CriterionScore[];
+    /**
+     * Per-item marks carried by a grade — for example the per-word marks of a
+     * read-aloud grade. `outcomeFromGrade` does not mirror them onto the
+     * outcome; read `outcome.grade.details`.
+     */
+    details?: ScoringDetail[];
+    /** Corrections anchored in the learner's text. */
+    corrections?: InlineCorrection[];
+    /** Supporting observations the grader cited. */
+    evidence?: string[];
+    /** How the grader reached this verdict. */
+    rationale?: string;
+    /** The grader's own confidence — a signal for routing to human review. */
+    confidence?: 'high' | 'medium' | 'low';
+    /** The grader is unsure or the submission is atypical; route to a human. */
+    requiresHumanReview?: boolean;
+    grader?: Grader;
+    usage?: GraderUsage;
+    /** ISO 8601 timestamp of when the grade was produced. */
+    gradedAt?: string;
+}
+
 /**
  * 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.
@@ -72,6 +213,7 @@ declare function matchText(input: string, accepted: string | readonly string[],
  * 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
@@ -250,142 +392,20 @@ interface AiTextResult {
     /** 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.
- *
- * `evaluate()` can say a submission is `deferred` — graded later by an AI or a
- * human — but until now there was no type for the grade that comes BACK, so
- * every consumer invented one. The shapes here are the intersection of two
- * independent production graders (a rubric-based essay grader and a CEFR
- * speaking grader) that converged on the same envelope: a normalised total,
- * per-criterion scores with comments, grader-authored artefacts, a confidence
- * signal, an explicit human-review flag, and provenance.
- *
- * The SDK models the SHAPE and the arithmetic. It never calls a model, never
- * holds a key, and never decides what a rubric means — that stays yours.
- */
-
-/**
- * Lifecycle of a deferred grade. A grade exists only in the `graded` state;
- * every other state means "no grade, and here is why" — which is precisely the
- * distinction that stops an ungraded submission being rendered as a zero.
- */
-type GradingState = 'queued' | 'running' | 'graded' | 'failed' | 'skipped';
-/**
- * Who produced a grade.
- *
- * - `'auto'` — a non-generative measurement engine, for example a
- *   pronunciation-assessment service.
- * - `'ai'` — a generative model.
- * - `'human'` — a person.
- */
-type GraderKind = 'ai' | 'human' | 'auto';
-/** Provenance of a grade, so a re-grade two years later is explicable. */
-interface Grader {
-    kind: GraderKind;
-    /** Identifier of the human grader, when `kind` is `'human'`. */
-    id?: string;
-    /** Model identifier, when `kind` is `'ai'` (e.g. a model name and version). */
-    model?: string;
-    /** Hash or id of the prompt/rubric revision used, for auditability. */
-    promptHash?: string;
-}
-/** Optional cost/usage telemetry emitted by an AI grader. */
-interface GraderUsage {
-    promptTokens?: number;
-    completionTokens?: number;
-    costUsd?: number;
-}
-/** A grader's verdict on one rubric criterion. */
-interface CriterionScore {
-    /** Matches a `WrittenResponseRubricCriterion.name` when a rubric is known. */
-    name: string;
     /**
-     * The grader's score for this criterion, out of {@link CriterionScore.maxScore}
-     * (which defaults to 1, the SDK's scaled convention). Absent when the
-     * criterion is judged on an ordinal `band`.
-     */
-    score?: number;
-    /**
-     * What `score` is out of. Defaults to `1`.
-     *
-     * Real graders rarely work in [0,1]: rubrics come back out of 100, out of 9
-     * (CEFR/IELTS bands), or out of a points total that differs between
-     * criteria. Before this field the only way to use {@link gradeFromRubric}
-     * was to normalise by hand first — and a grader that skipped that step got
-     * its scores REJECTED, which pushed integrators back to letting the model
-     * compute the weighted total itself. That is precisely the arithmetic this
-     * SDK exists to take away from a language model.
+     * What the call cost, as the provider reported it to your port: the same
+     * {@link GraderUsage} a returned grade carries, so one shape covers help for
+     * a learner and marking by a grader.
      *
-     * Set it per criterion, so a rubric mixing a /100 criterion with a /9 band
-     * score still composes. `gradeFromRubric` normalises `score / maxScore`
-     * before weighting; the resulting ratio must land in [0,1].
-     */
-    maxScore?: number;
-    /** Ordinal verdict when the rubric is banded rather than numeric (e.g. `"B1"`). */
-    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?: number;
-    /** Not applicable to this submission (e.g. interaction on a monologue task). */
-    notApplicable?: boolean;
-}
-/** A suggested correction anchored in the learner's own text. */
-interface InlineCorrection {
-    /** Verbatim span from the submission. */
-    original: string;
-    /** Suggested replacement. */
-    corrected: string;
-    explanation?: string;
-    /** Character offsets into the submitted text, so a UI can anchor it inline. */
-    range?: {
-        start: number;
-        end: number;
-    };
-    /** Error-type tag (`"article"`, `"tense"`, `"register"`). */
-    category?: string;
-}
-/**
- * A grade that came back from an asynchronous grader. `score` is scaled
- * [0,1] against `maxScore`, matching every other score in the SDK. A grader
- * 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.
- */
-interface GradeRecord {
-    score: number;
-    maxScore: number;
-    passed: boolean;
-    /** Narrative feedback addressed to the learner. */
-    feedback: string | null;
-    /** Per-criterion breakdown, when the grader worked against a rubric. */
-    criteria?: CriterionScore[];
-    /**
-     * Per-item marks carried by a grade — for example the per-word marks of a
-     * read-aloud grade. `outcomeFromGrade` does not mirror them onto the
-     * outcome; read `outcome.grade.details`.
+     * The SDK never estimates it and never adds it up. It carries what a port
+     * sends through to `onInteraction`, beside the provenance, so the record of
+     * what a learner was shown and the record of what it cost are the same
+     * record. Numbers that are not finite and zero or more are dropped.
      */
-    details?: ScoringDetail[];
-    /** Corrections anchored in the learner's text. */
-    corrections?: InlineCorrection[];
-    /** Supporting observations the grader cited. */
-    evidence?: string[];
-    /** How the grader reached this verdict. */
-    rationale?: string;
-    /** The grader's own confidence — a signal for routing to human review. */
-    confidence?: 'high' | 'medium' | 'low';
-    /** The grader is unsure or the submission is atypical; route to a human. */
-    requiresHumanReview?: boolean;
-    grader?: Grader;
     usage?: GraderUsage;
-    /** ISO 8601 timestamp of when the grade was produced. */
-    gradedAt?: string;
 }
+/** Why a result was not shown. */
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer';
 
 /**
  * An xAPI Activity object — the thing a statement is about.
@@ -1388,8 +1408,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
@@ -1416,6 +1441,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';
     /**
@@ -1530,8 +1561,18 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
  * 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 & {});
+/** An AI explanation of the graded answer was shown (`provenance`, `usage` when sent). */
+ | 'ai-explanation-shown'
+/**
+ * An AI answer was refused, and the learner was told help was not available
+ * (`feature`, `reason` — an {@link AiRefusal} — and `hintNumber` for a hint).
+ *
+ * **The text itself is never carried**: a hint refused for revealing the
+ * answer contains the answer, and this event is logged. It is how a host
+ * watches its own model in production, where the development console warning
+ * it accompanies is silent.
+ */
+ | 'ai-help-refused' | (string & {});
 /** Fired by activity components on every discrete learner interaction. */
 interface InteractionEvent {
     /** The kind of interaction that occurred. */