# OSHUN V1 Metis `PublicationPackage` Contract

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.
