@conform-ed/qti-react 0.0.18 → 0.0.20

package/src/headless.ts

@@ -1,11 +1,15 @@
 /**
- * Headless (React-free) surface of @conform-ed/qti-react: the normalize → view adapters
- * and the capability gate, importable on a server (e.g. a QTI ingest pipeline) without
- * pulling React. Exposed at `@conform-ed/qti-react/headless`; everything here is also
- * re-exported from the package root for React consumers.
+ * Headless (React-free) surface of @conform-ed/qti-react: the normalize → view adapters,
+ * the capability gate, and the **scoring engine** (Response Processing interpreter, the
+ * standard per-response scoring templates, the item-score aggregator, and the test-level
+ * outcome-processing controller). Importable on a server (e.g. a QTI ingest pipeline or an
+ * authoritative grade finalize) without pulling React. Exposed at
+ * `@conform-ed/qti-react/headless`; everything here is also re-exported from the package
+ * root for React consumers.
  *
- * Keep this entry free of React-coupled imports — only ./normalized-item and
- * ./item-capability (value) plus type-only re-exports.
+ * Keep this entry free of React-coupled imports — every module re-exported here
+ * (./normalized-item, ./item-capability, ./response-processing, ./rp, ./item-score,
+ * ./store, ./test, ./response-validity) is verified framework-light.
  */
 
 export {
@@ -14,6 +18,41 @@ export {
   stimulusContentFromNormalized,
 } from "./normalized-item";
 export { referenceInteractionKinds, reportItemCapability, type ItemCapabilityOptions } from "./item-capability";
+
+// The scoring engine, headless. Running these server-side re-derives the grade of record
+// from the learner's raw responses + the (server-held) answer keys — see emergent ADR-0019.
+export { foldString, mapResponse, matchCorrect, mapResponsePoint, scoreResponse } from "./response-processing";
+export { effectiveItemScore, type EffectiveItemScore } from "./item-score";
+export {
+  applyCorrectResponseOverrides,
+  collectRpIssues,
+  collectTemplateIssues,
+  executeResponseProcessing,
+  executeTemplateProcessing,
+  mulberry32,
+  resolveTemplate,
+} from "./rp";
+export type {
+  CustomOperatorImplementation,
+  InterpolationTableView,
+  MatchTableView,
+  MaybeRpValue,
+  OutcomeDeclarationView,
+  OutcomeValue,
+  ResponseNormalization,
+  ResponseProcessingContext,
+  ResponseProcessingResult,
+  ResponseProcessingView,
+  RpConditionBranch,
+  RpExpressionView,
+  RpRuleView,
+  RpScalar,
+  RpValue,
+  TemplateDeclarationView,
+} from "./rp";
+export { createAttemptStore, type AttemptSnapshot, type AttemptStore, type AttemptStoreOptions } from "./store";
+export { createTestController, type TestController, type TestSessionState } from "./test";
+
 export type { CapabilityIssue, CapabilityIssueType, CapabilityReport } from "./capability";
 export type {
   AssessmentItemView,
@@ -23,4 +62,45 @@ export type {
   StimulusContentView,
   XmlContentNode,
 } from "./runtime";
-export type { AssessmentTestView } from "./test";
+export type { AssessmentItemRefView, AssessmentSectionView, AssessmentTestView, TestPartView } from "./test";
+export type { Cardinality, ResponseDeclarationView, ResponseValue, ScoreResult } from "./types";
+
+// QTI validation surface (zod mirrors of the views above) — atoms, the recursive
+// rpExpression/outcome schemas, and the structure factory. React-free; reusable for
+// import/parse validation and parameterized for authoring deltas (emergent's itemVersionId).
+export {
+  cardinalitySchema,
+  interpolationTableSchema,
+  matchTableSchema,
+  outcomeDeclarationSchema,
+  rpExpressionSchema,
+  rpScalarSchema,
+  type OutcomeDeclarationSchema,
+  type RpExpressionSchema,
+  type RpScalarSchema,
+} from "./rp/schema";
+export {
+  assessmentItemRefViewSchema,
+  assessmentTestViewSchema,
+  branchRuleSchema,
+  itemSessionControlSchema,
+  makeAssessmentTestSchema,
+  orderingSchema,
+  outcomeConditionBranchSchema,
+  outcomeProcessingSchema,
+  outcomeRuleSchema,
+  selectionSchema,
+  testFeedbackSchema,
+  timeLimitsSchema,
+  type AssessmentItemRefViewSchema,
+  type AssessmentSectionNode,
+  type AssessmentTestNode,
+  type AssessmentTestSchemas,
+  type AssessmentTestViewSchema,
+  type BranchRuleSchema,
+  type ItemSessionControlSchema,
+  type OrderingSchema,
+  type SelectionSchema,
+  type TestPartNode,
+  type TimeLimitsSchema,
+} from "./test/schema";

package/src/index.ts

@@ -14,6 +14,8 @@ export {
 
 export { foldString, mapResponse, matchCorrect, mapResponsePoint, scoreResponse } from "./response-processing";
 
+export { effectiveItemScore, type EffectiveItemScore } from "./item-score";
+
 export {
   assessmentItemViewFromNormalized,
   assessmentTestViewFromNormalized,
@@ -227,3 +229,42 @@ export {
   type PnpView,
   type ResolvedCatalogSupport,
 } from "./pnp";
+
+// QTI validation surface (zod mirrors of the assessmentTest/RP views). Also exposed at
+// `@conform-ed/qti-react/headless` for server-side import/parse validation without React.
+export {
+  cardinalitySchema,
+  interpolationTableSchema,
+  matchTableSchema,
+  outcomeDeclarationSchema,
+  rpExpressionSchema,
+  rpScalarSchema,
+  type OutcomeDeclarationSchema,
+  type RpExpressionSchema,
+  type RpScalarSchema,
+} from "./rp/schema";
+export {
+  assessmentItemRefViewSchema,
+  assessmentTestViewSchema,
+  branchRuleSchema,
+  itemSessionControlSchema,
+  makeAssessmentTestSchema,
+  orderingSchema,
+  outcomeConditionBranchSchema,
+  outcomeProcessingSchema,
+  outcomeRuleSchema,
+  selectionSchema,
+  testFeedbackSchema,
+  timeLimitsSchema,
+  type AssessmentItemRefViewSchema,
+  type AssessmentSectionNode,
+  type AssessmentTestNode,
+  type AssessmentTestSchemas,
+  type AssessmentTestViewSchema,
+  type BranchRuleSchema,
+  type ItemSessionControlSchema,
+  type OrderingSchema,
+  type SelectionSchema,
+  type TestPartNode,
+  type TimeLimitsSchema,
+} from "./test/schema";

package/src/item-score.ts

@@ -0,0 +1,40 @@
+import type { ScoreResult } from "./types";
+
+export interface EffectiveItemScore {
+  readonly raw: number;
+  readonly max: number;
+  /** True when SCORE came from the RP outcomes of record rather than per-variable scoring. */
+  readonly fromOutcomes: boolean;
+}
+
+function numericOutcome(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * The item score of record (QTI): a numeric SCORE outcome from response processing is
+ * authoritative — PCI/RP-scored items (e.g. math-entry) have no per-variable
+ * correctResponse basis, so their standard scores read 0. Summed per-variable standard
+ * scoring is the fallback for items without RP. MAXSCORE follows the same precedence.
+ *
+ * Pure and framework-light: client and server (authoritative finalize) share it so the
+ * grade of record is derived identically on both sides.
+ */
+export function effectiveItemScore(
+  scores: readonly ScoreResult[],
+  outcomes: Readonly<Record<string, unknown>>,
+): EffectiveItemScore {
+  const scoreOutcome = numericOutcome(outcomes["SCORE"]);
+  const maxOutcome = numericOutcome(outcomes["MAXSCORE"]);
+  const summedMax = scores.reduce((total, score) => total + score.maxScore, 0);
+
+  if (scoreOutcome !== null) {
+    return { raw: scoreOutcome, max: maxOutcome ?? summedMax, fromOutcomes: true };
+  }
+
+  return {
+    raw: scores.reduce((total, score) => total + score.score, 0),
+    max: maxOutcome ?? summedMax,
+    fromOutcomes: false,
+  };
+}

package/src/rp/schema.ts

@@ -0,0 +1,143 @@
+/**
+ * Zod mirrors of the Response-Processing view types (./types.ts). conform-ed owns the
+ * QTI view *types*; this is the validation surface that sits beside them — reusable for
+ * import/parse validation and kept honest against the types it mirrors. React-free.
+ *
+ * The expression union is deliberately permissive (`kind: z.string()`), exactly like
+ * `RpExpressionView`: kinds the interpreter does not implement still validate structurally
+ * and surface as `unsupported-rp` issues at evaluation time rather than being rejected here.
+ *
+ * The recursive schema is annotated against an explicit interface (`RpExpressionNode`); under
+ * `exactOptionalPropertyTypes` zod emits `T | undefined` optionals, so `z.infer` is a
+ * superset of the hand-written views (every view value parses — verified in the schema
+ * tests against real view samples). Callers that need the exact view shape map explicitly.
+ */
+
+import { z } from "zod";
+
+import type { RpScalar } from "./types";
+
+/** string | number | boolean — the QTI scalar value space (NULL is modelled by absence). */
+export const rpScalarSchema = z.union([z.string(), z.number(), z.boolean()]);
+
+/**
+ * The inferred shape of `rpExpressionSchema` — a faithful, recursive mirror of
+ * `RpExpressionView` with zod's `T | undefined` optionals. Declared explicitly (and the
+ * schema is annotated with it) because zod's getter-based recursion degrades the recursive
+ * `expressions` field to `Record<string, unknown>` under `z.infer`; the `z.lazy` + interface
+ * form keeps the type precise (the expression-builder authoring relies on it).
+ */
+export interface RpExpressionNode {
+  readonly kind: string;
+  readonly identifier?: string | undefined;
+  readonly baseType?: string | undefined;
+  readonly value?: RpScalar | undefined;
+  readonly expressions?: readonly RpExpressionNode[] | undefined;
+  readonly min?: number | string | undefined;
+  readonly max?: number | string | undefined;
+  readonly step?: number | string | undefined;
+  readonly toleranceMode?: "exact" | "absolute" | "relative" | undefined;
+  readonly tolerance?: readonly (number | string)[] | undefined;
+  readonly includeLowerBound?: boolean | undefined;
+  readonly includeUpperBound?: boolean | undefined;
+  readonly n?: number | string | undefined;
+  readonly name?: string | undefined;
+  readonly roundingMode?: "decimalPlaces" | "significantFigures" | undefined;
+  readonly figures?: number | string | undefined;
+  readonly numberRepeats?: number | string | undefined;
+  readonly pattern?: string | undefined;
+  readonly caseSensitive?: boolean | undefined;
+  readonly substring?: boolean | undefined;
+  readonly shape?: string | undefined;
+  readonly coords?: string | undefined;
+  readonly variableIdentifier?: string | undefined;
+  readonly outcomeIdentifier?: string | undefined;
+  readonly weightIdentifier?: string | undefined;
+  readonly sectionIdentifier?: string | undefined;
+  readonly includeCategory?: string | readonly string[] | undefined;
+  readonly excludeCategory?: string | readonly string[] | undefined;
+  readonly class?: string | undefined;
+  readonly definition?: string | undefined;
+  readonly fieldIdentifier?: string | undefined;
+}
+
+/**
+ * A numeric attribute that may also be a variable reference (§2.11.3.6 / §7.13): the
+ * random/aggregate bounds, `index`/`anyN` positions, rounding `figures`, `repeat` counts.
+ */
+const numberOrRef = z.union([z.number(), z.string()]);
+
+/** `includeCategory` / `excludeCategory` accept a single category or a list. */
+const categoryFilter = z.union([z.string(), z.array(z.string())]);
+
+export const cardinalitySchema = z.enum(["single", "multiple", "ordered", "record"]);
+
+/** The recursive expression schema (`z.lazy` recursion; annotated for a precise `z.infer`). */
+export const rpExpressionSchema: z.ZodType<RpExpressionNode> = z.lazy(() =>
+  z.object({
+    kind: z.string(),
+    identifier: z.string().optional(),
+    baseType: z.string().optional(),
+    value: rpScalarSchema.optional(),
+    expressions: z.array(rpExpressionSchema).optional(),
+    min: numberOrRef.optional(),
+    max: numberOrRef.optional(),
+    step: numberOrRef.optional(),
+    toleranceMode: z.enum(["exact", "absolute", "relative"]).optional(),
+    tolerance: z.array(numberOrRef).optional(),
+    includeLowerBound: z.boolean().optional(),
+    includeUpperBound: z.boolean().optional(),
+    n: numberOrRef.optional(),
+    name: z.string().optional(),
+    roundingMode: z.enum(["decimalPlaces", "significantFigures"]).optional(),
+    figures: numberOrRef.optional(),
+    numberRepeats: numberOrRef.optional(),
+    pattern: z.string().optional(),
+    caseSensitive: z.boolean().optional(),
+    substring: z.boolean().optional(),
+    shape: z.string().optional(),
+    coords: z.string().optional(),
+    variableIdentifier: z.string().optional(),
+    outcomeIdentifier: z.string().optional(),
+    weightIdentifier: z.string().optional(),
+    sectionIdentifier: z.string().optional(),
+    includeCategory: categoryFilter.optional(),
+    excludeCategory: categoryFilter.optional(),
+    class: z.string().optional(),
+    definition: z.string().optional(),
+    fieldIdentifier: z.string().optional(),
+  }),
+);
+
+// ---------- Outcome declarations (lookup tables) ----------
+
+export const matchTableSchema = z.object({
+  defaultValue: rpScalarSchema.optional(),
+  matchTableEntries: z.array(z.object({ sourceValue: z.number(), targetValue: rpScalarSchema })),
+});
+
+export const interpolationTableSchema = z.object({
+  defaultValue: rpScalarSchema.optional(),
+  interpolationTableEntries: z.array(
+    z.object({
+      sourceValue: z.number(),
+      targetValue: rpScalarSchema,
+      includeBoundary: z.boolean().optional(),
+    }),
+  ),
+});
+
+export const outcomeDeclarationSchema = z.object({
+  identifier: z.string(),
+  cardinality: cardinalitySchema,
+  baseType: z.string().optional(),
+  defaultValue: z.object({ values: z.array(z.object({ value: rpScalarSchema })) }).optional(),
+  matchTable: matchTableSchema.optional(),
+  interpolationTable: interpolationTableSchema.optional(),
+  normalMaximum: z.number().optional(),
+  normalMinimum: z.number().optional(),
+});
+
+export type RpScalarSchema = z.infer<typeof rpScalarSchema>;
+export type RpExpressionSchema = z.infer<typeof rpExpressionSchema>;
+export type OutcomeDeclarationSchema = z.infer<typeof outcomeDeclarationSchema>;

package/src/test/schema.ts

@@ -0,0 +1,272 @@
+/**
+ * Zod mirrors of the `assessmentTest` structural views (./types.ts) — the shared QTI
+ * atoms (`timeLimits`, `itemSessionControl`, `selection`, `ordering`, `branchRule`,
+ * test-level outcome processing/feedback) and the recursive structure
+ * (`assessmentSection` / `testPart` / `assessmentTest`).
+ *
+ * The structure is exposed as a **factory parameterized by the itemRef schema** —
+ * `makeAssessmentTestSchema(itemRefSchema)` — because the only thing that varies between
+ * delivery (an `href`) and authoring (an `itemVersionId`) is the item reference's identity.
+ * The ready `assessmentTestViewSchema` binds the delivery `href` itemRef; emergent binds
+ * its authoring itemRef. React-free; see ../rp/schema.ts for the RP-level mirrors.
+ */
+
+import { z } from "zod";
+
+import {
+  outcomeDeclarationSchema,
+  type OutcomeDeclarationSchema,
+  type RpExpressionSchema,
+  rpExpressionSchema,
+} from "../rp/schema";
+
+// ---------- Shared atoms (cascade levels: testPart → section → itemRef) ----------
+
+/** `timeLimits` (seconds); the controller enforces these under its injected clock. */
+export const timeLimitsSchema = z.object({
+  minTime: z.number().nonnegative().optional(),
+  maxTime: z.number().nonnegative().optional(),
+  allowLateSubmission: z.boolean().optional(),
+});
+
+/** `itemSessionControl`: per-level overrides cascading testPart → section → itemRef. */
+export const itemSessionControlSchema = z.object({
+  maxAttempts: z.number().int().nonnegative().optional(),
+  showFeedback: z.boolean().optional(),
+  allowReview: z.boolean().optional(),
+  showSolution: z.boolean().optional(),
+  allowComment: z.boolean().optional(),
+  allowSkipping: z.boolean().optional(),
+  validateResponses: z.boolean().optional(),
+});
+
+/** `selection`: how many children to draw, optionally with replacement (§4.2.6). */
+export const selectionSchema = z.object({
+  select: z.number().int().nonnegative(),
+  withReplacement: z.boolean().optional(),
+});
+
+/** `ordering`: whether the surviving children are shuffled (§4.2.7). */
+export const orderingSchema = z.object({ shuffle: z.boolean().optional() });
+
+export type TimeLimitsSchema = z.infer<typeof timeLimitsSchema>;
+export type ItemSessionControlSchema = z.infer<typeof itemSessionControlSchema>;
+export type SelectionSchema = z.infer<typeof selectionSchema>;
+export type OrderingSchema = z.infer<typeof orderingSchema>;
+
+/** `branchRule`: a target identifier (or EXIT_*) gated by a boolean expression. */
+export const branchRuleSchema = z.object({
+  target: z.string().trim().min(1),
+  expression: rpExpressionSchema,
+});
+
+export type BranchRuleSchema = z.infer<typeof branchRuleSchema>;
+
+const weightSchema = z.object({ identifier: z.string().trim().min(1), value: z.number() });
+
+const templateDefaultSchema = z.object({
+  templateIdentifier: z.string().trim().min(1),
+  expression: rpExpressionSchema,
+});
+
+// ---------- Test-level outcome processing + feedback ----------
+
+/** A gate plus its nested rules (`outcomeIf` / `outcomeElseIf`); see `OutcomeRuleNode`. */
+export interface OutcomeConditionBranchNode {
+  readonly expression: RpExpressionSchema;
+  readonly rules: readonly OutcomeRuleNode[];
+}
+
+/**
+ * The recursive outcome-rule shape (a faithful mirror of `OutcomeRuleView` with zod's
+ * `T | undefined` optionals). Declared explicitly so `z.infer` stays precise through the
+ * recursion (the getter form degrades nested rules to `Record<string, unknown>`).
+ */
+export interface OutcomeRuleNode {
+  readonly kind: string;
+  readonly identifier?: string | undefined;
+  readonly expression?: RpExpressionSchema | undefined;
+  readonly rules?: readonly OutcomeRuleNode[] | undefined;
+  readonly outcomeIf?: OutcomeConditionBranchNode | undefined;
+  readonly outcomeElseIfs?: readonly OutcomeConditionBranchNode[] | undefined;
+  readonly outcomeElse?: { readonly rules: readonly OutcomeRuleNode[] } | undefined;
+}
+
+/** One `outcomeIf` / `outcomeElseIf` branch: a gate plus its nested rules. */
+export const outcomeConditionBranchSchema: z.ZodType<OutcomeConditionBranchNode> = z.lazy(() =>
+  z.object({
+    expression: rpExpressionSchema,
+    rules: z.array(outcomeRuleSchema),
+  }),
+);
+
+/** A recursive outcome rule (mirrors `OutcomeRuleView`); `kind` stays permissive. */
+export const outcomeRuleSchema: z.ZodType<OutcomeRuleNode> = z.lazy(() =>
+  z.object({
+    kind: z.string(),
+    identifier: z.string().optional(),
+    expression: rpExpressionSchema.optional(),
+    rules: z.array(outcomeRuleSchema).optional(),
+    outcomeIf: outcomeConditionBranchSchema.optional(),
+    outcomeElseIfs: z.array(outcomeConditionBranchSchema).optional(),
+    outcomeElse: z.object({ rules: z.array(outcomeRuleSchema) }).optional(),
+  }),
+);
+
+export const outcomeProcessingSchema = z.object({ rules: z.array(outcomeRuleSchema) });
+
+export type OutcomeProcessingSchema = z.infer<typeof outcomeProcessingSchema>;
+
+/**
+ * `testFeedback` — the scalar attributes are mirrored; the `content` body is accepted
+ * opaquely (BodyNode is the item runtime's content model, not authored at the test level).
+ */
+export const testFeedbackSchema = z.object({
+  access: z.enum(["atEnd", "during"]).optional(),
+  outcomeIdentifier: z.string().trim().min(1),
+  identifier: z.string().trim().min(1),
+  showHide: z.enum(["show", "hide"]).optional(),
+  content: z.array(z.unknown()).optional(),
+});
+
+export type TestFeedbackSchema = z.infer<typeof testFeedbackSchema>;
+
+// ---------- The delivery itemRef (href identity) ----------
+
+/** The delivery `assessmentItemRef` (`href` identity) — the ready view itemRef. */
+export const assessmentItemRefViewSchema = z.object({
+  kind: z.literal("assessmentItemRef"),
+  identifier: z.string().trim().min(1),
+  href: z.string().optional(),
+  categories: z.array(z.string()).optional(),
+  fixed: z.boolean().optional(),
+  required: z.boolean().optional(),
+  preConditions: z.array(rpExpressionSchema).optional(),
+  branchRules: z.array(branchRuleSchema).optional(),
+  itemSessionControl: itemSessionControlSchema.optional(),
+  timeLimits: timeLimitsSchema.optional(),
+  weights: z.array(weightSchema).optional(),
+  templateDefaults: z.array(templateDefaultSchema).optional(),
+});
+
+// ---------- The recursive structure factory ----------
+
+const assessmentSectionFlags = {
+  title: z.string().trim().min(1).optional(),
+  visible: z.boolean().optional(),
+  fixed: z.boolean().optional(),
+  required: z.boolean().optional(),
+  keepTogether: z.boolean().optional(),
+  selection: selectionSchema.optional(),
+  ordering: orderingSchema.optional(),
+  preConditions: z.array(rpExpressionSchema).optional(),
+  branchRules: z.array(branchRuleSchema).optional(),
+  itemSessionControl: itemSessionControlSchema.optional(),
+  timeLimits: timeLimitsSchema.optional(),
+} as const;
+
+const testPartLevel = {
+  preConditions: z.array(rpExpressionSchema).optional(),
+  branchRules: z.array(branchRuleSchema).optional(),
+  itemSessionControl: itemSessionControlSchema.optional(),
+  timeLimits: timeLimitsSchema.optional(),
+} as const;
+
+/**
+ * The recursive section shape, parameterized by the injected itemRef's inferred type.
+ * Optionals carry `| undefined` and arrays are `readonly` so this matches zod's object
+ * output exactly — letting the `z.lazy` section schema below be annotated `z.ZodType<…>`
+ * (a getter cannot self-infer once a generic itemRef joins the `children` union).
+ */
+export interface AssessmentSectionNode<TItemRef> {
+  readonly kind: "assessmentSection";
+  readonly identifier: string;
+  readonly title?: string | undefined;
+  readonly visible?: boolean | undefined;
+  readonly fixed?: boolean | undefined;
+  readonly required?: boolean | undefined;
+  readonly keepTogether?: boolean | undefined;
+  readonly selection?: SelectionSchema | undefined;
+  readonly ordering?: OrderingSchema | undefined;
+  readonly preConditions?: readonly RpExpressionSchema[] | undefined;
+  readonly branchRules?: readonly BranchRuleSchema[] | undefined;
+  readonly itemSessionControl?: ItemSessionControlSchema | undefined;
+  readonly timeLimits?: TimeLimitsSchema | undefined;
+  readonly children: ReadonlyArray<AssessmentSectionNode<TItemRef> | TItemRef>;
+}
+
+/** A test part: navigation/submission modes plus the cascade levels and its sections. */
+export interface TestPartNode<TItemRef> {
+  readonly identifier: string;
+  readonly navigationMode: "linear" | "nonlinear";
+  readonly submissionMode: "individual" | "simultaneous";
+  readonly preConditions?: readonly RpExpressionSchema[] | undefined;
+  readonly branchRules?: readonly BranchRuleSchema[] | undefined;
+  readonly itemSessionControl?: ItemSessionControlSchema | undefined;
+  readonly timeLimits?: TimeLimitsSchema | undefined;
+  readonly assessmentSections: readonly AssessmentSectionNode<TItemRef>[];
+}
+
+/** The whole `assessmentTest`: declarations/processing/feedback plus the ordered parts. */
+export interface AssessmentTestNode<TItemRef> {
+  readonly identifier: string;
+  readonly title?: string | undefined;
+  readonly outcomeDeclarations?: readonly OutcomeDeclarationSchema[] | undefined;
+  readonly timeLimits?: TimeLimitsSchema | undefined;
+  readonly testParts: readonly TestPartNode<TItemRef>[];
+  readonly outcomeProcessing?: OutcomeProcessingSchema | undefined;
+  readonly testFeedbacks?: readonly TestFeedbackSchema[] | undefined;
+}
+
+/** The schema bundle the factory returns (each level parameterized by the itemRef type). */
+export interface AssessmentTestSchemas<TItemRef> {
+  readonly assessmentSectionSchema: z.ZodType<AssessmentSectionNode<TItemRef>>;
+  readonly testPartSchema: z.ZodType<TestPartNode<TItemRef>>;
+  readonly assessmentTestSchema: z.ZodType<AssessmentTestNode<TItemRef>>;
+}
+
+/**
+ * Build the recursive `assessmentTest` schema around a caller-supplied itemRef schema.
+ * Sections nest sections-or-itemRefs through `children` (recursion via `z.lazy`); `z.infer`
+ * follows the recursion and carries the injected itemRef's inferred type. The explicit
+ * return type keeps the package's `isolatedDeclarations` build able to emit the bundle.
+ */
+export function makeAssessmentTestSchema<ItemRef extends z.ZodType>(
+  itemRefSchema: ItemRef,
+): AssessmentTestSchemas<z.infer<ItemRef>> {
+  const assessmentSectionSchema: z.ZodType<AssessmentSectionNode<z.infer<ItemRef>>> = z.lazy(() =>
+    z.object({
+      kind: z.literal("assessmentSection"),
+      identifier: z.string().trim().min(1),
+      ...assessmentSectionFlags,
+      children: z.array(z.union([assessmentSectionSchema, itemRefSchema])),
+    }),
+  );
+
+  const testPartSchema: z.ZodType<TestPartNode<z.infer<ItemRef>>> = z.object({
+    identifier: z.string().trim().min(1),
+    navigationMode: z.enum(["linear", "nonlinear"]),
+    submissionMode: z.enum(["individual", "simultaneous"]),
+    ...testPartLevel,
+    assessmentSections: z.array(assessmentSectionSchema),
+  });
+
+  const assessmentTestSchema: z.ZodType<AssessmentTestNode<z.infer<ItemRef>>> = z.object({
+    identifier: z.string().trim().min(1),
+    title: z.string().trim().min(1).optional(),
+    outcomeDeclarations: z.array(outcomeDeclarationSchema).optional(),
+    timeLimits: timeLimitsSchema.optional(),
+    testParts: z.array(testPartSchema),
+    outcomeProcessing: outcomeProcessingSchema.optional(),
+    testFeedbacks: z.array(testFeedbackSchema).optional(),
+  });
+
+  return { assessmentSectionSchema, testPartSchema, assessmentTestSchema };
+}
+
+/** The ready delivery-view schema: the recursive structure over the `href` itemRef. */
+export const assessmentTestViewSchema: z.ZodType<AssessmentTestNode<AssessmentItemRefViewSchema>> =
+  makeAssessmentTestSchema(assessmentItemRefViewSchema).assessmentTestSchema;
+
+export type AssessmentItemRefViewSchema = z.infer<typeof assessmentItemRefViewSchema>;
+export type AssessmentTestViewSchema = z.infer<typeof assessmentTestViewSchema>;