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.mddocs/releases/v1/specs/metis-grounding-pack-contract.mddocs/releases/v1/specs/metis-course-build-contract.mddocs/releases/v1/reports/metis-v1-scorecard.mddocs/releases/v1/specs/todos.mdservices/metis/src/metis/models/course.pyservices/metis/src/metis/schemas/course.pyapps/metis/web/src/app/courses/[courseId]/page.tsxapps/metis/web/src/lib/course-data.tsapps/metis/web/src/lib/grounded-sources.tslibs/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:
LearningSourceBundleGroundingPackCourseBuildLessonAssetBundlePublicationPackage
Responsibility rule:
LearningSourceBundlegoverns approved source scope.GroundingPackgoverns learner-facing evidence support.CourseBuildgoverns course assembly and lesson intent.LessonAssetBundlegoverns lesson payload, renditions, media, attachments, and previewability.PublicationPackagegoverns 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:
- It must support the currently live Metis lesson modes: text, video, interactive, quiz, and code exercise.
- It must distinguish authoring intent from learner delivery, so learner clients do not need to parse raw authoring blobs or infer preview rules.
- It must support grounded-source disclosure and downloadable lesson artifacts without duplicating raw source-ingestion internals.
- It must support multiple delivery renditions for the same lesson, including text, structured blocks, video, captions, overlays, worksheets, and future generated media.
- It must make preview, publish, and fallback behavior explicit for shell, web, mobile, and export consumers.
4. Canonical Contract#
4.1 Identity#
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#
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#
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
CourseBuildlesson 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#
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#
type LessonAssetBundleLifecycle =
| 'draft'
| 'assembling'
| 'review'
| 'publish_ready'
| 'published'
| 'superseded'
| 'revoked'
| 'archived';
Lifecycle rule:
publish_readymeans the bundle is structurally complete and not blocked by lesson-asset-specific requirements.publishedmeans it is allowed to serve as the active learner-delivery bundle.revokedmeans it must no longer be served, even if a course remains published.
4.6 Availability#
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:
isFreePreviewis the canonical lesson-level preview flag behind today’s liveLesson.is_free_previewfield.- If
previewMode === 'none', no learner client may expose lesson body content before enrollment. shell_previewis allowed to render launch-entry summaries, but it must honorpreviewMode.
4.7 Delivery Payload#
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:
primaryBodyis the canonical learner payload.alternateBodiescontain 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#
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.
assetCountmust equalassets.length.
4.9 Attachments#
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_urlsfrom the current lesson model should normalize intoattachments.- A
citation_exportattachment may expose learner-safe source references, but it must not leak restricted raw bundle internals.
4.10 Learner Disclosure#
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
showGroundedSourcesis true,evidencePosturemay not behidden.
4.11 Quality State#
interface LessonAssetQualityState {
completionPercent: number;
accessibilityReady: boolean;
transcriptReady: boolean;
fallbackReady: boolean;
brokenAssetCount: number;
blockingIssues: string[];
warnings: string[];
}
4.12 Governance#
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,
learnerDisclosureRequiredmust be true. - If
exportAllowedis 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:
media.assetCount === media.assets.length.quality.completionPercentis an integer from0to100.- If
availability.isPublished === true,lifecyclemust be eitherpublish_ready,published, orsuperseded. - If
availability.isFreePreview === true,availability.previewModemay not benone. - If
delivery.primaryBody.kind === 'video', eithertranscriptis present orquality.transcriptReady === falsewith an explicit blocking issue or warning. - If
learnerDisclosure.showGroundedSources === true,learnerDisclosure.groundedSourceCountmust be greater than0. - Any asset or attachment marked
learnerVisiblemust resolve to a published, non-blocked bundle version. fallbackBehavior === 'show_text_fallback'is only valid when a text rendition exists inprimaryBodyoralternateBodies.
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#
{
"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.