Eve library

OSHUN V1 Metis `LessonAssetBundle` Contract

Spec

Revision 1

On this page

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.