@longsightgroup/qti3-core 0.10.6 → 0.11.0

package/src/support.ts

@@ -92,7 +92,11 @@ export const processingSupport: QtiProcessingElementSupport[] = [
     "packages/fixtures/xml/random-integer-template-reference.xml",
     "packages/fixtures/xml/template-content-reference.xml",
   ]),
-  templateProcessingEntry("qti-set-default-value"),
+  {
+    ...templateProcessingEntry("qti-set-default-value"),
+    notes:
+      "Updates effective response/outcome defaults for the clone, including explicit NULL overrides; rejected template passes discard their overrides.",
+  },
   templateProcessingEntry("qti-set-correct-response", [
     "packages/fixtures/xml/template-processing-reference.xml",
     "packages/fixtures/xml/random-integer-template-reference.xml",
@@ -133,32 +137,65 @@ export const processingSupport: QtiProcessingElementSupport[] = [
   operatorProcessingEntry("qti-null"),
   mappingProcessingEntry("qti-match-table"),
   mappingProcessingEntry("qti-match-table-entry"),
-  mappingProcessingEntry("qti-interpolation-table"),
+  {
+    ...mappingProcessingEntry("qti-interpolation-table"),
+    notes:
+      "Selects the first authored entry whose source-value is below the input, including equality only when include-boundary permits it.",
+  },
   mappingProcessingEntry("qti-interpolation-table-entry"),
-  operatorProcessingEntry("qti-is-null"),
+  {
+    ...operatorProcessingEntry("qti-is-null"),
+    notes:
+      "Accepts one arbitrary expression, evaluates it in the full variable context, and tests the result for NULL.",
+  },
   mappingProcessingEntry("qti-match", [
     "packages/fixtures/xml/generic-match-processing-reference.xml",
     "packages/fixtures/xml/advanced-processing-reference.xml",
   ]),
   mappingProcessingEntry("qti-correct"),
-  mappingProcessingEntry("qti-default"),
-  mappingProcessingEntry("qti-map-response"),
-  mappingProcessingEntry("qti-map-response-point"),
-  responseProcessingEntry("qti-variable", [
-    "packages/fixtures/xml/generic-match-processing-reference.xml",
-    "packages/fixtures/xml/template-processing-reference.xml",
-    "packages/fixtures/xml/random-integer-template-reference.xml",
-    "packages/fixtures/xml/template-content-reference.xml",
-    "packages/fixtures/xml/advanced-processing-reference.xml",
-    "packages/fixtures/xml/adaptive-feedback-reference.xml",
-  ]),
+  {
+    ...mappingProcessingEntry("qti-default", [], [processingTemplateTest]),
+    notes:
+      "Reads the effective authored or template-overridden default, independently of the variable's current value.",
+  },
+  {
+    ...mappingProcessingEntry("qti-map-response"),
+    notes:
+      "String map entries honor case-sensitive (default false); mapping counts each distinct response value once using QTI base-type equality, then applies bounds.",
+  },
+  {
+    ...mappingProcessingEntry("qti-map-response-point"),
+    notes:
+      "Each point selects the first matching authored area; each selected area contributes at most once.",
+  },
+  {
+    ...responseProcessingEntry("qti-variable", [
+      "packages/fixtures/xml/generic-match-processing-reference.xml",
+      "packages/fixtures/xml/template-processing-reference.xml",
+      "packages/fixtures/xml/random-integer-template-reference.xml",
+      "packages/fixtures/xml/template-content-reference.xml",
+      "packages/fixtures/xml/advanced-processing-reference.xml",
+      "packages/fixtures/xml/adaptive-feedback-reference.xml",
+    ]),
+    notes:
+      "Resolves declared variables and implicit completionStatus, numAttempts, timed-item duration (float seconds), and QTI_CONTEXT; session environment is resolved before template processing.",
+    tests: [
+      processingResponseTest,
+      "packages/core/src/session-builtins.test.ts",
+      "tests/browser/player-lifecycle.spec.ts",
+    ],
+  },
   templateProcessingEntry(
     "qti-random-integer",
     ["packages/fixtures/xml/random-integer-template-reference.xml"],
     [...processingBrowserEvidence["qti-random-integer"]],
   ),
   operatorProcessingEntry("qti-random-float"),
-  operatorProcessingEntry("qti-random"),
+  {
+    ...operatorProcessingEntry("qti-random"),
+    notes:
+      "Evaluates one multiple/ordered container expression, including variables, then selects a scalar member; NULL/empty containers return NULL and serialization retains the operand.",
+  },
   operatorProcessingEntry("qti-multiple", [
     "packages/fixtures/xml/advanced-processing-reference.xml",
   ]),
@@ -166,7 +203,15 @@ export const processingSupport: QtiProcessingElementSupport[] = [
     "packages/fixtures/xml/advanced-processing-reference.xml",
   ]),
   operatorProcessingEntry("qti-index"),
-  operatorProcessingEntry("qti-contains"),
+  {
+    ...operatorProcessingEntry(
+      "qti-contains",
+      [],
+      ["packages/core/src/processing-containment.test.ts"],
+    ),
+    notes:
+      "Multiple containers use multiset containment; ordered containers require a contiguous sequence and preserve duplicate counts, including variable/delete/repeat operands.",
+  },
   operatorProcessingEntry("qti-container-size", [
     "packages/fixtures/xml/advanced-processing-reference.xml",
   ]),
@@ -192,10 +237,20 @@ export const processingSupport: QtiProcessingElementSupport[] = [
   operatorProcessingEntry("qti-any-n"),
   operatorProcessingEntry("qti-or"),
   operatorProcessingEntry("qti-not"),
-  operatorProcessingEntry("qti-equal"),
-  operatorProcessingEntry("qti-equal-rounded", [
-    "packages/fixtures/xml/advanced-processing-reference.xml",
-  ]),
+  {
+    ...operatorProcessingEntry("qti-equal", [], ["packages/core/src/processing-equality.test.ts"]),
+    notes:
+      "Preserves and evaluates exact, absolute, and relative tolerance with asymmetric bounds, variable tolerances, and inclusive/exclusive boundaries.",
+  },
+  {
+    ...operatorProcessingEntry(
+      "qti-equal-rounded",
+      ["packages/fixtures/xml/advanced-processing-reference.xml"],
+      ["packages/core/src/processing-equality.test.ts"],
+    ),
+    notes:
+      "Defaults rounding-mode to significantFigures and resolves integer-or-variable-reference figures at evaluation time, preserving both through serialization.",
+  },
   mappingProcessingEntry("qti-field-value"),
   operatorProcessingEntry("qti-lt"),
   operatorProcessingEntry("qti-lte"),
@@ -203,7 +258,12 @@ export const processingSupport: QtiProcessingElementSupport[] = [
   operatorProcessingEntry("qti-gte"),
   operatorProcessingEntry("qti-string-match"),
   operatorProcessingEntry("qti-substring"),
-  operatorProcessingEntry("qti-pattern-match"),
+  {
+    ...operatorProcessingEntry("qti-pattern-match"),
+    tests: [processingOperatorsTest, "packages/core/src/processing-pattern.test.ts"],
+    notes:
+      "XML Schema Appendix F whole-string matching, XML name escapes, Unicode categories/blocks and class subtraction; brace-enclosed pattern variables, NULL propagation and explicit syntax/resource diagnostics. No JavaScript-pattern fallback.",
+  },
   operatorProcessingEntry("qti-member"),
   operatorProcessingEntry("qti-delete"),
   operatorProcessingEntry("qti-duration-gte"),
@@ -272,10 +332,11 @@ export const itemMetadataSupport: QtiItemMetadataElementSupport[] = [
     tests: [
       processingResponseTest,
       "packages/core/src/parser-item-metadata.test.ts",
+      "packages/core/src/adaptive-turn-materializer.test.ts",
       ...browserFeedbackTests,
     ],
     notes:
-      "Parsed by parser-item-metadata.ts and validated by validateModalFeedback. Response processing supplies the outcome value used for visibility, and the player renders the matching feedback in player-feedback.spec.ts.",
+      "Parsed by parser-item-metadata.ts and validated by validateModalFeedback. Response processing supplies the scalar/container outcome used for show/hide visibility, including inverse hide conditions, in both player rendering and adaptive candidate XML materialization.",
   },
   {
     qtiName: "qti-companion-materials-info",
@@ -406,7 +467,7 @@ function entry(qtiName: string, interactionType: QtiInteractionType): QtiInterac
         ? "Supports single and multiple unordered pair responses."
         : "Supports single and multiple directedPair responses."
       : interactionType === "graphicGapMatch"
-        ? "Requires multiple directedPair responses."
+        ? "Requires multiple directedPair responses; multiple and repeated placements in one hotspot preserve each association through rendering, removal, scoring, and restoration, subject to source/target match-max and max-associations."
         : undefined,
   };
 }

package/src/trusted-item-session.ts

@@ -1,3 +1,4 @@
+import type { QtiSessionEnvironment } from "./session-builtins.js";
 import { parseQtiXml } from "./parser.js";
 import { itemExpectsAutomatedScore, itemHasExternalScore } from "./item-scoring-expectation.js";
 import { parseQtiResponseVariables } from "./response-validation.js";
@@ -31,6 +32,8 @@ export interface QtiTrustedResponseApplication {
 }
 
 export interface QtiTrustedItemParseOptions {
+  /** Trusted host environment; never take duration/context from candidate response fields. */
+  sessionEnvironment?: QtiSessionEnvironment | undefined;
   allowedUndeclaredResponseIdentifiers?: readonly string[] | undefined;
 }
 
@@ -48,7 +51,7 @@ export interface RunTrustedItemSessionInput extends QtiTrustedItemParseOptions {
   diagnosticPrefix: QtiTrustedInputDiagnosticPrefix;
   submission: QtiTrustedResponseApplication;
   priorState?: QtiAttemptStateV1 | null | undefined;
-  /** Applied before submission. Intended for server-side scoring, not adaptive turns. */
+  /** Applied before submission, except completed is applied after capture. For server scoring, not adaptive turns. */
   attemptStatus?: QtiAttemptStatus | undefined;
   scoring: QtiTrustedItemScoringPolicy;
   requireNumericScore: boolean;
@@ -156,12 +159,15 @@ export function runTrustedItemSession(
     input.diagnosticPrefix,
     input.allowedUndeclaredResponseIdentifiers,
     parsedResult.parsed.diagnostics,
+    input.sessionEnvironment,
   );
   if (!sessionResult.ok) {
     return emptyTrustedItemSessionFailure(sessionResult.diagnostics);
   }
 
-  if (input.attemptStatus) sessionResult.session.setStatus(input.attemptStatus);
+  if (input.attemptStatus && input.attemptStatus !== "completed") {
+    sessionResult.session.setStatus(input.attemptStatus);
+  }
 
   let submission = input.submission;
   if (input.submissionValidation === "strict") {
@@ -189,6 +195,9 @@ export function runTrustedItemSession(
     return emptyTrustedItemSessionFailure(diagnostics);
   }
 
+  // Capture the submitted attempt before closing it, so built-in counters reflect participation.
+  if (input.attemptStatus === "completed") sessionResult.session.setStatus("completed");
+
   const shouldScore = input.scoring === "always" || applicationResult.appliedSubmission;
   const externalScore = itemHasExternalScore(parsedResult.parsed.document.item);
 
@@ -277,11 +286,13 @@ function createTrustedItemSession(
   diagnosticPrefix: QtiTrustedInputDiagnosticPrefix,
   allowedUndeclaredResponseIdentifiers: readonly string[] | undefined,
   existingDiagnostics: QtiDiagnostic[] = [],
+  sessionEnvironment: QtiSessionEnvironment = {},
 ): { ok: true; session: QtiItemSession } | { ok: false; diagnostics: QtiDiagnostic[] } {
   try {
     return {
       ok: true,
       session: createItemSession(parsed.document, priorState ?? undefined, {
+        ...sessionEnvironment,
         allowedUndeclaredResponseIdentifiers,
       }),
     };

package/src/types.ts

@@ -459,6 +459,13 @@ export interface QtiAssessmentItem {
   stylesheets: QtiStylesheet[];
   body: QtiContentNode[];
   bodyText: string;
+  /** Authored direct children in XML order; omitted for items created without source XML. */
+  sourceChildren?:
+    | readonly {
+        readonly qtiName: string;
+        readonly source?: QtiSourceLocation | undefined;
+      }[]
+    | undefined;
   source?: QtiSourceLocation | undefined;
 }
 
@@ -593,7 +600,7 @@ export type QtiProcessingExpression = (
       baseType?: string | undefined;
     }
   | { type: "null" }
-  | { type: "isNull"; identifier: string }
+  | { type: "isNull"; expression: QtiProcessingExpression }
   | { type: "matchCorrect"; identifier: string; correctIdentifier: string }
   | { type: "match"; left: QtiProcessingExpression; right: QtiProcessingExpression }
   | { type: "correct"; identifier: string }
@@ -614,7 +621,7 @@ export type QtiProcessingExpression = (
       max: number;
       attributes: Record<string, string>;
     }
-  | { type: "random"; values: QtiProcessingExpression[] }
+  | { type: "random"; expression: QtiProcessingExpression }
   | { type: "multiple"; expressions: QtiProcessingExpression[] }
   | { type: "ordered"; expressions: QtiProcessingExpression[] }
   | { type: "index"; expression: QtiProcessingExpression; n: string }
@@ -641,13 +648,18 @@ export type QtiProcessingExpression = (
   | { type: "anyN"; expressions: QtiProcessingExpression[]; min: string; max: string }
   | { type: "or"; expressions: QtiProcessingExpression[] }
   | { type: "not"; expression: QtiProcessingExpression }
-  | { type: "equal"; left: QtiProcessingExpression; right: QtiProcessingExpression }
+  | {
+      type: "equal";
+      left: QtiProcessingExpression;
+      right: QtiProcessingExpression;
+      attributes?: Record<string, string> | undefined;
+    }
   | {
       type: "equalRounded";
       left: QtiProcessingExpression;
       right: QtiProcessingExpression;
       roundingMode: string;
-      figures: number;
+      figures: number | string;
     }
   | {
       type: "numericCompare";
@@ -724,8 +736,22 @@ export interface QtiValidationResult {
   diagnostics: QtiDiagnostic[];
 }
 
+export interface QtiSessionContext {
+  candidateIdentifier: string;
+  testIdentifier: string;
+  environmentIdentifier: string;
+}
+
+export interface QtiBuiltInVariables {
+  numAttempts: number;
+  duration: number | null;
+  attemptInProgress: boolean;
+  context: QtiSessionContext;
+}
+
 export interface QtiAttemptStateV1 {
   schema: "qti3.attempt-state.v1";
+  builtInVariables?: QtiBuiltInVariables | undefined;
   itemIdentifier: string;
   status: QtiAttemptStatus;
   responses: Record<string, QtiValue>;

package/src/validation-declaration-entries.ts

@@ -5,7 +5,7 @@ import {
   isNumericCsv,
   numericCsv,
 } from "./validation-geometry.js";
-import { isFiniteNumber, isInteger } from "./validation-primitives.js";
+import { isBooleanAttribute, isFiniteNumber, isInteger } from "./validation-primitives.js";
 
 interface DeclarationEntryAttributes {
   attributes: Record<string, string>;
@@ -18,6 +18,16 @@ export function validateMapEntryAttributes(
   entry: DeclarationEntryAttributes,
   diagnostics: QtiDiagnostic[],
 ): void {
+  const caseSensitive = entry.attributes["case-sensitive"];
+  if (caseSensitive !== undefined && !isBooleanAttribute(caseSensitive)) {
+    diagnostics.push({
+      code: "mapEntry.caseSensitive",
+      severity: "error",
+      message: `Response declaration ${declarationIdentifier} map entry requires a boolean case-sensitive value.`,
+      path: entry.source?.path,
+      source: entry.source,
+    });
+  }
   if (!entry.attributes["map-key"]) {
     diagnostics.push({
       code: "mapEntry.mapKey.required",

package/src/validation-item-children.ts

@@ -0,0 +1,48 @@
+import type { QtiAssessmentItem, QtiDiagnostic } from "./types.js";
+
+// QTI 3.0.1 AssessmentItemDType sequence:
+// https://purl.imsglobal.org/spec/qti/v3p0/schema/xsd/imsqti_itemv3p0p1_v1p0.xsd
+const itemChildOrder: readonly string[] = [
+  "qti-context-declaration",
+  "qti-response-declaration",
+  "qti-outcome-declaration",
+  "qti-template-declaration",
+  "qti-template-processing",
+  "qti-assessment-stimulus-ref",
+  "qti-companion-materials-info",
+  "qti-stylesheet",
+  "qti-item-body",
+  "qti-catalog-info",
+  "qti-response-processing",
+  "qti-modal-feedback",
+];
+
+/** Validate the authored direct-child sequence retained by the XML parser. */
+export function validateAssessmentItemChildren(
+  item: QtiAssessmentItem,
+  diagnostics: QtiDiagnostic[],
+): void {
+  let lastOrder = -1;
+  for (const child of item.sourceChildren ?? []) {
+    const order = itemChildOrder.indexOf(child.qtiName);
+    if (order < 0) {
+      diagnostics.push({
+        code: "assessmentItem.child.unsupported",
+        severity: "error",
+        message: `qti-assessment-item does not allow ${child.qtiName} as a direct child.`,
+        path: child.source?.path,
+        source: child.source,
+      });
+    } else if (order < lastOrder) {
+      diagnostics.push({
+        code: "assessmentItem.child.order",
+        severity: "error",
+        message: `${child.qtiName} appears out of QTI 3 qti-assessment-item child order.`,
+        path: child.source?.path,
+        source: child.source,
+      });
+    } else {
+      lastOrder = order;
+    }
+  }
+}

package/src/validation-processing.ts

@@ -7,6 +7,7 @@ import type {
   QtiSetOutcomeValue,
   QtiTemplateRule,
 } from "./types.js";
+import { parseXmlSchemaRegex, patternVariableIdentifier } from "./xml-schema-regex.js";
 import { expressionChildren } from "./processing-expression-children.js";
 import { MAX_QTI_REPEAT_RESULT_ELEMENTS } from "./processing-limits.js";
 import { MATH_OPERATOR_NAMES, STATS_OPERATOR_NAMES } from "./processing-operators.js";
@@ -21,6 +22,7 @@ import {
   isInteger,
 } from "./validation-primitives.js";
 import { COMPLETION_STATUS } from "./attempt-state-constants.js";
+import { validateEqualTolerance } from "./processing-equality.js";
 
 export function validateResponseProcessingTemplate(
   item: QtiAssessmentItem,
@@ -120,7 +122,14 @@ export function validateProcessingReferences(
   const outcomes = new Set(item.outcomeDeclarations.map((declaration) => declaration.identifier));
   outcomes.add(COMPLETION_STATUS);
   const templates = new Set(item.templateDeclarations.map((declaration) => declaration.identifier));
-  const variables = new Set([...responses, ...outcomes, ...templates]);
+  const variables = new Set([
+    ...responses,
+    ...outcomes,
+    ...templates,
+    "numAttempts",
+    "QTI_CONTEXT",
+    ...(item.timeDependent ? ["duration"] : []),
+  ]);
 
   for (const rule of item.templateProcessing?.rules ?? []) {
     validateTemplateRule(rule, responses, outcomes, templates, variables, diagnostics);
@@ -324,7 +333,7 @@ function validateExpressionReferences(
 ): void {
   if (!expression) return;
 
-  if (expression.type === "variable" || expression.type === "isNull") {
+  if (expression.type === "variable") {
     validateProcessingIdentifier(
       expression.identifier,
       "processing.variable",
@@ -429,6 +438,30 @@ function validateExpressionReferences(
     }
   }
 
+  if (expression.type === "patternMatch") {
+    const reference = patternVariableIdentifier(expression.pattern);
+    if (reference !== undefined) {
+      if (!variables.has(reference))
+        diagnostics.push({
+          code: "processing.variable.reference",
+          severity: "error",
+          message: `Pattern references missing variable ${reference}.`,
+          source: expression.source,
+          path: expression.source?.path,
+        });
+    } else {
+      const parsed = parseXmlSchemaRegex(expression.pattern);
+      if (!parsed.ok)
+        diagnostics.push({
+          code: `processing.pattern.${parsed.problem.code}`,
+          severity: "error",
+          message: parsed.problem.message,
+          source: expression.source,
+          path: expression.source?.path,
+        });
+    }
+  }
+
   if (expression.type === "randomInteger") {
     validateRandomIntegerExpression(expression, diagnostics);
   }
@@ -446,11 +479,16 @@ function validateExpressionReferences(
       "qti-equal-rounded",
       expression.roundingMode,
       expression.figures,
+      variables,
       diagnostics,
       expression.source,
     );
   }
 
+  if (expression.type === "equal") {
+    validateEqualTolerance(expression, variables, diagnostics);
+  }
+
   if (expression.type === "anyN") {
     validateAnyNBound("min", expression.min, responses, variables, diagnostics, expression.source);
     validateAnyNBound("max", expression.max, responses, variables, diagnostics, expression.source);
@@ -544,7 +582,8 @@ const statsOperatorNames = new Set<string>(STATS_OPERATOR_NAMES);
 function validateRounding(
   qtiName: string,
   roundingMode: string,
-  figures: number,
+  figures: number | string,
+  variables: ReadonlySet<string>,
   diagnostics: QtiDiagnostic[],
   source: QtiDiagnostic["source"],
 ): void {
@@ -558,7 +597,10 @@ function validateRounding(
     });
   }
   const validFigures =
-    Number.isInteger(figures) && (roundingMode === "decimalPlaces" ? figures >= 0 : figures > 0);
+    typeof figures === "string"
+      ? variables.has(figures)
+      : Number.isInteger(figures) &&
+        (roundingMode === "decimalPlaces" ? figures >= 0 : figures > 0);
   if (!validFigures) {
     diagnostics.push({
       code: "processing.roundingFigures",
@@ -683,12 +725,7 @@ function minimumExpressionElements(expression: QtiProcessingExpression): number
     return minimumProducedElements(expression.expressions);
   }
   if (expression.type === "random") {
-    if (expression.values.length === 0) return 0;
-    let minimum = MAX_QTI_REPEAT_RESULT_ELEMENTS + 1;
-    for (const value of expression.values) {
-      minimum = Math.min(minimum, minimumExpressionElements(value));
-    }
-    return minimum;
+    return minimumExpressionElements(expression.expression) > 0 ? 1 : 0;
   }
   if (expression.type !== "repeat" || !/^\d+$/.test(expression.numberRepeats)) return 0;
   const perRepeat = minimumProducedElements(expression.expressions);

package/src/validation.ts

@@ -1,3 +1,4 @@
+import { validateAssessmentItemChildren } from "./validation-item-children.js";
 import type {
   QtiAssessmentItem,
   QtiBaseType,
@@ -44,6 +45,7 @@ export function validateAssessmentItem(document: QtiDocument): QtiValidationResu
 
   requireIdentifier("qti-assessment-item", item.identifier, diagnostics, item.source);
   validateAssessmentItemRoot(item, diagnostics);
+  validateAssessmentItemChildren(item, diagnostics);
   validateItemBody(item, diagnostics);
   validateItemBodySharedVocabulary(item, diagnostics);
   validateDeclarationIdentifiers(item, diagnostics);
@@ -132,6 +134,18 @@ function validateDeclarationIdentifiers(
         source: declaration.source,
       });
     }
+    if (
+      ["numAttempts", "duration", "QTI_CONTEXT"].includes(declaration.identifier) ||
+      (declaration.identifier === COMPLETION_STATUS && declaration.kind !== "outcome")
+    ) {
+      diagnostics.push({
+        code: "declaration.builtIn",
+        severity: "error",
+        message: `${declaration.identifier} is a reserved built-in variable and must not be declared explicitly.`,
+        path: declaration.source?.path,
+        source: declaration.source,
+      });
+    }
     if (seen.has(declaration.identifier)) {
       diagnostics.push({
         code: "identifier.duplicate",

package/src/value-guards.ts

@@ -0,0 +1,6 @@
+import type { QtiRecordValue, QtiValue } from "./types.js";
+
+/** Narrow an already-typed QTI value to its record variant. */
+export function isRecordValue(value: QtiValue): value is QtiRecordValue {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}