Eve library

OSHUN V1 Release Event Taxonomy

Spec

Revision 1

On this page

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).