# Migrating from Engine 1.5

> Plan it as a new integration that reuses your token backend, your proxy and your interface, not as a rename.

## What changes in the model

In Engine 1.5 a page opened a **session**, captured for a while and asked for the interpretation. In Engine 2 a person is **enrolled in a protocol**, and each capture is **one position** of it, with a plan of steps (see [Protocols](/docs/concepts/protocols/)). Creating users and enrolling them is your backend's job.

## What stays the same

- The API key never reaches the browser: your backend mints tokens and proxies Engine.
- Capture still sends facial geometry, never images.

## Route by route

| Topic | Engine 1.5 | Engine 2 |
| --- | --- | --- |
| Token | `POST /token` with `user`, `tenant` and `securityKey`: one token per end user | `POST /token` with `apiKey`: one token per key. The end user moves from the token to each request (`externalId`, enrolment ids) |
| Users | Created on the fly with the first token | Created by your backend with `POST /users`; `externalId` is unique per organization |
| What you capture | A free **session** (`POST /session`, with its `order`) | A **position** of a protocol the user is **enrolled** in (`POST /user-protocols`), identified by `userProtocolId` and `protocolMechanicId`, with its plan of steps |
| Taxonomy of the interpretation | Fields in the body of `POST /session` | `POST /user-protocols/{userProtocolId}/{protocolMechanicId}/context` |
| Narrative (voice, depth, language) | In the body of the session | In the user's profile (`POST /users` and `PATCH /users/{external_id}`), plus `audience` in `/analyze` |
| Sending frames | `POST /process-kpn-emo` with `sessionId`, `step` = `order` and `baseline` | The same route with `userProtocolId`, `protocolMechanicId` and the `step` of the plan; no `baseline` flag; `featuresMeta` on every frame |
| Baseline | A `baseline: true` session; validity worked out by the client | Its own route, `POST` and `GET /users/{app_user}/baseline`; the server says whether it is valid |
| Results | `GET /results/{sessionId}` | `GET /results/{userProtocolId}/{protocolMechanicId}` (also per step and per enrolment) |
| Interpretation | `POST /analyze` with `sessionId`, `timeStart`, `timeEnd` | `POST /analyze` with `userProtocolId`, `protocolMechanicId`, optional `step` and `audience`, cached per audience; also `POST /analyze/stream` |
| Events | `GET /stream/{sessionId}` | `GET /stream/{userProtocolId}`, per enrolment, closed with `stream.end` and a `reason` |
| Listing sessions | `GET /sessions/` | `GET /user-protocols/{userProtocolId}/{protocolMechanicId}/sessions` and `GET /users/{external_id}/status` |
| Constellation Lite | `lite_analysis` in the session | Not part of the public Engine 2 API; ask Neurologyca |

This guide covers the integration, not your data: for existing users and baselines, ask Neurologyca.

## If you use the SDK

| Engine 1.5 SDK | Engine 2 SDK |
| --- | --- |
| `createNeuroClient` | `createProtocolClient` |
| `defineNeuroCapture` | No component: `createProtocolClient` and your own screens ([Steps and marking](/docs/sdk/steps/)) |
| `siteKeyTokenProvider` and the hosted gateway | Removed: your backend's proxy adds the token ([Your backend](/docs/sdk/backend/)) |
| `narrative` | Rejected with a message: the narrative goes in the user's profile (`POST` and `PATCH /users/{external_id}`), from your backend |
| `lite_analysis` | Rejected: not part of Engine 2; ask Neurologyca |
| `contextText` | No equivalent: the only free text the interpretation receives is the transcript (the `query` phrase still exists) |
| `interpretationTimeoutMs` | Renamed `analyzeTimeoutMs` |
| `triggerAnalysis` on the client | Per capture (`captureProtocol`) |
| — | A new server package, `@neurologyca/capture-server`, for creating users, enrolling them and building the kit of a context |

Your proxy grows from the routes of Engine 1.5 to the [13 routes](/docs/api/proxy/) the Engine 2 SDK calls.

## What Engine 2 adds

The catalogue, user status and blocking, deletion with confirmation, Measurement, microinterventions, and key scopes. Start with the [quickstart](/docs/start/quickstart/).

## From 0.25 to 0.27

If you already run the previous preview of the Engine 2 SDK (0.25), these are the changes to make, from the changelog of `@neurologyca/capture` (0.26.0 **Breaking** and 0.27.0) and of `@neurologyca/capture-server` 0.9.0. The full list is in [SDK changelog](/docs/resources/changelog/).

### Breaking

1. `<neuro-capture>` is removed: use `createProtocolClient` or `createRecordingClient`, `describeStep` and your own screens. What the element did for you (keeping the screen on, the `beforeunload` guard) is now yours: use `keepScreenOn` and `guardUnload`.
2. `stop()` resolves with the outcome: a `CaptureOutcome` live, a `RecordingResult` when recording.
3. `RecordingSessionHandle` no longer extends `ProtocolSessionHandle`: use `createRecordingClient`, which needs no cast.
4. One shape for `E_CONFLICT`: `e.reason` and `e.conflict.<field>`.
5. The recording client (`@neurologyca/capture/record`) records MP4/H.264 only.
6. A recording refuses a `captureId` already stored in the browser (`E_CAPTURE_ID_IN_USE`).
7. `RecordingResult` has a required `storage`, and `ProtocolSessionHandle` has `captureId` and `stepTiming()`: a hand-written test double must add them.
8. `CaptureSource` gains `{ type: 'frames' }`, so an exhaustive `switch` on `source.type` stops compiling.
9. The recordings database moves to version 2: close tabs with an older SDK before recording.
10. `capture.global.js` registers no tag: the API is on `window.NeuroCapture`.
11. `@neurologyca/capture-server` 0.9.0 requires Node 20.3 or later (`engines.node` is `>=20.3`).

### New or recommended

12. The browser needs no token: create the client without `getToken` (it is now optional), behind your backend's proxy (`createEngineProxy`).
13. Upload recordings with `uploadRecording`, the browser half of the contract whose server half is `createUploadReceiver`.
14. `stepDurations` warns by default and has an `'off'`.
15. From 0.27.0, a `<video>` is a full source: its audio reaches transcription (with its `src` set before), its end is the end of the source (`source.ended`), and you can record it.

## From 0.27 to 0.43

If you run 0.27, these are the changes to make up to `@neurologyca/capture` 0.43.0 and `@neurologyca/capture-server` 0.19.0, from their changelogs (the **Breaking** of 0.36.0, 0.36.3, 0.38.0, 0.42.0, 0.42.1 and 0.43.0, and the wider type of 0.28.0). The full list is in [SDK changelog](/docs/resources/changelog/).

### Breaking

1. 0.28.0: `ManifestStep.endedBy` gains `'source'`, the step that the end of the recorded source closed (a `<video>` or a stream that finished); before, it said `'timer'`. An exhaustive `switch` over it needs the new case.
2. 0.36.0 (kodec 5): `FORWARDED_CODEC_EVENTS` no longer lists `hubert-enabled`, `hubert-revoked`, `voice-enabled` and `voice-revoked`; a listener on them never fires.
3. 0.36.0 renamed `PlanStep.targetConstellationHciId` to `targetHciId` and 0.36.3 undid it (with `ProtocolSummary.group` in `@neurologyca/capture-server` 0.14.3): coming from 0.27 the name does not change, but code written against 0.36.0 to 0.36.2 goes back to `targetConstellationHciId`.
4. 0.38.0: `stop()` no longer generates a second interpretation: it waits for the one Engine stores (up to `analyzeTimeoutMs`) and only then calls `POST /analyze` once, so it can take longer; `analyze.progress` only arrives with `interpretation: 'stream'` ([The outcome](/docs/sdk/on-device/#the-outcome)).
5. 0.38.0: `PlanStep` gains the required `expectsSpeech` and `presentationSeconds`, and `SessionReport` gains `interpretationSource`, `interpretationMode` and `streamDropsDuringWait`: code that builds them by hand must add them.
6. 0.42.0: a `transcribe.selfHost.wasmPaths` string is now a prefix that must end in `/`, under which your host serves the onnxruntime pair the device asks for ([CSP and transcription](/docs/guides/csp-transcription/)).
7. 0.42.0: `createProtocolClient` throws `E_UNKNOWN_OPTION` for an option it does not know, as `createRecordingClient` already did: remove any extra key from the config.
8. 0.42.0: `ProtocolClientHandle` gains `prepare`, `release` and `cacheStatus` (and `RecordingClientHandle`, `prepare` and `release`), `SessionReport` gains `startup` and `transcriptionLoad`, and `CaptureStartError` gains `stage` and `reason`: a typed test double must add them.
9. 0.42.1 and 0.43.0: `StartupMessageKey` gains `'first-frame.timeout-media'` and `'first-frame.face-reload-failed'`: a `Record<StartupMessageKey, string>` of your own texts must add both.
10. 0.43.0: `StartupReport.schema` is `1 | 2` and `PreparedBlock.prepareId` can be `null`. A receiver of startup reports validates schema 2 with `@neurologyca/capture-server` 0.19.0 or later ([Startup reports](/docs/sdk/backend/#startup-reports-optional)).
11. 0.43.0 (kodec `5.0.0-rc.14`): a source that has already ended when the capture starts fails at once, with `CaptureStartError` and `stage: 'source'`; pass a live stream or a video that is still playing.

### New or recommended

12. `client.prepare()` and `client.release()` (0.42.0) load the models before Start ([Prepare before Start](/docs/sdk/on-device/#prepare-before-start)), and `keepPrepared` (0.43.0) keeps them from one capture to the next ([Keep the models between captures](/docs/sdk/on-device/#keep-the-models-between-captures)).
13. `startup`, `onStartupStage` and `STARTUP_MESSAGES` (0.42.0) show the startup stage by stage, with caps so it cannot hang ([The startup screen](/docs/sdk/on-device/#the-startup-screen)).
14. `signal` in `captureProtocol` (0.42.0) cancels a capture while it starts, and `captureProtocol({ transcribe: false })` runs one capture without the microphone on a client configured with transcription.

## From 0.43 to 0.45

If you run 0.43, these are the changes to make up to `@neurologyca/capture` 0.45.0 and `@neurologyca/capture-server` 0.20.1, from their changelogs (0.44.0, 0.45.0, 0.20.0 and 0.20.1). None of them breaks at runtime: what changes is the reading of a `202` and some types that gain required fields. `PlanStep.expectsSpeech` (0.38.0) and `targetConstellationHciId` (0.36.3) do not change in this stretch. Coming from an earlier version, first follow [From 0.27 to 0.43](#from-027-to-043), whose 0.43.0 is the last breaking release. The full list is in [SDK changelog](/docs/resources/changelog/).

### Changes to make

1. 0.44.0: `client.analyze()` (on `createProtocolClient` and `createRecordingClient`) resolves to `AnalyzeAnswer`, which adds the required `inProgress` and `retryAfterMs` to `interpretation`, `fromCache` and `raw`: a typed test double that builds its result must add both (`inProgress: false, retryAfterMs: null` for an ordinary answer).
2. 0.44.0: at the close of a capture, a `202 ANALYSIS_IN_PROGRESS` no longer ends with `E_INTERPRETATION_TIMEOUT`: the SDK waits and asks again (`analysis.in-progress`) and, if the wait runs out, ends with the new `E_ANALYSIS_IN_PROGRESS` (recoverable, status `timeout`). Code that branches on `E_INTERPRETATION_TIMEOUT` to say "interpretation pending" must also handle `E_ANALYSIS_IN_PROGRESS` ([Errors](/docs/sdk/errors/)), and an exhaustive `switch` over `ProtocolErrorCode` needs the new case.
3. 0.44.0 and 0.20.0: a `null` interpretation with `inProgress: true` means "interpreting", not "none": check `inProgress` before treating `interpretation: null` as final, and ask again after `retryAfterMs` ([The 202 of the interpretation](/docs/sdk/errors/#the-202-of-the-interpretation)).
4. 0.20.0: `AnalyzeResult` (`analyze()` and `EngineAdmin.analyze`) and `AudienceReading` (`analyzeForAudiences`) gain the required `inProgress` and `retryAfterMs`, `ProtocolSummary` and its `group` gain `interpreted` (`boolean | null`), and `TenantKit` gains `kind` (`'context' | 'measurement'`): a typed test double of any of them must add them.
5. 0.20.0: `buildTenantKit` no longer throws `E_KIT_NO_CONTEXT` for Measurement: it gives `kind: 'measurement'`, with `taxonomy.contextId: MEASUREMENT_CONTEXT_ID` and a notice to capture with `triggerAnalysis: false`. Branch on `kit.kind` where you caught `E_KIT_NO_CONTEXT` to fall back to a fixed Measurement configuration ([Your backend](/docs/sdk/backend/#people-and-enrolments-createengineadmin)).

### New or recommended

6. `credentials` (0.45.0) on `createProtocolClient`, `createRecordingClient` and `urlTokenProvider`: `'include'` for a proxy on another origin that decides by your session cookie, with `cors: { origins, credentials: true }` in `createEngineProxy` and `capture-server` 0.20.1, which exposes `Retry-After` to that page ([A proxy on another origin](/docs/api/proxy/#a-proxy-on-another-origin)).
7. 0.45.0: an `/analyze` asked again after a `202` gets only what is left of the wait, so the close ends at most about 10 s past `analyzeTimeoutMs`.
