# @oshun/evidence-sophia

Canonical Sophia grounding and evidence contracts for OSHUN.

This package defines the shared adapter surface for evidence-heavy flows across:

- Veritas claim inspection
- Nisaba study and notebook grounding
- assistant grounded answers
- Studio and Admin research-integrity workflows

The package is intentionally substrate-oriented. Sophia is modeled here as the
shared grounding layer behind OSHUN, not as another shell peer domain.

## Scope

- canonical evidence, citation, source, notebook, trace-export, and
  grounded-answer DTOs
- low-level adapter interface for Sophia-backed retrieval, claim verification,
  notebook, graph, and export operations
- high-level adapter interface for product-wide grounded flows
- canonical adapter factory (`createCanonicalSophiaEvidenceAdapter`) that wraps
  an injected low-level Sophia adapter
- normalization helpers that map existing `@sophia/*` types into OSHUN-native
  contracts

## Non-goals

- direct UI surfaces or domain launch cards
- domain-specific routing assumptions
- direct implementation of the backing Sophia clients

The canonical factory expects an injected `SophiaEvidenceApiAdapter`, keeping
transport and deployment concerns outside the shared OSHUN contract package.

## Usage

```ts
import { createCanonicalSophiaEvidenceAdapter } from '@oshun/evidence-sophia';

const sophia = createCanonicalSophiaEvidenceAdapter({
  apiAdapter,
  notebookUserId: 'user-123',
});

const answer = await sophia.ground({
  query: 'Does meditation improve attention?',
  consumer: 'assistant',
  citationPolicy: 'required',
  includeGraph: true,
});
```