Data Invariants

Intent

Capture non-negotiable model constraints that must hold across schema, APIs, sync, and integrations.

These invariants are implementation requirements, not optional guidelines.

Person identity durability A person identity must not be destroyed when affiliations, memberships, or roles change.
Person history continuity Learning history remains linked to the same person across institutions and role transitions.
Multi-role compatibility A person may hold multiple active roles in overlapping time windows.
External identity traceability Every external identity binding must include provider, external subject, and validity period.

Time-bounded participation Membership and role grants must support effective windows.
No hidden overwrites State transitions must preserve previous state in audit/event logs.
Event ordering semantics For a single aggregate, state transitions must be orderable and replay-safe.

Unified participation model Learner and teacher participation use the same membership abstraction.
Scoped visibility Access is granted through explicit membership/affiliation, never inferred from profile fields alone.
Contextual administration Organization context governs authorization but does not redefine person identity.

Attempt integrity An attempt belongs to exactly one person and one assessment definition.
Score traceability Final scores must reference attempt version and evaluation source.
Qualification provenance Every qualification award must reference definition, issuer context, and grant basis.

Versioned competency stability Published competency framework versions are immutable.
Evidence provenance completeness Competency evidence must include source, actor/provenance, and timestamp metadata.
Derived-state integrity Person competency state is derived from evidence and policy rules, not ad hoc overwrite. Current state attaches to the durable competency node and spans framework editions (ADR-0018); contributing editions live in the evidence rows and derivation metadata.
Node/revision framework coherence A competency node revision’s framework version must belong to its node’s framework. This is not FK-enforceable (the two FKs land on different parents); writers assert it and seeds/imports must uphold it.

Learner exportability Person-linked learning evidence must be exportable in standards-aligned formats.
Full attempt and feedback portability by default Person-portable exports include full attempt-level and feedback-level history unless explicitly redacted by policy.
Import reconciliation Imported records must preserve source provenance and avoid destructive merge semantics.

Core stability first Core entities should not accumulate specialization fields without review.
Typed extension for critical data High-value domain extensions must use typed extension tables/contracts.
Extension namespace ownership Every extension must declare namespace, owner, and versioning policy.

Offline-safe identity keys IDs must support deterministic reconciliation across Postgres and PGlite contexts.
Conflict visibility Conflict outcomes must be auditable and observable, not silent.
Convergence requirement Sync strategy must guarantee eventual convergence for supported mutation classes.

Use this checklist whenever changing model semantics:

If any answer is yes, document the exception and add compensating controls.