From 51decd5003df1a33f49e71d6469e5a0cd382e7dc Mon Sep 17 00:00:00 2001
From: 732642856 <732642856@qq.com>
Date: Sun, 19 Jul 2026 06:56:59 +0800
Subject: [PATCH] docs: align cross-project sync boundary

---
 ...ercial_web_backport_boundary_2026_07_19.md | 42 +++++++++++++++++++
 .../sync_policy.v1.json                       |  8 ++++
 tests/test_cross_project_sync_status.py       |  8 ++++
 3 files changed, 58 insertions(+)
 create mode 100644 docs/research/commercial_web_backport_boundary_2026_07_19.md

diff --git a/docs/research/commercial_web_backport_boundary_2026_07_19.md b/docs/research/commercial_web_backport_boundary_2026_07_19.md
new file mode 100644
index 00000000..6da7234e
--- /dev/null
+++ b/docs/research/commercial_web_backport_boundary_2026_07_19.md
@@ -0,0 +1,42 @@
+# Research-to-commercial capability boundary — 2026-07-19
+
+Purpose: keep the asset flow honest. Research repo is the personal core asset and source of astrological capability. Commercial repo productizes stable research contracts for users.
+
+## Research capabilities that commercial may productize
+
+| Capability | Research web status | Evidence |
+|---|---|---|
+| Daily starlanguage entry | local research UX exists | `jyotish-app/index.html#daily-guidance-card`; guarded by `tests/test_frontend_productization.py` |
+| Birth-time rectification entry | local research UX exists | `jyotish-app/index.html#entry-rectification`; guarded by `tests/test_frontend_productization.py` |
+| Local chart library | local research UX exists | `jyotish-app/index.html#saved-chart-panel`; `jyotish-app/main.js#saveCurrentChartToLibrary`; guarded by `tests/test_frontend_productization.py` |
+| Display-name field | local research profile exists | `jyotish-app/index.html#profile-display-name`; `PROFILE_DISPLAY_NAME_KEY`; guarded by `tests/test_frontend_productization.py` |
+| Chat history actions | local research sessions exist | rename/share/archive/delete in `jyotish-app/main.js`; guarded by `tests/test_frontend_productization.py` |
+
+## Not equivalent by design
+
+| Commercial capability | Research boundary |
+|---|---|
+| Supabase `/api/account` profile save | Research web is static/local-first; it must not claim cloud profile persistence. |
+| `profiles` service-role upsert grants | Commercial database migration only; research repo may document it but should not require Supabase for local research web. |
+| Cookie-authenticated account route | Commercial runtime only; research web stores display name locally. |
+| Credits, billing, subscriptions | Commercial-only business layer; never part of research repo capability. |
+
+## Claim rule
+
+Research web may say:
+- “research capability has a local UX/reference implementation”
+- “profile display name and sessions persist in localStorage”
+- “stable research contracts can be synced outward to commercial”
+
+Research web must not say:
+- “cloud profile persistence is equivalent to commercial”
+- “Supabase account/profile upsert is available in the static research site”
+- “research web and commercial web are 100% identical”
+- “commercial credits, billing, subscriptions, or account entitlements are research capabilities”
+
+## Current optimization priority
+
+1. Improve real research capability first; sync stable contracts outward to commercial.
+2. Keep timing claims exploratory until independent negative holdout labels exist.
+3. Keep external oracle mismatch reports as attribution, not majority-vote truth.
+4. Keep commercial account/payment/runtime details out of research repo except as deployment contract notes.
diff --git a/references/cross_project_contract/sync_policy.v1.json b/references/cross_project_contract/sync_policy.v1.json
index 0f5f468b..08dc1d96 100644
--- a/references/cross_project_contract/sync_policy.v1.json
+++ b/references/cross_project_contract/sync_policy.v1.json
@@ -24,6 +24,14 @@
       ]
     }
   },
+  "research_repo_exclusions": [
+    "commercial_credits",
+    "billing",
+    "subscriptions",
+    "payment",
+    "account_entitlements",
+    "service_role_runtime"
+  ],
   "shared_files": [
     "references/cross_project_contract/fixture_manifest.v1.json",
     "references/cross_project_contract/sync_ledger.json",
diff --git a/tests/test_cross_project_sync_status.py b/tests/test_cross_project_sync_status.py
index aabfed3f..6da125a6 100644
--- a/tests/test_cross_project_sync_status.py
+++ b/tests/test_cross_project_sync_status.py
@@ -36,6 +36,14 @@ def test_sync_policy_encodes_research_first_commercial_mature_rule() -> None:
     assert policy["sync_model"] == "research_validates_commercial_receives_mature"
     assert policy["directional_gates"]["research_to_commercial"]["source_required"] == "validated_in_research"
     assert policy["directional_gates"]["research_to_commercial"]["target_required"] == "commercial_safe"
+    assert set(policy["research_repo_exclusions"]) >= {
+        "commercial_credits",
+        "billing",
+        "subscriptions",
+        "payment",
+        "account_entitlements",
+        "service_role_runtime",
+    }
     assert "references/cross_project_contract/fixture_manifest.v1.json" in policy["shared_files"]