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 validationoshun.model_card.*,oshun.model_version.*— lifecycle transitionsoshun.model_promotion_gate.*— promotion gatesoshun.eval_run.*— eval runs that feed promotion gatesoshun.provenance_bundle.*— provenance lifecycleoshun.rights_inspection.*— rights and takedown handlingoshun.media_generation.*— media generation jobsoshun.media_release.*— media release lifecycleoshun.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.tslibs/contracts/src/common/model-version.tslibs/contracts/src/common/provenance-bundle.tslibs/contracts/src/common/admin-rights-provenance.tslibs/contracts/src/common/publication-release-gate.tslibs/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_STATUSESmirrorsModelCard.Status.oshun.model_version.status_changed—OSHUN_V1_MODEL_VERSION_STATUSESmirrorsModelVersion.Status.oshun.model_version.deployed—OSHUN_V1_MODEL_ENVIRONMENTSmirrorsModelVersion.environment.oshun.model_version.health_changed—OSHUN_V1_MODEL_DEPLOYMENT_HEALTHSmirrorsModelVersion.DeploymentHealth.oshun.model_promotion_gate.decision_recorded—OSHUN_V1_MODEL_PROMOTION_DECISIONSmirrorsModelCard/Version.PromotionDecision.oshun.provenance_bundle.*— subject-type, release-state, watermark, and disclosure enums mirrorProvenanceBundle.*enums.oshun.rights_inspection.*— inspection-status and takedown-status enums mirroradmin-rights-provenance.ts.oshun.media_release.gate_evaluated—OSHUN_V1_PUBLICATION_GATE_STATUSESmirrorspublication-release-gate.tsStatus.oshun.release_readiness.*— gate status, decision, and tier enums mirroradmin-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_STATUSESenum (passing,warning,failing,waived,unknown). oshun.model_promotion_gate.waivedandoshun.release_readiness.gate_waivedcarry 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:
- updating
release-taxonomy.tswith the new or changed entry - updating tests (lock-style tests fail closed if entries drift)
- updating this document if the change is structurally significant
- 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).