mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-11 03:37:56 +00:00
f0d4b265e5
Docs for supermemoryai/mono#3415: delete and batch return `count`; ingest `status` is `queued`/`done` (batch adds `error`, files say `queued`); document `system.status` values; search `isInference` and `included.document.system`; `metadata` never null.
60 lines
2.8 KiB
Text
60 lines
2.8 KiB
Text
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 list accepted documents first, then failures, and surface partial failures; match by ID, not position.
|
|
- Metadata-only updates leave source content unchanged.
|
|
- Accepted writes are polled until processing reaches a terminal state.
|
|
|
|
### Compare reads and recall
|
|
|
|
- Document includes are absent when omitted and empty arrays when requested without results.
|
|
- Unified list responses populate only the selected resource array.
|
|
- `metadata` is always an object, `{}` when empty; it is never `null`.
|
|
- 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.
|