feat(api): V6 representative fingerprint column, envelope validation + embeddings cache feed (ADR 0113) #1268

Merged
chris merged 2 commits from feat/rep-cache-api into main 2026-10-16 21:29:09 +02:00
Owner

Summary

API side of ADR 0113 V6 (fingerprint-keyed representative cache): persist the worker-computed per-person fingerprint and serve the persisted set back so the next run can skip the per-person linkage recompute.

  • V168 migration: nullable fingerprint TEXT on person_instance_representatives (no index; column rides the existing V156 FULL-REPLACE rows — absent = recompute next run).
  • Envelope validation (WorkerResultService.personRepresentativesValidation): additive optional fingerprint per entry — absent/JSON-null legal (older worker), present-but-malformed (non-string, not 64 lowercase hex) rejected fail-closed with the existing envelope-rejection shape, before any write.
  • Persist (ClassInstanceDiscoveryService.persistPersonRepresentatives): fingerprint stored on every row of that person's set inside the existing candidate-ingestion transaction; a fingerprint-less run NULLs it via the same full replace.
  • Embeddings response (OwnerFaceEmbeddingsController): GET /api/worker/jobs/{id}/owner-face-embeddings gains top-level personRepresentatives (envelope/ADR 0109 entry shape + fingerprint, deterministic person-ASC/rep_index order, empty list on all no-data paths). Explicit "fingerprint": null for fingerprint-less runs — the worker treats null as a miss.

Test plan

  • rtk ./gradlew :apps:api:compileJava :apps:api:compileTestJava green.
  • dev.memories.api.discovery.* + dev.memories.api.worker.*: 956 tests, 0 failures; dev.memories.api.people.*: 346 tests, 0 failures. New coverage: envelope accept/reject matrix (+6), ingestion persist/replace/malformed (+2 + helper), embeddings response order/null/isolation/empty (+3), V168 migration pin (+1).
  • Testcontainers Postgres harnesses migrated through V168 cleanly (Flyway ordering validated in-situ).
  • Cross-lane contract verified against the worker branch feat/rep-cache-worker: key names (modelName/modelVersion/personId/fingerprint/reps[{repIndex,clusterSize,embedding}]), 64-hex definition, null-as-miss.
  • Merge order: this PR merges and deploys BEFORE the worker PR (old worker ignores the new response key; new worker against old API would ship envelope fingerprints into the stricter old validation).
## Summary API side of ADR 0113 V6 (fingerprint-keyed representative cache): persist the worker-computed per-person fingerprint and serve the persisted set back so the next run can skip the per-person linkage recompute. - **V168 migration**: nullable `fingerprint TEXT` on `person_instance_representatives` (no index; column rides the existing V156 FULL-REPLACE rows — absent = recompute next run). - **Envelope validation** (`WorkerResultService.personRepresentativesValidation`): additive optional `fingerprint` per entry — absent/JSON-null legal (older worker), present-but-malformed (non-string, not 64 lowercase hex) rejected fail-closed with the existing envelope-rejection shape, before any write. - **Persist** (`ClassInstanceDiscoveryService.persistPersonRepresentatives`): fingerprint stored on every row of that person's set inside the existing candidate-ingestion transaction; a fingerprint-less run NULLs it via the same full replace. - **Embeddings response** (`OwnerFaceEmbeddingsController`): `GET /api/worker/jobs/{id}/owner-face-embeddings` gains top-level `personRepresentatives` (envelope/ADR 0109 entry shape + `fingerprint`, deterministic person-ASC/rep_index order, empty list on all no-data paths). Explicit `"fingerprint": null` for fingerprint-less runs — the worker treats null as a miss. ## Test plan - `rtk ./gradlew :apps:api:compileJava :apps:api:compileTestJava` green. - `dev.memories.api.discovery.*` + `dev.memories.api.worker.*`: **956 tests, 0 failures**; `dev.memories.api.people.*`: **346 tests, 0 failures**. New coverage: envelope accept/reject matrix (+6), ingestion persist/replace/malformed (+2 + helper), embeddings response order/null/isolation/empty (+3), V168 migration pin (+1). - Testcontainers Postgres harnesses migrated through V168 cleanly (Flyway ordering validated in-situ). - Cross-lane contract verified against the worker branch `feat/rep-cache-worker`: key names (`modelName/modelVersion/personId/fingerprint/reps[{repIndex,clusterSize,embedding}]`), 64-hex definition, null-as-miss. - Merge order: this PR merges and deploys BEFORE the worker PR (old worker ignores the new response key; new worker against old API would ship envelope fingerprints into the stricter old validation).
- V168__person_instance_representatives_fingerprint.sql: nullable fingerprint TEXT
  on the ADR 0109 representative set (full-replace ride-along, no index)
- WorkerResultService.personRepresentativesValidation: per-person additive
  fingerprint field, fail-closed (64 lowercase hex) like sibling fields
- ClassInstanceDiscoveryService.persistPersonRepresentatives: persist the
  fingerprint per row; envelope without it writes NULL (absent = recompute)
- OwnerFaceEmbeddingsController: top-level personRepresentatives feed in the
  envelope entry shape + fingerprint, deterministic person/rep_index order
- H2 test schemas gain the column/table
test(api): ADR 0113 V6 fingerprint coverage — envelope, ingestion, cache feed, migration
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 2m38s
67eaa44c68
- WorkerResultSemisupervisedEnvelopeTest: valid/absent/null fingerprint accepted;
  short-non-hex, uppercase, wrong-length, non-string rejected fail-closed (job stays leased)
- ClassInstanceDiscoveryServiceTest: NULL on fingerprint-less replace, stored per row
  on fingerprinted run, re-nulled by a later fingerprint-less full replace; defensive
  reject of malformed fingerprint before any write
- OwnerFaceEmbeddingsControllerTest: personRepresentatives feed in envelope shape
  with fingerprints, deterministic person/rep_index order, null round-trip,
  cross-owner isolation, empty-list cases (including unknown job)
- PersonInstanceRepresentativesMigrationTest: V168 column content pins
chris merged commit 5cd9c22755 into main 2026-10-16 21:29:09 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1268
No description provided.