# Session ID usage (`sessionId`)

This document describes how **`sessionId`** should be used when integrating with Activix and related systems. It is **guidance** for application code—the **happy path** for correlating a run—not a list of things Activix rejects at runtime.

**Direct vs nested:** your code may be **called directly** (no parent run) or **from another layer** that passes a full or partial run context. **Use what you get.** Activix does **not force** a single calling pattern. The rules below matter most when you **already received** a `sessionId` for a run and must **keep** it stable; at a **true entry** where nothing was supplied, your product decides whether to assign one once or require the caller to send one (Activix does not mint one for you—see [Library behavior when `sessionId` is omitted](#library-behavior-when-sessionid-is-omitted)). Wrappers and UI components should **recommend** this path and **not force** more than their API documents.

## What `sessionId` represents

`sessionId` identifies one logical **session or run** from **start through finish**. All related persistence for that run (for example `startRecord`, updates, and completion for the same user-facing or job-scoped flow) should share the **same** value.

Treat it as a **correlation key** across that run. It is not meant to be a new id per HTTP request or per arbitrary sub-step unless your product explicitly defines it that way.

## Source of truth: upstream, when you are not the entry

On the **happy path**, the `sessionId` for a run is chosen and owned **above** layers that only **participate** in that run:

- Examples of owners for that path: orchestrator, gateway, job runner, top-level page or route shell, API entry boundary, or any component that **starts** or **scopes** the run.
- Code **below** that boundary (nested UI, helpers, internal services) that **was given** a `sessionId` **should not** create, randomize, or substitute a different one.

Those inner layers should **receive** `sessionId` (or full `runContext`) from the outside—props, context, dependency injection, request metadata, or equivalent—and **pass it through unchanged** when calling Activix or forwarding work.

**If you are the entry** and nothing upstream passed a run id, **you** are the place that may assign one once (per your product rules)—that is not the same as a nested child minting a second id.

**Why the nested rule:** If a child that **already had** a run id mints its own `sessionId`, sibling branches and parent orchestration cannot correlate records to a single run. The run boundary breaks as soon as ids diverge.

## Uniqueness

**Recommendation:** use a **unique** `sessionId` for each distinct run (for example a UUID) so queries such as `findRecordsByRunContext({ sessionId })` return records for that run only and do not accidentally mix unrelated runs.

Activix **does not** enforce global uniqueness of `sessionId` across your product or database. Reusing the same id for different runs, or colliding ids, is a **data and modeling risk**; the library will not reject it on that basis alone.

## How this maps to Activix

- You may pass `sessionId` as a **top-level** field on the payload or inside the configured **`runContext`** object. If both are present, they must **agree** (see main [README](../README.md) and types for `FindByRunContextCriteria`).
- For the lifetime of one run, keep the same `sessionId` stable across all Activix calls that belong to that run.

### Library behavior when `sessionId` is omitted

If neither `runContext.sessionId` nor top-level `sessionId` is provided, Activix **does not** add one. It emits an internal **warning** only when diagnostics are enabled with **`ENABLE_ACTIVIX_LOGXER=true`**, and persists **`runContext` without `sessionId`**. Prefer always supplying `sessionId` from the run owner so correlation and `findRecordsByRunContext({ sessionId })` stay predictable.

## Related documentation

- [Run context](./run-context-object.md) (onboarding, layers, `instance`, mistakes, v5 API, graphs appendix)
- [README: Query by `sessionId` / `runContext` / `status`](../README.md#query-by-sessionid--runcontext--status) for API mechanics and index hints.