[BE] Implement the plan to handle large quantities of competency criteria associations (pagination, filtering, cues to user, other?) on the backend

In short

What changes. This is an additive extension to the competency criteria endpoint that #681 introduces, GET /cbe/rest_api/v1/competencies/<competency_tag_id>/criteria-groups/, and to the function behind it, get_competency_criteria_tree. The endpoint gains one optional query parameter, course_keys, holding a comma-separated list of course run key strings, and the response gains two integer counts. Whether it's omitted, sent empty, or populated determines which of the three Acceptance Criteria states applies; omitting it is #681's existing unfiltered behavior, kept for admin, export, and debugging use.

Deciding what is in scope. The course run keys arrive already resolved by the caller: deciding which course runs are in view, including title search, date filtering, and paging, is the job of #669 and #670. This endpoint turns those keys into internal CourseRun ids through a new bulk resolver in openedx_catalog, then selects groups with a single predicate: the group belongs to this competency, and either it has no course scope at all or its course scope is one of the resolved ids. Every group inside a course-scoped subtree carries the course id, not just the top one, so "no course scope" picks out exactly the instance-wide subtree, and the three states need almost no branching: with no ids the predicate degrades to "no course scope," and with the parameter absent the course clause is dropped entirely.

Normalizing what the caller sent. The raw parameter is parsed into course keys before any of the Acceptance Criteria scenarios above apply, handling stray separators, duplicates, and the length cap in one pass; see Implementation specifics for the exact order and the status codes involved.

Ordering the response. #681's response is two flat arrays, groups and criteria, that a client reassembles into a tree using the parent references each row carries. Course scoping ranks each row by its course run's position in the caller's request, matching the order guaranteed in Acceptance Criteria; sorting happens in Python after the rows are fetched, since the cap already bounds how many rows there can be.

The two counts. criteria_count and total_criteria_count are what the Acceptance Criteria call the number of criteria in view and the instance-wide total. The numerator costs nothing extra, because it is a count of the criteria rows the response already loaded. The denominator is one additional COUNT(*). The important property is that the denominator is the numerator's query with the course-scope predicate removed and nothing else changed, in particular the same exclusion of archived groups and archived criteria; if the two queries filter differently, the unfiltered case stops satisfying its own acceptance criterion that the two numbers agree. Both counts cover the selected competency's own criteria only, filtering on that one tag id exactly.

The layering contract. openedx_catalog is currently absent from .importlinter's package list even though it is a real Django app, so no rule governs who may import it. This ticket is the first code to import it from another app, via the bulk resolver, so it is the natural moment to give it a declared position. It belongs beside openedx_tagging as a peer: openedx_catalog imports only openedx_django_lib, and openedx_tagging stays generic about what it tags.

Implementation specifics

• Signature. get_competency_criteria_tree(tag_id: int, course_keys: list[CourseKey] | None = None) -> CompetencyCriteriaTree in src/openedx_learning/applets/cbe/api.py. None means unfiltered, [] means instance-wide subtree only; the docstring must state that distinction explicitly, since it is the whole contract.
• Return type. Add criteria_count: int and total_criteria_count: int to the CompetencyCriteriaTree dataclass and populate both inside get_competency_criteria_tree, so the two counts always share exactly the same filters.
• Query-parameter parsing. Add a CompetencyCriteriaQueryParamsSerializer alongside #681's serializers, following the existing *QueryParamsSerializer pattern in src/openedx_tagging/rest_api/v1/serializers.py, fed from request.query_params.dict() as in that app's views. The field is serializers.CharField(required=False, allow_blank=True) with no default, so the three states stay distinguishable by testing whether the key is present in validated_data.
• Normalization order, exactly. Split on ,; strip each element; drop empty elements; reject with 400 if more than 100 elements remain; parse each remaining element with CourseKey.from_string, converting InvalidKeyError into a 400 for the whole request; de-duplicate with dict.fromkeys to preserve first-occurrence order. Duplicates count toward the 100 limit because the limit is applied before de-duplication.
• Cap. 100 entries, rejected with HTTP 400 whose detail names the number. Comma-separated list parameters already exist in this codebase without a cap (get_object_tag_counts in src/openedx_tagging/api.py); this endpoint caps deliberately, because a bounded input is what lets the response guarantee complete subtrees.
• Group predicate. oel_tagging_tag_id = <tag> AND (course_id IS NULL OR course_id IN <resolved ids>), with the parenthesized clause omitted entirely when course_keys is None. Filter on the exact tag id, so sub-competency criteria stay out of the result and both counts.
• Bulk resolver. Add get_course_run_ids(course_keys: Iterable[CourseKey]) -> dict[CourseKey, CourseRun.ID] to src/openedx_catalog/api_impl.py and list it in that module's __all__. It runs one CourseRun.objects.filter(course_key__in=...).values_list("course_key", "id"); keys with no matching row are simply absent from the returned mapping, so a stale key resolves silently. Matching is case-sensitive, consistent with get_course_run. An empty input returns an empty dict directly.
• Ordering. Build {course_run_id: index} from the de-duplicated request list and sort groups and criteria in Python by that rank as the primary key, with unscoped rows ranked ahead of every scoped one. Leave #681's existing within-subtree ordering as the secondary key, and tie-break by id so the order is total. A criterion inherits its parent group's rank, so a client walking either array sees the same course sequence.
• Counts and the archived filter. Both counts are of CompetencyCriterion rows reached through CompetencyCriteriaGroup.oel_tagging_tag_id. Both exclude rows where the criterion is archived or its group is archived. total_criteria_count is one extra COUNT(*), built as the numerator's query with the course-scope predicate removed and every other filter identical; criteria_count costs no query, it is the length of the criteria list already loaded. The archived column comes from #716.
• Permission and error precedence. Reuse CompetencyReadPermission in src/openedx_learning/applets/cbe/rest_api/v1/permissions.py unchanged. Fetch the competency tag and run the permission check before parsing course_keys, so a caller who lacks permission gets 403 and a nonexistent competency gets 404, ahead of any 400 about their query string.
• Indexes. ADR 0002 Decision 5's CompetencyCriteriaGroup(oel_tagging_tag_id, course_id) and CompetencyCriteria(competency_criteria_group_id) already cover both the scoped read and the instance-wide count.
• Layering. Add openedx_catalog to root_packages in .importlinter, and to the src_layering contract on the same line as openedx_tagging using the existing peer syntax (openedx_tagging | openedx_catalog, matching how components | containers is already written). Verify with lint-imports.
• Tests. In tests/openedx_learning/applets/cbe/test_api.py, cover the three parameter states, request-order preservation including a reordered request, duplicate collapsing to first position, a well-formed key matching no CourseRun, criteria present but none in scope (zero numerator, non-zero denominator), a competency with no criteria at all (both zero), archived criteria and archived groups excluded from the returned rows and from both counts, and a parent competency whose sub-competencies have criteria of their own. In tests/openedx_learning/applets/cbe/test_rest_api.py, cover trailing and doubled commas, a value of only commas, a malformed key, 101 entries rejected with the limit named, and a 403 that discloses neither count. In tests/openedx_catalog/test_api.py, cover the resolver's empty input, unknown key, and duplicate key cases.
• Companion tickets. Wiring the authoring frontend to this parameter is #683. Resolving which course runs are in view, including title search, date filtering, and paging, is #669 and #670.

Files to create and modify Modified files

• Context #681 defines the endpoint and the get_competency_criteria_tree function this ticket extends; this work is additive to both and adds no new endpoint.
• #613 (the CompetencyCriteriaGroup and CompetencyCriterion models) and #716 (their archived column) must both land before this work can start.
• #676 holds the backend design reasoning behind scoping by caller-supplied course keys rather than by a server-side course query. A follow-up amendment to ADR 0002's retrieval-scope and pagination wording is tracked on #676 and is not part of this ticket's work; the ADR's current text predates this design.
• docs/openedx_learning/decisions/0002-competency-criteria-model.rst for the criteria data model, and Decision 5 for the existing indexes this access pattern relies on.
• Prior art for the query-parameter serializer pattern: src/openedx_tagging/rest_api/v1/serializers.py and src/openedx_tagging/rest_api/v1/views.py. Prior art for a comma-separated list parameter: get_object_tag_counts in src/openedx_tagging/api.py.
• src/openedx_catalog/api.py's module docstring states that the catalog app provides no "list courses" methods because course visibility is not modeled there. That is why the caller resolves which course runs are in view and passes their keys in.
• src/openedx_catalog/models/course_run.py's class docstring is the rule against ever exposing CourseRun's integer primary key in an API, which is why the parameter and the response both speak in course keys.