Eve library

OSHUN V1 Metis `CourseBuild` Contract

Spec

Revision 1

On this page

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.md
  • docs/releases/v1/specs/metis-grounding-pack-contract.md
  • docs/releases/v1/reports/metis-subsystem-ownership-matrix.md
  • docs/releases/v1/reports/metis-v1-scorecard.md
  • docs/releases/v1/specs/todos.md
  • services/metis/src/metis/schemas/course.py
  • services/metis/src/metis/services/admin_service.py
  • apps/metis/web/src/lib/authoring-data.ts
  • apps/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:

  1. LearningSourceBundle governs source scope and rights posture.
  2. GroundingPack governs claim-to-evidence support.
  3. CourseBuild governs how Metis assembles educational structure from those governed inputs.
  4. PublicationPackage governs 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#

ts
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#

ts
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#

ts
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#

ts
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 CourseBuild may exist in draft without finalized grounding refs.
  • A CourseBuild may not be release-ready if any required source bundle or grounding pack ref is not approved.

3.5 Modules#

ts
interface CourseBuildModule {
  id: CourseBuildModuleId;
  title: string;
  description: string | null;
  order: number;
  estimatedMinutes: number | null;
  isPublished: boolean;
  lessons: CourseBuildLesson[];
}

3.6 Lessons#

ts
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:

  • sourceBundleIds declare the source scope the lesson depends on.
  • groundingPackIds declare the evidence packages supporting the lesson’s learner-facing claims.

3.7 Assessments#

ts
interface CourseBuildAssessment {
  id: CourseBuildAssessmentId;
  title: string;
  description: string | null;
  type: 'quiz' | 'exam' | 'assignment' | 'practice';
  isPublished: boolean;
  questionCount: number;
  groundingPackIds: string[];
}

3.8 Readiness#

ts
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#

ts
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:

  1. readiness.lessonCount equals the total number of lessons across all modules.
  2. readiness.assessmentCount equals the number of attached assessments.
  3. readiness.sourceCoveragePercent, groundedLessonPercent, assessmentSupportPercent, and releaseReadinessPercent are integers from 0 to 100.
  4. publishedLessonCount <= lessonCount.
  5. publishedAssessmentCount <= assessmentCount.
  6. If course.status === 'published', publicationReviewRequired must still be true and readiness.blockers must be empty for a release-ready build.
  7. A published lesson must not claim grounding support unless its groundingPackIds are 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#

json
{
  "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:

  1. CourseBuild is defined as the canonical Metis-owned educational assembly contract.
  2. It references, rather than duplicates, the source-bundle and grounding-pack layers.
  3. Its readiness metrics and blockers map directly to the current grounded-build and publication review seams.