中文版

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.

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

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.

  • Idea Jev #5 — dispute sorting
  • Area backend/go, rental app, panel app
  • Landlord sees Type chip, type filter, missing-item match hint
  • Tenant sees Type chip only
  • Admins see "Handover escalations" list + email
  • Switch TYPESAFE_RENTAL_HANDOVER_ENABLED (default off)
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.

ActionTargetExample
dispute_entry (争议)One item (HandoverEntry)"Sofa: clean" but there is a stain
report_omission (漏报)One room (HandoverArea)"The aircon remote is missing"
  1. 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.
  2. 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).

#DecisionWhy
H3Jev only (a) matches a missing-item report to an existing item and (b) answers the four reasonsThe two things plain code cannot do
H5Text only: no photosJev is a text judge. Photos would need a vision model with its own cost and consent rules.
H8Results live in a new table, not on rental_handover_responsesResponses are append-only evidence that enters the final snapshot
H9The check is queued in the same transaction as the event and run by a sweepNo user waits on Jev, and no check is lost if the process stops
H10At most 100 checks per reportReplies alternate between the sides, so this is a safety limit, not a normal one
H11A new ADR covers both the privacy of sending comment text to TypeSafe and why admin-only escalation is not the grading slice 5 bansSame 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:

ColumnTypeMeaning
response_iduuid PRIMARY KEY REFERENCES rental_handover_responses(id)The checked event
report_iduuid NOT NULLFor the per-report cap and the admin link
thread_iduuid NOT NULLFor one email per thread
statustext NOT NULLpending, done, skipped, failed (CHECK)
ask_matchboolean NOT NULLTrue only for an opening report_omission event
escalation_reasonstext[] NOT NULL DEFAULT '{}'Subset of the four codes
match_entry_iduuid NULLMatched item, or null for "no match"
attemptsint NOT NULL DEFAULT 0Failed Jev calls so far
checked_attimestamptz NULLWhen done was saved
alerted_attimestamptz NULLWhen the admin email was sent for this thread
review_statustext NOT NULL DEFAULT 'open'open, reviewed, false_alarm (CHECK)
reviewed_by, reviewed_attext NULL, timestamptz NULLAdmin review
created_attimestamptz NOT NULLEvent time

Indexes:

  • (created_at) WHERE status = 'pending' for the sweep.
  • (created_at DESC) WHERE escalation_reasons <> '{}' for the admin list.
Check row status. Admin review_status (open → reviewed / false_alarm) applies only to done rows with reasons
Check row status. Admin 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.

From thread event to admin email. The user never waits on Jev
From thread event to admin email. The user never waits on Jev.
  1. Switch check

    Both switches off → do nothing.

  2. Claim

    At most 20 pending rows, oldest first (FOR UPDATE SKIP LOCKED).

  3. 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.

  4. Judge

    Call the judge once under a 10s timeout.

  5. Save on success

    done, the reasons, match_entry_id and checked_at.

  6. Retry on failure

    attempts + 1. At 5 attempts, or when created_at is older than 24h → failed. One row's failure does not stop the run.

  7. Alert

    When reasons are not empty and no row in the same thread_id has alerted_at set → email all admins and set alerted_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.HandoverCheckJudge with Judge(ctx, HandoverCheckInput) (HandoverCheckResult, error).
  • Adapter backend/go/internal/modules/rental/adapter/outbound/typesafe/handover_check_judge.go, shaped like duplicate_judge.go.
  • State: comment, author_role, target_label, target_condition_note, room, and when matching, items as [{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_entry over the item keys and none when matching.
  • The comment is passed only as state data, never inside a question.
  • Caller{rental, handover_check, <response id>}; every call is logged in typesafe_calls. cmd/replay-typesafe accepts handover_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.
  • EscalationThresholds reason = yes when p ≥ thresholdper provider 0.7
  • MatchThresholds match when top choice ≠ none AND p ≥ thresholdper provider 0.7
  • per-report cap check rows per report 100
  • sweep batch pending rows per 1-minute run 20
  • give up attempts ≥ 5 OR created_at older than 24h → failed 5

Config and wiring

  • TYPESAFE_RENTAL_HANDOVER_ENABLED (default false), TYPESAFE_HANDOVER_PROVIDER (default jev), read in config.go beside the other TypeSafe values.
  • IsRentalHandoverCheckEnabled() = rental switch and handover switch both on.
  • module.go resolves 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.example lists both variables.

API

RouteWhoChange
Handover report detail (existing)LandlordEach thread gains matched_entry_id (null when none or not checked)
Handover report detail (existing)TenantNo change: matched_entry_id is never sent
GET /api/rental/admin/handover-escalations?status=open|allAdminEscalated events, newest first: id, time, property, report id, thread id, author role, reasons, comment, target label, review status
GET /api/rental/admin/handover-escalations/:idAdminThe whole thread, oldest first, with target and the thread's photo ids
POST /api/rental/admin/handover-escalations/:id/reviewAdminBody {"status": "reviewed"|"false_alarm"}; stores who and when
GET /api/rental/admin/handover-escalations/:id/media/:media_idAdminStreams 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)

WhereChange
HandoverThreadListA type chip on every thread: "Condition", "Inventory", "Access device", "Meter reading", "Missing from report". Both parties see it.
HandoverThreadList, landlord onlyA filter by type ("All" by default)
HandoverThreadList, landlord onlyOn 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 pendingNothing shown; the hint appears on the next refresh
All Condition Inventory Missing from report
Living room Missing from report

Tenant: "The aircon remote is missing."

May be about an existing item: Remote control x2 (Living room)
Landlord view of a missing-item thread in HandoverThreadList: type filter, type chip and match hint. The tenant sees the chip only.

Panel app (frontend/solidstart/apps/panel)

WhereChange
Sidebar"Handover escalations", beside "Chat findings"
/admin/rental/handover-escalationsList: time, property, report, author role, reason chips, comment, status. Filter Open (default) / All.
Row detailThe whole thread with target and photos; Mark reviewed and Mark false alarm

Email

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

CaseResult
Jev fails, times out or returns bad outputStays pending; retried next run; 5 attempts or 24h → failed. No hint, no escalation.
Switch offNo 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 reportFurther events → skipped
Matched item later removedCannot happen: areas and entries are immutable after submission (slice 5)
Admin email failsLogged; the row is still in the admin list; no retry
Same thread escalated twiceOne email (alerted_at)
Prompt injection in a commentComment is state data only; calibration set includes injection cases
Report finalized while pendingStill checked

Testing

TDD: write a failing test first, then the code. Go tests run on pg-test (:55432), never UAT.

LevelWhatWhere
Go unitState 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 failstypesafe/handover_check_judge_test.go, pin_test.go, module tests
Go use caseRow 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 → skippedusecase handover tests
Go sweep20 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-opusecase sweep tests
Go handlerLandlord 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 whenhttp/ tests
MigrationTable, CHECKs on status and review_status, indexes, rerun changes nothingmigrations/ tests
Frontend unitChip 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 appsVitest
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 UATcmd/ script, like #1
Browser smokeOn 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 reviewedManual 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:

  1. ADR accepted

    The ADR in H11 is written and accepted.

  2. Calibration

    The calibration run sets the two thresholds.

  3. Disclosure

    The user disclosure covers handover comments sent to TypeSafe and admin review of escalated threads.