# OSHUN V1 Assistant Event Taxonomy

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 lifecycle
- `oshun.assistant_continuity.*` for the V1-AST-007 continuity journey
- `oshun.assistant_safety.*` for safety refusals/blocks
- `oshun.memory_scope.*` and `oshun.memory.*` for Iris memory state
- `oshun.grounding.*`, `oshun.evidence_pack.*`, `oshun.citation.*` for Sophia
  grounding/evidence
- `oshun.persona_identity.*` for Lilith persona identity
- `oshun.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:

1. **Customer-engagement (consent-gated)**: `assistant_session`,
   `assistant_turn`, `assistant_continuity`, `assistant_feedback`, plus the
   non-compliance entries within `grounding`, `evidence`, `citation`, and
   `memory.retrieved` / `memory.persisted`.

2. **Compliance-mandatory (NOT consent-gated)**:
   - `disclosure` family (per ADR-0060)
   - `assistant_safety` family
   - `persona_identity` family
   - 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.

3. **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`/`consumed` reuse the contract's `kind` enum
  (`claim_support`, `report`, `assistant_turn`, `study_note`, `source_set`,
  `comparative_analysis`).
- `citation.surfaced` records the contract `stance` enum (`supports`,
  `qualifies`, `contradicts`, `context`, `neutral`, `refutes`).
- Tests assert these enum sets verbatim.

---

## 9. Lilith persona alignment

- `persona_identity.bound`/`switched`/`policy_violation_detected` reuse the
  Persona contract's `role` enum (`assistant`, `teacher`, `guide`, `coach`,
  `scholar`, `explainer`, `reporter`, `philosopher`, `support`, `moderator`,
  `operator`, `companion`).
- `persona_identity.policy_violation_detected` carries 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`:

1. `inherit-the-current-context`
2. `bound-the-need`
3. `ground-and-shape-the-answer`
4. `hand-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:

1. updating `assistant-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 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).
