# Canonical Curriculum Alpha Surface Open these first: - Customer website: https://platform3-andymontgomery-9773s-projects.vercel.app/curriculum/alpha/customer_website - Data dictionary: https://platform3-andymontgomery-9773s-projects.vercel.app/curriculum/alpha/data_dictionary - Architecture: https://platform3-andymontgomery-9773s-projects.vercel.app/curriculum/alpha/architecture - Surface QC: https://platform3-andymontgomery-9773s-projects.vercel.app/curriculum/alpha/surface_qc - Integration proof: https://platform3-andymontgomery-9773s-projects.vercel.app/curriculum/alpha/integration - Convergence answer key: https://platform3-andymontgomery-9773s-projects.vercel.app/curriculum/alpha/integration/convergence.json - Implementation API: https://platform3-andymontgomery-9773s-projects.vercel.app/curriculum/alpha/implementation/api ## Credentials Demo: ```sh export CURRICULUM_BASE_URL="${CURRICULUM_BASE_URL:-https://platform3-andymontgomery-9773s-projects.vercel.app/curriculum/alpha/implementation/api}" export CURRICULUM_TOKEN="$(curl -fsSL -X POST "$CURRICULUM_BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')" ``` Real or reviewer tenant: ```sh export CURRICULUM_BASE_URL="${CURRICULUM_BASE_URL:?set by operator}" export CURRICULUM_TOKEN="${CURRICULUM_TOKEN:-${CURRICULUM_REVIEWER_JWT:?set by operator}}" ``` Never print, commit, or persist bearer tokens. ## Storage Model Authoritative storage: `case.cf_document`, `case.cf_item`, `case.cf_association`, `alpha.standards_source_release`, `alpha.standards_source_row_binding`, `alpha.knowledge_component`, `alpha.knowledge_component_version`, `alpha.kc_prerequisite`, `alpha.kc_relation`, `alpha.standard_kc_map`. There are no Alpha course/component, renderer, alias, external-course, track, lesson, or course-component-member base tables in the deployed compatibility model. The governed KC and standards-lineage Alpha tables named above are real authorities; derived `alpha.curriculum_*` component views remain CASE-backed read conveniences. Agent-facing rule: read the API's typed fields, especially `kind`, `target_ref`, `renderer_ref`, compatibility `renderer_kind`, `passing_criteria_ref`, and remediation `reason`. Do not inspect CASE JSON payload internals to recover app facts. ## Public Names | Alpha name | Kind | Surface source | Rule | |---|---|---|---| | `standards_framework` | view | case.cf_document, exposed through the standards-frameworks endpoint | Frozen imported standards framework. Alpha names the document plainly but does not move or copy it. | | `standard` | view | case.cf_item standard rows, exposed as standards by the surface | Publisher standards are read as standards. They link to KCs only through alpha.standard_kc_map. | | `knowledge_component` | governed registry | alpha.knowledge_component + alpha.knowledge_component_version | Create with stored_as=alpha.knowledge_component and definition, then use only the returned canonical kc_id UUID for create replay, read, version, retire, graph, scope, remediation, standards-map, and Content-attribution operations. Optional source_kc_id is creation provenance only and never resolves an identity; HTTP retries reuse the original Idempotency-Key. Semantic edits append through /versions; identity publication is If-Match protected and never firms. | | `curriculum_component` | view | case.cf_item component rows with a storage-validated Alpha kind property | The single component table is CASE CFItem; apps read the returned kind, publication_status, and retired_at fields and never inspect CASE payload internals. DELETE retires incident CASE associations before the component tombstone and never cascade-retires neighboring components. | | `track` | derived view | case.cf_item component row returned with kind=track | Flat track view is derived. The authoritative row is still CFItem. | | `course` | derived view | case.cf_item component row returned with kind=course | Flat course view is derived. Aggregate scope_kcs and expected_xp are derived from expected-XP-bearing leaves/fallbacks and never double-count a container with descendants. | | `lesson` | derived view | case.cf_item component row returned with kind=lesson | Lesson view selects acquisition components. Ordinary scoped lessons preserve the full non-empty producer-authored KC cluster; an exact content-bearing lesson may instead preserve scope_kc_refs=[] plus kc_scope_decision=authoritative_no_kc and contributes no KC/mastery evidence. Platform3 does not impose one-KC-per-lesson grain or synthesize a KC for explicit absence. | | `component_containment` | view | case.cf_association isChildOf relationship | isChildOf is component containment only; sequenceNumber orders siblings. KCs have no containment tree. | | `kc_prerequisite` | governed registry relation | alpha.kc_prerequisite, exposed through GET/POST /alpha/curriculum/v1/kc-prerequisites | Exact active tenant-owned registry UUID endpoints enter the sole forward prerequisite DAG; cycles are rejected at write time. | | `kc_relation` | governed registry relation | alpha.kc_relation | Typed non-prerequisite KC graph semantics live here. It is not a containment tree and never substitutes for alpha.kc_prerequisite. | | `kc_standard_map` | governed registry relation | alpha.standard_kc_map | Exact registry KCs map to frozen release-and-row-pinned CASE standards here, never through CASE isPartOf. | | `framework_alignment` | view | stock CASE alignment associations | Cross-framework alignment remains a stock CASE association. No Alpha alias table exists. | | `content_reference` | validated component property | target_ref plus renderer_ref on a CASE-backed component/member | Curriculum references one immutable Content version by target_ref {content_id, content_version_id, content_kind}. Content-owned release eligibility is checked at authoring and again at launch; Curriculum never substitutes latest, caches a verdict, or copies producer evidence. renderer_kind is a compatibility alias only, and registration proves routing validity rather than rendering support. | | `gate_contract` | validated component property | passing_criteria_ref plus on_fail on a gated CASE-backed component | passing_criteria_ref and on_fail live on the gated component and point to Policy/remediation behavior. | | `standards_framework_import` | surface command | POST /alpha/curriculum/v1/standards-frameworks/import | Accepts source-shaped standards framework and standard rows and normalizes server-side into stock CASE rows. | | `timeback_source_ingest` | surface command | POST /alpha/curriculum/v1/ingest/timeback-course-refs | Accepts source-shaped TimeBack course references plus ordered unit/lesson component rows, stages deterministic CASE identities as drafts, verifies the complete intended tree, and publishes bottom-up with the course root last. Content remains flat and does not imply lesson order. | ## Endpoint Families ```text POST /dev/mint?tenantId=demo POST /alpha/curriculum/v1/components GET /alpha/curriculum/v1/components/{componentId} PATCH /alpha/curriculum/v1/components/{componentId} POST /alpha/curriculum/v1/components/{componentId}/repoint DELETE /alpha/curriculum/v1/components/{componentId} POST /alpha/curriculum/v1/kcs GET /alpha/curriculum/v1/kcs GET /alpha/curriculum/v1/kcs/{kcId} POST /alpha/curriculum/v1/kcs/{kcId}/versions GET /alpha/curriculum/v1/kcs/{kcId}/versions GET /alpha/curriculum/v1/kcs/{kcId}/versions/{versionId} PATCH /alpha/curriculum/v1/kcs/{kcId} POST /alpha/curriculum/v1/kc-review-decisions GET /alpha/curriculum/v1/kc-review-decisions POST /alpha/curriculum/v1/kc-firming-events GET /alpha/curriculum/v1/kc-firming-events POST /alpha/curriculum/v1/courses/{courseId}/approvals GET /alpha/curriculum/v1/courses/{courseId}/approvals POST /alpha/curriculum/v1/kc-prerequisites GET /alpha/curriculum/v1/kc-prerequisites DELETE /alpha/curriculum/v1/kcs/{kcId} POST /alpha/curriculum/v1/associations GET /alpha/curriculum/v1/associations GET /alpha/curriculum/v1/associations/{associationId} PATCH /alpha/curriculum/v1/associations/{associationId} GET /alpha/curriculum/v1/standards-frameworks GET /alpha/curriculum/v1/standard-kc-maps POST /alpha/curriculum/v1/standards-frameworks/import GET /alpha/curriculum/v1/components GET /alpha/curriculum/v1/renderer-registry GET /alpha/curriculum/v1/components/{componentId}/tree GET /alpha/curriculum/v1/courses/{courseId}/next-lesson GET /alpha/curriculum/v1/tracks/{trackId}/placement-candidates GET /alpha/curriculum/v1/gates/{componentId} GET /alpha/curriculum/v1/gates/{componentId}/status GET /alpha/curriculum/v1/gates/{componentId}/next-form GET /alpha/curriculum/v1/gates/{componentId}/remediation POST /alpha/curriculum/v1/ingest/timeback-course-refs ``` ## Governed KC Authoring For Content Attribution And Mastery Gates Call `POST /alpha/curriculum/v1/kcs` with top-level `stored_as=alpha.knowledge_component`, `definition`, no CASE fields, and optional provenance-only `source_kc_id`. The registry rejects fields it cannot read back. Capture the returned canonical `kc_id`; only that exact active tenant-owned UUID is valid in `/kc-prerequisites`, Curriculum `scope_kc_refs`, remediation entries, `alpha.standard_kc_map`, or Content `/kc-tags`. `GET /alpha/curriculum/v1/kcs/{kcId}` accepts only that canonical UUID; no source-id or CASE fallback exists. Append semantic corrections with `POST /kcs/{kcId}/versions`, record the exact-version outcome through `/kc-review-decisions`, and publish only the mutable KC identity with its current ETag. After building the published course graph, call `POST /courses/{courseId}/approvals`; require a complete exact snapshot and course-approval firming evidence, then require `next-lesson` to echo the approval and lesson KC-version snapshot. Publication and assignment alone leave versions draft. Captured CASE KC rows and `alpha.kc_source_identity` are immutable migration evidence only, never active reads or aliases. Author a registry KC and use its canonical UUID; do not infer or copy a KC from a standard, lesson, title, source id, or whole gate scope. A Content test form may become a `bank_member` only after every embedded question carries at least one active governed tag. For PATCH component corrections and association resequencing on the hosted Platform3 surface, send the current `x-curriculum-etag` value in `X-Curriculum-If-Match` plus `Idempotency-Key`. Direct runtimes also accept standard `If-Match`. ## Typed Fields To Trust Use these fields directly. Do not recover them from text: - `kind`, `component_id`, `document_id`, `parent_component_id`, `position`, `depth`, and `stored_as` on component reads. - Exact `target_ref.content_id`, `target_ref.content_version_id`, and `target_ref.content_kind` plus `renderer_ref`, compatibility `renderer_kind`, `passing_criteria_ref`, and `on_fail` on gated/content-referencing components. Missing or ineligible exact versions fail closed; never resolve `latest_version_id` locally. - `registered_for_routing`, `verified_rendering`, `rendering_state`, `verified_scope`, and `capability_matrix_url` on renderer-registry rows. Never infer rendering from registration or accepted Content kinds. - `kc_id`, `current_version_id`, `kc_granularity`, `subject_id`, and `grade_ids` on exact registry KC reads. - `prerequisite_kc_id` and `dependent_kc_id` on `alpha.kc_prerequisite`; other typed KC semantics belong to `alpha.kc_relation`, never CASE containment. - `relationship_type`, `from_id`, `to_id`, and `position` on component/standards CASE associations. - `entry_policy_ref`, `results_owner`, and `source_state_refs` when placement, status, or next lesson reads cross into Results or Policy references. - `remediation_entries[].reason`, `assigned_kind`, `assigned_component_ref`, and `insert_before_gate_ref` on gate remediation reads. Read allowed values from `GET /` or the hosted data dictionary. This pack intentionally does not carry copied value tables. ## Boundary Rules - Curriculum owns the shared CASE-backed curriculum graph and reusable path/course structure. - Results owns `student_track_state`, `student_kc_state`, next-task selection, attempts, scores, gate passes, and report-card rollups. - Content owns questions, stimuli, tests, articles, media, interactives, external links, answer keys, and content-effectiveness rollups. - Events owns activity moments. - People and Orgs owns students, guides, schools, classes, and enrollments. - Policy owns thresholds, cut scores, retake rules, rewards, penalties, retention model, and school-day calendars. - Common Cartridge is transport generated on demand, not stored Curriculum.