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_idis required on every admin event.roleis 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).consentRequiredis 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 eventsreview—oshun.review.*lifecycle (created, assigned, reassigned, decided, delegated, escalated, revised) per ADR-0029policy— policy and policy-bundle eventstrust-safety— moderation and copilot feedbackrights— rights request lifecycle and consent updatesincidents—oshun.incident.*lifecycleeditorial— editorial review, rehearsal, premium cast decisionsresearch-integrity— investigation lifecycle and notebook promotionspersonas—oshun.persona.*governance and tone calibrationmodels—oshun.model.*governance and spot checkssupport—oshun.support_case.*lifecycleprivacy—oshun.privacy_request.*lifecycleanalytics—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.createdoshun.review.assignedoshun.review.reassignedoshun.review.decided(decision enum:approved,rejected,changes_requested)oshun.review.delegatedoshun.review.escalatedoshun.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_raisedoshun.moderation.action_takenoshun.privacy_request.resolvedoshun.rights.request_resolvedoshun.research_integrity.case_resolvedoshun.editorial.review_completedoshun.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:
- updating
admin-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 the
owningWorkspaceworkspace'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).