# OSHUN V1 Structured Tracing Manifest

Status: Canonical Date: 2026-04-26 Owners: OSHUN Platform Engineering, OSHUN
Reliability Tracks: `V1-OBS-009` from `OSHUN_V1_TODOS.md` Spec source:
`libs/oshun/analytics/src/tracing-manifest.ts`

This document is the canonical, human-readable companion to the machine-readable
V1 tracing manifest in `@oshun/analytics`.

The machine-readable manifest is the single source of truth.

---

## 1. Scope

This manifest defines the trace span boundaries, propagation rules, and
attribute conventions every Oshun-critical subsystem MUST follow. Downstream
OpenTelemetry SDKs (TS / Rust / Python) compile this manifest into their span
builders so traces remain shape-compatible end to end.

Subsystems covered:

- `shell_web`, `shell_mobile`, `shell_pwa` — customer shells
- `shell_admin_web`, `shell_admin_mobile` — admin shells
- `bff_consumer`, `bff_admin`, `bff_flows`, `bff_release`, `bff_assistant`
- `sophia` — grounding/evidence
- `iris` — memory
- `psyche` — embodiment
- `lilith` — persona / policy
- `isis` — generation control

---

## 2. Required propagation channels

Every cross-subsystem call MUST forward trace context through one of:

- W3C `traceparent` / `tracestate` over HTTP headers
- W3C `traceparent` / `tracestate` over gRPC metadata
- `baggage` headers / metadata
- queue message attributes
- browser pageload-to-BFF context exchange
- in-process AsyncLocalStorage (or equivalent)

BFF span families MUST propagate W3C trace context over HTTP (enforced by
tests). Sophia/Iris/Psyche/Lilith/Isis span families MUST declare at least one
propagation channel.

---

## 3. Shared attributes

Every span carries the shared attribute set:

- `oshun.tenant_id` (required)
- `oshun.session_id` (when known)
- `oshun.domain_context` (required)
- `oshun.platform_shell` (when known)
- `oshun.user_id` (sanitized hash; raw user_id is never sent)
- `oshun.persona_id` (assistant operations)
- `oshun.event_id` (correlation with analytics events)

---

## 4. Span families

The manifest publishes the canonical span families:

- Shell entry: `shell.app.opened`, `shell.route.transitioned`,
  `shell.admin_app.opened`
- BFF: `bff_consumer.request.handled`, `bff_admin.request.handled`,
  `bff_flows.request.handled`, `bff_release.request.handled`,
  `bff_assistant.turn.handled`
- Sophia: `sophia.evidence_pack.assembled`, `sophia.grounding.applied`
- Iris: `iris.memory.retrieved`, `iris.memory.persisted`
- Psyche: `psyche.embodiment.invoked`
- Lilith: `lilith.persona.bound`, `lilith.policy.evaluated`
- Isis: `isis.generation.run`, `isis.workflow.run`

Each family publishes its required propagation channels and span-specific
attributes. The shared attribute set is added implicitly.

---

## 5. PII handling

No span attribute carries PII. The `oshun.user_id` attribute records a stable
hash of the user identifier rather than the raw ID. Free-form content (prompts,
narratives, message bodies) never appears on any span.

---

## 6. Governance

### 6.1 Amendments

Adding or changing a span family or attribute requires:

1. updating `tracing-manifest.ts`
2. updating tests (lock-style tests fail closed if entries drift)
3. updating this document if the change is structurally significant
4. signoff from Platform Engineering and Reliability

### 6.2 Versioning

The manifest publishes attribute keys without versions; SDKs compile the
manifest at boot time, so changes are picked up on the next deploy.

---

## 7. Change log

- 2026-04-26 — Initial canonical V1 structured tracing manifest published
  alongside `libs/oshun/analytics/src/tracing-manifest.ts` (V1-OBS-009).
