@longsightgroup/qti3-core 0.10.5 → 0.11.0

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

@@ -51,21 +51,31 @@ export function browserTestsFor(interactionType: QtiInteractionType): string[] {
     "tests/browser/player-interaction-sweep.spec.ts",
   ];
   const extras: Partial<Record<QtiInteractionType, string[]>> = {
-    associate: browserKeyboardA11yTests,
+    associate: [
+      ...browserKeyboardA11yTests,
+      "packages/core/src/association-contracts.test.ts",
+      "tests/browser/player-dom-behavior.spec.ts",
+    ],
     choice: ["tests/browser/player-choice.spec.ts", "tests/browser/player-dom-behavior.spec.ts"],
     drawing: ["tests/browser/player-graphic.spec.ts"],
     endAttempt: ["tests/browser/player-dom-behavior.spec.ts", ...browserKeyboardA11yTests],
     extendedText: [
+      "packages/core/src/text-response.test.ts",
       "tests/browser/player-dom-behavior.spec.ts",
       "tests/browser/player-extended-text-xhtml.spec.ts",
     ],
     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",
+      "tests/browser/player-graphic.spec.ts",
     ],
-    graphicOrder: ["tests/browser/player-graphic.spec.ts"],
     hotspot: ["tests/browser/player-graphic.spec.ts"],
     hottext: ["tests/browser/player-hottext.spec.ts", "tests/browser/player-dom-behavior.spec.ts"],
     inlineChoice: ["tests/browser/player-inline-choice.spec.ts"],
@@ -81,7 +91,10 @@ export function browserTestsFor(interactionType: QtiInteractionType): string[] {
       "tests/browser/player-slider-cross-browser.spec.ts",
       ...browserKeyboardA11yTests,
     ],
-    textEntry: ["tests/browser/player-dom-behavior.spec.ts"],
+    textEntry: [
+      "packages/core/src/text-response.test.ts",
+      "tests/browser/player-dom-behavior.spec.ts",
+    ],
     upload: ["tests/browser/player-dom-behavior.spec.ts"],
   };
   return [...base, ...(extras[interactionType] ?? [])];

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",
@@ -401,20 +462,29 @@ function entry(qtiName: string, interactionType: QtiInteractionType): QtiInterac
     process: true,
     fixtures: interactionSupportFixtures(interactionType),
     tests: interactionSupportTests(interactionType),
+    notes: ["associate", "graphicAssociate", "match", "gapMatch"].includes(interactionType)
+      ? interactionType === "associate" || interactionType === "graphicAssociate"
+        ? "Supports single and multiple unordered pair responses."
+        : "Supports single and multiple directedPair responses."
+      : interactionType === "graphicGapMatch"
+        ? "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,
   };
 }
 
 function extendedTextInteractionEntry(): QtiInteractionElementSupport {
   return {
     ...entry("qti-extended-text-interaction", "extendedText"),
-    notes: "Supports plain and format=xhtml extended text.",
+    notes:
+      "Supports single, multiple, ordered and numeric record responses; string/integer/float values; min-strings/max-strings; plain, preformatted and string XHTML capture.",
   };
 }
 
 function textEntryInteractionEntry(): QtiInteractionElementSupport {
   return {
     ...entry("qti-text-entry-interaction", "textEntry"),
-    notes: "Supports placeholder-text and pattern-mask on text-entry controls.",
+    notes:
+      "Supports single string/integer/float and numeric record responses, base 2–36, string-identifier, placeholder-text and pattern-mask; text-entry format is plain only.",
   };
 }
 

package/src/text-response.ts

@@ -0,0 +1,106 @@
+import type { QtiInteraction, QtiRecordValue, QtiValue } from "./types.js";
+
+/** Capture text using the interaction's declared response type and authored radix. */
+export function captureQtiTextResponse(interaction: QtiInteraction, text: string): QtiValue {
+  if (interaction.responseCardinality === "record") return numericRecord(text, radix(interaction));
+  if (interaction.responseBaseType === "string") return text;
+  if (text.trim() === "") return null;
+  const record = numericRecord(text, radix(interaction));
+  return interaction.responseBaseType === "integer"
+    ? (record.integerValue ?? null)
+    : (record.floatValue ?? null);
+}
+
+/** Recover editable text, including the original lexical form in a numeric record. */
+export function qtiTextResponseString(value: QtiValue): string {
+  if (value !== null && typeof value === "object") {
+    return !Array.isArray(value) && typeof value.stringValue === "string" ? value.stringValue : "";
+  }
+  return value === null ? "" : String(value);
+}
+
+/** Format a captured scalar in its authored radix, preserving companion and record text. */
+export function formatQtiTextResponse(interaction: QtiInteraction, value: QtiValue): string {
+  const base = radix(interaction);
+  if (typeof value === "number" && Number.isInteger(base) && base >= 2 && base <= 36) {
+    return value.toString(base);
+  }
+  return qtiTextResponseString(value);
+}
+
+function radix(interaction: QtiInteraction): number {
+  return Number(interaction.attributes.base ?? 10);
+}
+
+function numericRecord(text: string, base: number): QtiRecordValue {
+  const empty: QtiRecordValue = {
+    stringValue: text,
+    floatValue: null,
+    integerValue: null,
+    leftDigits: null,
+    rightDigits: null,
+    ndp: null,
+    nsf: null,
+    exponent: null,
+  };
+  if (!Number.isInteger(base) || base < 2 || base > 36) return empty;
+  const normalized = text.trim();
+  const match = (
+    base === 10
+      ? /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/
+      : /^([+-]?)([0-9a-z]*)(?:\.([0-9a-z]*))?$/i
+  ).exec(normalized);
+  if (!match) return empty;
+  const left = match[2] ?? "";
+  const right = match[3] ?? "";
+  const digits = left + right;
+  if (!digits || digits.split("").some((digit) => Number.parseInt(digit, 36) >= base)) return empty;
+  const exponent = match[4] === undefined ? null : Number(match[4]);
+  if (exponent !== null && !Number.isSafeInteger(exponent)) return empty;
+  const ndp = Math.max(0, right.length - (exponent ?? 0));
+  if (!Number.isSafeInteger(ndp)) return empty;
+  const magnitude =
+    (Number.parseInt(left || "0", base) +
+      right
+        .split("")
+        .reduce(
+          (sum, digit, index) => sum + Number.parseInt(digit, base) / base ** (index + 1),
+          0,
+        )) *
+    base ** (exponent ?? 0);
+  const value = base === 10 ? Number(normalized) : match[1] === "-" ? -magnitude : magnitude;
+  if (!Number.isFinite(value)) return empty;
+  const integer =
+    match[3] === undefined && exponent === null && Number.isSafeInteger(value) ? value : null;
+  return {
+    stringValue: text,
+    floatValue: value,
+    integerValue: integer,
+    leftDigits: left.length,
+    rightDigits: right.length,
+    ndp,
+    nsf: digits.replace(/^0+/, "").length || 1,
+    exponent,
+  };
+}
+
+export function isQtiTextResponseRecord(value: QtiValue): boolean {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const integerFields = new Set([
+    "integerValue",
+    "leftDigits",
+    "rightDigits",
+    "ndp",
+    "nsf",
+    "exponent",
+  ]);
+  return Object.entries(value).every(([field, entry]) => {
+    if (field === "stringValue") return typeof entry === "string" || entry === null;
+    if (field === "floatValue")
+      return entry === null || (typeof entry === "number" && Number.isFinite(entry));
+    return (
+      integerFields.has(field) &&
+      (entry === null || (typeof entry === "number" && Number.isSafeInteger(entry)))
+    );
+  });
+}

package/src/trusted-item-session.ts

@@ -1,5 +1,6 @@
+import type { QtiSessionEnvironment } from "./session-builtins.js";
 import { parseQtiXml } from "./parser.js";
-import { itemExpectsAutomatedScore } from "./item-scoring-expectation.js";
+import { itemExpectsAutomatedScore, itemHasExternalScore } from "./item-scoring-expectation.js";
 import { parseQtiResponseVariables } from "./response-validation.js";
 import { createItemSession, isQtiAttemptStateV1, type QtiItemSession } from "./session.js";
 import type {
@@ -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,7 +195,11 @@ 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);
 
   let outcomes = sessionResult.session.serialize().outcomes;
   let state = sessionResult.session.serialize();
@@ -212,7 +222,7 @@ export function runTrustedItemSession(
       scoredResult.scored.state,
       parsedResult.parsed.responseIdentifiers,
     );
-    score = readNumericScore(outcomes.SCORE);
+    score = externalScore ? null : readNumericScore(outcomes.SCORE);
 
     if (scoredResult.scored.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
       return emptyTrustedItemSessionFailure(scoredDiagnostics, {
@@ -241,7 +251,7 @@ export function runTrustedItemSession(
   } else {
     state = stripUndeclaredResponses(state, parsedResult.parsed.responseIdentifiers);
     outcomes = state.outcomes;
-    score = readNumericScore(outcomes.SCORE);
+    score = externalScore ? null : readNumericScore(outcomes.SCORE);
   }
 
   return {
@@ -276,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,
       }),
     };