@intellectif/lk-core 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { F as AiSupportedActivityType, g as AiActivityInput, p as AiFeature, ab as LearnerResponse, aa as ItemOutcome, o as AiExplanationRequest, t as AiGrade, u as AiHintRequest, ar as ScoringDetail, v as AiItemFacts, G as AiTextResult, C as AiRefusal, a2 as GradeRecord, j as AiCoachingRequest, i as AiCoaching, M as AiWritingFeedbackRequest, L as AiWritingFeedback, a as ActivityData, aw as ValidationError, f as ActivityType, b as ActivityDataMap, P as CriterionScore, aj as NativeControlHint, d as ActivityMedia, at as ScoringResult, R as DeferredScoringPartial, S as DictationData, U as DictationLearnerResponse, X as FillInTheBlanksData, Y as FillInTheBlanksLearnerResponse, $ as GapSelectData, a1 as GapSelectLearnerResponse, af as MultipleChoiceData, ag as MultipleChoiceLearnerResponse, ak as ReadAloudData, an as ReadAloudLearnerResponse, ay as WrittenResponseData, az as WrittenResponseLearnerResponse } from './activity-MBOYLBjR.cjs';
-export { A as ActivityAiPermissions, c as ActivityFeedback, e as ActivityResult, h as AiBlankFact, k as AiCoachingResult, l as AiCoachingWord, m as AiCriterionJudgement, n as AiDictationFacts, q as AiFillInTheBlanksFacts, r as AiGapFact, s as AiGapSelectFacts, w as AiMultipleChoiceFacts, x as AiOptionFact, y as AiProvenance, z as AiReadingFacts, B as AiReadingWordFact, D as AiRubricCriterionFact, E as AiSoundFact, H as AiVerdict, I as AiWordFact, J as AiWritingCorrection, K as AiWritingFacts, N as AiWritingFeedbackResult, O as BlankConfig, Q as DeferredReason, T as DictationEquivalence, V as DictationSlowMedia, W as DictationTolerance, Z as GapSelectBank, _ as GapSelectChoice, a0 as GapSelectGap, a3 as Grader, a4 as GraderKind, a5 as GraderUsage, a6 as GradingState, a7 as InlineCorrection, a8 as InteractionEvent, a9 as InteractionKind, ac as LearnerResponseMap, ad as MediaPlaybackPolicy, ae as MediaTrack, ah as MultipleChoiceOption, ai as MultipleChoiceOptionMedia, al as ReadAloudDimension, am as ReadAloudDimensionWeight, ao as ReadAloudSlowMedia, ap as RecordingBounds, aq as RecordingRef, as as ScoringOutcome, au as TextMatchPolicy, av as TextMatchResult, ax as ValidationResult, aA as WrittenResponseRubric, aB as WrittenResponseRubricCriterion, aC as XAPIActor, aD as XAPIConfig, aE as XAPIContext, aF as XAPIContextActivities, aG as XAPIError, aH as XAPIObject, aI as XAPIResult, aJ as XAPIScore, aK as XAPIStatement, aL as XAPIVerbObject, aM as levenshteinDistance, aN as matchText } from './activity-MBOYLBjR.cjs';
+import { W as AiSupportedActivityType, g as AiActivityInput, G as AiFeature, aB as LearnerResponse, aA as ItemOutcome, F as AiExplanationRequest, L as AiGrade, M as AiHintRequest, aR as ScoringDetail, N as AiItemFacts, X as AiTextResult, T as AiRefusal, aq as GradeRecord, j as AiCoachingRequest, i as AiCoaching, f as ActivityType, s as AiCritiqueRequest, n as AiCritique, D as AiDraftsRequest, B as AiDrafts, K as AiGeneratedDraft, z as AiDraftType, y as AiDraftSource, x as AiDraftSettings, E as AiDraftsRun, d as ActivityMedia, Z as AiVideoDraft, a2 as AiWritingFeedbackRequest, a1 as AiWritingFeedback, a as ActivityData, ae as DraftContext, ay as ItemFinding, ai as DraftValidationResult, b as ActivityDataMap, aW as ValidationError, a5 as CriterionScore, aJ as NativeControlHint, af as DraftIssue, aT as ScoringResult, a7 as DeferredScoringPartial, a8 as DictationData, aa as DictationLearnerResponse, aj as FillInTheBlanksData, ak as FillInTheBlanksLearnerResponse, an as GapSelectData, ap as GapSelectLearnerResponse, aF as MultipleChoiceData, aG as MultipleChoiceLearnerResponse, aK as ReadAloudData, aN as ReadAloudLearnerResponse, aY as WrittenResponseData, aZ as WrittenResponseLearnerResponse } from './activity-D705CXng.cjs';
+export { A as ActivityAiPermissions, c as ActivityFeedback, e as ActivityResult, h as AiBlankFact, k as AiCoachingResult, l as AiCoachingWord, m as AiCriterionJudgement, o as AiCritiqueField, p as AiCritiqueFinding, q as AiCritiqueFindingResult, r as AiCritiqueKind, t as AiCritiqueResult, u as AiDictationFacts, v as AiDraftCaption, w as AiDraftProblem, C as AiDraftsCall, H as AiFillInTheBlanksFacts, I as AiGapFact, J as AiGapSelectFacts, O as AiMultipleChoiceFacts, P as AiOptionFact, Q as AiProvenance, R as AiReadingFacts, S as AiReadingWordFact, U as AiRubricCriterionFact, V as AiSoundFact, Y as AiVerdict, _ as AiWordFact, $ as AiWritingCorrection, a0 as AiWritingFacts, a3 as AiWritingFeedbackResult, a4 as BlankConfig, a6 as DeferredReason, a9 as DictationEquivalence, ab as DictationSlowMedia, ac as DictationTolerance, ad as DraftComplete, ag as DraftNotComplete, ah as DraftSeverity, al as GapSelectBank, am as GapSelectChoice, ao as GapSelectGap, ar as Grader, as as GraderKind, at as GraderUsage, au as GradingState, av as InlineCorrection, aw as InteractionEvent, ax as InteractionKind, az as ItemFindingSeverity, aC as LearnerResponseMap, aD as MediaPlaybackPolicy, aE as MediaTrack, aH as MultipleChoiceOption, aI as MultipleChoiceOptionMedia, aL as ReadAloudDimension, aM as ReadAloudDimensionWeight, aO as ReadAloudSlowMedia, aP as RecordingBounds, aQ as RecordingRef, aS as ScoringOutcome, aU as TextMatchPolicy, aV as TextMatchResult, aX as ValidationResult, a_ as WrittenResponseRubric, a$ as WrittenResponseRubricCriterion, b0 as XAPIActor, b1 as XAPIConfig, b2 as XAPIContext, b3 as XAPIContextActivities, b4 as XAPIError, b5 as XAPIObject, b6 as XAPIResult, b7 as XAPIScore, b8 as XAPIStatement, b9 as XAPIVerbObject, ba as levenshteinDistance, bb as matchText } from './activity-D705CXng.cjs';
 import { SpeechAssessment, 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, 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 { p as SequenceSlot, S as SequenceEntry, I as ItemGroup, M as MediaProgress } from './index-DlCW0XaQ.cjs';
-export { a as MediaTimeline, R as RedactedActivity, b as RedactedBlankConfig, c as RedactedDictationData, d as RedactedDictationSlowMedia, e as RedactedFillInTheBlanksData, f as RedactedGapSelectBank, g as RedactedGapSelectChoice, h as RedactedGapSelectData, i as RedactedGapSelectGap, j as RedactedMultipleChoiceData, k as RedactedMultipleChoiceOption, l as RedactedMultipleChoiceOptionMedia, m as RedactedReadAloudData, n as RedactedStimulus, o as RedactedWrittenResponseData, q as SequenceSlotGroup, r as Stimulus, s as StimulusKind, T as TimelineChapter, t as TimelineCue, u as dictationJsonSchema, v as fillInTheBlanksJsonSchema, w as gapSelectJsonSchema, x as itemGroupJsonSchema, y as jsonSchemaFor, z as multipleChoiceJsonSchema, A as readAloudJsonSchema, B as stimulusJsonSchema, C as validateActivity, D as validateItemGroup, E as validateMedia, F as validateOptionMedia, G as writtenResponseJsonSchema } from './index-DlCW0XaQ.cjs';
+import { p as SequenceSlot, S as SequenceEntry, I as ItemGroup, M as MediaProgress } from './index-VXt_v3YI.cjs';
+export { a as MediaTimeline, R as RedactedActivity, b as RedactedBlankConfig, c as RedactedDictationData, d as RedactedDictationSlowMedia, e as RedactedFillInTheBlanksData, f as RedactedGapSelectBank, g as RedactedGapSelectChoice, h as RedactedGapSelectData, i as RedactedGapSelectGap, j as RedactedMultipleChoiceData, k as RedactedMultipleChoiceOption, l as RedactedMultipleChoiceOptionMedia, m as RedactedReadAloudData, n as RedactedStimulus, o as RedactedWrittenResponseData, q as SequenceSlotGroup, r as Stimulus, s as StimulusKind, T as TimelineChapter, t as TimelineCue, u as dictationJsonSchema, v as fillInTheBlanksJsonSchema, w as gapSelectJsonSchema, x as itemGroupJsonSchema, y as jsonSchemaFor, z as multipleChoiceJsonSchema, A as readAloudJsonSchema, B as stimulusJsonSchema, C as validateActivity, D as validateItemGroup, E as validateMedia, F as validateOptionMedia, G as writtenResponseJsonSchema } from './index-VXt_v3YI.cjs';
 export { AnsweredStatementParams, CompletedStatementParams, SubmittedStatementParams, XAPIObjectParams, XAPIStatementParams, XAPIVerb, XAPIVerbKey, XAPI_VERB_DISPLAY, validateXAPIStatement, xAPIBuilder, xapiDefinitionFor } from './xapi.cjs';
 
 /**
@@ -188,6 +188,192 @@ declare function checkAiCoaching(raw: unknown, request: AiCoachingRequest): {
     refusal: AiRefusal;
 };
 
+/** The most findings one critique may carry. More is refused, not cut. */
+declare const AI_CRITIQUE_MAX_FINDINGS = 20;
+/** The longest message or quote in a finding, in code points. */
+declare const AI_CRITIQUE_MAX_FIELD_LENGTH = 500;
+/**
+ * What a model is given to review an item, or `null` when there is nothing to
+ * review: a draft that is not an object, or one with no words in it yet.
+ *
+ * The facts are the item as the author wrote it — the answer key included; this
+ * is for an author, never a learner — every text field a finding may point at,
+ * and what the SDK's own critic already found there, so a model spends its
+ * words on what a rule cannot see: a stem that reads two ways, a distractor
+ * that is defensibly right, a key that is wrong, language above the level.
+ *
+ * Works for every registered type, the SDK's own and yours: the fields are read
+ * from the draft itself.
+ *
+ * @throws UnknownActivityTypeError when `type` has no registered descriptor.
+ */
+declare function aiCritiqueRequest(input: {
+    type: ActivityType;
+    draft: unknown;
+    level?: string;
+    authorLocale?: string;
+}): AiCritiqueRequest | null;
+/**
+ * Checks a critique a port returned for `request`, and turns it into findings
+ * an editor lists beside the SDK's own. As every AI answer, it is shown whole
+ * or not at all.
+ *
+ * - **Every finding points at a field the item has.** Its `path` is one of
+ *   `facts.fields`, exactly; a path to a field the item does not have refuses
+ *   the whole reply as `contradicts-item`.
+ * - **A quote is words that field contains**, typographic quotes and runs of
+ *   spacing aside, case kept; one it does not refuses the reply the same way.
+ * - **Every finding is `advice`.** It is a model's opinion about the item, and
+ *   nothing in the SDK acts on it; its code is `ai_` and the kind
+ *   (`ai_second_answer`).
+ * - **Limits:** {@link AI_CRITIQUE_MAX_FINDINGS} findings; a message or quote of
+ *   {@link AI_CRITIQUE_MAX_FIELD_LENGTH} code points; over them `too-long`. A
+ *   kind the SDK does not name, or any other shape, is `malformed`.
+ */
+declare function checkAiCritique(raw: unknown, request: AiCritiqueRequest): {
+    ok: true;
+    critique: AiCritique;
+} | {
+    ok: false;
+    refusal: AiRefusal;
+};
+
+/** The most drafts one request may ask for, and the most a reply may hold when it names no count. */
+declare const AI_DRAFTS_MAX_COUNT = 50;
+/** The most repair passes `generateDrafts` makes. */
+declare const AI_DRAFTS_MAX_REPAIRS = 3;
+/**
+ * What a model is given to draft items from a source, or `null` when there is
+ * no source to draft from: an empty text, or no caption with words in it.
+ *
+ * `types` are the ones the author chose, in the author's order: the model
+ * leans on the first, and where several drafts share a moment of a video — or
+ * the end of one — they are shown in this order. `count` is how many to write
+ * at most; left out, the model writes as many as the source is worth, up to
+ * {@link AI_DRAFTS_MAX_COUNT}.
+ *
+ * The facts are the source — a caption list numbered, with its times in
+ * seconds — the types, the count, and the language, level and instructions
+ * the author gave. `shape` is the JSON Schema of the reply: each draft names
+ * its type and writes that type's own fields, with no ids, no HTML, no media
+ * and no settings. Those are not a model's to write. `settings` are yours, put
+ * on every draft of a type: a read-aloud's `recording` and `scoring`, say, which
+ * the SDK has no default for.
+ *
+ * @throws RangeError when `types` is empty, repeats a type or names one a model
+ *   does not draft, or `count` is not a whole number from 1 to
+ *   {@link AI_DRAFTS_MAX_COUNT}.
+ */
+declare function aiDraftsRequest(input: {
+    types: readonly AiDraftType[];
+    source: AiDraftSource;
+    count?: number;
+    locale?: string;
+    level?: string;
+    instructions?: string;
+    settings?: AiDraftSettings;
+}): AiDraftsRequest | null;
+/**
+ * Reads a model's reply to {@link aiDraftsRequest} into drafts an editor can
+ * show for approval: each with ids from `newId`, your settings for its type,
+ * what `validateDraft` says of it, what the item critic finds in it, and — from
+ * captions — where it goes, and for a dictation the stretch of the video that
+ * says its words. They come back in the author's order of types.
+ *
+ * Drafts are independent: one that is unfinished or wrong is returned as such,
+ * for an author or {@link aiDraftsRepairRequest} to fix, beside the ones that
+ * are complete. `complete` means valid, never approved: a model wrote it, and a
+ * person decides whether learners see it. The whole reply is refused only when
+ * it is not `{ drafts: [...] }` of objects of the chosen types (`malformed`), or
+ * holds more drafts than asked for (`too-long`) — on a repair, not exactly one
+ * per draft to fix (`malformed`).
+ *
+ * Only the fields a type's shape names are read: a model cannot set an id,
+ * HTML, media, a switch or a scoring setting through this. A question is scored
+ * `all-or-nothing` unless your settings say otherwise, a written response's
+ * criteria are weighted equally, and a dictation carries no recording — attach
+ * one, or cut it from the video at `clip`.
+ *
+ * @throws Error when `newId` returns an empty or repeated id.
+ */
+declare function checkAiDrafts(raw: unknown, request: AiDraftsRequest, options: {
+    newId: () => string;
+}): {
+    ok: true;
+    drafts: AiDrafts;
+} | {
+    ok: false;
+    refusal: AiRefusal;
+};
+/**
+ * A second request, for the drafts with something wrong the model can fix —
+ * unfinished, wrong, or a flaw the critic warns about, at a field the model
+ * writes — each as the model wrote it, with those problems at the paths the
+ * model wrote. `null` when there is none.
+ *
+ * The reply holds one draft for each, in order; {@link checkAiDrafts} reads it
+ * and gives each the `index` of the draft it replaces.
+ */
+declare function aiDraftsRepairRequest(request: AiDraftsRequest, drafts: AiDrafts | readonly AiGeneratedDraft[]): AiDraftsRequest | null;
+/**
+ * Drafts items from a source, with a bounded repair loop: asks the port with
+ * `request`, reads the reply with {@link checkAiDrafts}, then — up to `repairs`
+ * times — sends back the drafts with something wrong the model can fix
+ * ({@link aiDraftsRepairRequest}), and keeps a repaired draft only when it is
+ * no worse than the one it replaces. A repaired draft keeps its id.
+ *
+ * Never throws for a model's failure: a port that throws or a reply the SDK
+ * refuses ends the loop, and is recorded in `calls` beside the provenance and
+ * usage of every call — which the SDK never adds up. A first call that fails
+ * leaves no drafts.
+ *
+ * ```ts
+ * const run = await generateDrafts({
+ *   request: aiDraftsRequest({ types: ['multiple-choice', 'dictation'], source: { kind: 'transcript', text } }),
+ *   port: (request) => callMyModel(DRAFTS_PROMPT, request),
+ *   newId: () => crypto.randomUUID(),
+ * });
+ * // run.drafts: store each as proposed, for a person to approve.
+ * ```
+ *
+ * @throws RangeError when `repairs` is not a whole number from 0 to
+ *   {@link AI_DRAFTS_MAX_REPAIRS} (default 1), and Error when `newId` returns an
+ *   empty or repeated id.
+ */
+declare function generateDrafts(input: {
+    request: AiDraftsRequest;
+    port: (request: AiDraftsRequest) => Promise<unknown> | unknown;
+    newId: () => string;
+    repairs?: number;
+}): Promise<AiDraftsRun>;
+/**
+ * An interactive video made of drafts: an item group whose stimulus is
+ * `video`, whose items are the drafts, and whose timeline opens a quiz at each
+ * moment a draft was placed — drafts placed at one moment share its quiz, in
+ * the author's order of types — and one more at `durationSeconds` for every
+ * draft placed nowhere: all of them when the source had no times.
+ *
+ * The SDK never reads the video, so it cannot know where the end is: without
+ * `durationSeconds` that last quiz has no time yet, which
+ * `validateItemGroupDraft` reports for the author to set. The source is kept on
+ * the stimulus as its author-only `transcript`.
+ *
+ * Like every draft it is checked (`validateItemGroupDraft`) and critiqued
+ * (`critiqueItemGroupDraft`), never approved. A dictation still needs its own
+ * recording; a type a video does not take — a written response — is reported,
+ * not dropped.
+ *
+ * @throws Error when `newId` returns an empty or repeated id.
+ */
+declare function interactiveVideoFromDrafts(input: {
+    request: AiDraftsRequest;
+    drafts: AiDrafts | AiDraftsRun | readonly AiGeneratedDraft[];
+    video: ActivityMedia;
+    durationSeconds?: number;
+    title?: string;
+    newId: () => string;
+}): AiVideoDraft;
+
 /** 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. */
@@ -709,61 +895,6 @@ declare function restoreAttemptState(plan: AttemptPlan, state: AttemptState): At
  */
 declare function diffResponses(before: Pick<AttemptState, 'responses'>, after: Pick<AttemptState, 'responses'>): ResponseDiffEntry[];
 
-/**
- * Why a draft is not an activity yet.
- *
- * - `incomplete` — something the author has not written yet: an empty title, an
- *   option with no text, no option marked correct. The fix is to add it.
- * - `invalid` — something is wrong in a way that writing more cannot fix: two
- *   correct options on a single-selection question, a maximum word count below
- *   the minimum, a media address with a scheme the SDK refuses, a `null` in an
- *   optional field that accepts none. The fix is to change it.
- */
-type DraftSeverity = 'incomplete' | 'invalid';
-/**
- * One problem with a draft. A {@link ValidationError} with a severity, so code
- * that already lists `validateActivity` errors can list these unchanged.
- */
-interface DraftIssue extends ValidationError {
-    severity: DraftSeverity;
-}
-/** A draft that is a valid activity and has nothing left to write. */
-interface DraftComplete<T> {
-    status: 'complete';
-    /** The validated activity, exactly as `validateActivity` returns it. */
-    data: T;
-    /** Always empty. Present so that every result can be read the same way. */
-    issues: DraftIssue[];
-}
-/**
- * A draft that is not an activity yet: `invalid` when any issue is invalid,
- * otherwise `incomplete`. It carries no `data`, because nothing here may be
- * stored or rendered as an activity.
- */
-interface DraftNotComplete {
-    status: 'incomplete' | 'invalid';
-    issues: DraftIssue[];
-}
-/**
- * The result of `validateDraft`.
- *
- * There is deliberately no `success` boolean. A boolean has to call an
- * incomplete draft either a success, which lets a half-written answer key
- * through anything that checks it, or a failure, which is the conflation this
- * result exists to remove. Branch on `status`.
- */
-type DraftValidationResult<T> = DraftComplete<T> | DraftNotComplete;
-/** What `createDraft` hands an activity type's `authoring.createDraft`. */
-interface DraftContext {
-    /**
-     * Returns a new id on every call. The SDK invents none: an id made here would
-     * need `crypto`, which plain-http origins do not have, or would be positional —
-     * and option ids reach the learner, so ids like `"a"` and `"b"` would tell them
-     * which option was written first.
-     */
-    newId: () => string;
-}
-
 /**
  * A new, empty reading or listening testlet for an editor to start from.
  *
@@ -814,6 +945,24 @@ declare function createInteractiveVideoDraft(context: DraftContext): ItemGroup;
  *   turned into an issue: a fault in a type's own code is not a problem with the
  *   draft, and reporting it as an unknown type would hide it.
  */
+/**
+ * The item critic over a testlet: each item's findings, under `items.N.…`, and
+ * what only the set shows — every single-answer question keeping its right
+ * option in one place. The stimulus is not searched for answers: a reading
+ * group's answers are meant to be in its passage.
+ *
+ * An item of a type that is not registered, or without a `type`, is skipped:
+ * {@link validateItemGroupDraft} already reports it.
+ */
+declare function critiqueItemGroupDraft(draft: unknown): ItemFinding[];
+/**
+ * The item critic over a question set, as `<ActivitySequence>` takes one: each
+ * entry's findings under its index — an item group's under `N.items.M.…` — and,
+ * over the entries that are items, what only the set shows (see
+ * {@link critiqueItemGroupDraft}). An entry of a type that is not registered is
+ * skipped.
+ */
+declare function critiqueDrafts(entries: readonly unknown[]): ItemFinding[];
 declare function validateItemGroupDraft(draft: unknown): DraftValidationResult<ItemGroup>;
 
 /**
@@ -872,6 +1021,29 @@ declare function validateDraft<T extends ActivityType>(type: T, draft: unknown):
  *   `newId` returns an empty or repeated id.
  */
 declare function createDraft<T extends ActivityType>(type: T, context: DraftContext): ActivityDataMap[T];
+/**
+ * What an experienced item writer would point out on review: flaws a learner
+ * can exploit or trip over (`warning`) and item-writing guidelines the item
+ * departs from (`advice`) — the right option much longer than the rest, an
+ * answer printed in the passage, a hint that gives the answer away, two
+ * options that read the same, "all of the above" under shuffle.
+ *
+ * A finding is never a reason to refuse an item. It does not change what
+ * {@link validateDraft} says: a valid item with findings is still valid. The
+ * shape is a `DraftIssue`'s, so an editor shows both in one list.
+ *
+ * It reads a draft, finished or not, and skips any rule whose fields are not
+ * written yet. The codes are documented in `docs/authoring.md`, each with its
+ * severity; the rule behind a code is advice and may be refined in a minor.
+ *
+ * ```ts
+ * const list = [...validateDraft(type, draft).issues, ...critiqueDraft(type, draft)];
+ * ```
+ *
+ * @throws UnknownActivityTypeError when `type` has no registered descriptor —
+ *   including `'item-group'`: use {@link critiqueItemGroupDraft}.
+ */
+declare function critiqueDraft(type: ActivityType, draft: unknown): ItemFinding[];
 
 /**
  * Content fingerprinting — "is this the same content the learner was served?"
@@ -1433,6 +1605,19 @@ interface ActivityTypeAuthoring<TData> {
      * reported as `invalid`.
      */
     readonly checkDraft?: (draft: Readonly<Record<string, unknown>>) => DraftIssue[];
+    /**
+     * The item critic for the type: what `critiqueDraft` reports about a draft
+     * that may be perfectly valid — a flaw a learner can exploit (`warning`), or
+     * an item-writing guideline it departs from (`advice`). Receives any plain
+     * object, finished or not, and must not throw on one: skip a rule whose
+     * fields are not there yet. Never a reason to refuse the item; that is
+     * `checkDraft`'s.
+     *
+     * A code documented in `docs/authoring.md` is reported with its documented
+     * severity. For a code of your own, a severity other than `'advice'` is
+     * reported as `warning`.
+     */
+    readonly critique?: (draft: Readonly<Record<string, unknown>>) => ItemFinding[];
 }
 /**
  * A value-level description of an activity type: its contract (schema), its
@@ -1852,4 +2037,4 @@ interface ThemeTokens {
     '--lk-transition-base': string;
 }
 
-export { AI_COACHING_MAX_TIP_LENGTH, AI_COACHING_MAX_WORDS, 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, AiCoaching, AiCoachingRequest, 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, SpeechAssessment, StandardSchemaV1, TIMELINE_MAX_CHAPTERS, TIMELINE_MAX_ITEMS, TIMELINE_MAX_QUIZZES, TIMELINE_MAX_TITLE_LENGTH, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, aiAllowedByContent, aiCoachingRequest, aiExplanationRequest, aiGradeOf, aiHintRequest, aiSupports, aiWritingFeedbackRequest, assertRedacted, assertRedactedItemGroup, buildAiFacts, canonicalJson, checkAiCoaching, 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 };
+export { AI_COACHING_MAX_TIP_LENGTH, AI_COACHING_MAX_WORDS, AI_CRITIQUE_MAX_FIELD_LENGTH, AI_CRITIQUE_MAX_FINDINGS, AI_DRAFTS_MAX_COUNT, AI_DRAFTS_MAX_REPAIRS, 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, AiCoaching, AiCoachingRequest, AiCritique, AiCritiqueRequest, AiDraftSettings, AiDraftSource, AiDraftType, AiDrafts, AiDraftsRequest, AiDraftsRun, AiExplanationRequest, AiFeature, AiGeneratedDraft, AiGrade, AiHintRequest, AiItemFacts, AiRefusal, AiSupportedActivityType, AiTextResult, AiVideoDraft, AiWritingFeedback, AiWritingFeedbackRequest, AssessmentScore, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CompositionPolicy, CriterionScore, DeferredScoringError, DeferredScoringPartial, type DeliveryPolicy, type DeliveryPolicyIssue, DictationData, DictationLearnerResponse, DraftContext, DraftIssue, DraftValidationResult, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, GapSelectData, GapSelectLearnerResponse, type GradeFromRubricOptions, GradeRecord, INTERACTIVE_VIDEO_ITEM_TYPES, type InteractiveVideoItemType, ItemFinding, 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, SpeechAssessment, StandardSchemaV1, TIMELINE_MAX_CHAPTERS, TIMELINE_MAX_ITEMS, TIMELINE_MAX_QUIZZES, TIMELINE_MAX_TITLE_LENGTH, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, aiAllowedByContent, aiCoachingRequest, aiCritiqueRequest, aiDraftsRepairRequest, aiDraftsRequest, aiExplanationRequest, aiGradeOf, aiHintRequest, aiSupports, aiWritingFeedbackRequest, assertRedacted, assertRedactedItemGroup, buildAiFacts, canonicalJson, checkAiCoaching, checkAiCritique, checkAiDrafts, checkAiExplanation, checkAiHint, checkAiWritingFeedback, combineDeliveryPolicies, composeTimelineScore, contentHash, countWords, createDraft, createInteractiveVideoDraft, createItemGroupDraft, critiqueDraft, critiqueDrafts, critiqueItemGroupDraft, defineActivityType, dictationType, diffResponses, entryKeyOf, fillInTheBlanksType, fingerprint, flattenSequence, gapSelectType, generateDrafts, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, hintRevealsAnswer, interactiveVideoFromDrafts, 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 };