tessera-learn 0.0.4 → 0.0.5

package/src/runtime/adapters/cmi5.ts

@@ -15,9 +15,11 @@ const VERBS = {
   completed: 'http://adlnet.gov/expapi/verbs/completed',
   passed: 'http://adlnet.gov/expapi/verbs/passed',
   failed: 'http://adlnet.gov/expapi/verbs/failed',
-  suspended: 'http://adlnet.gov/expapi/verbs/suspended',
   terminated: 'http://adlnet.gov/expapi/verbs/terminated',
-  satisfied: 'https://w3id.org/xapi/adl/verbs/satisfied',
+  // Intentionally absent: "satisfied" (LMS-only, §9.3.9) and
+  // "suspended" (not a cmi5-defined verb — §9.3 enumerates nine, none
+  // of them Suspended). The LMS infers Abandoned vs resume from
+  // registration state when Terminated lands without Completed.
 } as const;
 
 const CMI_INTERACTION_TYPE = 'http://adlnet.gov/expapi/activities/cmi.interaction';
@@ -25,6 +27,16 @@ const CMI_INTERACTION_TYPE = 'http://adlnet.gov/expapi/activities/cmi.interactio
 const CMI5_MASTERYSCORE_EXT =
   'https://w3id.org/xapi/cmi5/context/extensions/masteryscore';
 
+// cmi5 §9.6 — every cmi5 Defined Statement MUST carry the "cmi5" Category
+// Activity in context.contextActivities.category, and "completed", "passed",
+// "failed" MUST additionally carry the "moveOn" Category. Without these, an
+// LRS will accept the statement as an arbitrary xAPI verb but won't roll it
+// up into cmi5 lifecycle state — the LMS never sees the AU as completed.
+const CMI5_CATEGORY_CMI5 =
+  'https://w3id.org/xapi/cmi5/context/categories/cmi5';
+const CMI5_CATEGORY_MOVEON =
+  'https://w3id.org/xapi/cmi5/context/categories/moveon';
+
 export type CMI5MoveOn =
   | 'Passed'
   | 'Completed'
@@ -40,6 +52,67 @@ const VALID_MOVE_ON: ReadonlySet<CMI5MoveOn> = new Set([
   'NotApplicable',
 ]);
 
+/** cmi5 §10.2.2 — launch mode dictates which Defined Statements the AU may emit. */
+export type CMI5LaunchMode = 'Normal' | 'Browse' | 'Review';
+const VALID_LAUNCH_MODE: ReadonlySet<CMI5LaunchMode> = new Set([
+  'Normal',
+  'Browse',
+  'Review',
+]);
+
+/** State doc id (cmi5 §10) the LMS pre-populates with launch metadata. */
+const LMS_LAUNCH_DATA_STATE_ID = 'LMS.LaunchData';
+
+/** Agent Profile id (cmi5 §11) where the LMS stores learner preferences. */
+const CMI5_LEARNER_PREFS_PROFILE_ID = 'cmi5LearnerPreferences';
+
+/** xAPI cmi5 sessionid context extension IRI (cmi5 §9.6.3.1). */
+const CMI5_SESSIONID_EXT_IRI =
+  'https://w3id.org/xapi/cmi5/context/extensions/sessionid';
+
+/** cmi5 §10 `LMS.LaunchData` document. `contextTemplate` is the base context for every Defined Statement (§9.6.2). */
+interface CMI5LaunchData {
+  contextTemplate?: {
+    contextActivities?: {
+      category?: Array<{ id: string; objectType?: string }>;
+      grouping?: Array<{ id: string }>;
+      [k: string]: unknown;
+    };
+    extensions?: Record<string, unknown>;
+    [k: string]: unknown;
+  };
+  launchMode?: CMI5LaunchMode;
+  launchMethod?: 'OwnWindow' | 'AnyWindow';
+  launchParameters?: string;
+  returnURL?: string;
+  masteryScore?: number;
+  moveOn?: CMI5MoveOn;
+  entitlementKey?: Record<string, string>;
+  [k: string]: unknown;
+}
+
+/** cmi5 §11.1 Learner Preferences Agent Profile document. */
+interface CMI5LearnerPreferences {
+  languagePreference?: string;
+  audioPreference?: 'on' | 'off';
+  [k: string]: unknown;
+}
+
+/** `.then` handler that warns on LRS non-2xx. Publisher resolves successfully on 4xx/5xx (failure is in the outcome), so `.catch` alone misses them. */
+function warnOnLRSReject(
+  verbName: string
+): (res: { destinations?: Array<{ ok?: boolean; status?: number; error?: Error }> }) => void {
+  return (res) => {
+    const dest = res.destinations?.[0];
+    if (dest && !dest.ok) {
+      console.warn(
+        `Tessera cmi5: ${verbName} statement rejected by LRS (${dest.status ?? 'network error'})`,
+        dest.error
+      );
+    }
+  };
+}
+
 /**
  * CMI5 persistence adapter using xAPI.
  *
@@ -67,9 +140,7 @@ export class CMI5Adapter implements PersistenceAdapter {
   #durationSeconds = 0;
   #state: SavedState | null = null;
   #completedSent = false;
-  #completionStatus: 'incomplete' | 'complete' = 'incomplete';
   #successSent = false;
-  #passed = false;
   #terminated = false;
 
   // cmi5 §8 launch params. masteryScore (when present) overrides the
@@ -77,7 +148,19 @@ export class CMI5Adapter implements PersistenceAdapter {
   // authority. moveOn drives the optional Satisfied statement (§9.5.3).
   #masteryScore: number | null = null;
   #moveOn: CMI5MoveOn = 'NotApplicable';
-  #satisfiedSent = false;
+
+  // cmi5 §10 LMS.LaunchData. `contextTemplate` is the AU's base context
+  // (§9.6.2) — Publisher Activity and session id live there, and strict
+  // LRSes validate every Defined Statement against it.
+  #launchData: CMI5LaunchData | null = null;
+  /** cmi5 §10.2.2 — Browse/Review forbid every Defined Statement except Initialized/Terminated. */
+  #launchMode: CMI5LaunchMode = 'Normal';
+  /** cmi5 §10.2.6 — AU redirects here on `exit()`. */
+  #returnURL: string | undefined;
+  /** cmi5 §10.2.3 — opaque per-launch content config string. */
+  #launchParameters: string | undefined;
+  /** cmi5 §11.1 Learner Preferences. */
+  #learnerPreferences: CMI5LearnerPreferences | null = null;
 
   async init(): Promise<void> {
     const params = new URLSearchParams(window.location.search);
@@ -150,27 +233,105 @@ export class CMI5Adapter implements PersistenceAdapter {
         `Tessera cmi5: fetch token request returned ${resp.status}. The cmi5 launch fetch URL is single-use; reload from the LMS to retry.`
       );
     }
-    const text = await resp.text();
-    // The fetch URL returns the token, possibly with "auth-token=" prefix
-    // (cmi5 §6.2). The credential itself is the value used as the
-    // "Basic" Authorization header — NOT a Bearer token.
-    this.#authToken = text.replace(/^auth-token=/, '').trim();
+    const text = (await resp.text()).trim();
+    // cmi5 §11.2 — response is `{"auth-token": "..."}`. Some
+    // non-conformant LMSes return bare text with an `auth-token=`
+    // prefix, so we fall back to that. The token value is the literal
+    // Basic credential (already base64); we don't re-encode.
+    let token = '';
+    if (text.startsWith('{')) {
+      try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed['auth-token'] === 'string') {
+          token = parsed['auth-token'].trim();
+        }
+      } catch {
+        // fall through to legacy parsing
+      }
+    }
+    if (!token) {
+      token = text.replace(/^auth-token=/, '').trim();
+    }
+    this.#authToken = token;
     if (!this.#authToken) {
       throw new Error(
-        'Tessera cmi5: fetch token request returned an empty body. Expected an "auth-token=..." or bare token.'
+        'Tessera cmi5: fetch token request returned an empty token. Expected a JSON body of the form {"auth-token": "..."}.'
       );
     }
 
+    // cmi5 §10 — LaunchData is the only spec-defined channel for the
+    // session id (§9.6.3.1) and Publisher Activity (§9.6.2.3) the LRS
+    // validates against, plus launchMode/returnURL/launchParameters/
+    // masteryScore/moveOn (§10.2). LaunchData values override the URL
+    // masteryScore parsed earlier (§10.2.4 makes it authoritative).
+    this.#launchData = await this.#fetchLaunchData();
+    const tmpl = this.#launchData?.contextTemplate ?? {};
+    let sessionId: string | undefined;
+    const launchSession = (tmpl.extensions ?? {})[CMI5_SESSIONID_EXT_IRI];
+    if (typeof launchSession === 'string' && launchSession.trim()) {
+      sessionId = launchSession.trim();
+    }
+    if (this.#launchData) {
+      if (
+        typeof this.#launchData.launchMode === 'string' &&
+        VALID_LAUNCH_MODE.has(this.#launchData.launchMode)
+      ) {
+        this.#launchMode = this.#launchData.launchMode;
+      }
+      if (
+        typeof this.#launchData.returnURL === 'string' &&
+        this.#launchData.returnURL
+      ) {
+        this.#returnURL = this.#launchData.returnURL;
+      }
+      if (typeof this.#launchData.launchParameters === 'string') {
+        this.#launchParameters = this.#launchData.launchParameters;
+      }
+      if (
+        typeof this.#launchData.masteryScore === 'number' &&
+        Number.isFinite(this.#launchData.masteryScore) &&
+        this.#launchData.masteryScore >= 0 &&
+        this.#launchData.masteryScore <= 1
+      ) {
+        this.#masteryScore = this.#launchData.masteryScore;
+      }
+      if (
+        typeof this.#launchData.moveOn === 'string' &&
+        VALID_MOVE_ON.has(this.#launchData.moveOn)
+      ) {
+        this.#moveOn = this.#launchData.moveOn;
+      }
+    }
+
+    // cmi5 §11 — fetch the Agent Profile BEFORE Initialized. Strict
+    // LRSes track the GET and reject Initialized otherwise. A 404 here
+    // is legitimate (no prefs set); the GET itself is what's required.
+    this.#learnerPreferences = await this.#fetchLearnerPreferences();
+
     this.#publisher = new XAPIPublisher({
       endpoint: this.#endpoint,
       auth: this.#authToken,
       actor: this.#actor,
       activityId: this.#activityId,
       registration: this.#registration,
+      sessionId,
       cmi5Mode: true,
     });
     await this.#publisher.init();
 
+    // cmi5 §9.3.2 — queue Initialized before the resume State GET so a
+    // slow LRS can't push it past the spec's "reasonable period". The
+    // publisher queue keeps it ordered before any later Defined Statement.
+    this.#publisher
+      .sendStatement({
+        verb: { id: VERBS.initialized, display: { 'en-US': 'initialized' } },
+        context: this.#cmi5Context(),
+      })
+      .then(warnOnLRSReject('Initialized'))
+      .catch((err) => {
+        console.warn('Tessera cmi5: failed to send Initialized statement', err);
+      });
+
     // Retrieve saved state from xAPI State API. The State API is a different
     // URL than statements/, so it doesn't go through the publisher's send
     // path — but we still use the same auth/headers.
@@ -179,22 +340,17 @@ export class CMI5Adapter implements PersistenceAdapter {
       const resp = await this.#xapiFetch(stateUrl, { method: 'GET' });
       if (resp.ok) {
         this.#state = await resp.json();
+      } else if (resp.status !== 404) {
+        console.warn(
+          `Tessera cmi5: State API GET returned ${resp.status}; resume disabled for this launch.`
+        );
       }
-    } catch {
+    } catch (err) {
+      console.warn(
+        `Tessera cmi5: State API GET failed (${err instanceof Error ? err.message : String(err)}); resume disabled for this launch.`
+      );
       this.#state = null;
     }
-
-    // Send Initialized statement (queued through publisher). Log failures
-    // here too — the publisher's per-destination outcome covers transport
-    // errors but won't surface to console; lifecycle statements are rare
-    // enough that an explicit warning helps production triage.
-    await this.#publisher
-      .sendStatement({
-        verb: { id: VERBS.initialized, display: { 'en-US': 'initialized' } },
-      })
-      .catch((err) => {
-        console.warn('Tessera cmi5: failed to send Initialized statement', err);
-      });
   }
 
   /**
@@ -221,6 +377,26 @@ export class CMI5Adapter implements PersistenceAdapter {
     return this.#moveOn;
   }
 
+  /** cmi5 §10.2.2 — "Normal" is the only mode where progress-bearing Defined Statements are permitted. */
+  getLaunchMode(): CMI5LaunchMode {
+    return this.#launchMode;
+  }
+
+  /** cmi5 §10.2.6 — URL the AU navigates to on `exit()`. Returns undefined when the LMS didn't supply one. */
+  getReturnURL(): string | undefined {
+    return this.#returnURL;
+  }
+
+  /** cmi5 §10.2.3 — opaque per-launch content-config string. */
+  getLaunchParameters(): string | undefined {
+    return this.#launchParameters;
+  }
+
+  /** cmi5 §11.1 Learner Preferences. Null when the LMS didn't publish one. */
+  getLearnerPreferences(): CMI5LearnerPreferences | null {
+    return this.#learnerPreferences;
+  }
+
   getState(): SavedState | null {
     return this.#state;
   }
@@ -232,11 +408,16 @@ export class CMI5Adapter implements PersistenceAdapter {
     // Terminated. We can't use sendStatement here (different URL/verb).
     this.#publisher.chainTask(async () => {
       try {
-        await this.#xapiFetch(this.#buildStateUrl(), {
+        const resp = await this.#xapiFetch(this.#buildStateUrl(), {
           method: 'PUT',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(state),
         });
+        if (!resp.ok) {
+          console.warn(
+            `Tessera cmi5: State API PUT returned ${resp.status}; learner progress did not persist.`
+          );
+        }
       } catch (err) {
         console.warn('Tessera: Failed to save CMI5 state', err);
       }
@@ -244,36 +425,42 @@ export class CMI5Adapter implements PersistenceAdapter {
   }
 
   setScore(score: number): void {
-    this.#score = score;
+    // Clamped to [0, 100] so the /100 division yields a spec-legal
+    // scaled value in [0, 1] (xAPI).
+    if (!Number.isFinite(score)) {
+      this.#score = null;
+      return;
+    }
+    this.#score = Math.max(0, Math.min(100, score));
   }
 
   setCompletionStatus(status: 'incomplete' | 'complete'): void {
-    this.#completionStatus = status;
     if (status !== 'complete' || this.#completedSent || !this.#publisher) return;
+    // cmi5 §10.2.2 — Browse/Review launches MUST NOT emit Completed.
+    if (this.#launchMode !== 'Normal') return;
     this.#completedSent = true;
+    // cmi5 §9.5.1 — `score` MUST NOT appear on Completed (Passed/Failed only).
     const result: Record<string, unknown> = {
       completion: true,
       duration: formatISO8601Duration(this.#durationSeconds),
     };
-    if (this.#score !== null) {
-      result.score = { scaled: this.#score / 100 };
-    }
     this.#publisher
       .sendStatement({
         verb: { id: VERBS.completed, display: { 'en-US': 'completed' } },
         result,
-        context: this.#masteryContext(),
+        context: this.#cmi5Context({ moveOn: true }),
       })
+      .then(warnOnLRSReject('Completed'))
       .catch((err) => {
         console.warn('Tessera cmi5: failed to send Completed statement', err);
       });
-    this.#maybeSendSatisfied();
   }
 
   setSuccessStatus(status: 'passed' | 'failed' | 'unknown'): void {
     if (status === 'unknown' || this.#successSent || !this.#publisher) return;
+    // cmi5 §10.2.2 — Browse/Review launches MUST NOT emit Passed/Failed.
+    if (this.#launchMode !== 'Normal') return;
     this.#successSent = true;
-    this.#passed = status === 'passed';
 
     const verb = status === 'passed' ? VERBS.passed : VERBS.failed;
     const verbName = status === 'passed' ? 'passed' : 'failed';
@@ -282,18 +469,38 @@ export class CMI5Adapter implements PersistenceAdapter {
       duration: formatISO8601Duration(this.#durationSeconds),
     };
     if (this.#score !== null) {
-      result.score = { scaled: this.#score / 100 };
+      const scaled = this.#score / 100;
+      // cmi5 §9.3.4 / §9.3.5 — Passed-with-score requires scaled >=
+      // masteryScore; Failed-with-score requires scaled < masteryScore.
+      // The author asserted the verb, so on contradiction we keep the
+      // verb and drop the score (and warn).
+      if (this.#masteryScore !== null) {
+        const violatesPassed = status === 'passed' && scaled < this.#masteryScore;
+        const violatesFailed = status === 'failed' && scaled >= this.#masteryScore;
+        if (violatesPassed || violatesFailed) {
+          console.warn(
+            `Tessera cmi5: refusing to attach scaled score ${scaled.toFixed(3)} to ` +
+              `${status === 'passed' ? 'Passed' : 'Failed'} (masteryScore=${this.#masteryScore}); ` +
+              `per cmi5 §9.3.${status === 'passed' ? '4' : '5'} the score would contradict the verb. ` +
+              `Statement will be sent without a score.`
+          );
+        } else {
+          result.score = { scaled };
+        }
+      } else {
+        result.score = { scaled };
+      }
     }
     this.#publisher
       .sendStatement({
         verb: { id: verb, display: { 'en-US': verbName } },
         result,
-        context: this.#masteryContext(),
+        context: this.#cmi5Context({ moveOn: true, mastery: true }),
       })
+      .then(warnOnLRSReject(verbName === 'passed' ? 'Passed' : 'Failed'))
       .catch((err) => {
         console.warn(`Tessera cmi5: failed to send ${verbName} statement`, err);
       });
-    this.#maybeSendSatisfied();
   }
 
   setDuration(seconds: number): void {
@@ -334,7 +541,10 @@ export class CMI5Adapter implements PersistenceAdapter {
         },
         result,
       })
-      .catch(() => {});
+      .then(warnOnLRSReject('Answered'))
+      .catch((err) => {
+        console.warn('Tessera cmi5: failed to send Answered statement', err);
+      });
   }
 
   commit(): void {
@@ -350,87 +560,102 @@ export class CMI5Adapter implements PersistenceAdapter {
     // must be the last statement of the cmi5 session (§9.3.6).
     this.#publisher.markUnloading();
     const duration = formatISO8601Duration(this.#durationSeconds);
-    // cmi5 §10.1: when the AU exits without Completed, send Suspended
-    // first so the LMS distinguishes a deliberate pause from abandonment.
-    if (!this.#completedSent && this.#completionStatus !== 'complete') {
-      this.#publisher
-        .sendStatement({
-          verb: { id: VERBS.suspended, display: { 'en-US': 'suspended' } },
-          result: { duration },
-        })
-        .catch((err) => {
-          console.warn('Tessera cmi5: failed to send Suspended statement', err);
-        });
-    }
-    // cmi5 §9.5.4.1: Terminated MUST include result.duration.
+    // No Suspended — cmi5 doesn't define that verb (§9.3); the LMS
+    // handles resume vs Abandoned itself when a new session opens
+    // against an active registration (§9.3.6).
+    // cmi5 §9.5.4.1 — Terminated MUST include result.duration.
     this.#publisher
       .sendStatement({
         verb: { id: VERBS.terminated, display: { 'en-US': 'terminated' } },
         result: { duration },
+        context: this.#cmi5Context(),
       })
+      .then(warnOnLRSReject('Terminated'))
       .catch((err) => {
         console.warn('Tessera cmi5: failed to send Terminated statement', err);
       });
   }
 
-  // ---- Private helpers ----
-
   /**
-   * Build a context object carrying the cmi5 masteryscore extension when
-   * the LMS provided one. Returns undefined otherwise so the publisher
-   * doesn't add an empty `context.extensions` block.
+   * cmi5 §10.2.6 — explicit-Exit path. Terminate, wait for the
+   * publisher queue to drain so Terminated lands first, then redirect
+   * to `returnURL`. `terminate()` alone (called from pagehide) can't
+   * redirect — the page is already unloading.
    */
-  #masteryContext(): Record<string, unknown> | undefined {
-    if (this.#masteryScore === null) return undefined;
-    return {
-      extensions: { [CMI5_MASTERYSCORE_EXT]: this.#masteryScore },
-    };
+  async exit(): Promise<void> {
+    this.terminate();
+    if (this.#publisher) {
+      // chainTask with a no-op task awaits the queue head.
+      try {
+        await this.#publisher.chainTask(async () => {});
+      } catch {
+        // never rejects today; don't let a refactor block redirect.
+      }
+    }
+    if (this.#returnURL && typeof window !== 'undefined') {
+      window.location.assign(this.#returnURL);
+    }
   }
 
+  // ---- Private helpers ----
+
   /**
-   * cmi5 §9.5.3: when the moveOn criterion has been met, the AU MAY send
-   * a Satisfied statement so LMSes that don't compute moveOn themselves
-   * still see satisfaction. NotApplicable disables emission entirely.
+   * Build the cmi5 context for a Defined Statement, starting from the
+   * LMS contextTemplate (§9.6.2 — AU MUST NOT overwrite). Adds the
+   * cmi5 Category Activity (§9.6.2.1), the moveOn Category for
+   * Completed/Passed/Failed (§9.6.2.2), and the masteryScore extension
+   * for Passed/Failed (§9.6.3.2).
    */
-  #maybeSendSatisfied(): void {
-    if (this.#satisfiedSent || !this.#publisher) return;
-    if (this.#moveOn === 'NotApplicable') return;
-
-    let satisfied = false;
-    switch (this.#moveOn) {
-      case 'Passed':
-        satisfied = this.#passed;
-        break;
-      case 'Completed':
-        satisfied = this.#completedSent;
-        break;
-      case 'CompletedAndPassed':
-        satisfied = this.#completedSent && this.#passed;
-        break;
-      case 'CompletedOrPassed':
-        satisfied = this.#completedSent || this.#passed;
-        break;
+  #cmi5Context(
+    opts: { moveOn?: boolean; mastery?: boolean } = {}
+  ): Record<string, unknown> {
+    const tmpl = this.#launchData?.contextTemplate ?? {};
+    const tmplActivities = (tmpl.contextActivities ?? {}) as Record<string, unknown>;
+
+    // Concat-dedupe category to preserve any template-supplied entries
+    // (§10.2.1 forbids overwriting them).
+    const seen = new Set<string>();
+    const category: Array<{ id: string; objectType: string }> = [];
+    const push = (id: string) => {
+      if (!seen.has(id)) {
+        seen.add(id);
+        category.push({ id, objectType: 'Activity' });
+      }
+    };
+    const templateCategory = Array.isArray((tmplActivities as { category?: unknown }).category)
+      ? ((tmplActivities as { category: Array<{ id: string; objectType?: string }> }).category)
+      : [];
+    for (const c of templateCategory) {
+      if (c && typeof c.id === 'string') push(c.id);
     }
-    if (!satisfied) return;
+    push(CMI5_CATEGORY_CMI5);
+    if (opts.moveOn) push(CMI5_CATEGORY_MOVEON);
 
-    this.#satisfiedSent = true;
-    this.#publisher
-      .sendStatement({
-        verb: { id: VERBS.satisfied, display: { 'en-US': 'satisfied' } },
-        result: { duration: formatISO8601Duration(this.#durationSeconds) },
-        context: this.#masteryContext(),
-      })
-      .catch((err) => {
-        console.warn('Tessera cmi5: failed to send Satisfied statement', err);
-      });
+    const contextActivities: Record<string, unknown> = {
+      ...tmplActivities,
+      category,
+    };
+
+    const ctx: Record<string, unknown> = {
+      ...(tmpl as Record<string, unknown>),
+      contextActivities,
+    };
+    // cmi5 §9.6.3.2 — masteryScore extension is scoped to Passed/Failed.
+    if (opts.mastery && this.#masteryScore !== null) {
+      ctx.extensions = {
+        ...((tmpl.extensions ?? {}) as Record<string, unknown>),
+        [CMI5_MASTERYSCORE_EXT]: this.#masteryScore,
+      };
+    }
+    return ctx;
   }
 
-  #buildStateUrl(): string {
+  #buildStateUrl(stateId: string = 'tessera-state'): string {
     const agentJson = JSON.stringify(this.#actor);
     const params = new URLSearchParams({
       activityId: this.#activityId,
       agent: agentJson,
-      stateId: 'tessera-state',
+      stateId,
     });
     // registration is optional per CMI5 spec — omit it when not provided
     if (this.#registration) {
@@ -439,6 +664,58 @@ export class CMI5Adapter implements PersistenceAdapter {
     return `${this.#endpoint}activities/state?${params.toString()}`;
   }
 
+  /** cmi5 §11 — Agent Profile URL. Scoped to agent only (no activity/registration). */
+  #buildAgentProfileUrl(profileId: string): string {
+    const agentJson = JSON.stringify(this.#actor);
+    const params = new URLSearchParams({
+      agent: agentJson,
+      profileId,
+    });
+    return `${this.#endpoint}agents/profile?${params.toString()}`;
+  }
+
+  /** GET the cmi5 §10 `LMS.LaunchData` document. Null if absent — strict LRSes will then reject Defined Statements. */
+  async #fetchLaunchData(): Promise<CMI5LaunchData | null> {
+    try {
+      const url = this.#buildStateUrl(LMS_LAUNCH_DATA_STATE_ID);
+      const resp = await this.#xapiFetch(url, { method: 'GET' });
+      if (resp.ok) {
+        return (await resp.json()) as CMI5LaunchData;
+      }
+      console.warn(
+        `Tessera cmi5: LMS.LaunchData State GET returned ${resp.status}; ` +
+          'cmi5 Defined Statements may be rejected by strict LRSes ' +
+          '(missing Publisher Activity / session id).'
+      );
+    } catch (err) {
+      console.warn(
+        `Tessera cmi5: LMS.LaunchData State GET failed (${err instanceof Error ? err.message : String(err)}).`
+      );
+    }
+    return null;
+  }
+
+  /** GET cmi5 §11.1 Learner Preferences. 404 is normal (no prefs set). */
+  async #fetchLearnerPreferences(): Promise<CMI5LearnerPreferences | null> {
+    try {
+      const url = this.#buildAgentProfileUrl(CMI5_LEARNER_PREFS_PROFILE_ID);
+      const resp = await this.#xapiFetch(url, { method: 'GET' });
+      if (resp.ok) {
+        return (await resp.json()) as CMI5LearnerPreferences;
+      }
+      if (resp.status !== 404) {
+        console.warn(
+          `Tessera cmi5: Agent Profile GET (cmi5LearnerPreferences) returned ${resp.status}.`
+        );
+      }
+    } catch (err) {
+      console.warn(
+        `Tessera cmi5: Agent Profile GET (cmi5LearnerPreferences) failed (${err instanceof Error ? err.message : String(err)}).`
+      );
+    }
+    return null;
+  }
+
   async #xapiFetch(url: string, options: RequestInit = {}): Promise<Response> {
     const headers = new Headers(options.headers);
     if (this.#authToken) {

package/src/runtime/xapi/publisher.ts

@@ -568,11 +568,30 @@ export class XAPIPublisher {
           })
         );
     }
-    return {
-      ok: false,
-      status: resp.status,
-      error: new Error(`LRS responded ${resp.status}`),
-    };
+    // Append the LRS body to the error message so callers see the
+    // specific reason (e.g. "Forbidden cmi5 defined statement: ...").
+    // Cap at 500 chars; on read failure, fall back to bare status.
+    if (typeof resp.text !== 'function') {
+      return {
+        ok: false,
+        status: resp.status,
+        error: new Error(`LRS responded ${resp.status}`),
+      };
+    }
+    return resp.text().then(
+      (respBody): SendOutcome => ({
+        ok: false,
+        status: resp.status,
+        error: new Error(
+          `LRS responded ${resp.status}${respBody ? `: ${respBody.slice(0, 500)}` : ''}`
+        ),
+      }),
+      (): SendOutcome => ({
+        ok: false,
+        status: resp.status,
+        error: new Error(`LRS responded ${resp.status}`),
+      })
+    );
   }
 
   #resolveAuth(forceRefresh: boolean): Promise<string> {