Competency Framework Model

Intent

Define the concrete, implementation-ready competency model used in the initial platform architecture.

This model is core architecture, not an optional extension. Updated for ADR-0018: competency nodes are durable referents; statement text lives on per-edition revisions; associations use the CASE vocabulary and may cross frameworks.

Design Goals

• Represent domain-agnostic competencies with language-learning specialization support
• Support framework versioning without corrupting historical evidence
• Keep longitudinal mastery history attached to a stable object across framework editions
• Make crosswalks and framework translations first-class core features
• Support multiple evidence sources (assessment, rubric, instructor validation, external import)
• Keep person competency state derivable and auditable

Canonical Entity Set

Framework Structure

• competency_framework Top-level framework descriptor and owner metadata. Also carries the framework-stable CASE CFDocument descriptive fields (ADR-0018 neutral columns): framework_type, official_source_url, publisher, description, language, and a license_id reference into competency_license.

• competency_framework_version Immutable published edition boundary for framework semantics. Carries the per-edition CASE CFDocument lifecycle fields as descriptive metadata (ADR-0018; the frozen snapshot is unaffected): adoption_status, status_start_date, status_end_date, notes.

• competency_node Durable competency referent (ADR-0018): framework-scoped, identified by a stable node_key, persisting across editions. Longitudinal mastery history, content alignments, and external framework identifier bindings (e.g. CASE GUIDs/URIs, held in boundary mapping tables) attach here — never to a revision.

• competency_node_revision Per-edition statement text and descriptive metadata for a durable node: title, description, level hint, plus the neutral descriptive set absorbed from CASE (coding scheme, node type, language, abbreviated statement, alternative label, list enumeration, concept keywords, notes, status start/end dates) and a revision_meta payload for the rest. References into the CFDefinitions registries (item_type_id, concept_id, license_id) carry the CASE CFItemTypeURI / conceptKeywordsURI / licenseURI on export. One revision per node per edition. Education levels and subjects link through junctions to the neutral vocabulary registries (below), never as free strings.

• education_level / subject (neutral vocabulary registries) Platform-wide registries serving every boundary (case-competency-v1 decision 10): CASE educationLevel/CFSubjects and OneRoster grades/subjects reconcile onto the same rows. Junctions: competency_node_revision_education_level, competency_node_revision_subject (here), plus learning_container_*/offering_* junctions on the OneRoster side.

• competency_association Typed, directed relationship between durable nodes using the CASE association vocabulary: is-child-of, is-peer-of, is-part-of, exact-match-of, precedes, is-related-to, replaced-by, exemplar, has-skill-level, is-translation-of. Associations may cross frameworks — crosswalks and translations are core features. Edition-structural associations (e.g. an edition’s is-child-of tree) carry the asserting competency_framework_version_id; platform-level assertions carry none. sequence_number orders siblings for display; notes and an association_grouping_id reference (→ competency_association_grouping) carry the CASE CFAssociation notes / CFAssociationGroupingURI on export.

• competency_license / competency_item_type / competency_concept / competency_association_grouping (CASE CFDefinitions registries) Neutral, framework-agnostic definition registries (ADR-0018; CASE-PROV-2). Authored frameworks reference them by FK from the framework / revision / association; the CASE provider export gathers the ones an edition references into the package’s CFDefinitions (alongside CFSubjects, which reuse the neutral subject registry). CASE vocabulary stays at the export boundary — these columns are neutral, and the wire uri is synthesized at export time, never stored.

Alignment

• competency_alignment Time-aware mapping from learning_unit and assessment_definition to durable competency nodes. Alignments survive new framework editions; an optional competency_framework_version_id records the edition whose statement text the alignment was authored against (reproducibility context).

Person Evidence and State

• person_competency_evidence Append-oriented evidence records contributing to competency inference. Evidence references the durable node and the framework version active at capture time — psychometric pooling and research reproducibility need the edition.

• person_competency_state Derived, current state for person + durable competency node, spanning framework editions (the longitudinal fix ADR-0018 exists for). Contributing editions live in the evidence rows and derivation_meta.

• person_competency_state_transition Optional explicit transition ledger for explainability and replay diagnostics.

Relationship Model

• One framework has many immutable editions (versions).
• One framework has many durable nodes; a node has at most one revision per edition.
• A revision’s framework version must belong to its node’s framework — not FK-enforceable (the two FKs land on different parents); writers assert it (data-invariants.md #17).
• Associations relate durable nodes and may cross frameworks; within-edition structure is scoped by the asserting edition on the association row.
• Alignments reference durable nodes so historical unit/assessment mappings remain valid as editions advance; the effective window provides time-awareness.
• Evidence references person, durable node, capture-time edition, and source event/artifact.
• Current state is computed from evidence under policy rules and linked to latest contributing evidence IDs.

Competency States

Baseline state vocabulary:

• not-started
• in-progress
• demonstrated
• mastered
• regressed

State meaning:

• demonstrated means minimum threshold reached with sufficient evidence.
• mastered means stronger evidence confidence and/or repeated demonstration.
• regressed captures negative evidence after a stronger prior state.

Evidence Taxonomy

Supported evidence classes:

• assessment-attempt
• rubric-evaluation
• instructor-attestation
• observation-event
• external-import

Required evidence metadata:

• Source type and source ID
• Timestamp and actor/provenance
• Confidence or weight signal (if policy requires)
• Framework version context (capture-time edition)

Inference Policy Baseline

The first implementation should support policy-driven state derivation:

• Threshold-based rule sets per competency
• Optional recency decay for long-lived skills
• Minimum evidence count requirements
• Policy versioning with deterministic recompute support

Inference policy is explicit configuration, never hidden in application code paths.

Versioning Rules

• Published framework editions are immutable.
• New meaning requires a new edition; the durable node threads identity across editions via new revisions. A node whose meaning genuinely changes identity gets a NEW durable node (linked replaced-by), not a revised statement.
• Evidence remains bound to the edition active at capture time.
• Alignments bind durable nodes and can be superseded for future learning flows without rewriting old evidence.

Boundary Mapping (CASE and beyond)

• CASE 1.1 is a totality-gated boundary adapter (ADR-0018), never the core model: staging snapshots, reconcile service, CASE GUIDs/URIs in boundary mapping tables bound to durable nodes. CASE terms (CFDocument, CFItem, CFAssociation, fullStatement) stay at the @conform-ed/contracts boundary.
• The CASE consumer is implemented (case-competency-v1, 2026-06-13): CFPackage file import → case_* snapshots/mappings → framework/edition/node/revision/ association reconcile; content hash decides edition reuse vs a new edition; node continuity flows through case_item_mapping GUIDs.
• Imported framework updates create new editions with node continuity established through the CASE GUID bindings.
• Emergent-authored frameworks gain a provider/export path as CASE CFPackages (case-competency-v1, implemented 2026-06-13): export-service.ts projects a framework edition → CFPackage (the consumer’s inverse: fullStatement ← title, CFItem/CFAssociation identifiers = durable core uuids, root associations synthesized to the CFDocument), exposed at GET /workflow/case/frameworks/:id/export and gated by the round-trip totality test (import → export → re-import → compare cores), the ADR-0012 CI pattern.
• xAPI statements should include competency context extensions where applicable.
• CLR exports should include competency-linked achievements/evidence where profile supports it.

Query and Indexing Guidance

Minimum index families:

• person_id + competency_node_id (state uniqueness)
• competency_node_id + captured_at
• source_type + source_id
• competency_framework_version_id on revisions (edition reads)
• association from/to + type (uniqueness) and reverse to_node_id lookups

These indexes support learner profile reads, recomputation, and export jobs.

Implementation Anchors

• Domain contracts and inference policy schemas: packages/domain
• Relational tables and constraints: packages/db (schema/competency-framework.ts)
• Offline projections for learner progress views: packages/offline-data
• Inference orchestration and recomputation jobs: apps/api

Implementation status (2026-06-13)

• Built: the full framework structure — competency_framework, competency_framework_version, durable competency_node, competency_node_revision, competency_association, and the neutral education_level/subject registries — is populated by the CASE consumer and read back by the CASE provider/export (case-competency-v1, validated by the round-trip totality gate).
• Schema-only (no application writers yet): the person-mastery surface — person_competency_evidence, person_competency_state, and competency_alignment (Learning Unit / Assessment → node). The tables and erasure declarations exist, but the evidence-capture → state-derivation inference engine and the alignment-authoring path are unbuilt; the Open Decisions below gate that work and resolve when it starts.

Open Decisions

1. Whether person_competency_state_transition is mandatory in v1 or introduced in v1.1
2. Whether recency decay is enabled by default or profile-specific
3. How deeply hierarchy semantics (tree vs DAG) are constrained in initial validation