Eve library

OSHUN V1 Metis `LearningSourceBundle` Contract

Spec

Revision 1

On this page

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.md
  • docs/releases/v1/reports/metis-v1-scorecard.md
  • docs/releases/v1/reports/metis-v1-workstream-tracking.md
  • docs/releases/v1/runbooks/metis-operator-workflows-runbook.md
  • docs/releases/v1/specs/todos.md
  • services/metis/src/metis/schemas/admin.py
  • services/metis/src/metis/services/admin_service.py
  • apps/metis/admin/src/types/admin.ts
  • apps/metis/web/src/lib/grounded-sources.ts
  • libs/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:

  1. 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.
  2. It must carry enough rights and provenance posture for admin review and publication gating.
  3. It must preserve enough extraction and coverage detail to explain why a bundle is approved, blocked, or only safe for internal review.
  4. It must support multiple source ingress modes without changing downstream consumers.
  5. 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:

  1. Ingest files, URLs, feeds, LMS packages, or institutional corpora.
  2. Extract text, structure, citations, hashes, metadata, and rights signals.
  3. Normalize those materials into a LearningSourceBundle.
  4. Submit that bundle to rights and source-quality review.
  5. Use approved bundle contents to produce a GroundingPack.
  6. Use the GroundingPack to build CourseBuild, 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#

ts
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#

ts
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#

ts
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#

ts
type LearningSourceBundleLifecycle =
  | 'draft'
  | 'extracting'
  | 'review'
  | 'approved'
  | 'changes_requested'
  | 'rejected'
  | 'deprecated'
  | 'archived';

Lifecycle rule:

  • Only approved bundles may feed release-grade grounded builds and publication-grade tutoring constraints.
  • review and changes_requested bundles may be visible to operators but must not be treated as learner-safe by default.

4.5 Review State#

ts
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#

ts
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#

ts
type LearningSourceProvenancePosture =
  | 'verified'
  | 'partial'
  | 'weak'
  | 'missing';

interface LearningSourceBundleProvenanceState {
  posture: LearningSourceProvenancePosture;
  provenanceCoveragePercent: number;
  citationCount: number;
  latestSourceUpdateAt: string | null;
  sourceDomains: string[];
}

4.8 Extraction State#

ts
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#

ts
interface LearningSourceBundleCoverage {
  lessonCoveragePercent: number;
  lessonsInScope: number;
  lessonsWithAttachedMaterial: number;
  groundedLessonPercent: number | null;
  assessmentSupportPercent: number | null;
  linkedEscalationCount: number;
}

Coverage rule:

  • lessonCoveragePercent describes how much of the scoped lesson set has attributable material inside the bundle.
  • groundedLessonPercent and assessmentSupportPercent are nullable because those are downstream build-readiness signals, not intrinsic extraction facts.

4.10 Materials#

ts
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#

ts
interface LearningSourceBundleUsage {
  usedByGroundedBuildIds: string[];
  usedByPublicationPackageIds: string[];
  usedByTutorPolicyIds: string[];
  usedByAssessmentIds: string[];
  learnerVisibleArtifactCount: number;
}

4.12 Governance#

ts
interface LearningSourceBundleGovernance {
  sourceOfRecord: 'sophia';
  educationalOwner: 'metis';
  rightsOwner: 'metis-compliance';
  reviewQueueType: 'source_bundle';
  rightsWorkspaceRequired: boolean;
  auditTrailRequired: boolean;
}

Governance rule:

  • sourceOfRecord is 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:

  1. materials.length equals rights.sourceCount for normalized source artifacts in the bundle.
  2. provenance.provenanceCoveragePercent and rights.licenseCoveragePercent are integers from 0 to 100.
  3. If rights.posture === 'blocked', review.blockers.length must be greater than 0.
  4. If lifecycle === 'approved', review.status must be approved.
  5. If lifecycle === 'approved', governance.auditTrailRequired must be true.
  6. If rights.unknownSourceCount > 0, rights.policyFlags must contain an unknown-rights or equivalent governance signal.
  7. 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#

json
{
  "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:

  1. This contract exists as the canonical definition of LearningSourceBundle.
  2. The contract is explicitly tied to current Metis runtime seams rather than invented in isolation.
  3. Ownership and downstream consumer rules are explicit.
  4. The Metis scorecard and implementation guide can link to this document as the canonical source-bundle contract artifact.