@intellectif/lk-core 0.20.0 → 0.22.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { v as AiSupportedActivityType, g as AiActivityInput, k as AiFeature, Z as LearnerResponse, Y as ItemOutcome, j as AiExplanationRequest, o as AiGrade, p as AiHintRequest, ad as ScoringDetail, q as AiItemFacts, w as AiTextResult, u as AiRefusal, a as ActivityData, ai as ValidationError, f as ActivityType, b as ActivityDataMap, C as CriterionScore, Q as GradeRecord, a5 as NativeControlHint, d as ActivityMedia, af as ScoringResult, z as DeferredScoringPartial, E as DictationData, G as DictationLearnerResponse, J as FillInTheBlanksData, K as FillInTheBlanksLearnerResponse, N as GapSelectData, P as GapSelectLearnerResponse, a1 as MultipleChoiceData, a2 as MultipleChoiceLearnerResponse, a6 as ReadAloudData, a9 as ReadAloudLearnerResponse, ak as WrittenResponseData, al as WrittenResponseLearnerResponse } from './activity-f0bgZSTP.cjs';
-export { A as ActivityAiPermissions, c as ActivityFeedback, e as ActivityResult, h as AiBlankFact, i as AiDictationFacts, l as AiFillInTheBlanksFacts, m as AiGapFact, n as AiGapSelectFacts, r as AiMultipleChoiceFacts, s as AiOptionFact, t as AiProvenance, x as AiVerdict, y as AiWordFact, B as BlankConfig, D as DeferredReason, F as DictationEquivalence, H as DictationSlowMedia, I as DictationTolerance, L as GapSelectBank, M as GapSelectChoice, O as GapSelectGap, R as Grader, S as GraderKind, T as GraderUsage, U as GradingState, V as InlineCorrection, W as InteractionEvent, X as InteractionKind, _ as LearnerResponseMap, $ as MediaPlaybackPolicy, a0 as MediaTrack, a3 as MultipleChoiceOption, a4 as MultipleChoiceOptionMedia, a7 as ReadAloudDimension, a8 as ReadAloudDimensionWeight, aa as ReadAloudSlowMedia, ab as RecordingBounds, ac as RecordingRef, ae as ScoringOutcome, ag as TextMatchPolicy, ah as TextMatchResult, aj as ValidationResult, am as WrittenResponseRubric, an as WrittenResponseRubricCriterion, ao as XAPIActor, ap as XAPIConfig, aq as XAPIContext, ar as XAPIContextActivities, as as XAPIError, at as XAPIObject, au as XAPIResult, av as XAPIScore, aw as XAPIStatement, ax as XAPIVerbObject, ay as levenshteinDistance, az as matchText } from './activity-f0bgZSTP.cjs';
-import { ScoredItem, RoundingPolicy, CompositionPolicy, AssessmentScore } from './scoring.cjs';
-export { AssessmentSectionInput, Band, DEFAULT_PASS_THRESHOLD, DICTATION_MAX_ACCEPTED_TRANSCRIPTS, DICTATION_MAX_EQUIVALENCES, DICTATION_MAX_EQUIVALENCE_LENGTH, DICTATION_MAX_TEXT_LENGTH, DICTATION_MAX_TRANSCRIPT_LENGTH, DictationAlignment, DictationCharOp, DictationReference, DictationWordAlignment, GradeReadAloudOptions, PassFailureReason, READ_ALOUD_MAX_DIMENSION_WEIGHT, READ_ALOUD_MAX_REFERENCE_LENGTH, READ_ALOUD_MAX_SECONDS, READ_ALOUD_MAX_TAKES, ReadAloudWordAlignment, ReadAloudWordState, RoundingMode, SPEECH_ASSESSMENT_MAX_WORDS, ScoringOptions, SectionScore, SpeechAssessment, SpeechMeasurement, SpeechPhoneme, SpeechPhonemeCandidate, SpeechPlausibilityPolicy, SpeechSyllable, SpeechUnscorable, SpeechUnscorableCode, SpeechWord, SpeechWordError, WavInspection, WavInspectionPolicy, alignDictation, alignReadAloud, classifyBand, composeAssessmentScore, computePassThreshold, dictationReferenceWords, diffDictationChars, evaluate, gradeReadAloud, gte, inspectWav, outcomeFromUnscorable, roundGrade, score, validateSpeechAssessment } from './scoring.cjs';
-import { a5 as SequenceSlot, a4 as SequenceEntry, I as ItemGroup, i as MediaProgress } from './index-7S3-TLjT.cjs';
-export { A as AiPermissionsSchema, B as BlankConfigSchema, D as DictationDataSchema, a as DictationEquivalenceSchema, b as DictationSlowMediaSchema, c as DictationToleranceSchema, F as FeedbackSchema, d as FillInTheBlanksDataSchema, G as GapSelectBankSchema, e as GapSelectChoiceSchema, f as GapSelectDataSchema, g as GapSelectGapSchema, h as ItemGroupSchema, M as MediaPlaybackSchema, j as MediaSchema, k as MediaTimeline, l as MediaTimelineSchema, m as MediaTrackSchema, n as MediaUrlSchema, o as MultipleChoiceDataSchema, p as MultipleChoiceOptionMediaSchema, q as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as ReadAloudDataSchema, r as ReadAloudSlowMediaSchema, s as RedactedActivity, t as RedactedBlankConfig, u as RedactedBlankConfigSchema, v as RedactedDictationData, w as RedactedDictationDataSchema, x as RedactedDictationSlowMedia, y as RedactedDictationSlowMediaSchema, z as RedactedFillInTheBlanksData, C as RedactedFillInTheBlanksDataSchema, E as RedactedGapSelectBank, H as RedactedGapSelectBankSchema, J as RedactedGapSelectChoice, K as RedactedGapSelectChoiceSchema, L as RedactedGapSelectData, O as RedactedGapSelectDataSchema, P as RedactedGapSelectGap, Q as RedactedGapSelectGapSchema, S as RedactedItemGroupSchema, T as RedactedMediaSchema, U as RedactedMultipleChoiceData, V as RedactedMultipleChoiceDataSchema, W as RedactedMultipleChoiceOption, X as RedactedMultipleChoiceOptionMedia, Y as RedactedMultipleChoiceOptionMediaSchema, Z as RedactedMultipleChoiceOptionSchema, _ as RedactedReadAloudData, $ as RedactedReadAloudDataSchema, a0 as RedactedStimulus, a1 as RedactedStimulusSchema, a2 as RedactedWrittenResponseData, a3 as RedactedWrittenResponseDataSchema, a6 as SequenceSlotGroup, a7 as Stimulus, a8 as StimulusKind, a9 as StimulusSchema, aa as TextMatchPolicySchema, ab as TimelineChapter, ac as TimelineChapterSchema, ad as TimelineCue, ae as TimelineCueSchema, af as WrittenResponseDataSchema, ag as WrittenResponseRubricCriterionSchema, ah as WrittenResponseRubricSchema, ai as dictationJsonSchema, aj as fillInTheBlanksJsonSchema, ak as gapSelectJsonSchema, al as itemGroupJsonSchema, am as jsonSchemaFor, an as multipleChoiceJsonSchema, ao as readAloudJsonSchema, ap as stimulusJsonSchema, aq as validateActivity, ar as validateItemGroup, as as writtenResponseJsonSchema } from './index-7S3-TLjT.cjs';
+import { x as AiSupportedActivityType, g as AiActivityInput, l as AiFeature, a4 as LearnerResponse, a3 as ItemOutcome, k as AiExplanationRequest, p as AiGrade, q as AiHintRequest, ak as ScoringDetail, r as AiItemFacts, y as AiTextResult, v as AiRefusal, F as AiWritingFeedbackRequest, E as AiWritingFeedback, a as ActivityData, ap as ValidationError, f as ActivityType, b as ActivityDataMap, I as CriterionScore, X as GradeRecord, ac as NativeControlHint, d as ActivityMedia, am as ScoringResult, K as DeferredScoringPartial, L as DictationData, N as DictationLearnerResponse, Q as FillInTheBlanksData, R as FillInTheBlanksLearnerResponse, U as GapSelectData, W as GapSelectLearnerResponse, a8 as MultipleChoiceData, a9 as MultipleChoiceLearnerResponse, ad as ReadAloudData, ag as ReadAloudLearnerResponse, ar as WrittenResponseData, as as WrittenResponseLearnerResponse } from './activity-CYc7SD3d.cjs';
+export { A as ActivityAiPermissions, c as ActivityFeedback, e as ActivityResult, h as AiBlankFact, i as AiCriterionJudgement, j as AiDictationFacts, m as AiFillInTheBlanksFacts, n as AiGapFact, o as AiGapSelectFacts, s as AiMultipleChoiceFacts, t as AiOptionFact, u as AiProvenance, w as AiRubricCriterionFact, z as AiVerdict, B as AiWordFact, C as AiWritingCorrection, D as AiWritingFacts, G as AiWritingFeedbackResult, H as BlankConfig, J as DeferredReason, M as DictationEquivalence, O as DictationSlowMedia, P as DictationTolerance, S as GapSelectBank, T as GapSelectChoice, V as GapSelectGap, Y as Grader, Z as GraderKind, _ as GraderUsage, $ as GradingState, a0 as InlineCorrection, a1 as InteractionEvent, a2 as InteractionKind, a5 as LearnerResponseMap, a6 as MediaPlaybackPolicy, a7 as MediaTrack, aa as MultipleChoiceOption, ab as MultipleChoiceOptionMedia, ae as ReadAloudDimension, af as ReadAloudDimensionWeight, ah as ReadAloudSlowMedia, ai as RecordingBounds, aj as RecordingRef, al as ScoringOutcome, an as TextMatchPolicy, ao as TextMatchResult, aq as ValidationResult, at as WrittenResponseRubric, au as WrittenResponseRubricCriterion, av as XAPIActor, aw as XAPIConfig, ax as XAPIContext, ay as XAPIContextActivities, az as XAPIError, aA as XAPIObject, aB as XAPIResult, aC as XAPIScore, aD as XAPIStatement, aE as XAPIVerbObject, aF as levenshteinDistance, aG as matchText } from './activity-CYc7SD3d.cjs';
+import { ResolvedItemScoringPolicy, ItemScoringPolicy, ScoredItem, RoundingPolicy, CompositionPolicy, AssessmentScore } from './scoring.cjs';
+export { AssessmentSectionInput, Band, DEFAULT_ITEM_SCORING_POLICY, DEFAULT_PASS_THRESHOLD, DICTATION_MAX_ACCEPTED_TRANSCRIPTS, DICTATION_MAX_EQUIVALENCES, DICTATION_MAX_EQUIVALENCE_LENGTH, DICTATION_MAX_TEXT_LENGTH, DICTATION_MAX_TRANSCRIPT_LENGTH, DictationAlignment, DictationCharOp, DictationReference, DictationWordAlignment, EvaluateOptions, GradeReadAloudOptions, ITEM_SCORING_MAX_RETRIES, ItemScoringCount, ItemScoringPolicyIssue, ItemTriesOutcome, ItemTriesScore, ItemTry, ItemTryScore, PassFailureReason, READ_ALOUD_MAX_DIMENSION_WEIGHT, READ_ALOUD_MAX_REFERENCE_LENGTH, READ_ALOUD_MAX_SECONDS, READ_ALOUD_MAX_TAKES, ReadAloudWordAlignment, ReadAloudWordState, RoundingMode, SPEECH_ASSESSMENT_MAX_WORDS, ScoringOptions, SectionScore, SpeechAssessment, SpeechMeasurement, SpeechPhoneme, SpeechPhonemeCandidate, SpeechPlausibilityPolicy, SpeechSyllable, SpeechUnscorable, SpeechUnscorableCode, SpeechWord, SpeechWordError, WavInspection, WavInspectionPolicy, alignDictation, alignReadAloud, classifyBand, composeAssessmentScore, computePassThreshold, dictationReferenceWords, diffDictationChars, evaluate, evaluateTries, gradeReadAloud, gte, inspectWav, outcomeFromUnscorable, resolveItemScoringPolicy, roundGrade, score, scoreTries, validateItemScoringPolicy, validateSpeechAssessment } from './scoring.cjs';
+import { a5 as SequenceSlot, a4 as SequenceEntry, I as ItemGroup, i as MediaProgress } from './index-CxxiNSSH.cjs';
+export { A as AiPermissionsSchema, B as BlankConfigSchema, D as DictationDataSchema, a as DictationEquivalenceSchema, b as DictationSlowMediaSchema, c as DictationToleranceSchema, F as FeedbackSchema, d as FillInTheBlanksDataSchema, G as GapSelectBankSchema, e as GapSelectChoiceSchema, f as GapSelectDataSchema, g as GapSelectGapSchema, h as ItemGroupSchema, M as MediaPlaybackSchema, j as MediaSchema, k as MediaTimeline, l as MediaTimelineSchema, m as MediaTrackSchema, n as MediaUrlSchema, o as MultipleChoiceDataSchema, p as MultipleChoiceOptionMediaSchema, q as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as ReadAloudDataSchema, r as ReadAloudSlowMediaSchema, s as RedactedActivity, t as RedactedBlankConfig, u as RedactedBlankConfigSchema, v as RedactedDictationData, w as RedactedDictationDataSchema, x as RedactedDictationSlowMedia, y as RedactedDictationSlowMediaSchema, z as RedactedFillInTheBlanksData, C as RedactedFillInTheBlanksDataSchema, E as RedactedGapSelectBank, H as RedactedGapSelectBankSchema, J as RedactedGapSelectChoice, K as RedactedGapSelectChoiceSchema, L as RedactedGapSelectData, O as RedactedGapSelectDataSchema, P as RedactedGapSelectGap, Q as RedactedGapSelectGapSchema, S as RedactedItemGroupSchema, T as RedactedMediaSchema, U as RedactedMultipleChoiceData, V as RedactedMultipleChoiceDataSchema, W as RedactedMultipleChoiceOption, X as RedactedMultipleChoiceOptionMedia, Y as RedactedMultipleChoiceOptionMediaSchema, Z as RedactedMultipleChoiceOptionSchema, _ as RedactedReadAloudData, $ as RedactedReadAloudDataSchema, a0 as RedactedStimulus, a1 as RedactedStimulusSchema, a2 as RedactedWrittenResponseData, a3 as RedactedWrittenResponseDataSchema, a6 as SequenceSlotGroup, a7 as Stimulus, a8 as StimulusKind, a9 as StimulusSchema, aa as TextMatchPolicySchema, ab as TimelineChapter, ac as TimelineChapterSchema, ad as TimelineCue, ae as TimelineCueSchema, af as WrittenResponseDataSchema, ag as WrittenResponseRubricCriterionSchema, ah as WrittenResponseRubricSchema, ai as dictationJsonSchema, aj as fillInTheBlanksJsonSchema, ak as gapSelectJsonSchema, al as itemGroupJsonSchema, am as jsonSchemaFor, an as multipleChoiceJsonSchema, ao as readAloudJsonSchema, ap as stimulusJsonSchema, aq as validateActivity, ar as validateItemGroup, as as writtenResponseJsonSchema } from './index-CxxiNSSH.cjs';
 import { z } from 'zod/v4';
 export { AnsweredStatementParams, CompletedStatementParams, SubmittedStatementParams, XAPIObjectParams, XAPIStatementParams, XAPIVerb, XAPIVerbKey, XAPI_VERB_DISPLAY, validateXAPIStatement, xAPIBuilder, xapiDefinitionFor } from './xapi.cjs';
 
@@ -17,14 +17,18 @@ declare const AI_HINT_TYPES: readonly AiSupportedActivityType[];
 /** The longest AI text shown, in code points. Longer is refused, not cut. */
 declare const AI_TEXT_MAX_LENGTH = 2000;
 /**
- * Whether the SDK supports `feature` for this activity type. A type it builds
- * no facts for — a written response, a read-aloud, a consumer's own — has
- * neither.
+ * Whether the SDK supports `feature` for this activity type: explanations and
+ * hints for the types it builds facts for, and writing feedback for a written
+ * response. A read-aloud, or a consumer's own type, has none.
  */
 declare function aiSupports(activityType: string, feature: AiFeature): boolean;
 /**
  * Whether the item's author allows `feature`. Only an explicit `false`
  * switches it off: an author can refuse a feature, never force one on.
+ *
+ * Writing feedback reads `explanations`: both are a model's words about the
+ * learner's own answer, and an author who switched one off has switched off
+ * the other.
  */
 declare function aiAllowedByContent(data: AiActivityInput, feature: AiFeature): boolean;
 /** A grade as an explanation must speak to it: all marks, some, or none. */
@@ -128,6 +132,59 @@ declare function checkAiHint(raw: unknown, request: AiHintRequest): {
  */
 declare function hintRevealsAnswer(facts: AiItemFacts, hint: string): boolean;
 
+/** The most corrections one piece of writing feedback may carry. More is refused, not cut. */
+declare const AI_WRITING_MAX_CORRECTIONS = 20;
+/** The longest quote, correction, explanation or criterion comment, in code points. */
+declare const AI_WRITING_MAX_FIELD_LENGTH = 500;
+/**
+ * The request for feedback on a draft, or `null` when there is none to give:
+ * not a written response, an author who switched explanations off (writing
+ * feedback reads `ai.explanations`), a redacted item — feedback is for
+ * practice, where the item is whole — or a draft with nothing in it.
+ *
+ * The facts are the task as the learner saw it, the draft verbatim with its
+ * word count recomputed as the grader will count it, and the rubric the answer
+ * will be graded on. `previousFeedback` is the text of the feedback already
+ * shown on earlier drafts, so a model can speak to what changed.
+ */
+declare function aiWritingFeedbackRequest(input: {
+    data: AiActivityInput;
+    response: LearnerResponse | null;
+    previousFeedback?: readonly string[];
+    learnerLocale?: string;
+}): AiWritingFeedbackRequest | null;
+/**
+ * Checks writing feedback a port returned for `request`, and turns it into what
+ * a learner is shown. The SDK shows a model's feedback whole or not at all: it
+ * never drops the part it doubts and shows the rest.
+ *
+ * - **The text** is read as every AI text is (`readAiTextResult`): plain text,
+ *   not empty, at most {@link AI_TEXT_MAX_LENGTH} code points.
+ * - **Every correction must quote the draft** — the check only this SDK can run.
+ *   The SDK finds each quote in the draft itself, typographic quotes and runs of
+ *   whitespace aside, and anchors it there; a range the model claims must hold
+ *   the quote. A correction of words the learner did not write refuses the
+ *   whole reply as `misquotes-answer`, as a hint that gives the answer away
+ *   refuses the hint. The `original` shown is the draft's own text at the range.
+ *   At most {@link AI_WRITING_MAX_CORRECTIONS}; a correction that changes
+ *   nothing is `malformed`.
+ * - **Criteria are judgements; the arithmetic is the SDK's.** Each names a
+ *   criterion of the item's rubric, once; its score, when it has one, is a
+ *   score out of its `maxScore`. The rubric's weights are attached, whatever
+ *   the model sent. Anything else is `malformed`, as is any criterion on an
+ *   item with no rubric.
+ * - **`indicativeScore`** is the rubric's weighted total, computed as
+ *   `gradeFromRubric` computes a grade, when every criterion of the rubric was
+ *   judged; `null` otherwise. An indication, never a grade.
+ */
+declare function checkAiWritingFeedback(raw: unknown, request: AiWritingFeedbackRequest): {
+    ok: true;
+    feedback: AiWritingFeedback;
+} | {
+    ok: false;
+    refusal: AiRefusal;
+};
+
 /**
  * How a paper is delivered: what a learner is shown around the questions, as
  * the school running it decides — separately from the content, so that one
@@ -308,6 +365,13 @@ interface AttemptPlan {
      * Absent when `planAttempt` was given none. Part of `planHash` when present.
      */
     delivery?: ResolvedDeliveryPolicy;
+    /**
+     * The scoring policy the attempt was sat under, every setting spelled out:
+     * the tries each question gave, which counted, and what tries and hints
+     * cost. Absent when `planAttempt` was given none. Part of `planHash` when
+     * present.
+     */
+    scoring?: ResolvedItemScoringPolicy;
     slots: AttemptPlanSlot[];
     /** Sum of every slot's `points`, frozen. The denominator of the paper. */
     totalPoints: number;
@@ -348,6 +412,12 @@ interface AttemptPlanDrift {
      * policy has exactly the shape it had before policies existed.
      */
     deliveryChanged?: true;
+    /**
+     * The scoring policy differs: one plan records a policy the other does not,
+     * or a setting differs. The same answers are worth something else under
+     * another policy, so it breaks `matches`. Present only when it is `true`.
+     */
+    scoringChanged?: true;
 }
 
 /** Options for {@link planAttempt}. */
@@ -386,6 +456,19 @@ interface PlanAttemptOptions<TItem> {
      *         record an appeal reads.
      */
     delivery?: DeliveryPolicy | null;
+    /**
+     * The scoring policy this attempt is sat under — how many tries each
+     * question gives, which one counts, and what tries and hints cost. Frozen
+     * into the plan with every setting spelled out, like `delivery`, and for a
+     * stronger reason: every setting in it moves a grade, so a re-grade must
+     * apply the rules the learner sat under, not today's.
+     *
+     * Recorded only when given: a plan made without one is byte-identical to a
+     * plan made before scoring policies existed, `planHash` included.
+     *
+     * @throws Error when the policy does not pass `validateItemScoringPolicy`.
+     */
+    scoring?: ItemScoringPolicy | null;
 }
 /**
  * Freezes what an attempt is being served: the presented order, each slot's
@@ -1612,4 +1695,4 @@ interface ThemeTokens {
     '--lk-transition-base': string;
 }
 
-export { AI_EXPLANATION_TYPES, AI_HINT_TYPES, AI_TEXT_MAX_LENGTH, ActivityData, ActivityDataMap, ActivityMedia, ActivitySchemaError, ActivityType, type ActivityTypeAuthoring, type ActivityTypeDescriptor, type ActivityTypeInterop, type ActivityTypeScoring, AiActivityInput, AiExplanationRequest, AiFeature, AiGrade, AiHintRequest, AiItemFacts, AiRefusal, AiSupportedActivityType, AiTextResult, AssessmentScore, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CompositionPolicy, CriterionScore, DeferredScoringError, DeferredScoringPartial, type DeliveryPolicy, type DeliveryPolicyIssue, DictationData, DictationLearnerResponse, type DraftComplete, type DraftContext, type DraftIssue, type DraftNotComplete, type DraftSeverity, type DraftValidationResult, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, GapSelectData, GapSelectLearnerResponse, type GradeFromRubricOptions, GradeRecord, INTERACTIVE_VIDEO_ITEM_TYPES, type InteractiveVideoItemType, ItemGroup, ItemOutcome, LearnerResponse, type MediaBudgetRef, type MediaPlayClaim, type MediaPlayGrant, type MediaPlayLedger, type MediaPlayLedgerEntry, MediaProgress, type MissingOutcomePolicy, MultipleChoiceData, MultipleChoiceLearnerResponse, NativeControlHint, OPEN_DELIVERY_POLICY, type PartialScoringResult, type PlanAttemptOptions, type PlannableEntry, ReadAloudData, ReadAloudLearnerResponse, type RedactOptions, type RedactedActivityData, type RedactedItemGroup, RedactedScoringError, type RegisteredActivityTypeDescriptor, type ResolvedDeliveryPolicy, type ResolvedPlaybackPolicy, type ResponseDiffEntry, RoundingPolicy, ScoredItem, ScoringDetail, ScoringResult, type SeededShuffleOptions, type Sensitivity, SequenceEntry, SequenceSlot, type ShuffleVersion, TIMELINE_MAX_CHAPTERS, TIMELINE_MAX_ITEMS, TIMELINE_MAX_QUIZZES, TIMELINE_MAX_TITLE_LENGTH, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, aiAllowedByContent, aiExplanationRequest, aiGradeOf, aiHintRequest, aiSupports, assertRedacted, assertRedactedItemGroup, buildAiFacts, canonicalJson, checkAiExplanation, checkAiHint, combineDeliveryPolicies, composeTimelineScore, contentHash, countWords, createDraft, createInteractiveVideoDraft, createItemGroupDraft, defineActivityType, dictationType, diffResponses, entryKeyOf, fillInTheBlanksType, fingerprint, flattenSequence, gapSelectType, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, hintRevealsAnswer, isInteractiveVideoItemType, isItemGroup, multipleChoiceType, outcomeFromGrade, planAttempt, planMediaBudgets, readAiTextResult, readAloudType, readMediaProgress, redact, redactItemGroup, registerActivityType, registeredActivityTypes, resolveDeliveryPolicy, resolvePlaybackPolicy, restoreAttemptState, restoreMediaPlayLedger, scoredItemsFromPlan, seededShuffle, serializeAttemptState, serializeMediaPlayLedger, slotMediaKey, stimulusMediaKey, validateDeliveryPolicy, validateDraft, validateItemGroupDraft, verifyAttemptPlan, writtenResponseType };
+export { AI_EXPLANATION_TYPES, AI_HINT_TYPES, AI_TEXT_MAX_LENGTH, AI_WRITING_MAX_CORRECTIONS, AI_WRITING_MAX_FIELD_LENGTH, ActivityData, ActivityDataMap, ActivityMedia, ActivitySchemaError, ActivityType, type ActivityTypeAuthoring, type ActivityTypeDescriptor, type ActivityTypeInterop, type ActivityTypeScoring, AiActivityInput, AiExplanationRequest, AiFeature, AiGrade, AiHintRequest, AiItemFacts, AiRefusal, AiSupportedActivityType, AiTextResult, AiWritingFeedback, AiWritingFeedbackRequest, AssessmentScore, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CompositionPolicy, CriterionScore, DeferredScoringError, DeferredScoringPartial, type DeliveryPolicy, type DeliveryPolicyIssue, DictationData, DictationLearnerResponse, type DraftComplete, type DraftContext, type DraftIssue, type DraftNotComplete, type DraftSeverity, type DraftValidationResult, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, GapSelectData, GapSelectLearnerResponse, type GradeFromRubricOptions, GradeRecord, INTERACTIVE_VIDEO_ITEM_TYPES, type InteractiveVideoItemType, ItemGroup, ItemOutcome, ItemScoringPolicy, LearnerResponse, type MediaBudgetRef, type MediaPlayClaim, type MediaPlayGrant, type MediaPlayLedger, type MediaPlayLedgerEntry, MediaProgress, type MissingOutcomePolicy, MultipleChoiceData, MultipleChoiceLearnerResponse, NativeControlHint, OPEN_DELIVERY_POLICY, type PartialScoringResult, type PlanAttemptOptions, type PlannableEntry, ReadAloudData, ReadAloudLearnerResponse, type RedactOptions, type RedactedActivityData, type RedactedItemGroup, RedactedScoringError, type RegisteredActivityTypeDescriptor, type ResolvedDeliveryPolicy, ResolvedItemScoringPolicy, type ResolvedPlaybackPolicy, type ResponseDiffEntry, RoundingPolicy, ScoredItem, ScoringDetail, ScoringResult, type SeededShuffleOptions, type Sensitivity, SequenceEntry, SequenceSlot, type ShuffleVersion, TIMELINE_MAX_CHAPTERS, TIMELINE_MAX_ITEMS, TIMELINE_MAX_QUIZZES, TIMELINE_MAX_TITLE_LENGTH, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, aiAllowedByContent, aiExplanationRequest, aiGradeOf, aiHintRequest, aiSupports, aiWritingFeedbackRequest, assertRedacted, assertRedactedItemGroup, buildAiFacts, canonicalJson, checkAiExplanation, checkAiHint, checkAiWritingFeedback, combineDeliveryPolicies, composeTimelineScore, contentHash, countWords, createDraft, createInteractiveVideoDraft, createItemGroupDraft, defineActivityType, dictationType, diffResponses, entryKeyOf, fillInTheBlanksType, fingerprint, flattenSequence, gapSelectType, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, hintRevealsAnswer, isInteractiveVideoItemType, isItemGroup, multipleChoiceType, outcomeFromGrade, planAttempt, planMediaBudgets, readAiTextResult, readAloudType, readMediaProgress, redact, redactItemGroup, registerActivityType, registeredActivityTypes, resolveDeliveryPolicy, resolvePlaybackPolicy, restoreAttemptState, restoreMediaPlayLedger, scoredItemsFromPlan, seededShuffle, serializeAttemptState, serializeMediaPlayLedger, slotMediaKey, stimulusMediaKey, validateDeliveryPolicy, validateDraft, validateItemGroupDraft, verifyAttemptPlan, writtenResponseType };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { v as AiSupportedActivityType, g as AiActivityInput, k as AiFeature, Z as LearnerResponse, Y as ItemOutcome, j as AiExplanationRequest, o as AiGrade, p as AiHintRequest, ad as ScoringDetail, q as AiItemFacts, w as AiTextResult, u as AiRefusal, a as ActivityData, ai as ValidationError, f as ActivityType, b as ActivityDataMap, C as CriterionScore, Q as GradeRecord, a5 as NativeControlHint, d as ActivityMedia, af as ScoringResult, z as DeferredScoringPartial, E as DictationData, G as DictationLearnerResponse, J as FillInTheBlanksData, K as FillInTheBlanksLearnerResponse, N as GapSelectData, P as GapSelectLearnerResponse, a1 as MultipleChoiceData, a2 as MultipleChoiceLearnerResponse, a6 as ReadAloudData, a9 as ReadAloudLearnerResponse, ak as WrittenResponseData, al as WrittenResponseLearnerResponse } from './activity-f0bgZSTP.js';
-export { A as ActivityAiPermissions, c as ActivityFeedback, e as ActivityResult, h as AiBlankFact, i as AiDictationFacts, l as AiFillInTheBlanksFacts, m as AiGapFact, n as AiGapSelectFacts, r as AiMultipleChoiceFacts, s as AiOptionFact, t as AiProvenance, x as AiVerdict, y as AiWordFact, B as BlankConfig, D as DeferredReason, F as DictationEquivalence, H as DictationSlowMedia, I as DictationTolerance, L as GapSelectBank, M as GapSelectChoice, O as GapSelectGap, R as Grader, S as GraderKind, T as GraderUsage, U as GradingState, V as InlineCorrection, W as InteractionEvent, X as InteractionKind, _ as LearnerResponseMap, $ as MediaPlaybackPolicy, a0 as MediaTrack, a3 as MultipleChoiceOption, a4 as MultipleChoiceOptionMedia, a7 as ReadAloudDimension, a8 as ReadAloudDimensionWeight, aa as ReadAloudSlowMedia, ab as RecordingBounds, ac as RecordingRef, ae as ScoringOutcome, ag as TextMatchPolicy, ah as TextMatchResult, aj as ValidationResult, am as WrittenResponseRubric, an as WrittenResponseRubricCriterion, ao as XAPIActor, ap as XAPIConfig, aq as XAPIContext, ar as XAPIContextActivities, as as XAPIError, at as XAPIObject, au as XAPIResult, av as XAPIScore, aw as XAPIStatement, ax as XAPIVerbObject, ay as levenshteinDistance, az as matchText } from './activity-f0bgZSTP.js';
-import { ScoredItem, RoundingPolicy, CompositionPolicy, AssessmentScore } from './scoring.js';
-export { AssessmentSectionInput, Band, DEFAULT_PASS_THRESHOLD, DICTATION_MAX_ACCEPTED_TRANSCRIPTS, DICTATION_MAX_EQUIVALENCES, DICTATION_MAX_EQUIVALENCE_LENGTH, DICTATION_MAX_TEXT_LENGTH, DICTATION_MAX_TRANSCRIPT_LENGTH, DictationAlignment, DictationCharOp, DictationReference, DictationWordAlignment, GradeReadAloudOptions, PassFailureReason, READ_ALOUD_MAX_DIMENSION_WEIGHT, READ_ALOUD_MAX_REFERENCE_LENGTH, READ_ALOUD_MAX_SECONDS, READ_ALOUD_MAX_TAKES, ReadAloudWordAlignment, ReadAloudWordState, RoundingMode, SPEECH_ASSESSMENT_MAX_WORDS, ScoringOptions, SectionScore, SpeechAssessment, SpeechMeasurement, SpeechPhoneme, SpeechPhonemeCandidate, SpeechPlausibilityPolicy, SpeechSyllable, SpeechUnscorable, SpeechUnscorableCode, SpeechWord, SpeechWordError, WavInspection, WavInspectionPolicy, alignDictation, alignReadAloud, classifyBand, composeAssessmentScore, computePassThreshold, dictationReferenceWords, diffDictationChars, evaluate, gradeReadAloud, gte, inspectWav, outcomeFromUnscorable, roundGrade, score, validateSpeechAssessment } from './scoring.js';
-import { a5 as SequenceSlot, a4 as SequenceEntry, I as ItemGroup, i as MediaProgress } from './index-BA9f2ydg.js';
-export { A as AiPermissionsSchema, B as BlankConfigSchema, D as DictationDataSchema, a as DictationEquivalenceSchema, b as DictationSlowMediaSchema, c as DictationToleranceSchema, F as FeedbackSchema, d as FillInTheBlanksDataSchema, G as GapSelectBankSchema, e as GapSelectChoiceSchema, f as GapSelectDataSchema, g as GapSelectGapSchema, h as ItemGroupSchema, M as MediaPlaybackSchema, j as MediaSchema, k as MediaTimeline, l as MediaTimelineSchema, m as MediaTrackSchema, n as MediaUrlSchema, o as MultipleChoiceDataSchema, p as MultipleChoiceOptionMediaSchema, q as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as ReadAloudDataSchema, r as ReadAloudSlowMediaSchema, s as RedactedActivity, t as RedactedBlankConfig, u as RedactedBlankConfigSchema, v as RedactedDictationData, w as RedactedDictationDataSchema, x as RedactedDictationSlowMedia, y as RedactedDictationSlowMediaSchema, z as RedactedFillInTheBlanksData, C as RedactedFillInTheBlanksDataSchema, E as RedactedGapSelectBank, H as RedactedGapSelectBankSchema, J as RedactedGapSelectChoice, K as RedactedGapSelectChoiceSchema, L as RedactedGapSelectData, O as RedactedGapSelectDataSchema, P as RedactedGapSelectGap, Q as RedactedGapSelectGapSchema, S as RedactedItemGroupSchema, T as RedactedMediaSchema, U as RedactedMultipleChoiceData, V as RedactedMultipleChoiceDataSchema, W as RedactedMultipleChoiceOption, X as RedactedMultipleChoiceOptionMedia, Y as RedactedMultipleChoiceOptionMediaSchema, Z as RedactedMultipleChoiceOptionSchema, _ as RedactedReadAloudData, $ as RedactedReadAloudDataSchema, a0 as RedactedStimulus, a1 as RedactedStimulusSchema, a2 as RedactedWrittenResponseData, a3 as RedactedWrittenResponseDataSchema, a6 as SequenceSlotGroup, a7 as Stimulus, a8 as StimulusKind, a9 as StimulusSchema, aa as TextMatchPolicySchema, ab as TimelineChapter, ac as TimelineChapterSchema, ad as TimelineCue, ae as TimelineCueSchema, af as WrittenResponseDataSchema, ag as WrittenResponseRubricCriterionSchema, ah as WrittenResponseRubricSchema, ai as dictationJsonSchema, aj as fillInTheBlanksJsonSchema, ak as gapSelectJsonSchema, al as itemGroupJsonSchema, am as jsonSchemaFor, an as multipleChoiceJsonSchema, ao as readAloudJsonSchema, ap as stimulusJsonSchema, aq as validateActivity, ar as validateItemGroup, as as writtenResponseJsonSchema } from './index-BA9f2ydg.js';
+import { x as AiSupportedActivityType, g as AiActivityInput, l as AiFeature, a4 as LearnerResponse, a3 as ItemOutcome, k as AiExplanationRequest, p as AiGrade, q as AiHintRequest, ak as ScoringDetail, r as AiItemFacts, y as AiTextResult, v as AiRefusal, F as AiWritingFeedbackRequest, E as AiWritingFeedback, a as ActivityData, ap as ValidationError, f as ActivityType, b as ActivityDataMap, I as CriterionScore, X as GradeRecord, ac as NativeControlHint, d as ActivityMedia, am as ScoringResult, K as DeferredScoringPartial, L as DictationData, N as DictationLearnerResponse, Q as FillInTheBlanksData, R as FillInTheBlanksLearnerResponse, U as GapSelectData, W as GapSelectLearnerResponse, a8 as MultipleChoiceData, a9 as MultipleChoiceLearnerResponse, ad as ReadAloudData, ag as ReadAloudLearnerResponse, ar as WrittenResponseData, as as WrittenResponseLearnerResponse } from './activity-CYc7SD3d.js';
+export { A as ActivityAiPermissions, c as ActivityFeedback, e as ActivityResult, h as AiBlankFact, i as AiCriterionJudgement, j as AiDictationFacts, m as AiFillInTheBlanksFacts, n as AiGapFact, o as AiGapSelectFacts, s as AiMultipleChoiceFacts, t as AiOptionFact, u as AiProvenance, w as AiRubricCriterionFact, z as AiVerdict, B as AiWordFact, C as AiWritingCorrection, D as AiWritingFacts, G as AiWritingFeedbackResult, H as BlankConfig, J as DeferredReason, M as DictationEquivalence, O as DictationSlowMedia, P as DictationTolerance, S as GapSelectBank, T as GapSelectChoice, V as GapSelectGap, Y as Grader, Z as GraderKind, _ as GraderUsage, $ as GradingState, a0 as InlineCorrection, a1 as InteractionEvent, a2 as InteractionKind, a5 as LearnerResponseMap, a6 as MediaPlaybackPolicy, a7 as MediaTrack, aa as MultipleChoiceOption, ab as MultipleChoiceOptionMedia, ae as ReadAloudDimension, af as ReadAloudDimensionWeight, ah as ReadAloudSlowMedia, ai as RecordingBounds, aj as RecordingRef, al as ScoringOutcome, an as TextMatchPolicy, ao as TextMatchResult, aq as ValidationResult, at as WrittenResponseRubric, au as WrittenResponseRubricCriterion, av as XAPIActor, aw as XAPIConfig, ax as XAPIContext, ay as XAPIContextActivities, az as XAPIError, aA as XAPIObject, aB as XAPIResult, aC as XAPIScore, aD as XAPIStatement, aE as XAPIVerbObject, aF as levenshteinDistance, aG as matchText } from './activity-CYc7SD3d.js';
+import { ResolvedItemScoringPolicy, ItemScoringPolicy, ScoredItem, RoundingPolicy, CompositionPolicy, AssessmentScore } from './scoring.js';
+export { AssessmentSectionInput, Band, DEFAULT_ITEM_SCORING_POLICY, DEFAULT_PASS_THRESHOLD, DICTATION_MAX_ACCEPTED_TRANSCRIPTS, DICTATION_MAX_EQUIVALENCES, DICTATION_MAX_EQUIVALENCE_LENGTH, DICTATION_MAX_TEXT_LENGTH, DICTATION_MAX_TRANSCRIPT_LENGTH, DictationAlignment, DictationCharOp, DictationReference, DictationWordAlignment, EvaluateOptions, GradeReadAloudOptions, ITEM_SCORING_MAX_RETRIES, ItemScoringCount, ItemScoringPolicyIssue, ItemTriesOutcome, ItemTriesScore, ItemTry, ItemTryScore, PassFailureReason, READ_ALOUD_MAX_DIMENSION_WEIGHT, READ_ALOUD_MAX_REFERENCE_LENGTH, READ_ALOUD_MAX_SECONDS, READ_ALOUD_MAX_TAKES, ReadAloudWordAlignment, ReadAloudWordState, RoundingMode, SPEECH_ASSESSMENT_MAX_WORDS, ScoringOptions, SectionScore, SpeechAssessment, SpeechMeasurement, SpeechPhoneme, SpeechPhonemeCandidate, SpeechPlausibilityPolicy, SpeechSyllable, SpeechUnscorable, SpeechUnscorableCode, SpeechWord, SpeechWordError, WavInspection, WavInspectionPolicy, alignDictation, alignReadAloud, classifyBand, composeAssessmentScore, computePassThreshold, dictationReferenceWords, diffDictationChars, evaluate, evaluateTries, gradeReadAloud, gte, inspectWav, outcomeFromUnscorable, resolveItemScoringPolicy, roundGrade, score, scoreTries, validateItemScoringPolicy, validateSpeechAssessment } from './scoring.js';
+import { a5 as SequenceSlot, a4 as SequenceEntry, I as ItemGroup, i as MediaProgress } from './index-0Z3-nnAP.js';
+export { A as AiPermissionsSchema, B as BlankConfigSchema, D as DictationDataSchema, a as DictationEquivalenceSchema, b as DictationSlowMediaSchema, c as DictationToleranceSchema, F as FeedbackSchema, d as FillInTheBlanksDataSchema, G as GapSelectBankSchema, e as GapSelectChoiceSchema, f as GapSelectDataSchema, g as GapSelectGapSchema, h as ItemGroupSchema, M as MediaPlaybackSchema, j as MediaSchema, k as MediaTimeline, l as MediaTimelineSchema, m as MediaTrackSchema, n as MediaUrlSchema, o as MultipleChoiceDataSchema, p as MultipleChoiceOptionMediaSchema, q as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as ReadAloudDataSchema, r as ReadAloudSlowMediaSchema, s as RedactedActivity, t as RedactedBlankConfig, u as RedactedBlankConfigSchema, v as RedactedDictationData, w as RedactedDictationDataSchema, x as RedactedDictationSlowMedia, y as RedactedDictationSlowMediaSchema, z as RedactedFillInTheBlanksData, C as RedactedFillInTheBlanksDataSchema, E as RedactedGapSelectBank, H as RedactedGapSelectBankSchema, J as RedactedGapSelectChoice, K as RedactedGapSelectChoiceSchema, L as RedactedGapSelectData, O as RedactedGapSelectDataSchema, P as RedactedGapSelectGap, Q as RedactedGapSelectGapSchema, S as RedactedItemGroupSchema, T as RedactedMediaSchema, U as RedactedMultipleChoiceData, V as RedactedMultipleChoiceDataSchema, W as RedactedMultipleChoiceOption, X as RedactedMultipleChoiceOptionMedia, Y as RedactedMultipleChoiceOptionMediaSchema, Z as RedactedMultipleChoiceOptionSchema, _ as RedactedReadAloudData, $ as RedactedReadAloudDataSchema, a0 as RedactedStimulus, a1 as RedactedStimulusSchema, a2 as RedactedWrittenResponseData, a3 as RedactedWrittenResponseDataSchema, a6 as SequenceSlotGroup, a7 as Stimulus, a8 as StimulusKind, a9 as StimulusSchema, aa as TextMatchPolicySchema, ab as TimelineChapter, ac as TimelineChapterSchema, ad as TimelineCue, ae as TimelineCueSchema, af as WrittenResponseDataSchema, ag as WrittenResponseRubricCriterionSchema, ah as WrittenResponseRubricSchema, ai as dictationJsonSchema, aj as fillInTheBlanksJsonSchema, ak as gapSelectJsonSchema, al as itemGroupJsonSchema, am as jsonSchemaFor, an as multipleChoiceJsonSchema, ao as readAloudJsonSchema, ap as stimulusJsonSchema, aq as validateActivity, ar as validateItemGroup, as as writtenResponseJsonSchema } from './index-0Z3-nnAP.js';
 import { z } from 'zod/v4';
 export { AnsweredStatementParams, CompletedStatementParams, SubmittedStatementParams, XAPIObjectParams, XAPIStatementParams, XAPIVerb, XAPIVerbKey, XAPI_VERB_DISPLAY, validateXAPIStatement, xAPIBuilder, xapiDefinitionFor } from './xapi.js';
 
@@ -17,14 +17,18 @@ declare const AI_HINT_TYPES: readonly AiSupportedActivityType[];
 /** The longest AI text shown, in code points. Longer is refused, not cut. */
 declare const AI_TEXT_MAX_LENGTH = 2000;
 /**
- * Whether the SDK supports `feature` for this activity type. A type it builds
- * no facts for — a written response, a read-aloud, a consumer's own — has
- * neither.
+ * Whether the SDK supports `feature` for this activity type: explanations and
+ * hints for the types it builds facts for, and writing feedback for a written
+ * response. A read-aloud, or a consumer's own type, has none.
  */
 declare function aiSupports(activityType: string, feature: AiFeature): boolean;
 /**
  * Whether the item's author allows `feature`. Only an explicit `false`
  * switches it off: an author can refuse a feature, never force one on.
+ *
+ * Writing feedback reads `explanations`: both are a model's words about the
+ * learner's own answer, and an author who switched one off has switched off
+ * the other.
  */
 declare function aiAllowedByContent(data: AiActivityInput, feature: AiFeature): boolean;
 /** A grade as an explanation must speak to it: all marks, some, or none. */
@@ -128,6 +132,59 @@ declare function checkAiHint(raw: unknown, request: AiHintRequest): {
  */
 declare function hintRevealsAnswer(facts: AiItemFacts, hint: string): boolean;
 
+/** The most corrections one piece of writing feedback may carry. More is refused, not cut. */
+declare const AI_WRITING_MAX_CORRECTIONS = 20;
+/** The longest quote, correction, explanation or criterion comment, in code points. */
+declare const AI_WRITING_MAX_FIELD_LENGTH = 500;
+/**
+ * The request for feedback on a draft, or `null` when there is none to give:
+ * not a written response, an author who switched explanations off (writing
+ * feedback reads `ai.explanations`), a redacted item — feedback is for
+ * practice, where the item is whole — or a draft with nothing in it.
+ *
+ * The facts are the task as the learner saw it, the draft verbatim with its
+ * word count recomputed as the grader will count it, and the rubric the answer
+ * will be graded on. `previousFeedback` is the text of the feedback already
+ * shown on earlier drafts, so a model can speak to what changed.
+ */
+declare function aiWritingFeedbackRequest(input: {
+    data: AiActivityInput;
+    response: LearnerResponse | null;
+    previousFeedback?: readonly string[];
+    learnerLocale?: string;
+}): AiWritingFeedbackRequest | null;
+/**
+ * Checks writing feedback a port returned for `request`, and turns it into what
+ * a learner is shown. The SDK shows a model's feedback whole or not at all: it
+ * never drops the part it doubts and shows the rest.
+ *
+ * - **The text** is read as every AI text is (`readAiTextResult`): plain text,
+ *   not empty, at most {@link AI_TEXT_MAX_LENGTH} code points.
+ * - **Every correction must quote the draft** — the check only this SDK can run.
+ *   The SDK finds each quote in the draft itself, typographic quotes and runs of
+ *   whitespace aside, and anchors it there; a range the model claims must hold
+ *   the quote. A correction of words the learner did not write refuses the
+ *   whole reply as `misquotes-answer`, as a hint that gives the answer away
+ *   refuses the hint. The `original` shown is the draft's own text at the range.
+ *   At most {@link AI_WRITING_MAX_CORRECTIONS}; a correction that changes
+ *   nothing is `malformed`.
+ * - **Criteria are judgements; the arithmetic is the SDK's.** Each names a
+ *   criterion of the item's rubric, once; its score, when it has one, is a
+ *   score out of its `maxScore`. The rubric's weights are attached, whatever
+ *   the model sent. Anything else is `malformed`, as is any criterion on an
+ *   item with no rubric.
+ * - **`indicativeScore`** is the rubric's weighted total, computed as
+ *   `gradeFromRubric` computes a grade, when every criterion of the rubric was
+ *   judged; `null` otherwise. An indication, never a grade.
+ */
+declare function checkAiWritingFeedback(raw: unknown, request: AiWritingFeedbackRequest): {
+    ok: true;
+    feedback: AiWritingFeedback;
+} | {
+    ok: false;
+    refusal: AiRefusal;
+};
+
 /**
  * How a paper is delivered: what a learner is shown around the questions, as
  * the school running it decides — separately from the content, so that one
@@ -308,6 +365,13 @@ interface AttemptPlan {
      * Absent when `planAttempt` was given none. Part of `planHash` when present.
      */
     delivery?: ResolvedDeliveryPolicy;
+    /**
+     * The scoring policy the attempt was sat under, every setting spelled out:
+     * the tries each question gave, which counted, and what tries and hints
+     * cost. Absent when `planAttempt` was given none. Part of `planHash` when
+     * present.
+     */
+    scoring?: ResolvedItemScoringPolicy;
     slots: AttemptPlanSlot[];
     /** Sum of every slot's `points`, frozen. The denominator of the paper. */
     totalPoints: number;
@@ -348,6 +412,12 @@ interface AttemptPlanDrift {
      * policy has exactly the shape it had before policies existed.
      */
     deliveryChanged?: true;
+    /**
+     * The scoring policy differs: one plan records a policy the other does not,
+     * or a setting differs. The same answers are worth something else under
+     * another policy, so it breaks `matches`. Present only when it is `true`.
+     */
+    scoringChanged?: true;
 }
 
 /** Options for {@link planAttempt}. */
@@ -386,6 +456,19 @@ interface PlanAttemptOptions<TItem> {
      *         record an appeal reads.
      */
     delivery?: DeliveryPolicy | null;
+    /**
+     * The scoring policy this attempt is sat under — how many tries each
+     * question gives, which one counts, and what tries and hints cost. Frozen
+     * into the plan with every setting spelled out, like `delivery`, and for a
+     * stronger reason: every setting in it moves a grade, so a re-grade must
+     * apply the rules the learner sat under, not today's.
+     *
+     * Recorded only when given: a plan made without one is byte-identical to a
+     * plan made before scoring policies existed, `planHash` included.
+     *
+     * @throws Error when the policy does not pass `validateItemScoringPolicy`.
+     */
+    scoring?: ItemScoringPolicy | null;
 }
 /**
  * Freezes what an attempt is being served: the presented order, each slot's
@@ -1612,4 +1695,4 @@ interface ThemeTokens {
     '--lk-transition-base': string;
 }
 
-export { AI_EXPLANATION_TYPES, AI_HINT_TYPES, AI_TEXT_MAX_LENGTH, ActivityData, ActivityDataMap, ActivityMedia, ActivitySchemaError, ActivityType, type ActivityTypeAuthoring, type ActivityTypeDescriptor, type ActivityTypeInterop, type ActivityTypeScoring, AiActivityInput, AiExplanationRequest, AiFeature, AiGrade, AiHintRequest, AiItemFacts, AiRefusal, AiSupportedActivityType, AiTextResult, AssessmentScore, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CompositionPolicy, CriterionScore, DeferredScoringError, DeferredScoringPartial, type DeliveryPolicy, type DeliveryPolicyIssue, DictationData, DictationLearnerResponse, type DraftComplete, type DraftContext, type DraftIssue, type DraftNotComplete, type DraftSeverity, type DraftValidationResult, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, GapSelectData, GapSelectLearnerResponse, type GradeFromRubricOptions, GradeRecord, INTERACTIVE_VIDEO_ITEM_TYPES, type InteractiveVideoItemType, ItemGroup, ItemOutcome, LearnerResponse, type MediaBudgetRef, type MediaPlayClaim, type MediaPlayGrant, type MediaPlayLedger, type MediaPlayLedgerEntry, MediaProgress, type MissingOutcomePolicy, MultipleChoiceData, MultipleChoiceLearnerResponse, NativeControlHint, OPEN_DELIVERY_POLICY, type PartialScoringResult, type PlanAttemptOptions, type PlannableEntry, ReadAloudData, ReadAloudLearnerResponse, type RedactOptions, type RedactedActivityData, type RedactedItemGroup, RedactedScoringError, type RegisteredActivityTypeDescriptor, type ResolvedDeliveryPolicy, type ResolvedPlaybackPolicy, type ResponseDiffEntry, RoundingPolicy, ScoredItem, ScoringDetail, ScoringResult, type SeededShuffleOptions, type Sensitivity, SequenceEntry, SequenceSlot, type ShuffleVersion, TIMELINE_MAX_CHAPTERS, TIMELINE_MAX_ITEMS, TIMELINE_MAX_QUIZZES, TIMELINE_MAX_TITLE_LENGTH, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, aiAllowedByContent, aiExplanationRequest, aiGradeOf, aiHintRequest, aiSupports, assertRedacted, assertRedactedItemGroup, buildAiFacts, canonicalJson, checkAiExplanation, checkAiHint, combineDeliveryPolicies, composeTimelineScore, contentHash, countWords, createDraft, createInteractiveVideoDraft, createItemGroupDraft, defineActivityType, dictationType, diffResponses, entryKeyOf, fillInTheBlanksType, fingerprint, flattenSequence, gapSelectType, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, hintRevealsAnswer, isInteractiveVideoItemType, isItemGroup, multipleChoiceType, outcomeFromGrade, planAttempt, planMediaBudgets, readAiTextResult, readAloudType, readMediaProgress, redact, redactItemGroup, registerActivityType, registeredActivityTypes, resolveDeliveryPolicy, resolvePlaybackPolicy, restoreAttemptState, restoreMediaPlayLedger, scoredItemsFromPlan, seededShuffle, serializeAttemptState, serializeMediaPlayLedger, slotMediaKey, stimulusMediaKey, validateDeliveryPolicy, validateDraft, validateItemGroupDraft, verifyAttemptPlan, writtenResponseType };
+export { AI_EXPLANATION_TYPES, AI_HINT_TYPES, AI_TEXT_MAX_LENGTH, AI_WRITING_MAX_CORRECTIONS, AI_WRITING_MAX_FIELD_LENGTH, ActivityData, ActivityDataMap, ActivityMedia, ActivitySchemaError, ActivityType, type ActivityTypeAuthoring, type ActivityTypeDescriptor, type ActivityTypeInterop, type ActivityTypeScoring, AiActivityInput, AiExplanationRequest, AiFeature, AiGrade, AiHintRequest, AiItemFacts, AiRefusal, AiSupportedActivityType, AiTextResult, AiWritingFeedback, AiWritingFeedbackRequest, AssessmentScore, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CompositionPolicy, CriterionScore, DeferredScoringError, DeferredScoringPartial, type DeliveryPolicy, type DeliveryPolicyIssue, DictationData, DictationLearnerResponse, type DraftComplete, type DraftContext, type DraftIssue, type DraftNotComplete, type DraftSeverity, type DraftValidationResult, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, GapSelectData, GapSelectLearnerResponse, type GradeFromRubricOptions, GradeRecord, INTERACTIVE_VIDEO_ITEM_TYPES, type InteractiveVideoItemType, ItemGroup, ItemOutcome, ItemScoringPolicy, LearnerResponse, type MediaBudgetRef, type MediaPlayClaim, type MediaPlayGrant, type MediaPlayLedger, type MediaPlayLedgerEntry, MediaProgress, type MissingOutcomePolicy, MultipleChoiceData, MultipleChoiceLearnerResponse, NativeControlHint, OPEN_DELIVERY_POLICY, type PartialScoringResult, type PlanAttemptOptions, type PlannableEntry, ReadAloudData, ReadAloudLearnerResponse, type RedactOptions, type RedactedActivityData, type RedactedItemGroup, RedactedScoringError, type RegisteredActivityTypeDescriptor, type ResolvedDeliveryPolicy, ResolvedItemScoringPolicy, type ResolvedPlaybackPolicy, type ResponseDiffEntry, RoundingPolicy, ScoredItem, ScoringDetail, ScoringResult, type SeededShuffleOptions, type Sensitivity, SequenceEntry, SequenceSlot, type ShuffleVersion, TIMELINE_MAX_CHAPTERS, TIMELINE_MAX_ITEMS, TIMELINE_MAX_QUIZZES, TIMELINE_MAX_TITLE_LENGTH, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, aiAllowedByContent, aiExplanationRequest, aiGradeOf, aiHintRequest, aiSupports, aiWritingFeedbackRequest, assertRedacted, assertRedactedItemGroup, buildAiFacts, canonicalJson, checkAiExplanation, checkAiHint, checkAiWritingFeedback, combineDeliveryPolicies, composeTimelineScore, contentHash, countWords, createDraft, createInteractiveVideoDraft, createItemGroupDraft, defineActivityType, dictationType, diffResponses, entryKeyOf, fillInTheBlanksType, fingerprint, flattenSequence, gapSelectType, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, hintRevealsAnswer, isInteractiveVideoItemType, isItemGroup, multipleChoiceType, outcomeFromGrade, planAttempt, planMediaBudgets, readAiTextResult, readAloudType, readMediaProgress, redact, redactItemGroup, registerActivityType, registeredActivityTypes, resolveDeliveryPolicy, resolvePlaybackPolicy, restoreAttemptState, restoreMediaPlayLedger, scoredItemsFromPlan, seededShuffle, serializeAttemptState, serializeMediaPlayLedger, slotMediaKey, stimulusMediaKey, validateDeliveryPolicy, validateDraft, validateItemGroupDraft, verifyAttemptPlan, writtenResponseType };

package/dist/index.js

@@ -35,25 +35,32 @@ import {
   AI_EXPLANATION_TYPES,
   AI_HINT_TYPES,
   AI_TEXT_MAX_LENGTH,
+  AI_WRITING_MAX_CORRECTIONS,
+  AI_WRITING_MAX_FIELD_LENGTH,
   aiAllowedByContent,
   aiExplanationRequest,
   aiGradeOf,
   aiHintRequest,
   aiSupports,
+  aiWritingFeedbackRequest,
   buildAiFacts,
   checkAiExplanation,
   checkAiHint,
+  checkAiWritingFeedback,
   hintRevealsAnswer,
   readAiTextResult
-} from "./chunk-BIJCO2HM.js";
+} from "./chunk-5UCR4UNR.js";
 import {
+  DEFAULT_ITEM_SCORING_POLICY,
   DEFAULT_PASS_THRESHOLD,
+  ITEM_SCORING_MAX_RETRIES,
   alignReadAloud,
   classifyBand,
   composeAssessmentScore,
   computePassThreshold,
   diffDictationChars,
   evaluate,
+  evaluateTries,
   gradeFromRubric,
   gradeReadAloud,
   gte,
@@ -61,10 +68,13 @@ import {
   inspectWav,
   outcomeFromGrade,
   outcomeFromUnscorable,
+  resolveItemScoringPolicy,
   roundGrade,
   score,
+  scoreTries,
+  validateItemScoringPolicy,
   validateSpeechAssessment
-} from "./chunk-MMEQKFFQ.js";
+} from "./chunk-Q7MV3IXJ.js";
 import {
   ActivitySchemaError,
   AiPermissionsSchema,
@@ -612,6 +622,7 @@ function planSlot(slot, points) {
 function planAttempt(entries, options = {}) {
   const { seed, shuffleEntries, points } = options;
   const delivery = frozenDelivery(options.delivery);
+  const scoring = frozenScoring(options.scoring);
   const slots = flattenSequence(entries, {
     ...shuffleEntries !== void 0 ? { shuffleEntries } : {},
     ...seed !== void 0 ? { seed } : {}
@@ -629,8 +640,19 @@ function planAttempt(entries, options = {}) {
     // A policy joins it when there is one: the same paper sat with hints and
     // without is two different attempts. Without one, the fingerprint is the
     // one every plan before policies had.
-    planHash: contentHash(delivery === void 0 ? planned : { slots: planned, delivery }),
+    // So does a scoring policy: the same answers are worth something else when
+    // a hint costs a tenth of the marks. Each joins only when it is there, so
+    // a plan with neither — or with a delivery policy alone — keeps the
+    // fingerprint it always had.
+    planHash: contentHash(
+      delivery === void 0 && scoring === void 0 ? planned : {
+        slots: planned,
+        ...delivery !== void 0 ? { delivery } : {},
+        ...scoring !== void 0 ? { scoring } : {}
+      }
+    ),
     ...delivery !== void 0 ? { delivery } : {},
+    ...scoring !== void 0 ? { scoring } : {},
     slots: planned,
     totalPoints
   };
@@ -646,6 +668,7 @@ function verifyAttemptPlan(plan, current) {
   const changedPointsSlotIds = [];
   const reorderedSlotIds = [];
   const deliveryChanged = contentHash(plan.delivery ?? null) !== contentHash(current.delivery ?? null);
+  const scoringChanged = contentHash(plan.scoring ?? null) !== contentHash(current.scoring ?? null);
   for (const slot of plan.slots) {
     const now = after.get(slot.slotId);
     if (now === void 0) {
@@ -668,7 +691,7 @@ function verifyAttemptPlan(plan, current) {
     }
   }
   return {
-    matches: missingSlotIds.length === 0 && addedSlotIds.length === 0 && changedSlotIds.length === 0 && changedStimulusSlotIds.length === 0 && changedCueSlotIds.length === 0 && changedPointsSlotIds.length === 0 && reorderedSlotIds.length === 0 && !deliveryChanged,
+    matches: missingSlotIds.length === 0 && addedSlotIds.length === 0 && changedSlotIds.length === 0 && changedStimulusSlotIds.length === 0 && changedCueSlotIds.length === 0 && changedPointsSlotIds.length === 0 && reorderedSlotIds.length === 0 && !deliveryChanged && !scoringChanged,
     missingSlotIds,
     addedSlotIds,
     changedSlotIds,
@@ -679,7 +702,8 @@ function verifyAttemptPlan(plan, current) {
     // Present only when it is true, as `rejectedSlotIds` is on a composed
     // score: a drift report between two plans without a policy — every one
     // written before policies existed — keeps exactly the shape it had.
-    ...deliveryChanged ? { deliveryChanged: true } : {}
+    ...deliveryChanged ? { deliveryChanged: true } : {},
+    ...scoringChanged ? { scoringChanged: true } : {}
   };
 }
 function frozenDelivery(policy) {
@@ -695,6 +719,19 @@ function frozenDelivery(policy) {
   }
   return resolveDeliveryPolicy(checked.data);
 }
+function frozenScoring(policy) {
+  if (policy === void 0 || policy === null) {
+    return void 0;
+  }
+  const checked = validateItemScoringPolicy(policy);
+  if (!checked.success) {
+    const first = checked.issues[0];
+    throw new Error(
+      `planAttempt: the scoring policy is not one to record \u2014 ${first?.message ?? "invalid"}` + (checked.issues.length > 1 ? ` (and ${checked.issues.length - 1} more)` : "")
+    );
+  }
+  return resolveItemScoringPolicy(checked.data);
+}
 function missingOutcome(slot, policy) {
   if (typeof policy === "function") {
     return policy(slot);
@@ -1629,9 +1666,12 @@ export {
   AI_EXPLANATION_TYPES,
   AI_HINT_TYPES,
   AI_TEXT_MAX_LENGTH,
+  AI_WRITING_MAX_CORRECTIONS,
+  AI_WRITING_MAX_FIELD_LENGTH,
   ActivitySchemaError,
   AiPermissionsSchema,
   BlankConfigSchema,
+  DEFAULT_ITEM_SCORING_POLICY,
   DEFAULT_PASS_THRESHOLD,
   DICTATION_MAX_ACCEPTED_TRANSCRIPTS,
   DICTATION_MAX_EQUIVALENCES,
@@ -1650,6 +1690,7 @@ export {
   GapSelectDataSchema,
   GapSelectGapSchema,
   INTERACTIVE_VIDEO_ITEM_TYPES,
+  ITEM_SCORING_MAX_RETRIES,
   ItemGroupSchema,
   MediaPlaybackSchema,
   MediaSchema,
@@ -1704,6 +1745,7 @@ export {
   aiGradeOf,
   aiHintRequest,
   aiSupports,
+  aiWritingFeedbackRequest,
   alignDictation,
   alignReadAloud,
   assertRedacted,
@@ -1712,6 +1754,7 @@ export {
   canonicalJson,
   checkAiExplanation,
   checkAiHint,
+  checkAiWritingFeedback,
   classifyBand,
   combineDeliveryPolicies,
   composeAssessmentScore,
@@ -1730,6 +1773,7 @@ export {
   diffResponses,
   entryKeyOf,
   evaluate,
+  evaluateTries,
   fillInTheBlanksJsonSchema,
   fillInTheBlanksType,
   fingerprint,
@@ -1765,11 +1809,13 @@ export {
   registerActivityType,
   registeredActivityTypes,
   resolveDeliveryPolicy,
+  resolveItemScoringPolicy,
   resolvePlaybackPolicy,
   restoreAttemptState,
   restoreMediaPlayLedger,
   roundGrade,
   score,
+  scoreTries,
   scoredItemsFromPlan,
   seededShuffle,
   serializeAttemptState,
@@ -1782,6 +1828,7 @@ export {
   validateDraft,
   validateItemGroup,
   validateItemGroupDraft,
+  validateItemScoringPolicy,
   validateSpeechAssessment,
   validateXAPIStatement,
   verifyAttemptPlan,