@longsightgroup/qti3-core 0.9.3 → 0.9.4

package/src/template-presentation-materializer.ts

@@ -0,0 +1,219 @@
+import {
+  applySourceRangeEdits,
+  parseDeliveryXml,
+  sourceRangeFor,
+  type SourceRangeEdit,
+} from "./delivery-redaction.js";
+import type { QtiDiagnostic, QtiValue } from "./types.js";
+import { qtiValueToString } from "./value-format.js";
+import { descendants, escapeXmlText, type XmlNode } from "./xml.js";
+
+interface TemplateBlockBinding {
+  readonly templateIdentifier: string;
+  readonly identifier: string;
+  readonly value: QtiValue;
+}
+
+export interface QtiTemplatePresentationVariables {
+  readonly outcomes: Record<string, QtiValue>;
+  readonly templateValues: Record<string, QtiValue>;
+  readonly responses?: Record<string, QtiValue> | undefined;
+}
+
+export function materializeTemplatePresentation(
+  xml: string,
+  variables: QtiTemplatePresentationVariables,
+): { ok: true; xml: string } | { ok: false; diagnostics: QtiDiagnostic[] } {
+  const parsed = parseDeliveryXml(xml);
+  if (!parsed.root) return { ok: true, xml };
+
+  const diagnostics: QtiDiagnostic[] = [];
+  const edits: SourceRangeEdit[] = [];
+  const nodes = [parsed.root, ...descendants(parsed.root, () => true)];
+
+  for (const node of nodes) {
+    if (isInsideTemplateContentNode(node)) continue;
+
+    if (node.localName === "qti-printed-variable") {
+      const edit = printedVariableEdit(node, variables, diagnostics);
+      if (edit) edits.push(edit);
+      continue;
+    }
+
+    if (node.localName === "qti-template-block" || node.localName === "qti-template-inline") {
+      const edit = templateContentEdit(xml, node, variables, diagnostics);
+      if (edit) edits.push(edit);
+    }
+  }
+
+  if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    return { ok: false, diagnostics };
+  }
+
+  return { ok: true, xml: applySourceRangeEdits(xml, edits) };
+}
+
+function printedVariableEdit(
+  node: XmlNode,
+  variables: QtiTemplatePresentationVariables,
+  diagnostics: QtiDiagnostic[],
+): SourceRangeEdit | undefined {
+  const text = resolvePrintedVariableText(node, variables, diagnostics);
+  if (text === undefined) return undefined;
+
+  const range = sourceRangeFor(node)[0];
+  if (!range) {
+    diagnostics.push(unsupportedTemplateMaterializationDiagnostic(node));
+    return undefined;
+  }
+
+  return { ...range, text };
+}
+
+function templateContentEdit(
+  xml: string,
+  node: XmlNode,
+  variables: QtiTemplatePresentationVariables,
+  diagnostics: QtiDiagnostic[],
+): SourceRangeEdit | undefined {
+  const binding = resolveTemplateBlockBinding(node, variables.templateValues, diagnostics);
+  if (!binding) return undefined;
+
+  const range = sourceRangeFor(node)[0];
+  if (!range) {
+    diagnostics.push(unsupportedTemplateMaterializationDiagnostic(node));
+    return undefined;
+  }
+
+  return {
+    ...range,
+    text: isTemplateContentVisible(node, binding.value)
+      ? materializedContentXml(xml, node, variables, diagnostics)
+      : "",
+  };
+}
+
+function resolvePrintedVariableText(
+  node: XmlNode,
+  variables: QtiTemplatePresentationVariables,
+  diagnostics: QtiDiagnostic[],
+): string | undefined {
+  const identifier = node.attributes.identifier;
+  if (!identifier) {
+    diagnostics.push(unsupportedTemplateMaterializationDiagnostic(node));
+    return undefined;
+  }
+
+  const value = resolvePresentationVariable(identifier, variables);
+  if (value === undefined) {
+    diagnostics.push(unsupportedTemplateMaterializationDiagnostic(node));
+    return undefined;
+  }
+
+  return escapeXmlText(qtiValueToString(value));
+}
+
+function resolvePresentationVariable(
+  identifier: string,
+  variables: QtiTemplatePresentationVariables,
+): QtiValue | undefined {
+  return (
+    variables.outcomes[identifier] ??
+    variables.templateValues[identifier] ??
+    variables.responses?.[identifier]
+  );
+}
+
+function resolveTemplateBlockBinding(
+  node: XmlNode,
+  templateValues: Record<string, QtiValue>,
+  diagnostics: QtiDiagnostic[],
+): TemplateBlockBinding | undefined {
+  const templateIdentifier = node.attributes["template-identifier"];
+  const identifier = node.attributes.identifier;
+  if (!templateIdentifier || !identifier || templateValues[templateIdentifier] === undefined) {
+    diagnostics.push(unsupportedTemplateMaterializationDiagnostic(node));
+    return undefined;
+  }
+
+  return { templateIdentifier, identifier, value: templateValues[templateIdentifier] };
+}
+
+function materializedContentXml(
+  xml: string,
+  node: XmlNode,
+  variables: QtiTemplatePresentationVariables,
+  diagnostics: QtiDiagnostic[],
+): string {
+  return node.content
+    .map((child) => {
+      if (typeof child === "string") return escapeXmlText(child);
+      if (child.localName === "qti-printed-variable") {
+        return resolvePrintedVariableText(child, variables, diagnostics) ?? "";
+      }
+      if (child.localName === "qti-template-block" || child.localName === "qti-template-inline") {
+        return materializedNestedTemplateContentXml(xml, child, variables, diagnostics);
+      }
+      return materializedElementXml(xml, child, variables, diagnostics);
+    })
+    .join("");
+}
+
+function materializedNestedTemplateContentXml(
+  xml: string,
+  node: XmlNode,
+  variables: QtiTemplatePresentationVariables,
+  diagnostics: QtiDiagnostic[],
+): string {
+  const binding = resolveTemplateBlockBinding(node, variables.templateValues, diagnostics);
+  if (!binding) return "";
+
+  return isTemplateContentVisible(node, binding.value)
+    ? materializedContentXml(xml, node, variables, diagnostics)
+    : "";
+}
+
+function isTemplateContentVisible(node: XmlNode, value: QtiValue): boolean {
+  const identifier = node.attributes.identifier;
+  const hasIdentifier = Array.isArray(value)
+    ? value.map(String).includes(identifier ?? "")
+    : qtiValueToString(value) === identifier;
+  return node.attributes["show-hide"] === "hide" ? !hasIdentifier : hasIdentifier;
+}
+
+function materializedElementXml(
+  xml: string,
+  node: XmlNode,
+  variables: QtiTemplatePresentationVariables,
+  diagnostics: QtiDiagnostic[],
+): string {
+  if (node.sourceRange.endOffset === undefined || node.endSource === undefined) {
+    diagnostics.push(unsupportedTemplateMaterializationDiagnostic(node));
+    return "";
+  }
+
+  const startTag = xml.slice(node.sourceRange.startOffset, node.sourceRange.startTagEndOffset + 1);
+  const endTag = xml.slice(node.endSource.offset, node.sourceRange.endOffset);
+  return `${startTag}${materializedContentXml(xml, node, variables, diagnostics)}${endTag}`;
+}
+
+function isInsideTemplateContentNode(node: XmlNode): boolean {
+  let parent = node.parent;
+  while (parent) {
+    if (parent.localName === "qti-template-block" || parent.localName === "qti-template-inline") {
+      return true;
+    }
+    parent = parent.parent;
+  }
+  return false;
+}
+
+function unsupportedTemplateMaterializationDiagnostic(node: XmlNode): QtiDiagnostic {
+  return {
+    code: "adaptiveTurn.materialization.unsupported",
+    severity: "error",
+    message: `${node.name} could not be materialized from authoritative template state.`,
+    path: node.source.path,
+    source: node.source,
+  };
+}

package/src/trusted-item-session.ts

@@ -1,7 +1,8 @@
 import { parseQtiXml } from "./parser.js";
+import { itemExpectsAutomatedScore } from "./item-scoring-expectation.js";
+import { validateQtiResponseVariables } from "./response-validation.js";
 import { createItemSession, isQtiAttemptStateV1, type QtiItemSession } from "./session.js";
 import type {
-  QtiAssessmentItem,
   QtiAttemptStateV1,
   QtiAttemptStatus,
   QtiDiagnostic,
@@ -10,20 +11,20 @@ import type {
   QtiValue,
 } from "./types.js";
 import { isQtiPortableCustomStateValue, readQtiJsonValue } from "./value-format.js";
+import {
+  listNamedResponseInputs,
+  type QtiNamedResponseInput,
+  type QtiNamedResponsesInput,
+} from "./response-input.js";
 
-export type QtiTrustedInputDiagnosticPrefix = "serverScoring" | "adaptiveTurn";
+export type QtiTrustedResponseInput = QtiNamedResponseInput;
 
-export interface QtiTrustedResponseInput {
-  identifier: string;
-  value: unknown;
-}
+export type QtiTrustedResponsesInput = QtiNamedResponsesInput;
+
+export type QtiTrustedInputDiagnosticPrefix = "serverScoring" | "adaptiveTurn" | "itemSubmission";
 
-export type QtiTrustedResponsesInput =
-  | Record<string, unknown>
-  | readonly QtiTrustedResponseInput[]
-  | undefined;
+export type QtiTrustedSubmissionValidation = "trusted" | "strict";
 
-/** Trusted candidate responses and portable custom interaction state for one application. */
 export interface QtiTrustedResponseApplication {
   trustedResponses?: QtiTrustedResponsesInput;
   trustedInteractionStates?: Record<string, QtiPortableCustomStateValue> | undefined;
@@ -33,7 +34,7 @@ export interface QtiTrustedItemParseOptions {
   allowedUndeclaredResponseIdentifiers?: readonly string[] | undefined;
 }
 
-interface QtiParsedTrustedItem {
+export interface QtiTrustedItemDocument {
   document: QtiDocument;
   diagnostics: QtiDiagnostic[];
   responseIdentifiers: Set<string>;
@@ -43,6 +44,7 @@ export type QtiTrustedItemScoringPolicy = "always" | "onSubmission";
 
 export interface RunTrustedItemSessionInput extends QtiTrustedItemParseOptions {
   itemXml: string;
+  parsedItem?: QtiTrustedItemDocument | undefined;
   diagnosticPrefix: QtiTrustedInputDiagnosticPrefix;
   submission: QtiTrustedResponseApplication;
   priorState?: QtiAttemptStateV1 | null | undefined;
@@ -50,6 +52,12 @@ export interface RunTrustedItemSessionInput extends QtiTrustedItemParseOptions {
   attemptStatus?: QtiAttemptStatus | undefined;
   scoring: QtiTrustedItemScoringPolicy;
   requireNumericScore: boolean;
+  /**
+   * `strict` rejects undeclared and malformed responses before trusted application.
+   * `trusted` keeps the legacy warning path for undeclared identifiers.
+   */
+  submissionValidation?: QtiTrustedSubmissionValidation | undefined;
+  allowIncompleteResponses?: boolean | undefined;
 }
 
 export interface RunTrustedItemSessionSuccess {
@@ -86,19 +94,58 @@ export function readPriorAttemptState(
       {
         code: `${diagnosticPrefix}.state.value`,
         severity: "error",
-        message: "Prior adaptive turn state is not a valid qti3.attempt-state.v1 value.",
+        message: "Prior attempt state is not a valid qti3.attempt-state.v1 value.",
       },
     ],
   };
 }
 
+export function parseTrustedItemDocument(
+  itemXml: string,
+  allowedUndeclaredResponseIdentifiers: readonly string[] = [],
+): { ok: true; parsed: QtiTrustedItemDocument } | { ok: false; diagnostics: QtiDiagnostic[] } {
+  let parsed: ReturnType<typeof parseQtiXml>;
+  try {
+    parsed = parseQtiXml(itemXml);
+  } catch (error) {
+    return {
+      ok: false,
+      diagnostics: [
+        {
+          code: "xml.parse",
+          severity: "error",
+          message: error instanceof Error ? error.message : String(error),
+        },
+      ],
+    };
+  }
+
+  const allowedUndeclared = new Set(allowedUndeclaredResponseIdentifiers);
+  const diagnostics = parsed.diagnostics.filter(
+    (diagnostic) => !isAllowedUndeclaredVariableReference(diagnostic, allowedUndeclared),
+  );
+  if (!parsed.document || diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    return { ok: false, diagnostics };
+  }
+
+  return {
+    ok: true,
+    parsed: {
+      document: parsed.document,
+      diagnostics,
+      responseIdentifiers: new Set(
+        parsed.document.item.responseDeclarations.map((declaration) => declaration.identifier),
+      ),
+    },
+  };
+}
+
 export function runTrustedItemSession(
   input: RunTrustedItemSessionInput,
 ): RunTrustedItemSessionResult {
-  const parsedResult = parseTrustedItemXml(
-    input.itemXml,
-    input.allowedUndeclaredResponseIdentifiers,
-  );
+  const parsedResult = input.parsedItem
+    ? { ok: true as const, parsed: input.parsedItem }
+    : parseTrustedItemDocument(input.itemXml, input.allowedUndeclaredResponseIdentifiers);
   if (!parsedResult.ok) {
     return emptyTrustedItemSessionFailure(parsedResult.diagnostics);
   }
@@ -116,6 +163,18 @@ export function runTrustedItemSession(
 
   if (input.attemptStatus) sessionResult.session.setStatus(input.attemptStatus);
 
+  if (input.submissionValidation === "strict") {
+    const validation = validateQtiResponseVariables({
+      item: parsedResult.parsed.document.item,
+      responses: input.submission.trustedResponses ?? {},
+      allowIncompleteResponses: input.allowIncompleteResponses,
+      allowedUndeclaredResponseIdentifiers: input.allowedUndeclaredResponseIdentifiers,
+    });
+    if (!validation.ok) {
+      return emptyTrustedItemSessionFailure(validation.diagnostics);
+    }
+  }
+
   const applicationResult = applyTrustedResponseApplication(
     sessionResult.session,
     parsedResult.parsed,
@@ -164,7 +223,7 @@ export function runTrustedItemSession(
 
     if (
       input.requireNumericScore &&
-      shouldRequireNumericScore(parsedResult.parsed.document.item) &&
+      itemExpectsAutomatedScore(parsedResult.parsed.document.item) &&
       score === null
     ) {
       return emptyTrustedItemSessionFailure(
@@ -209,48 +268,8 @@ function emptyTrustedItemSessionFailure(
   };
 }
 
-function parseTrustedItemXml(
-  itemXml: string,
-  allowedUndeclaredResponseIdentifiers: readonly string[] = [],
-): { ok: true; parsed: QtiParsedTrustedItem } | { ok: false; diagnostics: QtiDiagnostic[] } {
-  let parsed: ReturnType<typeof parseQtiXml>;
-  try {
-    parsed = parseQtiXml(itemXml);
-  } catch (error) {
-    return {
-      ok: false,
-      diagnostics: [
-        {
-          code: "xml.parse",
-          severity: "error",
-          message: error instanceof Error ? error.message : String(error),
-        },
-      ],
-    };
-  }
-
-  const allowedUndeclared = new Set(allowedUndeclaredResponseIdentifiers);
-  const diagnostics = parsed.diagnostics.filter(
-    (diagnostic) => !isAllowedUndeclaredVariableReference(diagnostic, allowedUndeclared),
-  );
-  if (!parsed.document || diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
-    return { ok: false, diagnostics };
-  }
-
-  return {
-    ok: true,
-    parsed: {
-      document: parsed.document,
-      diagnostics,
-      responseIdentifiers: new Set(
-        parsed.document.item.responseDeclarations.map((declaration) => declaration.identifier),
-      ),
-    },
-  };
-}
-
 function createTrustedItemSession(
-  parsed: QtiParsedTrustedItem,
+  parsed: QtiTrustedItemDocument,
   priorState: QtiAttemptStateV1 | null | undefined,
   diagnosticPrefix: QtiTrustedInputDiagnosticPrefix,
   allowedUndeclaredResponseIdentifiers: readonly string[] | undefined,
@@ -280,7 +299,7 @@ function createTrustedItemSession(
 
 function applyTrustedResponseApplication(
   session: QtiItemSession,
-  parsed: QtiParsedTrustedItem,
+  parsed: QtiTrustedItemDocument,
   submission: QtiTrustedResponseApplication,
   allowedUndeclaredResponseIdentifiers: readonly string[] | undefined,
   diagnosticPrefix: QtiTrustedInputDiagnosticPrefix,
@@ -289,7 +308,7 @@ function applyTrustedResponseApplication(
   const allowedUndeclared = new Set(allowedUndeclaredResponseIdentifiers ?? []);
   let appliedSubmission = false;
 
-  for (const response of normalizeResponseInputs(submission.trustedResponses)) {
+  for (const response of listNamedResponseInputs(submission.trustedResponses)) {
     const identifier = response.identifier.trim();
     if (!identifier) {
       diagnostics.push({
@@ -371,13 +390,6 @@ function scoreTrustedItemSession(
   }
 }
 
-function shouldRequireNumericScore(item: QtiAssessmentItem): boolean {
-  return (
-    Boolean(item.responseProcessing) ||
-    item.outcomeDeclarations.some((declaration) => declaration.identifier === "SCORE")
-  );
-}
-
 function readNumericScore(value: QtiValue | undefined): number | null {
   if (typeof value === "number" && Number.isFinite(value)) return value;
   if (typeof value === "string") {
@@ -411,12 +423,6 @@ function stripUndeclaredResponses(
   };
 }
 
-function normalizeResponseInputs(responses: QtiTrustedResponsesInput): QtiTrustedResponseInput[] {
-  if (!responses) return [];
-  if (Array.isArray(responses)) return [...responses];
-  return Object.entries(responses).map(([identifier, value]) => ({ identifier, value }));
-}
-
 function isAllowedUndeclaredVariableReference(
   diagnostic: QtiDiagnostic,
   allowedUndeclaredResponseIdentifiers: Set<string>,

package/src/trusted-session-materialization.ts

@@ -0,0 +1,67 @@
+import {
+  classifyQtiItemScoringDisposition,
+  type QtiItemSubmissionScoringDisposition,
+} from "./scoring-disposition-policy.js";
+import type { QtiAssessmentItem, QtiAttemptStateV1, QtiDiagnostic, QtiValue } from "./types.js";
+import { snapshotQtiVariableDeclarations, type QtiVariableSnapshot } from "./variable-snapshot.js";
+
+export interface QtiTrustedSessionMaterialization {
+  diagnostics: QtiDiagnostic[];
+  state: QtiAttemptStateV1;
+  responses: Record<string, QtiValue>;
+  outcomes: Record<string, QtiValue>;
+  score: number | null;
+  candidateSafeXml?: string | undefined;
+}
+
+export interface QtiItemSubmissionMaterializationSuccess {
+  ok: true;
+  diagnostics: QtiDiagnostic[];
+  state: QtiAttemptStateV1;
+  responseVariables: QtiVariableSnapshot[];
+  outcomeVariables: QtiVariableSnapshot[];
+  score: number | null;
+  scoringDisposition: Exclude<QtiItemSubmissionScoringDisposition, "invalid">;
+  candidateSafeXml?: string | undefined;
+}
+
+export interface QtiItemSubmissionMaterializationFailure {
+  ok: false;
+  diagnostics: QtiDiagnostic[];
+  state?: QtiAttemptStateV1 | undefined;
+  responseVariables: QtiVariableSnapshot[];
+  outcomeVariables: QtiVariableSnapshot[];
+  score: null;
+  scoringDisposition: "invalid";
+}
+
+export function buildItemSubmissionMaterializationSuccess(
+  item: QtiAssessmentItem,
+  result: QtiTrustedSessionMaterialization,
+): QtiItemSubmissionMaterializationSuccess {
+  return {
+    ok: true,
+    diagnostics: result.diagnostics,
+    state: result.state,
+    responseVariables: snapshotQtiVariableDeclarations(item.responseDeclarations, result.responses),
+    outcomeVariables: snapshotQtiVariableDeclarations(item.outcomeDeclarations, result.outcomes),
+    score: result.score,
+    scoringDisposition: classifyQtiItemScoringDisposition(item, result.score),
+    candidateSafeXml: result.candidateSafeXml,
+  };
+}
+
+export function buildItemSubmissionMaterializationFailure(
+  diagnostics: QtiDiagnostic[],
+  state?: QtiAttemptStateV1,
+): QtiItemSubmissionMaterializationFailure {
+  return {
+    ok: false,
+    diagnostics,
+    state,
+    responseVariables: [],
+    outcomeVariables: [],
+    score: null,
+    scoringDisposition: "invalid",
+  };
+}

package/src/validation-primitives.ts

@@ -48,6 +48,11 @@ export function isNonNegativeInteger(value: string): boolean {
   return /^\d+$/.test(value);
 }
 
+export function parseNonNegativeInteger(value: string | undefined): number | undefined {
+  if (value === undefined || !isNonNegativeInteger(value)) return undefined;
+  return Number(value);
+}
+
 export function isBooleanAttribute(value: string): boolean {
   return value === "true" || value === "false" || value === "1" || value === "0";
 }

package/src/variable-snapshot.ts

@@ -0,0 +1,20 @@
+import type { QtiBaseType, QtiCardinality, QtiValue, QtiVariableDeclaration } from "./types.js";
+
+export interface QtiVariableSnapshot {
+  identifier: string;
+  value: QtiValue;
+  cardinality: QtiCardinality;
+  baseType?: QtiBaseType | undefined;
+}
+
+export function snapshotQtiVariableDeclarations(
+  declarations: readonly QtiVariableDeclaration[],
+  values: Record<string, QtiValue>,
+): QtiVariableSnapshot[] {
+  return declarations.map((declaration) => ({
+    identifier: declaration.identifier,
+    value: values[declaration.identifier] ?? null,
+    cardinality: declaration.cardinality,
+    baseType: declaration.baseType,
+  }));
+}