@longsightgroup/qti3-core 0.10.5 → 0.11.0

package/src/qti-package.ts

@@ -1,26 +1,42 @@
-import { pushPackageDiagnostic } from "./qti-package-paths.js";
+import { normalizePackagePath, pushPackageDiagnostic } from "./qti-package-paths.js";
 import { QTI_PACKAGE_MANIFEST_PATH } from "./qti-package-manifest.js";
-import { buildPackageSummary, inspectPackageManifest } from "./qti-package-plan.js";
+import {
+  buildPackageSummary,
+  failedPackageSummary,
+  inspectPackageManifest,
+} from "./qti-package-plan.js";
 import {
   itemReferencesForPackageShape,
   parseAssessmentTestPackageModel,
   parsePackageItems,
 } from "./qti-package-items.js";
 import type { QtiPackageParseResult } from "./qti-package-types.js";
-import { parseXmlFiles } from "./qti-package-xml.js";
+import { parseXmlFiles, pushXmlDiagnostics } from "./qti-package-xml.js";
 import {
   DEFAULT_QTI_PACKAGE_RESOURCE_LIMITS,
   decodeUtf8,
   readQtiPackageZipEntries,
+  readQtiPackageZipEntriesAsync,
+  resolveResourceLimits,
   type QtiPackageEntry,
   type QtiPackageParseOptions,
 } from "./qti-package-zip.js";
 import type { QtiDiagnostic } from "./types.js";
 
-export { DEFAULT_QTI_PACKAGE_RESOURCE_LIMITS, decodeUtf8, readQtiPackageZipEntries };
+export {
+  DEFAULT_QTI_PACKAGE_RESOURCE_LIMITS,
+  decodeUtf8,
+  readQtiPackageZipEntries,
+  readQtiPackageZipEntriesAsync,
+};
 export { discoverQtiPackageContentAssets } from "./qti-package-assets.js";
 export { normalizePackagePath } from "./qti-package-paths.js";
-export { QTI_ITEM_RESOURCE_TYPE, QTI_PACKAGE_MANIFEST_PATH } from "./qti-package-manifest.js";
+export { scopeDiagnosticToPackagePath } from "./qti-package-xml.js";
+export {
+  QTI_ITEM_RESOURCE_TYPE,
+  QTI_PACKAGE_MANIFEST_PATH,
+  isQtiItemResource,
+} from "./qti-package-manifest.js";
 export type { QtiPackageEntry };
 
 export type {
@@ -35,6 +51,7 @@ export type {
   QtiPackageItem,
   QtiPackageItemSource,
   QtiPackageParseResult,
+  QtiPackageXmlFileSummary,
   QtiPackageShape,
   QtiItemSessionControl,
   QtiStandardAlignment,
@@ -48,6 +65,8 @@ export type {
 export type {
   QtiPackageInflateContext,
   QtiPackageInflateRaw,
+  QtiPackageInflateRawAsync,
+  QtiPackageZipAsyncOptions,
   QtiPackageParseOptions,
   QtiPackageResourceLimits,
 } from "./qti-package-zip.js";
@@ -59,12 +78,82 @@ export function parseQtiPackage(
 ): QtiPackageParseResult {
   const diagnostics: QtiDiagnostic[] = [];
   const entries = readQtiPackageZipEntries(bytes, options, diagnostics);
-  return parseQtiPackageEntries(entries, options, diagnostics);
+  return parseQtiPackageEntries(entries, diagnostics);
+}
+
+/**
+ * Parse already extracted or restored entries with the same package semantics as ZIP input.
+ * Paths must be unique and canonical. Entry count and expanded byte limits apply;
+ * compression-ratio limits are irrelevant after extraction. Inspect ok before use.
+ */
+export function parseQtiPackageFromEntries(
+  entries: readonly QtiPackageEntry[],
+  options: Pick<QtiPackageParseOptions, "limits"> = {},
+): QtiPackageParseResult {
+  const diagnostics: QtiDiagnostic[] = [];
+  const limits = resolveResourceLimits(options.limits, diagnostics);
+  if (limits) {
+    if (entries.length > limits.maxEntries) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.entries.limit",
+        "error",
+        "Package contains more entries than allowed.",
+      );
+    } else {
+      let total = 0;
+      const paths = new Set<string>();
+      for (const entry of entries) {
+        const path = normalizePackagePath(entry.path, "entry", diagnostics);
+        if (path === undefined) break;
+        if (!path || path !== entry.path || path.includes("\\") || path.includes("\0")) {
+          pushPackageDiagnostic(
+            diagnostics,
+            "package.entry.path",
+            "error",
+            "Package entry paths must be canonical and package-relative.",
+            entry.path,
+          );
+          break;
+        }
+        if (paths.has(path)) {
+          pushPackageDiagnostic(
+            diagnostics,
+            "package.entry.duplicate",
+            "error",
+            `QTI package contains duplicate entry ${path}.`,
+            path,
+          );
+          break;
+        }
+        paths.add(path);
+        total += entry.bytes.byteLength;
+        if (
+          entry.bytes.byteLength > limits.maxEntryUncompressedBytes ||
+          !Number.isSafeInteger(total) ||
+          total > limits.maxTotalUncompressedBytes
+        ) {
+          pushPackageDiagnostic(
+            diagnostics,
+            "package.bytes.limit",
+            "error",
+            "Package entry or total size exceeds its configured budget.",
+            path,
+          );
+          break;
+        }
+      }
+    }
+  }
+  if (diagnostics.length) {
+    const { itemCount: _itemCount, ...summary } = failedPackageSummary(diagnostics);
+    return { ...summary, entries: [], items: [], xmlFiles: [] };
+  }
+  return parseQtiPackageEntries(entries, diagnostics);
 }
 
 function parseQtiPackageEntries(
   entries: readonly QtiPackageEntry[],
-  options: QtiPackageParseOptions,
   diagnostics: QtiDiagnostic[],
 ): QtiPackageParseResult {
   const entriesByPath = indexEntries(entries, diagnostics);
@@ -116,6 +205,16 @@ function parseQtiPackageEntries(
     ...summary,
     entries,
     items,
+    xmlFiles: [...xmlFilesByPath.values()].map((file) => {
+      const xmlDiagnostics: QtiDiagnostic[] = [];
+      pushXmlDiagnostics(file, xmlDiagnostics);
+      return {
+        path: file.path,
+        rootLocalName: file.root?.localName,
+        rootNamespaceUri: file.root?.uri,
+        diagnostics: xmlDiagnostics,
+      };
+    }),
   };
 }
 

package/src/response-validation-policy.ts

@@ -31,6 +31,8 @@ export function responseLimitAttribute(
   choiceKey: "min-choices" | "max-choices",
   associationKey: "min-associations" | "max-associations",
 ): string | undefined {
+  if (interaction.type === "extendedText")
+    return interaction.attributes[choiceKey === "min-choices" ? "min-strings" : "max-strings"];
   if (interaction.type === "order" || interaction.type === "graphicOrder") {
     return interaction.attributes[choiceKey];
   }
@@ -42,7 +44,7 @@ function interactionRequiresResponse(interaction: QtiInteraction): boolean {
 }
 
 export function minimumRequiredResponses(interaction: QtiInteraction | undefined): number {
-  if (!interaction) return 1;
+  if (!interaction) return 0;
   if (interaction.type === "media") return minimumMediaPlays(interaction);
   const explicit = responseLimitAttribute(interaction, "min-choices", "min-associations");
   if (explicit === undefined) return interactionRequiresResponse(interaction) ? 1 : 0;
@@ -54,6 +56,10 @@ export function maximumAllowedResponses(
 ): number | undefined {
   if (!interaction) return undefined;
   if (interaction.type === "media") return maximumMediaPlays(interaction);
+  if (interaction.type === "extendedText") {
+    const maximum = interaction.attributes["max-strings"];
+    return maximum === undefined ? undefined : parseNonNegativeInteger(maximum);
+  }
   if (
     (interaction.type === "order" || interaction.type === "graphicOrder") &&
     !orderSubsetLimitsActive(interaction)
@@ -61,7 +67,32 @@ export function maximumAllowedResponses(
     return undefined;
   }
   const explicit = responseLimitAttribute(interaction, "max-choices", "max-associations");
-  if (explicit === undefined) return undefined;
+  if (explicit === undefined) {
+    switch (interaction.type) {
+      case "associate":
+      case "match":
+      case "gapMatch":
+      case "graphicAssociate":
+      case "graphicGapMatch":
+      case "choice":
+      case "hottext":
+      case "hotspot":
+      case "positionObject":
+        return 1;
+      case "custom":
+      case "drawing":
+      case "endAttempt":
+      case "graphicOrder":
+      case "inlineChoice":
+      case "order":
+      case "portableCustom":
+      case "selectPoint":
+      case "slider":
+      case "textEntry":
+      case "upload":
+        return undefined;
+    }
+  }
   const parsed = parseNonNegativeInteger(explicit);
   return parsed === undefined || parsed <= 0 ? undefined : parsed;
 }
@@ -90,6 +121,7 @@ export { maximumMediaPlays, minimumMediaPlays };
 export function responseValidationPolicy(
   declaration: { readonly correctResponse: QtiValue | null },
   interaction: QtiInteraction | undefined,
+  requireScoredResponses = false,
 ): QtiResponseValidationPolicy {
   const authoredMinimum =
     interaction === undefined
@@ -97,16 +129,20 @@ export function responseValidationPolicy(
       : responseLimitAttribute(interaction, "min-choices", "min-associations");
   const minimum = interaction === undefined ? undefined : minimumRequiredResponses(interaction);
   const validatesMinimum =
-    declaration.correctResponse !== null ||
+    (requireScoredResponses && declaration.correctResponse !== null) ||
     interaction?.type === "media" ||
     authoredMinimum !== undefined ||
     (minimum !== undefined && minimum > 0);
   const maximum = maximumAllowedResponses(interaction);
+  const hasMatchMaximum = interaction?.choices.some(
+    (choice) => choiceMatchMaximum(choice) !== undefined,
+  );
   if (
     declaration.correctResponse === null &&
     interaction?.type !== "media" &&
     !validatesMinimum &&
-    maximum === undefined
+    maximum === undefined &&
+    !hasMatchMaximum
   ) {
     return { checkMinimum: false, checkMaximum: false, checkMatchMax: false };
   }
@@ -225,3 +261,39 @@ export function matchMaxDiagnostics(
   }
   return diagnostics;
 }
+
+/** Enforce authored per-choice minimum uses when a response is finalized. */
+export function matchMinDiagnostics(
+  responseIdentifier: string,
+  interaction: QtiInteraction,
+  response: QtiValue,
+): QtiDiagnostic[] {
+  if (
+    !["associate", "graphicAssociate", "match", "gapMatch", "graphicGapMatch"].includes(
+      interaction.type,
+    )
+  )
+    return [];
+  const pairs = qtiValueToIdentifierList(response);
+  const diagnostics: QtiDiagnostic[] = [];
+  for (const choice of interaction.choices) {
+    const minimum = parseNonNegativeInteger(choice.attributes["match-min"] ?? "0") ?? 0;
+    if (minimum === 0) continue;
+    const side =
+      choice.role === "matchSource" || choice.role === "gapChoice"
+        ? "source"
+        : choice.role === "matchTarget" ||
+            (interaction.type === "graphicGapMatch" && choice.role === "hotspot")
+          ? "target"
+          : "either";
+    if (directedPairChoiceUseCount(choice, pairs, side) >= minimum) continue;
+    diagnostics.push({
+      code: "response.matchMin",
+      severity: "error",
+      message: `${choice.text || choice.identifier} must be used at least ${minimum} time${minimum === 1 ? "" : "s"}.`,
+      path: responseIdentifier,
+      source: choice.source,
+    });
+  }
+  return diagnostics;
+}

package/src/response-validation.ts

@@ -8,11 +8,14 @@ import type {
   QtiScalarValue,
   QtiValue,
 } from "./types.js";
+import { isQtiTextResponseRecord, qtiTextResponseString } from "./text-response.js";
 import { assertNever } from "./assert-never.js";
-import { isNullResponse, isRecordValue, valueContainer } from "./processing-values.js";
+import { isNullResponse, valueContainer } from "./processing-values.js";
+import { isRecordValue } from "./value-guards.js";
 import { listNamedResponseInputs, type QtiNamedResponseInput } from "./response-input.js";
 import {
   matchMaxDiagnostics,
+  matchMinDiagnostics,
   maximumAllowedResponses,
   maximumResponseDiagnostic,
   mediaPlayCount,
@@ -33,6 +36,7 @@ export type QtiResponseValidationDiagnosticCode =
   | "response.required"
   | "response.maximum"
   | "response.matchMax"
+  | "response.matchMin"
   | "response.cardinality"
   | "response.baseType"
   | "response.domain"
@@ -65,6 +69,8 @@ export interface QtiResponseValidationInput {
   item: QtiAssessmentItem;
   responses: QtiResponseVariablesInput;
   allowIncompleteResponses?: boolean | undefined;
+  /** Host policy: require a scored response when no minimum is authored; defaults to false. */
+  requireScoredResponses?: boolean | undefined;
   allowedUndeclaredResponseIdentifiers?: readonly string[] | undefined;
   responseIdentifiers?: Iterable<string> | undefined;
 }
@@ -113,6 +119,17 @@ export function parseQtiResponseVariables(
       if (cardinalityMatches && parsedValue !== undefined) {
         responses.set(declaration.identifier, parsedValue);
         validateResponseDomain(declaration, interactions ?? [], parsedValue, diagnostics);
+        if (
+          declaration.cardinality === "record" &&
+          parsedValue !== null &&
+          interactions?.some(
+            (interaction) =>
+              interaction.type === "textEntry" || interaction.type === "extendedText",
+          ) &&
+          !isQtiTextResponseRecord(parsedValue)
+        ) {
+          pushResponseDomainDiagnostic(declaration, parsedValue, diagnostics);
+        }
       }
     }
 
@@ -122,6 +139,7 @@ export function parseQtiResponseVariables(
         undefined,
         value,
         input.allowIncompleteResponses,
+        input.requireScoredResponses,
         diagnostics,
       );
       continue;
@@ -133,6 +151,7 @@ export function parseQtiResponseVariables(
         interaction,
         value,
         input.allowIncompleteResponses,
+        input.requireScoredResponses,
         diagnostics,
       );
     }
@@ -379,17 +398,37 @@ function validateDeclarationResponse(
   interaction: QtiInteraction | undefined,
   value: QtiValue | undefined,
   allowIncompleteResponses: boolean | undefined,
+  requireScoredResponses: boolean | undefined,
   diagnostics: QtiResponseValidationDiagnostic[],
 ): void {
-  const policy = responseValidationPolicy(declaration, interaction);
+  if (interaction && !allowIncompleteResponses) {
+    diagnostics.push(
+      ...matchMinDiagnostics(declaration.identifier, interaction, value ?? null).map((diagnostic) =>
+        attachResponseIdentifier(declaration.identifier, diagnostic),
+      ),
+    );
+  }
+  const policy = responseValidationPolicy(declaration, interaction, requireScoredResponses);
   if (!policy.checkMinimum && !policy.checkMaximum && !policy.checkMatchMax) return;
 
   const effectiveValue = value ?? null;
   const count =
-    interaction?.type === "media" ? mediaPlayCount(effectiveValue) : responseCount(effectiveValue);
+    interaction?.type === "extendedText" || interaction?.type === "textEntry"
+      ? Array.isArray(effectiveValue)
+        ? effectiveValue.filter((entry) => entry !== "").length
+        : qtiTextResponseString(effectiveValue) === ""
+          ? 0
+          : 1
+      : interaction?.type === "media"
+        ? mediaPlayCount(effectiveValue)
+        : responseCount(effectiveValue);
 
   if (policy.checkMinimum && !allowIncompleteResponses) {
-    const minimum = effectiveMinimumRequiredResponses(declaration, interaction);
+    const minimum = effectiveMinimumRequiredResponses(
+      declaration,
+      interaction,
+      requireScoredResponses,
+    );
     if (count < minimum) {
       diagnostics.push(
         attachResponseIdentifier(
@@ -424,9 +463,15 @@ function validateDeclarationResponse(
 function effectiveMinimumRequiredResponses(
   declaration: { readonly correctResponse: QtiValue | null },
   interaction: QtiInteraction | undefined,
+  requireScoredResponses: boolean | undefined,
 ): number {
   const minimum = minimumRequiredResponses(interaction);
-  if (declaration.correctResponse === null || hasAuthoredMinimum(interaction)) return minimum;
+  if (
+    !requireScoredResponses ||
+    declaration.correctResponse === null ||
+    hasAuthoredMinimum(interaction)
+  )
+    return minimum;
   return Math.max(minimum, 1);
 }
 
@@ -453,6 +498,7 @@ function isResponseValidationDiagnosticCode(
     code === "response.required" ||
     code === "response.maximum" ||
     code === "response.matchMax" ||
+    code === "response.matchMin" ||
     code === "response.cardinality" ||
     code === "response.baseType" ||
     code === "response.domain" ||

package/src/scoring-disposition-policy.ts

@@ -1,5 +1,5 @@
 import type { QtiAssessmentItem } from "./types.js";
-import { itemExpectsAutomatedScore } from "./item-scoring-expectation.js";
+import { itemExpectsAutomatedScore, itemHasExternalScore } from "./item-scoring-expectation.js";
 
 export type QtiItemSubmissionScoringDisposition =
   | "scored"
@@ -23,7 +23,11 @@ export function itemHasManuallyScoredInteractions(item: QtiAssessmentItem): bool
 }
 
 export function itemNeedsScoringFollowUpWhenUnscored(item: QtiAssessmentItem): boolean {
-  return itemExpectsAutomatedScore(item) || itemHasManuallyScoredInteractions(item);
+  return (
+    itemHasExternalScore(item) ||
+    itemExpectsAutomatedScore(item) ||
+    itemHasManuallyScoredInteractions(item)
+  );
 }
 
 /** Default generic disposition taxonomy shipped by qti3-core for submission materialization. */
@@ -31,6 +35,7 @@ export function classifyQtiItemScoringDisposition(
   item: QtiAssessmentItem,
   score: number | null,
 ): Exclude<QtiItemSubmissionScoringDisposition, "invalid"> {
+  if (itemHasExternalScore(item)) return "manual-scoring-required";
   if (score !== null) return "scored";
   if (itemNeedsScoringFollowUpWhenUnscored(item)) return "manual-scoring-required";
   return "unscored-reference";

package/src/serializer-processing-expressions.ts

@@ -79,8 +79,6 @@ export function serializeExpression(
       return serializeBaseValue(expression, context, indent);
     case "null":
       return renderElement("qti-null", [], [], indent);
-    case "isNull":
-      return serializeIsNull(expression, context, indent);
     case "matchCorrect":
       return serializeMatchCorrect(expression, context, indent);
     case "randomInteger":
@@ -104,13 +102,6 @@ export function serializeExpression(
         [],
         indent,
       );
-    case "random":
-      return renderElement(
-        "qti-random",
-        [],
-        expression.values.flatMap((value) => serializeExpression(value, context, indent + 1)),
-        indent,
-      );
     case "index":
       return renderExpressionContainer(
         "qti-index",
@@ -143,6 +134,14 @@ export function serializeExpression(
       );
     case "not":
       return renderExpressionContainer("qti-not", [], [expression.expression], context, indent);
+    case "equal":
+      return renderExpressionContainer(
+        "qti-equal",
+        sortedBagAttributes(expression.attributes),
+        [expression.left, expression.right],
+        context,
+        indent,
+      );
     case "equalRounded":
       return renderExpressionContainer(
         "qti-equal-rounded",
@@ -337,22 +336,6 @@ function baseValueText(
   return qtiValueToString(expression.value);
 }
 
-function serializeIsNull(
-  expression: Extract<QtiProcessingExpression, { type: "isNull" }>,
-  context: SerializationContext,
-  indent: number,
-): string[] {
-  if (!requireIdentifier(expression.identifier, "qti-is-null", expression.source, context)) {
-    return [];
-  }
-  return renderElement(
-    "qti-is-null",
-    [],
-    renderElement("qti-variable", [["identifier", expression.identifier]], [], indent + 1),
-    indent,
-  );
-}
-
 function serializeMatchCorrect(
   expression: Extract<QtiProcessingExpression, { type: "matchCorrect" }>,
   context: SerializationContext,

package/src/server-scoring.ts

@@ -28,6 +28,7 @@ export function scoreQtiItemServerSide(input: QtiServerScoringInput): QtiServerS
     itemXml: input.itemXml,
     diagnosticPrefix: "serverScoring",
     allowedUndeclaredResponseIdentifiers: input.allowedUndeclaredResponseIdentifiers,
+    sessionEnvironment: input.sessionEnvironment,
     submission: {
       trustedResponses: input.trustedResponses,
       trustedInteractionStates: input.trustedInteractionStates,

package/src/session-builtins.ts

@@ -0,0 +1,75 @@
+import type { QtiBuiltInVariables, QtiDiagnostic, QtiSessionContext, QtiValue } from "./types.js";
+
+export interface QtiSessionEnvironment {
+  /** Host context, resolved before template processing. Unspecified fields are empty strings. */
+  context?: Partial<QtiSessionContext> | undefined;
+  /** Accumulated item-session seconds supplied by a scoring host. */
+  duration?: number | undefined;
+  /** Monotonic milliseconds supplied by a delivery host; suspension time is excluded. */
+  now?: (() => number) | undefined;
+}
+
+export function createSessionBuiltIns(
+  prior: QtiBuiltInVariables | undefined,
+  options: QtiSessionEnvironment,
+  report: (diagnostic: QtiDiagnostic) => void,
+) {
+  const state: QtiBuiltInVariables = {
+    numAttempts: prior?.numAttempts ?? 0,
+    attemptInProgress: prior?.attemptInProgress ?? false,
+    duration: options.duration ?? prior?.duration ?? (options.now ? 0 : null),
+    context: {
+      candidateIdentifier:
+        options.context?.candidateIdentifier ?? prior?.context.candidateIdentifier ?? "",
+      testIdentifier: options.context?.testIdentifier ?? prior?.context.testIdentifier ?? "",
+      environmentIdentifier:
+        options.context?.environmentIdentifier ?? prior?.context.environmentIdentifier ?? "",
+    },
+  };
+  let previousTime = options.now?.();
+  let elapsed = state.duration;
+  let timingValid = elapsed === null || (Number.isFinite(elapsed) && elapsed >= 0);
+  if (!timingValid) state.duration = elapsed = null;
+
+  function captureTime(active: boolean): void {
+    if (!options.now) return;
+    const current = options.now();
+    if (
+      !Number.isFinite(current) ||
+      previousTime === undefined ||
+      !Number.isFinite(previousTime) ||
+      current < previousTime
+    ) {
+      timingValid = false;
+      elapsed = state.duration = null;
+    } else if (active && elapsed !== null) {
+      elapsed += (current - previousTime) / 1000;
+      // Preserve clock precision across suspension and restoration.
+      state.duration = elapsed;
+    }
+    previousTime = current;
+  }
+
+  function duration(): QtiValue {
+    if (state.duration !== null && timingValid) return Math.floor(state.duration * 1000) / 1000;
+    report({
+      code: timingValid ? "session.duration.unavailable" : "session.duration.invalid",
+      severity: "error",
+      message: timingValid
+        ? "Reading duration requires host-supplied accumulated seconds or a monotonic clock."
+        : "Duration requires finite non-negative seconds and a monotonic finite clock.",
+    });
+    return null;
+  }
+
+  return { state, captureTime, duration };
+}
+
+export function builtInVariableBaseType(
+  identifier: string,
+): "integer" | "float" | "identifier" | undefined {
+  if (identifier === "numAttempts") return "integer";
+  if (identifier === "duration") return "float";
+  if (identifier === "completionStatus") return "identifier";
+  return undefined;
+}