Status: Canonical Date: 2026-04-26 Owners: OSHUN Platform Engineering, OSHUN
Trust & Safety, OSHUN Compliance, OSHUN Memory (Iris), OSHUN Grounding (Sophia),
OSHUN Persona (Lilith) Tracks: V1-OBS-003 from OSHUN_V1_TODOS.md Spec
source: libs/oshun/analytics/src/assistant-taxonomy.ts
This document is the canonical, human-readable companion to the machine-readable
V1 assistant event taxonomy in @oshun/analytics.
The machine-readable taxonomy is the single source of truth. Any divergence
between this document and assistant-taxonomy.ts is a bug in this document —
follow the code.
1. Scope#
This taxonomy defines every analytics event emitted by or about the OSHUN assistant: assistant interactions (sessions, turns, suggestions, actions, feedback), memory state (Iris), grounding state and evidence (Sophia), persona identity (Lilith), and AI disclosure compliance (per ADR-0060).
It pairs with:
- the customer taxonomy (
customer-taxonomy.ts, V1-OBS-001) - the admin taxonomy (
admin-taxonomy.ts, V1-OBS-002)
It is partitioned from both by entity:
oshun.assistant.*for interaction lifecycleoshun.assistant_continuity.*for the V1-AST-007 continuity journeyoshun.assistant_safety.*for safety refusals/blocksoshun.memory_scope.*andoshun.memory.*for Iris memory stateoshun.grounding.*,oshun.evidence_pack.*,oshun.citation.*for Sophia grounding/evidenceoshun.persona_identity.*for Lilith persona identityoshun.disclosure.*for AI disclosure compliance
Out-of-scope:
- customer surface events (V1-OBS-001)
- admin operator events (V1-OBS-002)
- review/moderation/appeal/incident lifecycle (V1-OBS-004)
- model intake/promotion/media release gates (V1-OBS-005)
The taxonomy is consistent with:
- ADR-0006 — analytics taxonomy and event naming
- ADR-0060 — disclosure and synthetic-indicator UI behavior
libs/contracts/src/common/memory-scope.ts(Iris MemoryScope contract)libs/contracts/src/common/evidence-pack.ts(Sophia EvidencePack contract)libs/contracts/src/common/citation.ts(Sophia Citation contract)libs/contracts/src/common/persona.ts(Lilith Persona contract)libs/oshun/navigation/src/assistant-continuity-journey.ts(V1-AST-007 stages)libs/oshun/shell-assistant/src/types.ts(assistant session/turn types)libs/oshun/memory-iris/src/assistant-identity.ts(assistant identity kernel)
2. Naming and envelope#
Names follow <namespace>.<entity>.<action> per ADR-0006. Per ADR-0006
§"Namespace Ownership", assistant events use the oshun.* namespace.
Property names are snake_case. PII is never sent (raw conversation content is excluded by design — only stable identifiers, lengths, classifications, and confidence scores are recorded).
3. Surfaces#
Customer surfaces are the primary emitters; admin surfaces emit assistant events when operators review or audit assistant runs.
| Surface | Description |
|---|---|
web_assistant |
Web continuity assistant surface. |
mobile_assistant |
Mobile continuity assistant surface. |
web_shell |
Web shell — disclosure and continuity emissions. |
mobile_shell |
Mobile shell — disclosure and continuity emissions. |
pwa_shell |
PWA shell — disclosure and continuity emissions. |
domain_app |
Customer-facing domain app launched from the shell. |
assistant_bff |
Assistant BFF service (turn lifecycle, grounding, safety). |
assistant_background |
Assistant background workers. |
admin_review |
Admin review workspace (transcript review/audit). |
admin_trust_safety |
Admin trust & safety workspace. |
admin_personas |
Admin personas workspace. |
admin_privacy |
Admin privacy workspace (memory operations). |
4. Families#
| Family | Description |
|---|---|
assistant_session |
Session start/end. |
assistant_turn |
Turn requested/completed/failed/suggestion/action. |
assistant_continuity |
V1-AST-007 continuity-journey stage events. |
assistant_safety |
Safety refusals, unsafe input/output detections. |
assistant_feedback |
Customer feedback on suggestions and turns. |
memory |
Iris memory scope and record state. |
grounding |
Sophia grounding requests, application, fallback. |
evidence |
EvidencePack assembly and consumption. |
citation |
Citation surfacing, follow, flagging. |
persona_identity |
Lilith persona binding/switching/violation. |
disclosure |
AI disclosure indicator shown/dismissed/acknowledged. |
5. Consent vs compliance#
Assistant events fall into three buckets:
-
Customer-engagement (consent-gated):
assistant_session,assistant_turn,assistant_continuity,assistant_feedback, plus the non-compliance entries withingrounding,evidence,citation, andmemory.retrieved/memory.persisted. -
Compliance-mandatory (NOT consent-gated):
disclosurefamily (per ADR-0060)assistant_safetyfamilypersona_identityfamily- memory-scope lifecycle events (
memory_scope.created,memory_scope.updated,memory_scope.archived,memory_scope.revoked,memory_scope.consent_changed,memory.access_denied)
These are operational and compliance-mandatory observations per ADR-0006 §"Consent and Privacy Rules". The audit trail cannot be silenced by customer-side consent toggles.
-
Pure operational: assistant background workers (e.g. evidence pack assembly) carry consent gates only when they ride alongside a customer turn; standalone background telemetry follows operational rules.
Tests in assistant-taxonomy.test.ts lock these rules in.
6. ADR-0060 disclosure alignment#
The disclosure family enforces the indicator vocabulary defined in ADR-0060 /
OSHUN_V1_AI_DISCLOSURE_COPY_GUIDANCE.md:
ai_assistant, memory_off, memory_session, memory_profile,
synthetic_voice, synthetic_avatar, synthetic_media,
human_review_present.
Every disclosure event records the indicator that was shown/dismissed/
acknowledged, and oshun.disclosure.compliance_check_failed records the
indicator that should have been shown but was not — driving the
disclosure-compliance dashboard.
7. Iris memory contract alignment#
Memory events use the enums from libs/contracts/src/common/memory-scope.ts:
- storage class:
session,profile,episodic,semantic,notebook - sensitivity tier:
standard,sensitive,restricted,regulated - privacy boundary (used in
memory.access_denied):private,persona_bound,surface_bound,domain_bound,organization_bound,cross_domain
The constants OSHUN_V1_MEMORY_STORAGE_CLASSES and
OSHUN_V1_MEMORY_SENSITIVITY_TIERS mirror the contract verbatim and are checked
by tests.
8. Sophia grounding/evidence/citation alignment#
evidence_pack.assembled/consumedreuse the contract'skindenum (claim_support,report,assistant_turn,study_note,source_set,comparative_analysis).citation.surfacedrecords the contractstanceenum (supports,qualifies,contradicts,context,neutral,refutes).- Tests assert these enum sets verbatim.
9. Lilith persona alignment#
persona_identity.bound/switched/policy_violation_detectedreuse the Persona contract'sroleenum (assistant,teacher,guide,coach,scholar,explainer,reporter,philosopher,support,moderator,operator,companion).persona_identity.policy_violation_detectedcarries a violation classifier that aligns with Lilith's policy enforcement points.
10. V1-AST-007 continuity-journey alignment#
The continuity-journey events use the four canonical stages from
assistant-continuity-journey.ts:
inherit-the-current-contextbound-the-needground-and-shape-the-answerhand-back-and-preserve
oshun.assistant_continuity.handback_completed is reserved for the stage-4
completion signal and carries the count of preserved artifacts and the target
shell surface.
11. Governance#
11.1 Amendments#
Adding, changing, or deprecating an assistant event requires:
- updating
assistant-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 relevant subsystem owner (Iris/Sophia/Lilith/Disclosure) plus platform analytics
11.2 Versioning#
Same rules as the customer and admin taxonomies. The version field starts at
1; breaking changes bump version and may require a dual-write window.
11.3 PII and content#
Raw assistant transcripts, raw memory contents, and raw evidence text are never
recorded in event payloads. Events carry stable IDs, lengths, scores, and
classifications only. Tests fail closed on any property flagged isPii: true.
12. Out-of-scope#
This taxonomy intentionally does not define:
- customer-facing events (V1-OBS-001)
- admin operator events (V1-OBS-002)
- customer-perceived appeals/decisions (V1-OBS-004)
- model intake/promotion gates (V1-OBS-005)
13. Change log#
- 2026-04-26 — Initial canonical V1 assistant event taxonomy published alongside
libs/oshun/analytics/src/assistant-taxonomy.ts(V1-OBS-003).