# OSHUN V1 Metis `GroundingPack` Contract

Status: Active

Date: April 10, 2026

Owners: OSHUN Sophia, OSHUN Metis Engineering, OSHUN Safety, OSHUN Compliance

Related:

- `docs/releases/v1/specs/metis-learning-source-bundle-contract.md`
- `docs/releases/v1/reports/metis-subsystem-ownership-matrix.md`
- `docs/releases/v1/reports/metis-v1-scorecard.md`
- `docs/releases/v1/specs/todos.md`
- `apps/metis/web/src/lib/grounded-sources.ts`
- `apps/metis/web/src/types/index.ts`
- `services/metis/src/metis/services/admin_service.py`
- `apps/metis/admin/src/types/admin.ts`

## 1. Purpose

This document defines the canonical `GroundingPack` contract for Metis V1.

`GroundingPack` is the governed evidence package that sits between an approved
`LearningSourceBundle` and any grounded Metis output such as:

- course lessons
- assessment questions and explanations
- tutor answers
- learner-visible study artifacts
- operator build-evidence summaries
- publication gating and audit evidence

If `LearningSourceBundle` defines what source materials are allowed,
`GroundingPack` defines what evidence from those materials is actually being
used to support a specific educational output.

## 2. Role in the Contract Chain

Contract order:

1. `LearningSourceBundle`
2. `GroundingPack`
3. `CourseBuild`
4. `LessonAssetBundle`
5. `PublicationPackage`

Pipeline rule:

- `LearningSourceBundle` governs source scope and rights posture.
- `GroundingPack` governs evidence selection, support coverage, and
  claim-to-source traceability.
- `CourseBuild` governs educational assembly.

`GroundingPack` must not invent source materials outside the approved
`LearningSourceBundle` versions it references.

## 3. Canonical Contract

### 3.1 Identity

```ts
type GroundingPackId = `gpk_${string}`;
type GroundingPackVersionId = `gpkv_${string}`;
type GroundingEvidenceId = `gev_${string}`;
type GroundingClaimId = `gcl_${string}`;
```

### 3.2 Top-Level Shape

```ts
interface GroundingPack {
  id: GroundingPackId;
  versionId: GroundingPackVersionId;
  scope: GroundingPackScope;
  sourceBundleRefs: GroundingSourceBundleRef[];
  status: GroundingPackStatus;
  supportSummary: GroundingSupportSummary;
  claims: GroundingClaim[];
  evidence: GroundingEvidence[];
  governance: GroundingGovernance;
  createdAt: string;
  updatedAt: string;
}
```

### 3.3 Scope

```ts
type GroundingPackScope =
  | {
      kind: 'course_lesson';
      courseId: string;
      lessonId: string;
      lessonTitle: string;
    }
  | {
      kind: 'assessment_question';
      courseId: string;
      assessmentId: string;
      questionId: string;
    }
  | {
      kind: 'tutor_answer';
      courseId: string | null;
      sessionId: string;
      messageId: string;
    }
  | {
      kind: 'study_artifact';
      artifactType: 'achievement' | 'study_guide' | 'flashcard' | 'quiz_review';
      artifactId: string;
      courseId: string | null;
    }
  | {
      kind: 'build_summary';
      courseId: string;
      artifactId: string;
    };
```

### 3.4 Source Bundle References

```ts
interface GroundingSourceBundleRef {
  bundleId: string;
  bundleVersionId: string;
  posture: 'approved' | 'review_only' | 'blocked';
}
```

Rule:

- Every `GroundingPack` must reference at least one source bundle version.
- Any referenced bundle with posture other than `approved` prevents
  release-grade downstream use.

### 3.5 Status

```ts
type GroundingPackStatus =
  | 'draft'
  | 'assembled'
  | 'partial'
  | 'unsupported'
  | 'approved'
  | 'superseded'
  | 'revoked';
```

Status rule:

- `assembled` means evidence selection exists but operator or policy approval is
  not yet implied.
- `partial` means some claims or educational segments lack adequate support.
- `unsupported` means the pack may explain missing support but may not be
  marketed as grounded.

### 3.6 Support Summary

```ts
interface GroundingSupportSummary {
  claimCount: number;
  supportedClaimCount: number;
  unsupportedClaimCount: number;
  supportCoveragePercent: number;
  evidenceCount: number;
  learnerVisibleSourceCount: number;
  missingSupportReasons: string[];
}
```

### 3.7 Claims

```ts
interface GroundingClaim {
  id: GroundingClaimId;
  label: string;
  claimText: string;
  claimType:
    | 'lesson_explanation'
    | 'quiz_question'
    | 'quiz_explanation'
    | 'tutor_answer'
    | 'artifact_summary'
    | 'build_readiness_statement';
  supportStatus: 'supported' | 'partial' | 'unsupported';
  evidenceIds: GroundingEvidenceId[];
  learnerVisible: boolean;
}
```

Claim rule:

- Every learner-visible claim must explicitly declare whether it is `supported`,
  `partial`, or `unsupported`.
- Empty evidence references are valid only when `supportStatus !== 'supported'`.

### 3.8 Evidence

```ts
interface GroundingEvidence {
  id: GroundingEvidenceId;
  sourceMaterialId: string;
  label: string;
  kind:
    | 'lesson'
    | 'question'
    | 'answer'
    | 'artifact'
    | 'reference'
    | 'resource';
  url: string | null;
  locator: string | null;
  excerpt: string | null;
  summary: string | null;
  citationConfidence: 'high' | 'medium' | 'low' | 'unknown';
  learnerVisible: boolean;
}
```

Evidence rule:

- `GroundingEvidence` is the canonical form behind today’s `groundedSources`
  payloads.
- Learner clients may receive a filtered projection of evidence, but they must
  not need to parse raw source metadata strings when a `GroundingPack` exists.

### 3.9 Governance

```ts
interface GroundingGovernance {
  sourceOfRecord: 'sophia';
  consumingDomain: 'metis';
  reviewQueueType: 'grounded_build';
  rightsChecked: boolean;
  auditTrailRequired: boolean;
  learnerDisclosureRequired: boolean;
}
```

Governance rule:

- A `GroundingPack` is not publishable if `rightsChecked` is false.
- If any evidence is learner-visible, `learnerDisclosureRequired` must be true.

## 4. Required Invariants

The contract is invalid if any of the following are false:

1. `supportSummary.claimCount === claims.length`.
2. `supportSummary.evidenceCount === evidence.length`.
3. `supportSummary.supportCoveragePercent` is an integer from `0` to `100`.
4. `supportedClaimCount + unsupportedClaimCount` may be less than `claimCount`
   only when partial claims exist.
5. If `status === 'approved'`, every referenced source bundle must have posture
   `approved`.
6. If a claim has `supportStatus === 'supported'`, `evidenceIds.length` must be
   greater than `0`.
7. If any evidence has `learnerVisible === true`, governance must require
   learner disclosure.

## 5. Mapping to Existing Runtime Truth

This contract formalizes existing Metis runtime seams rather than replacing
them.

| `GroundingPack` field                                               | Existing seam                                                                                 |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `scope.kind === 'course_lesson'` and `evidence[].kind === 'lesson'` | lesson `groundedSources` in `apps/metis/web/src/lib/course-data.ts` and `grounded-sources.ts` |
| `scope.kind === 'assessment_question'` and `claims/evidence`        | assessment `source_refs_json` and question `groundedSources` normalization                    |
| `scope.kind === 'tutor_answer'`                                     | tutoring `metadata_json` and message `groundedSources` normalization                          |
| `scope.kind === 'study_artifact'`                                   | progress achievement `metadata_json` and grounded artifact sources                            |
| `supportSummary.supportCoveragePercent`                             | current grounded-build and operator build-evidence percentages in `admin_service.py`          |
| `governance.reviewQueueType`                                        | existing `grounded_build` review queue taxonomy                                               |
| `evidence[].url`, `locator`, `excerpt`, `summary`, `kind`           | current `GroundedSource` shape in `apps/metis/web/src/types/index.ts`                         |

## 6. Downstream Consumer Rules

### 6.1 Web Learner Surfaces

Course lessons, assessments, tutoring, and progress artifacts should consume a
filtered projection of `GroundingPack.evidence`, not ad hoc source-parsing
formats, once the canonical pack is available from the API.

### 6.2 Admin Review and Operations

The grounded-build review queue and operator build-evidence surface may
summarize coverage and risk from the `GroundingPack`, but they do not replace
the claim-and-evidence contract itself.

### 6.3 Publication Gating

`PublicationPackage` may aggregate grounding readiness from one or more
`GroundingPack` objects, but it must not flatten away unsupported-claim state.

## 7. JSON Example

```json
{
  "id": "gpk_course-1_lesson-2",
  "versionId": "gpkv_course-1_lesson-2_2026-04-10T00:00:00Z",
  "scope": {
    "kind": "course_lesson",
    "courseId": "course-1",
    "lessonId": "lesson-2",
    "lessonTitle": "Supervised learning foundations"
  },
  "sourceBundleRefs": [
    {
      "bundleId": "lsb_course-1",
      "bundleVersionId": "lsbv_course-1_2026-04-10T00:00:00Z",
      "posture": "approved"
    }
  ],
  "status": "assembled",
  "supportSummary": {
    "claimCount": 2,
    "supportedClaimCount": 2,
    "unsupportedClaimCount": 0,
    "supportCoveragePercent": 100,
    "evidenceCount": 2,
    "learnerVisibleSourceCount": 2,
    "missingSupportReasons": []
  },
  "claims": [
    {
      "id": "gcl_lesson-2_1",
      "label": "Definition",
      "claimText": "Supervised learning uses labeled examples to map inputs to outputs.",
      "claimType": "lesson_explanation",
      "supportStatus": "supported",
      "evidenceIds": ["gev_lesson-2_1"],
      "learnerVisible": true
    }
  ],
  "evidence": [
    {
      "id": "gev_lesson-2_1",
      "sourceMaterialId": "lsa_course-1_src-1",
      "label": "Recursion concept guide",
      "kind": "lesson",
      "url": "https://example.edu/ml/supervised-learning",
      "locator": "Section 2.1",
      "excerpt": "Labeled examples provide the target output used during training.",
      "summary": "Core definition used in the lesson explanation.",
      "citationConfidence": "high",
      "learnerVisible": true
    }
  ],
  "governance": {
    "sourceOfRecord": "sophia",
    "consumingDomain": "metis",
    "reviewQueueType": "grounded_build",
    "rightsChecked": true,
    "auditTrailRequired": true,
    "learnerDisclosureRequired": true
  },
  "createdAt": "2026-04-10T00:00:00Z",
  "updatedAt": "2026-04-10T00:00:00Z"
}
```

## 8. Non-Goals

`GroundingPack` does not define:

- raw source-ingestion mechanics
- course assembly order or module structure
- media-render bundles
- tutor pedagogy strategy
- publication approval workflow state in full

Those belong to adjacent Metis contracts.

## 9. Completion Rule for `V1-MET-050`

`V1-MET-050` is complete only when:

1. `GroundingPack` is defined as the canonical evidence package between source
   bundles and grounded outputs.
2. The contract explicitly maps to current Metis lesson, tutor, assessment, and
   operator evidence seams.
3. Governance and invariants prevent unsupported outputs from being mislabeled
   as grounded.
