@intellectif/lk-core 0.5.0 → 0.7.0

package/dist/{index-CLmXzBhB.d.ts → index-CDWH2WIg.d.cts}

@@ -1,4 +1,4 @@
-import { A as ActivityData, c as ActivityMedia, t as ValidationResult, e as ActivityType, a as ActivityDataMap } from './activity-wkzRemHx.js';
+import { A as ActivityData, c as ActivityMedia, t as ValidationResult, e as ActivityType, a as ActivityDataMap } from './activity-gelWNZ6V.cjs';
 import { z } from 'zod/v4';
 
 /** What a stimulus primarily is. Drives validation and layout, never scoring. */
@@ -56,9 +56,26 @@ interface ItemGroup<TItem = ActivityData> {
     type: 'item-group';
     id: string;
     title?: string;
+    /**
+     * Stable identity for this entry's slots, independent of where it sits in
+     * the array. See {@link SequenceSlot.slotId}: without one, inserting a
+     * question above this group re-maps every slot id beneath it, and stored
+     * grades quietly start naming different questions.
+     */
+    slotKey?: string;
     stimulus: Stimulus;
-    /** The items, in authored order. Non-empty; ids unique within the group; no nested groups. */
-    items: TItem[];
+    /**
+     * The items, in authored order. Non-empty; ids unique within the group; no
+     * nested groups.
+     *
+     * An item may declare its own `slotKey`, for the same reason an entry can:
+     * it pins the item's identity within the group (`"reading.q1"` rather than
+     * `"reading.0"`), so inserting a question into a published group does not
+     * re-map the ones after it.
+     */
+    items: (TItem & {
+        slotKey?: string;
+    })[];
     /**
      * `none` (default) keeps authored order; `within-group` shuffles the items
      * among themselves under the sequence seed. Either way the group stays one
@@ -66,8 +83,20 @@ interface ItemGroup<TItem = ActivityData> {
      */
     shuffle?: 'none' | 'within-group';
 }
-/** What a sequence is made of: loose activities and item groups, in authored order. */
-type SequenceEntry<TItem = ActivityData> = TItem | ItemGroup<TItem>;
+/**
+ * What a sequence is made of: loose activities and item groups, in authored
+ * order.
+ *
+ * A plain activity may carry `slotKey` here even though no activity SCHEMA
+ * declares one, because a slot key describes an item's PLACE in a paper, not
+ * its content — the same question keeps its own id in every paper it appears
+ * in. Putting it on the entry rather than on the activity is what lets it be
+ * authored without every activity type having to know about assessment
+ * assembly. See {@link SequenceSlot.slotId}.
+ */
+type SequenceEntry<TItem = ActivityData> = (TItem & {
+    slotKey?: string;
+}) | ItemGroup<TItem>;
 /** The group a presented slot belongs to. */
 interface SequenceSlotGroup {
     id: string;
@@ -82,10 +111,20 @@ interface SequenceSlotGroup {
 interface SequenceSlot<TItem = ActivityData> {
     /**
      * Identity of the slot within the sequence definition — unique, and stable
-     * under shuffling. Derived from the AUTHORED position (`"2"` for the third
+     * under shuffling. Feed it to `composeAssessmentScore` as `slotId`.
+     *
+     * By default it is derived from the AUTHORED position (`"2"` for the third
      * top-level entry; `"2.1"` for the second item of that entry when it is a
      * group), so the same activity can appear in two entries and still be two
-     * slots. Feed it to `composeAssessmentScore` as `slotId`.
+     * slots.
+     *
+     * **A positional id is only valid against one version of the entries
+     * array.** Insert a question at the top of a published paper and every id
+     * below it shifts: rows stored as `"3"` now name what used to be entry 2,
+     * and a re-grade or a review render pairs each response with the wrong
+     * question — silently, because the ids still look valid. For any content
+     * whose slot ids you persist, give the entries an explicit `slotKey`; it is
+     * used verbatim here and survives insertion, deletion and re-ordering.
      */
     slotId: string;
     /** 0-based PRESENTED position, after shuffling. */
@@ -212,7 +251,7 @@ declare const FillInTheBlanksDataSchema: z.ZodObject<{
     passThreshold: z.ZodOptional<z.ZodNumber>;
     locale: z.ZodOptional<z.ZodString>;
     learningObjectives: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    difficultyLevel: z.ZodOptional<z.ZodLiteral<1 | 2 | 3 | 4 | 5>>;
+    difficultyLevel: z.ZodOptional<z.ZodLiteral<2 | 1 | 3 | 4 | 5>>;
 }, z.core.$loose>;
 
 /**
@@ -262,6 +301,7 @@ declare const ItemGroupSchema: z.ZodObject<{
     type: z.ZodLiteral<"item-group">;
     id: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
+    slotKey: z.ZodOptional<z.ZodString>;
     stimulus: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
@@ -292,12 +332,15 @@ declare const ItemGroupSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{
         type: z.ZodString;
         id: z.ZodString;
+        slotKey: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
     shuffle: z.ZodOptional<z.ZodEnum<{
         none: "none";
         "within-group": "within-group";
     }>>;
 }, z.core.$loose>;
+/** The learner-safe shape of a stimulus, derived from the strict schema below. */
+type RedactedStimulus = z.infer<typeof RedactedStimulusSchema>;
 /** Strict learner-safe stimulus: everything but the author-only `transcript`. */
 declare const RedactedStimulusSchema: z.ZodObject<{
     id: z.ZodString;
@@ -336,6 +379,7 @@ declare const RedactedItemGroupSchema: z.ZodObject<{
     type: z.ZodLiteral<"item-group">;
     id: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
+    slotKey: z.ZodOptional<z.ZodString>;
     stimulus: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
@@ -527,7 +571,7 @@ declare const MultipleChoiceDataSchema: z.ZodObject<{
     shuffle: z.ZodOptional<z.ZodBoolean>;
     locale: z.ZodOptional<z.ZodString>;
     learningObjectives: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    difficultyLevel: z.ZodOptional<z.ZodLiteral<1 | 2 | 3 | 4 | 5>>;
+    difficultyLevel: z.ZodOptional<z.ZodLiteral<2 | 1 | 3 | 4 | 5>>;
 }, z.core.$loose>;
 
 /** A redacted Multiple Choice option: id and display text only — no `isCorrect`, no feedback. */
@@ -557,6 +601,8 @@ declare const RedactedMultipleChoiceDataSchema: z.ZodObject<{
     shuffle: z.ZodOptional<z.ZodBoolean>;
     /** Marker distinguishing a redacted projection from full activity data. */
     redacted: z.ZodLiteral<true>;
+    /** Slot identity, carried through redaction so the client and the plan agree. */
+    slotKey: z.ZodOptional<z.ZodString>;
     schemaVersion: z.ZodLiteral<"1.0">;
     id: z.ZodString;
     title: z.ZodString;
@@ -574,7 +620,7 @@ declare const RedactedMultipleChoiceDataSchema: z.ZodObject<{
     passThreshold: z.ZodOptional<z.ZodNumber>;
     locale: z.ZodOptional<z.ZodString>;
     learningObjectives: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    difficultyLevel: z.ZodOptional<z.ZodLiteral<1 | 2 | 3 | 4 | 5>>;
+    difficultyLevel: z.ZodOptional<z.ZodLiteral<2 | 1 | 3 | 4 | 5>>;
 }, z.core.$strict>;
 /** A redacted blank: id and hint only — no accepted answers, no matching rules, no feedback. */
 declare const RedactedBlankConfigSchema: z.ZodObject<{
@@ -592,6 +638,8 @@ declare const RedactedFillInTheBlanksDataSchema: z.ZodObject<{
     }, z.core.$strict>>;
     /** Marker distinguishing a redacted projection from full activity data. */
     redacted: z.ZodLiteral<true>;
+    /** Slot identity, carried through redaction so the client and the plan agree. */
+    slotKey: z.ZodOptional<z.ZodString>;
     schemaVersion: z.ZodLiteral<"1.0">;
     id: z.ZodString;
     title: z.ZodString;
@@ -609,7 +657,7 @@ declare const RedactedFillInTheBlanksDataSchema: z.ZodObject<{
     passThreshold: z.ZodOptional<z.ZodNumber>;
     locale: z.ZodOptional<z.ZodString>;
     learningObjectives: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    difficultyLevel: z.ZodOptional<z.ZodLiteral<1 | 2 | 3 | 4 | 5>>;
+    difficultyLevel: z.ZodOptional<z.ZodLiteral<2 | 1 | 3 | 4 | 5>>;
 }, z.core.$strict>;
 /**
  * Redacted Written Response data: the prompt, word bounds and rubric are
@@ -633,6 +681,8 @@ declare const RedactedWrittenResponseDataSchema: z.ZodObject<{
     languageTarget: z.ZodOptional<z.ZodString>;
     /** Marker distinguishing a redacted projection from full activity data. */
     redacted: z.ZodLiteral<true>;
+    /** Slot identity, carried through redaction so the client and the plan agree. */
+    slotKey: z.ZodOptional<z.ZodString>;
     schemaVersion: z.ZodLiteral<"1.0">;
     id: z.ZodString;
     title: z.ZodString;
@@ -650,8 +700,45 @@ declare const RedactedWrittenResponseDataSchema: z.ZodObject<{
     passThreshold: z.ZodOptional<z.ZodNumber>;
     locale: z.ZodOptional<z.ZodString>;
     learningObjectives: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    difficultyLevel: z.ZodOptional<z.ZodLiteral<1 | 2 | 3 | 4 | 5>>;
+    difficultyLevel: z.ZodOptional<z.ZodLiteral<2 | 1 | 3 | 4 | 5>>;
 }, z.core.$strict>;
+/**
+ * The learner-safe SHAPE of each built-in type, derived from the strict schema
+ * above rather than hand-written beside it.
+ *
+ * `redact()` returns {@link RedactedActivityData}, which proves a payload is
+ * learner-safe but is index-signature typed — it deliberately says nothing
+ * about what the payload still CONTAINS. That is right for the assertion and
+ * useless for anything that has to render or transport the result, so every
+ * integrator ends up re-declaring these interfaces by hand and they drift the
+ * moment a schema changes. Deriving them with `z.infer` means the type and the
+ * validator can never disagree.
+ *
+ * Use them for the payload a server sends an exam client, and for the props of
+ * a renderer that must never see an answer key.
+ */
+type RedactedMultipleChoiceOption = z.infer<typeof RedactedMultipleChoiceOptionSchema>;
+/** A Multiple Choice item with the answer key, feedback and strategy removed. */
+type RedactedMultipleChoiceData = z.infer<typeof RedactedMultipleChoiceDataSchema>;
+/** A blank with its accepted answers and matching rules removed; the hint survives. */
+type RedactedBlankConfig = z.infer<typeof RedactedBlankConfigSchema>;
+/** A Fill-in-the-Blanks item with every accepted answer removed. */
+type RedactedFillInTheBlanksData = z.infer<typeof RedactedFillInTheBlanksDataSchema>;
+/** A Written Response item; the rubric survives, because it tells the learner what is assessed. */
+type RedactedWrittenResponseData = z.infer<typeof RedactedWrittenResponseDataSchema>;
+/**
+ * Discriminated union of every built-in redacted activity. Narrow it on
+ * `type`, exactly as you would {@link ActivityData}:
+ *
+ * ```ts
+ * function render(item: RedactedActivity) {
+ *   if (item.type === 'multiple-choice') {
+ *     return item.options.map((option) => option.text); // no `isCorrect` to leak
+ *   }
+ * }
+ * ```
+ */
+type RedactedActivity = RedactedMultipleChoiceData | RedactedFillInTheBlanksData | RedactedWrittenResponseData;
 
 /** Zod schema for a single rubric criterion. Loose: unknown keys preserved. */
 declare const WrittenResponseRubricCriterionSchema: z.ZodObject<{
@@ -712,7 +799,7 @@ declare const WrittenResponseDataSchema: z.ZodObject<{
     passThreshold: z.ZodOptional<z.ZodNumber>;
     locale: z.ZodOptional<z.ZodString>;
     learningObjectives: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    difficultyLevel: z.ZodOptional<z.ZodLiteral<1 | 2 | 3 | 4 | 5>>;
+    difficultyLevel: z.ZodOptional<z.ZodLiteral<2 | 1 | 3 | 4 | 5>>;
 }, z.core.$loose>;
 
 /**
@@ -729,4 +816,4 @@ declare const WrittenResponseDataSchema: z.ZodObject<{
  */
 declare function validateActivity<T extends ActivityType>(type: T, data: unknown): ValidationResult<ActivityDataMap[T]>;
 
-export { BlankConfigSchema as B, FeedbackSchema as F, type ItemGroup as I, MediaSchema as M, RedactedBlankConfigSchema as R, type SequenceEntry as S, TextMatchPolicySchema as T, WrittenResponseDataSchema as W, FillInTheBlanksDataSchema as a, ItemGroupSchema as b, MediaUrlSchema as c, MultipleChoiceDataSchema as d, MultipleChoiceOptionSchema as e, RedactedFillInTheBlanksDataSchema as f, RedactedItemGroupSchema as g, RedactedMultipleChoiceDataSchema as h, RedactedMultipleChoiceOptionSchema as i, RedactedStimulusSchema as j, RedactedWrittenResponseDataSchema as k, type SequenceSlot as l, type SequenceSlotGroup as m, type Stimulus as n, type StimulusKind as o, StimulusSchema as p, WrittenResponseRubricCriterionSchema as q, WrittenResponseRubricSchema as r, fillInTheBlanksJsonSchema as s, itemGroupJsonSchema as t, jsonSchemaFor as u, multipleChoiceJsonSchema as v, stimulusJsonSchema as w, validateActivity as x, validateItemGroup as y, writtenResponseJsonSchema as z };
+export { itemGroupJsonSchema as A, BlankConfigSchema as B, jsonSchemaFor as C, multipleChoiceJsonSchema as D, stimulusJsonSchema as E, FeedbackSchema as F, validateActivity as G, validateItemGroup as H, type ItemGroup as I, writtenResponseJsonSchema as J, MediaSchema as M, type RedactedActivity as R, type SequenceEntry as S, TextMatchPolicySchema as T, WrittenResponseDataSchema as W, FillInTheBlanksDataSchema as a, ItemGroupSchema as b, MediaUrlSchema as c, MultipleChoiceDataSchema as d, MultipleChoiceOptionSchema as e, type RedactedBlankConfig as f, RedactedBlankConfigSchema as g, type RedactedFillInTheBlanksData as h, RedactedFillInTheBlanksDataSchema as i, RedactedItemGroupSchema as j, type RedactedMultipleChoiceData as k, RedactedMultipleChoiceDataSchema as l, type RedactedMultipleChoiceOption as m, RedactedMultipleChoiceOptionSchema as n, type RedactedStimulus as o, RedactedStimulusSchema as p, type RedactedWrittenResponseData as q, RedactedWrittenResponseDataSchema as r, type SequenceSlot as s, type SequenceSlotGroup as t, type Stimulus as u, type StimulusKind as v, StimulusSchema as w, WrittenResponseRubricCriterionSchema as x, WrittenResponseRubricSchema as y, fillInTheBlanksJsonSchema as z };