@longsightgroup/qti3-core 0.10.6 → 0.12.0

package/src/support.ts

@@ -8,6 +8,7 @@ import type {
   QtiProcessingElementSupport,
   QtiSourceLocation,
 } from "./types.js";
+import { testExecutionSupport } from "./test-support.js";
 import {
   browserFeedbackTests,
   browserHarnessTests,
@@ -92,7 +93,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 +138,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 +204,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 +238,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 +259,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 +333,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",
@@ -336,6 +398,7 @@ export const itemMetadataSupport: QtiItemMetadataElementSupport[] = [
 ];
 
 export const elementSupport: QtiElementSupport[] = [
+  ...testExecutionSupport,
   ...interactionSupport,
   ...deprecatedInteractionSupport,
   ...processingSupport,
@@ -406,7 +469,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/test-expression-parser.ts

@@ -0,0 +1,89 @@
+import { assertNever } from "./assert-never.js";
+import { coerceValue } from "./parser-values.js";
+import { isTestBaseType, testExpressionSyntax, type QtiTestExpression } from "./test-expression.js";
+import { checkTestXml, rejectTestXml } from "./test-xml.js";
+import type { QtiDiagnostic } from "./types.js";
+import { textContent, type XmlNode } from "./xml.js";
+
+/** Read the single expression owned by a branch or outcome assignment. */
+export function parseTestExpressionChild(
+  node: XmlNode,
+  diagnostics: QtiDiagnostic[],
+): QtiTestExpression | undefined {
+  const first = node.children[0];
+  if (node.children.length !== 1 || !first) {
+    rejectTestXml(node, diagnostics);
+    return undefined;
+  }
+  return parseTestExpression(first, diagnostics);
+}
+
+function parseTestExpression(
+  node: XmlNode,
+  diagnostics: QtiDiagnostic[],
+): QtiTestExpression | undefined {
+  const syntax = testExpressionSyntax.find((entry) => entry.name === node.localName);
+  if (!syntax) {
+    rejectTestXml(node, diagnostics);
+    return undefined;
+  }
+  checkTestXml(
+    node,
+    testExpressionSyntax.map((entry) => entry.name),
+    syntax.attributes,
+    diagnostics,
+    syntax.type === "baseValue",
+  );
+  const arityValid =
+    syntax.arity === "oneOrMore" ? node.children.length > 0 : node.children.length === syntax.arity;
+  if (!arityValid) {
+    rejectTestXml(node, diagnostics);
+    return undefined;
+  }
+  const expressions: QtiTestExpression[] = [];
+  for (const child of node.children) {
+    const parsed = parseTestExpression(child, diagnostics);
+    if (!parsed) return undefined;
+    expressions.push(parsed);
+  }
+  const source = node.source;
+  switch (syntax.type) {
+    case "baseValue": {
+      const baseType = node.attributes["base-type"];
+      if (!isTestBaseType(baseType)) {
+        rejectTestXml(node, diagnostics);
+        return undefined;
+      }
+      return {
+        type: "baseValue",
+        baseType,
+        value: coerceValue(textContent(node), baseType),
+        source,
+      };
+    }
+    case "variable":
+      return { type: "variable", identifier: node.attributes.identifier ?? "", source };
+    case "testVariables":
+      return {
+        type: "testVariables",
+        variableIdentifier: node.attributes["variable-identifier"] ?? "",
+        includeCategory: node.attributes["include-category"],
+        source,
+      };
+    case "sum":
+    case "and":
+    case "or":
+      return { type: syntax.type, expressions, source };
+    case "numericCompare": {
+      const [left, right] = expressions;
+      if (!left || !right) return undefined;
+      return { type: "numericCompare", operator: syntax.operator, left, right, source };
+    }
+    case "not": {
+      const expression = expressions[0];
+      return expression ? { type: "not", expression, source } : undefined;
+    }
+    default:
+      return assertNever(syntax);
+  }
+}

package/src/test-expression-serializer.ts

@@ -0,0 +1,71 @@
+import { assertNever } from "./assert-never.js";
+import { renderElement, type XmlAttribute } from "./serializer-processing-xml.js";
+import { testExpressionSyntax, type QtiTestExpression } from "./test-expression.js";
+import { testFailure, type QtiTestResult } from "./test-model.js";
+import { escapeXmlText } from "./xml.js";
+
+/** Serialize the closed test expression language without involving item processing. */
+export function serializeTestExpression(expression: QtiTestExpression): QtiTestResult<string> {
+  const result = serializeExpression(expression, 0);
+  return result.ok ? { ok: true, value: result.value.join("\n") } : result;
+}
+
+function serializeExpression(
+  expression: QtiTestExpression,
+  indent: number,
+): QtiTestResult<readonly string[]> {
+  const syntax = testExpressionSyntax.find(
+    (entry) =>
+      entry.type === expression.type &&
+      (expression.type !== "numericCompare" ||
+        (entry.type === "numericCompare" && entry.operator === expression.operator)),
+  );
+  if (!syntax)
+    return testFailure(
+      "expression.unsupported",
+      "Cannot serialize an unsupported test expression.",
+    );
+  const attributes: XmlAttribute[] = [];
+  let children: readonly QtiTestExpression[] = [];
+  switch (expression.type) {
+    case "baseValue":
+      return {
+        ok: true,
+        value: renderElement(
+          syntax.name,
+          [["base-type", expression.baseType]],
+          escapeXmlText(String(expression.value)),
+          indent,
+        ),
+      };
+    case "variable":
+      attributes.push(["identifier", expression.identifier]);
+      break;
+    case "testVariables":
+      attributes.push(
+        ["variable-identifier", expression.variableIdentifier],
+        ["include-category", expression.includeCategory],
+      );
+      break;
+    case "sum":
+    case "and":
+    case "or":
+      children = expression.expressions;
+      break;
+    case "numericCompare":
+      children = [expression.left, expression.right];
+      break;
+    case "not":
+      children = [expression.expression];
+      break;
+    default:
+      return assertNever(expression);
+  }
+  const content: string[] = [];
+  for (const child of children) {
+    const result = serializeExpression(child, indent + 1);
+    if (!result.ok) return result;
+    content.push(...result.value);
+  }
+  return { ok: true, value: renderElement(syntax.name, attributes, content, indent) };
+}

package/src/test-expression-validation.ts

@@ -0,0 +1,139 @@
+import { assertNever } from "./assert-never.js";
+import {
+  isTestBaseType,
+  testExpressionSyntax,
+  type QtiTestBaseType,
+  type QtiTestExpression,
+} from "./test-expression.js";
+import type { QtiDiagnostic, QtiOutcomeDeclaration, QtiValue } from "./types.js";
+
+/** The declared QTI type of an expression, including its cardinality. */
+export interface TestExpressionType {
+  readonly baseType: QtiTestBaseType;
+  readonly cardinality: "single" | "multiple";
+}
+
+/** Check scalar literals and defaults against the supported base types. */
+export function isTestScalarValue(baseType: string | undefined, value: QtiValue): boolean {
+  if (baseType === undefined) return false;
+  switch (baseType) {
+    case "integer":
+      return typeof value === "number" && Number.isSafeInteger(value);
+    case "float":
+      return typeof value === "number" && Number.isFinite(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "string":
+    case "identifier":
+      return typeof value === "string";
+    default:
+      return false;
+  }
+}
+
+/** Infer a test expression's QTI type and diagnose invalid operands and scope. */
+export function checkTestExpression(
+  expression: QtiTestExpression,
+  declarations: ReadonlyMap<string, QtiOutcomeDeclaration>,
+  categories: ReadonlySet<string>,
+  scope: "outcome" | "branch",
+  diagnostics: QtiDiagnostic[],
+): TestExpressionType | undefined {
+  const reject = (code: string, message: string) => {
+    diagnostics.push({
+      code: `test.${code}`,
+      severity: "error",
+      message,
+      source: expression.source,
+    });
+  };
+  const check = (child: QtiTestExpression) =>
+    checkTestExpression(child, declarations, categories, scope, diagnostics);
+  if (!testExpressionSyntax.some((syntax) => syntax.type === expression.type)) {
+    reject("expression.unsupported", "Expression is outside the supported test execution profile.");
+    return undefined;
+  }
+  switch (expression.type) {
+    case "baseValue":
+      if (!isTestScalarValue(expression.baseType, expression.value)) {
+        reject("expression.value", "Expression values must match a supported scalar base type.");
+        return undefined;
+      }
+      return { baseType: expression.baseType, cardinality: "single" };
+    case "variable": {
+      const declaration = declarations.get(expression.identifier);
+      if (!declaration || !isTestBaseType(declaration.baseType)) {
+        reject(
+          "expression.variable",
+          "Test expression references an undeclared or unsupported outcome.",
+        );
+        return undefined;
+      }
+      return { baseType: declaration.baseType, cardinality: "single" };
+    }
+    case "testVariables":
+      if (scope === "branch")
+        reject(
+          "branch.scope",
+          "Test-variable aggregation belongs in outcome processing, not a branch rule.",
+        );
+      if (
+        expression.variableIdentifier !== "SCORE" ||
+        (expression.includeCategory !== undefined && !categories.has(expression.includeCategory))
+      )
+        reject(
+          "expression.testVariables",
+          "This test profile aggregates item SCORE values from declared categories.",
+        );
+      return { baseType: "float", cardinality: "multiple" };
+    case "sum": {
+      const operands = expression.expressions.map(check);
+      if (!operands.length || operands.some((type) => !isNumeric(type)))
+        reject("expression.sum", "Test sums require numeric operands.");
+      return {
+        baseType: operands.every((type) => type?.baseType === "integer") ? "integer" : "float",
+        cardinality: "single",
+      };
+    }
+    case "numericCompare": {
+      const left = check(expression.left);
+      const right = check(expression.right);
+      if (
+        !testExpressionSyntax.some(
+          (syntax) => syntax.type === "numericCompare" && syntax.operator === expression.operator,
+        )
+      )
+        reject("expression.compare", "Unsupported test comparison operator.");
+      if (
+        !isNumeric(left) ||
+        left?.cardinality !== "single" ||
+        !isNumeric(right) ||
+        right?.cardinality !== "single"
+      )
+        reject("expression.compare", "Test comparisons require two scalar numbers.");
+      return { baseType: "boolean", cardinality: "single" };
+    }
+    case "and":
+    case "or": {
+      const operands = expression.expressions.map(check);
+      if (!operands.length || operands.some((type) => !isBoolean(type)))
+        reject("expression.boolean", "Test logic requires boolean operands.");
+      return { baseType: "boolean", cardinality: "single" };
+    }
+    case "not":
+      if (!isBoolean(check(expression.expression)))
+        reject("expression.boolean", "Test logic requires a boolean operand.");
+      return { baseType: "boolean", cardinality: "single" };
+    default:
+      return assertNever(expression);
+  }
+}
+
+function isNumeric(type: TestExpressionType | undefined): boolean {
+  return type?.baseType === "integer" || type?.baseType === "float";
+}
+
+/** Whether a branch expression has the required single boolean type. */
+export function isBoolean(type: TestExpressionType | undefined): boolean {
+  return type?.baseType === "boolean" && type.cardinality === "single";
+}

package/src/test-expression.ts

@@ -0,0 +1,66 @@
+import type { QtiSourceLocation } from "./types.js";
+
+/** Scalar types supported by deterministic test outcome processing. */
+export type QtiTestBaseType = "integer" | "float" | "boolean" | "string" | "identifier";
+
+/** Test expressions form a closed language, independent of item processing. */
+export type QtiTestExpression = (
+  | {
+      readonly type: "baseValue";
+      readonly baseType: QtiTestBaseType;
+      readonly value: number | boolean | string;
+    }
+  | { readonly type: "variable"; readonly identifier: string }
+  | {
+      readonly type: "testVariables";
+      readonly variableIdentifier: string;
+      readonly includeCategory?: string | undefined;
+    }
+  | { readonly type: "sum"; readonly expressions: readonly QtiTestExpression[] }
+  | { readonly type: "and"; readonly expressions: readonly QtiTestExpression[] }
+  | { readonly type: "or"; readonly expressions: readonly QtiTestExpression[] }
+  | {
+      readonly type: "numericCompare";
+      readonly operator: "gt" | "gte" | "lt" | "lte";
+      readonly left: QtiTestExpression;
+      readonly right: QtiTestExpression;
+    }
+  | { readonly type: "not"; readonly expression: QtiTestExpression }
+) & { readonly source?: QtiSourceLocation | undefined };
+
+/** XML names, AST variants, arities and attributes owned by the test language. */
+export const testExpressionSyntax = [
+  { name: "qti-base-value", type: "baseValue", arity: 0, attributes: ["base-type"] },
+  { name: "qti-variable", type: "variable", arity: 0, attributes: ["identifier"] },
+  {
+    name: "qti-test-variables",
+    type: "testVariables",
+    arity: 0,
+    attributes: ["variable-identifier", "include-category"],
+  },
+  { name: "qti-sum", type: "sum", arity: "oneOrMore", attributes: [] },
+  { name: "qti-gt", type: "numericCompare", operator: "gt", arity: 2, attributes: [] },
+  { name: "qti-gte", type: "numericCompare", operator: "gte", arity: 2, attributes: [] },
+  { name: "qti-lt", type: "numericCompare", operator: "lt", arity: 2, attributes: [] },
+  { name: "qti-lte", type: "numericCompare", operator: "lte", arity: 2, attributes: [] },
+  { name: "qti-and", type: "and", arity: "oneOrMore", attributes: [] },
+  { name: "qti-or", type: "or", arity: "oneOrMore", attributes: [] },
+  { name: "qti-not", type: "not", arity: 1, attributes: [] },
+] as const satisfies readonly {
+  name: string;
+  type: QtiTestExpression["type"];
+  operator?: "gt" | "gte" | "lt" | "lte";
+  arity: number | "oneOrMore";
+  attributes: readonly string[];
+}[];
+
+/** Refine a supported test scalar type without accepting item-only base types. */
+export function isTestBaseType(value: string | undefined): value is QtiTestBaseType {
+  return (
+    value === "integer" ||
+    value === "float" ||
+    value === "boolean" ||
+    value === "string" ||
+    value === "identifier"
+  );
+}

package/src/test-model.ts

@@ -0,0 +1,68 @@
+import type { QtiDiagnostic, QtiOutcomeDeclaration } from "./types.js";
+import type { QtiTestBaseType, QtiTestExpression } from "./test-expression.js";
+
+/** An ordered branch evaluated after the section's final item submission. */
+export interface QtiTestBranch {
+  readonly target: string;
+  readonly expression: QtiTestExpression;
+}
+
+/** A fixed item reference; categories participate in test-variable aggregation. */
+export interface QtiTestItemRef {
+  readonly identifier: string;
+  readonly href: string;
+  readonly categories: readonly string[];
+}
+
+/** A flat section in the supported linear, individually submitted test profile. */
+export interface QtiTestSection {
+  readonly identifier: string;
+  readonly title: string;
+  readonly items: readonly QtiTestItemRef[];
+  readonly branches: readonly QtiTestBranch[];
+}
+
+/** Framework-neutral QTI test definition. Validation establishes executable support. */
+export interface QtiTestDefinition {
+  readonly identifier: string;
+  readonly title: string;
+  readonly partIdentifier: string;
+  readonly sections: readonly QtiTestSection[];
+  readonly outcomeDeclarations: readonly QtiOutcomeDeclaration[];
+  readonly outcomeProcessing: readonly QtiTestOutcomeRule[];
+}
+
+/** Sequential assignment of a test expression to a declared test outcome. */
+export interface QtiTestOutcomeRule {
+  readonly type: "setOutcomeValue";
+  readonly identifier: string;
+  readonly expression: QtiTestExpression;
+}
+
+type ExecutableSection = QtiTestSection & {
+  readonly items: readonly [QtiTestItemRef, ...QtiTestItemRef[]];
+};
+type ExecutableOutcome = Readonly<QtiOutcomeDeclaration> & {
+  readonly cardinality: "single";
+  readonly baseType: QtiTestBaseType;
+  readonly defaultValue: number | boolean | string | null;
+};
+
+declare const executableTest: unique symbol;
+
+/** A test checked for supported expressions, unique identifiers and forward routing. */
+export type QtiExecutableTest = Omit<QtiTestDefinition, "sections" | "outcomeDeclarations"> & {
+  readonly [executableTest]: true;
+  readonly sections: readonly [ExecutableSection, ...ExecutableSection[]];
+  readonly outcomeDeclarations: readonly ExecutableOutcome[];
+};
+
+/** Typed failure channel shared by test construction, parsing and transitions. */
+export type QtiTestResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly diagnostics: readonly QtiDiagnostic[] };
+
+/** Construct a safe test diagnostic without including submitted content. */
+export function testFailure(code: string, message: string): QtiTestResult<never> {
+  return { ok: false, diagnostics: [{ code: `test.${code}`, severity: "error", message }] };
+}