# OSHUN V1 Metis `LearningSourceBundle` Contract

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.
