TypeSafe Jev — Handover Dispute Sorting and Escalation
Jev helps with move-in handover disputes without grading damage: it matches a tenant's missing-item report to an existing report item for the landlord, and checks every thread comment for four fixed escalation reasons that only admins see. The original severity score is replaced because slice 5 bans AI severity grading toward the parties.
Summary
Jev helps with move-in handover disputes in two ways that do not grade damage. It matches a tenant's "missing item" report to an item already in the report, shown to the landlord only. It also checks every thread comment for four fixed escalation reasons, which only admins see. The idea's original severity score is replaced, because slice 5 bans AI severity grading toward the parties.
- Status
- Design approved in chat (2026-10-02), waiting for written-spec review
- Related
- Slice 5 move-in handover §4.7 and §5.1 (AI may not grade severity); Jev chat message check (admin findings list, email alert, retry sweep); ADR-0066 (raw text to TypeSafe); Decision model providers (provider switch, per-provider thresholds); ADR-0068 (call log and replay)
Why
In tenant review of a move-in handover report (入住交接报告), the tenant can open two kinds of thread. Both sides then reply in turns.
| Action | Target | Example |
|---|---|---|
dispute_entry (争议) | One item (HandoverEntry) | "Sofa: clean" but there is a stain |
report_omission (漏报) | One room (HandoverArea) | "The aircon remote is missing" |
- A missing-item report points only at a room. The landlord must work out whether it is really new or the same as an item already in the report ("aircon remote" vs the item "Remote control x2"). Plain code cannot match these.
- Nobody on the platform sees a serious problem. A thread can mention a gas smell, no water, black mould or a threat, and only the two parties read it.
What this delivers
Landlord
sorting- A type chip on each thread, set by plain code
- A filter by type
- On a missing-item thread: "May be about an existing item: Sofa (Living room)" when Jev finds a match
Admins
escalation- Every event with a comment, from either side, checked for four reasons
- Any "yes" → new panel list "Handover escalations"
- One email to all admins per thread
Tenant
unchanged- Gains only the type chip
- Never sees the match hint or any escalation
Decisions
H1 · What replaces the severity score?
Four fixed yes/no escalation reasons, admins only.
Keeps the slice 5 ban toward the parties. Each alert says why, so an admin can act.
Rejected: a 1–5 score for admins only (closer to the banned grading, says nothing about why); a 1–5 score for admins and the landlord (breaks the slice 5 rule toward a party).
H2 · Where does the thread type come from?
Plain code: the target item's EntryType, or "Missing from report" for report_omission.
The type is always right and costs no call. The comment already says what kind of disagreement it is.
Rejected: Jev picks a kind of disagreement from a fixed list (one more AI field to tune; sometimes wrong).
H4 · Which events does Jev check?
Matching runs on the opening report_omission event only. Escalation runs on every event with a comment, from tenant or landlord.
A thread's topic does not change. A threat or a hazard can appear in any reply.
Rejected: opening event only (misses later threats); every event for both checks (re-sorts the same thread on every reply).
H6 · Who sees the match hint?
The landlord and admins. The tenant does not.
It helps the person who answers. Shown to the tenant, it reads like the platform brushing off their claim.
Rejected: both parties (feels like taking sides); admins only (the landlord gets no help).
H7 · What can an admin do?
Mark reviewed or false_alarm. Anything else happens outside the app.
Copies the tested #1 pattern. Admin actions never change the report.
Deferred: extend the review deadline. Rejected: message both parties (tells them an AI flagged them).
| # | Decision | Why |
|---|---|---|
| H3 | Jev only (a) matches a missing-item report to an existing item and (b) answers the four reasons | The two things plain code cannot do |
| H5 | Text only: no photos | Jev is a text judge. Photos would need a vision model with its own cost and consent rules. |
| H8 | Results live in a new table, not on rental_handover_responses | Responses are append-only evidence that enters the final snapshot |
| H9 | The check is queued in the same transaction as the event and run by a sweep | No user waits on Jev, and no check is lost if the process stops |
| H10 | At most 100 checks per report | Replies alternate between the sides, so this is a safety limit, not a normal one |
| H11 | A new ADR covers both the privacy of sending comment text to TypeSafe and why admin-only escalation is not the grading slice 5 bans | Same reason ADR-0066 exists for chat |
Escalation reasons
Safety risk mentioned
safety_hazard
Danger to people: gas smell, exposed wiring, sparks, a loose railing or balcony, a cracked ceiling, broken glass.
"Socket in bedroom sparks when plugged in"
Unit not livable mentioned
not_livable
A basic need is missing: no water, no power, no working toilet, a major leak or flooding, a door that will not lock.
"No water in the whole unit since move-in"
Health risk mentioned
health_risk
Mould over a large area, a pest infestation (cockroaches, rats, bedbugs), sewage.
"Black mould covering the bathroom ceiling"
Threat or abuse mentioned
threat_or_abuse
One side threatens, harasses or insults the other.
"If you don't fix it I will come to your house"
Data
One migration. New table rental_handover_response_checks:
| Column | Type | Meaning |
|---|---|---|
response_id | uuid PRIMARY KEY REFERENCES rental_handover_responses(id) | The checked event |
report_id | uuid NOT NULL | For the per-report cap and the admin link |
thread_id | uuid NOT NULL | For one email per thread |
status | text NOT NULL | pending, done, skipped, failed (CHECK) |
ask_match | boolean NOT NULL | True only for an opening report_omission event |
escalation_reasons | text[] NOT NULL DEFAULT '{}' | Subset of the four codes |
match_entry_id | uuid NULL | Matched item, or null for "no match" |
attempts | int NOT NULL DEFAULT 0 | Failed Jev calls so far |
checked_at | timestamptz NULL | When done was saved |
alerted_at | timestamptz NULL | When the admin email was sent for this thread |
review_status | text NOT NULL DEFAULT 'open' | open, reviewed, false_alarm (CHECK) |
reviewed_by, reviewed_at | text NULL, timestamptz NULL | Admin review |
created_at | timestamptz NOT NULL | Event time |
Indexes:
(created_at) WHERE status = 'pending'for the sweep.(created_at DESC) WHERE escalation_reasons <> '{}'for the admin list.
review_status (open → reviewed / false_alarm) applies only to done rows with reasons.Backend
Queueing in AppendResponse
File: backend/go/internal/modules/rental/application/usecase/handover.go. Inside the existing transaction, after the response is inserted, a pending check row is inserted when all are true:
IsRentalHandoverCheckEnabled()is on;- the event has a non-empty comment;
- the report has fewer than 100 check rows. Otherwise the row is saved as
skipped.
ask_match is true only when Action == report_omission and the thread is new. A rollback leaves no row.
Sweep
HandoverCheckSweepUseCase, run every minute on the shared scheduler.RunPeriodic, started beside the message-check sweep.
- Switch check
Both switches off → do nothing.
- Claim
At most 20
pendingrows, oldest first (FOR UPDATE SKIP LOCKED). - Load context
The response, its target (item label and condition note, or room name), the room name, the author role and, when
ask_match, every item in the report as "Room – Item" with its id. - Judge
Call the judge once under a 10s timeout.
- Save on success
done, the reasons,match_entry_idandchecked_at. - Retry on failure
attempts + 1. At 5 attempts, or whencreated_atis older than 24h →failed. One row's failure does not stop the run. - Alert
When reasons are not empty and no row in the same
thread_idhasalerted_atset → email all admins and setalerted_at. A mail failure is logged; the row still shows in the admin list.
A report finalized while a row is pending is still checked.
Jev judge
- Port
port.HandoverCheckJudgewithJudge(ctx, HandoverCheckInput) (HandoverCheckResult, error). - Adapter
backend/go/internal/modules/rental/adapter/outbound/typesafe/handover_check_judge.go, shaped likeduplicate_judge.go. - State:
comment,author_role,target_label,target_condition_note,room, and when matching,itemsas[{key, label}]. Keys are short generated labels (i1,i2, …), mapped back to entry ids in code. No user ids, names, addresses or tenancy data. - Questions: four Noul questions, one per reason, plus one Choice question
matched_entryover the item keys andnonewhen matching. - The comment is passed only as state data, never inside a question.
Caller{rental, handover_check, <response id>}; every call is logged intypesafe_calls.cmd/replay-typesafeacceptshandover_check.- The judge returns the four probabilities and the match result to the use case. Only the codes and the entry id are stored, not the probabilities.
-
EscalationThresholdsreason = yes when p ≥ thresholdper provider 0.7 -
MatchThresholdsmatch when top choice ≠ none AND p ≥ thresholdper provider 0.7 -
per-report capcheck rows per report100 -
sweep batchpending rows per 1-minute run20 -
give upattempts ≥ 5 OR created_at older than 24h → failed5
Config and wiring
TYPESAFE_RENTAL_HANDOVER_ENABLED(defaultfalse),TYPESAFE_HANDOVER_PROVIDER(defaultjev), read inconfig.gobeside the other TypeSafe values.IsRentalHandoverCheckEnabled()= rental switch and handover switch both on.module.goresolves the provider and builds the judge like the duplicate judge. An unknown provider, or one missing from either threshold map, fails module start-up when the switch is on. With the switch off, no judge or sweep is started..env.examplelists both variables.
API
| Route | Who | Change |
|---|---|---|
| Handover report detail (existing) | Landlord | Each thread gains matched_entry_id (null when none or not checked) |
| Handover report detail (existing) | Tenant | No change: matched_entry_id is never sent |
GET /api/rental/admin/handover-escalations?status=open|all | Admin | Escalated events, newest first: id, time, property, report id, thread id, author role, reasons, comment, target label, review status |
GET /api/rental/admin/handover-escalations/:id | Admin | The whole thread, oldest first, with target and the thread's photo ids |
POST /api/rental/admin/handover-escalations/:id/review | Admin | Body {"status": "reviewed"|"false_alarm"}; stores who and when |
GET /api/rental/admin/handover-escalations/:id/media/:media_id | Admin | Streams one photo of that thread. Today GET /handover-media/:id/content serves only the two parties. A photo outside the escalated thread → 404. |
Frontend
Rental app (frontend/solidstart/apps/rental)
| Where | Change |
|---|---|
HandoverThreadList | A type chip on every thread: "Condition", "Inventory", "Access device", "Meter reading", "Missing from report". Both parties see it. |
HandoverThreadList, landlord only | A filter by type ("All" by default) |
HandoverThreadList, landlord only | On a missing-item thread with matched_entry_id: "May be about an existing item: {item} ({room})", linking to that item. Never says "duplicate" or "already covered". |
| While pending | Nothing shown; the hint appears on the next refresh |
Tenant: "The aircon remote is missing."
HandoverThreadList: type filter, type chip and match hint. The tenant sees the chip only.Panel app (frontend/solidstart/apps/panel)
| Where | Change |
|---|---|
| Sidebar | "Handover escalations", beside "Chat findings" |
/admin/rental/handover-escalations | List: time, property, report, author role, reason chips, comment, status. Filter Open (default) / All. |
| Row detail | The whole thread with target and photos; Mark reviewed and Mark false alarm |
Subject "Rental handover escalation". The body has the reason labels and a link to the panel row, and no comment text, like the chat alert. Idempotency key rental:handover-escalation:<thread id>.
Wording
Error handling
| Case | Result |
|---|---|
| Jev fails, times out or returns bad output | Stays pending; retried next run; 5 attempts or 24h → failed. No hint, no escalation. |
| Switch off | No new rows. Existing pending rows wait. Turning it on does not back-fill old events. |
Event without a comment (resolve, withdraw) | No row |
| 100 checks on one report | Further events → skipped |
| Matched item later removed | Cannot happen: areas and entries are immutable after submission (slice 5) |
| Admin email fails | Logged; the row is still in the admin list; no retry |
| Same thread escalated twice | One email (alerted_at) |
| Prompt injection in a comment | Comment is state data only; calibration set includes injection cases |
| Report finalized while pending | Still checked |
Testing
TDD: write a failing test first, then the code. Go tests run on pg-test (:55432), never UAT.
| Level | What | Where |
|---|---|---|
| Go unit | State holds only the listed keys; item keys map back to entry ids; thresholds per provider; exactly at threshold → yes / match; top choice none or below threshold → no match; unknown provider or missing threshold fails | typesafe/handover_check_judge_test.go, pin_test.go, module tests |
| Go use case | Row created only with a comment and the switch on; same transaction (rollback → no row); ask_match only on an opening report_omission; the 101st check → skipped | usecase handover tests |
| Go sweep | 20 per run; SKIP LOCKED claim; failure → retry; 5th failure or 24h → failed; one bad row does not stop the run; one email per thread across two escalations; switch off → no-op | usecase sweep tests |
| Go handler | Landlord detail carries matched_entry_id; tenant detail never does; no party response or final snapshot holds reasons; admin list and review 401 / 403 / 404 / 400 cases; review stores who and when | http/ tests |
| Migration | Table, CHECKs on status and review_status, indexes, rerun changes nothing | migrations/ tests |
| Frontend unit | Chip for every type; match hint and filter for the landlord only; panel list, filter, review buttons; golden test that every reason code has en / ms / zh text in both apps | Vitest |
| Calibration (not CI) | Labelled Malaysian English, Malay and Manglish comments, with traps ("safety pin missing", "kill the bugs") and injection cases. Sets the thresholds before the switch goes on outside UAT | cmd/ script, like #1 |
| Browser smoke | On UAT with /ego-browser: tenant opens a missing-item report and a "socket sparks" dispute; landlord sees the chip and the match hint; admin sees the escalation, gets the email and marks it reviewed | Manual run |
Out of scope
- Admin extends the review deadline (
review_due_on). Planned later; needs its own rules for the final snapshot. - Telling the parties that an admin is looking.
- Photos as input.
- Move-out reports and deposit decisions.
- A severity score in any form.
- Checking chat messages (idea #1 already does).
Launch gate
TYPESAFE_RENTAL_HANDOVER_ENABLED stays off outside UAT until:
- ADR accepted
The ADR in H11 is written and accepted.
- Calibration
The calibration run sets the two thresholds.
- Disclosure
The user disclosure covers handover comments sent to TypeSafe and admin review of escalated threads.