Treat migration as a behavioral comparison, not a raw response snapshot update.

### Build deterministic fixtures

Use an isolated namespace with stable IDs and fixed source content. Include plaintext, URL, file, batch, metadata, grouping, profile facts, related memories, forgotten memories, and empty-result cases.

Record each legacy request, v5 request, expected semantic result, and intentional difference. Never compare generated IDs, signed URLs, timing, or JSON object order unless the contract guarantees them.

### Compare writes

- Repeated POST appends or diffs; PATCH replaces canonical content.
- Batch outcomes preserve input order and surface partial failures.
- Metadata-only updates leave source content unchanged.
- Accepted writes are polled until processing reaches a terminal state.

### Compare reads and recall

- Document attachments are absent when omitted and empty arrays when requested without results.
- Unified list responses populate only the selected resource array.
- Search parity uses explicit v4-equivalent mode and threshold before testing v5 defaults.
- Profiles always contain static, dynamic, and bucket sections.

### Exercise boundaries

| Boundary | Cases |
| --- | --- |
| Namespace | Correct, missing, unauthorized, cross-namespace ID |
| Pagination | First, middle, final, empty, maximum limit |
| Filters | Every operator, nested AND/OR, invalid type, excessive depth |
| Deletion | All success, partial success, unknown IDs, semantic dry run |
| Settings | Admin, non-admin, null removal, invalid empty value |

### Classify differences

```text
same request intent
       |
       +-- same semantic result ------> parity
       +-- documented v5 difference --> update assertion
       +-- undocumented difference ----> block cutover
```

Do not normalize away an undocumented difference. Capture the request pair, namespace, IDs, response status, and minimal response fragments needed to reproduce it.

### Cut over by domain

1. Ship v5 request construction behind a per-domain flag.
2. Dual-read or shadow-call where side effects allow it.
3. Switch ingestion, content management, search, profiles, then settings independently.
4. Monitor validation failures, authorization failures, latency, empty-result rate, and processing failures.
5. Retain the legacy path until the observation window passes.

### Completion checklist

- No application API call accidentally uses a `/v5` prefix.
- Unchanged connector routes retain their documented `/v3` paths.
- No legacy field aliases or response readers remain.
- Every changed default is either accepted intentionally or passed explicitly.
- Rollback restores the previous caller without requiring data repair.