Eve library

OSHUN V1 Admin Event Taxonomy

Spec

Revision 1

On this page

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.

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