Status: Active
Date: April 10, 2026
Owners: OSHUN Metis Engineering, OSHUN Sophia, OSHUN Safety, OSHUN Product
Related:
docs/releases/v1/specs/metis-learning-source-bundle-contract.mddocs/releases/v1/specs/metis-grounding-pack-contract.mddocs/releases/v1/reports/metis-subsystem-ownership-matrix.mddocs/releases/v1/reports/metis-v1-scorecard.mddocs/releases/v1/specs/todos.mdservices/metis/src/metis/schemas/course.pyservices/metis/src/metis/services/admin_service.pyapps/metis/web/src/lib/authoring-data.tsapps/metis/web/src/lib/course-data.ts
1. Purpose#
This document defines the canonical CourseBuild contract for Metis V1.
CourseBuild is the educational assembly object that turns approved source
inputs and grounding inputs into a structured course artifact with:
- course metadata
- module and lesson structure
- assessment structure
- build-readiness metrics
- release-blocking state
- downstream publication references
This is the first contract in the chain that Metis fully owns as an educational product object.
2. Contract Role in the Metis Pipeline#
Order of responsibility:
LearningSourceBundlegoverns source scope and rights posture.GroundingPackgoverns claim-to-evidence support.CourseBuildgoverns how Metis assembles educational structure from those governed inputs.PublicationPackagegoverns whether that build is safe to ship broadly.
CourseBuild must reference source and grounding inputs. It must not silently
replace them.
3. Canonical Contract#
3.1 Identity#
type CourseBuildId = `cb_${string}`;
type CourseBuildVersionId = `cbv_${string}`;
type CourseBuildModuleId = `cbm_${string}`;
type CourseBuildLessonId = `cbl_${string}`;
type CourseBuildAssessmentId = `cba_${string}`;
3.2 Top-Level Shape#
interface CourseBuild {
id: CourseBuildId;
versionId: CourseBuildVersionId;
course: CourseBuildCourse;
sourceBundleRefs: CourseBuildSourceBundleRef[];
groundingPackRefs: CourseBuildGroundingPackRef[];
modules: CourseBuildModule[];
assessments: CourseBuildAssessment[];
readiness: CourseBuildReadiness;
governance: CourseBuildGovernance;
createdAt: string;
updatedAt: string;
}
3.3 Course Metadata#
interface CourseBuildCourse {
courseId: string;
title: string;
slug: string;
description: string | null;
shortDescription: string | null;
category: string;
difficulty: 'beginner' | 'intermediate' | 'advanced' | 'expert';
thumbnailUrl: string | null;
tags: string[];
estimatedHours: number | null;
status: 'draft' | 'review' | 'published' | 'archived';
ownerId: string;
ownerName: string | null;
}
3.4 Source and Grounding References#
interface CourseBuildSourceBundleRef {
bundleId: string;
bundleVersionId: string;
approvalStatus: 'approved' | 'review_only' | 'blocked';
}
interface CourseBuildGroundingPackRef {
groundingPackId: string;
groundingPackVersionId: string;
scopeKind:
| 'course_lesson'
| 'assessment_question'
| 'tutor_answer'
| 'study_artifact'
| 'build_summary';
approvalStatus: 'approved' | 'partial' | 'unsupported' | 'revoked';
}
Reference rule:
- A
CourseBuildmay exist in draft without finalized grounding refs. - A
CourseBuildmay not be release-ready if any required source bundle or grounding pack ref is not approved.
3.5 Modules#
interface CourseBuildModule {
id: CourseBuildModuleId;
title: string;
description: string | null;
order: number;
estimatedMinutes: number | null;
isPublished: boolean;
lessons: CourseBuildLesson[];
}
3.6 Lessons#
interface CourseBuildLesson {
id: CourseBuildLessonId;
title: string;
description: string | null;
contentType: 'text' | 'video' | 'interactive' | 'quiz' | 'code_exercise';
content: string | null;
order: number;
durationMinutes: number | null;
isPublished: boolean;
isFreePreview: boolean;
sourceBundleIds: string[];
groundingPackIds: string[];
}
Lesson rule:
sourceBundleIdsdeclare the source scope the lesson depends on.groundingPackIdsdeclare the evidence packages supporting the lesson’s learner-facing claims.
3.7 Assessments#
interface CourseBuildAssessment {
id: CourseBuildAssessmentId;
title: string;
description: string | null;
type: 'quiz' | 'exam' | 'assignment' | 'practice';
isPublished: boolean;
questionCount: number;
groundingPackIds: string[];
}
3.8 Readiness#
interface CourseBuildReadiness {
lessonCount: number;
publishedLessonCount: number;
assessmentCount: number;
publishedAssessmentCount: number;
sourceCoveragePercent: number;
groundedLessonPercent: number;
assessmentSupportPercent: number;
tutorSpilloverCount: number;
releaseReadinessPercent: number;
blockers: string[];
}
Readiness rule:
- These metrics are the canonical build-readiness summary that current Metis grounded-build and publication-package review queues approximate separately.
3.9 Governance#
interface CourseBuildGovernance {
educationalOwner: 'metis';
sourceOfRecordForSources: 'sophia';
groundedBuildReviewRequired: boolean;
publicationReviewRequired: boolean;
auditTrailRequired: boolean;
}
4. Required Invariants#
The contract is invalid if any of the following are false:
readiness.lessonCountequals the total number of lessons across all modules.readiness.assessmentCountequals the number of attached assessments.readiness.sourceCoveragePercent,groundedLessonPercent,assessmentSupportPercent, andreleaseReadinessPercentare integers from0to100.publishedLessonCount <= lessonCount.publishedAssessmentCount <= assessmentCount.- If
course.status === 'published',publicationReviewRequiredmust still be true andreadiness.blockersmust be empty for a release-ready build. - A published lesson must not claim grounding support unless its
groundingPackIdsare non-empty or its support posture is explicitly partial or unsupported elsewhere.
5. Mapping to Existing Runtime Truth#
CourseBuild is derived from already-live Metis seams:
CourseBuild field |
Existing seam |
|---|---|
course.*, modules.*, lessons.* |
services/metis/src/metis/schemas/course.py and normalized course data in apps/metis/web/src/lib/course-data.ts |
assessments.* |
authoring flow assessment drafts plus live assessment publish state |
readiness.sourceCoveragePercent, groundedLessonPercent, assessmentSupportPercent, tutorSpilloverCount |
grounded-build metrics and operator build-evidence rows in services/metis/src/metis/services/admin_service.py |
readiness.blockers |
grounded-build and publication-package blocker derivation in admin_service.py |
releaseReadinessPercent |
publication-package review metric calculation in admin_service.py |
| lesson and assessment assembly rules | apps/metis/web/src/lib/authoring-data.ts and the live create/publish flow in apps/metis/web/src/app/create/page.tsx |
6. Downstream Consumer Rules#
6.1 Authoring#
The Metis authoring surface should create and edit draft projections of
CourseBuild. It should not maintain an incompatible parallel structure for
modules, lessons, and assessments.
6.2 Admin Review#
The grounded-build queue and publication-package queue should summarize
CourseBuild.readiness, but they are review projections, not replacements for
the build contract.
6.3 Learner Runtime#
The learner web app may consume a reduced course projection, but that projection
must remain compatible with the underlying CourseBuild structure for modules,
lessons, and assessments.
7. JSON Example#
{
"id": "cb_course-1",
"versionId": "cbv_course-1_2026-04-10T00:00:00Z",
"course": {
"courseId": "course-1",
"title": "Introduction to Machine Learning",
"slug": "introduction-to-machine-learning",
"description": "A practical entry into core machine learning ideas.",
"shortDescription": "Learn core ML concepts with grounded examples.",
"category": "Computer Science",
"difficulty": "beginner",
"thumbnailUrl": null,
"tags": ["machine-learning", "classification"],
"estimatedHours": 12,
"status": "review",
"ownerId": "instructor-1",
"ownerName": "Amara Osei"
},
"sourceBundleRefs": [
{
"bundleId": "lsb_course-1",
"bundleVersionId": "lsbv_course-1_2026-04-10T00:00:00Z",
"approvalStatus": "approved"
}
],
"groundingPackRefs": [
{
"groundingPackId": "gpk_course-1_lesson-1",
"groundingPackVersionId": "gpkv_course-1_lesson-1_2026-04-10T00:00:00Z",
"scopeKind": "course_lesson",
"approvalStatus": "approved"
}
],
"modules": [
{
"id": "cbm_module-1",
"title": "Foundations",
"description": "Core supervised learning concepts.",
"order": 0,
"estimatedMinutes": 90,
"isPublished": true,
"lessons": [
{
"id": "cbl_lesson-1",
"title": "Bias mitigation foundations",
"description": "Core grounded lesson on bias and evaluation.",
"contentType": "text",
"content": null,
"order": 0,
"durationMinutes": 20,
"isPublished": true,
"isFreePreview": false,
"sourceBundleIds": ["lsb_course-1"],
"groundingPackIds": ["gpk_course-1_lesson-1"]
}
]
}
],
"assessments": [
{
"id": "cba_assessment-1",
"title": "ML Foundations Quiz",
"description": "Checks core course understanding.",
"type": "quiz",
"isPublished": true,
"questionCount": 8,
"groundingPackIds": ["gpk_course-1_assessment-1"]
}
],
"readiness": {
"lessonCount": 6,
"publishedLessonCount": 5,
"assessmentCount": 1,
"publishedAssessmentCount": 1,
"sourceCoveragePercent": 83,
"groundedLessonPercent": 78,
"assessmentSupportPercent": 100,
"tutorSpilloverCount": 1,
"releaseReadinessPercent": 81,
"blockers": [
"Escalated tutoring sessions need grounding follow-up before approval."
]
},
"governance": {
"educationalOwner": "metis",
"sourceOfRecordForSources": "sophia",
"groundedBuildReviewRequired": true,
"publicationReviewRequired": true,
"auditTrailRequired": true
},
"createdAt": "2026-04-10T00:00:00Z",
"updatedAt": "2026-04-10T00:00:00Z"
}
8. Non-Goals#
CourseBuild does not define:
- raw source extraction
- claim-level evidence structure
- final publication approval envelope
- media-render packaging
- tutor runtime orchestration
Those belong to adjacent contracts.
9. Completion Rule for V1-MET-051#
V1-MET-051 is complete only when:
CourseBuildis defined as the canonical Metis-owned educational assembly contract.- It references, rather than duplicates, the source-bundle and grounding-pack layers.
- Its readiness metrics and blockers map directly to the current grounded-build and publication review seams.