Eve library

OSHUN V1 Metis `GroundingPack` Contract

Spec

Revision 1

On this page

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.