# OSHUN V1 Admin Event Taxonomy

Status: Canonical Date: 2026-04-26 Owners: OSHUN Platform Engineering, OSHUN
Trust & Safety, OSHUN Compliance, OSHUN Data Engineering Tracks: `V1-OBS-002`
from `OSHUN_V1_TODOS.md` Spec source:
`libs/oshun/analytics/src/admin-taxonomy.ts`

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

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

---

## 1. Scope

This taxonomy defines every analytics event an admin/operator-facing surface
(admin web shell, admin mobile shell, admin BFF, admin background workers, admin
notification handler) is permitted to emit during OSHUN V1.

It is the strict mirror of the customer taxonomy
(`docs/releases/v1/specs/customer-event-taxonomy.md`,
`libs/oshun/analytics/src/customer-taxonomy.ts`) and is partitioned from it by
surface and entity. There are no overlapping event names between the two
taxonomies — admin shell-level events disambiguate from customer counterparts
via an `admin_*` entity prefix (e.g. `oshun.admin_app.opened`).

Out-of-scope categories deferred to other V1 tasks:

- customer events (V1-OBS-001)
- assistant interactions, memory state, grounding state, persona identity —
  V1-OBS-003
- review/moderation/appeal/incident _content_ events that are part of the
  V1-OBS-004 customer-perceived surface — those are owned by V1-OBS-004; only
  operator-action events are part of V1-OBS-002
- model intake/promotion/media release _gates_ — V1-OBS-005

The taxonomy is consistent with:

- ADR-0006 — `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- ADR-0023 — admin audit/compliance contract
  (`docs/adr/ADR-0029-oshun-studio-audit-and-compliance-surfaces.md`)
- ADR-0029 — review/approval workflows
  (`docs/adr/ADR-0035-oshun-studio-review-and-approval-workflows.md`)
- Admin information architecture — `libs/oshun/navigation/src/admin-ia.ts`
- Admin PRD — `docs/releases/v1/specs/web-app-admin-v1-prd.md`

---

## 2. Naming and envelope

### 2.1 Canonical name format

All names follow the ADR-0006 format `<namespace>.<entity>.<action>`. Per
ADR-0006 §"Namespace Ownership", admin events use the `oshun.*` namespace —
there is no dedicated `admin.*` namespace.

To avoid ambiguity with customer events that share top-level shell concepts,
admin shell-level events use `admin_*` entity prefixes:

- `oshun.admin_app.*` (lifecycle)
- `oshun.admin_auth.*` (auth)
- `oshun.admin_workspace.*`, `oshun.admin_route.*`, `oshun.admin_deep_link.*`
  (navigation)
- `oshun.admin_notification.*` (notification handling)
- `oshun.admin_performance.*`, `oshun.admin_error.*` (operational)

Workspace-specific events use admin-only entity names that do not appear in the
customer taxonomy:

- `oshun.queue.*`, `oshun.inbox.*`
- `oshun.review.*`, `oshun.moderation.*`
- `oshun.persona.*`, `oshun.model.*`, `oshun.workflow_template.*`
- `oshun.incident.*`, `oshun.policy.*`, `oshun.policy_bundle.*`
- `oshun.support_case.*`, `oshun.rights.*`, `oshun.editorial.*`
- `oshun.research_integrity.*`, `oshun.privacy_request.*`
- `oshun.audit.*`, `oshun.rbac.*`, `oshun.tenant.*`
- `oshun.bulk_operation.*`, `oshun.collab_session.*`, `oshun.comment.*`
- `oshun.analytics_report.*`, `oshun.copilot_feedback.*`
- `oshun.premium_cast.*`

### 2.2 Required envelope

Admin events use the same ADR-0006 envelope as customer events with the
additional convention that every event property set carries `tenant_id` to
support multi-tenant analytics, plus an operator `role` on operator-initiated
events.

### 2.3 Property rules

- Property names are snake_case.
- No PII in any property value.
- `tenant_id` is required on every admin event.
- `role` is required on every operator-initiated event (audit pipeline events,
  inbound rights/privacy requests, and admin-auth-failed events are exceptions
  because the operator role may not be known at the time of emission).
- `consentRequired` is omitted from the admin schema entirely: admin/operational
  telemetry is excluded from customer consent gating per ADR-0006 §"Consent and
  Privacy Rules".
- Stable enum values are defined per property and locked by tests.

---

## 3. Surfaces

The taxonomy uses the following admin-surface taxonomy. Workspace surfaces align
with `OSHUN_ADMIN_WORKSPACE_IDS` in `admin-ia.ts` (hyphens replaced by
underscores).

| Surface                      | Description                                       |
| ---------------------------- | ------------------------------------------------- |
| `admin_web_shell`            | Admin web shell, surface-agnostic.                |
| `admin_mobile_shell`         | Admin mobile shell, surface-agnostic.             |
| `admin_bff`                  | Admin BFF service-emitted events.                 |
| `admin_background`           | Admin background workers (audit replay, exports). |
| `admin_notification_handler` | Admin push/email/in-app/Slack/PagerDuty handler.  |
| `admin_deep_link`            | Admin shell deep-link handler.                    |
| `admin_studio`               | Studio plane (design system + collaboration).     |
| `admin_dashboard`            | Dashboard workspace.                              |
| `admin_inbox`                | Inbox / unified-queue workspace.                  |
| `admin_review`               | Review and approval workspace.                    |
| `admin_policy`               | Policy and configuration workspace.               |
| `admin_trust_safety`         | Trust & safety / moderation workspace.            |
| `admin_rights`               | Rights & provenance workspace.                    |
| `admin_incidents`            | Incidents and reliability workspace.              |
| `admin_editorial`            | Editorial workspace.                              |
| `admin_research_integrity`   | Research integrity workspace.                     |
| `admin_personas`             | Personas and avatars workspace.                   |
| `admin_models`               | Model and workflow operations workspace.          |
| `admin_support`              | Support and customer operations workspace.        |
| `admin_privacy`              | Privacy and compliance workspace.                 |
| `admin_analytics`            | Analytics and executive reporting workspace.      |

---

## 4. Families

| Family               | Description                                                  |
| -------------------- | ------------------------------------------------------------ |
| `lifecycle`          | Admin shell open / background / resume.                      |
| `auth`               | Admin sign-in / sign-out / failure / scope assumption.       |
| `navigation`         | Workspace views, admin route transitions, deep-link opens.   |
| `queue`              | Queue views, item claims, filter applications.               |
| `review`             | Review/approval lifecycle per ADR-0029.                      |
| `moderation`         | Moderation actions and copilot feedback.                     |
| `governance`         | Persona, model, and workflow template governance.            |
| `incident`           | Incident open/mitigate/close/postmortem and related updates. |
| `policy`             | Policy and policy-bundle promotions, rollbacks, allowlists.  |
| `support`            | Support case lifecycle.                                      |
| `rights`             | Rights/provenance request handling.                          |
| `editorial`          | Editorial review and rehearsal completion.                   |
| `research_integrity` | Research integrity case management and notebook promotions.  |
| `privacy_ops`        | Admin-side privacy request handling and audit exports.       |
| `audit`              | Audit pipeline meta-events, exports, exceptions.             |
| `rbac`               | Role assignment and simulation events.                       |
| `tenant`             | Tenant isolation scope changes.                              |
| `bulk_operation`     | Bulk admin operations, started / completed.                  |
| `collaboration`      | Realtime collaboration session / presence / commenting.      |
| `notification`       | Admin notification received / opened / actioned.             |
| `analytics`          | Admin analytics report generation and copilot feedback.      |
| `performance`        | Admin shell startup and Web Vitals.                          |
| `error`              | Admin error boundaries and admin BFF API failures.           |

---

## 5. Workspace coverage

Every admin workspace declared in `admin-ia.ts` owns at least one event:

- `inbox` — queue and bulk-action events
- `review` — `oshun.review.*` lifecycle (created, assigned, reassigned, decided,
  delegated, escalated, revised) per ADR-0029
- `policy` — policy and policy-bundle events
- `trust-safety` — moderation and copilot feedback
- `rights` — rights request lifecycle and consent updates
- `incidents` — `oshun.incident.*` lifecycle
- `editorial` — editorial review, rehearsal, premium cast decisions
- `research-integrity` — investigation lifecycle and notebook promotions
- `personas` — `oshun.persona.*` governance and tone calibration
- `models` — `oshun.model.*` governance and spot checks
- `support` — `oshun.support_case.*` lifecycle
- `privacy` — `oshun.privacy_request.*` lifecycle
- `analytics` — `oshun.analytics_report.*`, `oshun.copilot_feedback.*`

The dashboard workspace is composed from cross-workspace events; it does not own
its own emitter set in V1.

---

## 6. ADR-0029 alignment

The following review-stage events are required by ADR-0029 and locked by tests:

- `oshun.review.created`
- `oshun.review.assigned`
- `oshun.review.reassigned`
- `oshun.review.decided` (decision enum: `approved`, `rejected`,
  `changes_requested`)
- `oshun.review.delegated`
- `oshun.review.escalated`
- `oshun.review.revised`

`oshun.review.decided` records the high-risk-confirmation flag for the
"confirm-high-risk-approval" path that the admin BFF exposes.

---

## 7. ADR-0023 alignment

Audit-bearing events declare an `outcome` enum aligned with ADR-0023's "audit
evidence contract" (`allowed`, `denied`, `error`, `success`):

- `oshun.audit.event_emitted`, `oshun.audit.export_completed`,
  `oshun.audit.exception_raised`
- `oshun.moderation.action_taken`
- `oshun.privacy_request.resolved`
- `oshun.rights.request_resolved`
- `oshun.research_integrity.case_resolved`
- `oshun.editorial.review_completed`
- `oshun.incident.closed`

Tests in `admin-taxonomy.test.ts` lock the outcome-property values against the
ADR-0023 enum.

---

## 8. Operator roles

The following operator-role values are declared in
`OSHUN_V1_ADMIN_OPERATOR_ROLES` and locked into the `role` enum on every
operator-initiated event:

`reviewer`, `moderator`, `analyst`, `compliance_officer`, `incident_commander`,
`support_agent`, `policy_editor`, `persona_owner`, `model_owner`,
`rights_specialist`, `researcher`, `editorial_lead`, `admin`.

---

## 9. Governance

### 9.1 Amendments

Adding, changing, or deprecating an admin event requires:

1. updating `admin-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 the `owningWorkspace` workspace's product and engineering leads,
   plus the platform analytics owner

### 9.2 Versioning

Same rules as the customer taxonomy: additive property changes keep the same
`version`; breaking changes bump `version` and may require a dual-write window
before dashboards cut over.

### 9.3 Tenant and consent

Admin events do not gate on customer consent. They are operational and
compliance telemetry per ADR-0006 §"Consent and Privacy Rules". Every admin
event carries `tenant_id` to support multi-tenant scoping.

---

## 10. Out-of-scope

This taxonomy intentionally does not define:

- customer-facing events (V1-OBS-001 — `customer-taxonomy.ts`)
- assistant-side governance and grounding events (V1-OBS-003)
- customer appeal flows that customers see directly (V1-OBS-004 covers the
  customer-visible side)
- model intake/promotion gating telemetry (V1-OBS-005)

When those follow-up taxonomies are defined, they will register their canonical
names in their own taxonomy spec files and will be cross-validated against the
global `validateEventName` regex and namespace allowlist.

---

## 11. Change log

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