# OSHUN V1 Metis `VoiceLikenessConsentRecord` Contract

Status: Active

Date: April 10, 2026

Owners: OSHUN Metis Engineering, OSHUN Psyche, OSHUN Aja, OSHUN Safety, OSHUN
Legal and Rights Governance

Related:

- `docs/releases/v1/specs/metis-avatar-teacher-profile-contract.md`
- `docs/releases/v1/specs/metis-media-runtime-tiers.md`
- `docs/releases/v1/reports/metis-v1-scorecard.md`
- `docs/releases/v1/specs/todos.md`
- `services/psyche/voice-engine/src/voice_engine/tts/voice_cloning.py`
- `libs/aja/consent-management/src/types.ts`
- `services/metis/src/metis/services/admin_service.py`

## 1. Purpose

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

Metis currently reviews generic likeness-consent records and Psyche voice-clone
consents separately, but the educational product still lacks one explicit record
that answers:

- whose voice or recognizable vocal likeness is involved
- who granted the permission
- what Metis teacher modes are allowed
- what territories, durations, and surfaces are allowed
- what must happen when consent expires or is revoked

`VoiceLikenessConsentRecord` is the Metis-owned rights-and-safety record for
voice and vocal-likeness use in teacher representations.

## 2. Contract Role in the Media Stack

Order of responsibility:

1. Aja owns generic consent primitives.
2. Psyche owns low-level `VoiceConsent` and clone provisioning checks.
3. Metis owns the educational consent record that governs teacher voice use
   across tutoring and lecture modes.

Rule:

- A voice pack must not ship into Metis teacher experiences without at least one
  active `VoiceLikenessConsentRecord` that covers the intended use.

## 3. Canonical Contract

### 3.1 Identity

```ts
type VoiceLikenessConsentRecordId = `vlcr_${string}`;
type VoiceLikenessConsentVersionId = `vlcrv_${string}`;
type VoicePackRefId = string;
type AvatarTeacherProfileRefId = string;
```

### 3.2 Top-Level Shape

```ts
interface VoiceLikenessConsentRecord {
  id: VoiceLikenessConsentRecordId;
  versionId: VoiceLikenessConsentVersionId;
  subject: VoiceLikenessConsentSubject;
  grant: VoiceLikenessConsentGrant;
  scope: VoiceLikenessConsentScope;
  verification: VoiceLikenessConsentVerification;
  linkedAssets: VoiceLikenessLinkedAssets;
  lifecycle: VoiceLikenessConsentLifecycle;
  createdAt: string;
  updatedAt: string;
}
```

### 3.3 Subject

```ts
interface VoiceLikenessConsentSubject {
  subjectId: string;
  subjectType: 'natural_person' | 'rights_holder' | 'institutional_program';
  displayName: string;
  sourceIdentityReference: string | null;
  likenessKinds: ('voice' | 'speech_pattern' | 'name_and_voice_association')[];
}
```

### 3.4 Grant

```ts
interface VoiceLikenessConsentGrant {
  grantedById: string;
  grantRelationship:
    | 'self'
    | 'legal_guardian'
    | 'rights_holder'
    | 'institutional_delegate';
  consentStatus: 'granted' | 'pending' | 'revoked' | 'expired' | 'denied';
  collectionMethod:
    | 'written'
    | 'signature'
    | 'verbal_recording'
    | 'api'
    | 'form';
  allowedUses: (
    | 'live_voice_tutor'
    | 'live_avatar_tutor'
    | 'prerecorded_lecturer'
    | 'multilingual_dubbing'
    | 'captioned_export'
  )[];
  prohibitedUses: (
    | 'marketing'
    | 'general_voice_clone_marketplace'
    | 'cross_domain_reuse'
    | 'third_party_training'
  )[];
  restrictions: string[];
}
```

### 3.5 Scope

```ts
interface VoiceLikenessConsentScope {
  territoryScope: string[] | 'global';
  productScope: ('metis_only' | 'oshun_multi_domain')[];
  organizationScopeIds: string[];
  expiresAt: string | null;
  reviewByAt: string | null;
  revocationPropagationRequired: boolean;
}
```

### 3.6 Verification

```ts
interface VoiceLikenessConsentVerification {
  verified: boolean;
  verificationMethod:
    | 'signature'
    | 'biometric'
    | 'email'
    | 'institutional_attestation';
  verifiedAt: string | null;
  verifierId: string | null;
  evidenceReferences: string[];
}
```

### 3.7 Linked Assets

```ts
interface VoiceLikenessLinkedAssets {
  voicePackIds: VoicePackRefId[];
  avatarTeacherProfileIds: AvatarTeacherProfileRefId[];
  psycheVoiceConsentIds: string[];
}
```

### 3.8 Lifecycle

```ts
interface VoiceLikenessConsentLifecycle {
  active: boolean;
  revokedAt: string | null;
  revokedById: string | null;
  revocationReason: string | null;
  auditTrailRequired: boolean;
  operatorReviewRequired: boolean;
}
```

## 4. Required Invariants

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

1. If `grant.consentStatus === 'granted'`, `verification.verified` must be
   `true`.
2. If `grant.allowedUses` contains `live_avatar_tutor`, it must also permit
   either `live_voice_tutor` or explicitly reference a linked avatar teacher
   profile in `linkedAssets.avatarTeacherProfileIds`.
3. `linkedAssets.voicePackIds` must be non-empty for any consent record used to
   ship a voice pack.
4. If `scope.expiresAt` is in the past, `grant.consentStatus` must be `expired`
   or `lifecycle.active` must be `false`.
5. If `lifecycle.revokedAt` is non-null, `lifecycle.active` must be `false`.
6. `grant.prohibitedUses` must include `third_party_training` unless the record
   explicitly states otherwise in `grant.restrictions` and passes separate legal
   review.
7. `scope.productScope` must include `metis_only` unless cross-domain reuse was
   explicitly approved.

## 5. Mapping to Existing Runtime Truth

`VoiceLikenessConsentRecord` aligns existing seams that are currently split
across systems:

| `VoiceLikenessConsentRecord` field                                   | Existing seam                                                                                              |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `grant.collectionMethod`, `scope.*`, and verification posture        | `libs/aja/consent-management/src/types.ts`                                                                 |
| `linkedAssets.psycheVoiceConsentIds` and voice-clone consent details | `services/psyche/voice-engine/src/voice_engine/tts/voice_cloning.py`                                       |
| `linkedAssets.voicePackIds` and educational runtime release review   | Metis admin `voice_pack` review queue in `services/metis/src/metis/services/admin_service.py`              |
| operator review and blocker posture                                  | Metis admin `likeness_consent_record` review queue in `services/metis/src/metis/services/admin_service.py` |

## 6. Consumer Rules

### 6.1 Voice Pack Approval

A voice pack may not move to approved Metis release unless all linked
`VoiceLikenessConsentRecord` objects are active and cover the intended product
tier.

### 6.2 Avatar Teacher Approval

An `AvatarTeacherProfile` that references a consent-bound voice pack must
inherit the linked consent record as a release dependency.

### 6.3 Revocation

When `lifecycle.active` becomes `false`, Metis must treat linked voice packs and
avatar teacher profiles as blocked or restricted until a replacement consent
record is attached and reviewed.

## 7. Ownership Boundary

Metis owns:

- educational-use allow lists
- release blocking and revocation propagation
- linkage from consent to teacher profiles and voice packs

Aja owns:

- generic consent primitives and broad consent taxonomy

Psyche owns:

- low-level voice clone consent checks
- clone lifecycle and provider integration

## 8. Implementation Direction

`V1-MET-090` is complete when Metis docs, review flows, and future runtime
models use `VoiceLikenessConsentRecord` as the canonical consent object for
teacher voice use instead of treating generic consent rows and Psyche
`VoiceConsent` entries as sufficient on their own.
