xAPI and cmi5 Event Model

Status: in-progress

Intent

Define how internal domain events map to xAPI statements and cmi5-compatible flows.

Design Direction

• Internal transactional model remains canonical
• xAPI statements are generated from domain events and lifecycle transitions
• cmi5-specific launch/session constraints are layered on top of xAPI generation
• The upstream ADL LRS Conformance Test Suite is a hard gate for the public LRS surface, so route order and normalization rules should be implemented in slices that let the relevant batteries pass early.

Actor Mapping

• Actor maps to a stable Emergent-controlled account IFI, not mbox.
• account.homePage is the Emergent-controlled identity namespace for the deployment.
• account.name is the stable internal person identifier, not a mutable username or email address.
• Person display metadata is optional and should remain lossy-safe; it must not be required for identity matching.
• Teacher previews, admin imports, and service-driven statements use separate authority mapping from actor mapping.

Activity IRI Strategy

• Material assignment activity: https://emergent.app/xapi/activities/material-assignment/{assignmentId}
• Material version activity: https://emergent.app/xapi/activities/material-version/{courseMaterialVersionId}
• Learning unit activity: https://emergent.app/xapi/activities/learning-unit/{learningUnitId}
• Competency node activity: https://emergent.app/xapi/activities/competency-node/{competencyNodeId}
• Qualification activity: https://emergent.app/xapi/activities/qualification/{qualificationDefinitionId}

Rules:

• The assignment activity is the primary object for learner playback and progress statements.
• The material-version activity is used in context when statement provenance needs to survive reassignment.
• Activity IRIs are owned by Emergent and should resolve to human-readable metadata over time.
• H5P runtime-local ids must never appear as the canonical xAPI activity id.

Verb and Object Mapping Baseline

Internal event	xAPI verb (illustrative)	xAPI object
unit viewed	experienced	learning unit activity
attempt started	initialized	assessment activity
attempt submitted	completed	assessment activity
score finalized	scored or profile-specific verb	assessment attempt result projection
feedback issued	profile-specific feedback verb	feedback activity linked to attempt
competency demonstrated	profile-specific competency verb	competency node activity
competency state changed	profile-specific progression verb	competency-state activity
qualification granted	earned	qualification activity

Verb profiles should be versioned and documented.

H5P Event Mapping

Runtime event	xAPI verb	xAPI object	Notes
launch issued	https://w3id.org/xapi/adl/verbs/launched	material assignment activity	Emitted by platform boundary, not by Lumi directly
player initialized	http://adlnet.gov/expapi/verbs/initialized	material assignment activity	Registration is required
content experienced	http://adlnet.gov/expapi/verbs/experienced	material assignment activity	Used for lightweight interaction start
question answered	http://adlnet.gov/expapi/verbs/answered	interaction activity or parent	Use interaction metadata when available
progress checkpoint recorded	https://emergent.app/xapi/verbs/progressed	material assignment activity	Emergent-owned profile verb
content completed	http://adlnet.gov/expapi/verbs/completed	material assignment activity	Completion is not equivalent to success
score finalized	https://w3id.org/xapi/adl/verbs/scored	material assignment activity	Include scaled/raw/min/max when known
teacher preview launched	https://emergent.app/xapi/verbs/previewed	material assignment activity	Must not write learner progress projections

Registration and Authority Mapping

• Registration is per launch lineage, not per person or per raw H5P package.
• A new registration is issued when the platform creates a new launch session.
• Authority is derived from the authenticated LRS credential used on ingest.
• Actor and authority may differ, especially for platform-imported or teacher-preview statements.
• Statement ids should be deterministic when emitted from platform domain events and may be generated by the LRS for accepted runtime events that arrive without ids.

Result and Context Mapping

result should include:

• Completion and success indicators where applicable
• Score details including scaled/raw/min/max where meaningful
• Duration when session semantics apply
• Response payloads only when the interaction type supports them and the privacy posture allows them

context should include:

• Offering or container context identifiers
• Assignment lineage identifiers
• Material version identifiers
• Competency framework/version and competency-node identifiers where applicable
• Platform extension context required for traceability

Recommended context layout:

• context.registration: launch-session registration UUID
• context.contextActivities.parent: assignment activity
• context.contextActivities.grouping: offering activity
• context.contextActivities.category: Emergent verb-profile or product-profile activities when needed
• context.contextAgents: teacher or reviewer relationships where the relationship matters to the statement
• context.contextGroups: cohort or group relationships only when they materially change meaning
• context.extensions:
  • https://emergent.app/xapi/extensions/offering-id
  • https://emergent.app/xapi/extensions/learning-unit-id
  • https://emergent.app/xapi/extensions/course-material-version-id
  • https://emergent.app/xapi/extensions/launch-session-id
  • https://emergent.app/xapi/extensions/runtime-provider

cmi5 Considerations

For cmi5-compatible flows:

• Respect launch/session boundaries in event generation
• Support AU (assignable unit) progression semantics
• Ensure move-on criteria can be evaluated from generated statement stream

Current launch-boundary limits:

• Assignment-level cmi5 AU metadata now comes from course_material_assignment.cmi5_au_metadata_payload and feeds moveOn, masteryScore, launchParameters, entitlementKey, and publisher grouping activity when populated.
• Assignment AU metadata is populated at import (derived from the version manifest) and maintained in bulk via the admin backfill (POST .../cmi5-au-metadata/backfill); there is no per-assignment update endpoint.
• Workflow auth also exposes POST /workflow/course-material-assignments/cmi5-au-metadata/backfill to populate empty assignment AU metadata in bulk from derivable version manifests for the caller’s accessible organizations.
• The backfill request accepts dryRun plus optional organizationId scope, and the admin console dashboard now uses that path as the first concrete admin caller for previewing or applying manifest-derived AU metadata.
• Launch resolution falls back to course_material_version.source_manifest_payload when assignment AU metadata is empty. The normalized import shape is cmi5AuMetadata or cmi5.auMetadata, with direct cmi5 and root-object fallback for the same AU fields.
• H5P launch handlers still accept /runtime/assignments/{assignmentId}/launch inside the service, but the Kubernetes gateway deployment publishes that surface through the Supabase-compatible /functions/v1/runtime/assignments/{assignmentId}/launch path. The LMS-launched statement records the public launch URL in the cmi5 launchURL context extension.
• LMS.LaunchData now includes a real returnURL when the matching portal public URL is configured. Learner launches return to /classes/{offeringId}; preview launches return to the configured portal root.
• If neither assignment metadata nor a derivable source manifest is present, launches still fall back to spec-safe defaults and omit optional cmi5 values.

Idempotency and Ordering

xAPI generation pipeline requirements:

• Deterministic statement identifiers or idempotency keys
• Stable ordering for transitions of the same attempt/session
• Retry-safe emission to LRS targets

Initial implementation rules:

• Platform-originated statements should use deterministic ids derived from the event identity.
• Runtime-originated statements that arrive without ids may be assigned ids by the LRS, but ordering must still preserve launch-session chronology.
• Projection updates must be idempotent by statement.id.
• Teacher preview traffic must be distinguishable from learner progress traffic at the statement level.

Implementation Anchors

• Domain events and contract types: packages/domain
• Event persistence or outbox support: packages/db and apps/api
• Local/offline event capture and replay markers: packages/offline-data

Conformance Gate

• Treat the IEEE xAPI 2.0 documentation as the normative protocol source and the upstream ADL LRS Conformance Test Suite as the executable compatibility oracle.
• Add the conformance harness early and keep it expected-red until the corresponding LRS slice exists; do not wait for the full H5P flow before exercising it.
• Basic-auth compatibility must stay first-wave because the upstream suite currently exercises Basic auth directly.
• MIT-licensed upstream helpers are eligible for direct TypeScript adaptation when they reduce ambiguity or spec risk, provided the required license notice is preserved for copied or derived material.

Remaining Decisions

1. Final Emergent-owned verb IRIs for progress and preview flows
2. Whether interaction-level child activities should be minted eagerly or lazily
3. Partitioning strategy for high-volume statement retrieval in large cohorts