feat: add mastery status lookup and learner competency status models

[jesperhodge]

What this is

Part of #642. It adds the shared mastery status lookup table and the competency-level
learner status table, plus the two migrations that create and seed them.

This does not close #642. Two of that issue's three learner-status models have foreign
keys into tables #641 creates (CompetencyCriteria and CompetencyCriteriaGroup), and
#641 has not merged, so those two models have nothing to point at. They follow in a second
pull request. The scope split is recorded as a comment on #642.

In this PR	Deferred to slice 2
CompetencyMasteryStatus lookup model	StudentCompetencyCriteriaStatus
StudentCompetencyStatus	StudentCompetencyCriteriaGroupStatus
ADR-0002 Decision 5 indexes 8 and 10	Indexes 6 and 7
Schema migration and seed data migration	The three whole-feature gates listed below

The whole-feature gates #642 carries (all ten indexes present, make pii_check at 100%
across every model #613 adds, and migrations applying from scratch across all three merged
tickets) all need #641's tables to exist before they mean anything, so they are verified in
slice 2.

How the status ordering works

The three status values are seeded with pinned primary keys in rank order, lowest to
highest: AttemptedNotDemonstrated is 1, PartiallyAttempted is 2, Demonstrated is 3.
A MasteryStatus enum names them so no integer literal appears in model code.

Pinning the order into the primary key is what makes it visible to the database. Raising a
learner's status is then a single statement, UPDATE ... SET status_id = %s WHERE ... AND status_id < %s, with no join and no subquery. That is what ADR-0004 Decision 4 needs: a
read, a comparison in Python, and a write would let two concurrent writers each read the
same old value, and the later write would then lower what the earlier one had raised.

Pinned ids are not just convenient here, they are forced. The constraint that keeps
AttemptedNotDemonstrated out of StudentCompetencyStatus has to be a single-row CHECK,
because MySQL does not allow a subquery inside one. A single-row check can only compare the
row's own status_id against literals, so stable ids are required either way, and a
separate rank column would be a second source of truth for the same ordering. It would
also be an extra column, which the acceptance criteria cap at ADR-0002 Decision 6's two.

The cost, stated plainly: a fourth status can be added above or below the existing three,
but not between them. If that is ever needed, a rank column can be added then and
backfilled from id.

Seeding a system-owned lookup row at a pinned id follows existing precedent in this repo,
src/openedx_tagging/migrations/0012_language_taxonomy.py.

Deliberate divergences from the acceptance criteria

1. created and modified use manual_date_time_field(), not auto_now_add/auto_now.

The criteria name the auto flags. They cannot work on this model. auto_now is applied by
DateTimeField.pre_save, which only runs on Model.save(); QuerySet.update() carries
only the values passed to it. So auto_now=True would leave modified stale on exactly
the conditional-UPDATE path that ADR-0004 Decision 4 mandates and that this PR exists to
enable. A field that looks automatic but silently is not is worse than one that makes the
caller pass a value.

manual_date_time_field() is also this repo's own convention for this shape of model. It
is used throughout the publishing and versioning core (LearningPackage,
PublishableEntity, PublishLog, DraftChangeLog, Content), where one logical
operation writes many rows that should share one timestamp, and auto_now_add is used in
peripheral single-row models. Learner status writes are the former: ADR-0004 opens by
noting that one grade change updates the leaf and every row above it, for many learners at
once. Because Decision 3 commits each level separately and celery may retry, those rows are
written at several wall-clock times, so a caller-supplied timestamp is the only way one
cascade's rows carry one "as of" value.

The field names are unchanged. created and modified are what OEP-38 mandates and what
both this repo and openedx-platform use.

2. The model class is CompetencyMasteryStatus, singular.

#642, #613 and ADR-0002 all write CompetencyMasteryStatuses. Django models are singular by
convention, and #641 already applies this same resolution within this ticket family, naming
its class CompetencyCriterion for the CompetencyCriteria table. Table naming follows
#640's precedent, letting Django derive it.

3. Field names are idiomatic Django, so index 8's columns differ from the ADR's spelling.

ADR-0002 writes the foreign key columns as oel_tagging_tag_id and status_id. The fields
here are tag and status, matching ObjectTag.tag in this repo, so index 8 lands on
(user_id, tag_id) rather than (user_id, oel_tagging_tag_id). Reviewers checking that
criterion literally should not read this as a miss.

Deletion behaviour

Each on_delete value here is final, and #642 as rewritten on 2026-09-02 records why. #655
closed with an approved design, #799 is closed as superseded, and no follow-up ticket will
revisit these values. The earlier TODO(#799) comments are gone.

Foreign key	Value	Why
user	CASCADE	A learner's competency status is a derived fact about that learner, so it goes when they do.
tag	PROTECT	Stops #641's CASCADE chain, which is what makes ADR-0002 Decision 7's guarantee real.
status	PROTECT	The lookup table is system-owned immutable data that live rows reference.

PROTECT on the status foreign keys is load-bearing, not defensive. #641's four
definition-to-definition foreign keys are CASCADE, decided on #655. So deleting a Tag
makes Django's collector walk down into its criteria groups and then into their criteria. The
PROTECT values on the status tables are the only thing that stops that walk, and they are
what turns ADR-0002 Decision 7 into behavior rather than intent: the delete succeeds when no
learner holds a status beneath the row, and raises ProtectedError when one does. Django
evaluates PROTECT on every row the collector reaches, not only the row passed to delete(),
which is what makes the transitive cases work. #675 re-implements the same predicate at the
API layer so the caller gets a clean status code instead of a 500; the database-level
PROTECT is the backstop for the paths that never reach #675.

An earlier revision of this description said the approved design archives a Tag instead of
deleting it, making PROTECT a backstop against a different check. That was wrong on both
counts and has been corrected here and in the code comment. Archiving belongs to #716 and to a
not-yet-filed openedx_tagging ticket, and it applies to the criteria and tagging rows rather
than replacing a Tag delete.

user is CASCADE, not PROTECT. PROTECT there let this library veto User.delete()
platform-wide, from openedx-platform code that has no reason to know CBE rows exist.
SET_NULL was never a candidate: a null user_id would break the (user_id, tag_id)
uniqueness the in-place-update design rests on.

CASCADE rather than DO_NOTHING, which #642 offered as the alternative, because
DO_NOTHING does not do what its name suggests. Django implements on_delete in Python, not
in the database: MySQL builds all three of these foreign keys as ON DELETE NO ACTION
whatever value is declared. So under DO_NOTHING, Django emits no SQL for the parent delete
while the database constraint stays in force, and deleting a user raises IntegrityError: FOREIGN KEY constraint failed rather than leaving an orphan. A genuine orphan additionally
needs db_constraint=False, which removes referential integrity on user_id altogether.
Both behaviours were verified against a real database before choosing.

status is PROTECT because the mastery status table is seeded by migration and never
deleted, so PROTECT stops a later migration or an admin from removing a status value that
live rows still reference.

Tests

Four delete tests, one per foreign key plus a transitive case:

• Deleting a referenced Tag or a referenced status row raises ProtectedError.
• Deleting a learner removes their status row and leaves the competency untouched.
• Deleting the Taxonomy above a referenced Tag raises ProtectedError. Tag.taxonomy is
  CASCADE, so this is a genuine transitive case, and it already exercises the mechanism that
  will guard Competency criteria models (authoring/definition layer) #641's chain from Tag down through groups to criteria, without waiting for
  Competency criteria models (authoring/definition layer) #641. It also covers PROTECT firing when the referencing row is inside the batch being
  deleted, since only RESTRICT exempts that case.

#642's remaining transitive criteria, deleting a Tag or a nested CompetencyCriteriaGroup
with a leaf status row beneath it, need #641's tables and belong to the slice that follows it.
That criterion says so itself. The same applies to the criteria requiring CASCADE on the
user foreign key and PROTECT on the definition-table foreign keys of all three status
models: this pull request ships one of the three, and satisfies them for it.

Nothing here implements deletion behavior in code: no delete() override, no
archive-versus-delete branch, no deletion-lock field.

Verification

Run from this branch against the repo's own tooling. Everything below passed:

Check	Result
pytest tests/openedx_learning (SQLite)	19 passed
pytest tests/openedx_learning (MySQL 8.4)	19 passed
makemigrations openedx_learning --check --dry-run	No changes detected
pylint, pycodestyle, pydocstyle, isort, mypy	clean
lint-imports	2 contracts kept, 0 broken

Nothing was suppressed to get there: no # noqa, # pylint: disable, or # type: ignore
was added.

The MySQL run matters here, because the check constraint is the centre of this change and a
green SQLite suite is not evidence for it. Inspecting the schema MySQL actually built:

CHECK constraint: oex_learning_studentcompetencystatus_status_allowed -> (`status_id` in (2,3))
unique index:     status                                              -> ['status']            (index 10)
unique index:     oex_learning_studentcompetencystatus_user_tag_uniq  -> ['user_id', 'tag_id'] (index 8)
seeded rows:      (1, 'AttemptedNotDemonstrated') (2, 'PartiallyAttempted') (3, 'Demonstrated')

Two pre-existing failures on main are unrelated to this branch and are not addressed here:
code_annotations --lint reports openedx_content.Draft and
openedx_content.PublishableEntityVersion as both annotated and safelisted, and pydocstyle
reports a missing package docstring on tests/openedx_learning/__init__.py. Both reproduce
on an untouched checkout. The two models added here carry inline .. no_pii: annotations and
neither appears in the uncovered list.

Tests

Eleven behaviours in tests/openedx_learning/applets/cbe/test_mastery.py: the seed's
contents and rank order; uniqueness of status; the conditional raise being a no-op against
a higher stored value and effective against a lower one, asserted on the row count returned
by update(); rejection of AttemptedNotDemonstrated on create(), bulk_create() and
QuerySet.update(), since none of the last two call clean(); acceptance of the two
permitted values; the one-row-per-learner-and-competency constraint; created and modified
being required and UTC-validated; a conditional raise carrying modified without touching
created; and the absence of any history package.

Admin

Both models get a bare-bones page subclassing ReadOnlyModelAdmin from
openedx_django_lib.admin_utils, whose docstring is the standing instruction to do so
rather than subclass ModelAdmin directly. Read-only is also right on the merits: the
lookup table is immutable configuration per ADR-0002 Decision 6.1, and an editable
StudentCompetencyStatus page would be the staff-correction path, which ADR-0004 Decision 6
requires to take a row lock and recompute every ancestor. None of that exists yet.

Merge order

#642 merges after #641, which is draft PR #800. Both branches add migrations to this same app:
#800 has 0002_competency_criteria and 0003_seed_default_rule_profile, this one has
0002_competency_mastery_status_models and 0003_seed_competency_mastery_statuses. So this
branch needs a rebase and a renumber to 0004/0005 once #800 lands. Docstrings here refer
to the seed migration by name rather than number, so renumbering leaves no stale references.

#800 also converts applets/cbe/models.py into a models/ package, with
competency_taxonomy.py and criteria.py in it. The slice that follows moves these two models
into that package as models/mastery.py. That needs no migration, since a model's table name
comes from its app label and class name rather than its module path, but the package
__init__.py has to re-export the names so the wildcard import in
src/openedx_learning/models.py keeps working, and admin.py's import has to be repointed.

🤖 Generated with Claude Code

[openedx-webhooks]

Thanks for the pull request, @jesperhodge!

This repository is currently maintained by @axim-engineering.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Update the status of your PR

Your PR is currently marked as a draft. After completing the steps above, update its status by clicking "Ready for Review", or removing "WIP" from the title, as appropriate.

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.