@intellectif/lk-core 0.19.0 → 0.21.0

package/dist/index.js

@@ -45,15 +45,18 @@ import {
   checkAiHint,
   hintRevealsAnswer,
   readAiTextResult
-} from "./chunk-BIJCO2HM.js";
+} from "./chunk-IHOEP4EB.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 +64,13 @@ import {
   inspectWav,
   outcomeFromGrade,
   outcomeFromUnscorable,
+  resolveItemScoringPolicy,
   roundGrade,
   score,
+  scoreTries,
+  validateItemScoringPolicy,
   validateSpeechAssessment
-} from "./chunk-MMEQKFFQ.js";
+} from "./chunk-Q7MV3IXJ.js";
 import {
   ActivitySchemaError,
   AiPermissionsSchema,
@@ -208,6 +214,106 @@ function contentHash(value) {
   return fingerprint(canonicalJson(value));
 }
 
+// src/delivery.ts
+var OPEN_DELIVERY_POLICY = Object.freeze({
+  feedback: true,
+  solutions: true,
+  hints: true,
+  ai: Object.freeze({ hints: true, explanations: true })
+});
+var SETTINGS = ["feedback", "solutions", "hints"];
+var AI_SETTINGS = ["hints", "explanations"];
+function allows(value) {
+  return value === void 0 || value === null || value === true;
+}
+function resolveDeliveryPolicy(policy) {
+  if (policy === void 0 || policy === null) {
+    return OPEN_DELIVERY_POLICY;
+  }
+  if (typeof policy !== "object" || Array.isArray(policy)) {
+    return {
+      feedback: false,
+      solutions: false,
+      hints: false,
+      ai: { hints: false, explanations: false }
+    };
+  }
+  const given = policy;
+  const ai = given.ai;
+  const aiGiven = ai === void 0 || ai === null || ai === true ? {} : typeof ai === "object" && !Array.isArray(ai) ? ai : { hints: false, explanations: false };
+  return {
+    feedback: allows(given.feedback),
+    solutions: allows(given.solutions),
+    hints: allows(given.hints),
+    ai: { hints: allows(aiGiven.hints), explanations: allows(aiGiven.explanations) }
+  };
+}
+function combineDeliveryPolicies(...policies) {
+  const resolved = policies.map(resolveDeliveryPolicy);
+  const every = (read) => resolved.every(read);
+  return {
+    feedback: every((one) => one.feedback),
+    solutions: every((one) => one.solutions),
+    hints: every((one) => one.hints),
+    ai: {
+      hints: every((one) => one.ai.hints),
+      explanations: every((one) => one.ai.explanations)
+    }
+  };
+}
+function validateDeliveryPolicy(policy) {
+  const issues = [];
+  if (policy === void 0 || policy === null) {
+    return { success: true, data: {} };
+  }
+  if (typeof policy !== "object" || Array.isArray(policy)) {
+    return {
+      success: false,
+      issues: [{ path: "", message: "A delivery policy is an object of settings." }]
+    };
+  }
+  const given = policy;
+  for (const key of Object.keys(given)) {
+    if (key === "ai") {
+      continue;
+    }
+    if (!SETTINGS.includes(key)) {
+      issues.push({
+        path: key,
+        message: `"${key}" is not a delivery setting. The settings are feedback, solutions, hints and ai.`
+      });
+      continue;
+    }
+    const value = given[key];
+    if (value !== true && value !== false && value !== null && value !== void 0) {
+      issues.push({ path: key, message: `"${key}" must be true, false or null.` });
+    }
+  }
+  const ai = given.ai;
+  if (ai !== void 0 && ai !== null && ai !== true && ai !== false) {
+    if (typeof ai !== "object" || Array.isArray(ai)) {
+      issues.push({
+        path: "ai",
+        message: '"ai" must be true, false, or an object of hints and explanations.'
+      });
+    } else {
+      for (const [key, value] of Object.entries(ai)) {
+        if (!AI_SETTINGS.includes(key)) {
+          issues.push({
+            path: `ai.${key}`,
+            message: `"ai.${key}" is not an AI setting. The settings are hints and explanations.`
+          });
+          continue;
+        }
+        if (value !== true && value !== false && value !== null && value !== void 0) {
+          issues.push({ path: `ai.${key}`, message: `"ai.${key}" must be true, false or null.` });
+        }
+      }
+    }
+  }
+  return issues.length > 0 ? { success: false, issues } : { success: true, data: given };
+}
+
 // src/shuffle.ts
 function hashSeed(input) {
   let h = 2166136261 >>> 0;
@@ -511,6 +617,8 @@ 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 } : {}
@@ -525,7 +633,22 @@ function planAttempt(entries, options = {}) {
     // The plan's own fingerprint covers the slots verbatim — identity, order,
     // points and content hashes — so one stored value answers "is this still
     // the paper that was sat?" and the per-slot hashes then say what moved.
-    planHash: contentHash(planned),
+    // 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.
+    // 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
   };
@@ -540,6 +663,8 @@ function verifyAttemptPlan(plan, current) {
   const changedCueSlotIds = [];
   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) {
@@ -562,16 +687,47 @@ 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,
+    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,
     changedStimulusSlotIds,
     changedCueSlotIds,
     changedPointsSlotIds,
-    reorderedSlotIds
+    reorderedSlotIds,
+    // 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 } : {},
+    ...scoringChanged ? { scoringChanged: true } : {}
   };
 }
+function frozenDelivery(policy) {
+  if (policy === void 0 || policy === null) {
+    return void 0;
+  }
+  const checked = validateDeliveryPolicy(policy);
+  if (!checked.success) {
+    const first = checked.issues[0];
+    throw new Error(
+      `planAttempt: the delivery policy is not one to record \u2014 ${first?.message ?? "invalid"}` + (checked.issues.length > 1 ? ` (and ${checked.issues.length - 1} more)` : "")
+    );
+  }
+  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);
@@ -1509,6 +1665,7 @@ export {
   ActivitySchemaError,
   AiPermissionsSchema,
   BlankConfigSchema,
+  DEFAULT_ITEM_SCORING_POLICY,
   DEFAULT_PASS_THRESHOLD,
   DICTATION_MAX_ACCEPTED_TRANSCRIPTS,
   DICTATION_MAX_EQUIVALENCES,
@@ -1527,6 +1684,7 @@ export {
   GapSelectDataSchema,
   GapSelectGapSchema,
   INTERACTIVE_VIDEO_ITEM_TYPES,
+  ITEM_SCORING_MAX_RETRIES,
   ItemGroupSchema,
   MediaPlaybackSchema,
   MediaSchema,
@@ -1537,6 +1695,7 @@ export {
   MultipleChoiceOptionMediaSchema,
   MultipleChoiceOptionSchema,
   NativeControlHintSchema,
+  OPEN_DELIVERY_POLICY,
   READ_ALOUD_MAX_DIMENSION_WEIGHT,
   READ_ALOUD_MAX_REFERENCE_LENGTH,
   READ_ALOUD_MAX_SECONDS,
@@ -1589,6 +1748,7 @@ export {
   checkAiExplanation,
   checkAiHint,
   classifyBand,
+  combineDeliveryPolicies,
   composeAssessmentScore,
   composeTimelineScore,
   computePassThreshold,
@@ -1605,6 +1765,7 @@ export {
   diffResponses,
   entryKeyOf,
   evaluate,
+  evaluateTries,
   fillInTheBlanksJsonSchema,
   fillInTheBlanksType,
   fingerprint,
@@ -1639,11 +1800,14 @@ export {
   redactItemGroup,
   registerActivityType,
   registeredActivityTypes,
+  resolveDeliveryPolicy,
+  resolveItemScoringPolicy,
   resolvePlaybackPolicy,
   restoreAttemptState,
   restoreMediaPlayLedger,
   roundGrade,
   score,
+  scoreTries,
   scoredItemsFromPlan,
   seededShuffle,
   serializeAttemptState,
@@ -1652,9 +1816,11 @@ export {
   stimulusJsonSchema,
   stimulusMediaKey,
   validateActivity,
+  validateDeliveryPolicy,
   validateDraft,
   validateItemGroup,
   validateItemGroupDraft,
+  validateItemScoringPolicy,
   validateSpeechAssessment,
   validateXAPIStatement,
   verifyAttemptPlan,