Eve library

OSHUN V1 Assistant Event Taxonomy

Spec

Revision 1

On this page

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.

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