Status: Active
Date: April 10, 2026
Owners: OSHUN Metis Engineering, OSHUN Sophia, OSHUN Safety, OSHUN Compliance
Related:
docs/releases/v1/reports/metis-subsystem-ownership-matrix.mddocs/releases/v1/reports/metis-v1-scorecard.mddocs/releases/v1/reports/metis-v1-workstream-tracking.mddocs/releases/v1/runbooks/metis-operator-workflows-runbook.mddocs/releases/v1/specs/todos.mdservices/metis/src/metis/schemas/admin.pyservices/metis/src/metis/services/admin_service.pyapps/metis/admin/src/types/admin.tsapps/metis/web/src/lib/grounded-sources.tslibs/sophia/schemas/src/research-document.ts
1. Purpose#
This document defines the canonical LearningSourceBundle contract for Metis
V1.
It is the shared object that turns raw imported or attached learning materials into a governed, reviewable, reusable bundle that can safely feed:
- grounded course builds
- tutor answer constraints
- assessment support evidence
- learner-facing grounded-source inspection
- source-rights review
- publication gating
- audit and export provenance
This contract is intentionally upstream of GroundingPack, CourseBuild,
LessonAssetBundle, and PublicationPackage.
2. Design Constraints#
LearningSourceBundle must satisfy all of the following:
- It must be a Metis-owned educational assembly contract, but it must not replace Sophia as the source-of-record for document and citation lineage.
- It must carry enough rights and provenance posture for admin review and publication gating.
- It must preserve enough extraction and coverage detail to explain why a bundle is approved, blocked, or only safe for internal review.
- It must support multiple source ingress modes without changing downstream consumers.
- It must let learner surfaces reference grounded source artifacts without requiring learner clients to understand raw ingestion internals.
3. Contract Role in the Metis Pipeline#
LearningSourceBundle is the first canonical object after ingestion and
extraction.
Pipeline position:
- Ingest files, URLs, feeds, LMS packages, or institutional corpora.
- Extract text, structure, citations, hashes, metadata, and rights signals.
- Normalize those materials into a
LearningSourceBundle. - Submit that bundle to rights and source-quality review.
- Use approved bundle contents to produce a
GroundingPack. - Use the
GroundingPackto buildCourseBuild, tutoring, and assessment artifacts.
If LearningSourceBundle is absent or unapproved, downstream grounded flows may
not claim release-grade source support.
4. Canonical Contract#
4.1 Identity#
type LearningSourceBundleId = `lsb_${string}`;
type LearningSourceAssetId = `lsa_${string}`;
type LearningSourceVersionId = `lsbv_${string}`;
Rules:
- The bundle ID is stable across revisions of the same logical source set.
- The version ID changes whenever bundle composition or extracted evidence changes.
- Asset IDs are stable per normalized source artifact inside the bundle.
4.2 Top-Level Shape#
interface LearningSourceBundle {
id: LearningSourceBundleId;
versionId: LearningSourceVersionId;
title: string;
summary: string;
scope: LearningSourceBundleScope;
lifecycle: LearningSourceBundleLifecycle;
review: LearningSourceBundleReviewState;
rights: LearningSourceBundleRightsState;
provenance: LearningSourceBundleProvenanceState;
extraction: LearningSourceBundleExtractionState;
coverage: LearningSourceBundleCoverage;
materials: LearningSourceMaterial[];
usage: LearningSourceBundleUsage;
governance: LearningSourceBundleGovernance;
createdAt: string;
updatedAt: string;
}
4.3 Scope#
type LearningSourceBundleScope =
| {
level: 'course';
courseId: string;
courseTitle: string;
ownerId: string;
ownerName: string;
}
| {
level: 'workspace';
workspaceId: string;
workspaceTitle: string;
ownerId: string;
ownerName: string;
}
| {
level: 'notebook';
notebookId: string;
notebookTitle: string;
ownerId: string;
ownerName: string;
}
| {
level: 'learner-session';
sessionId: string;
learnerId: string;
learnerName: string;
};
Scope rule:
- A bundle has exactly one primary scope.
- Downstream usage may reference the same bundle from multiple derived artifacts, but the bundle itself has one authoring or operational home.
4.4 Lifecycle#
type LearningSourceBundleLifecycle =
| 'draft'
| 'extracting'
| 'review'
| 'approved'
| 'changes_requested'
| 'rejected'
| 'deprecated'
| 'archived';
Lifecycle rule:
- Only
approvedbundles may feed release-grade grounded builds and publication-grade tutoring constraints. reviewandchanges_requestedbundles may be visible to operators but must not be treated as learner-safe by default.
4.5 Review State#
interface LearningSourceBundleReviewState {
status: 'pending' | 'approved' | 'changes_requested' | 'rejected';
riskLevel: 'low' | 'medium' | 'high' | 'critical';
blockers: string[];
reviewFocus: string[];
dueAt: string | null;
latestDecisionAt: string | null;
latestDecisionBy: string | null;
}
4.6 Rights State#
type LearningSourceRightsPosture = 'cleared' | 'needs_review' | 'blocked';
type LearningSourceLicenseType =
| 'open_license'
| 'licensed'
| 'institutional'
| 'open_reference'
| 'restricted'
| 'unknown'
| 'missing';
interface LearningSourceBundleRightsState {
posture: LearningSourceRightsPosture;
licenseType: LearningSourceLicenseType;
allowedUse: string;
sourceCount: number;
licensedSourceCount: number;
restrictedSourceCount: number;
unknownSourceCount: number;
licenseCoveragePercent: number;
policyFlags: string[];
}
4.7 Provenance State#
type LearningSourceProvenancePosture =
| 'verified'
| 'partial'
| 'weak'
| 'missing';
interface LearningSourceBundleProvenanceState {
posture: LearningSourceProvenancePosture;
provenanceCoveragePercent: number;
citationCount: number;
latestSourceUpdateAt: string | null;
sourceDomains: string[];
}
4.8 Extraction State#
interface LearningSourceBundleExtractionState {
status: 'pending' | 'processing' | 'complete' | 'partial' | 'failed';
textExtracted: boolean;
structureExtracted: boolean;
citationsExtracted: boolean;
rightsSignalsExtracted: boolean;
parserFailures: number;
ocrFailures: number;
extractionWarnings: string[];
}
4.9 Coverage#
interface LearningSourceBundleCoverage {
lessonCoveragePercent: number;
lessonsInScope: number;
lessonsWithAttachedMaterial: number;
groundedLessonPercent: number | null;
assessmentSupportPercent: number | null;
linkedEscalationCount: number;
}
Coverage rule:
lessonCoveragePercentdescribes how much of the scoped lesson set has attributable material inside the bundle.groundedLessonPercentandassessmentSupportPercentare nullable because those are downstream build-readiness signals, not intrinsic extraction facts.
4.10 Materials#
type LearningSourceMaterialKind =
| 'file'
| 'url'
| 'feed'
| 'lms-package'
| 'institutional-corpus'
| 'citation-reference'
| 'derived-fragment';
interface LearningSourceMaterial {
id: LearningSourceAssetId;
kind: LearningSourceMaterialKind;
title: string;
url: string | null;
mimeType: string | null;
sourceHash: string | null;
sourceDomain: string | null;
rightsStatus: string | null;
locator: string | null;
excerpt: string | null;
summary: string | null;
attachedLessonIds: string[];
metadata: Record<string, string | number | boolean | null>;
}
Material rule:
- Each material is a normalized source artifact or referenceable fragment.
- A material may map to one or many lessons, but each lesson linkage must stay explicit.
4.11 Usage#
interface LearningSourceBundleUsage {
usedByGroundedBuildIds: string[];
usedByPublicationPackageIds: string[];
usedByTutorPolicyIds: string[];
usedByAssessmentIds: string[];
learnerVisibleArtifactCount: number;
}
4.12 Governance#
interface LearningSourceBundleGovernance {
sourceOfRecord: 'sophia';
educationalOwner: 'metis';
rightsOwner: 'metis-compliance';
reviewQueueType: 'source_bundle';
rightsWorkspaceRequired: boolean;
auditTrailRequired: boolean;
}
Governance rule:
sourceOfRecordis Sophia even when Metis owns educational packaging and review flow semantics.
5. Required Invariants#
The contract is invalid if any of the following are false:
materials.lengthequalsrights.sourceCountfor normalized source artifacts in the bundle.provenance.provenanceCoveragePercentandrights.licenseCoveragePercentare integers from0to100.- If
rights.posture === 'blocked',review.blockers.lengthmust be greater than0. - If
lifecycle === 'approved',review.statusmust beapproved. - If
lifecycle === 'approved',governance.auditTrailRequiredmust betrue. - If
rights.unknownSourceCount > 0,rights.policyFlagsmust contain an unknown-rights or equivalent governance signal. - If
provenance.posture !== 'verified', the bundle must not be represented downstream as fully grounded or release-cleared.
6. Mapping to Existing Runtime Truth#
This contract is derived from already-live or already-modeled Metis fields.
LearningSourceBundle field |
Existing implementation seam |
|---|---|
review.status, review.riskLevel, review.blockers, review.reviewFocus, review.dueAt |
services/metis/src/metis/schemas/admin.py review-queue models and source_bundle queue responses |
rights.posture, rights.licenseType, rights.allowedUse, counts, license coverage |
SourceRightsReviewItemResponse and _build_source_rights_item in services/metis/src/metis/services/admin_service.py |
provenance.posture, provenance.provenanceCoveragePercent, latestSourceUpdateAt, sourceDomains |
derive_provenance_posture inputs and source-rights item derivation in admin_service.py |
coverage.lessonsInScope, coverage.lessonsWithAttachedMaterial, coverage.linkedEscalationCount |
current review detail and review metrics for source_bundle in admin fixtures and queue derivation |
coverage.groundedLessonPercent, coverage.assessmentSupportPercent |
operator build-evidence and grounded-build queue metrics |
materials[].url, materials[].locator, materials[].excerpt, materials[].summary |
grounded-source normalization in apps/metis/web/src/lib/grounded-sources.ts |
governance.sourceOfRecord |
Metis ownership matrix assigns source-trust and grounding lineage to Sophia |
7. Downstream Consumer Rules#
7.1 Admin Review#
Admin review queues may summarize a LearningSourceBundle, but queue rows are
not the canonical bundle contract. They are operator projections of it.
7.2 Source Rights Workspace#
The source-rights workspace must consume the bundle’s rights and provenance state, not invent its own incompatible counters or posture vocabulary.
7.3 Learner Grounded UI#
Learner-facing grounded-source components should consume material-level
excerpts, locators, summaries, and URLs derived from the bundle or its
downstream GroundingPack, never from ad hoc free-text parsing alone where
canonical bundle data exists.
7.4 Publication Gating#
PublicationPackage may depend on LearningSourceBundle, but it must not copy
or mutate bundle governance state. It should reference the bundle and inherit
its approval posture.
8. JSON Example#
{
"id": "lsb_course-1",
"versionId": "lsbv_course-1_2026-04-10T00:00:00Z",
"title": "Introduction to Machine Learning source bundle",
"summary": "Bounded learning materials and extracted references for Introduction to Machine Learning.",
"scope": {
"level": "course",
"courseId": "course-1",
"courseTitle": "Introduction to Machine Learning",
"ownerId": "instructor-1",
"ownerName": "Amara Osei"
},
"lifecycle": "review",
"review": {
"status": "pending",
"riskLevel": "high",
"blockers": [
"Topical tags are missing, reducing source-scope traceability."
],
"reviewFocus": [
"Scope boundaries",
"Extraction completeness",
"Source freshness"
],
"dueAt": "2026-04-14T12:00:00Z",
"latestDecisionAt": null,
"latestDecisionBy": null
},
"rights": {
"posture": "needs_review",
"licenseType": "unknown",
"allowedUse": "Internal or review-only use until source rights are cleared",
"sourceCount": 7,
"licensedSourceCount": 4,
"restrictedSourceCount": 1,
"unknownSourceCount": 2,
"licenseCoveragePercent": 57,
"policyFlags": [
"Institutional source package",
"Unknown rights metadata present"
]
},
"provenance": {
"posture": "partial",
"provenanceCoveragePercent": 62,
"citationCount": 11,
"latestSourceUpdateAt": "2026-04-09T12:00:00Z",
"sourceDomains": ["example.edu", "openml.org"]
},
"extraction": {
"status": "complete",
"textExtracted": true,
"structureExtracted": true,
"citationsExtracted": true,
"rightsSignalsExtracted": true,
"parserFailures": 0,
"ocrFailures": 0,
"extractionWarnings": []
},
"coverage": {
"lessonCoveragePercent": 62,
"lessonsInScope": 6,
"lessonsWithAttachedMaterial": 4,
"groundedLessonPercent": null,
"assessmentSupportPercent": null,
"linkedEscalationCount": 1
},
"materials": [
{
"id": "lsa_course-1_src-1",
"kind": "url",
"title": "OpenML reference dataset guide",
"url": "https://www.openml.org/example",
"mimeType": "text/html",
"sourceHash": null,
"sourceDomain": "openml.org",
"rightsStatus": "open_reference",
"locator": "Lesson 2",
"excerpt": null,
"summary": "Reference material attached to the supervised learning lesson.",
"attachedLessonIds": ["lesson-2"],
"metadata": {}
}
],
"usage": {
"usedByGroundedBuildIds": [],
"usedByPublicationPackageIds": [],
"usedByTutorPolicyIds": [],
"usedByAssessmentIds": [],
"learnerVisibleArtifactCount": 0
},
"governance": {
"sourceOfRecord": "sophia",
"educationalOwner": "metis",
"rightsOwner": "metis-compliance",
"reviewQueueType": "source_bundle",
"rightsWorkspaceRequired": true,
"auditTrailRequired": true
},
"createdAt": "2026-04-07T09:00:00Z",
"updatedAt": "2026-04-09T12:00:00Z"
}
9. Non-Goals#
LearningSourceBundle does not define:
- the learner-facing grounding artifact payload in full
- the final release package for a course
- media-render artifact packaging
- model-routing or prompt-governance decisions
- LMS connector transport details
Those belong to later Metis contracts and implementation tasks.
10. Completion Rule for V1-MET-049#
V1-MET-049 is complete only when:
- This contract exists as the canonical definition of
LearningSourceBundle. - The contract is explicitly tied to current Metis runtime seams rather than invented in isolation.
- Ownership and downstream consumer rules are explicit.
- The Metis scorecard and implementation guide can link to this document as the canonical source-bundle contract artifact.