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.
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.
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 A | Landlord B | Today |
|---|---|---|
| Vista Komanwel, A-12-3 | Vista Komanwel Condo, A-12-3 | Missed — names differ |
| A-12-3 | A-12-03 | Missed — units differ |
| Unit typed inside the address line | Unit in the unit field | Missed |
| High-rise with no unit | anything | Never 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.
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.
| # | Decision | Choice |
|---|---|---|
| H1 | Goal | Catch missed cross-landlord duplicates. Not "cut false fingerprint flags" (rare) |
| H2 | On a "yes" | Save a Duplicate Hint. Admin confirms → Duplicate Flag. Jev never flags or holds by itself |
| H3 | Pairs | Different landlords only. Same-landlord duplicates are out of scope |
| H4 | Candidate search | Same trimmed postcode + one shared significant word, ranked by unit tokens, top 10. Plain SQL + Go, no new extension. SQL capped at 500 rows (H18) |
| H5 | Coverage | Creates 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) |
| H6 | Admin UI | One "Duplicates" page, two tabs: Possible (hints) and Flags |
| H7 | Switch | New TYPESAFE_RENTAL_DUPLICATE_ENABLED; runs only when it and TYPESAFE_RENTAL_ENABLED are on and the key is set |
| H8 | Storage | New table rental_duplicate_hints, one row per pair. Not a new status on rental_duplicate_flags |
| H9 | Queue | rental_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 |
| H10 | Privacy | Send address fields of the subject and up to 10 candidates. No names, emails or ids. See ADR-0067 |
| H11 | Flag origin | New rental_duplicate_flags.source: fingerprint (default) or jev. fingerprint column becomes nullable |
| H12 | Flag direction | On 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 |
| H13 | Dismiss | A dismissed pair is never asked again |
| H14 | Naming | Duplicate 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 |
| H15 | Pair already flagged | Show 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 |
| H16 | Hint freshness | Save 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 |
| H17 | Edit order | An address edit updates the property row (taking its lock) before deleting its open hints, in one transaction |
| H18 | Candidate cap | ORDER 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 |
| H19 | Blank postcode | A blank trimmed postcode is ineligible: due time cleared, no Jev call. Adding a postcode re-queues |
| H20 | Gone vs decided | Confirm or dismiss on a hint an address edit deleted → 404; on a decided hint → 409 hint_already_decided |
Rejected alternatives (18)
| Alternative | Why not |
|---|---|
| Jev reviews existing fingerprint flags to cut false ones | False flags are rare; missed duplicates are the real gap |
| Jev "yes" raises a Duplicate Flag directly | A flag can hold publication. An AI mistake would block a real landlord |
| Same-landlord matching too | A Duplicate Flag is never raised within one landlord. Needs its own outcome ("merge?") and UI |
pg_trgm fuzzy text search | Adds an extension and index. Revisit if admins report typo misses |
| pgvector address embeddings | Weak 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 word | A busy postcode holds more than 10 candidates; real matches get cut |
suggested status on rental_duplicate_flags | Every flag query must remember to skip it. One forgotten filter lets a guess hold a landlord |
| Hint JSON on the property row | A pair lives on two rows that must stay in step |
Reuse TYPESAFE_RENTAL_ENABLED alone | The 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 property | Any address change already re-queues the property |
| Newer property becomes the flagged side | 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 |
| Preselect a side in the confirm step | A default nudges the admin into the choice that punishes a landlord |
| Reuse an existing open flag, ignoring the admin's pick | Upheld could hit the side the admin did not choose |
| Gate hints on the candidate's due time | A 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 locks | Under 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 NULL | The 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 checked | Real matches beyond 500 rows would be dropped silently |
| Raw postcode equality | Every 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
| Env | Default | Effect |
|---|---|---|
TYPESAFE_API_KEY | empty | Existing |
TYPESAFE_RENTAL_ENABLED | false | Existing |
TYPESAFE_RENTAL_DUPLICATE_ENABLED | false | New. 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.gowith aWithDuplicateJudgeoption. 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:
| Event | Queued |
|---|---|
Panel Create | yes |
Panel Update with an address field changed | yes |
API Sync create, or any matched update (by external ref or by adopt) with an address field changed | yes |
| Any write to a test row | never |
"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)
UPDATE rental_properties— new address anddup_check_due_at. This takes the row lock.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:
-
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). -
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_overflowwith the subject id and postcode. Push the due time tonow() + 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. -
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)andNorm(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). -
3 · Go rank by unit-token overlap
Tokens come from
unit_numberplus digit/letter groups inaddress_line. Leading zeros are dropped:A-12-03→a,12,3. More shared tokens rank higher. Ties go to the newestupdated_at. Keep the top 10. -
4 · No candidates
Clear the due time (conditional, as step 6.5). No Jev call.
-
5 · Judge
With a 30 s
context.WithTimeout. -
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
idorder. The subject takesFOR UPDATE; hits takeFOR 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>. -
7 · Error
Log a zap warning, then
SET dup_check_due_at = now() + 1hwith the same condition.
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:
| Method | Notes |
|---|---|
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:
| Method | Notes |
|---|---|
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.
-
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. -
Check for an open flag —
FindOpenByPairAn open flag exists and its
property_idequalssuspect_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. -
Else create a flag
source='jev',fingerprint=NULL, statusopen,property_id=suspect_property_idfrom the request,matched_property_id= the other. -
Record the decision
Save
flag_id,decided_by,decided_aton 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
| Case | Result |
|---|---|
| Address changes while a hint is open | Open hints deleted; property re-queued (§5.3) |
| Address changes after a dismiss | Pair stays dismissed (H13). Accepted: rare, and the exact fingerprint check still runs |
| One property deleted | Hint removed by ON DELETE CASCADE |
| Fingerprint flag raised for a pair with an open hint | Hint 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 flags | Oldest is linked. open_flag_count > 1 tells the admin to inspect the rest on the Flags tab |
| Switch turned off mid-sweep | The current property finishes; the next tick returns early. Due times are kept |
| Jev returns fewer p values than candidates | Treated as an error (§5.4 step 7) |
| Property moves to another postcode | Queued by the address change; old open hints deleted |
| Subject's address edited during the Jev call | The 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 call | That hit is skipped; its edit re-queued it (H16) |
| Hit's due time changed, address unchanged | Hint saved (H16) |
| Two replicas lock overlapping pairs | Ascending id lock order; no deadlock (H16) |
| Hint deleted by an address edit while an admin confirms | 404; the panel refetches (H20) |
| Blank postcode | Not checked; due time cleared (H19) |
| More than 500 candidates | Overflow 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)
"Dosubjectandcandidates[i]describe the same rentable home — the same unit in the same building, or the same landed house?"
A-12-03vsA-12-3- "Vista Komanwel" vs "Vista Komanwel Condo"
- Unit in the unit field vs inside the address line
JlnvsJalan, Malay vs English building words
- 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 oncmd/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).
| Endpoint | Notes |
|---|---|
GET /api/rental/admin/duplicate-hints?status=open|all | Newest first, pagination.Wrap |
POST /api/rental/admin/duplicate-hints/:id/confirm | Body {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/dismiss | 204; 404; 409 hint_already_decided |
GET /api/rental/admin/duplicate-flags?status=open|all | New list. Newest first, paged |
POST /api/rental/admin/duplicate-flags/:id/resolve | Existing, 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_flagis the oldest open flag for the pair (FindOpenByPair).- For flags,
aisproperty_idandbismatched_property_id. has_verified_proofusesCountByProperty, 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.
| Part | Detail |
|---|---|
| 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 flagged | When 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 / dismiss | Toast "This pair changed and will be checked again", then refetch |
| 409 | hint_already_decided: toast "Another admin already decided this". pair_already_flagged: toast "This pair was flagged meanwhile". Both refetch |
| Wording | The 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 |
| i18n | Same 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.
The landlord app is unchanged. Landlords never see hints.
Testing
| Area | Test |
|---|---|
| Candidate filter | Postcodes 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 ranking | Leading zeros; unit inside address_line; tie-break by updated_at; top 10 |
| Sweep | Fake 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 |
| Queueing | Each 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 order | A hint from either side lands on the same row |
| Confirm / dismiss | Second 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 |
| Migration | Backfill 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' |
| Handlers | Admin role required; status filter; paging |
| Adapter | Builds 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:
- Gremlin confirming the landlord-facing disclosure covers addresses of never-submitted properties sent to TypeSafe for duplicate checks.
- Calibration using only synthetic pairs by default; real addresses need an explicit opt-in flag, gated on the same confirmation.
- 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
| Item | Why |
|---|---|
| Same-landlord duplicates | H3 |
pg_trgm or pgvector search | H4; revisit on reported misses |
| Different postcodes | H4 |
| Telling the landlord about a hint | Admin-only |
| Auto-flag or auto-hold from Jev | H2 |
| Undo a dismiss | Rare; add when asked |
| Admin view audit log | As ADR-0066 |
| Repeated API adopts insert a new fingerprint flag each time | Existing bug, tracked separately. This design only reads the oldest open flag |