refactor(tracking): retire the xAPI grading channel, SCORM 1.2 is the only one

[erseco]

Replaces #122, which went the other way — it tried to make the xAPI overall work. Measuring it end to end showed that is not worth doing.

Summary

The plugin grades through two channels. They are not equivalent, and the one enabled by default is the worse of the two.

	SCORM 1.2	xAPI
Per-iDevice grade	100 / 0	identical
Weighted overall (25/75)	25	50, or nothing at all
Attempts, completion, gradebook, events	full	the same code

The xAPI ingestor calls into track::apply_item_scores() and attempts::record_item() for everything except the overall. So the channel duplicates transport, authentication, validation and identity resolution to reach the same code, and the one thing it does on its own is the one thing it gets wrong.

It was always experimental

No product requirement asked for it — DEC-0-14 answered "no por ahora" to whether there was demand for LRS analytics. Its scope explicitly excluded cmi5 and any external LRS (DEC-17-01 §6, DEC-0-18 §9). This plugin has been its only consumer.

The numbers

Measured end to end in a real Moodle: same package, same learner actions, two pages, weights 25 / 75, first answered fully correct, second fully wrong. The weighted overall is 25.

• SCORM publishes 25, in both PERITEM and OVERALL grade models.
• xAPI publishes 50. statement_normalizer hardcodes 'weighted' => 0.0, so recompute_overall_pct() falls into its unweighted-mean branch.
• On main today a multipage xAPI attempt gets no overall row at all — no gradebook column, no attempt_completed, no OVERALL grade model.

Weights cannot travel on this channel: they are not in the statements, and putting them there was rejected on principle — package structure supplied by a learner's browser must not reshape another learner's grade.

What is NOT lost

• iDevice coverage. There is one dispatch site in the exported package and both channels share its trigger; the SCORM half only additionally needs pipwerks, which this plugin injects into every served page. No gradable iDevice reaches one channel and not the other.
• Identity across pages. This was xAPI's one real advantage — stable object IRIs against SCORM's page-local slots. The versioned exe12/ payload closes it: records carry their own stable id.
• Attempts, completion, gradebook, events, mobile. Shared code, untouched. Mobile was SCORM-only anyway; xAPI never had a web service.

exelearning_tracking_events is dropped, public release and all

This section changed twice, so here is the whole reasoning rather than just the conclusion.

An intermediate revision dropped the table claiming the plugin had never been published. That premise was false, and review caught it:

$ git show v4.0.2:db/install.xml | grep -c exelearning_tracking_events
1

v4.0.3 returns the same, and xapi_track.php is in both trees, so the published releases ship the table and a working writer. A site that used the xAPI channel can hold rows, and the table is absent from backup/moodle2. That correction stands.

The table is dropped anyway — a deliberate call, not an oversight. Three reasons:

• What is lost is audit, not assessment. Grades, attempts and reports live in exelearning_grade_item and exelearning_attempt and are untouched. This table held per-statement audit metadata — statementid, verb, objectid, registration, scaled, user and timestamp — and the statement.id deduplication those ids provided. It never stored the statement JSON, and no grade calculation has ever read it.
• The exposure window is very short. v4.0.2 is from 2026-07-07, the channel was switchable off, and the plugin is in early deployment. The row volume in the field is negligible against carrying an inert table indefinitely.
• Keeping it was not free. Neither exelearning_delete_instance() nor exelearning_reset_userdata() ever cleaned it, so deleting an activity or resetting a course orphaned learner-linked rows — unreachably, since the privacy API finds them by joining through the {exelearning} row that had just been deleted. Retaining an inert table meant fixing and then maintaining two cleanup paths forever, for a log nothing reads.

CHANGELOG.md announces it under Removed, so an administrator who wants those rows can dump them before upgrading.

So the definition leaves db/install.xml, all six sites leave classes/privacy/provider.php (metadata, the context-list and users-in-context queries, the export path and all four delete paths), and the eight language strings that translated them go with it.

Stage 19, which created the table, is left byte-identical — upgrade history is append-only. A new stage 21 drops it where it exists, and also calls

unset_config('xapiprimaryenabled', 'exelearning');

which is the pattern stage 20 already uses for the three configs the editor installer maintained. The setting was removed from settings.php, from the language files and from its helper, but its stored value was not: a site that had switched the channel on kept an orphan row in mdl_config_plugins that a future setting reusing the name would inherit. Now nothing survives the retirement.

Verified in a real Moodle, upgrading from the pre-stage version with the table populated and the setting on:

BEFORE: table=present rows=1 xapiprimaryenabled='1'
AFTER:  table=absent xapiprimaryenabled=false

A second stage (22, 2026082101) adds the gradable column described below. scripts/check-version.sh (DEC-111-01, wired into CI) requires $plugin->version to be strictly greater than every savepoint, so the version is 2026082102.

One deliberate call worth reviewing

disableTracking is removed, not repointed at gradeenabled.

Silencing the client for ungraded activities looks tidy but breaks two things: classes/completion/custom_completion.php queries exelearning_attempt for the itemnumber = 0 row with no grading filter, and mod_form.php::add_completion_rules() does not gate that rule on gradeenabled — so a teacher can require completion-by-status on an ungraded activity. It would also empty the attempt history DEC-13-07 promises can be recalculated when grading is re-enabled.

disableTracking was born with this channel and nothing would ever set it true again, so removing it restores the shim to its pre-DEC-85-01 behaviour.

Now fixed in this PR — see Turning grading off did not stop grading below. It was briefly attempted in #105 as an early return in track::ingest(), which broke completion by status; that commit has been dropped from #105 and the correct version lands here.

Upgrading with a page open

Upgrading while a learner has an xAPI-era page open leaves that tab with an inert SCORM shim — disableTracking was baked into the served page — and a listener posting to an endpoint that no longer exists. Its bounded retry (2 attempts, 3 s / 6 s) then drops those statements, so interactions in that tab are lost until the page reloads.

A maintenance-mode consideration rather than a data-loss path: attempts already committed are unaffected, and there is no retry storm. Recorded in DEC-122-01 and docs/tracking-architecture.md.

Language strings

A sweep of lang/ for xapi|lrs|statement|tincan now returns nothing, and no orphan is left behind: the eight strings that translated the dropped table's privacy declarations go with it, and the orphan viewstub string — which advertised an "iframe + sidebar + xAPI bridge" that does not exist — is removed from all five files. No language file still names the retired channel.

Separately, gradeenabled_help promised "no grade columns, no reports and no attempt tracking". The last third is false, and has been since the switch shipped: DEC-13-07 chose "ocultar y conservar" precisely so attempts survive. exelearning_sync_grade_items() removes the grade items; nothing touches exelearning_attempt. The clause is deleted — the diff is a pure removal — and the help text now ends at "no grade columns and no reports".

It belongs in this PR because removing disableTracking rests on the same fact: attempts must keep being written, since completion by status reads the itemnumber = 0 row with no grading filter.

Turning grading off did not stop grading

This is the defect this PR is most responsible for, because it is this PR that makes it reachable.

view.php passed disableTracking = $emitsxapi (DEC-85-01), so the SCORM shim was inert for any package that emits xAPI — which is every recent eXeLearning export, since the emitter ships in all of them. Removing disableTracking makes the shim always live, and a defect that existed in main only for non-emitting packages becomes universal.

track::ingest() never consulted gradeenabled. With the switch off the instance has no grade items, so the registered-objectid filter empties itemscores, the server-side recompute never runs, and the OVERALL publication falls back to the CLIENT's cmi.core.score.raw. And grade_update() recreates a deleted grade item — so the effect is not writing into an existing column, it is resurrecting the one the teacher just removed:

after switching grading OFF : overall=NO ITEM   items=0
after a learner submits     : overall=95.00000  attempts=1

That directly contradicts the help text this same PR ships: "no grade columns and no reports".

The guard goes at the single point that publishes, beside the grade-model condition already there:

if ($grademodel === EXELEARNING_GRADEMODEL_OVERALL && !empty($exe->gradeenabled)) {

Not as an early return in ingest(). The attempt row has to keep being written: DEC-69-01's completion by status reads it filtering on exelearningid, userid, itemnumber and status — never on gradeenabled — and mod_form.php does not gate that rule on the switch, so completion by status is settable, and has to work, on an ungraded activity.

apply_one()'s per-iDevice grade_update() needs no guard, and that is measured rather than argued. The test runs both grade models; the peritem case is green before the fix and stays green, because remove_all() marks the rows deleted = 1 and no objectid is left to recognise. A second check there would be dead code implying a path that does not exist. Recorded in DEC-124-02.

The test asserts $grades->items === [], which is stronger than "the value is null" — it requires the grade_item itself not to reappear.

And what about work done while it was off?

The two sections above compose into a question neither answers, and the answer used to depend on the grade model — which is the worst possible answer.

With grading off no objectid is registered, because remove_all() marks the mappings deleted = 1. So:

• PERITEM wrote no itemnumber > 0 rows at all. Nothing to resurrect.
• OVERALL wrote the itemnumber = 0 row completion needs, carrying a score that had not been through the server-side recompute — there was nothing to recompute from. It came straight from the browser's cmi.core.score.raw, and re-enabling published it.

Reproduced, same sequence in both models:

OVERALL  Item 0 must have no grade derived from the ungraded interval
         Failed asserting that '95.00000' is null.
PERITEM  (passes)

The same work by the same learner became a mark or not depending on a setting that says nothing about that — and where it did, the mark came from an unverified client value.

The decision: option A

The alternative was to keep per-iDevice scores through the off period and suppress only grade_update(), so re-enabling recovered everything with a proper server-side overall. Rejected: it requires objectids registered while the switch is off — exactly what remove_all() undoes — and it turns the switch into a pause button, where work done "outside assessment" ends up assessed anyway.

So the switch is a statement about what the activity is. A row written with grading off is completion-only, and the aggregation ignores it, always:

• new gradable column (INT, NOTNULL, DEFAULT 1), added by upgrade stage 22 (2026082101). Existing rows default to gradable — everything recorded before this stage came from an ingest() that made no such distinction, and assuming gradable is the conservative choice: it preserves grades a site already published;
• attempts::record_item() takes $gradable (default true, so no other caller changes) and track::ingest() passes !empty($exe->gradeenabled) at both write sites. The one inside apply_one() is unreachable with grading off, but passes the value rather than hardcoding true so the two cannot drift apart;
• all three aggregation queries filter gradable = 1 — aggregate_scaled(), fetch_scaled_by_user_item(), and the participation summary's mean. One unfiltered query would bring the asymmetry back through it.

Nothing is lost. The row keeps its score, status and timestamps, feeds completion by status and appears in the attempts report. It just never counts towards a grade. The field is declared to the privacy API, exported with transform::yesno(), and carries its string in five languages.

Which queries filter, and which must not. It is not a rule by category — it is one decision per query, and DEC-124-03 carries the table:

query	filters	why
aggregate_scaled(), fetch_scaled_by_user_item(), the summary's mean	yes	they are the grade
count_user_attempts(), behind maxattempt	yes	maxattempt is a grading control; charging it for work the activity declared outside assessment leaves a learner at the cap having never had a gradable attempt
the cap check in ingest()	does not run while grading is off	same reason: an ungraded activity must not refuse a learner on the strength of graded attempts spent earlier
MAX(attempt) in resolve_attempt_number()	no	it allocates the next number; skipping rows would reissue an existing one and collide with record_item()'s upsert key
participation COUNT(DISTINCT userid)	no	it counts who participated, not who was graded — and since the mean does filter, the summary now returns graded too and the string names both populations
custom_completion	no	completion is the reason the row exists

The flag belongs to the attempt, not the row — and the invariant is that every row of an attempt shares it. A session keeps the attempt it started with even if the switch flips underneath it; a write inherits completion-only if any row of the attempt already is, and the first ungraded write takes every row of the attempt down with it. Demoting only the row being written leaves a mixed attempt, which breaks three things at once: count_user_attempts() counts an attempt as used if any row is gradable, so it keeps charging maxattempt; the surviving gradable row can be republished when grading returns; and the inheritance itself becomes order-dependent, since IGNORE_MULTIPLE has no ORDER BY. Splitting the session into a second, gradable attempt was tried and is wrong: the client accumulates its itemScores map and never clears it — deliberately, so a failed POST cannot lose a score — so a fresh gradable attempt is a clean vessel for contaminated content. Measured against the split:

attempt=1 item=0 raw=95 gradable=0
attempt=2 item=0 raw=95 gradable=1
attempt=2 item=1 raw=95 gradable=1
GRADE item 1 = '95.00000'

A session that crossed the switch produces no trustworthy grade, so it produces none. Reloading mints a new token and a clean attempt, at no cost to the learner. The accepted price is that they keep working ungraded until they reload, with no signal — preferable to turning ungraded work into a mark, and their work is still recorded, still counts for completion, and still costs them no attempts. A UI signal needs the client to read a server flag and is noted as follow-up.

Both grade models had their own fallback to the client's score when there is no gradable history — $score in ingest()'s overall, $rawitem in apply_one(). Closing only the first left PERITEM publishing the browser's 95 beside rows correctly marked gradable = 0. Both now require gradable history to publish, which is why the mid-session test runs both models.

Two known limitations, both deliberate: the report's download gains a "counts towards grade" column, but the on-screen table still lists these rows with their score unmarked; and rows recorded before this version stay gradable, since after the fact there is no reliable way to tell which were written while the switch was off — a backfill keyed on "instances ungraded right now" does not discriminate, because switching off soft-deletes every mapping, so it would demote legitimate history on any site currently switched off.

test_work_done_while_ungraded_never_becomes_a_grade runs both models: the learner completes the activity with the switch off, the rows are asserted gradable = 0, the teacher enables grading, and every recreated column must be empty while the itemnumber = 0 row survives. Verified red in two variants to separate the halves — without the flag both models fail the gradable assertion; with the flag written but the readers unfiltered, overall fails on '95.00000' is null and peritem passes, which is the asymmetry itself. Stage 22 verified against an existing install (BEFORE: absent → AFTER: present). Recorded in DEC-124-03.

Re-enabling "Graded activity" lost the grades — fixed here

Found while checking the help string above, and it turned out to be real. DEC-13-07 keeps exelearning_attempt when the switch goes off precisely so that "reactivar gradeenabled re-detecta y recalcula desde el historial", and grade_item_manager::remove_all() repeats it in its own docblock. Only the re-detect half happened.

STEP 1 graded on  : overall='80.00000'  attempts=2
STEP 2 graded off : overall='NO ITEM'   attempts=2
STEP 3 re-enabled : overall='NULL'      attempts=2   ← column back, empty
STEP 4 after an explicit exelearning_update_grades(): overall='80.00000'

grade_sync::sync() recreates the gradebook columns but never repopulates them. The republish-from-history call added in DEC-34-01 (B2) lives in exelearning_update_instance(), and its condition enumerated grademodel and grademethod — gradeenabled was not in it. A teacher who switched grading off and back on got empty columns for learners already assessed, with the data sitting in exelearning_attempt the whole time.

gradeenabled joins that condition, and the $oldrow SELECT that feeds it. Two details worth review:

• The off direction needs no guard of its own. grade_sync::update_grades() already returns immediately when gradeenabled is unset, so nothing is published into the items sync() has just deleted. A direction check here would be dead code.
• When the caller omits the field, fall back to the stored value, not to a constant. grademodel/grademethod have a safe default earlier in the function; gradeenabled does not, and assuming enabled would let a programmatic update switch grading on in silence. With the fallback, omitting the field means unchanged.
• $data is hydrated with that fallback, which is not cosmetic. exelearning_update_grades() returns early on an empty gradeenabled, so a programmatic caller that changed grademodel/grademethod without passing gradeenabled reached the republish call and had it silently do nothing — pre-existing, and now covered:

B0 PERITEM item1 = 80.00000
B1 isset(data->gradeenabled) before = false
B2 stored gradeenabled = '1' | OVERALL column = NULL

$newgradeenabled = (int) ($data->gradeenabled ?? $oldrow->gradeenabled);
if (
    (int) $data->grademodel !== (int) $oldrow->grademodel
    || (int) $data->grademethod !== (int) $oldrow->grademethod
    || $newgradeenabled !== (int) $oldrow->gradeenabled
) {
    exelearning_update_grades($data, 0);
}

test_gradeenabled_toggled_back_on_republishes_from_history walks the whole cycle with a real attempt ingested through track::ingest(). Verified red without the fix — "Failed asserting that null matches expected 80.0" — and green with it. DEC-124-01 records the rule the condition now expresses: any pure grading-configuration change republishes from history, a content change deliberately does not (DEC-12-01 snapshot-and-warn). DEC-13-07 stays Accepted and unedited — this makes its promise true rather than changing it.

Alternative considered

Leaving xapiprimaryenabled at 0 and keeping the code. The kill switch does work — xapi_track.php refuses to grade when it is off — so that would also make SCORM authoritative. It was rejected: the dead code stays, the endpoint stays published, and the decision stays untaken. Recorded in DEC-122-01 §Opciones.

This does not close the door on xAPI

The emitter lives on upstream — every exported package keeps emitting statements. What is retired here is the consumer, which is the easy half to rebuild; the hard half, speaking xAPI, is untouched.

If a real analytics requirement appears, the starting point is not this grading channel but a core_xapi handler for events, beside the grade pipeline instead of competing with it. DEC-122-01 records what would have to be solved first — chiefly the per-iDevice weight, which does not travel in the statements and without which a correct overall cannot exist.

Tests

phpunit (full suite)     →  332 tests, 1209 assertions, exit 0
npx vitest run           →  21 tests passed
composer lint (phpcs)    →  exit 0, 118 files
make architecture-check  →  exit 0, 68 records
scripts/check-version.sh →  exit 0

Surviving tracking_events references

All intentional: db/upgrade.php stage 19 (append-only history) and the new drop stage; emit_tracking_events() in track.php and tracking_events() in its test helper, which are method names unrelated to the table; the prose recording the removal; and the append-only evidence archive under research/. No live production-code reference to the table remains.

Merge order

#125 first, then this. Both branch from the same main and both touch js/scorm_tracker.js and its spec, but in different places — #125 rewrites captureItemScores(), this removes disableTracking — so they are complementary, not conflicting. The ordering is a matter of meaning rather than mechanics: this PR makes SCORM the only grading channel, so the silent multipage loss #125 fixes should be gone before that happens.

Relationship with core

eXeLearning #2302 reduces the emitter to an analytics feed with no package verdict. The two are independent: this plugin ignores the emitter either way, and old packages that still emit are harmless — the emitter posts fire-and-forget inside a try, so a message nobody listens for is discarded by the browser.

Decision recorded in DEC-122-01, superseding DEC-85-01, DEC-17-01 and DEC-0-18.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 98.50746% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 93.82%. Comparing base (85f5b99) to head (bd9b1bd).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
classes/local/attempts.php	95.23%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #124      +/-   ##
============================================
+ Coverage     92.32%   93.82%   +1.49%     
+ Complexity      824      738      -86     
============================================
  Files            51       47       -4     
  Lines          3740     3350     -390     
============================================
- Hits           3453     3143     -310     
+ Misses          287      207      -80     

Flag	Coverage Δ
javascript	94.11% <ø> (-0.23%)	⬇️
php	93.81% <98.50%> (+1.57%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
PHP (server-side)	93.81% <98.50%> (+1.57%)	⬆️
JavaScript (SCORM tracker)	94.11% <ø> (-0.23%)	⬇️

Files with missing lines	Coverage Δ
classes/external/get_user_attempts.php	100.00% <100.00%> (ø)
classes/grades/grade_item_manager.php	98.82% <ø> (ø)
classes/local/package_manager.php	97.48% <ø> (+1.03%)	⬆️
classes/local/track.php	96.96% <100.00%> (+0.12%)	⬆️
classes/local/tracking_endpoint.php	100.00% <100.00%> (ø)
classes/privacy/provider.php	94.02% <100.00%> (+2.21%)	⬆️
js/scorm_tracker.js	94.11% <ø> (-0.12%)	⬇️
lib.php	82.45% <100.00%> (+2.31%)	⬆️
classes/local/attempts.php	96.75% <95.23%> (-0.33%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.