docs(adr): ADR 0113 representative density graph (semisupervised-v3) + validation plan #1254

Merged
chris merged 2 commits from docs/adr-0113-representative-graph into main 2026-10-16 10:54:32 +02:00
Owner

Summary

Draft ADR 0113 (proposed) + validation plan for the representative density graph optimization of face clustering.

Decision (V1–V7): new single-pass method semisupervised-v3: threshold graph over U ∪ R (unlabeled pool + ADR 0108 representatives as labeled identity-evidence nodes), pairwise computation restricted to U×U + U×R — no L-blocks. Steady state: (L+U)² → U² + U·R. Group formation on the U×U subgraph only; gates generalized (not forked) to read rep adjacency; contract version 2, fail-closed matrix on worker + Core; v1/v2 byte-identical and operator-selectable (rollback = stay on v2). Sub-decision: fingerprint-keyed representative cache (method-independent, benefits v2 immediately). Honest limits recorded: no bulk-import win (ANN = follow-up), no feed-level incrementality (future work), accepted rep-induced edge flips near threshold.

Validation plan G3 filled with measured prototype numbers: steady state 111× faster (3.35s→0.03s), computed pairs 228× fewer (78.1M→342k), peak RSS 733→8.5 MiB, max HAC component 102→10; mid 21.7×; bulk 5.7× faster (no regression). Identity sanity: 100% own-rep adjacency, 0% foreign-rep adjacency.

Status: ADR stays proposed until G1 (owner-library CV) and G4 (deploy-host run) pass.

Test plan

  • docs-only; ADR JSON validated with python3 -m json.tool
  • companion prototype branch: feat/representative-density-graph-prototype (additive module + benchmark, all suites green)
## Summary Draft ADR 0113 (`proposed`) + validation plan for the representative density graph optimization of face clustering. **Decision (V1–V7):** new single-pass method `semisupervised-v3`: threshold graph over U ∪ R (unlabeled pool + ADR 0108 representatives as labeled identity-evidence nodes), pairwise computation restricted to U×U + U×R — no L-blocks. Steady state: (L+U)² → U² + U·R. Group formation on the U×U subgraph only; gates generalized (not forked) to read rep adjacency; contract version 2, fail-closed matrix on worker + Core; v1/v2 byte-identical and operator-selectable (rollback = stay on v2). Sub-decision: fingerprint-keyed representative cache (method-independent, benefits v2 immediately). Honest limits recorded: no bulk-import win (ANN = follow-up), no feed-level incrementality (future work), accepted rep-induced edge flips near threshold. **Validation plan G3 filled with measured prototype numbers:** steady state 111× faster (3.35s→0.03s), computed pairs 228× fewer (78.1M→342k), peak RSS 733→8.5 MiB, max HAC component 102→10; mid 21.7×; bulk 5.7× faster (no regression). Identity sanity: 100% own-rep adjacency, 0% foreign-rep adjacency. **Status:** ADR stays `proposed` until G1 (owner-library CV) and G4 (deploy-host run) pass. ## Test plan - docs-only; ADR JSON validated with `python3 -m json.tool` - companion prototype branch: `feat/representative-density-graph-prototype` (additive module + benchmark, all suites green)
docs(adr): fill ADR 0113 G3/G4 cells with prototype benchmark numbers
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 3s
Build and Deploy / Run scoped PR tests (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker 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 / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build people worker image (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 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
cda91715b9
chris merged commit 0e470641cd into main 2026-10-16 10:54:32 +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!1254
No description provided.