# Hong Kong on Layout Analysis — layouts from the unit list, evidence from the Land Registry

> 📍 Part of the project catalogue doc set — the map and routing table is
> [start-here.md](/docs/modules_handbook/shared/project-catalogue/start-here.md). The table
> itself is documented in
> [main/analyze-property/readMe.md](/docs/modules_handbook/main/analyze-property/readMe.md)
> (*Layout Analysis — one row per unit*); the HK project page in
> [hk-data-requirements.md](/docs/hk-data-requirements.md); the HK field map in
> [hk-catalogue-mapping.md](/docs/hk-catalogue-mapping.md).

Built 2026-10-12. The owner's ask: *"for malaysia and dubai we show the layout and show general
price, so one project maybe got 3-4 layouts, then each layout got average price … for hk we direct
show everything. how we can offer the same layout analysis summary for HK market?"* — and, on the
follow-up, *"we need same comparison engine, then only a buyer can make judgment across 3 markets."*

So nothing in the engine is Hong Kong specific. Two things were missing, and both are data shape:

## 1. A Hong Kong launch is a handful of layouts, not a list of units

House730's `unitsData` is the developer's price list: every unit with its block, floor, flat letter,
**bedroom count (`rooms`)**, **saleable area (`sfa`)**, list price, sale status and drawing. The
adapter used to make one `catalog_floor_plans` row per distinct (flat letter, size) — no bedrooms,
29 rows named A–H on Blue Coast — which the table could not use.

[`HkUnitLayouts`](/app/Services/Property/Ingestion/Adapters/HkUnitLayouts.php) now groups the units
and [`House730NewProjAdapter::plansFromUnitsData`](/app/Services/Property/Ingestion/Adapters/House730NewProjAdapter.php)
emits one plan per group:

| Rule | What it does |
|---|---|
| group by `rooms` | `0` is a studio, a real value; a unit without `rooms` lands in a "Layout" group |
| split a bedroom group by size | sorted by saleable area; a new band starts when the next size is > 12 % above the previous one (`SIZE_STEP`) or > 25 % above the band's smallest (`SIZE_SPAN`) — Blue Coast's 3-beds at 728–813 sq ft are one layout, its 938–1,006 sq ft 3-beds another |
| `sqft` | the band's **median** saleable area |
| `price` | the **median list price** of the units that carry one — the floor premium averages out ("the general price"); unreleased units have none and count only in `units_count` |
| `asking_psf` | median of each priced unit's own price ÷ area |
| `units_count` | how many units the layout stands for |
| `name` | `2-bedroom · 345–400 sq ft` (bedroom label, then the band's size range) |
| `source_key` | `layout:{rooms}:{min}-{max}` — the band's own bounds. An ordinal key collided on re-sync (a shifted band took the identity its neighbour's plan still owned and the launch failed to ingest); with bounds, a changed band is a new plan and the old one is pruned |
| feed errors | a priced unit more than 3× above or below the **list's own median PSF** is dropped (`PSF_SPREAD`): the feed carried a 1-bed at 20 sq ft for HK$ 9.2M and a 3-bed at 3,004 sq ft for HK$ 5.7M beside 300-sq-ft units at the same price. Checked against the launch's own list (its median PSF over the units inside the feed's own sizeMin–sizeMax, when at least two are), so an all-house estate at HK$ 100,000 psf keeps every unit. The size range itself is never a gate: 594 genuine units sit outside it. Outside HK$ 3,000–300,000 psf a unit is dropped whatever its list says (`PSF_FLOOR` / `PSF_CEILING`; the HK record is ~HK$ 140,000) |
| drawing | the band's commonest `planImg`, plan-scoped as before; the raw per-unit boards are untouched |

Measured over the 299 published launches: a median of **6 layouts per project** (3 by bedrooms
alone), 174 of 299 at 3–8, 1,636 of 1,863 layouts with a price. Blue Coast → 6 layouts
(2-bed 452, 538, 750 sq ft; 3-bed 749 and 968; 4-bed 1,263), 柏蔚森 I → 4.

**What does not change.** The HK project page's 座 → 樓層 → 單位 stack, its only-available toggle,
cheapest-unit verdict and 单位户型图 gallery all read the raw payload (`BuildHkProjectDetail`),
never the plan rows. Its 實用面積 range now reads the feed's own `sizeMin`/`sizeMax` (else the
per-unit SFA) instead of the plans' min/max, which would be band medians. Publication completeness
needs ≥ 1 plan and still has it.

**Rolling it out** is a House730 re-sync on the Hub: `catalogue:sync house730 --full`. Each launch's
old per-unit plans lose their contribution and are pruned (`pruneUncontributedFloorPlans`); their
plan-scoped media re-link to the new plans by (name, sqft).

## 2. The engine's ring for Hong Kong: Land Registry sources on every estate

The engine prices a layout against the sales and rents of buildings within 2 km, read from the
market's **provider sources** (`MarketProfile::marketProvider()` →
`CatalogProjectSource::nearbyProviderCoordinates()`): EdgeProp in Malaysia, Bayut's DLD sales and
Ejari rents in the UAE. Hong Kong already held the ledger — `market_transactions`, the Land Registry
copy (2.2 M sales, 145 k rental agreements since 2021, on the catalogue connection) — but as rows,
not sources.

[`HkLandRegistryAdapter`](/app/Services/Property/Ingestion/Adapters/HkLandRegistryAdapter.php)
(`catalogue:sync landregistry`, provider `landregistry`, **attach-only, no canonical facts** — the
realtycheck pattern) writes one source per estate:

| Field on the source | From |
|---|---|
| `latitude` / `longitude` / `project_name` | the estate's own catalogue row |
| `property_type` | `Condominium` (every HK estate is strata flats; the type gate refuses only land and bungalows) |
| `asking_sale_listings` | the estate's newest ≤ 150 recorded sales in the 24 months before the ledger's as-of date — `{date, bedrooms, sqft (net), price_rm, psf_rm (net), floor, market}`, Bayut's row shape |
| `asking_rental_listings` | its newest ≤ 150 rental agreements in the same window — `price_rm` is the **monthly** rent |
| `total_transactions`, `psf_median`, `psf_25/75`, `price_median` | the same 24-month window |
| `quarterly_sale_psf` | 12 quarters of median net PSF, oldest first — the engine's growth reading needs 6 |

- **Matching is by registered name**, exactly as Property Explorer's HK list matches
  (`HkRecordedSales::keyFor` / `keysOf`: big-estate name, own name, or both joined).
- **One source per estate key.** 925 HK catalogue names are duplicated (a Centanet estate and a
  House730 launch of the same tower); the source goes on the **subsale** row when there is one, else
  the lowest id — two sources with the same sales would be counted twice in the weighted PSF.
- An estate with fewer than 3 sales **and** fewer than 3 rents in the window gets no source.
- The window is measured from the ledger's **own as-of date** (`HkMarketSnapshot::date()`, the last
  import — 2026-08-14, data to 2026-07-11), not from today: the copy is loaded in one go and nothing
  refreshes it yet, so a window from today would silently empty over time. The provider's staleness
  threshold is a year for the same reason.
- Sizes and PSF are on **net (saleable) area** on both sides — House730 sizes a launch's units on
  SFA, the registry's `net_psf` is on net area — so the layout's asking PSF and the ring compare like
  for like.

The `HK` block in [`config/markets.php`](/config/markets.php) names the provider and carries the
currency (HK$), the rent sanity band (HK$ 3,000–400,000 a month), the PSF thresholds, developer and
mall lists. The loan behind the cash-flow column stays the table's own — 100 % at 4 % over 35 years
for every market (`LayoutAnalysisProjector`) — **by the owner's decision**: one yardstick, so a buyer
reads the same columns across the three tabs. Under it most HK layouts show a negative cash flow
(HK yields run 2.5–3.5 %), which is the market, not a bug; the percentage columns (discount, yield)
compare across currencies, the cash flow within one.

## The Hub runbook

Every HK project is a **master** row, so all three steps run on the catalogue admin domain
(`CatalogueFederationService::consoleMayWriteMaster()`), like Malaysia's projection. On a site
(wk) each is a dry run at best — see *Proving it on wk* below.

```bash
php artisan migrate --path=database/migrations/catalogue --database=catalogue   # seeds the landregistry provider
php artisan migrate --path=database/migrations/catalogue                        # …and the local copy of its id
php artisan catalogue:sync house730 --full          # launches → layouts (step 1)
php artisan catalogue:sync landregistry --full      # estates → evidence sources (step 2)
php artisan layouts:project --country=HK --run      # engine + table rows; --fresh to recompute
```

The HK tab on `/analyze-property/layout-analysis?country=hk` appears by itself once `layout_analyses`
holds HK rows (`BuildLayoutTable::markets()` lists any market with rows; HKD → `PRICE_BANDS_HKD`,
HK$ from the country row's `currency_symbol`). Re-run `catalogue:sync landregistry --full` after
every ledger refresh; `layouts:project --country=HK --run --fresh` after that to re-price.

## Serving it on wk before the Hub has run (read-only master)

wk cannot write the master, but its own database carries a frozen mirror of every HK row (same ids
and uuids, no publication dates) and the same ledger copy. The owner wanted the tab on wk (2026-10-12,
"i dun see got hk"), so a site may now serve a market **the master has not projected at all** from
its own `layout_analyses`, computed here against that mirror with the current engine
(`BuildLayoutTable::sourceFor()`, second kind of own-side row). The moment the Hub projects HK onto the
master, the master branch wins and the site rows are ignored. The frozen copy's 461 stale Malaysian
rows cannot surface this way: Malaysia is projected on the master, which is read first.

The run is [`scripts/hk-layouts-on-mirror.php`](/scripts/hk-layouts-on-mirror.php), through tinker,
all inside one process (the `catalogue` connection redirected to the site database — the UAE v2
recipe — and the edit domain widened so `layouts:project` treats the mirror as writable):

```bash
php artisan tinker --execute="require 'scripts/hk-layouts-on-mirror.php';"          # layouts → evidence → project
HK_STEP=project HK_FRESH=1 php artisan tinker --execute="require 'scripts/hk-layouts-on-mirror.php';"   # re-price after a ledger refresh
```

Three things it does differently from the Hub, each for a reason in its header: the launches' House730
records are re-ingested **limited to the 319 published launches** (a full `catalogue:sync house730`
under the redirect would mint own-origin rows for the ~130 feed rows the mirror lacks); the projection
runs **per slug** (the mirror has no publication dates, so the command's listed-launch scope finds
nothing); and everything lands on the site connection. The landregistry provider row must exist
locally first: `php artisan migrate --path=database/migrations/catalogue` (done on wk 2026-10-12, id 14).

What a member sees is the same engine on the same data the Hub will use. Two small differences until
the Hub run: the row's floor-plan uuid is the mirror's (a shortlist saved now points at a plan the
master will mint afresh), and the HK project page it links to still shows the master's old per-unit
plans in its size range (its unit stack is raw-fed and unaffected).

## Related files

- `app/Services/Property/Ingestion/Adapters/HkUnitLayouts.php`, `House730NewProjAdapter.php`
- `app/Services/Property/Ingestion/Adapters/HkLandRegistryAdapter.php`
- `database/migrations/catalogue/2026_10_12_120000_seed_landregistry_provider.php`
- `config/project_catalogue.php` (`landregistry` registry entry), `config/markets.php` (`HK`)
- `app/Actions/BuildLayoutTable.php` (currency symbol), `app/Actions/BuildNewProjectListing.php`
  (`PRICE_BANDS_HKD`), `resources/js/Pages/Main/Site/newProjects.js`
- `app/Actions/BuildHkProjectDetail.php` (`house730SizeRange`)
- Tests: `tests/Feature/Console/HongKongAdaptersTest.php` (layouts),
  `tests/Feature/Console/HkLandRegistryAdapterTest.php`, `tests/Unit/Analysis/AnalysisEngineServiceTest.php`
  (a HK launch through the ring), `tests/Unit/Common/MarketProfileTest.php`,
  `tests/Feature/Main/Portal/Analyze/LayoutAnalysisCountryTest.php` (the HK tab)
