# Communicating the Activix v5 `runContext` rename

Use this page when **you** (maintainer) tell other teams, consumers, or chat channels that **`@x12i/activix` v5** renamed the per-run correlation object from **`identity`** to **`runContext`**.

## Facts to stress (copy as needed)

1. **Single new name:** the object is **`runContext`** in code and (by default) in MongoDB. It is **not** user auth, not AWS/Azure “identity,” and not logs-gateway call-site “identity.”
2. **No hidden compatibility:** v5 does **not** keep `identity` / `identityField` / `findRecordsByIdentity` on the default path. Callers must update imports, payload keys, filters, and indexes—or set **`runContextField: 'identity'`** only while data still uses the old BSON key.
3. **Wrong key is dangerous:** with default config, a top-level **`identity`** property on **`startRecord`** is **ignored** for correlation and may be stored as junk on the document. Use **`runContext`**.
4. **Docs:** [run-context-object.md](./run-context-object.md) (single canonical guide + v5 API table at top); upgrade steps = [MIGRATION-v5.md](./MIGRATION-v5.md); changelog = [CHANGELOG.md](../CHANGELOG.md).

## Short message (Slack / Teams / Discord)

> **@x12i/activix v5** — breaking rename: the per-run correlation field is now **`runContext`** (BSON + API). There is **no** `identity` / `identityField` / `findRecordsByIdentity` on the default API. Update payloads, queries, and indexes, or see **MIGRATION-v5** for a temporary `runContextField: 'identity'` bridge. Details: repo `.docs/run-context-object.md`, `.docs/MIGRATION-v5.md`.

## Slightly longer (email / internal wiki)

**Subject:** Activix v5 — `identity` → `runContext` (breaking)

We are upgrading to **`@x12i/activix` v5**. The correlation object that carries `sessionId`, `jobId`, task ids, etc. is now named **`runContext`** everywhere by default (Mongo field + TypeScript property + query helper **`findRecordsByRunContext`**).

**Action for each service that calls Activix:**

- Replace **`identity:`** with **`runContext:`** on writes.
- Replace **`identityField`** with **`runContextField`** in collection config if you customized it.
- Replace **`findRecordsByIdentity`** with **`findRecordsByRunContext`**; criteria use **`runContext`** instead of **`identity`**.
- Update raw Mongo filters and indexes from **`identity.*`** to **`runContext.*`** (or run a **`$rename`** per **MIGRATION-v5**).

There are **no** deprecated aliases on the default path—stale **`identity`** keys will not populate the correlation object.

**References:** [MIGRATION-v5.md](./MIGRATION-v5.md), [run-context-object.md](./run-context-object.md).

## Checklist you can paste for downstream owners

- [ ] Bump **`@x12i/activix`** to **^5.0.0** (or pinned 5.x).
- [ ] **`startRecord` / patches:** `identity` → **`runContext`**.
- [ ] **Config:** `identityField` → **`runContextField`** (if used).
- [ ] **Queries:** `findRecordsByIdentity` → **`findRecordsByRunContext`**; criteria **`identity`** → **`runContext`**.
- [ ] **Mongo:** indexes / filters **`identity.`** → **`runContext.`** (or **`$rename`** + optional bridge).
- [ ] **Your own docs** and OpenAPI/examples mention **`runContext`**, not **`identity`**.

## Release notes snippet (GitHub / package registry)

```markdown
### Breaking changes (v5.0.0)

- Renamed per-run correlation field from **`identity`** to **`runContext`** (default BSON key and API property).
- **`identityField`** → **`runContextField`**; **`findRecordsByIdentity`** → **`findRecordsByRunContext`**; **`FindByIdentityCriteria`** → **`FindByRunContextCriteria`**.
- No backward-compatible aliases on the default path. See **MIGRATION-v5** and **run-context-object** in the repo `.docs/` folder.
```

## After you publish

- Post the short message in the channel where integrators watch.
- Link **MIGRATION-v5** from your org’s “upgrade playbook” if you have one.
- For packages that wrap Activix, open issues or PRs with the checklist above.