docs: add ADR for persisted competency deletability signal

[mgwozdz-unicon]

Why

openedx-core#655 proposes how to enforce the
delete/edit guardrails ADR-0002 and ADR-0003 already decided for competency taxonomy data, and
raised surfacing a deletable signal on the relevant GET endpoints so Studio can disable/warn on
the delete action instead of only discovering the block from a failed request. How to compute that
signal turned into a real design question (read-time cost vs. write-path complexity), so it gets
its own ADR rather than staying an implementation detail of that issue.

Summary

• Adds ADR 0005: persist a deletable boolean on the five delete-protected models (Taxonomy,
  CompetencyTaxonomy, Tag, ObjectTag, CompetencyCriteriaGroup, CompetencyCriteria) rather
  than computing it per-request or caching it.
• The flip is one-directional (True to False only, never back), set synchronously in the same
  transaction as the learner-status write that triggers it. No cache-invalidation logic needed as a
  result.
• No backfill migration needed: the referencing learner-status tables are new, so no existing row
  can already be non-deletable.
• Enforcement stays on the write path; the persisted field is a UX convenience, not the guardrail
  itself.
• Rejects two alternatives considered in [Arch] Implementation approach for competency data delete/edit guardrails #655: a per-request Exists()/OuterRef() annotation, and
  caching that computed value with a TTL.

Related to #655.

[openedx-webhooks]

Thanks for the pull request, @mgwozdz-unicon!

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.

Details

---

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.

[bradenmacdonald]

If we really need to show per-tag deletable status in the taxonomy tag list / editor UI, and that deletability is primarily related to this criteria (whether or not any related learner status exists in StudentCompetencyStatus,
StudentCompetencyCriteriaGroupStatus, or StudentCompetencyCriteriaStatus), then I think this is a good approach to solving the problem efficiently. However, I'm not sure either of those assumptions are true. And I'm not a big fan of the vagueness of "deletable" nor how it's not really clear where/why/when that field is set, unless you happen to be familiar with the competency requirements.

---

I would personally prefer a simpler approach. Before I get to that, I want to review the status quo:

First of all, note that in the taxonomy UI, we already show how many times each tag is used:

If the usage count is > 0, we probably want to discourage deleting that tag in general (but we could still allow it, unless it's used for learner status of CBE). If the usage count is 0, we definitely don't care if it gets deleted or not, and there's no need to check anything else. So already we see one potential point of confusion: the most basic criteria for "how deletable is this tag?" has to do with usage_count, not the value of the proposed deletable field.

Second of all, we don't have a UI that supports selecting and deleting multiple tags at once. You must choose one tag to delete, at which point this dialog displays:

My suggestion is that when we load that dialog, whether it's deleting one tag or a future version that allows you to select multiple tags then click delete, we can make an is_deletable REST API request to the server, which hard-deletes the selected tag + associated ObjectTags, and then immediately rolls back the transaction without committing. That will instantly and performantly tell you whether the tag is used in any foreign keys that are blocking the delete via ON DELETE RESTRICT.

• No new field required, no potential confusion around what deletable is or when/how it gets set
• No need to keep deletable in sync with status of external tables.
• Clearly explains to the user why something cannot be deleted, rather than just disabling some "Delete" menu entries
• No expensive per-row Exists() join/subquery.
• Automatically works with any other Django apps that need the same functionality and use foreign keys to ObjectTag/Tag with ON DELETE RESTRICT.

However, this approach only works for Tag/Taxonomy, and I'm not sure how good a fit it is for the other things.

[mgwozdz-unicon]

Thanks for taking a look and reviewing @bradenmacdonald. The is_deletable dry-run (attempt the real delete in a transaction, roll back, let ON DELETE RESTRICT do the work) is appealing: no new field, no sync question to maintain, and it gets you the specific blocking record for free.

Before we commit to it, there's a dependency worth flagging. @jesperhodge's #657 (still unreviewed, per its own description) proposes moving the learner-status tables (StudentCompetencyStatus, ...GroupStatus, ...CriteriaStatus, plus their HISTORY siblings) onto a separate database alias for scale, and updates ADR-0002 Decision 6/7 so those tables reference the definition tables (Tag, CompetencyCriteriaGroup, CompetencyCriteria, etc.) via logical foreign keys with no database-level constraint, declared that way from day one so the schema doesn't have to change if those tables do move later. Delete protection ends up enforced in application code instead of a DB constraint as a result.

If that design lands, there's no ON DELETE RESTRICT to trial against for any of the five models this ADR covers, not just the ObjectTag case you already flagged, since the constraint is absent from the start rather than only once the tables are physically split out. A hard delete would just succeed at the DB layer regardless of learner status, so the dry-run wouldn't tell us anything reliable.

Given that, I'd like to get consensus on approach here before changing the ADR much further, since which mechanism is even viable depends on how #657 resolves. Curious whether either of you sees a way to keep an FK-based check under a cross-database status table design. If not, I see two app-code options worth weighing: keep this ADR's persisted deletable field, or drop it and run a fresh existence check against the status tables only at delete time. The ADR already rules out that same existence check on every list/detail read for its per-request JOIN cost, but running it once, only at the point of deletion, wouldn't have that cost.

[bradenmacdonald]

@mgwozdz-unicon Ah, good call out. Yep, let's hold off on a decision until we know which way that is going. I'd definitely prefer to land on an approach that uses foreign key constraints as much as possible, but I guess we have to do what's performant.

[jesperhodge]

@bradenmacdonald @mgwozdz-unicon see if you agree with my comment on 657 here.
If you don't see a problem with that, it would mean:

• The only table using a db alias and router is StudentCompetencyCriteriaStatusHistory. The non-history active StudentCompetencyCriteriaStatus table as well as all the other tables mentioned here (group status, mastery) will stay normal, and can have normal foreign keys.
• Be mindful of large read / write operations on the StudentCompetencyCriteriaStatus table as it's huge and we want to avoid blocking the db. Potentially we can specify using a read replica, if available, like on the StudentModule table.
• All very large tables in edx-platform, like StudentModule, avoid db constraints to users. For example, in StudentModule, student = models.ForeignKey(User, db_index=True, db_constraint=False, on_delete=models.CASCADE) specifies db_constraint=False. I assume there is a good reason for that, so we probably want to follow that principle.

[bradenmacdonald]

@jesperhodge Ok, so if History is the only table that's in a separate DB, then we can still expect that the StudentCompetencyCriteriaStatus table and others have normal foreign keys and will block the deletes using ON DELETE RESTRICT rules, right? That's great, it gives us more options here.