Real Estate Claims — Implementation Guide
Audience: Property developers, HOA boards, property managers, implementation teams. Vertical: Real Estate Development — large residential complexes, master-planned communities, apartment buildings, villa estates, retirement/lifestyle estates. Status: Configuration-only design; no bespoke tables, no schema changes. Substrate: Reuses Jijibora building/reflex/community infrastructure (see Jijibora Tie-In in the real estate doc set).
1. Claim Types — Real Estate
| Claim Type | CNS URI | Bound To | Typical Evidence Required |
|---|
| Defect / Snag Report | cns://claim/type/real-estate/defect | resource:unit | Photo, arrival point, inspector sign-off, contractor ID |
| Service Charge Dispute | cns://claim/type/real-estate/service-charge | claim:service-charge | Invoice, payment reference, lease terms, HOA board resolution |
| Construction Warranty Claim | cns://claim/type/real-estate/warranty | resource:unit | Handover certificate, defect list, contractor fix evidence, expiry date |
| HOA Assessment Dispute | cns://claim/type/real-estate/hoa-assessment | claim:governance/resolution | Vote record, BBS+ proof, resolution text, owner objection |
| Amenity Booking Dispute | cns://claim/type/real-estate/amenity-booking | resource:common-area | Booking confirmation, time slot, access log, cancellation policy |
| Lease / Tenancy Dispute | cns://claim/type/real-estate/lease | claim:lease | Lease agreement, rent payment history, notice to vacate, inspection report |
| Off-Plan Sale Claim | cns://claim/type/real-estate/sale | resource:unit | Sale agreement, payment schedule, handover certificate, title reference |
2. Guard Policies — Real Estate
All guard policies are declarative values loaded from NATS KV (SOVEREIGN_LOOKUPS). No hardcoded per-type stage lists.
2.1 Separation of Duties (SOD)
| Claim Type | Creator May Approve? | Barred Pairs | Notes |
|---|
| Defect / Snag | No | Inspector ↔ Contractor | Inspector certifies fix; contractor performs fix — different persons |
| Service Charge | No | Issuer ↔ Collector | Charge issuer and payment collector must be different |
| Warranty | No | Inspector ↔ Contractor | Same as defect |
| HOA Assessment | No | Voter ↔ Resolution Author | Owner who proposed resolution cannot be sole approver of objection |
| Amenity Booking | Yes (lenient) | — | Community ticket pattern; creator may approve |
| Lease Dispute | No | Landlord ↔ Tenant | Different parties; property manager mediates |
| Off-Plan Sale | No | Developer ↔ Buyer | Title transfer requires independent verification |
2.2 Quorum Bands (Amount × Risk → Named Quorum)
| Amount Range | Risk | Quorum | Approver Roles |
|---|
| < KES 50,000 | Low | One-person standard | Property manager |
| KES 50,000 – 500,000 | Mid | Two-person | Property manager + HOA board member |
| > KES 500,000 | High | Three-person | Property manager + HOA board + developer representative |
| Litigation | Any | Cross-agency | Legal counsel + external adjuster + board |
2.3 Evidence Requirements
| Claim Type | Required Evidence | Source |
|---|
| Defect / Snag | Photo (timestamped), arrival point (GPS), inspector sign-off | MinIO storage + PoCE receipt |
| Service Charge | Invoice, lease terms, payment reference | ERPNext integration + claim record |
| Warranty | Handover certificate, defect list, contractor fix evidence | Building safety inspection scenario |
| HOA Assessment | Vote record, BBS+ proof, resolution text | Community governance (s165) + PoCE |
| Amenity Booking | Booking confirmation, access log | Mall tenancy booking pattern |
| Lease Dispute | Lease agreement, rent history, inspection report | Lease register (append-only) |
| Off-Plan Sale | Sale agreement, payment schedule, title reference | Land registry mirror (integration_entity) |
3. Panel Roles — Real Estate
| Role | Capabilities Required | Attestation | Lease TTL | Claim Types |
|---|
| Property Manager | intake, distribution, maintenance_coordination | Yes | 1 hour | All |
| HOA Board Member | governance_vote, rule_enforcement, service_charge_approve | Yes | 8 hours | Service charge, HOA assessment |
| Contractor | motor_body_repair, defect_rectification, construction_repair | Yes | 1 hour | Defect, warranty |
| Inspector | loss_assessment, snag_inspection, safety_certification | Yes | 1 hour | Defect, warranty |
| Developer Representative | title_verification, handover_certificate, sale_approve | Yes | 8 hours | Off-plan sale, warranty |
| External Adjuster | loss_adjustment, litigation_evidence | Yes | 8 hours | High-value defects, litigation |
All roles require: approved affiliation + active status + attestation. Fail-closed: missing values refuse with a service error.
4. SLA Windows — Real Estate
| Claim Type | Severity | Default Window | Escalation To |
|---|
| Defect / Snag | Urgent | 48 hours | Property manager |
| Defect / Snag | Standard | 7 days | HOA board |
| Service Charge | Standard | 30 days | HOA board + finance |
| Warranty | Standard | 12 months (defects liability period) | Developer |
| HOA Assessment | Standard | 14 days | HOA board |
| Amenity Booking | Standard | 24 hours | Property manager |
| Lease Dispute | Standard | 30 days | Property manager + legal |
| Off-Plan Sale | Standard | 90 days | Developer representative |
Windows are values per type and severity, bound to the same workflow flow and namespace. Missing values refuse with a service error.
5. Intake Maps — Real Estate
| Map ID | Target | Fields Mapped | Source Channels |
|---|
intake:real-estate:defect | claim creation | unit_id, defect_type, description, photo_urls, severity, reported_by | WhatsApp, USSD, walk-in desk, API |
intake:real-estate:service-charge | claim creation | unit_id, charge_period, amount, invoice_ref, disputed_by | ERPNext, resident portal, walk-in |
intake:real-estate:warranty | claim creation | unit_id, handover_date, defect_list, contractor_id | Developer handover, inspector |
intake:real-estate:hoa-assessment | claim creation | resolution_id, voter_id, objection_reason, vote_proof | HOA meeting, AGM, portal |
Intake maps target claim creation only; any other target refuses. Preview validates against the target contract read-only.
6. PoCE Integration Points
| Transition | PoCE Trigger | Evidence Recorded |
|---|
| Defect reported | fn::lifecycle::start_poce_session | reporter, unit, severity, timestamp |
| Defect inspected | fn::lifecycle::record_poce_step | inspector, photos, arrival point, findings |
| Defect fixed | fn::lifecycle::record_poce_step | contractor, fix description, parts, completion photo |
| Defect signed off | fn::lifecycle::finalize_poce_session | inspector sign-off, handover certificate |
| Service charge disputed | fn::lifecycle::start_poce_session | unit, amount, invoice ref, dispute reason |
| Service charge resolved | fn::lifecycle::record_poce_step | resolution, adjustment, board approval |
| Warranty claim settled | fn::lifecycle::finalize_poce_session | contractor fix, inspector sign-off, certificate |
7. Worked Example — Defect / Snag Tracking
- Resident reports a water leak in unit A-1001 via WhatsApp intake.
- Claim created:
cns://claim/type/real-estate/defect, bound to resource:unit_A-1001, PoCE session started. - Property manager assigns inspector via panel eligibility (quorum: one-person for low severity).
- Inspector visits, records timestamped photo + GPS arrival point, logs defect findings.
- Contractor assigned via sourcing bus (qualified, nearest, certified), quote approved by property manager.
- Contractor fixes leak, uploads completion photo.
- Inspector re-visits, signs off on fix.
- Claim finalized with PoCE receipt: reporter → inspector → contractor → inspector sign-off chain.
- Escrow releases payment to contractor against verified proof (service charge finance desk).
Guard check: Inspector ≠ Contractor (SOD enforced). No payment without proof (escrow hold/release via fn::escrow::hold / fn::escrow::disburse).
8. What We Do Not Build
- No land-registry replacement. Title remains with the land registry; Sovereign OS mirrors title references via
integration_entity. - No dynamic property valuation. Unless expressible as solver-gateway capability + declarative lookups.
- No synthetic "optimal" repair route or service-charge budget. Solver down → 502/503 fail closed.
- No fake metrics (e.g., "98% defect resolution rate"). Live data or honest empty states.
9. Deployment
- Deploy strata:
s206_claim_dependency_cascade, s210_claim_validation_registry, s214_claim_arbitration, s233_unified_claims, s282_processing_claim - Seed CNS types:
cns://claim/type/real-estate/* - Seed lookups: guard policies, quorum bands, SLA windows, panel roles, intake maps in NATS KV
- Seed scenario packs: real estate defect, service charge, warranty packs
- Test:
GET /v1/claims/processing/readiness — all probes must pass before LIVE