# OSHUN V1 Release Event Taxonomy

Status: Canonical Date: 2026-04-26 Owners: OSHUN Model Operations, OSHUN
Editorial, OSHUN Rights, OSHUN Compliance, OSHUN Platform Engineering Tracks:
`V1-OBS-005` from `OSHUN_V1_TODOS.md` Spec source:
`libs/oshun/analytics/src/release-taxonomy.ts`

This document is the canonical, human-readable companion to the machine-readable
V1 release event taxonomy in `@oshun/analytics`.

The machine-readable taxonomy is the single source of truth. Any divergence
between this document and `release-taxonomy.ts` is a bug in this document —
follow the code.

---

## 1. Scope

This taxonomy defines every analytics event in the model intake/promotion
lifecycle, the media release pipeline, and the release-readiness gates that
govern production rollout — covering V1-OBS-005's "model intake, promotion, and
media release gates" mandate end to end.

Pairs with:

- the customer taxonomy (`customer-taxonomy.ts`, V1-OBS-001)
- the admin taxonomy (`admin-taxonomy.ts`, V1-OBS-002)
- the assistant taxonomy (`assistant-taxonomy.ts`, V1-OBS-003)
- the flows taxonomy (`flows-taxonomy.ts`, V1-OBS-004)

Event entity vocabulary:

- `oshun.model_intake.*` — intake submission and validation
- `oshun.model_card.*`, `oshun.model_version.*` — lifecycle transitions
- `oshun.model_promotion_gate.*` — promotion gates
- `oshun.eval_run.*` — eval runs that feed promotion gates
- `oshun.provenance_bundle.*` — provenance lifecycle
- `oshun.rights_inspection.*` — rights and takedown handling
- `oshun.media_generation.*` — media generation jobs
- `oshun.media_release.*` — media release lifecycle
- `oshun.release_readiness.*` — go/no-go release-readiness gates

Out-of-scope:

- customer surface events (V1-OBS-001)
- admin operator events outside the model/media-release scope (V1-OBS-002)
- assistant interactions (V1-OBS-003)
- review/moderation/appeal/incident lifecycle (V1-OBS-004)

Consistent with:

- ADR-0006 — analytics taxonomy and event naming
- ADR-0023 — admin audit and compliance surfaces
- ADR-0029 — review and approval workflows
- `libs/contracts/src/common/model-card.ts`
- `libs/contracts/src/common/model-version.ts`
- `libs/contracts/src/common/provenance-bundle.ts`
- `libs/contracts/src/common/admin-rights-provenance.ts`
- `libs/contracts/src/common/publication-release-gate.ts`
- `libs/contracts/src/common/admin-release-readiness-decision.ts`

---

## 2. Naming and envelope

Names follow `<namespace>.<entity>.<action>` per ADR-0006. All events use the
`oshun.*` namespace. Property names are snake_case. PII is never sent.

Tenant scoping is mandatory on every event (`tenant_id`).

`consentRequired` and `complianceMandatory` are intentionally omitted from the
schema: every event in this taxonomy is operational/governance telemetry. These
signals are recorded regardless of customer consent.

---

## 3. Surfaces

| Surface                    | Description                                               |
| -------------------------- | --------------------------------------------------------- |
| `admin_models`             | Admin model and workflow operations workspace.            |
| `admin_personas`           | Admin personas workspace (persona-pack provenance).       |
| `admin_review`             | Admin review workspace (release-readiness reviews).       |
| `admin_rights`             | Admin rights and provenance workspace.                    |
| `admin_trust_safety`       | Admin trust & safety workspace.                           |
| `admin_editorial`          | Admin editorial workspace (media release approval).       |
| `admin_research_integrity` | Admin research integrity workspace (notebook provenance). |
| `release_bff`              | Release BFF service.                                      |
| `release_background`       | Release background workers (eval runs, gate evaluators).  |
| `release_studio`           | Studio plane (model training, eval suites).               |

---

## 4. Families

| Family                 | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `model_intake`         | Submission, validation, registration of new models. |
| `model_lifecycle`      | ModelCard / ModelVersion status, deploy, rollback.  |
| `model_promotion_gate` | Gate evaluations and waivers for model promotion.   |
| `eval_run`             | Eval runs feeding promotion gates.                  |
| `provenance_bundle`    | ProvenanceBundle lifecycle and state transitions.   |
| `rights_inspection`    | Rights inspection and takedown lifecycle.           |
| `media_generation`     | Media generation jobs.                              |
| `media_release`        | Media release request, gates, publish, recall.      |
| `release_readiness`    | Admin go/no-go release-readiness gates.             |

---

## 5. Contract enum mirrors

Every status transition event reuses the canonical enum from the corresponding
contract:

- `oshun.model_card.status_changed` — `OSHUN_V1_MODEL_CARD_STATUSES` mirrors
  `ModelCard.Status`.
- `oshun.model_version.status_changed` — `OSHUN_V1_MODEL_VERSION_STATUSES`
  mirrors `ModelVersion.Status`.
- `oshun.model_version.deployed` — `OSHUN_V1_MODEL_ENVIRONMENTS` mirrors
  `ModelVersion.environment`.
- `oshun.model_version.health_changed` — `OSHUN_V1_MODEL_DEPLOYMENT_HEALTHS`
  mirrors `ModelVersion.DeploymentHealth`.
- `oshun.model_promotion_gate.decision_recorded` —
  `OSHUN_V1_MODEL_PROMOTION_DECISIONS` mirrors
  `ModelCard/Version.PromotionDecision`.
- `oshun.provenance_bundle.*` — subject-type, release-state, watermark, and
  disclosure enums mirror `ProvenanceBundle.*` enums.
- `oshun.rights_inspection.*` — inspection-status and takedown-status enums
  mirror `admin-rights-provenance.ts`.
- `oshun.media_release.gate_evaluated` — `OSHUN_V1_PUBLICATION_GATE_STATUSES`
  mirrors `publication-release-gate.ts` `Status`.
- `oshun.release_readiness.*` — gate status, decision, and tier enums mirror
  `admin-release-readiness-decision.ts`.

Tests in `release-taxonomy.test.ts` lock these constants verbatim.

---

## 6. ADR-0029 / ADR-0023 alignment

- Promotion-gate events emit the ADR-0029 stage outcomes via the
  `OSHUN_V1_RELEASE_READINESS_GATE_STATUSES` enum (`passing`, `warning`,
  `failing`, `waived`, `unknown`).
- `oshun.model_promotion_gate.waived` and `oshun.release_readiness.gate_waived`
  carry stable waiver-reason classifiers, satisfying ADR-0023's "Compliance
  review §exceptions" rule that every waiver be auditable with a stable reason.

---

## 7. Governance

### 7.1 Amendments

Adding, changing, or deprecating a release event requires:

1. updating `release-taxonomy.ts` with the new or changed entry
2. updating tests (lock-style tests fail closed if entries drift)
3. updating this document if the change is structurally significant
4. signoff from Model Operations, Editorial, Rights, and Compliance leads, plus
   platform analytics

### 7.2 Versioning

Same rules as the sibling taxonomies.

### 7.3 PII

No PII appears in any release-event property. Identifiers are stable (intake_id,
model_id, model_version, eval_run_id, bundle_id, inspection_id, takedown_id,
generation_id, release_id, readiness_id); free-form content (prompts,
narratives, license text) never appears.

---

## 8. Out-of-scope

- customer surface events (V1-OBS-001)
- admin operator events outside the release scope (V1-OBS-002)
- assistant interactions (V1-OBS-003)
- review/moderation/appeal/incident lifecycle (V1-OBS-004)

---

## 9. Change log

- 2026-04-26 — Initial canonical V1 release event taxonomy published alongside
  `libs/oshun/analytics/src/release-taxonomy.ts` (V1-OBS-005).
