feat(api): semisupervised-v3 contract matrix, allowlist + enqueue stamping (ADR 0113 V1/V5) #1258

Merged
chris merged 2 commits from feat/semisupervised-v3-api into main 2026-10-16 11:56:31 +02:00
Owner

Summary

Core-side of ADR 0113 (companion worker PR follows): semisupervised-v3 becomes a recognized clustering method with contract version 2, fail-closed on both directions.

  • Allowlist (PeopleClusteringResetController): semisupervised-v3 joins ALLOWED_CLUSTERING_METHODS; allowlist-sync javadoc updated; default + null→worker-default untouched.
  • Enqueue (WorkerJobEnqueueService): v3 jobs stamp clusteringContractVersion=2 + maxDistance + representativeSplitDistance (v2-or-v3 condition, mirroring v2 exactly — the worker's graph node set is built at the job-snapshotted split distance, ADR 0113 V2).
  • Result matrix (WorkerResultService): new requiredContractVersion(method) — v1@1, v2@1, v3@2, anything else fail-closed; enforced on immutable job settings before envelope comparison. Envelope-vs-job method/version mismatches use the pre-existing checks (incl. v3-stamped envelope on v2 job → reject). isSemisupervised mode routing + forged-marker + provenance guards cover v3.
  • Discovery (ClassInstanceDiscoveryService): v3 joins the semisupervised method guards (persist fail-closed stamp, bulk-confirm provenance).

Intentional tightening: v1 job@2 (previously passable if envelope echoed 2) is now rejected — no production path could produce it (enqueue stamps per-method), covered by a test.

Test plan

  • rtk ./gradlew :apps:api:test --tests '*Clustering*' --tests '*Semisupervised*' --tests '*WorkerResult*' → BUILD SUCCESSFUL; matrix coverage accepts (v1,1)/(v2,1)/(v3,2), rejects (v3,1)/(v3,3)/(v1,2)/(v2,2)/(v3,null) + envelope method/version mismatches (+16 new tests across 4 suites)
  • Supplemental: *ClassInstanceDiscovery* 334/0/0, *WorkerJobEnqueue* 43/0/0, *PeopleRepresentativeSplitDistance* 12/0/0, *MLResultAcceptance* 30/0/0
  • Cross-lane contract verified: method string, version matrix and split-distance stamping match the worker lane byte-for-byte
## Summary Core-side of ADR 0113 (companion worker PR follows): `semisupervised-v3` becomes a recognized clustering method with contract version 2, fail-closed on both directions. - **Allowlist** (`PeopleClusteringResetController`): `semisupervised-v3` joins `ALLOWED_CLUSTERING_METHODS`; allowlist-sync javadoc updated; default + null→worker-default untouched. - **Enqueue** (`WorkerJobEnqueueService`): v3 jobs stamp `clusteringContractVersion=2` + `maxDistance` + `representativeSplitDistance` (v2-or-v3 condition, mirroring v2 exactly — the worker's graph node set is built at the job-snapshotted split distance, ADR 0113 V2). - **Result matrix** (`WorkerResultService`): new `requiredContractVersion(method)` — v1@1, v2@1, v3@2, anything else fail-closed; enforced on immutable job settings before envelope comparison. Envelope-vs-job method/version mismatches use the pre-existing checks (incl. v3-stamped envelope on v2 job → reject). `isSemisupervised` mode routing + forged-marker + provenance guards cover v3. - **Discovery** (`ClassInstanceDiscoveryService`): v3 joins the semisupervised method guards (persist fail-closed stamp, bulk-confirm provenance). Intentional tightening: v1 job@2 (previously passable if envelope echoed 2) is now rejected — no production path could produce it (enqueue stamps per-method), covered by a test. ## Test plan - `rtk ./gradlew :apps:api:test --tests '*Clustering*' --tests '*Semisupervised*' --tests '*WorkerResult*'` → BUILD SUCCESSFUL; matrix coverage accepts (v1,1)/(v2,1)/(v3,2), rejects (v3,1)/(v3,3)/(v1,2)/(v2,2)/(v3,null) + envelope method/version mismatches (+16 new tests across 4 suites) - Supplemental: `*ClassInstanceDiscovery*` 334/0/0, `*WorkerJobEnqueue*` 43/0/0, `*PeopleRepresentativeSplitDistance*` 12/0/0, `*MLResultAcceptance*` 30/0/0 - Cross-lane contract verified: method string, version matrix and split-distance stamping match the worker lane byte-for-byte
- PeopleClusteringResetController: allowlist gains semisupervised-v3 (V1);
  DEFAULT_CLUSTERING_METHOD and null->worker-default semantics untouched.
- WorkerResultService: (method, contractVersion) acceptance matrix
  v1@1, v2@1, v3@2, everything else rejected fail-closed; isSemisupervised
  covers v3 (mode routing + legacy forged-marker guard).
- WorkerJobEnqueueService: v3 jobs snapshot clusteringContractVersion=2 and
  representativeSplitDistance, mirroring the v2 pattern (ADR 0113
  job-snapshotted representative split).
- ClassInstanceDiscoveryService: SEMISUPERVISED_V3_METHOD provenance stamp
  recognized by isSemisupervisedMethod.
test(api): ADR 0113 v3 allowlist, V5 matrix and enqueue-stamping coverage
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 / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter 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
Build and Deploy / Run scoped PR tests (push) Successful in 2m28s
885e1b954b
- WorkerResultSemisupervisedEnvelopeTest: matrix accepts (v1,1),(v2,1),
  (v3,2); rejects (v3,1),(v3,3),(v1,2),(v2,2),(v3,null); envelope-method
  and envelope-version mismatch cases; legacy forged-v3 marker pair.
- PeopleClusteringControlsControllerTest: allowlist rejects unknown with
  v3 enumerated, accepts semisupervised-v3.
- PeopleClusteringMethodPostgresTest: PUT v3 writes the V149 column; an
  enqueue stamps clusteringContractVersion=2 (+ representativeSplitDistance).
- Spec050SemisupervisedPostgresTest: v3 provenance stamp mirrors the
  validated envelope method.
chris merged commit dd4a92b886 into main 2026-10-16 11:56:31 +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!1258
No description provided.