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.mddocs/releases/v1/reports/metis-subsystem-ownership-matrix.mddocs/releases/v1/reports/metis-v1-scorecard.mddocs/releases/v1/specs/todos.mdapps/metis/web/src/lib/grounded-sources.tsapps/metis/web/src/types/index.tsservices/metis/src/metis/services/admin_service.pyapps/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:
LearningSourceBundleGroundingPackCourseBuildLessonAssetBundlePublicationPackage
Pipeline rule:
LearningSourceBundlegoverns source scope and rights posture.GroundingPackgoverns evidence selection, support coverage, and claim-to-source traceability.CourseBuildgoverns educational assembly.
GroundingPack must not invent source materials outside the approved
LearningSourceBundle versions it references.
3. Canonical Contract#
3.1 Identity#
type GroundingPackId = `gpk_${string}`;
type GroundingPackVersionId = `gpkv_${string}`;
type GroundingEvidenceId = `gev_${string}`;
type GroundingClaimId = `gcl_${string}`;
3.2 Top-Level Shape#
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#
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#
interface GroundingSourceBundleRef {
bundleId: string;
bundleVersionId: string;
posture: 'approved' | 'review_only' | 'blocked';
}
Rule:
- Every
GroundingPackmust reference at least one source bundle version. - Any referenced bundle with posture other than
approvedprevents release-grade downstream use.
3.5 Status#
type GroundingPackStatus =
| 'draft'
| 'assembled'
| 'partial'
| 'unsupported'
| 'approved'
| 'superseded'
| 'revoked';
Status rule:
assembledmeans evidence selection exists but operator or policy approval is not yet implied.partialmeans some claims or educational segments lack adequate support.unsupportedmeans the pack may explain missing support but may not be marketed as grounded.
3.6 Support Summary#
interface GroundingSupportSummary {
claimCount: number;
supportedClaimCount: number;
unsupportedClaimCount: number;
supportCoveragePercent: number;
evidenceCount: number;
learnerVisibleSourceCount: number;
missingSupportReasons: string[];
}
3.7 Claims#
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, orunsupported. - Empty evidence references are valid only when
supportStatus !== 'supported'.
3.8 Evidence#
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:
GroundingEvidenceis the canonical form behind today’sgroundedSourcespayloads.- Learner clients may receive a filtered projection of evidence, but they must
not need to parse raw source metadata strings when a
GroundingPackexists.
3.9 Governance#
interface GroundingGovernance {
sourceOfRecord: 'sophia';
consumingDomain: 'metis';
reviewQueueType: 'grounded_build';
rightsChecked: boolean;
auditTrailRequired: boolean;
learnerDisclosureRequired: boolean;
}
Governance rule:
- A
GroundingPackis not publishable ifrightsCheckedis false. - If any evidence is learner-visible,
learnerDisclosureRequiredmust be true.
4. Required Invariants#
The contract is invalid if any of the following are false:
supportSummary.claimCount === claims.length.supportSummary.evidenceCount === evidence.length.supportSummary.supportCoveragePercentis an integer from0to100.supportedClaimCount + unsupportedClaimCountmay be less thanclaimCountonly when partial claims exist.- If
status === 'approved', every referenced source bundle must have postureapproved. - If a claim has
supportStatus === 'supported',evidenceIds.lengthmust be greater than0. - 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#
{
"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:
GroundingPackis defined as the canonical evidence package between source bundles and grounded outputs.- The contract explicitly maps to current Metis lesson, tutor, assessment, and operator evidence seams.
- Governance and invariants prevent unsupported outputs from being mislabeled as grounded.