tessera-learn 0.0.10 → 0.0.13

package/src/runtime/quiz-engine.svelte.ts

@@ -0,0 +1,361 @@
+import { SvelteSet } from 'svelte/reactivity';
+import type { Interaction } from './interaction.js';
+import type { QuizConfig } from './types.js';
+import {
+  resolveFeedbackMode,
+  resolveRetryStrategy,
+  type QuizQuestionResult,
+  type FeedbackModePredicate,
+  type RetryStrategyPredicate,
+} from './quiz-policy.js';
+import type {
+  UseQuizInternalHandle,
+  UseQuizQuestionApi,
+  QuestionInternal,
+  Question,
+} from './hooks.svelte.js';
+
+/**
+ * Dependencies injected into {@link QuizEngine} so the engine itself stays
+ * framework- and DOM-free. The Svelte wrapper (`useQuiz`) provides the two
+ * callbacks that bridge to the host element and the LMS adapter.
+ */
+export interface QuizEngineDeps {
+  quizConfig: QuizConfig;
+  /**
+   * Live accessor for the resolved passing threshold (config + LMS mastery
+   * override). Read on each access rather than captured, because the cmi5/SCORM
+   * mastery override mutates `pageContext.passingScore` after `useQuiz()` may
+   * already have run.
+   */
+  passingScore: () => number;
+  /** Wraps `adapterCtx.adapter.reportInteraction`; a no-op when there is no adapter. */
+  report: (
+    id: string,
+    interaction: Interaction,
+    correct: boolean | null,
+  ) => void;
+  /**
+   * Wraps the host-element `CustomEvent` dispatch. Returns `false` when the host
+   * element is null (the engine treats that as "no LMS bridge listener").
+   */
+  dispatch: (name: string, detail?: unknown) => boolean;
+}
+
+interface InternalQuestion {
+  id: string;
+  weight: number;
+  checkAnswer: (answer?: unknown) => boolean;
+  reset?: () => void;
+  interaction?: () => Interaction;
+  render: unknown;
+}
+
+/**
+ * The quiz engine: all reactive state, scoring, retry/feedback policy and the
+ * register/submit/retry lifecycle that used to live inside the `useQuiz`
+ * closure. Directly instantiable (and unit-testable) because the only two
+ * side-effecting touchpoints — DOM events and LMS reporting — are injected.
+ */
+export class QuizEngine implements UseQuizInternalHandle {
+  #deps: QuizEngineDeps;
+  #feedbackPredicate: FeedbackModePredicate;
+  #retryPredicate: RetryStrategyPredicate;
+  #maxAttempts: number;
+
+  #internalQuestions = $state<InternalQuestion[]>([]);
+  #questionHandles = $state<QuestionInternal[]>([]);
+  #answers = new Map<number, unknown>();
+  #reportedAnswers = new Map<number, string>();
+  #answersVersion = $state(0);
+  #submitted = $state(false);
+  #reviewing = $state(false);
+  #score = $state(0);
+  #attemptCount = $state(0);
+  #submitCalled = false; // plain field, not $state — only the wrapper's onDestroy reads it
+  #feedbackShown = new SvelteSet<number>();
+  #lockedCorrect = new SvelteSet<number>();
+  #seenIds = new Set<string>();
+
+  constructor(deps: QuizEngineDeps) {
+    this.#deps = deps;
+    this.#maxAttempts = deps.quizConfig.maxAttempts ?? Infinity;
+    this.#feedbackPredicate = resolveFeedbackMode(deps.quizConfig);
+    this.#retryPredicate = resolveRetryStrategy(deps.quizConfig);
+  }
+
+  // Derived values are plain getters over $state, mirroring ProgressState (which
+  // has no $derived). Getters recompute on read with or without a tracking
+  // effect, so engine-construction tests need no $effect.root.
+  get #totalQuestions(): number {
+    return this.#internalQuestions.length;
+  }
+
+  get #allAnswered(): boolean {
+    void this.#answersVersion;
+    return (
+      this.#totalQuestions > 0 && this.#answers.size >= this.#totalQuestions
+    );
+  }
+
+  get state(): 'answering' | 'submitted' | 'reviewing' {
+    return this.#reviewing
+      ? 'reviewing'
+      : this.#submitted
+        ? 'submitted'
+        : 'answering';
+  }
+
+  get questions(): ReadonlyArray<Question> {
+    return this.#questionHandles;
+  }
+
+  get canSubmit(): boolean {
+    return !this.#submitted && this.#allAnswered;
+  }
+
+  get canRetry(): boolean {
+    return this.#submitted && this.#attemptCount < this.#maxAttempts;
+  }
+
+  get score(): number {
+    return this.#score;
+  }
+
+  get passingScore(): number {
+    return this.#deps.passingScore();
+  }
+
+  get attemptCount(): number {
+    return this.#attemptCount;
+  }
+
+  /** Dev-warning inputs the wrapper reads in onDestroy. */
+  get stats(): {
+    questionsCount: number;
+    answersCount: number;
+    submitCalled: boolean;
+  } {
+    return {
+      questionsCount: this.#internalQuestions.length,
+      answersCount: this.#answers.size,
+      submitCalled: this.#submitCalled,
+    };
+  }
+
+  registerQuestion(api: UseQuizQuestionApi): QuestionInternal {
+    if (this.#seenIds.has(api.id)) {
+      console.warn(
+        `[tessera] useQuiz: duplicate question id "${api.id}" — ` +
+          'each question id must be unique within a quiz (LMS interaction records key by id).',
+      );
+    }
+    this.#seenIds.add(api.id);
+    const internal: InternalQuestion = {
+      id: api.id,
+      weight: typeof api.weight === 'number' && api.weight > 0 ? api.weight : 1,
+      checkAnswer: api.checkAnswer,
+      reset: api.reset,
+      interaction: api.interaction,
+      render: undefined,
+    };
+    this.#internalQuestions.push(internal);
+    const handle = this.#makeQuestionHandle(this.#internalQuestions.length - 1);
+    this.#questionHandles.push(handle);
+    return handle;
+  }
+
+  setAnswer(index: number, answer: unknown): void {
+    this.#answers.set(index, answer);
+    this.#answersVersion++;
+    this.#deps.dispatch('tessera-quiz-question-answered', { index });
+  }
+
+  getAnswer(index: number): unknown {
+    void this.#answersVersion;
+    return this.#answers.get(index);
+  }
+
+  setRender(index: number, render: unknown): void {
+    if (this.#internalQuestions[index])
+      this.#internalQuestions[index].render = render;
+  }
+
+  getRender(index: number): unknown {
+    return this.#internalQuestions[index]?.render;
+  }
+
+  feedbackVisible(index: number): boolean {
+    if (this.#deps.quizConfig.feedbackMode === 'never') return false;
+    return this.#feedbackPredicate({
+      questionIndex: index,
+      submitted: this.#submitted,
+      reviewing: this.#reviewing,
+      hasAnswered: this.#answers.has(index),
+      revealed: this.#feedbackShown.has(index),
+      attemptCount: this.#attemptCount,
+    });
+  }
+
+  revealFeedbackByIndex(index: number): void {
+    if (this.#deps.quizConfig.feedbackMode === 'never') return;
+    this.#feedbackShown.add(index);
+  }
+
+  isLockedCorrect(index: number): boolean {
+    return this.#lockedCorrect.has(index);
+  }
+
+  revealFeedback(q: Question): void {
+    const index = this.#internalQuestions.findIndex((iq) => iq.id === q.id);
+    if (index >= 0) this.revealFeedbackByIndex(index);
+  }
+
+  submit(): void {
+    this.#submitCalled = true;
+    if (this.#submitted) return;
+    if (!this.#allAnswered) return;
+    // Combined null-host guard + before-submit dispatch: dispatch() returns false
+    // when the host element is null, which is the silent-LMS-dropout case.
+    if (!this.#deps.dispatch('tessera-quiz-before-submit')) {
+      console.warn(
+        '[tessera] useQuiz: submit() ran but the host element was null — no LMS bridge ' +
+          'listener exists, so this score will not be persisted. Make sure your custom ' +
+          'quiz shell binds the element it passes to useQuiz({ element: () => ... }).',
+      );
+      return;
+    }
+
+    for (let i = 0; i < this.#internalQuestions.length; i++) this.#commit(i);
+
+    const { rounded } = this.#computeScore();
+    this.#score = rounded;
+    this.#submitted = true;
+    this.#attemptCount++;
+
+    this.#deps.dispatch('tessera-quiz-complete', { score: rounded });
+  }
+
+  startReview(): void {
+    if (!this.#submitted) return;
+    this.#reviewing = true;
+  }
+
+  exitReview(): void {
+    this.#reviewing = false;
+  }
+
+  retry(): void {
+    if (!this.canRetry) return;
+    const results: QuizQuestionResult[] = [];
+    for (let i = 0; i < this.#internalQuestions.length; i++) {
+      const a = this.#answers.has(i) ? this.#answers.get(i) : undefined;
+      results.push({
+        interaction:
+          this.#internalQuestions[i].interaction?.() ?? ({} as never),
+        correct: this.#internalQuestions[i].checkAnswer(a),
+        weight: this.#internalQuestions[i].weight,
+      });
+    }
+    const newLocked = this.#retryPredicate(results);
+    const preserved = new Map<number, unknown>();
+    for (const i of newLocked) {
+      if (this.#answers.has(i)) preserved.set(i, this.#answers.get(i));
+    }
+    this.#lockedCorrect.clear();
+    for (const i of newLocked) this.#lockedCorrect.add(i);
+    this.#answers.clear();
+    this.#reportedAnswers.clear();
+    for (const [i, a] of preserved) this.#answers.set(i, a);
+    for (let i = 0; i < this.#internalQuestions.length; i++) {
+      if (!newLocked.has(i) && this.#internalQuestions[i].reset)
+        this.#internalQuestions[i].reset!();
+    }
+    this.#answersVersion++;
+    this.#feedbackShown.clear();
+    this.#submitted = false;
+    this.#reviewing = false;
+    this.#score = 0;
+    this.#deps.dispatch('tessera-quiz-retry');
+  }
+
+  #commit(index: number): void {
+    const q = this.#internalQuestions[index];
+    if (!q || typeof q.interaction !== 'function') return;
+    const interaction = q.interaction();
+    if (!interaction) return;
+    const fingerprint = JSON.stringify(interaction);
+    if (this.#reportedAnswers.get(index) === fingerprint) return;
+    const answer = this.#answers.has(index)
+      ? this.#answers.get(index)
+      : undefined;
+    this.#deps.report(q.id, interaction, q.checkAnswer(answer));
+    this.#reportedAnswers.set(index, fingerprint);
+  }
+
+  #computeScore(): { rounded: number; correctCount: number } {
+    let weighted = 0;
+    let totalWeight = 0;
+    let correctCount = 0;
+    for (let i = 0; i < this.#internalQuestions.length; i++) {
+      const q = this.#internalQuestions[i];
+      const a = this.#answers.has(i) ? this.#answers.get(i) : undefined;
+      const ok = q.checkAnswer(a);
+      totalWeight += q.weight;
+      if (ok) {
+        weighted += q.weight;
+        correctCount++;
+      }
+    }
+    if (totalWeight === 0) return { rounded: 0, correctCount: 0 };
+    return {
+      rounded: Math.round((weighted / totalWeight) * 100),
+      correctCount,
+    };
+  }
+
+  #makeQuestionHandle(i: number): QuestionInternal {
+    const engine = this;
+    return {
+      get id() {
+        return engine.#internalQuestions[i].id;
+      },
+      get submitted() {
+        return engine.#submitted;
+      },
+      get correct() {
+        if (!engine.#submitted) return null;
+        const a = engine.#answers.has(i) ? engine.#answers.get(i) : undefined;
+        return engine.#internalQuestions[i].checkAnswer(a);
+      },
+      get answer() {
+        return engine.getAnswer(i);
+      },
+      get feedbackVisible() {
+        return engine.feedbackVisible(i);
+      },
+      get locked() {
+        return (
+          engine.#submitted ||
+          engine.feedbackVisible(i) ||
+          engine.isLockedCorrect(i)
+        );
+      },
+      get isLockedCorrect() {
+        return engine.isLockedCorrect(i);
+      },
+      get render() {
+        return engine.getRender(i);
+      },
+      setAnswer(a: unknown) {
+        engine.setAnswer(i, a);
+      },
+      commit() {
+        engine.#commit(i);
+      },
+      setRender(r: unknown) {
+        engine.setRender(i, r);
+      },
+    };
+  }
+}

package/src/runtime/quiz-policy.ts

@@ -1,10 +1,12 @@
 /**
- * Quiz config desugaring. Authors drive feedback / retry / submit-gating /
- * scoring with either string enums or predicate functions; this module
- * normalizes both forms into predicates so `useQuiz` only ever interacts
- * with the predicate API.
+ * Quiz config desugaring. Authors pick feedback / retry behavior with string
+ * enums in `pageConfig.quiz`; this module normalizes them into predicates so
+ * `useQuiz` only ever interacts with the predicate API. Config is extracted
+ * from source as a static object literal (JSON5), so only the enum forms are
+ * representable — there are no function-valued options.
  */
 import type { Interaction } from './interaction.js';
+import type { QuizConfig } from './types.js';
 
 export interface QuizQuestionResult {
   /** The original interaction reported for the question. */
@@ -15,12 +17,7 @@ export interface QuizQuestionResult {
   weight: number;
 }
 
-/**
- * State the feedback predicate is given so it can decide independently of
- * the string-enum branches inside `useQuiz`. The predicate is the single
- * source of truth — the enums (`'immediate'` / `'review'`) desugar into
- * predicates over this same state.
- */
+/** State the feedback predicate decides over. */
 export interface FeedbackVisibilityState {
   /** Index of the question being asked about. */
   questionIndex: number;
@@ -30,114 +27,43 @@ export interface FeedbackVisibilityState {
   reviewing: boolean;
   /** Has the question been answered (the shell called `setAnswer`)? */
   hasAnswered: boolean;
-  /**
-   * Has the shell explicitly revealed feedback for this question via
-   * `revealFeedback(index)`? Lets `'immediate'` flows distinguish "answered
-   * but not yet revealed" from "Check Answer button pressed."
-   */
+  /** Has the shell revealed feedback for this question via `revealFeedback`? */
   revealed: boolean;
   /** Number of times `submit()` has fired for this quiz instance. */
   attemptCount: number;
 }
 
 export type FeedbackModePredicate = (state: FeedbackVisibilityState) => boolean;
-export type RetryStrategyPredicate = (results: QuizQuestionResult[]) => Set<number>;
-export type CanSubmitPredicate = (answeredCount: number, totalCount: number) => boolean;
-export type ScorePredicate = (results: QuizQuestionResult[]) => number;
-
-export interface QuizPolicyConfig {
-  /**
-   * When feedback for a question should render:
-   *  - `'immediate'` — after the shell calls `revealFeedback(q)` for the question.
-   *  - `'review'` (default) — only while the quiz is in review mode.
-   *  - `'never'` — feedback never renders, no Review button.
-   *  - predicate `(state) => boolean` — full control over visibility.
-   *
-   * Predicates receive a `FeedbackVisibilityState` so they can decide
-   * independently of the enum branches — the enums themselves desugar to
-   * predicates over the same state.
-   */
-  feedbackMode?: 'immediate' | 'review' | 'never' | FeedbackModePredicate;
-  /**
-   * On retry, clear every answer (`'full'`), preserve correct answers
-   * (`'incorrect-only'`), or pass a custom predicate that takes the previous
-   * attempt's results and returns the set of question indices to keep locked.
-   */
-  retryMode?: 'full' | 'incorrect-only' | RetryStrategyPredicate;
-  /**
-   * Custom gate for the Submit button. Defaults to "every registered
-   * question has an answer". Predicates take (answered, total).
-   */
-  canSubmit?: CanSubmitPredicate;
-  /**
-   * Custom score formula. Defaults to weighted-correct percentage —
-   * `Σ(weight × correct) / Σ(weight) × 100`. Authors must return a value in
-   * 0–100; values outside that range warn in dev mode.
-   */
-  score?: ScorePredicate;
-}
+export type RetryStrategyPredicate = (
+  results: QuizQuestionResult[],
+) => Set<number>;
 
 /**
- * Resolve the configured feedback policy into a single predicate that owns
- * the "should this question's feedback be visible right now?" decision.
- *
- * The shipping enums desugar to:
- *  - `'immediate'` — visible after the shell calls `revealFeedback(q)` for
- *    the question, OR while the quiz is in review mode.
- *  - `'review'` (default) — visible only while the quiz is in review mode.
- *  - `'never'` — never visible. `useQuiz` short-circuits before calling here.
- *
- * Predicates receive the full visibility state so they can encode any policy
- * — e.g. "only after first wrong attempt": `(s) => s.attemptCount > 0 && s.submitted`.
+ * Resolve the configured feedback policy into the "should this question's
+ * feedback be visible now?" predicate.
+ *  - `'immediate'` — visible after the shell calls `revealFeedback(q)`, or in review.
+ *  - `'review'` (default) — visible only while reviewing.
+ *  - `'never'` — never visible (`useQuiz` short-circuits before calling here).
  */
-export function resolveFeedbackMode(cfg: QuizPolicyConfig | undefined | null): FeedbackModePredicate {
+export function resolveFeedbackMode(
+  cfg: QuizConfig | undefined | null,
+): FeedbackModePredicate {
   const mode = cfg?.feedbackMode;
-  if (typeof mode === 'function') return mode;
-  if (mode === 'immediate') {
-    return (s) => s.revealed || s.reviewing;
-  }
-  if (mode === 'never') {
-    return () => false;
-  }
-  // Default + 'review'
+  if (mode === 'immediate') return (s) => s.revealed || s.reviewing;
+  if (mode === 'never') return () => false;
   return (s) => s.reviewing;
 }
 
-function isDevMode(): boolean {
-  return import.meta.env?.DEV === true;
-}
-
 /**
- * Resolve the configured retry strategy into a predicate that returns the
- * set of question indices to lock as "already correct" on the next attempt.
- *
- *  - `'full'` (default) — reset everything.
+ * Resolve the retry strategy into a predicate returning the set of question
+ * indices to lock as "already correct" on the next attempt.
  *  - `'incorrect-only'` — keep questions the learner got right.
- *  - function — author decides per result.
- *
- * Author predicates are wrapped: a non-Set return turns into "lock nothing"
- * in production and throws in dev so the bug stays local. An author returning
- * `[0, 1]` instead of `new Set([0, 1])` would otherwise silently no-op the
- * lock and quietly break `'incorrect-only'`-style retries.
+ *  - `'full'` (default) — reset everything.
  */
-export function resolveRetryStrategy(cfg: QuizPolicyConfig | undefined | null): RetryStrategyPredicate {
-  const mode = cfg?.retryMode;
-  if (typeof mode === 'function') {
-    return (results) => {
-      const raw = mode(results);
-      if (!(raw instanceof Set)) {
-        if (isDevMode()) {
-          throw new TypeError(
-            `[tessera] quiz retryMode predicate returned ${Object.prototype.toString.call(raw)}; ` +
-              `expected a Set<number> of question indices to lock.`
-          );
-        }
-        return new Set<number>();
-      }
-      return raw;
-    };
-  }
-  if (mode === 'incorrect-only') {
+export function resolveRetryStrategy(
+  cfg: QuizConfig | undefined | null,
+): RetryStrategyPredicate {
+  if (cfg?.retryMode === 'incorrect-only') {
     return (results) => {
       const locked = new Set<number>();
       results.forEach((r, i) => {
@@ -146,82 +72,5 @@ export function resolveRetryStrategy(cfg: QuizPolicyConfig | undefined | null):
       return locked;
     };
   }
-  // Default 'full': clear every answer.
   return () => new Set<number>();
 }
-
-/**
- * Resolve the Submit gate. Default — all answered.
- *
- * Author predicates are wrapped: a non-boolean return is coerced with `!!` in
- * production and throws in dev. Authors returning `answered` (a number) would
- * otherwise enable Submit on `0` answered ↔ disable on a count that happens
- * to equal `NaN` — silently wrong gates either way.
- */
-export function resolveCanSubmit(cfg: QuizPolicyConfig | undefined | null): CanSubmitPredicate {
-  if (typeof cfg?.canSubmit === 'function') {
-    const fn = cfg.canSubmit;
-    return (answered, total) => {
-      const raw = fn(answered, total);
-      if (typeof raw !== 'boolean') {
-        if (isDevMode()) {
-          throw new TypeError(
-            `[tessera] quiz canSubmit predicate returned ${typeof raw}; expected a boolean.`
-          );
-        }
-        return !!raw;
-      }
-      return raw;
-    };
-  }
-  return (answered, total) => total > 0 && answered >= total;
-}
-
-/**
- * Resolve the score formula. Default — weighted-correct percentage. With all
- * weights = 1 (the default for every existing course), the output equals the
- * pre-Phase-5 unweighted formula.
- */
-export function resolveScore(cfg: QuizPolicyConfig | undefined | null): ScorePredicate {
-  if (typeof cfg?.score === 'function') {
-    return (results) => {
-      const raw = cfg.score!(results);
-      const isDev = isDevMode();
-      if (typeof raw !== 'number' || !Number.isFinite(raw)) {
-        // NaN/Infinity/non-number can't ride through to setScore(...) — the LMS
-        // either rejects the cmi write or rolls it up to nonsense. Throw in dev
-        // so the bug stays local; clamp to 0 in prod so a runaway predicate
-        // can't crash the learner's session.
-        if (isDev) {
-          throw new TypeError(
-            `[tessera] quiz score predicate returned ${String(raw)}; expected a finite number in 0–100.`
-          );
-        }
-        return 0;
-      }
-      if (raw < 0 || raw > 100) {
-        if (isDev) {
-          // eslint-disable-next-line no-console
-          console.warn(
-            `[tessera] quiz score predicate returned ${raw}; expected a finite number in 0–100. ` +
-              `Clamping to range — LMSes reject out-of-range cmi.score.raw values.`
-          );
-        }
-        return Math.max(0, Math.min(100, raw));
-      }
-      return raw;
-    };
-  }
-  return (results) => {
-    if (results.length === 0) return 0;
-    let weighted = 0;
-    let totalWeight = 0;
-    for (const r of results) {
-      const w = r.weight > 0 ? r.weight : 1;
-      totalWeight += w;
-      if (r.correct) weighted += w;
-    }
-    if (totalWeight === 0) return 0;
-    return Math.round((weighted / totalWeight) * 100);
-  };
-}

package/src/runtime/types.ts

@@ -1,6 +1,14 @@
 import type { AccessFn } from './access.js';
 import type { XAPIAgent } from './xapi/types.js';
 
+/**
+ * Quiz enum domains as runtime tuples. The unions below derive from these, and
+ * the build-time validator imports them too — so the accepted value set has a
+ * single source and can't drift between the types and the validator.
+ */
+export const FEEDBACK_MODES = ['review', 'immediate', 'never'] as const;
+export const RETRY_MODES = ['full', 'incorrect-only'] as const;
+
 /**
  * Per-page quiz configuration. Single source of truth — the build plugin
  * extracts this from `pageConfig.quiz` and embeds it in the manifest;
@@ -10,8 +18,8 @@ export interface QuizConfig {
   graded?: boolean;
   gatesProgress?: boolean;
   maxAttempts?: number;
-  feedbackMode?: 'review' | 'immediate' | 'never';
-  retryMode?: 'full' | 'incorrect-only';
+  feedbackMode?: (typeof FEEDBACK_MODES)[number];
+  retryMode?: (typeof RETRY_MODES)[number];
 }
 
 export interface CourseConfig {
@@ -19,6 +27,10 @@ export interface CourseConfig {
   description?: string;
   author?: string;
   version?: string;
+  /** BCP-47 language tag for <html lang>. Defaults to 'en'. WCAG 3.1.1. */
+  language?: string;
+  /** Accessibility checker configuration. */
+  a11y?: A11yConfig;
   branding?: {
     logo?: string;
     primaryColor?: string;
@@ -45,6 +57,16 @@ export interface CourseConfig {
   xapi?: XAPIConfig | XAPIConfig[];
 }
 
+/** Accessibility checker configuration. */
+export interface A11yConfig {
+  /** Build-gate severity for promotable Tier-1 rules + Tier-1a warnings. */
+  level?: 'warn' | 'error';
+  /** axe ruleset tags for the Tier-2 runtime auditor. */
+  standard?: 'wcag2a' | 'wcag2aa' | 'wcag21aa';
+  /** Per-rule escape hatch matched literally against each diagnostic's ID. */
+  ignore?: string[];
+}
+
 export interface ManualCompletion {
   mode: 'manual';
   /**

package/src/runtime/xapi/agent-rules.ts

@@ -7,6 +7,11 @@
  * Keeping the rules in one place prevents the two callsites from drifting.
  */
 
+/** Join a field label with a validator suffix: `.foo` chains, others get `: `. */
+export function joinFieldError(label: string, suffix: string): string {
+  return suffix.startsWith('.') ? `${label}${suffix}` : `${label}: ${suffix}`;
+}
+
 /**
  * Validate that a candidate is an Identified Agent per xAPI 1.0.3.
  * Returns null on success or a human-readable error suffix on failure.
@@ -40,7 +45,10 @@ export function validateAgent(actor: unknown): string | null {
     }
   }
   if (a.mbox_sha1sum !== undefined) {
-    if (typeof a.mbox_sha1sum !== 'string' || !/^[0-9a-f]{40}$/i.test(a.mbox_sha1sum)) {
+    if (
+      typeof a.mbox_sha1sum !== 'string' ||
+      !/^[0-9a-f]{40}$/i.test(a.mbox_sha1sum)
+    ) {
       return '.mbox_sha1sum must be a 40-character hex string';
     }
   }
@@ -81,10 +89,10 @@ export function validateAgent(actor: unknown): string | null {
  */
 export function validateAuthCredential(auth: string): string | null {
   if (typeof auth !== 'string' || !auth) {
-    return 'auth must be a non-empty string';
+    return 'must be a non-empty string';
   }
   if (/^basic\s/i.test(auth)) {
-    return "auth must be the Basic credential value only, not the full header. Drop the 'Basic ' prefix.";
+    return "must be the Basic credential value only, not the full header. Drop the 'Basic ' prefix.";
   }
   if (/^bearer\s/i.test(auth)) {
     return 'Bearer/OAuth credentials are not supported in v1. Use Basic auth, or wrap your token-exchange in an auth function that returns a Basic credential.';