@longsightgroup/qti3-core 0.10.6 → 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

@@ -134,11 +134,15 @@ export function responseValidationPolicy(
     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 };
   }

package/src/response-validation.ts

@@ -10,7 +10,8 @@ import type {
 } 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,

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;
+}

package/src/session.ts

@@ -43,6 +43,9 @@ import {
 } from "./processing-state.js";
 import { booleanValue, normalizeValueForCardinality, qtiMatchValues } from "./processing-values.js";
 
+import { createSessionBuiltIns, type QtiSessionEnvironment } from "./session-builtins.js";
+export type { QtiSessionEnvironment } from "./session-builtins.js";
+
 interface SessionProcessingContext {
   responseDefaults: Record<string, QtiValue>;
   evaluation: EvaluationContext;
@@ -58,7 +61,7 @@ interface ConditionalRules<Rule> {
   elseRules: Rule[];
 }
 
-export interface QtiItemSessionOptions {
+export interface QtiItemSessionOptions extends QtiSessionEnvironment {
   randomSeed?: string | number | undefined;
   customOperators?: QtiCustomOperatorRegistry | undefined;
   allowedUndeclaredResponseIdentifiers?: readonly string[] | undefined;
@@ -67,6 +70,8 @@ export interface QtiItemSessionOptions {
 export interface QtiItemSession {
   readonly item: QtiAssessmentItem;
   correctResponses(): Record<string, QtiValue>;
+  /** Starts an attempt without requiring a response; repeated calls and resume are idempotent. */
+  beginAttempt(): void;
   respond(identifier: string, value: QtiValue): void;
   setInteractionState(identifier: string, state: QtiPortableCustomStateValue): void;
   interactionState(identifier: string): QtiPortableCustomStateValue | undefined;
@@ -80,11 +85,12 @@ export function visibleModalFeedback(
   outcomes: Record<string, QtiValue>,
 ): QtiModalFeedback[] {
   return item.modalFeedback.filter((feedback) => {
-    if (feedback.showHide === "hide") return false;
     const outcome = outcomes[feedback.outcomeIdentifier];
     const outcomeValue: QtiValue = outcome === undefined ? null : outcome;
-    if (Array.isArray(outcomeValue)) return outcomeValue.includes(feedback.identifier);
-    return qtiValueToString(outcomeValue) === feedback.identifier;
+    const matches = Array.isArray(outcomeValue)
+      ? outcomeValue.includes(feedback.identifier)
+      : qtiValueToString(outcomeValue) === feedback.identifier;
+    return feedback.showHide === "hide" ? !matches : matches;
   });
 }
 
@@ -109,6 +115,12 @@ export function createItemSession(
   const interactionStates: Record<string, QtiPortableCustomStateValue> = {};
   const correctResponses: Record<string, QtiValue> = {};
   let status: QtiAttemptStatus = priorState?.status ?? "initialized";
+  const builtInDiagnostics: QtiDiagnostic[] = [];
+  const builtIns = createSessionBuiltIns(priorState?.builtInVariables, options, (diagnostic) => {
+    if (!builtInDiagnostics.some((existing) => existing.code === diagnostic.code))
+      builtInDiagnostics.push(diagnostic);
+  });
+  const captureTime = () => builtIns.captureTime(status !== "suspended" && status !== "completed");
   const random = seededRandom(options.randomSeed ?? document.item.identifier);
   const customOperators = options.customOperators ?? {};
   const allowedUndeclaredResponseIdentifiers = new Set(
@@ -131,7 +143,10 @@ export function createItemSession(
     templateValues[declaration.identifier] = cloneValue(declaration.defaultValue);
   }
   for (const outcome of document.item.outcomeDeclarations) {
-    outcomes[outcome.identifier] = cloneValue(outcome.defaultValue);
+    const numericSingle =
+      outcome.cardinality === "single" &&
+      (outcome.baseType === "integer" || outcome.baseType === "float");
+    outcomes[outcome.identifier] = cloneValue(outcome.defaultValue ?? (numericSingle ? 0 : null));
   }
   outcomes[COMPLETION_STATUS] = COMPLETION_NOT_ATTEMPTED;
   const baseResponses = cloneValueRecord(responses);
@@ -145,7 +160,20 @@ export function createItemSession(
     correctResponses,
     random,
     customOperators,
-    { allowedUndeclaredResponseIdentifiers },
+    {
+      allowedUndeclaredResponseIdentifiers,
+      builtInVariable(identifier) {
+        if (identifier === "completionStatus")
+          return outcomes[COMPLETION_STATUS] ?? COMPLETION_NOT_ATTEMPTED;
+        if (identifier === "numAttempts") return builtIns.state.numAttempts;
+        if (identifier === "QTI_CONTEXT") return { ...builtIns.state.context };
+        if (identifier === "duration" && document.item.timeDependent) {
+          captureTime();
+          return builtIns.duration();
+        }
+        return undefined;
+      },
+    },
   );
   const processingContext: SessionProcessingContext = {
     responseDefaults,
@@ -170,6 +198,7 @@ export function createItemSession(
       baseOutcomes,
     );
   }
+  const templateDiagnostics = [...evaluation.diagnostics, ...builtInDiagnostics];
   const defaultOutcomes = cloneValueRecord(outcomes);
   Object.assign(responses, priorResponses);
   Object.assign(outcomes, priorOutcomes);
@@ -177,6 +206,7 @@ export function createItemSession(
 
   return {
     item: document.item,
+    beginAttempt: startAttempt,
     correctResponses() {
       return cloneValueRecord(correctResponses);
     },
@@ -198,10 +228,15 @@ export function createItemSession(
       return state === undefined ? undefined : clonePortableCustomState(state);
     },
     setStatus(nextStatus: QtiAttemptStatus) {
+      captureTime();
+      if (nextStatus === "interacting") startAttempt();
+      if (nextStatus === "completed") builtIns.state.attemptInProgress = false;
       status = nextStatus;
     },
     score() {
-      const diagnostics: QtiDiagnostic[] = [];
+      evaluation.diagnostics.length = 0;
+      builtInDiagnostics.length = 0;
+      captureTime();
       if (document.item.adaptive || status !== "initialized") {
         startAttempt();
       }
@@ -211,6 +246,12 @@ export function createItemSession(
         outcomes[COMPLETION_STATUS] = completionStatus;
       }
       applyResponseProcessing(processingContext);
+      builtIns.state.attemptInProgress = false;
+      const diagnostics = [
+        ...templateDiagnostics,
+        ...evaluation.diagnostics,
+        ...builtInDiagnostics,
+      ];
       if (outcomes[COMPLETION_STATUS] === COMPLETION_COMPLETED) status = "completed";
       validationMessages = diagnostics;
       const state = serialize(
@@ -221,10 +262,12 @@ export function createItemSession(
         templateValues,
         interactionStates,
         diagnostics,
+        builtIns.state,
       );
       return { outcomes: cloneValueRecord(outcomes), diagnostics, state };
     },
     serialize() {
+      captureTime();
       return serialize(
         document.item.identifier,
         status,
@@ -233,11 +276,18 @@ export function createItemSession(
         templateValues,
         interactionStates,
         validationMessages,
+        builtIns.state,
       );
     },
   };
 
   function startAttempt(): void {
+    captureTime();
+    if (status === "completed") return;
+    if (!builtIns.state.attemptInProgress) {
+      builtIns.state.numAttempts += 1;
+      builtIns.state.attemptInProgress = true;
+    }
     for (const [identifier, value] of Object.entries(responseDefaults)) {
       if (responses[identifier] === undefined) responses[identifier] = cloneValue(value);
     }
@@ -264,6 +314,8 @@ function applyTemplateProcessing(
 ): void {
   const { evaluation } = context;
   const rules = evaluation.document.item.templateProcessing?.rules ?? [];
+  // A retry or restored clone must derive defaults afresh from the authored declarations.
+  resetRecord(evaluation.defaultValues, {});
   let restarts = 0;
   for (let index = 0; index < rules.length; index += 1) {
     const rule = rules[index]!;
@@ -276,6 +328,7 @@ function applyTemplateProcessing(
         resetRecord(evaluation.responses, cloneValueRecord(baseResponses));
         resetRecord(context.responseDefaults, cloneValueRecord(baseResponseDefaults));
         resetRecord(evaluation.outcomes, cloneValueRecord(baseOutcomes));
+        resetRecord(evaluation.defaultValues, {});
         resetCorrectResponses(evaluation.document, evaluation.correctResponses);
         restarts += 1;
         if (restarts <= 100) index = -1;
@@ -352,6 +405,7 @@ function applyTemplateRule(
     const responseDeclaration = getResponseDeclaration(evaluation.document, rule.identifier);
     if (responseDeclaration) {
       const normalized = normalizeValueForCardinality(value, responseDeclaration.cardinality);
+      evaluation.defaultValues[rule.identifier] = cloneValue(normalized);
       if (normalized === null) {
         delete context.responseDefaults[rule.identifier];
       } else {
@@ -363,7 +417,9 @@ function applyTemplateRule(
       (declaration) => declaration.identifier === rule.identifier,
     );
     if (outcomeDeclaration) {
-      evaluation.outcomes[rule.identifier] = value;
+      const normalized = normalizeValueForCardinality(value, outcomeDeclaration.cardinality);
+      evaluation.defaultValues[rule.identifier] = cloneValue(normalized);
+      evaluation.outcomes[rule.identifier] = cloneValue(normalized);
     }
     return false;
   }

package/src/support-evidence.ts

@@ -67,8 +67,10 @@ export function browserTestsFor(interactionType: QtiInteractionType): string[] {
     gapMatch: ["tests/browser/player-gap-match.spec.ts"],
     graphicAssociate: ["tests/browser/player-graphic.spec.ts"],
     graphicGapMatch: [
+      "packages/core/src/core-session-graphic-gap-state.test.ts",
       "tests/browser/player-graphic-gap-match.spec.ts",
       "tests/browser/player-graphic.spec.ts",
+      ...browserLifecycleTests,
     ],
     graphicOrder: [
       "packages/core/src/graphic-image-contracts.test.ts",