From bab91ef6b999881baa74bbe99ebbb695742908f5 Mon Sep 17 00:00:00 2001
From: wpdev <webdemo2080@gmail.com>
Date: Sun, 27 Sep 2026 09:15:20 +0800
Subject: [PATCH] docs(2meet-data-optimizer-hivepress-addon): document
 registered keys HivePress never writes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- docs/REGISTERED-KEYS.md lists the six registered keys that are aliases of core columns in the HivePress models (listing hp_vendor → post_parent, hp_status → post_status; request hp_status, hp_user → post_author; vendor hp_user; review hp_rating → comment_karma), with the dev36 evidence (0 meta rows each) and why the schema stays (plan D03). README links it.
- PR: PR-082
---
 README.md               |  2 ++
 docs/REGISTERED-KEYS.md | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 docs/REGISTERED-KEYS.md

diff --git a/README.md b/README.md
index 0cce256..6b31bdd 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,8 @@ reviews / messages / memberships / requests / listing-meta
 
 ---
 
+Registered keys HivePress keeps in core columns instead of meta (`hp_vendor`, `hp_status`, …): see [docs/REGISTERED-KEYS.md](docs/REGISTERED-KEYS.md).
+
 ## Requirements
 
 - WordPress ≥ 6.0
diff --git a/docs/REGISTERED-KEYS.md b/docs/REGISTERED-KEYS.md
new file mode 100644
index 0000000..c02c94c
--- /dev/null
+++ b/docs/REGISTERED-KEYS.md
@@ -0,0 +1,38 @@
+# Registered keys HivePress never writes
+
+Some keys the AddOn registers in its flat groups are **aliases of core columns** in the
+HivePress models: HivePress reads and writes the column, never a meta row. Their flat
+columns therefore stay `NULL`, and a meta query on them finds nothing — natively and
+routed alike.
+
+| Entity / group | Key | HivePress model field | Stored in |
+|---|---|---|---|
+| post / `hp_listing_core` | `hp_vendor` | Listing `vendor` | `wp_posts.post_parent` |
+| post / `hp_listing_core` | `hp_status` | Listing `status` | `wp_posts.post_status` |
+| post / `hp_request_core` | `hp_status` | Request `status` | `wp_posts.post_status` |
+| post / `hp_request_core` | `hp_user` | Request `user` | `wp_posts.post_author` |
+| post / `hp_vendor_core` | `hp_user` | Vendor `user` | `wp_posts.post_author` |
+| comment / `hp_review` | `hp_rating` | Review `rating` (hivepress-reviews) | `wp_comments.comment_karma` |
+
+Sources: `'_alias' => …` in `hivepress/includes/models/class-listing.php`,
+`class-vendor.php`, `hivepress-requests/includes/models/class-request.php` and
+`hivepress-reviews/includes/models/class-review.php`.
+
+## Checked on dev36 (2026-09-27, 101,175 listings)
+
+- Native meta rows: `hp_vendor` 0, `hp_status` 0, `hp_user` 0, comment `hp_rating` 0.
+- Instead: 101,175 / 101,175 listings have `post_parent > 0`; listing statuses are
+  `publish` 91,804 / `draft` 9,371; 5,244 of 5,324 `hp_review` comments carry
+  `comment_karma`.
+
+## What this means
+
+- Filters and sorts HivePress builds on these fields use the core columns, never
+  `meta_query`, so the router has nothing to route for them.
+- Drift checks report nothing for them: native and flat are both empty.
+- **No schema change** (plan decision D03, 2.2): the columns cost only NULLs, and
+  dropping them would need a flat-table migration on every site.
+
+Not in this list: `hp_expired_time` and `hp_featured_time` are real meta fields of the
+Listing model (no alias); they are empty on dev36 only because its seeded listings
+never expire or get featured.