Eve library

OSHUN V1 Metis `PublicationPackage` Contract

Spec

Revision 1

On this page

Status: Active

Date: April 10, 2026

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

Related:

  • docs/releases/v1/specs/metis-learning-source-bundle-contract.md
  • docs/releases/v1/specs/metis-grounding-pack-contract.md
  • docs/releases/v1/specs/metis-course-build-contract.md
  • docs/releases/v1/specs/metis-lesson-asset-bundle-contract.md
  • docs/releases/v1/reports/metis-v1-scorecard.md
  • docs/releases/v1/runbooks/metis-operator-workflows-runbook.md
  • docs/releases/v1/specs/todos.md
  • services/metis/src/metis/services/admin_service.py
  • services/metis/src/metis/schemas/admin.py
  • apps/metis/admin/src/types/admin.ts
  • apps/metis/web/src/lib/authoring-data.ts
  • apps/metis/web/src/app/create/page.tsx

1. Purpose#

This document defines the canonical PublicationPackage contract for Metis V1.

PublicationPackage is the governed release object that determines whether a course build can be shipped into learner-facing channels and exports.

It is the contract that bundles:

  • the release candidate course build
  • the approved lesson-delivery bundles
  • the learner-facing assessments
  • rights, grounding, and provenance posture
  • channel and export eligibility
  • review decisions, release notes, and rollback references

If CourseBuild defines what Metis assembled and LessonAssetBundle defines what a lesson delivers, PublicationPackage defines what is actually approved to ship.

2. Contract Role in the Metis Pipeline#

Contract order:

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

Responsibility rule:

  • CourseBuild governs educational structure.
  • LessonAssetBundle governs lesson payload delivery.
  • PublicationPackage governs release readiness, distribution scope, export eligibility, and operational rollback.

PublicationPackage must reference approved upstream artifacts. It must not reconstruct release state from raw lessons or review queue summaries alone.

3. Design Constraints#

PublicationPackage must satisfy all of the following:

  1. It must encode the same release blockers currently surfaced through Metis review queues, source-rights review, and export-failure monitoring.
  2. It must distinguish in-product publication from export eligibility, because some courses may be renderable but not downloadable or distributable.
  3. It must support channel targeting across web, mobile, PWA, shell preview, and governed exports.
  4. It must preserve enough governance history to explain who approved the release, under what posture, and how to roll it back.
  5. It must remain compatible with the current live Metis behavior where a publication approval changes the learner-visible course status.

4. Canonical Contract#

4.1 Identity#

ts
type PublicationPackageId = `pp_${string}`;
type PublicationPackageVersionId = `ppv_${string}`;
type PublicationReleaseId = `pr_${string}`;
type PublicationPackageAssessmentId = `ppa_${string}`;

Identity rule:

  • The package ID is stable for the course’s release lineage.
  • The version ID changes whenever learner-visible release composition, distribution rules, rights posture, or approval evidence changes.
  • The release ID changes on each distinct launch, relaunch, rollback, or superseding shipment event.

4.2 Top-Level Shape#

ts
interface PublicationPackage {
  id: PublicationPackageId;
  versionId: PublicationPackageVersionId;
  releaseId: PublicationReleaseId;
  course: PublicationCourseRef;
  courseBuildRef: PublicationCourseBuildRef;
  lessonBundles: PublicationLessonBundleRef[];
  assessments: PublicationAssessmentRef[];
  sourceBundleRefs: PublicationSourceBundleRef[];
  groundingPackRefs: PublicationGroundingPackRef[];
  readiness: PublicationReadiness;
  distribution: PublicationDistribution;
  export: PublicationExportState;
  governance: PublicationGovernance;
  releaseHistory: PublicationReleaseRecord[];
  createdAt: string;
  updatedAt: string;
}

4.3 Course and Build References#

ts
interface PublicationCourseRef {
  courseId: string;
  slug: string;
  title: string;
  ownerId: string;
  ownerName: string | null;
  courseStatus: 'draft' | 'review' | 'published' | 'archived';
  category: string;
  difficulty: 'beginner' | 'intermediate' | 'advanced' | 'expert';
}

interface PublicationCourseBuildRef {
  courseBuildId: string;
  courseBuildVersionId: string;
  reviewStatus: 'draft' | 'review' | 'publish_ready' | 'published';
  sourceCoveragePercent: number;
  groundedLessonPercent: number;
  assessmentSupportPercent: number;
  releaseReadinessPercent: number;
}

Reference rule:

  • Every PublicationPackage must reference exactly one CourseBuild version.
  • A package may include only lesson bundles and assessments derived from that course build lineage.

4.4 Lesson and Assessment Composition#

ts
interface PublicationLessonBundleRef {
  lessonBundleId: string;
  lessonBundleVersionId: string;
  lessonId: string;
  moduleId: string;
  title: string;
  isPublished: boolean;
  isFreePreview: boolean;
  previewMode: 'none' | 'metadata_only' | 'partial_content' | 'full_lesson';
  evidencePosture: 'approved' | 'partial' | 'unsupported' | 'hidden';
  exportAllowed: boolean;
}

interface PublicationAssessmentRef {
  assessmentId: PublicationPackageAssessmentId;
  sourceAssessmentId: string;
  title: string;
  type: 'quiz' | 'exam' | 'assignment' | 'practice';
  isPublished: boolean;
  questionCount: number;
  supportPosture: 'approved' | 'partial' | 'unsupported';
}

Composition rule:

  • A package is incomplete if any required lesson or assessment from the chosen course build is missing from these arrays.
  • Preview settings in the package must match the referenced LessonAssetBundle versions for that release.

4.5 Source and Grounding References#

ts
interface PublicationSourceBundleRef {
  bundleId: string;
  bundleVersionId: string;
  approvalStatus: 'approved' | 'review_only' | 'blocked';
  rightsPosture: 'cleared' | 'needs_review' | 'blocked';
  provenancePosture: 'verified' | 'partial' | 'weak' | 'missing';
}

interface PublicationGroundingPackRef {
  groundingPackId: string;
  groundingPackVersionId: string;
  scopeKind:
    | 'course_lesson'
    | 'assessment_question'
    | 'tutor_answer'
    | 'study_artifact'
    | 'build_summary';
  supportStatus: 'approved' | 'partial' | 'unsupported' | 'revoked';
}

Reference rule:

  • A release-grade package may not include blocked source bundles.
  • A package may carry partial or unsupported grounding refs only when the package readiness explicitly records that limitation and distribution policy allows it.

4.6 Readiness#

ts
interface PublicationReadiness {
  status:
    | 'draft'
    | 'pending_review'
    | 'approved'
    | 'released'
    | 'paused'
    | 'rolled_back'
    | 'rejected';
  blockerCount: number;
  blockers: string[];
  warnings: string[];
  reviewFocus: string[];
  lessonCoveragePercent: number;
  assessmentCoveragePercent: number;
  exportReadinessPercent: number;
  launchReadinessPercent: number;
  learnerImpactSummary: string;
}

Readiness rule:

  • launchReadinessPercent is the package-level decision metric for learner release.
  • exportReadinessPercent is separate and may be lower than launch readiness.
  • blockerCount must equal blockers.length.

4.7 Distribution#

ts
interface PublicationDistribution {
  channels: Array<'web' | 'mobile' | 'pwa' | 'shell_preview' | 'api_export'>;
  releaseStage:
    | 'internal'
    | 'preview'
    | 'general_availability'
    | 'limited_rollout';
  geographicPolicy: 'global' | 'institution_limited' | 'contract_limited';
  enrollmentPolicy: 'open' | 'invite_only' | 'institution_managed';
  discoverability: 'listed' | 'unlisted' | 'hidden';
  releaseNotes: string | null;
  rollbackTargetReleaseId: string | null;
}

Distribution rule:

  • shell_preview may be enabled without full listed discoverability.
  • api_export requires export readiness and rights posture consistent with the export block state.

4.8 Export State#

ts
interface PublicationExportState {
  allowed: boolean;
  blockedReason: string | null;
  downloadableArtifacts: PublicationArtifactRef[];
  citationExportIncluded: boolean;
  learnerArtifactTypes: Array<
    | 'study_guide'
    | 'worksheet'
    | 'slides'
    | 'dataset'
    | 'starter_code'
    | 'solution'
  >;
}

interface PublicationArtifactRef {
  label: string;
  kind:
    | 'course_outline'
    | 'lesson_notes'
    | 'study_guide'
    | 'worksheet'
    | 'citation_export'
    | 'assessment_review'
    | 'certificate_template';
  url: string | null;
  rightsChecked: boolean;
}

Export rule:

  • allowed must be false whenever source rights or provenance posture remain blocking for any exported artifact.
  • citationExportIncluded may be true only when learner-safe evidence exposure has been approved.

4.9 Governance#

ts
interface PublicationGovernance {
  reviewQueueType: 'publication_package';
  rightsReviewRequired: boolean;
  groundedBuildApprovalRequired: boolean;
  learnerDisclosureRequired: boolean;
  auditTrailRequired: boolean;
  approvedBy: string | null;
  approvedAt: string | null;
  latestDecision: 'approve' | 'request_changes' | 'reject' | null;
}

interface PublicationReleaseRecord {
  releaseId: PublicationReleaseId;
  action:
    | 'created'
    | 'approved'
    | 'released'
    | 'paused'
    | 'rolled_back'
    | 'superseded';
  actor: string;
  summary: string;
  happenedAt: string;
}

Governance rule:

  • A released package must always have approvedBy, approvedAt, and latestDecision === 'approve'.
  • Rollback and supersedure events must append new release-history records rather than mutating prior history away.

5. Required Invariants#

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

  1. readiness.blockerCount === readiness.blockers.length.
  2. lessonCoveragePercent, assessmentCoveragePercent, exportReadinessPercent, and launchReadinessPercent are integers from 0 to 100.
  3. If readiness.status === 'released', distribution.channels.length must be greater than 0.
  4. If distribution.channels includes api_export, export.allowed must be true.
  5. If any sourceBundleRefs[*].approvalStatus === 'blocked', readiness.status may not be approved or released.
  6. If any required lesson bundle has isPublished === false, readiness.status may not be released.
  7. If any assessment has isPublished === false, assessmentCoveragePercent must be less than 100.
  8. If readiness.status === 'rolled_back', distribution.rollbackTargetReleaseId must not be null.

6. Mapping to Existing Runtime Truth#

PublicationPackage formalizes already-live Metis release signals:

PublicationPackage field Existing seam
course.*, courseBuildRef.*, readiness.blockers, reviewFocus, readiness percentages publication queue derivation and review metrics in services/metis/src/metis/services/admin_service.py
governance.*, releaseHistory publication review decisions and audit recording in admin_service.py and services/metis/src/metis/schemas/admin.py
distribution.* current authoring publish controls and course status transitions in apps/metis/web/src/app/create/page.tsx, apps/metis/web/src/lib/authoring-data.ts, and admin_service.py
export.* export-failure monitoring, learner export/download surfaces, and rights-linked blockers in admin_service.py
lessonBundles.* the lesson publish and preview state now normalized by LessonAssetBundle and the live lesson/course schemas

7. Downstream Consumer Rules#

7.1 Admin Review#

The Metis admin review queue for publication_package should summarize and operate on PublicationPackage, not invent an incompatible release schema.

7.2 Learner Runtime#

Learner clients should never see a lesson, assessment, or export artifact that is absent from the active released PublicationPackage for the course.

7.3 Authoring#

Authoring flows may stage draft publication projections, but final publication state should resolve into PublicationPackage rather than direct course-status mutation without package metadata.

7.4 Operations and Incident Response#

Monitoring, complaints, incident command, and source-rights workspaces should link back to PublicationPackage when the issue is about release posture rather than raw course structure.

8. JSON Example#

json
{
  "id": "pp_course-1",
  "versionId": "ppv_course-1_2026-04-10T00:00:00Z",
  "releaseId": "pr_course-1_ga_001",
  "course": {
    "courseId": "course-1",
    "slug": "introduction-to-machine-learning",
    "title": "Introduction to Machine Learning",
    "ownerId": "instructor-1",
    "ownerName": "Amara Osei",
    "courseStatus": "published",
    "category": "Computer Science",
    "difficulty": "beginner"
  },
  "courseBuildRef": {
    "courseBuildId": "cb_course-1",
    "courseBuildVersionId": "cbv_course-1_2026-04-10T00:00:00Z",
    "reviewStatus": "published",
    "sourceCoveragePercent": 92,
    "groundedLessonPercent": 89,
    "assessmentSupportPercent": 100,
    "releaseReadinessPercent": 94
  },
  "lessonBundles": [
    {
      "lessonBundleId": "lab_course-1_lesson-1",
      "lessonBundleVersionId": "labv_course-1_lesson-1_2026-04-10T00:00:00Z",
      "lessonId": "lesson-1",
      "moduleId": "module-1",
      "title": "What Makes a Model Learn?",
      "isPublished": true,
      "isFreePreview": true,
      "previewMode": "partial_content",
      "evidencePosture": "approved",
      "exportAllowed": true
    },
    {
      "lessonBundleId": "lab_course-1_lesson-2",
      "lessonBundleVersionId": "labv_course-1_lesson-2_2026-04-10T00:00:00Z",
      "lessonId": "lesson-2",
      "moduleId": "module-1",
      "title": "Features, Labels, and Outcomes",
      "isPublished": true,
      "isFreePreview": false,
      "previewMode": "none",
      "evidencePosture": "approved",
      "exportAllowed": true
    }
  ],
  "assessments": [
    {
      "assessmentId": "ppa_course-1_quiz-1",
      "sourceAssessmentId": "quiz-1",
      "title": "Core concepts quiz",
      "type": "quiz",
      "isPublished": true,
      "questionCount": 8,
      "supportPosture": "approved"
    }
  ],
  "sourceBundleRefs": [
    {
      "bundleId": "lsb_course-1",
      "bundleVersionId": "lsbv_course-1_2026-04-10T00:00:00Z",
      "approvalStatus": "approved",
      "rightsPosture": "cleared",
      "provenancePosture": "verified"
    }
  ],
  "groundingPackRefs": [
    {
      "groundingPackId": "gpk_course-1_lesson-1",
      "groundingPackVersionId": "gpkv_course-1_lesson-1_2026-04-10T00:00:00Z",
      "scopeKind": "course_lesson",
      "supportStatus": "approved"
    }
  ],
  "readiness": {
    "status": "released",
    "blockerCount": 0,
    "blockers": [],
    "warnings": ["One lesson is still preview-only in shell marketing mode."],
    "reviewFocus": [
      "Confirm export posture stays aligned with rights coverage.",
      "Watch tutoring escalations for grounding drift after release."
    ],
    "lessonCoveragePercent": 100,
    "assessmentCoveragePercent": 100,
    "exportReadinessPercent": 91,
    "launchReadinessPercent": 94,
    "learnerImpactSummary": "Ready for learner release across web, mobile, and PWA."
  },
  "distribution": {
    "channels": ["web", "mobile", "pwa", "shell_preview", "api_export"],
    "releaseStage": "general_availability",
    "geographicPolicy": "global",
    "enrollmentPolicy": "open",
    "discoverability": "listed",
    "releaseNotes": "Publishes the grounded lesson bundles and assessment package for general learners.",
    "rollbackTargetReleaseId": null
  },
  "export": {
    "allowed": true,
    "blockedReason": null,
    "downloadableArtifacts": [
      {
        "label": "Course outline PDF",
        "kind": "course_outline",
        "url": "https://cdn.metis.example/course-1/outline.pdf",
        "rightsChecked": true
      },
      {
        "label": "Grounded references export",
        "kind": "citation_export",
        "url": "https://cdn.metis.example/course-1/sources.json",
        "rightsChecked": true
      }
    ],
    "citationExportIncluded": true,
    "learnerArtifactTypes": ["study_guide", "worksheet", "slides"]
  },
  "governance": {
    "reviewQueueType": "publication_package",
    "rightsReviewRequired": true,
    "groundedBuildApprovalRequired": true,
    "learnerDisclosureRequired": true,
    "auditTrailRequired": true,
    "approvedBy": "Metis Release Council",
    "approvedAt": "2026-04-10T00:00:00Z",
    "latestDecision": "approve"
  },
  "releaseHistory": [
    {
      "releaseId": "pr_course-1_ga_001",
      "action": "approved",
      "actor": "Metis Release Council",
      "summary": "Package approved for learner release.",
      "happenedAt": "2026-04-10T00:00:00Z"
    },
    {
      "releaseId": "pr_course-1_ga_001",
      "action": "released",
      "actor": "Metis Release Automation",
      "summary": "Package shipped to learner channels.",
      "happenedAt": "2026-04-10T00:15:00Z"
    }
  ],
  "createdAt": "2026-04-10T00:00:00Z",
  "updatedAt": "2026-04-10T00:15:00Z"
}

9. Completion Rule#

Metis should treat PublicationPackage as the canonical release contract for V1. Future publication review, launch gating, export decisions, audit trails, and rollback controls should converge on this object rather than continuing to spread release truth across queue summaries, course status flags, and ad hoc monitoring derivations.