# OSHUN V1 Metis `CourseBuild` Contract

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.
