@sentrial/sdk 0.4.5 → 0.6.0

package/README.md

@@ -19,35 +19,92 @@ pnpm add @sentrial/sdk
 yarn add @sentrial/sdk
 ```
 
+## Breaking changes
+
+**0.5.0**
+
+- **Transport is now OpenTelemetry (OTLP).** Telemetry ships over `/api/otel/v1/traces`; this SDK no
+  longer POSTs sessions/events to the legacy `/api/sdk/*` endpoints (those endpoints remain available
+  server-side as thin compatibility adapters that translate onto the OTLP ingest pipeline, so older SDK
+  releases keep working — new integrations use OTLP; the Python sync and async clients both emit OTLP
+  too). The OTLP ingest route requires the API
+  key to carry **both `sessions:write` and `events:write`** scopes — dashboard-generated keys include
+  both, but a manually-scoped `sessions:write`-only key will silently drop data. Add `events:write`
+  to the key (see [Transport](#transport)).
+- **Timestamp fields are now `string` (ISO 8601), not `Date`.** The `Session` fields (`createdAt` /
+  `updatedAt` / `completedAt`) and `Event.timestamp` were retyped because the API returns JSON and
+  `response.json()` never revived them into `Date` objects, so the old `Date` typing was incorrect —
+  but this is a compile-breaking change for code like `session.createdAt.getTime()`. Migrate by
+  parsing where needed: `new Date(session.createdAt).getTime()`.
+- **`PiiConfig.enhancedDetection` was removed.** The field was a no-op (never read by redaction
+  logic) and is gone from `PiiConfig`, mirroring the Python SDK. Drop it from any `PiiConfig`
+  literal — it had no effect.
+
+Shipped under a minor bump (not a patch), per the SDK compatibility policy.
+
 ## CLI
 
 The SDK package also ships a `sentrial` binary for scriptable workflows. This is the
 first packaging step toward a dedicated `npm install sentrial` style CLI package.
 
 ```bash
-# Run the CLI without a global install and set up the current project
-npx --yes --package=@sentrial/sdk@latest sentrial install
+# Install globally
+npm install -g @sentrial/sdk
+
+# Or run without installing
+npx -p @sentrial/sdk sentrial sessions list
 
 # Save credentials locally
-npx sentrial login --api-key sentrial_live_xxx
+sentrial login --api-key sentrial_live_xxx
 
 # Install the SDK package and scaffold a safe example integration
-npx sentrial install
+sentrial install
 
 # Or scaffold only, without installing packages
-npx sentrial init
+sentrial init
 
 # Inspect production runs
-npx sentrial sessions list --last 7d --status failed --agent support
-npx sentrial sessions get <session-id>
-npx sentrial events list <session-id> --type tool_call
+sentrial sessions list --last 7d --status failed --agent support
+sentrial sessions get <session-id>
+sentrial events list <session-id> --type tool_call
 
 # Review signals and run CI gates
-npx sentrial signals list --type negative --last 30d
-npx sentrial diagnose <session-id>
-npx sentrial evaluate <experiment-id> --min-score 80
+sentrial signals list --type negative --last 30d
+sentrial diagnose <session-id>
+sentrial evaluate <experiment-id> --min-score 80
+```
+
+> Note: `sentrial evaluate` calls `/api/v1/evaluate`, which requires an API key
+> scoped with `metrics:read`. Make sure the key you use (via `--api-key`,
+> `SENTRIAL_API_KEY`, or `sentrial login`) carries that scope, or the CI gate
+> will fail with a 403.
+
+### Guided setup and delivery checks
+
+Setup and Doctor require `@sentrial/sdk` 0.6.0 or later. Start in your agent project:
+
+```bash
+npx -p @sentrial/sdk@0.6.0 sentrial setup --dry-run --json
+npx -p @sentrial/sdk@0.6.0 sentrial setup
+# Coding agents / CI: set SENTRIAL_API_KEY privately first.
+npx -p @sentrial/sdk@0.6.0 sentrial setup --yes --non-interactive --json
+npx -p @sentrial/sdk@0.6.0 sentrial doctor --workspace <organization-uuid> --json
+npx -p @sentrial/sdk@0.6.0 sentrial doctor --session <session-uuid> --json
 ```
 
+Setup verifies workspace read access, inspects installed dependencies and creates an integration
+example while preserving existing files. A prompted key is hidden and is not saved. It does not
+execute the example or call a model. Keep the key in your agent runtime, adapt the example to your
+agent, run it, then use Doctor to inspect its session ID. Python-only projects can use
+`python -m sentrial.cli setup` from Python SDK 0.8.0 without Node.
+
+Doctor's `ready_for_instrumentation` result verifies read access, not delivery. `trace_verified`
+means this completed trace's source-numbered events were read back without reported gaps or
+inspection warnings. It does not establish business success, application-wide coverage or signal
+accuracy. Session listing needs `sessions:read`; delivery readback also needs `events:read` and
+an API deployment supporting `/api/v1/sessions/<id>/health`. Both reads share one bounded
+`--timeout-ms` deadline (100–30000 ms). Redirects are refused; reports omit trace content and keys.
+
 ## Quick Start (30 seconds)
 
 ### Option 1: Auto-Wrap LLM Clients (Recommended)
@@ -95,11 +152,11 @@ const supportAgent = withSession('support-agent', async (userId: string, message
 ### Option 3: Vercel AI SDK
 
 ```typescript
-import { configure, wrapAISDK } from '@sentrial/sdk';
+import { configureVercel, wrapAISDK } from '@sentrial/sdk';
 import * as ai from 'ai';
 import { openai } from '@ai-sdk/openai';
 
-configure({ apiKey: process.env.SENTRIAL_API_KEY, defaultAgent: 'my-agent' });
+configureVercel({ apiKey: process.env.SENTRIAL_API_KEY });
 
 const { generateText, streamText } = wrapAISDK(ai);
 
@@ -110,6 +167,59 @@ const { text } = await generateText({
 });
 ```
 
+### Option 4: OpenAI Agents SDK
+
+One call registers a trace processor with the Agents SDK (`@openai/agents`, an optional peer
+dependency, supported range `>=0.1.0 <1.0.0`) — every run becomes a Sentrial session with LLM
+events, tool calls, handoffs, and guardrails. Don't combine with `wrapOpenAI()` on the same run
+(LLM calls would be double-counted).
+
+```typescript
+import { Agent, run, addTraceProcessor } from '@openai/agents';
+import { sentrial, instrumentOpenAIAgents } from '@sentrial/sdk';
+
+sentrial.configure({ apiKey: process.env.SENTRIAL_API_KEY });
+instrumentOpenAIAgents({ addTraceProcessor }, { userId: 'user_123' });
+
+const agent = new Agent({ name: 'Assistant', instructions: 'Be helpful.' });
+const result = await run(agent, 'Write a haiku about recursion.');
+// The run is now a Sentrial session with LLM events, tool calls, handoffs.
+```
+
+See the [OpenAI Agents SDK integration docs](https://www.sentrial.com/docs/integrations/openai-agents)
+for configuration options, the run→session mapping, and batching/flush guidance.
+
+### Option 5: Google ADK
+
+Register one Plugin on your Google ADK `Runner` (`@google/adk`, an optional peer dependency,
+supported range `>=0.1.0 <2.0.0`) — every run becomes a Sentrial session with LLM events, tool
+calls, tokens, cost, and errors. The Plugin fires globally across every agent, tool, and model
+call in the invocation. Don't combine with `wrapGoogle()` on the same run (LLM calls would be
+double-counted).
+
+```typescript
+import { InMemoryRunner, LlmAgent } from '@google/adk';
+import { sentrial, SentrialAdkPlugin } from '@sentrial/sdk';
+
+sentrial.configure({ apiKey: process.env.SENTRIAL_API_KEY });
+
+const agent = new LlmAgent({ name: 'assistant', model: 'gemini-2.0-flash' });
+const runner = new InMemoryRunner({ agent, plugins: [new SentrialAdkPlugin()] });
+// Every runner.runAsync(...) is now a Sentrial session with LLM events, tool calls, and cost.
+```
+
+Already constructed the `Runner`? Attach after the fact — `instrumentAdk()` is idempotent per
+runner:
+
+```typescript
+import { instrumentAdk } from '@sentrial/sdk';
+
+instrumentAdk(runner, { userId: 'user_123' });
+```
+
+See the [Google ADK integration docs](https://www.sentrial.com/docs/integrations/google-adk)
+for configuration options, the run→session mapping, and batching/flush guidance.
+
 ## Features
 
 ### LLM Auto-Wrappers
@@ -170,7 +280,7 @@ await experiment.run(async (testCase, variant, tracker) => {
 
 ### Vercel AI SDK Integration
 
-Full support for Vercel AI SDK v3-v6:
+Full support for Vercel AI SDK v3-v7:
 
 ```typescript
 import { wrapAISDK } from '@sentrial/sdk';
@@ -193,6 +303,8 @@ const { text } = await generateText({
 });
 ```
 
+> **Note:** `zod` is not a direct dependency of `@sentrial/sdk` — it comes transitively from the Vercel AI SDK (`ai`), which you install to use `wrapAISDK`. The `import { z } from 'zod'` above resolves because `ai` pulls `zod` in as a peer.
+
 ## Configuration
 
 ### Environment Variables
@@ -202,6 +314,45 @@ SENTRIAL_API_URL=https://api.sentrial.com
 SENTRIAL_API_KEY=sentrial_live_xxx
 ```
 
+### Optional agent reports
+
+An agent can report missing context, a tool problem, a missing capability, or uncertain completion without marking the session failed:
+
+```ts
+await interaction.reportDiagnostic({
+  reportId: 'claim-context-1',
+  category: 'missing_context',
+  state: 'reported',
+  description: 'The policy number needed for this claim is missing.',
+});
+// Later, reuse the report ID and set state: 'recovered' with a new description.
+```
+
+The equivalent client method is `client.reportDiagnostic({ sessionId, report })`. Both a problem and its claimed recovery are agent assertions. They do not create a confirmed signal, training label, business outcome, or automatic action. Each call records a separate event; no prior report is overwritten. There are no model calls.
+
+Use an opaque report ID (1–128 letters, digits, `.`, `_`, `:`, or `-`, starting with a letter/digit). Descriptions are limited to 4,096 UTF-8 bytes. Optional `relatedSpanIds` contains at most eight distinct, nonzero, lowercase 16-digit OTel span IDs from the current trace. These references are agent-supplied and are not verified or followed automatically. Normal metadata redaction, batching, transport retry and fail-silent behavior apply. A resolved call is not a durable-delivery receipt; use delivery diagnostics and inspect the retained event. Unknown/degraded/finished sessions cannot accept new reports.
+
+The updated collector and trace UI display these as **Agent report**, including **Reported recovered**. Older collectors preserve generic event metadata but do not supply the validated report view. Existing signal evidence selectors do not consume reports as authoritative evidence; measuring incremental detection and review noise requires a separately reviewed evaluation.
+
+### Transport
+
+The SDK sends telemetry over **OpenTelemetry (OTLP)** to `/api/otel/v1/traces` — this is the sole
+ingestion path for this SDK (it no longer POSTs sessions/events to the legacy `/api/sdk/*` endpoints,
+which remain available server-side as thin compatibility adapters translated onto the OTLP ingest
+pipeline so older SDK releases keep working; the Python sync and async clients both emit OTLP too).
+The OTLP ingest route
+requires the API key to carry **both `sessions:write` and `events:write`** scopes — keys
+generated in the dashboard include both automatically. If you use a manually-scoped key that
+only has `sessions:write`, session creation will 403 and tracking is silently dropped; add
+`events:write` to the key.
+
+Events and completion attach to an in-memory span the client holds from
+`createSession()` / `begin()`, so they only apply to sessions **created on the same client
+instance**. If you obtain a session id elsewhere — a session created out-of-band, shared across
+processes, or tracked on a different `SentrialClient` — its events and finalization are skipped
+(the SDK logs a one-time warning). Use the same client instance for the full begin→track→finish
+flow.
+
 ### Programmatic
 
 ```typescript
@@ -284,23 +435,23 @@ const cost = calculateOpenAICost({
 
 ## Framework Compatibility
 
-| Framework            | Integration       | Status |
-| -------------------- | ----------------- | ------ |
-| **Direct OpenAI**    | `wrapOpenAI()`    | ✔️     |
-| **Direct Anthropic** | `wrapAnthropic()` | ✔️     |
-| **Direct Gemini**    | `wrapGoogle()`    | ✔️     |
-| **Vercel AI SDK**    | `wrapAISDK()`     | ✔️     |
-| **Express/Fastify**  | Decorators        | ✔️     |
-| **Next.js**          | Decorators        | ✔️     |
-| **Custom agents**    | Full API          | ✔️     |
+| Framework             | Integration                | Status |
+| --------------------- | -------------------------- | ------ |
+| **Direct OpenAI**     | `wrapOpenAI()`             | ✔️     |
+| **Direct Anthropic**  | `wrapAnthropic()`          | ✔️     |
+| **Direct Gemini**     | `wrapGoogle()`             | ✔️     |
+| **Vercel AI SDK**     | `wrapAISDK()`              | ✔️     |
+| **OpenAI Agents SDK** | `instrumentOpenAIAgents()` | ✔️     |
+| **Google ADK**        | `instrumentAdk()`          | ✔️     |
+| **Express/Fastify**   | Decorators                 | ✔️     |
+| **Next.js**           | Decorators                 | ✔️     |
+| **Custom agents**     | Full API                   | ✔️     |
 
 ## Documentation
 
-See the `docs/` folder in the repository:
-
-- `docs/sdks/typescript-sdk.md` - Full SDK reference
-- `docs/integrations/vercel-ai-sdk.md` - Vercel AI SDK integration
-- `docs/features/experiments.md` - Experiments guide
+- Full reference: [https://sentrial.com/docs](https://sentrial.com/docs)
+- Repository README: the root `README.md` maps every SDK entry point and the ingest flow
+- Framework wrappers live in `src/vercel.ts` (Vercel AI SDK), `src/openai-agents.ts` (OpenAI Agents SDK), `src/google-adk.ts` (Google ADK), `src/wrappers.ts` (OpenAI/Anthropic), and `src/decorators.ts`
 
 ## Support
 
@@ -313,20 +464,185 @@ See the `docs/` folder in the repository:
 Both SDKs share the same core API (`begin`/`finish`, tool & LLM tracking, production
 experiments, provider wrappers). Framework integrations currently differ:
 
-| Capability                                            | TypeScript            | Python              |
-| ----------------------------------------------------- | --------------------- | ------------------- |
-| Core tracking (begin/finish, tools, LLM, experiments) | ✓                     | ✓                   |
-| OpenAI / Anthropic / Google wrappers                  | ✓                     | ✓                   |
-| Vercel AI SDK helper                                  | ✓                     | — (JS-only)         |
-| Claude Agent SDK                                      | partial (single-turn) | ✓ (full multi-turn) |
-| OpenTelemetry export                                  | —                     | ✓                   |
-| Langfuse dual-write                                   | —                     | ✓                   |
-| AutoGen / CrewAI / LangChain handlers                 | —                     | ✓                   |
-
-Porting the missing TypeScript integrations (OpenTelemetry, Langfuse, Claude
-multi-turn) is planned; new TS integrations must keep V1 API response shapes
-backward-compatible.
+| Capability                                            | TypeScript                 | Python              |
+| ----------------------------------------------------- | -------------------------- | ------------------- |
+| Core tracking (begin/finish, tools, LLM, experiments) | ✓                          | ✓                   |
+| OpenAI / Anthropic / Google wrappers                  | ✓                          | ✓                   |
+| Vercel AI SDK helper                                  | ✓                          | — (JS-only)         |
+| Claude Agent SDK                                      | partial (single-turn)      | ✓ (full multi-turn) |
+| OpenTelemetry export                                  | ✓ (default OTLP transport) | ✓                   |
+| Langfuse dual-write                                   | —                          | ✓                   |
+| AutoGen / CrewAI / LangChain handlers                 | —                          | ✓                   |
+| OpenAI Agents SDK trace processor                     | ✓                          | ✓                   |
+| Google ADK Runner plugin                              | ✓                          | ✓                   |
+
+Porting the missing TypeScript integrations (Langfuse, Claude multi-turn) is
+planned; new TS integrations must keep V1 API response shapes backward-compatible.
 
 ## License
 
 MIT
+
+## Delivery diagnostics and worker handoffs
+
+### Large tool content (opt-in preview)
+
+For enabled workspaces, the native SDK can upload serialized tool inputs/outputs larger than 64 KiB directly to private storage and attach a small reference to the tool span. The configured PII policy runs before byte counting, hashing and upload. Enable the policy fields you need; `redactionRevision` labels that policy and does not itself redact data.
+
+```typescript
+const client = new SentrialClient({
+  apiKey: process.env.SENTRIAL_API_KEY,
+  pii: { enabled: true },
+  largeToolContent: {
+    enabled: true,
+    redactionRevision: 'claims-redaction-v1',
+    timeoutMs: 20_000,
+  },
+});
+```
+
+This remains disabled by default and requires separately enabled server storage and workspace quotas. It applies to named `tool_call` input/output fields, including calls recorded through the native SDK integrations; arbitrary external OpenTelemetry spans, LLM messages, metadata and state snapshots are not uploaded. The [Python clients](../python-sdk/README.md#large-tool-content-opt-in-preview) implement the same opt-in; hosted acceptance remains pending.
+
+Each field retains a prefix of at most 4 KiB of UTF-8 source bytes inline, with a 16 MiB object limit and two simultaneous uploads per client. Excess concurrent fields, quota failures, unavailable storage, cancellation and oversized objects keep the excerpt plus an explicit missing-content marker. Small fields and clients without the opt-in keep their existing inline behavior. Uploads use at most 24 requests and a configurable 1–60 second per-field deadline (20 seconds by default); this does not bound the subsequent normal trace delivery. A lost PUT acknowledgement is reconciled against retained parts before any retry. Recovery is in memory; restarting a process does not resume its SDK upload.
+
+`completeSession()` and `flush()` wait for uploads already started before draining their telemetry. `shutdown()` cancels outstanding uploads and drains their fallback events; call `flush()` first when you want to wait for uploads. Do not emit more events after finishing a session. Abrupt process exit cannot guarantee delivery.
+
+`getContentUploadDiagnostics()` returns payload-free attempted/submitted/missing/active/pending-event counts, or `null` when disabled. **Submitted is not verified or inspected:** the server must verify stored bytes, and a detector must separately load the relevant content within its evidence budget. A UI preview also does not establish detector coverage. See the [implementation and rollout limits](../../docs/plans/2026-10-17-telemetry-large-content.md).
+
+### Request and delivery diagnostics
+
+For request latency and response reports, read `client.getTransportDiagnostics()` (also available without batching). It separates logical requests, retries, in-flight attempts, response outcomes, reported span acceptance and fixed server timing stages. It retains lifetime aggregates plus 32 recent completed attempts, with no payloads or identifiers. Missing values stay unknown; a successful HTTP response is not proof of unique durable writes. [Usage and measurement limits](../../docs/testing/sdk-transport-timing.md).
+
+Call finish after the work belonging to a session has completed, then explicitly flush/close before process exit. Native SDK spans carry source sequence numbers and a final count, so missing events can be detected independently of server arrival order. This proves delivery of emitted spans, not that every application action was instrumented. Queues remain in memory and can drop events at capacity; abrupt termination cannot guarantee a flush.
+
+Read `client.getDeliveryDiagnostics()` for payload-free batcher counters (`null` when batching is disabled). A `failed` request was not confirmed delivered; it may have reached the server.
+
+```typescript
+import { actionMetadata, resumeHandoffContext } from '@sentrial/sdk';
+
+const parent = await client.begin({
+  userId: 'example', event: 'workflow',
+  metadata: actionMetadata({ actionId: 'order:42' }),
+});
+const carrier = parent.sessionId
+  ? await client.handoff({ sessionId: parent.sessionId, actionId: 'order:42' })
+  : null;
+// Pass carrier through your job queue, then in the worker:
+const child = await workerClient.begin({
+  userId: 'example', event: 'worker', ...(carrier ? resumeHandoffContext(carrier) : {}),
+});
+const metadata = actionMetadata({ actionId: 'order:42', attemptId: 'try-2', retryOfAttemptId: 'try-1' });
+```
+
+Handoff records delegation before returning the carrier and the worker starts a separate trace linked by parent session. The carrier is correlation metadata, not a credential or verified business outcome. Use opaque identifiers, never customer content or secrets. Low-level `createHandoffContext` / `create_handoff_context` only serializes a carrier; it does not record delegation. V2 signal evidence treats detached outcomes as unresolved until their context is supported.
+
+### Account for worker completion
+
+The v2 lifecycle adds a dispatch ID and four explicit records. Existing `handoff()` carriers remain supported. Use a fresh UUID per worker execution; preserve it only when retrying delivery of the same dispatch. A retry that executes work again gets a new dispatch ID (and a new `attemptId`, optionally linked with `retryOfAttemptId`). Use opaque identifiers.
+
+```typescript
+// Parent: record intent before sending the carrier through your queue/RPC.
+import { randomUUID } from 'node:crypto';
+
+const carrier = await parentClient.dispatchHandoff({
+  sessionId: parentSessionId,
+  actionId: 'order:42',
+  dispatchId: randomUUID(),
+});
+
+// Worker: use its own session, initialized from the received carrier.
+const worker = await workerClient.begin({
+  userId: 'example', event: 'order-worker', ...resumeHandoffContext(carrier),
+});
+const workerSessionId = worker.getSessionId();
+if (workerSessionId) {
+  await workerClient.acceptHandoff(workerSessionId, carrier);
+  // Execute the work here. Report the actual execution outcome.
+  await workerClient.finishHandoff(workerSessionId, carrier, 'completed');
+}
+await worker.finish({ output: 'Worker finished' });
+
+// Parent: only after your application receives the worker's terminal result.
+// Send the worker session ID and actual outcome with that result.
+if (workerSessionId) {
+  await parentClient.receiveHandoff(parentSessionId, carrier, workerSessionId, 'completed');
+}
+```
+
+`completed`, `failed` and `cancelled` describe worker execution, not business success. Record `finishHandoff` before closing the worker session and `receiveHandoff` before closing the parent. Do not emit a completion in an unconditional `finally`; crashes, timeouts or lost results must remain unresolved. A telemetry method returning does not prove the queue or collector received anything. Continue using delivery diagnostics and flush/shutdown normally. If telemetry session creation fails, application work should still continue without these optional records.
+
+The internal related-evidence reader detects missing phases, duplicate worker claims, conflicting outcomes and invalid local order. It uses SDK producer sequences rather than arrival order or clocks across machines. Captures remain incomplete for definitive signal judgments. See the [handoff verification contract](../../docs/plans/2026-10-09-handoff-lifecycle-delivery.md).
+
+### Report experiment exposure explicitly
+
+`getVariant()` and `createSession()` associate an assignment with a session, including
+holdouts. An association does **not** assert that your application used the configuration.
+After using the returned settings, report that usage explicitly:
+
+```typescript
+const assignment = await client.getVariant({
+  experimentName: 'support-prompt',
+  agentName: 'Support agent',
+  userId: 'stable-user-id',
+});
+const sessionId = await client.createSession({
+  name: 'Support request',
+  agentName: 'Support agent',
+  userId: 'stable-user-id',
+});
+// Apply the returned settings in your application before recording exposure.
+if (sessionId && assignment.assignmentId && assignment.configurationHash) {
+  const receipt = await client.recordExperimentExposure({
+    sessionId,
+    assignmentId: assignment.assignmentId,
+    variant: assignment.variant,
+    configurationHash: assignment.configurationHash,
+  });
+  // null means delivery failed under failSilently:true; retry these same fields.
+}
+```
+
+Only report when your application used that configuration. Do not gate holdout reporting
+on `assignment.active`: a holdout has `active:false` and `reason:'holdout'`. Historical
+assignments may lack `configurationHash` and cannot produce a verified matching receipt.
+The digest identifies the frozen returned configuration, not a model provider's behavior.
+
+Receipts are idempotent per assignment/session; `recordedAt` is server arrival time.
+Conflicting configuration reports return 409. Deleted source sessions return 410, with
+history retained as tombstones. Delayed reports for previously issued assignments may
+arrive after the experiment stops. The method flushes queued telemetry before sending;
+it does not run inference. `failSilently:false` propagates delivery errors.
+
+For overlapping sessions on one client, pass `sessionId` to `getVariant()` or pass
+`experimentAssignmentIds` explicitly when creating a session. Automatic linking targets
+the next session and should only be used when that matches your application's ordering.
+Each experiment/session may belong to only one assignment identity.
+
+### Assignment identity and telemetry acknowledgment
+
+An experiment's declared assignment unit is required: supply `userId`/`user_id` for
+user assignment, `convoId`/`convo_id` for conversation assignment, or
+`anonymousId`/`anonymous_id` for anonymous assignment. Another identifier or a session
+ID will not substitute for it. Missing or whitespace-only identity returns
+`active:false`, `reason:'missing_identity'`, the required `assignmentUnit`, and your
+default variant. No assignment is created. Preserve a stable identifier across requests.
+Pass that same user or conversation identifier when creating the session. A conflicting
+session identifier rejects the link; once linked, it cannot be changed or cleared.
+Assignments from different experiments must also agree on each shared assignment unit.
+An anonymous assignment has no corresponding session identity field, so its consistency
+is checked against the session's other anonymous assignments. This does not verify that
+the caller's identifier represents a real person or remains stable outside this session.
+
+New assignments report `identityProvenance:'declared'` and their immutable
+`assignmentUnit`. Existing assignments report `identityProvenance:'legacy_unknown'`
+when their historical fallback identity cannot be established. A lookup does not upgrade
+that provenance. Start a new experiment for a prospectively defined identity/analysis plan.
+
+Native telemetry commits a session's assignment links in the same transaction as its
+session/events. A failed link fails the request, and a retry preserves the original trace
+identity. Unknown or foreign assignments cannot be silently skipped. Explicit assignment
+lists must contain at most 64 UUIDs; malformed or oversized lists receive HTTP 400 before
+any trace in that batch writes. UUIDs are deduplicated without dropping distinct entries.
+A valid list whose assignment was deleted or is unavailable fails instead of returning a
+false success; correct the references before retrying a permanent error. The existing SDK
+fail-silent/strict error policy still applies.