Architecture Mapping — Real Estate Operations to Canonical Primitives

Status: Technical Specification
Sources: Playbook Engine Architecture & Runtime Execution Model §2, Integration Matrix & System Adapters Specification, Jijibora Architecture — Design Thesis in Developer Terms, AGENTS.md — Sovereign OS / Cosmic Circuit Schema Architecture

1. Governing Rule — Zero Bespoke Tables

No real-estate-specific tables (unit_sale, hoa_vote, service_charge, snagging_defect, lease_agreement, amenity_booking) are created. Every development entity maps to the existing canonical base infrastructure:

claim — sale agreements, leases, service charges, defect/snag reports, amenity bookings, rule violations (CNS-typed, traits, signatures)
truth_node & truth_edge — structural relationship graph (owner→unit, tenant→unit, unit→building, charge→unit, vote→resolution)
resource & resource_edge — tangible assets (units, common areas, amenities, budget pools, service-charge funds)
integration_entity (Stratum 356) — universal mirror for external records (land registry, ERPNext invoice, access-control card, CRM lead)
s184_record_federation — boundary security for records crossing developer/HOA/vendor boundaries

If an entity cannot be mapped to these primitives, stop and ask — do not create a new table.

2. Canonical Mapping Table

Real Estate Concept	Canonical Primitive	CNS Type / Binding	Example Fields
Unit (apartment/villa/home)	`resource`	`cns://resource/unit`	unit number, block, floor, type, size, status, price
Owner / proprietor	`truth_node`	`cns://truth/node/person`	name, ID, contact, ownership share, voting rights
Tenant / lessee	`truth_node`	`cns://truth/node/person`	name, ID, lease start/end, deposit
Developer / management company	`truth_node`	`cns://truth/node/organization`	registration, license, contact
Sale agreement (off-plan / resale)	`claim`	`cns://claim/type/real-estate/sale`	unit, buyer, price, payment schedule, handover date
Lease agreement	`claim`	`cns://claim/type/real-estate/lease`	unit, tenant, rent, deposit, term, renewal
Service charge	`claim`	`cns://claim/type/real-estate/service-charge`	unit, amount, period, due date, status
Defect / snag report	`claim`	`cns://claim/type/real-estate/defect`	unit, description, photo, severity, contractor, status
Amenity booking	`claim`	`cns://claim/type/real-estate/amenity-booking`	unit, amenity (gym/pool/clubhouse), date, time slot
HOA rule / resolution	`claim`	`cns://claim/type/governance/resolution`	title, description, vote threshold, status
HOA vote	`claim`	`cns://claim/type/governance/vote`	resolution, voter, choice, BBS+ proof
Common area / amenity	`resource`	`cns://resource/common-area`	name, type, capacity, booking rules, maintenance schedule
Access grant	`truth_edge`	person→unit→access	access level, valid from/to, key card ID
Land registry mirror	`integration_entity`	system: "land-registry", external_id	title number, last synced, checksum
ERPNext invoice mirror	`integration_entity`	system: "erpnext", external_id	invoice number, fiscal status
Access-control mirror	`integration_entity`	system: "access-control", external_id	card number, active status

3. Truth Edge Examples (Real Estate Relationship Graph)

text

truth_node:owner_O123  --owns-->  resource:unit_A-1001
truth_node:tenant_T456  --leases-->  resource:unit_A-1001
resource:unit_A-1001  --part_of-->  resource:building_A
resource:unit_A-1001  --charges_service-->  claim:service-charge_SC-2026-001
claim:sale_S-2026-001  --transfers_title_to-->  truth_node:owner_O123
claim:defect_D-77  --reported_in-->  resource:unit_A-1001
claim:defect_D-77  --assigned_to-->  truth_node:contractor_C9
claim:amenity-booking_B-5  --uses-->  resource:common-area-pool
claim:vote_V-3  --cast_on-->  claim:resolution_R-2

Each edge is created via fn::create_truth_edge (10-arg signature from s25_reactive_edge_protocol.surql) and is subject to vault scope / lease gates (fn::vault::check_scope_access, fn::vault::grant_lease).

4. Developer vs. HOA vs. Property Manager Architecture

For large developments, three distinct legal entities typically coexist:

Developer — sells units, manages construction, hands over to HOA
HOA (Homeowners Association) — owns common areas, collects service charges, enforces rules
Property Manager — day-to-day operations, maintenance, leasing on behalf of owners

Each is a scope with isolation boundaries. Cross-entity operations (service-charge collection, defect handover from developer to HOA, rule enforcement) use s184_record_federation:

cns_federation_policy — which CNS schemas may cross entity boundaries (e.g., cns://claim/type/real-estate/sale may federate developer→HOA; cns://claim/type/real-estate/lease may not)
record_federation_binding — binds a local record to an authorized peer scope
record_federation_event — immutable audit ledger of cross-entity actions
APF (s230) resolves effective permissions per user per entity scope

See Cross-Organization Federation & Federated PoCE Specification for the federated PoCE sequence.

5. PoCE Integration Points for Real Estate

Every critical development state transition starts a PoCE session (fn::lifecycle::start_poce_session):

Transition	PoCE trigger	Evidence recorded
Unit sale agreement	lifecycle event	buyer, price, payment schedule, signatures
Handover / snag closure	`record_poce_step`	inspector, defect list, photos, sign-off
Lease execution	`record_poce_step`	tenant, rent, deposit, lease term
Service-charge collection	`fn::poce::record_step`	unit, amount, payment reference, date
HOA resolution vote	`fn::poce::record_step`	voter, choice, BBS+ proof, timestamp
Maintenance work-order close	`record_poce_step`	contractor, parts, expert sign-off
Amenity booking confirmation	`fn::poce::finalize_session`	unit, amenity, slot, confirmation

See Core Subsystem → PoCE Bridge Architecture and Playbook Engine Architecture & Runtime Execution Model §3.

6. What We Do NOT Build (Honesty Limits)

Per AGENTS.md — Sovereign OS / Cosmic Circuit mandates and the Jijibora architecture:

No land-registry replacement. The land registry remains the legal system of title; Sovereign OS mirrors title references and tracks operational state.
No dynamic property-valuation engine unless expressible as solver-gateway capability + declarative lookups.
No synthetic "optimal" maintenance route, service-charge budget, or vendor selection. If the solver-gateway (:3070) is down, refuse with 502/503 (fail closed).
No fake metrics on dashboards (no 98% collection rate, no 42 units sold). UI renders live data or honest skeleton/empty states (mandate 12).
No filesystem lookups at runtime. All config lives in NATS JetStream KV (SOVEREIGN_LOOKUPS, SOVEREIGN_SCENARIOS, SOVEREIGN_TEMPLATES), seeded offline.