DIY Rental Platform — Slice 4: Tenancy Establishment, Rent Ledger, and AI Payment Proof Matching

Executive summary

Slice 4 turns the signed agreement into a trustworthy operational ledger without making Gremlin a payment intermediary. Optional vision AI removes receipt transcription work, but deterministic rules validate the claim and only the landlord can decide that money was received.

• StatusReviewed draft · assumptions A1–A3 remain
• Core proofAgreement → tenancy → full fixed-term ledger
• Money boundaryExternal payments only; platform never holds funds
• Human gateLandlord confirmation is authoritative
• AI featurerental:payment_proof_extract
• AI fundingProduct-scoped platform key and caps
• CalendarAsia/Kuala_Lumpur
• Primary surfacesTenant ledger/upload + landlord review/notice

Outcomes and dependencies

Success criteria

• Agreement completion creates exactly one tenancy and the complete fixed-term charge schedule.
• One property cannot have overlapping completed tenancies, including through different listings.
• Landlord and tenant see the same upcoming, due, overdue, paid, and cancelled charges.
• Tenant manual or JPEG/PNG-proof payments and landlord-recorded cash/unreported transfers are complete without AI.
• With consent and available platform AI, receipt fields pre-fill; every unavailable or failed AI path preserves the manual flow.
• Ledger state changes only when the landlord confirms a tenant claim or records a receipt themselves.
• Every Day 1, Day 3, and Day 7 stage ends durably as sent, superseded, or failed; Day 7 offers a fixed notice to the landlord.
• Confirmations, rejections, reversals, reminders, charge transitions, and notices stay auditable.

Delivery dependencies

Slice 1

2026-08-24-rental-platform-slice1-listings-design.md · merged

Slice 2

2026-08-24-rental-platform-slice2-viewings-design.md · merged

Slice 3

2026-08-26-rental-platform-slice3-agreements-design.md · design approved, implementation must land first

Source brief

/Users/waynecheah/Downloads/DIY_Rental_Platform_Malaysia.md

Existing seams to reuse: the organization-less B2C Rental module and its domain/entity, application/{port,usecase}, adapter/{inbound,outbound} shape; optional WithPhotoStore, WithProofStore, and WithMailer adapters; private storage and authorized streaming; the existing reminder scheduler; and the AI module's provider construction, credential resolution, kill switch, prompts, access events, and usage accounting.

Scope

Explicit rejections

Core domain decisions

One Payment Record, two meanings

A mistaken confirmation is reversed, never deleted. Allocations remain as evidence with reversed_at, charges reopen atomically, and a reason is mandatory. “Void” remains reserved for ending an agreement before completion.

Charge cancellation stops the ledger

A landlord may cancel one open charge with a reason and later reopen it with another reason. The charge stays visible, cannot be selected or reminded, and every transition is appended to rental_charge_cancellation_events.

• Cancellation is allowed only from open, with no active allocation and no selecting pending_review record.
• Cancellation supersedes every remaining unsent reminder stage in the same transaction.
• Reopening never resurrects superseded stages; the next sweep sends only the highest applicable stage without an outcome.
• This is not tenancy termination, settlement, or deposit return; Slice 5 will reuse this action for remaining charges.

Payment creation survives storage failure

Every create uses a caller-supplied UUIDv7 record_id, a server-computed create_fingerprint_sha256, and a deterministic private proof key. Same ID + same fingerprint returns or completes the existing draft; same ID + different fingerprint returns 409 idempotency_conflict. A retry cannot create a second draft, AI attempt, or allocation.

Pending review suppresses escalation

A selected charge under pending_review receives no reminders and cannot generate a notice until the landlord decides. There is no clock-based expiry or automatic rejection because elapsed time cannot establish whether an external transfer occurred. The review queue is oldest-first and displays age.

AI matching and governance

Extract, match, decide

flowchart LR
    select["Tenant selects open charges"] --> proof["Store private JPEG or PNG proof"]
    proof --> consent{"Consent and config still match?"}
    consent -->|No| manual["Manual entry"]
    consent -->|Yes| cap{"Daily and product caps allow?"}
    cap -->|No| manual
    cap -->|Yes| vision["Governed vision extraction"]
    vision --> validate["Strict schema validation"]
    validate --> edit["Tenant confirms or edits fields"]
    manual --> edit
    edit --> rules["Exact-total validation, ai_agreement, duplicates"]
    rules --> review["Landlord review"]
    review -->|Confirm| alloc["Create active allocations"]
    review -->|Reject| rejected["Preserve rejected claim"]    

The model returns candidate fields only:

{
  "amount_sen": 175000,
  "paid_on": "2026-09-01",
  "reference": "MYBANK-8H3K2",
  "sender_name": "string or null",
  "sender_account_tail": "string or null",
  "recipient_name": "string or null",
  "recipient_account_tail": "string or null",
  "unreadable_fields": []
}

All extracted values except unreadable_fields may be null. The parser rejects prose, extra top-level fields, floating money, impossible dates, and overlong strings.

Three separate answers

duplicate_signals is a set containing neither, either, or both of same_reference and same_proof_hash. Reference normalization trims outer whitespace, collapses internal whitespace, and uppercases Unicode without removing punctuation. A match requires normalized reference + amount + tenancy on another submitted record; a proof match is exact SHA-256. Signals reveal nothing about the other record and never block submission.

Optional AI and bounded spend

• per_recordOne extraction attempt; PATCH never reruns vision1
• per_tenancy_dayAsia/Kuala_Lumpur day, atomically reserved before provider call10
• product_monthCalendar-month call/token caps in ai_product_configscap

Absent capability, kill switch, disabled config, cap, missing credentials, timeout, provider error, or invalid JSON never turns stored-proof success into HTTP 5xx. The caller receives the usable draft/manual form plus a separate AI status. Daily-cap copy is explicit: “AI assistance limit reached for this tenancy today. Your proof is saved; enter the details manually or try again tomorrow.”

Product-scoped platform AI

ai_product_configs controls enabled state, vision-capable provider/model, config_version, monthly caps/counters, period start, updater, and timestamps. Enabling requires platform eligibility, vision support, and available platform credentials. Access and usage rows have exactly one scope: organization_id xor product_key.

Private proof and informed consent

• Inline, versioned checkbox text states the data, named provider, possible processing outside Malaysia, sole extraction purpose, human payment decision, manual alternative, and landlord visibility of validated fields.
• The availability response provides provider + ai_config_version; create echoes them and stores ai_consent_provider + ai_consent_config_version.
• Immediately before sending bytes, authorization's chosen config must match the echo. A mismatch stores the proof, sends no image, sets AI unavailable, and asks the tenant to review new disclosure or continue manually.
• ai_provider, ai_model, and prompt version record what actually processed that upload.
• The provider receives image bytes, true media type, and extraction prompt only—never user IDs, NRIC, agreement PDF, messages, or unrelated tenancy data.
• Raw provider response is discarded; only validated extraction and processing metadata remain.

Drafts and unsubmitted proofs may be deleted by the tenant. Once submitted, proof and ai_result are shared review evidence and live exactly as long as the Payment Record under the platform retention schedule.

Privacy basis: PDPC Cross-Border Personal Data Transfer Guideline 3/2025 and Malaysia's PDPA principles, including retention.

Property overlap: prevent early, resolve terminally

flowchart TD
    offer["Landlord accepts Offer"] --> issueLock["Lock property row at Issue"]
    issueLock --> issueCheck{"Overlap with tenancy or non-voided agreement?"}
    issueCheck -->|Yes| reject["409 property_tenancy_overlap and conflicting_ends_on only"]
    issueCheck -->|No| agreement["Issue agreement"]
    agreement --> signatures["Parties sign"]
    signatures --> completeLock["Lock property row at completion"]
    completeLock --> completeCheck{"Overlap with established tenancy?"}
    completeCheck -->|No| establish["Complete + tenancy + charges in one transaction"]
    completeCheck -->|Yes| void["Keep signature; system-void loser with fixed reason"]
    void --> notify["Commit, notify both, return terminal 409"]    

Primary guard at Issue

Slice 3's issue transaction locks rental_properties, derives [starts_on, ends_on) from the accepted Offer, and rejects overlap with either an established Tenancy or a non-voided Agreement for the property. This closes the cross-listing gap created when an admin-suspended listing can be replaced while an older agreement remains in signing.

Completion defence in depth

Completion locks the property and rechecks established tenancies. If the residual race fires, rolling back is forbidden because it would discard the triggering signature and strand a fully signed agreement at awaiting_signatures. Instead, the transaction keeps the signature, moves the losing agreement to voided with property_let_under_another_agreement, commits, notifies both parties, and returns terminal 409 with the agreement reported voided.

Architecture

flowchart LR
    panel["SolidStart tenant and landlord surfaces"] --> http["Rental inbound HTTP adapters"]
    http --> usecases["Rental application use cases"]
    usecases --> domain["Tenancy, charge, payment domain"]
    usecases --> repos["PostgreSQL repositories and transactions"]
    usecases --> private["Private proof and notice storage"]
    usecases --> pdf["Deterministic notice renderer"]
    usecases --> mail["Mailer after commit or durable sweep"]
    usecases --> localAI["Narrow Rental AI port"]
    localAI --> gate["Shared product Access Gate"]
    gate --> runner["Vision runner and usage recording"]
    runner --> providers["Existing provider adapters"]    

rental/module.go obtains an optional AICapability from the container and adapts it to local interfaces. Rental never imports external provider adapters or constructs providers; tests inject fakes through the established functional-option pattern.

Minimum shared AI extension

1. Add SupportsVision bool / supports_vision to model metadata.
2. Add MediaType to VisionRequest; Rental sends base64, never ImageURL.
3. Add RunVision(ctx, authz, request) to Runner / AuthzRunner.
4. Add vision RunAndRecord parity so latency, total usage, and provider failure book exactly once. Like gated_call.go:46, record provider TokensUsed as output tokens; caps remain correct because adapters already sum totals (anthropic_provider.go:290), while input/output reporting remains imprecise and is out of scope.
5. Add AuthorizeProduct(...) and product configuration to the concrete Gate.
6. Support exactly one organization/product scope in access and usage persistence, including partial indexes, two upserts, product decisions, and report indexes.
7. Fix OpenAI, Anthropic, and Google adapters to use actual media type rather than hard-coded image/jpeg; reject non-vision provider/models before construction. Groq currently rejects vision.

Prompt contract

Load Prompt.GetActive for feature rental:payment_proof_extract, locale en-MY. It must transcribe visible information only, output exactly the schema, use integer Malaysian sen and ISO dates, return null + unreadable names rather than infer, and never judge authenticity, fraud, settlement, or payment state.

Email contract and reliability

Every email links to an authorized panel route and has no attachment. Time-triggered Day 1/3/7 mail uses durable retry events. Action-triggered mail is after-commit fire-and-forget; failure is logged and never changes a committed command. SMTP inside a transaction is forbidden.

Data model

All Rental tables are owned by migrator_rental.go. Money is integer sen, dates are DATE, and decision timestamps are TIMESTAMPTZ.

INSERT INTO rental_ai_daily_usage (tenancy_id, usage_date, attempt_count)
VALUES ($1, $2, 1)
ON CONFLICT (tenancy_id, usage_date) DO UPDATE
   SET attempt_count = rental_ai_daily_usage.attempt_count + 1,
       updated_at    = now()
 WHERE rental_ai_daily_usage.attempt_count < $3
RETURNING attempt_count;

State machines

stateDiagram-v2
    [*] --> draft: tenant creates
    draft --> draft: tenant edits
    draft --> pending_review: submits
    pending_review --> confirmed: landlord confirms
    pending_review --> rejected: landlord rejects
    confirmed --> reversed: landlord reverses
    [*] --> confirmed: landlord records receipt
    rejected --> [*]
    reversed --> [*]    

stateDiagram-v2
    [*] --> open
    open --> paid: active allocation created
    paid --> open: allocation reversed with reason
    open --> cancelled: landlord cancels with reason
    cancelled --> open: landlord reopens with reason    

Charge schedule

1. Start from frozen terms

   starts_on is the agreement start date; ends_on is the independently calculated term_months offset.

2. Anchor every boundary

   For offset n, use the original start day in month n, clamping only if that target month is shorter. Never add a month to the prior clamped date; raw Go time.AddDate is also wrong for 31 January.

3. Create deposits

   Security and utility deposits are monthly rent × agreed multiple, due on start. Zero-value deposits create no rows.

4. Create monthly rent

   One ordinary charge per month. Advance-rent months are the first N ordinary charges due on start, not extra rows; later rent is due on its period start.

5. Calculate in sen

   Convert whole-ringgit rent to sen before multiplying by allowed NUMERIC(4,1) deposit months, producing exact integer sen.

Authorization and privacy

• The generic landlord role grants no access to another landlord's tenancy; tenant access remains a row relationship, not an auth role.
• Authorize against the loaded tenancy before returning proof, AI metadata, notice metadata, or bytes.
• Reminder delivery exposes only a status word to the landlord; address, last_error, attempt count, and provider message ID remain server-side.
• Proof response is an authorized stream endpoint, never an object key or signed URL. AI evidence is visible to both parties; provider credentials are never exposed.

Operational flows

A · Agreement completion establishes tenancy

1. At Issue: lock property, derive interval, reject any tenancy/non-voided-agreement overlap with neutral 409.
2. At completion: lock property and recheck established tenancies.
3. On conflict: keep signature, system-void with fixed reason, commit, notify both, return terminal 409.
4. Otherwise complete agreement and set listing rented per Slice 3.
5. Insert tenancy from frozen terms and generate all deposit/rent charges.
6. Commit once, then notify both parties. Unique agreement makes retry return existing tenancy.

B · Tenant creates draft

1. Select open charges; optionally upload one JPEG/PNG ≤5 MB and choose AI assistance.
2. Require UUIDv7 record_id; validate, fingerprint, create/recover draft, stream deterministic private object, then set proof_ready_at. Proof-key-without-ready rows are hidden and recoverable; fully manual null/null drafts are valid.
3. Without proof, consent, or capability, return manual entry.
4. Load prompt and authorize product vision before reading proof bytes.
5. Reject consent/config race without sending bytes; preserve proof and manual draft.
6. Reserve daily attempt; cap returns explicit unavailable/manual response.
7. Read bytes, run vision once, record usage/error once, validate JSON, return candidate fields. Recompute warnings again at submit.

C · Tenant submits

1. Require amount, paid date, and ≥1 selected open charge; reference may be absent.
2. 422 unless selected total equals amount exactly.
3. Recompute duplicate signals and ai_agreement server-side; warnings never block.
4. Freeze fields/selection and move draft → pending_review.
5. Notify landlord with review link.

D · Landlord confirms or rejects

Confirm locks record and charges, rechecks pending/open state, inserts one allocation per charge, marks charges paid, timestamps with confirmation time, and commits atomically. Reject requires a reason, changes no charge, and notifies the tenant.

E · Landlord records received payment

One transaction requires paid date, method, open whole charges, and exact total; locks charges; inserts confirmed landlord record with ai_agreement = not_applicable, applicable reference duplicate warning, allocations, and paid charge state; commits and notifies tenant. No proof or AI is accepted.

F · Landlord reverses confirmation

With mandatory reason, lock record/allocations/charges, timestamp active allocations reversed, reopen charges and clear current paid_at, move to reversed, preserve actor/time/reason, commit, and notify tenant.

G · Cancel or reopen charge

Cancel requires open status, no allocation, no pending selector, reason, lock, append-only event, and superseding all remaining reminder outcomes in one transaction. Reopen requires reason and event; it does not resurrect prior reminder stages.

H · Reminder and notice ladder

Pending review suppresses all stages. When suppression ends, send only the highest applicable unsent stage and mark all lower missing/pending stages superseded atomically. Paid/cancelled charges are ignored. Mail retries five times, then landlord sees “reminder delivery failed” without diagnostics.

The landlord explicitly generates one deterministic PDF from a lawyer-reviewed fixed template containing structured blanks only: names, property address, agreement reference, charge period, amount, due date, and outstanding duration. It excludes NRIC, labels itself a platform payment reminder rather than legal advice or a law-firm demand, stores SHA-256 and template_version, and emails the tenant a link. No automatic generation, clause selection, conditional wording, or free text.

HTTP surface

GET    /api/rental/me/tenancies
GET    /api/rental/tenancies/:id
GET    /api/rental/tenancies/:id/charges

POST   /api/rental/tenancies/:id/payment-records
GET    /api/rental/payment-records/:id
PATCH  /api/rental/payment-records/:id
DELETE /api/rental/payment-records/:id          (draft only, tenant)
POST   /api/rental/payment-records/:id/submit
POST   /api/rental/payment-records/:id/confirm
POST   /api/rental/payment-records/:id/reject
POST   /api/rental/payment-records/:id/reverse
GET    /api/rental/payment-records/:id/proof

POST   /api/rental/charges/:id/cancel
POST   /api/rental/charges/:id/reopen
POST   /api/rental/charges/:id/late-payment-notice
GET    /api/rental/late-payment-notices/:id/document

GET    /api/v1/admin/ai-config/products/rental
PUT    /api/v1/admin/ai-config/products/rental

One create route serves exactly one tenancy party: tenant gets draft; landlord gets confirmed receipt; others get 403. Multipart is used only with proof; JSON serves manual and landlord paths. Every form requires UUIDv7 record_id. Party-inapplicable fields such as landlord proof/AI consent return 422. PATCH is draft-only and review actions remain separate commands.

Error contract

Testing strategy

Delivery order

1. 1 · Land Slice 3

   Approved agreement completion transaction first.

2. 2–3 · Tenancy ledger

   Entities, migrations, schedule/overlap tests, atomic establishment, repositories, authorized reads.

3. 4–5 · Payments

   Manual tenant/proof/duplicates, review/reversal, landlord receipts, after-commit mail.

4. 6–7 · Dunning

   Durable reminders, cancellation/reopen, reviewed deterministic notice and private download.

5. 8–9 · AI enhancement

   Shared vision/product scope first; then prompt, parser, comparison, consent, daily cap, fallback.

6. 10 · Panel UI

   Tenant ledger/upload and landlord review/notice flows.

Risks and mitigations

Open assumptions and launch gates

What this unblocks

Slice 4 completes the MVP's post-signature promise: shared rent tracking, reminders, and evidence without the cost and compliance surface of taking payments. The operational Tenancy aggregate supports later move-in condition reports, maintenance, utilities, renewals, termination, deposit return, and eventual gateway reconciliation. The product-scoped vision path is reusable by future B2C Rental features without inventing organizations or duplicating provider code.