# OSHUN V1 Metis `LessonAssetBundle` Contract

Status: Active

Date: April 10, 2026

Owners: OSHUN Metis Engineering, OSHUN Sophia, OSHUN Product, OSHUN Safety

Related:

- `docs/releases/v1/specs/metis-learning-source-bundle-contract.md`
- `docs/releases/v1/specs/metis-grounding-pack-contract.md`
- `docs/releases/v1/specs/metis-course-build-contract.md`
- `docs/releases/v1/reports/metis-v1-scorecard.md`
- `docs/releases/v1/specs/todos.md`
- `services/metis/src/metis/models/course.py`
- `services/metis/src/metis/schemas/course.py`
- `apps/metis/web/src/app/courses/[courseId]/page.tsx`
- `apps/metis/web/src/lib/course-data.ts`
- `apps/metis/web/src/lib/grounded-sources.ts`
- `libs/metis/integrations/src/yemaya-integration.ts`

## 1. Purpose

This document defines the canonical `LessonAssetBundle` contract for Metis V1.

`LessonAssetBundle` is the lesson-delivery contract that takes structured lesson
intent from `CourseBuild` and turns it into the publishable, learner-visible
asset package consumed by:

- lesson detail and syllabus rendering
- preview and enrolled lesson playback
- downloadable study artifacts attached to a lesson
- grounded source inspection and learner disclosure
- media and multimodal lesson delivery
- publication review and export packaging

If `CourseBuild` defines the educational structure, `LessonAssetBundle` defines
the concrete lesson payload that is actually delivered.

## 2. Contract Role in the Metis Pipeline

Contract order:

1. `LearningSourceBundle`
2. `GroundingPack`
3. `CourseBuild`
4. `LessonAssetBundle`
5. `PublicationPackage`

Responsibility rule:

- `LearningSourceBundle` governs approved source scope.
- `GroundingPack` governs learner-facing evidence support.
- `CourseBuild` governs course assembly and lesson intent.
- `LessonAssetBundle` governs lesson payload, renditions, media, attachments,
  and previewability.
- `PublicationPackage` governs cross-course release shipment.

`LessonAssetBundle` must not replace `CourseBuild` structure or source-of-truth
governance. It is a delivery layer that references those upstream objects.

## 3. Design Constraints

`LessonAssetBundle` must satisfy all of the following:

1. It must support the currently live Metis lesson modes: text, video,
   interactive, quiz, and code exercise.
2. It must distinguish authoring intent from learner delivery, so learner
   clients do not need to parse raw authoring blobs or infer preview rules.
3. It must support grounded-source disclosure and downloadable lesson artifacts
   without duplicating raw source-ingestion internals.
4. It must support multiple delivery renditions for the same lesson, including
   text, structured blocks, video, captions, overlays, worksheets, and future
   generated media.
5. It must make preview, publish, and fallback behavior explicit for shell, web,
   mobile, and export consumers.

## 4. Canonical Contract

### 4.1 Identity

```ts
type LessonAssetBundleId = `lab_${string}`;
type LessonAssetBundleVersionId = `labv_${string}`;
type LessonAssetId = `la_${string}`;
type LessonAttachmentId = `lat_${string}`;
```

Identity rule:

- The bundle ID is stable for the logical lesson-delivery object.
- The version ID changes whenever learner-visible lesson payloads, evidence, or
  previewability rules change.
- Asset IDs are stable per delivery asset inside the bundle when that asset
  remains materially the same across revisions.

### 4.2 Top-Level Shape

```ts
interface LessonAssetBundle {
  id: LessonAssetBundleId;
  versionId: LessonAssetBundleVersionId;
  lessonRef: LessonAssetLessonRef;
  courseBuildRef: LessonAssetCourseBuildRef;
  sourceBundleRefs: LessonAssetSourceBundleRef[];
  groundingPackRefs: LessonAssetGroundingPackRef[];
  lifecycle: LessonAssetBundleLifecycle;
  availability: LessonAssetAvailability;
  delivery: LessonAssetDelivery;
  media: LessonAssetMediaState;
  attachments: LessonAttachment[];
  learnerDisclosure: LessonAssetLearnerDisclosure;
  quality: LessonAssetQualityState;
  governance: LessonAssetGovernance;
  createdAt: string;
  updatedAt: string;
}
```

### 4.3 Lesson and Build References

```ts
interface LessonAssetLessonRef {
  lessonId: string;
  lessonTitle: string;
  moduleId: string;
  moduleTitle: string;
  courseId: string;
  courseTitle: string;
  order: number;
  contentType: 'text' | 'video' | 'interactive' | 'quiz' | 'code_exercise';
  durationMinutes: number | null;
}

interface LessonAssetCourseBuildRef {
  courseBuildId: string;
  courseBuildVersionId: string;
  lessonBuildId: string;
  readinessStatus: 'draft' | 'review' | 'publish_ready' | 'published';
}
```

Reference rule:

- Every bundle must point back to exactly one `CourseBuild` lesson node.
- The bundle may contain richer delivery detail than `CourseBuild`, but it may
  not redefine lesson order, ownership, or course identity.

### 4.4 Source and Grounding References

```ts
interface LessonAssetSourceBundleRef {
  bundleId: string;
  bundleVersionId: string;
  role: 'primary' | 'supplemental' | 'media_reference';
  approvalStatus: 'approved' | 'review_only' | 'blocked';
}

interface LessonAssetGroundingPackRef {
  groundingPackId: string;
  groundingPackVersionId: string;
  supportStatus: 'approved' | 'partial' | 'unsupported' | 'revoked';
  learnerVisibleEvidenceCount: number;
}
```

Reference rule:

- A learner-visible lesson explanation may not claim full grounding support
  unless at least one referenced grounding pack has `supportStatus: 'approved'`.
- Media-only decorative assets may exist without their own grounding pack, but
  the lesson’s educational claims still require upstream evidence posture.

### 4.5 Lifecycle

```ts
type LessonAssetBundleLifecycle =
  | 'draft'
  | 'assembling'
  | 'review'
  | 'publish_ready'
  | 'published'
  | 'superseded'
  | 'revoked'
  | 'archived';
```

Lifecycle rule:

- `publish_ready` means the bundle is structurally complete and not blocked by
  lesson-asset-specific requirements.
- `published` means it is allowed to serve as the active learner-delivery
  bundle.
- `revoked` means it must no longer be served, even if a course remains
  published.

### 4.6 Availability

```ts
interface LessonAssetAvailability {
  isPublished: boolean;
  isFreePreview: boolean;
  enrollmentRequired: boolean;
  previewMode: 'none' | 'metadata_only' | 'partial_content' | 'full_lesson';
  platformTargets: Array<'web' | 'mobile' | 'pwa' | 'export' | 'shell_preview'>;
  fallbackBehavior:
    | 'hide_lesson'
    | 'show_overview_only'
    | 'show_text_fallback'
    | 'show_preview_only';
}
```

Availability rule:

- `isFreePreview` is the canonical lesson-level preview flag behind today’s live
  `Lesson.is_free_preview` field.
- If `previewMode === 'none'`, no learner client may expose lesson body content
  before enrollment.
- `shell_preview` is allowed to render launch-entry summaries, but it must honor
  `previewMode`.

### 4.7 Delivery Payload

```ts
interface LessonAssetDelivery {
  summary: string | null;
  learnerObjectives: string[];
  primaryBody: LessonAssetBody;
  alternateBodies: LessonAssetBody[];
  transcript: LessonTranscript | null;
  navigation: LessonAssetNavigation;
}

type LessonAssetBody =
  | {
      kind: 'rich_text';
      assetId: LessonAssetId;
      format: 'markdown' | 'html' | 'portable_text';
      body: string;
      estimatedReadMinutes: number | null;
    }
  | {
      kind: 'video';
      assetId: LessonAssetId;
      streamUrl: string;
      posterUrl: string | null;
      captionAssetId: LessonAssetId | null;
      chapterMarkers: LessonVideoMarker[];
    }
  | {
      kind: 'interactive';
      assetId: LessonAssetId;
      runtime: 'web_embed' | 'sandbox' | 'simulator';
      manifestUrl: string | null;
      inlineConfig: Record<string, unknown> | null;
      fallbackTextAssetId: LessonAssetId | null;
    }
  | {
      kind: 'quiz';
      assetId: LessonAssetId;
      questionSetId: string;
      explanationAssetId: LessonAssetId | null;
      inlineAttemptsAllowed: number | null;
    }
  | {
      kind: 'code_exercise';
      assetId: LessonAssetId;
      runtime: 'browser_sandbox' | 'remote_runner' | 'notebook';
      templateAssetId: LessonAssetId | null;
      solutionAssetId: LessonAssetId | null;
      fallbackTextAssetId: LessonAssetId | null;
    };

interface LessonVideoMarker {
  label: string;
  startSeconds: number;
}

interface LessonTranscript {
  assetId: LessonAssetId;
  format: 'vtt' | 'srt' | 'plain_text';
  body: string;
  language: string;
}

interface LessonAssetNavigation {
  previousLessonId: string | null;
  nextLessonId: string | null;
  estimatedCompletionMinutes: number | null;
}
```

Delivery rule:

- `primaryBody` is the canonical learner payload.
- `alternateBodies` contain approved fallbacks or channel-specific renditions,
  not speculative drafts.
- A video or interactive lesson should include a fallback path when feasible so
  degraded clients can still expose educational continuity.

### 4.8 Media State

```ts
interface LessonAssetMediaState {
  heroImageUrl: string | null;
  assetCount: number;
  assets: LessonMediaAsset[];
  generatedMedia: LessonGeneratedMedia[];
}

interface LessonMediaAsset {
  id: LessonAssetId;
  role:
    | 'hero'
    | 'inline_image'
    | 'diagram'
    | 'slide'
    | 'caption'
    | 'overlay'
    | 'audio'
    | 'downloadable';
  mimeType: string;
  url: string;
  checksum: string | null;
  durationSeconds: number | null;
  width: number | null;
  height: number | null;
  accessibilityLabel: string | null;
}

interface LessonGeneratedMedia {
  assetId: LessonAssetId;
  generator: 'yemaya' | 'metis' | 'manual';
  purpose:
    | 'style_transfer'
    | 'diagram_generation'
    | 'video_edit'
    | 'animation'
    | 'thumbnail'
    | 'worksheet';
  status: 'draft' | 'approved' | 'blocked' | 'retired';
  sourceAssetIds: LessonAssetId[];
}
```

Media rule:

- Generated media may be attached only as approved delivery assets or blocked
  review artifacts; unpublished experimental media must not be silently mixed
  into the learner bundle.
- `assetCount` must equal `assets.length`.

### 4.9 Attachments

```ts
interface LessonAttachment {
  id: LessonAttachmentId;
  label: string;
  kind:
    | 'resource_link'
    | 'worksheet'
    | 'study_guide'
    | 'slides'
    | 'dataset'
    | 'starter_code'
    | 'solution'
    | 'transcript'
    | 'citation_export';
  url: string | null;
  assetId: LessonAssetId | null;
  learnerVisible: boolean;
  downloadOnly: boolean;
}
```

Attachment rule:

- `resource_urls` from the current lesson model should normalize into
  `attachments`.
- A `citation_export` attachment may expose learner-safe source references, but
  it must not leak restricted raw bundle internals.

### 4.10 Learner Disclosure

```ts
interface LessonAssetLearnerDisclosure {
  groundedSourceCount: number;
  showGroundedSources: boolean;
  showSupportWarnings: boolean;
  supportWarnings: string[];
  evidencePosture: 'approved' | 'partial' | 'unsupported' | 'hidden';
}
```

Disclosure rule:

- This is the contract layer behind the learner grounded-source inspector and
  any lesson-level evidence disclosure.
- If `showGroundedSources` is true, `evidencePosture` may not be `hidden`.

### 4.11 Quality State

```ts
interface LessonAssetQualityState {
  completionPercent: number;
  accessibilityReady: boolean;
  transcriptReady: boolean;
  fallbackReady: boolean;
  brokenAssetCount: number;
  blockingIssues: string[];
  warnings: string[];
}
```

### 4.12 Governance

```ts
interface LessonAssetGovernance {
  educationalOwner: 'metis';
  sourceOfRecordForSources: 'sophia';
  learnerDisclosureRequired: boolean;
  publicationReviewRequired: boolean;
  exportAllowed: boolean;
  auditTrailRequired: boolean;
}
```

Governance rule:

- If attachments or disclosure expose source-backed evidence to learners,
  `learnerDisclosureRequired` must be true.
- If `exportAllowed` is false, the lesson may still render in-product but must
  not be packed into external publication exports.

## 5. Required Invariants

The contract is invalid if any of the following are false:

1. `media.assetCount === media.assets.length`.
2. `quality.completionPercent` is an integer from `0` to `100`.
3. If `availability.isPublished === true`, `lifecycle` must be either
   `publish_ready`, `published`, or `superseded`.
4. If `availability.isFreePreview === true`, `availability.previewMode` may not
   be `none`.
5. If `delivery.primaryBody.kind === 'video'`, either `transcript` is present or
   `quality.transcriptReady === false` with an explicit blocking issue or
   warning.
6. If `learnerDisclosure.showGroundedSources === true`,
   `learnerDisclosure.groundedSourceCount` must be greater than `0`.
7. Any asset or attachment marked `learnerVisible` must resolve to a published,
   non-blocked bundle version.
8. `fallbackBehavior === 'show_text_fallback'` is only valid when a text
   rendition exists in `primaryBody` or `alternateBodies`.

## 6. Mapping to Existing Runtime Truth

`LessonAssetBundle` is a canonicalization of already-live Metis lesson seams:

| `LessonAssetBundle` field                                               | Existing seam                                                                                                                                                      |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lessonRef.*`, `availability.isPublished`, `availability.isFreePreview` | `services/metis/src/metis/models/course.py` lesson fields and corresponding course schemas                                                                         |
| `delivery.primaryBody`, `delivery.summary`, `navigation`                | learner course detail rendering and normalized lesson payloads in `apps/metis/web/src/app/courses/[courseId]/page.tsx` and `apps/metis/web/src/lib/course-data.ts` |
| `learnerDisclosure.*`                                                   | grounded source normalization in `apps/metis/web/src/lib/grounded-sources.ts` and learner inspection UI                                                            |
| `attachments`                                                           | current `resource_urls` plus lesson artifact export/download surfaces                                                                                              |
| `media.generatedMedia.*`                                                | future style transfer, edited video, and animation outputs exposed by `libs/metis/integrations/src/yemaya-integration.ts`                                          |
| `quality.*`                                                             | lesson-specific readiness and fallback concerns currently split across authoring, learner states, and publication review                                           |

## 7. Downstream Consumer Rules

### 7.1 Learner Web and Mobile

Learner clients should consume `LessonAssetBundle` or a projection derived from
it. They should not parse raw `Lesson.content` blobs without delivery metadata
once this contract exists.

### 7.2 Shell and Public Entry

Shell preview surfaces may consume lesson summaries and preview-safe metadata,
but they must obey `availability.previewMode` and may not expose hidden lesson
body content.

### 7.3 Authoring and Studio

Authoring tools may edit draft delivery projections, but upstream educational
structure remains owned by `CourseBuild`.

### 7.4 Publication and Export

`PublicationPackage` should include `LessonAssetBundle` references rather than
reconstructing lesson payloads from scratch.

## 8. JSON Example

```json
{
  "id": "lab_course-1_lesson-1",
  "versionId": "labv_course-1_lesson-1_2026-04-10T00:00:00Z",
  "lessonRef": {
    "lessonId": "lesson-1",
    "lessonTitle": "What Makes a Model Learn?",
    "moduleId": "module-1",
    "moduleTitle": "Core Concepts",
    "courseId": "course-1",
    "courseTitle": "Introduction to Machine Learning",
    "order": 1,
    "contentType": "video",
    "durationMinutes": 18
  },
  "courseBuildRef": {
    "courseBuildId": "cb_course-1",
    "courseBuildVersionId": "cbv_course-1_2026-04-10T00:00:00Z",
    "lessonBuildId": "cbl_lesson-1",
    "readinessStatus": "publish_ready"
  },
  "sourceBundleRefs": [
    {
      "bundleId": "lsb_course-1",
      "bundleVersionId": "lsbv_course-1_2026-04-10T00:00:00Z",
      "role": "primary",
      "approvalStatus": "approved"
    }
  ],
  "groundingPackRefs": [
    {
      "groundingPackId": "gpk_course-1_lesson-1",
      "groundingPackVersionId": "gpkv_course-1_lesson-1_2026-04-10T00:00:00Z",
      "supportStatus": "approved",
      "learnerVisibleEvidenceCount": 4
    }
  ],
  "lifecycle": "published",
  "availability": {
    "isPublished": true,
    "isFreePreview": true,
    "enrollmentRequired": false,
    "previewMode": "partial_content",
    "platformTargets": ["web", "mobile", "pwa", "shell_preview", "export"],
    "fallbackBehavior": "show_text_fallback"
  },
  "delivery": {
    "summary": "Introduce training data, feedback loops, and iterative model improvement.",
    "learnerObjectives": [
      "Explain how examples and feedback shape model behavior",
      "Recognize the difference between input data and target outcomes"
    ],
    "primaryBody": {
      "kind": "video",
      "assetId": "la_video_1",
      "streamUrl": "https://cdn.metis.example/lessons/lesson-1/master.m3u8",
      "posterUrl": "https://cdn.metis.example/lessons/lesson-1/poster.jpg",
      "captionAssetId": "la_caption_1",
      "chapterMarkers": [
        { "label": "Training examples", "startSeconds": 0 },
        { "label": "Feedback signals", "startSeconds": 215 }
      ]
    },
    "alternateBodies": [
      {
        "kind": "rich_text",
        "assetId": "la_text_1",
        "format": "markdown",
        "body": "## Lesson notes\n\nTraining starts with examples...",
        "estimatedReadMinutes": 8
      }
    ],
    "transcript": {
      "assetId": "la_caption_1",
      "format": "vtt",
      "body": "WEBVTT\n\n00:00:00.000 --> 00:00:05.000\nWelcome back...",
      "language": "en"
    },
    "navigation": {
      "previousLessonId": null,
      "nextLessonId": "lesson-2",
      "estimatedCompletionMinutes": 18
    }
  },
  "media": {
    "heroImageUrl": "https://cdn.metis.example/lessons/lesson-1/poster.jpg",
    "assetCount": 3,
    "assets": [
      {
        "id": "la_video_1",
        "role": "overlay",
        "mimeType": "application/x-mpegURL",
        "url": "https://cdn.metis.example/lessons/lesson-1/master.m3u8",
        "checksum": "sha256:lesson-video",
        "durationSeconds": 1080,
        "width": 1920,
        "height": 1080,
        "accessibilityLabel": "Instructor video explaining supervised learning feedback"
      },
      {
        "id": "la_caption_1",
        "role": "caption",
        "mimeType": "text/vtt",
        "url": "https://cdn.metis.example/lessons/lesson-1/captions.vtt",
        "checksum": "sha256:lesson-captions",
        "durationSeconds": 1080,
        "width": null,
        "height": null,
        "accessibilityLabel": "English captions"
      },
      {
        "id": "la_slide_1",
        "role": "slide",
        "mimeType": "image/png",
        "url": "https://cdn.metis.example/lessons/lesson-1/diagram.png",
        "checksum": "sha256:lesson-diagram",
        "durationSeconds": null,
        "width": 1600,
        "height": 900,
        "accessibilityLabel": "Diagram showing training inputs and target labels"
      }
    ],
    "generatedMedia": [
      {
        "assetId": "la_slide_1",
        "generator": "yemaya",
        "purpose": "diagram_generation",
        "status": "approved",
        "sourceAssetIds": []
      }
    ]
  },
  "attachments": [
    {
      "id": "lat_notes_1",
      "label": "Lesson notes PDF",
      "kind": "study_guide",
      "url": "https://cdn.metis.example/lessons/lesson-1/notes.pdf",
      "assetId": null,
      "learnerVisible": true,
      "downloadOnly": true
    },
    {
      "id": "lat_sources_1",
      "label": "Grounded references",
      "kind": "citation_export",
      "url": "https://cdn.metis.example/lessons/lesson-1/sources.json",
      "assetId": null,
      "learnerVisible": true,
      "downloadOnly": true
    }
  ],
  "learnerDisclosure": {
    "groundedSourceCount": 4,
    "showGroundedSources": true,
    "showSupportWarnings": false,
    "supportWarnings": [],
    "evidencePosture": "approved"
  },
  "quality": {
    "completionPercent": 100,
    "accessibilityReady": true,
    "transcriptReady": true,
    "fallbackReady": true,
    "brokenAssetCount": 0,
    "blockingIssues": [],
    "warnings": []
  },
  "governance": {
    "educationalOwner": "metis",
    "sourceOfRecordForSources": "sophia",
    "learnerDisclosureRequired": true,
    "publicationReviewRequired": true,
    "exportAllowed": true,
    "auditTrailRequired": true
  },
  "createdAt": "2026-04-10T00:00:00Z",
  "updatedAt": "2026-04-10T00:00:00Z"
}
```

## 9. Completion Rule

Metis should treat `LessonAssetBundle` as the canonical lesson-delivery contract
for V1. Future lesson APIs, publish flows, export packaging, and learner clients
should converge on this shape rather than proliferating parallel,
surface-specific lesson payloads.
