中文版

TypeSafe Jev — Rental Duplicate Property Check

Adds TypeSafe Jev as a judge for rental duplicate properties that the exact address fingerprint misses. Code narrows candidates by trimmed postcode and a shared word, Jev scores each cross-landlord pair, and a strong yes becomes a Duplicate Hint that an admin must confirm, choosing the suspect side, before it becomes a normal Duplicate Flag.

  • Predecessor Builds on the 2026-09-23 TypeSafe Jev listing check (shared client, J13 naming, J21 code contract)
  • ADRs 0066
  • New ADR 0067
  • Status Approved

View source markdown ↗ generated by claude-opus-5-5 · diagrams mermaid

Summary

Two landlords can list the same home, and today only an exact address fingerprint catches it. This design adds TypeSafe Jev as a judge: code narrows candidates by postcode and shared words, Jev scores each pair, and a strong "yes" becomes a Duplicate Hint that an admin must confirm before it becomes a normal Duplicate Flag. Jev never flags or holds anything by itself.

  • Area backend/go, frontend/solidstart/apps/panel
  • Goal Catch missed cross-landlord duplicates (H1)
  • Output Duplicate Hint → admin confirm → Duplicate Flag
  • Switch TYPESAFE_RENTAL_DUPLICATE_ENABLED + TYPESAFE_RENTAL_ENABLED + key (default off)
  • Queue rental_properties.dup_check_due_at, sweep every 5 min, 20 per tick
  • Privacy Up to 11 landlords' addresses per call — ADR-0067
  • Admin surface Panel /admin/rental/duplicates: Possible + Flags tabs
  • Status Grill review closed (2026-09-26), ready for rendering

Related: Jev listing check (shared client, J13 naming, J21 code contract); Jev chat message check; Landlord API idempotent sync (fingerprint D18, publication hold D25, weak match D29, open risks §13); ADR-0067 (address privacy trade-off); CONTEXT.md — Duplicate Flag (flagged side), Duplicate Hint.

Why

The address fingerprint hashes the cleaned building or street name, the unit and the postcode. Only an exact match raises a Duplicate Flag. Exact matching misses the common cases:

Landlord ALandlord BToday
Vista Komanwel, A-12-3Vista Komanwel Condo, A-12-3Missed — names differ
A-12-3A-12-03Missed — units differ
Unit typed inside the address lineUnit in the unit fieldMissed
High-rise with no unitanythingNever checked — no fingerprint (D18)

This is the third rental use of TypeSafe. It reuses the merged shared client (internal/shared/infrastructure/typesafe/) and its call log.

What this delivers

  • Every non-test property with a postcode is checked once for missed cross-landlord duplicates, then again whenever its address changes. Existing properties are checked by a one-time backfill.
  • Code narrows the candidates. Jev judges each pair: "same home?".
  • A strong "yes" becomes a Duplicate Hint. It never holds anything.
  • Admins get a Duplicates page with two tabs: Possible (hints, "Same home, raise flag" / "Not a duplicate") and Flags (open Duplicate Flags, "Cleared" / "Upheld" — today these can only be resolved through the API).
  • A confirmed hint becomes a normal Duplicate Flag. The existing hold (D25) and resolve flow take over unchanged.
End-to-end flow: queue, sweep, Jev judgment, admin decision, existing flag flow
End-to-end flow: queue, sweep, Jev judgment, admin decision, existing flag flow.

Decisions

What happens on a Jev "yes"?

Save a Duplicate Hint. An admin confirms it into a Duplicate Flag (H2, H8).

A flag can hold publication. An AI mistake would block a real landlord. A separate table means no flag query can forget to skip a guess.

Rejected: Jev raises a flag directly; a suggested status on rental_duplicate_flags; hint JSON on the property row.

Which side does the new flag act on?

The admin must pick the suspect property. Nothing is preselected. It is saved as property_id, the flagged side that "Upheld" acts on (H12).

created_at is not evidence for Jev pairs. A backfilled pair may be years apart; the real owner can be the newer side, and Upheld would suspend them. Fingerprint flags keep their newcomer direction.

Rejected: newer property becomes the flagged side; preselect a side (a default nudges the admin into punishing a landlord).

How is a stale Jev answer kept out?

Lock subject and hit rows in ascending id order, then insert a hint only if both are still live, non-test, different-owner and their 8 judged address fields are unchanged (H16, H17).

Only an address change makes Jev's answer stale. Under READ COMMITTED a plain conditional insert reads the last committed row while an edit is still open; row locks make it wait for the edit.

Rejected: gate hints on the candidate's due time (ranking is not symmetric, pair lost for good); conditional insert without row locks.

#DecisionChoice
H1GoalCatch missed cross-landlord duplicates. Not "cut false fingerprint flags" (rare)
H2On a "yes"Save a Duplicate Hint. Admin confirms → Duplicate Flag. Jev never flags or holds by itself
H3PairsDifferent landlords only. Same-landlord duplicates are out of scope
H4Candidate searchSame trimmed postcode + one shared significant word, ranked by unit tokens, top 10. Plain SQL + Go, no new extension. SQL capped at 500 rows (H18)
H5CoverageCreates and address edits on every write path (panel, API create, API ref-matched update, API adopt), plus a one-time backfill of every existing non-test property. Blank postcodes are not checked (H19)
H6Admin UIOne "Duplicates" page, two tabs: Possible (hints) and Flags
H7SwitchNew TYPESAFE_RENTAL_DUPLICATE_ENABLED; runs only when it and TYPESAFE_RENTAL_ENABLED are on and the key is set
H8StorageNew table rental_duplicate_hints, one row per pair. Not a new status on rental_duplicate_flags
H9Queuerental_properties.dup_check_due_at. The backfill runs once, in the same migration DO block that adds the column, behind a transaction-scoped advisory lock. Later or concurrent boots never re-queue checked rows
H10PrivacySend address fields of the subject and up to 10 candidates. No names, emails or ids. See ADR-0067
H11Flag originNew rental_duplicate_flags.source: fingerprint (default) or jev. fingerprint column becomes nullable
H12Flag directionOn confirm, the admin must pick the suspect property. No side is preselected. Saved as property_id, the side "Upheld" acts on. Fingerprint flags keep their newcomer direction
H13DismissA dismissed pair is never asked again
H14NamingDuplicate Hint — new glossary term. Never call a hint a "flag" in UI or code. Text may say confirming a hint raises or links a Duplicate Flag. property_id is the flagged side
H15Pair already flaggedShow the oldest open flag and its flagged side. Confirm links it only if suspect_property_id equals its property_id, else 409 pair_already_flagged. An existing flag's direction is never changed. open_flag_count shows when there are several
H16Hint freshnessSave a hint only after locking the subject and hit rows in ascending id order and checking both are still live, non-test, different-owner, with the 8 judged address fields unchanged. Due time gates only clearing the subject
H17Edit orderAn address edit updates the property row (taking its lock) before deleting its open hints, in one transaction
H18Candidate capORDER BY updated_at DESC, id LIMIT 501. 501 rows = overflow: no Jev call, not cleared, distinct warning, retry in 24 h. Before enabling, a SQL count above 500 keeps the switch off
H19Blank postcodeA blank trimmed postcode is ineligible: due time cleared, no Jev call. Adding a postcode re-queues
H20Gone vs decidedConfirm or dismiss on a hint an address edit deleted → 404; on a decided hint → 409 hint_already_decided
Rejected alternatives (18)
AlternativeWhy not
Jev reviews existing fingerprint flags to cut false onesFalse flags are rare; missed duplicates are the real gap
Jev "yes" raises a Duplicate Flag directlyA flag can hold publication. An AI mistake would block a real landlord
Same-landlord matching tooA Duplicate Flag is never raised within one landlord. Needs its own outcome ("merge?") and UI
pg_trgm fuzzy text searchAdds an extension and index. Revisit if admins report typo misses
pgvector address embeddingsWeak on unit numbers; needs the Ollama embedder in production, a backfill and an embedding sweep; pgvector is optional per database
Same postcode only, no shared wordA busy postcode holds more than 10 candidates; real matches get cut
suggested status on rental_duplicate_flagsEvery flag query must remember to skip it. One forgotten filter lets a guess hold a landlord
Hint JSON on the property rowA pair lives on two rows that must stay in step
Reuse TYPESAFE_RENTAL_ENABLED aloneThe backfill queues the whole property table at once, and every subject with candidates sends up to 11 landlords' addresses; it needs its own privacy OK
Monthly re-check of every propertyAny address change already re-queues the property
Newer property becomes the flagged sidecreated_at is not evidence for Jev pairs. A backfilled pair may be years apart; the real owner can be the newer side, and Upheld would suspend them
Preselect a side in the confirm stepA default nudges the admin into the choice that punishes a landlord
Reuse an existing open flag, ignoring the admin's pickUpheld could hit the side the admin did not choose
Gate hints on the candidate's due timeA due time also changes when the candidate's own turn finishes. The ranking is not symmetric, so the pair would be lost for good
Conditional insert without row locksUnder READ COMMITTED it reads the last committed row while an address edit is still open
Backfill as a plain UPDATE ... WHERE dup_check_due_at IS NULLThe migrator re-runs every statement on boot, so each deploy would re-queue every checked property and re-send the addresses of those with candidates
Treat an overflowing subject as checkedReal matches beyond 500 rows would be dropped silently
Raw postcode equalityEvery blank postcode would match every other; "57000 " would miss "57000"

Provisional assumptions

These are not measured. If one proves wrong, revisit the named decision.

Scope

Checked

in scope
  • Live-mode properties from the panel and the API
  • Pairs with different owner_user_id
  • Pairs with the same trimmed postcode
  • Properties with a postcode
  • Pairs with no Duplicate Flag and no hint yet

Not checked

out of scope
  • Test rows (is_test)
  • Same-landlord pairs
  • Pairs whose postcodes differ (e.g. a typo on one side)
  • Properties whose trimmed postcode is blank (postcode is optional on save)
  • Pairs already flagged, hinted or dismissed

Backend: configuration

EnvDefaultEffect
TYPESAFE_API_KEYemptyExisting
TYPESAFE_RENTAL_ENABLEDfalseExisting
TYPESAFE_RENTAL_DUPLICATE_ENABLEDfalseNew. The duplicate sweep runs only when all three are set

The switch is read on every sweep tick, like the listing check. Queueing (§5.3) does not read the switch.

SELECT max(n) FROM (
  SELECT s.id, count(c.id) AS n
  FROM rental_properties s
  JOIN rental_properties c
    ON trim(c.postcode) = trim(s.postcode) AND c.owner_user_id <> s.owner_user_id
   AND c.is_test = false AND c.deleted_at IS NULL
  WHERE s.is_test = false AND s.deleted_at IS NULL AND trim(s.postcode) <> ''
  GROUP BY s.id
) t;

Backend: port and adapter

// DuplicateJudge asks Jev whether each candidate is the same home as the subject.
type DuplicateJudge interface {
    Judge(ctx context.Context, in DuplicateJudgeInput) ([]float64, error) // p per candidate, same order
}

type DuplicateJudgeInput struct {
    SubjectID  string // Caller.RefID only; never sent
    Subject    JudgedAddress
    Candidates []JudgedAddress // 1..10
}

type JudgedAddress struct {
    PropertyType string // landed | condo | ...
    BuildingName string
    AddressLine  string
    UnitNumber   string
    Area, City, State, Postcode string
}
Adapter
adapter/outbound/typesafe/duplicate_judge.go
Caller
Caller{App:"rental", Feature:"duplicate_check", RefID: SubjectID}
Call shape
One call, one Noul question per candidate (they run in parallel)
Wiring
module.go with a WithDuplicateJudge option. A nil judge means the sweep does nothing

Backend: queueing

dup_check_due_at = now() is set in the same transaction as the write when:

EventQueued
Panel Createyes
Panel Update with an address field changedyes
API Sync create, or any matched update (by external ref or by adopt) with an address field changedyes
Any write to a test rownever

"Address field" means PropertyType, BuildingName, AddressLine, UnitNumber, Area, City, State, Postcode. This is wider than the existing addressChanged (address line only), so it is a new helper.

On an address change, the same transaction also deletes open hints for that property (either side of the pair). If the pair still matches, the next sweep creates a fresh hint. Confirmed and dismissed hints stay.

Order inside the edit transaction (H17)

  1. UPDATE rental_properties — new address and dup_check_due_at. This takes the row lock.
  2. DeleteOpenByProperty.

Queueing ignores the switches. It costs nothing, and the backlog is picked up when the switches go on.

Backend: sweep — DuplicateCheckSweepUseCase

Runs every 5 minutes on scheduler.RunPeriodic. Each tick returns early unless the key and both switches are set and the judge is not nil, then loads the 20 properties with the oldest dup_check_due_at <= now(), not deleted, not test. For each, in order:

Candidate narrowing as nested stages: same trimmed postcode, other landlord, SQL cap of 500 rows; then Go filter by building class and shared word, excluding existing pairs; then top 10 by unit tokens; then hits at p of at least 0.7. Same postcode SQL ≤ 500 rows Class, shared word Go filter Unit-token rank top 10 Jev hits p ≥ 0.7
Candidate narrowing: each stage is a subset of the one around it. Only the innermost set becomes hints.
  1. 0 · Blank postcode

    trim(postcode) = '' → ineligible. Clear the due time (conditional, as step 6.5). No SQL, no Jev call. Adding a postcode later is an address edit, so it re-queues the property (§5.3).

  2. 1 · SQL — FindDuplicateCandidates(subject)

    Other owner_user_id, trim(postcode) = trim(subject.postcode), is_test = false, deleted_at IS NULL, ORDER BY updated_at DESC, id LIMIT 501. The order only makes the result repeatable. It does not make it complete: above 500 rows, real matches can still be cut.

    Overflow (501 rows): do not call Jev and do not clear the due time. Log a distinct zap warning duplicate_check_candidate_overflow with the subject id and postcode. Push the due time to now() + 24h (same conditional update as step 7), so an overflowing subject does not sit at the head of the queue and starve the rest. It stays queued until the retrieval design is revised.

  3. 2 · Go filter

    Same building class: landed vs not landed (the fingerprint's rule). Share at least one significant word — words come from Norm(building_name) and Norm(address_line) on each side. Stop-words dropped: jalan, lorong, taman, bandar, kampung, persiaran, block, residensi, residence, condo, kondominium, apartment, pangsapuri, and tokens that are only digits. Drop pairs with any hint (any status) or any Duplicate Flag (any status).

  4. 3 · Go rank by unit-token overlap

    Tokens come from unit_number plus digit/letter groups in address_line. Leading zeros are dropped: A-12-03 → a, 12, 3. More shared tokens rank higher. Ties go to the newest updated_at. Keep the top 10.

  5. 4 · No candidates

    Clear the due time (conditional, as step 6.5). No Jev call.

  6. 5 · Judge

    With a 30 s context.WithTimeout.

  7. 6 · Success — one short transaction

    6.1 Hits = candidates with p ≥ 0.7. No hits → skip to 6.5.

    6.2 Lock the subject and the hit rows in ascending id order. The subject takes FOR UPDATE; hits take FOR SHARE. A stable order means two replicas cannot deadlock.

    6.3 Subject: must still be live (deleted_at IS NULL), non-test, and its 8 judged address fields must equal what Jev saw. Otherwise insert no hints and leave it queued (its edit already re-queued it). Go to 6.5.

    6.4 Each hit: must be live, non-test, a different owner_user_id, and its 8 judged address fields must equal what Jev saw. Otherwise skip it (its edit re-queued it). Insert the rest (ON CONFLICT (property_a_id, property_b_id) DO NOTHING).

    6.5 UPDATE ... SET dup_check_due_at = NULL WHERE id = ? AND dup_check_due_at = <value read in step 2>.

  8. 7 · Error

    Log a zap warning, then SET dup_check_due_at = now() + 1h with the same condition.

Edit vs sweep race: the edit takes the row lock first, so the sweep waits and sees the new address
Edit vs sweep race: the edit takes the row lock first, so the sweep waits and sees the new address.

Backend: tables

rental_properties

-- Column add and backfill together: the backfill runs once, on the boot that adds
-- the column, never again.
DO $$
BEGIN
  -- The migrator has no lock, so two replicas may boot together. Without this lock
  -- both could pass the check below before either commits, and both would backfill.
  -- The loser waits here until the winner commits, then sees the column and skips.
  PERFORM pg_advisory_xact_lock(hashtext('rental_properties.dup_check_due_at_backfill'));
  IF NOT EXISTS (
    SELECT 1 FROM information_schema.columns
    WHERE table_schema = current_schema()
      AND table_name = 'rental_properties' AND column_name = 'dup_check_due_at'
  ) THEN
    ALTER TABLE rental_properties ADD COLUMN dup_check_due_at TIMESTAMPTZ;
    UPDATE rental_properties SET dup_check_due_at = now()
      WHERE is_test = false AND deleted_at IS NULL;
  END IF;
END $$;
CREATE INDEX IF NOT EXISTS idx_props_dup_check_due
  ON rental_properties (dup_check_due_at)
  WHERE dup_check_due_at IS NOT NULL AND deleted_at IS NULL AND is_test = false;

rental_duplicate_hints (new)

CREATE TABLE IF NOT EXISTS rental_duplicate_hints (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  property_a_id UUID NOT NULL REFERENCES rental_properties(id) ON DELETE CASCADE,
  property_b_id UUID NOT NULL REFERENCES rental_properties(id) ON DELETE CASCADE,
  p             DOUBLE PRECISION NOT NULL,
  status        TEXT NOT NULL DEFAULT 'open'
                CHECK (status IN ('open','confirmed','dismissed')),
  flag_id       UUID REFERENCES rental_duplicate_flags(id) ON DELETE SET NULL,
  decided_by    TEXT,
  decided_at    TIMESTAMPTZ,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  CHECK (property_a_id < property_b_id)
);
CREATE UNIQUE INDEX IF NOT EXISTS uq_dup_hints_pair
  ON rental_duplicate_hints (property_a_id, property_b_id);
CREATE INDEX IF NOT EXISTS idx_dup_hints_open
  ON rental_duplicate_hints (created_at) WHERE status = 'open';

The pair is stored in sorted order (a < b), so one pair has one row whichever side was judged.

rental_duplicate_flags

ALTER TABLE rental_duplicate_flags
  ADD COLUMN IF NOT EXISTS source TEXT NOT NULL DEFAULT 'fingerprint'
    CHECK (source IN ('fingerprint','jev'));
ALTER TABLE rental_duplicate_flags ALTER COLUMN fingerprint DROP NOT NULL;

Existing flag code keeps working: it never reads source, and it always writes a fingerprint. entity.DuplicateFlag.Fingerprint becomes *string. All of this lands in migrator_rental.go as a new Create... function called from RunMigrations.

Repository methods

DuplicateHintRepository:

MethodNotes
SaveHints(ctx, subjectID string, hits []HintHit)Sorts each pair; ON CONFLICT DO NOTHING
DeleteOpenByProperty(ctx, propertyID)Used on address change (§5.3)
ExistingPairs(ctx, subjectID, candidateIDs)For the §5.4 filter
List(ctx, status, limit, offset)Admin list
Confirm(ctx, id, adminID, flagID) (bool, error)WHERE status='open'
Dismiss(ctx, id, adminID) (bool, error)WHERE status='open'

PropertyRepository gains:

MethodNotes
ListDupCheckDue(ctx, limit)§5.4 step 2; oldest dup_check_due_at first
FindDuplicateCandidates(ctx, subject, limit)Step 3.1; trimmed postcode, ORDER BY updated_at DESC, id
LockForDuplicateHints(ctx, subjectID, hitIDs)Step 6.2; ascending id, subject FOR UPDATE, hits FOR SHARE; returns the current rows for the 6.3 / 6.4 checks. Must run inside the step 6 transaction
SetDupCheckDue(ctx, id, readDue, next) (bool, error)Steps 3.0, 3.1 overflow, 3.4, 6.5 and 7; WHERE dup_check_due_at = readDue; next nil clears

The address-edit write uses UPDATE rental_properties then DeleteOpenByProperty in that order (H17, §5.3).

DuplicateFlagRepository gains List(ctx, status, limit, offset) and FindOpenByPair(ctx, a, b) (oldest *DuplicateFlag, openCount int, err error). It matches either direction and picks the oldest open flag (created_at, then id), so the choice is stable.

Backend: confirm and dismiss

Confirm, in one transaction. suspect_property_id must be one of the hint's two properties, else 400 invalid_suspect_property; this is checked before step 1.

  1. Mark the hint confirmed

    Confirm(... WHERE status='open'). No row changed → re-read the hint: missing → 404 (an address edit deleted it); decided → 409 hint_already_decided.

  2. Check for an open flag — FindOpenByPair

    An open flag exists and its property_id equals suspect_property_id → link its id. Otherwise → 409 pair_already_flagged, nothing written. This covers a flag that appeared after the page loaded, or a stale choice. The existing flag's direction is never changed.

  3. Else create a flag

    source='jev', fingerprint=NULL, status open, property_id = suspect_property_id from the request, matched_property_id = the other.

  4. Record the decision

    Save flag_id, decided_by, decided_at on the hint.

The existing D25 hold and ResolveDuplicateFlag then apply unchanged. "Upheld" acts on property_id only (review.go ResolveDuplicateFlag).

Dismiss: the same WHERE status='open' guard and the same 404 / 409 split, then decided_by, decided_at.

Edge cases

CaseResult
Address changes while a hint is openOpen hints deleted; property re-queued (§5.3)
Address changes after a dismissPair stays dismissed (H13). Accepted: rare, and the exact fingerprint check still runs
One property deletedHint removed by ON DELETE CASCADE
Fingerprint flag raised for a pair with an open hintHint stays open. The panel shows the existing flag; confirm links it (§5.6 step 2). Happens on API adopt and during a Jev call
Pair has several open flagsOldest is linked. open_flag_count > 1 tells the admin to inspect the rest on the Flags tab
Switch turned off mid-sweepThe current property finishes; the next tick returns early. Due times are kept
Jev returns fewer p values than candidatesTreated as an error (§5.4 step 7)
Property moves to another postcodeQueued by the address change; old open hints deleted
Subject's address edited during the Jev callThe edit waits on the row lock, or the sweep sees the new address. No hints saved; subject stays queued (H16)
Hit's address edited during the Jev callThat hit is skipped; its edit re-queued it (H16)
Hit's due time changed, address unchangedHint saved (H16)
Two replicas lock overlapping pairsAscending id lock order; no deadlock (H16)
Hint deleted by an address edit while an admin confirms404; the panel refetches (H20)
Blank postcodeNot checked; due time cleared (H19)
More than 500 candidatesOverflow warning; stays queued, retried in 24 h (H18)

Questions and threshold

State sent to Jev

{
  "subject": { "property_type": "condo", "building_name": "Vista Komanwel Condo",
               "address_line": "Jalan 1/62A, Bukit Komanwel", "unit_number": "A-12-03",
               "area": "Bukit Jalil", "city": "Kuala Lumpur", "state": "WP Kuala Lumpur",
               "postcode": "57000" },
  "candidates": [
    { "property_type": "condo", "building_name": "Vista Komanwel", "...": "..." }
  ]
}

No ids, owner names or emails. Candidates are referred to by position.

Question (Noul, one per candidate)

"Do subject and candidates[i] describe the same rentable home — the same unit in the same building, or the same landed house?"
Yes cases
  • A-12-03 vs A-12-3
  • "Vista Komanwel" vs "Vista Komanwel Condo"
  • Unit in the unit field vs inside the address line
  • Jln vs Jalan, Malay vs English building words
Trap cases (no)
  • Same building, different unit
  • Same street, different house number
  • "Taman Desa" vs "Taman Desa Jaya"
  • Same unit number, different building in the same postcode

Threshold and calibration

Threshold
0.7, a Go constant beside the adapter. Calibration sets the real value before the switch goes on
Eval tool
cmd/eval-duplicate-check, modelled on cmd/eval-listing-check
Dataset
About 30 synthetic pairs covering the yes and trap cases, in English and Malay address styles
Real addresses
Need an explicit opt-in flag, gated on ADR-0067

API

All endpoints are in the rental admin group (admin, superadmin).

EndpointNotes
GET /api/rental/admin/duplicate-hints?status=open|allNewest first, pagination.Wrap
POST /api/rental/admin/duplicate-hints/:id/confirmBody {suspect_property_id} (required). 200 {flag_id}; 400 invalid_suspect_property; 404; 409 hint_already_decided; 409 pair_already_flagged
POST /api/rental/admin/duplicate-hints/:id/dismiss204; 404; 409 hint_already_decided
GET /api/rental/admin/duplicate-flags?status=open|allNew list. Newest first, paged
POST /api/rental/admin/duplicate-flags/:id/resolveExisting, unchanged

Row shape (hints and flags share it):

{
  "id": "...",
  "p": 0.94,                   // hints only
  "source": "jev",             // flags only
  "status": "open",
  "created_at": "...",
  "a": { "property": { ...address fields, "id", "created_at" },
         "owner": { "user_id", "name", "email" },
         "listing_status": "live",     // null when no active listing
         "has_verified_proof": true },
  "b": { ...same },
  "open_flag": { "id": "...", "property_id": "...", "open_flag_count": 2 }  // hints only; null when none
}
  • open_flag is the oldest open flag for the pair (FindOpenByPair).
  • For flags, a is property_id and b is matched_property_id.
  • has_verified_proof uses CountByProperty, the same check D25 uses, so the admin can see whether a hold applies.

Panel — /admin/rental/duplicates

File: apps/panel/src/routes/admin/rental/duplicates/index.tsx.

PartDetail
Sidebar"Duplicates" beside Listings in apps/panel/src/app.tsx, with the count of open hints + open flags
Tab "Possible"Table of open hints. A row opens a side panel: two properties side by side, differing fields highlighted, owners, listing status, proof. Buttons: Same home, raise flag, Not a duplicate. "Same home" opens a confirm step: the admin must choose which property is the suspect. Nothing is preselected, and the submit button stays disabled until one is chosen. The text says "If this flag is later Upheld, this property's listings are suspended or rejected"
Tab "Flags"Table of open flags with a source badge ("Exact match" / "Jev"). Buttons: Cleared, Upheld, with an optional note
Pair already flaggedWhen a hint has open_flag, the confirm step shows no picker. It names the flagged side and says "Upheld will suspend or reject this property's listings". The button is Link to existing flag and sends that property_id. If open_flag_count > 1, it says "This pair has N open flags" with a link to the Flags tab
404 on confirm / dismissToast "This pair changed and will be checked again", then refetch
409hint_already_decided: toast "Another admin already decided this". pair_already_flagged: toast "This pair was flagged meanwhile". Both refetch
WordingThe Possible tab never calls a hint a flag (H14). It may say "Confirming raises or links a Duplicate Flag". "Flagged side" names the side Upheld acts on
i18nSame rule as the chat findings page (chat spec §8.2)

Same home — which property is the suspect?

Confirming raises or links a Duplicate Flag. Jev p = 0.94.

Vista Komanwel Condo, A-12-03, 57000
Landlord A · listing live · verified proof
Vista Komanwel, A-12-3, 57000
Landlord B · no active listing · no proof
If this flag is later Upheld, this property's listings are suspended or rejected.
Cancel Raise flag
Panel confirm-step mockup — no side preselected; submit disabled until the admin picks the suspect.

The landlord app is unchanged. Landlords never see hints.

Testing

AreaTest
Candidate filterPostcodes compared trimmed ("57000 " matches "57000"); blank-postcode candidates never match; stop-words; digit-only tokens ignored; landed vs high-rise; existing hint/flag pairs dropped
Unit rankingLeading zeros; unit inside address_line; tie-break by updated_at; top 10
SweepFake judge. Hint saved at p ≥ 0.7, none below. No candidates → no call, due cleared. Error → +1h. Blank trimmed postcode → no SQL, no call, due cleared. Due changed mid-call → stays queued. 501 candidates → no call, warning logged, due pushed +24h, not cleared. Subject address changed mid-call → no hints, stays queued. Hit address changed → that hit skipped, others saved. Hit due changed but address same → hint saved. Hit deleted, now test, or same owner → skipped. Edit transaction blocked by sweep lock then deletes the new hint (pg-test, two connections). Switch off → no work. Wrong p count → error path
QueueingEach address field change queues, on panel update, API ref-matched update and API adopt; a non-address edit does not; adding a postcode to a blank one queues; test rows never; address change deletes open hints only
Pair orderA hint from either side lands on the same row
Confirm / dismissSecond action 409; hint deleted by an address edit → 404; existing flag reused only when its property_id matches, else 409 pair_already_flagged and no write; oldest of several open flags chosen; suspect_property_id becomes property_id, missing or foreign id → 400, older side can be the suspect; after confirm, Submit returns duplicate_under_review per D25
MigrationBackfill sets due time only for live-mode, non-deleted rows; running migrations a second time does not re-queue checked rows; concurrent boot (pg-test, two connections run the DO block at once) → the column is added once, the backfill UPDATE runs once, and no error; old flags get source='fingerprint'
HandlersAdmin role required; status filter; paging
AdapterBuilds state without ids; maps p by position; Caller fields
Panel (vitest)Both tabs render; buttons call the right endpoints; 409 toast; confirm disabled until a suspect is chosen, no side preselected

Rental Go tests run with -p 1 against pg-test.

Privacy — ADR-0067

Turning TYPESAFE_RENTAL_DUPLICATE_ENABLED on is gated on:

  1. Gremlin confirming the landlord-facing disclosure covers addresses of never-submitted properties sent to TypeSafe for duplicate checks.
  2. Calibration using only synthetic pairs by default; real addresses need an explicit opt-in flag, gated on the same confirmation.
  3. The pre-enable candidate-count check returning 500 or less (not a privacy gate — it stops the backfill starting while any postcode overflows the cap).

Out of scope

ItemWhy
Same-landlord duplicatesH3
pg_trgm or pgvector searchH4; revisit on reported misses
Different postcodesH4
Telling the landlord about a hintAdmin-only
Auto-flag or auto-hold from JevH2
Undo a dismissRare; add when asked
Admin view audit logAs ADR-0066
Repeated API adopts insert a new fingerprint flag each timeExisting bug, tracked separately. This design only reads the oldest open flag