DIY Rental Platform — Slice 5: Move-in Handover and AI-Assisted Condition Report

Summary

Slice 5 turns a landlord's move-in walkthrough and a tenant's review into one immutable evidence package without asking the platform to decide fault. The complete manual path ships first; optional AI only drafts neutral photo descriptions after the uploader consents and never controls report state.

• StatusDraft for written review
• Core outcomeOne trusted move-in baseline per tenancy
• Party flowLandlord drafts; tenant reviews and accepts
• Review windowFixed seven calendar days
• AI featurerental:condition_photo_describe
• Authenticated UIfrontend/solidstart/apps/panel
• Delivery5a manual end-to-end; 5b AI assistant
• Next sliceMove-out comparison and deposit workflow

Depends on

2026-08-26-rental-platform-slice3-agreements-design.md and 2026-08-28-rental-platform-slice4-tenancy-payments-ai-design.md

Source brief

/Users/waynecheah/Downloads/DIY_Rental_Platform_Malaysia.md

Module

internal/modules/rental

Existing decisions

ADR-0056, ADR-0059, ADR-0062

Outcome and scope

Success criteria

• At most one move-in Handover Report exists for a Tenancy.
• The landlord drafts areas, condition, inventory, keys/access devices, and initial meter readings.
• Creation and submission are allowed only from seven calendar days before through three calendar days after starts_on, using Malaysia time.
• The tenant gets exactly seven calendar days to review; neither party chooses the length.
• With the uploader's per-report consent and available Rental AI, each image may receive editable, unconfirmed area/item and neutral-condition suggestions.
• The tenant disputes entries, reports omissions, attaches optional evidence, and accepts the complete report once; there is no per-entry acceptance.
• The landlord may accept a correction or reply without rewriting the submitted baseline.
• Completion or deadline expiry finalizes the report. Silence is explicitly no_tenant_response, never implicit acceptance.
• Final structured evidence and its deterministic PDF cannot change after finalization.
• Media remains private and party-authorized; APIs disclose neither object keys nor public URLs.

Included evidence and surfaces

Non-goals

Decisions and tradeoffs

Lifecycle and invariants

stateDiagram-v2
    [*] --> draft
    draft --> tenant_review: landlord submits in window
    tenant_review --> finalized: all threads resolved + tenant accepts hash
    tenant_review --> finalized: deadline ends
    finalized --> [*]
    note right of finalized
      tenant_accepted
      or deadline_elapsed
    end note    

Creation late boundary

Allowed through starts_on + 3 in Asia/Kuala_Lumpur; later creation is refused so a user cannot start a permanently un-submittable draft.

Submission window

starts_on - 7 through starts_on + 3 calendar days, inclusive.

Review deadline

Tenant may act through 23:59:59 Malaysia time on review_due_on; the sweep finalizes only after the date ends.

Late agreement

A tenancy established after its own window gets no report; the window is never re-anchored to establishment time.

• Only the tenancy landlord mutates the draft baseline.
• draft → tenant_review validates the window, entry requirements, ready evidence, and complete deterministic baseline snapshot in one transaction.
• Areas, entries, and attached baseline media are immutable after submission.
• Responses append only during tenant_review, through the end of review_due_on.
• Early finalization requires every dispute and omission thread resolved plus one explicit tenant acceptance. It scans no per-entry review state.
• Deadline finalization preserves open disputes, labels undisputed entries no_tenant_response, and creates no acceptance row.
• The same undisputed entry is labelled accepted_by_report_acceptance after explicit acceptance.
• No transition leaves finalized; AI has no transition authority.

Architecture and dependencies

flowchart LR
    UI["SolidStart panel"] --> HTTP["Rental HTTP adapters"]
    HTTP --> UC["Handover use cases"]
    UC --> D["Domain state + reducers"]
    UC --> DB["PostgreSQL repositories"]
    UC --> IMG["Image processor"]
    UC --> STORE["Private object store"]
    UC --> AI["Rental AICapability"]
    UC --> PDF["Deterministic PDF"]
    UC --> NOTIFY["Shared notification events"]
    SWEEP["Rental scheduler"] --> UC    

Reused seams

• Rental's hexagonal layout and functional-option wiring.
• Private-bucket Go streaming already used for ownership/payment proofs.
• Slice 3 deterministic, content-addressed PDF pattern.
• Slice 4 product-scoped AI authorization, vision runner, prompt service, capability filtering, kill-switch, caps, access records, and usage records.
• Existing Rental scheduler pattern and Slice 4's shared notification claim/retry worker.

The application container supplies a present-or-absent AICapability. Tests replace AI, image processing, storage, rendering, mail, and clock through functional options. Report use cases know no provider names and import no external AI adapter.

Data model

All tables are Rental-owned and created through migrator_rental.go. Action times are TIMESTAMPTZ; user-facing lifecycle boundaries are Malaysian calendar DATE values.

Reports, areas, and entries

Media and AI tables

Review and acceptance tables

Shared notification table

Slice 5 creates no notification table. It uses Slice 4's ADR-0062 table:

rental_notification_events(id, subject_type, subject_id, kind, recipient_user_id, status, attempt_count, next_attempt_at, last_error, provider_message_id, sent_at, created_at, updated_at)

The natural key is unique on (subject_type, subject_id, kind, recipient_user_id). Report-grain events use subject_type=handover_report; each response-grain event uses handover_response with the append-only response ID. Slice 5 does not write Slice 4's superseded status.

Canonical evidence

Canonicalization is server-owned, versioned with schema_version, and defined independently of Go map iteration, host timezone, storage keys, or database-driver numeric formatting.

Area and entry ordering

sort_order, then ID

Media ordering

Authoritative upload time, then ID

Response ordering

Server timestamp, then ID

Meter serialization

Exactly three decimal places: 88.400, never 88.4

Other fixed rules

JSON key order, timestamp format, and null handling

Party-authored labels, notes, comments, and replies are stored and rendered exactly as typed in UI, snapshots, PDF, and future comparisons. Only surrounding chrome is English; translating evidence would put words into a party's mouth.

AI boundary

Strict call contract

Feature

rental:condition_photo_describe

Product and mode

rental, platform mode; no landlord or tenant BYOK

Locale

en-MY; English-only chrome, PDF labels, and model output

Input

One consented metadata-stripped normalized derivative plus prompt; no object URL or user/NRIC/address/agreement/message data

Governance

Slice 4 vision-capability filter, global kill-switch, product caps, access event, usage record

{
  "suggested_area": "Kitchen",
  "suggested_item": "Lower cabinet door",
  "condition_note": "Visible horizontal scratch near the lower-left edge"
}

Every field is nullable, and null is the only uncertainty signal. The parser rejects prose, extra fields, overlong strings, and prohibited categories. An earlier unreadable_or_uncertain array was removed because it duplicated null, had no consumer, and invited editorialization.

Prohibited and permitted language

• moneyRM, ringgit, cost, price, quote, estimate, currency-adjacent digitsreject
• liabilityfault, blame, negligent, responsible, liable, caused byreject
• depositdeposit, deduct, forfeit, withholdreject
• adjudicationwear and tear, normal wear, pre-existing, tenant caused, landlord causedreject
• repairneeds repair, must be replaced, should be fixedreject
• severitysevere, serious, major, minor, badly, slightreject

Multi-word items are phrase tests. Visible-defect nouns such as damaged, scratch, stain, crack, chip, dent, mould, missing, and discoloured are permitted: they describe visible condition; severity grading is the first step toward a verdict. Party-authored text is never filtered.

Graceful absence and human authority

If AI is absent, disabled, capped, timed out, or invalid, the stored media remains ready and the uploader types manually. The media API reports AI status separately; a provider failure never turns successful evidence storage into HTTP 5xx.

Media flow and budgets

Upload and processing

1. Create or resume lifecycle

   An authenticated party supplies an idempotency key inside an editable workflow. Repeating it returns the existing lifecycle.

2. Preflight

   Validate declared type and size; create uploading row and private report/media key.

3. Store original

   Stream immutable bytes to the private store.

4. Decode safely

   Verify actual JPEG/PNG signature and safe pixel dimensions; fix orientation; reject decompression hazards.

5. Derive

   Create thumbnail and bounded, reoriented, EXIF/location-free AI copy; compute original SHA-256 and low-resolution warning.

6. Commit readiness

   Write all derivatives before marking ready. Failed rows stay out of snapshots and remain retryable/removable while editable.

Separate party budgets

• image bytesHard limit per JPEG/PNG before storage or AI5 MB
• baseline/reportLandlord-owned total100
• baseline/targetLandlord-owned per area or entry10
• response/reportCounted separately for each party50
• response/threadCounted separately for each party10

A shared pool is rejected because a thorough landlord baseline could consume the tenant's ability to prove an omission, and one party could crowd out the other's thread reply. These are conservative sizing assumptions, not validated market facts. Drafting UI must show remaining baseline capacity before the walkthrough becomes impossible to repeat.

Optional analysis

1. Verify uploader consent

   Check active per-report consent for the media's uploader and the active provider/config version. Mismatch or withdrawal sends no image, records unavailable, and prompts that uploader once.

2. Authorize governed feature

   Load the prompt and authorize rental:condition_photo_describe under product rental.

3. Send minimal derivative

   Pass only the metadata-stripped normalized bytes and prompt, with no object URL or unrelated tenancy data.

4. Record attempt

   Persist usage/error through the shared capability, parse strict nullable output, and copy consent provenance into the immutable suggestion row.

5. Let the human author evidence

   Show editable draft text. Area matching is client-side trim/case-fold highlighting or prefilling only; the server does no fuzzy model-driven assignment.

Party workflows

Landlord draft and submit

1. Create idempotently

   From the tenancy dashboard, require an existing Tenancy, the tenancy landlord, and Malaysian date no later than starts_on + 3.

2. Build the draft

   Suggested common areas are UI conveniences. The landlord adds, renames, reorders, or removes areas and records condition, inventory, access, and meter entries.

3. Attach evidence

   Upload images, optionally apply/edit AI labels and notes, and see missing fields, areas without images, meters without direct evidence, and remaining capacity.

4. Submit atomically

   Lock report/tenancy; validate party, status, window, entries, ready media, per-area images, and meter images; canonicalize and hash baseline; derive review_due_on; store submit audit data; enter tenant_review; enqueue tenant notification.

The submission transaction calls no AI, storage, image processor, mail transport, or PDF renderer.

Tenant review and thread exchange

1. Review the exact baseline

   The tenant sees the frozen snapshot and remaining time. Undisputed entries need no action.

2. Open specific claims

   Dispute any entry with required comment and optional evidence, or report an omitted condition against an area.

3. Alternate positions

   Either party replies with required text and optional ready evidence; the actor who spoke last cannot reply again.

4. Resolve or withdraw

   The other actor may resolve by accepting the current position; the tenant may withdraw their own dispute or omission. All prior events remain visible.

5. Freeze disagreement if necessary

   The deadline closes any still-open thread with both positions side by side. Nothing adjudicates it.

Early and deadline finalization

Acceptance and the sweep lock the same report row. Whichever commits first finalizes; the loser receives 409 with the finalized representation.

Final document

First authorized download renders final_snapshot, pins creation date to finalized_at, and caches deterministic bytes under the content hash. It groups by area and prints baseline observations, thumbnails, dispute/omission evidence, alternating replies/resolutions, resolved/unresolved/no-response labels, meter values, access quantities, separately labelled submission and tenant-acceptance timestamps/hashes, and the non-adjudication statement.

Authorization, privacy, and retention

Object keys and AI credentials never enter API responses or snapshots. The other tenancy party sees the ai_assisted marker, but provider/model/prompt/request/consent/raw-suggestion provenance remains internal. Original evidence may expose uploader-supplied metadata to the counterparty after explicit upload disclosure; only stripped derivatives leave the platform for AI.

Provisional retention position

• Malaysia PDPA 2010's Retention Principle argues against indefinite storage of home photos, IP addresses, and user agents.
• Limitation Act 1953 section 6 motivates six years for contract actions, but time runs from cause-of-action accrual, not automatically ends_on. The chosen anchor is a product simplification because it is the date this module owns.
• A later lifecycle design must revisit the anchor if deposit or other claims accrue later and implement legal/dispute holds.
• One party cannot unilaterally erase shared evidence while its purpose remains; proper request handling belongs to the deferred case-scoped capability.

HTTP contract

POST   /api/rental/tenancies/:id/handover-reports/move-in
GET    /api/rental/tenancies/:id/handover-reports
GET    /api/rental/handover-reports/:id

POST   /api/rental/handover-reports/:id/areas
PATCH  /api/rental/handover-areas/:id
DELETE /api/rental/handover-areas/:id

POST   /api/rental/handover-reports/:id/entries
PATCH  /api/rental/handover-entries/:id
DELETE /api/rental/handover-entries/:id

POST   /api/rental/handover-reports/:id/ai-consent
DELETE /api/rental/handover-reports/:id/ai-consent

POST   /api/rental/handover-reports/:id/media
PATCH  /api/rental/handover-media/:id
GET    /api/rental/handover-media/:id/content?variant=thumbnail|original
POST   /api/rental/handover-media/:id/analyze
DELETE /api/rental/handover-media/:id

POST   /api/rental/handover-reports/:id/submit
POST   /api/rental/handover-reports/:id/responses
POST   /api/rental/handover-reports/:id/accept
GET    /api/rental/handover-reports/:id/document

No report PATCH

After removing configurable review length, every report field is server-owned; route absence communicates that contract.

Media content default

variant=thumbnail; omission must not stream up to 500 MB across 100 drafting tiles.

Forbidden variant

ai_derivative is explicitly rejected; it is a provider-processing artifact, not evidence or a party rendering.

Variant privacy/cache

Thumbnail and original share identical party authorization and Cache-Control: private. Each validator matches returned bytes; never validate a thumbnail with original_sha256.

Review-state echo

GET /handover-reports/:id returns exactly the review_state_sha256 the client must echo on acceptance.

Discovery summary

id, status, review_due_on, finalized_at, finalization_reason; never entries, comments, or media.

Discovery is state-aware: a draft exists only for the landlord. From submission onward both parties discover and read the same frozen baseline. After the late boundary, an empty list becomes the permanent “move-in report not completed” state visible to either party.

PATCH /handover-media/:id accepts exactly one of area_id, entry_id, or response_id, from the uploader, within the same report and editable workflow. It patches no bytes, hashes, or warnings. Delete applies only to caller-uploaded staged or draft-baseline media. Responses are validated commands; no generic response PATCH/DELETE exists.

Notifications and errors

Durable notifications

Every kind is durable: each has a collision-free natural key and is harmful to lose. Slice 4's single worker claims, retries, and backs off the same row. Delivery failure never moves a deadline. Provider idempotency uses the event ID when available, but ambiguous network failures may still duplicate mail.

Error contract

Test strategy

Delivery plan

1. Prerequisites

   Land Slices 3/4: Tenancy and product-scoped vision.

2. Domain + draft

   Entities, migrations, rules, repositories, APIs.

3. Private media

   Decode safety, derivatives, limits; real-device iOS Safari test.

4. Landlord UI

   Drafting and baseline validation in panel.

5. Submit

   Atomic snapshot/hash, audit metadata, tenant notice.

6. Review

   Append-only reducer, omissions, alternating replies, tenant UI.

7. Finalize

   Acceptance, deadline sweep, final snapshot/UI.

8. Document

   Lazy deterministic PDF and concurrency tests.

9. AI

   Prompt/parser/provenance and opt-in assistant UI.

Release acceptance

Risks and open questions

What this unblocks

Slice 5 provides Slice 6's trusted “before” state for AI-assisted move-out comparison, party review, deposit deduction proposals, and deposit return. It also establishes stable area, inventory, media, and append-only evidence concepts for maintenance and periodic inspection without letting later workflows mutate the move-in baseline.