@conform-ed/qti-react 0.0.15 → 0.0.16

package/src/store.ts

@@ -13,7 +13,15 @@
  */
 
 import { scoreResponse } from "./response-processing";
-import { applyCorrectResponseOverrides, executeResponseProcessing, executeTemplateProcessing, mulberry32 } from "./rp";
+import { collectResponseViolations } from "./response-validity";
+import type { InteractionConstraint, ResponseViolation } from "./response-validity";
+import {
+  applyCorrectResponseOverrides,
+  applyTemplateDefaultOverrides,
+  executeResponseProcessing,
+  executeTemplateProcessing,
+  mulberry32,
+} from "./rp";
 import type {
   CustomOperatorImplementation,
   OutcomeDeclarationView,
@@ -36,6 +44,23 @@ export interface AttemptSnapshot {
   readonly templateValues: Readonly<Record<string, OutcomeValue>>;
   /** Completed attempts so far (only ever exceeds 1 for adaptive items). */
   readonly attemptCount: number;
+  /**
+   * Elapsed session seconds at the latest submit (the built-in `duration` response
+   * variable handed to RP); null before the first submit. Persist it alongside the
+   * responses for server-side replay parity (ADR-0004).
+   */
+  readonly durationSeconds: number | null;
+  /**
+   * Interaction constraints the current responses fail (see response-validity).
+   * Always visible so UIs can explain themselves; submission is blocked on them
+   * only under `validateResponses`.
+   */
+  readonly responseViolations: readonly ResponseViolation[];
+  /**
+   * This clone's resolved correct responses (template `setCorrectResponse` overrides
+   * applied), keyed by response identifier. The solution state renders these.
+   */
+  readonly correctResponses: Readonly<Record<string, ResponseValue>>;
 }
 
 /**
@@ -51,12 +76,32 @@ export interface AttemptStoreOptions {
   readonly normalization?: ResponseNormalization | undefined;
   readonly templateDeclarations?: readonly TemplateDeclarationView[] | undefined;
   readonly templateProcessing?: TemplateProcessingView | undefined;
+  /**
+   * Test-level `templateDefault` values (§5.152) overriding the template
+   * declarations' defaults for this clone; the test session store supplies them from
+   * the controller's recorded `templateDefaultValues`.
+   */
+  readonly templateDefaultValues?: Readonly<Record<string, OutcomeValue>> | undefined;
   /** Clone seed for template processing; store it to replay the same clone. */
   readonly seed?: number | undefined;
   /** QTI adaptive item: multiple attempts, outcome carry-over, completionStatus lock. */
   readonly adaptive?: boolean | undefined;
   /** Registered vendor `customOperator` implementations by class (opt-in). */
   readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
+  /**
+   * Millisecond clock backing the built-in `duration` response variable (wall-clock
+   * from session start to submit). Injectable for deterministic tests and replays;
+   * defaults to Date.now.
+   */
+  readonly now?: (() => number) | undefined;
+  /** The item's interaction constraints (collectInteractionConstraints over the body). */
+  readonly constraints?: readonly InteractionConstraint[] | undefined;
+  /**
+   * ItemSessionControl validate-responses: "candidates are not allowed to submit the
+   * item until they have provided valid responses for all interactions". When set,
+   * submit() refuses while `responseViolations` is non-empty.
+   */
+  readonly validateResponses?: boolean | undefined;
 }
 
 export interface AttemptStore {
@@ -76,6 +121,15 @@ export interface AttemptStore {
   ) => () => void;
   readonly submit: () => readonly ScoreResult[];
   readonly reset: () => void;
+  /**
+   * Stop the session clock: duration "records the accumulated time (in seconds) of
+   * all Candidate Sessions for all Attempts … minus any time the session was in the
+   * suspended state". Navigating away from an item suspends its session (spec);
+   * the test session store drives this. Idempotent.
+   */
+  readonly suspend: () => void;
+  /** Restart the session clock after `suspend()`. Idempotent. */
+  readonly resume: () => void;
 }
 
 export function createAttemptStore(
@@ -84,9 +138,13 @@ export function createAttemptStore(
   options?: AttemptStoreOptions,
 ): AttemptStore {
   const seed = options?.seed ?? Math.floor(Math.random() * 2 ** 31);
+  // Test-level templateDefault values replace the declared defaults for this clone.
+  const templateDeclarations = options?.templateDefaultValues
+    ? applyTemplateDefaultOverrides(options.templateDeclarations ?? [], options.templateDefaultValues)
+    : (options?.templateDeclarations ?? []);
   const templateResult = options?.templateProcessing
     ? executeTemplateProcessing(options.templateProcessing, {
-        templateDeclarations: options.templateDeclarations ?? [],
+        templateDeclarations,
         responseDeclarations: declarations,
         seed,
         customOperators: options.customOperators,
@@ -102,14 +160,53 @@ export function createAttemptStore(
   // RP's random stream: seed-derived but independent of template processing's, and
   // continuous across attempts — seed + submission sequence replays exact outcomes.
   const rpRandom = mulberry32((seed ^ 0x9e3779b9) >>> 0);
+  const now = options?.now ?? Date.now;
+  // The session clock: accumulated active milliseconds plus the running stretch.
+  // "the time between the beginning and the end of the item session minus any time
+  // the session was in the suspended state."
+  let activeMs = 0;
+  let runningSinceMs: number | null = now();
+
+  const activeSeconds = (): number => (activeMs + (runningSinceMs === null ? 0 : now() - runningSinceMs)) / 1000;
+
+  // The built-in completionStatus "starts with the reserved value 'not_attempted'.
+  // At the start of the first attempt it changes to the reserved value 'unknown'."
+  // (§2.2.2.3). The store exists only for a presented item, so its creation is the
+  // start of the first attempt; "not_attempted" is the state of items that never got
+  // a store. Explicit declarations (legacy content) keep the declared path.
+  const completionStatusDeclared = (options?.outcomeDeclarations ?? []).some(
+    (declaration) => declaration.identifier === "completionStatus",
+  );
+  const maintainedOutcomes = (): Readonly<Record<string, OutcomeValue>> =>
+    completionStatusDeclared ? {} : { completionStatus: "unknown" };
+
+  const violationsOf = (responses: Readonly<Record<string, ResponseValue>>): readonly ResponseViolation[] =>
+    options?.constraints ? collectResponseViolations(options.constraints, responses) : [];
+
+  // The clone's correct responses, flattened to response values for the solution state.
+  const correctResponses: Record<string, ResponseValue> = {};
+
+  for (const declaration of effectiveDeclarations) {
+    const values = declaration.correctResponse?.values;
+
+    if (values !== undefined) {
+      correctResponses[declaration.identifier] =
+        declaration.cardinality === "single"
+          ? ((values[0]?.value ?? null) as ResponseValue)
+          : (values.map((entry) => entry.value) as never);
+    }
+  }
 
   let snapshot: AttemptSnapshot = {
     responses: { ...initialResponses },
     submitted: false,
     scores: [],
-    outcomes: {},
+    outcomes: maintainedOutcomes(),
     templateValues: templateResult?.templateValues ?? {},
     attemptCount: 0,
+    durationSeconds: null,
+    responseViolations: violationsOf(initialResponses),
+    correctResponses,
   };
 
   function emit(next: AttemptSnapshot): void {
@@ -128,6 +225,7 @@ export function createAttemptStore(
 
   function computeOutcomes(
     responses: Readonly<Record<string, ResponseValue>>,
+    durationSeconds: number,
     priorOutcomes?: Readonly<Record<string, OutcomeValue>>,
   ): Readonly<Record<string, OutcomeValue>> {
     if (!options?.responseProcessing) {
@@ -139,11 +237,18 @@ export function createAttemptStore(
       outcomeDeclarations: options.outcomeDeclarations ?? [],
       responses,
       normalization: options.normalization,
-      templateDeclarations: options.templateDeclarations,
+      templateDeclarations,
       templateValues: snapshot.templateValues,
       priorOutcomes,
       random: rpRandom,
       customOperators: options.customOperators,
+      // Built-in session variables: numAttempts "increases by 1 at the start of
+      // each attempt", so the attempt being scored is included.
+      duration: durationSeconds,
+      numAttempts: snapshot.attemptCount + 1,
+      ...(typeof snapshot.outcomes["completionStatus"] === "string"
+        ? { completionStatus: snapshot.outcomes["completionStatus"] }
+        : {}),
     }).outcomes;
   }
 
@@ -165,9 +270,12 @@ export function createAttemptStore(
         return;
       }
 
+      const responses = { ...snapshot.responses, [responseIdentifier]: value };
+
       emit({
         ...snapshot,
-        responses: { ...snapshot.responses, [responseIdentifier]: value },
+        responses,
+        responseViolations: violationsOf(responses),
       });
     },
 
@@ -198,12 +306,24 @@ export function createAttemptStore(
       }
 
       if (collected !== snapshot.responses) {
-        snapshot = { ...snapshot, responses: collected };
+        snapshot = { ...snapshot, responses: collected, responseViolations: violationsOf(collected) };
+      }
+
+      // "candidates are not allowed to submit the item until they have provided
+      // valid responses for all interactions" — the refusal is visible through
+      // `responseViolations`, never silent (ADR-0003).
+      if (options?.validateResponses && snapshot.responseViolations.length > 0) {
+        emit(snapshot);
+
+        return snapshot.scores;
       }
 
       const scores = computeScores(snapshot.responses);
+      const durationSeconds = activeSeconds();
       const priorOutcomes = options?.adaptive && snapshot.attemptCount > 0 ? snapshot.outcomes : undefined;
-      const outcomes = computeOutcomes(snapshot.responses, priorOutcomes);
+      const rpOutcomes = computeOutcomes(snapshot.responses, durationSeconds, priorOutcomes);
+      // Items without responseProcessing still carry the maintained built-in.
+      const outcomes = options?.responseProcessing ? rpOutcomes : { ...maintainedOutcomes(), ...rpOutcomes };
       // completion_status: the corpus's snake_case authoring of the same built-in.
       const completionStatus = outcomes["completionStatus"] ?? outcomes["completion_status"];
       const completed = !options?.adaptive || completionStatus === "completed";
@@ -229,19 +349,37 @@ export function createAttemptStore(
         scores,
         outcomes,
         attemptCount: snapshot.attemptCount + 1,
+        durationSeconds,
       });
 
       return scores;
     },
 
+    suspend: () => {
+      if (runningSinceMs !== null) {
+        activeMs += now() - runningSinceMs;
+        runningSinceMs = null;
+      }
+    },
+
+    resume: () => {
+      runningSinceMs ??= now();
+    },
+
     reset: () => {
+      activeMs = 0;
+      runningSinceMs = now();
+
       emit({
         responses: { ...initialResponses },
         submitted: false,
         scores: [],
-        outcomes: {},
+        outcomes: maintainedOutcomes(),
         templateValues: snapshot.templateValues,
         attemptCount: 0,
+        durationSeconds: null,
+        responseViolations: violationsOf(initialResponses),
+        correctResponses,
       });
     },
   };