Merge remote-tracking branch 'origin/main' into codex/optimize-runtime-ux

# Conflicts:
#	frontend/src/mastra/index.ts

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.

docs/research/day_level_holdout_labeling_guide_zh.md

@@ -0,0 +1,76 @@
+# 日级应期 holdout 人工标签指南
+
+目标：给研究仓提供真实、独立、可复验的正/负样本。你不需要会编程，只需要提供来源清楚的事实材料。
+
+## 需要收集什么
+
+每条标签只回答一个问题：
+
+某人在某个日期区间，某类事件是否发生？
+
+可用标签：
+
+- `target_event`：事件发生了。
+- `no_target_event`：有公开资料支持该区间没有发生这个目标事件。
+
+## 优先领域
+
+1. 事业：任命、创办公司、上市、获奖、重大作品发布。
+2. 婚恋：结婚、离婚、订婚、公开伴侣关系变化。
+3. 财富：上市、重大融资、破产、重大资产事件。
+
+暂不优先健康/死亡，噪音和伦理风险高。
+
+## 合格来源
+
+优先：
+
+- 官方 biography / timeline
+- Britannica / Nobel / company official timeline
+- 出版传记中可核对页码或章节的时间线
+- IMDb / MusicBrainz / company history 等结构化公开资料
+
+不合格：
+
+- “没搜到新闻所以没发生”
+- ChatGPT 生成内容
+- 无来源论坛故事
+- 已被本项目观察过的旧控制日期
+- 模糊说法：“那一年很平静”
+
+## 最小可用规模
+
+pilot 阶段：
+
+- 3 个公开人物
+- 每人 1 个领域
+- 每人 1 个正样本窗口
+- 每人 2 个负样本窗口
+
+正式升级门槛：
+
+- 至少 20 个独立案例
+- 至少 80 个独立负样本区间
+- 标签冻结后才允许评分
+
+## 填写方式
+
+生成空模板：
+
+```bash
+python3 scripts/day_level_holdout_template.py --output /tmp/holdout_annotation_template.json
+```
+
+把公开来源、日期区间、事件说明填进去，再交给 intake：
+
+```bash
+python3 scripts/day_level_negative_holdout_intake.py references/real_case_calibration/day_level_holdout_v3_preregistration.json --row-json '{"case_id":"..."}'
+```
+
+## 结论边界
+
+没有真实独立负样本前：
+
+- 可以输出候选日期排序；
+- 可以说明触发信号；
+- 不能说“精确日期预测已验证”。

docs/research/real_case_timing_optimization_audit_2026_07_19.md

@@ -0,0 +1,47 @@
+# Real-case timing optimization audit — 2026-07-19
+
+## Current verified layer
+
+Positive-event replay is healthy:
+
+| Manifest | Cases | Ready | Boundary |
+|---|---:|---:|---|
+| `references/real_case_calibration/replay_manifest.json` | 10 | 10 | known positive events only |
+| `references/real_case_calibration/replay_manifest_holdout_v2.json` | 10 | 10 | blind positive holdout; not specificity proof |
+| `references/real_case_calibration/replay_manifest_probe3_v2.json` | 3 | 3 | probe batch only |
+
+This verifies technical recall around known dated events. It does not verify day/month predictive specificity.
+
+## Current blocked layer
+
+Day-level negative holdout remains empty:
+
+- `references/real_case_calibration/day_level_holdout_v3_preregistration.json`
+- `annotation_count = 0`
+- `negative_count = 0`
+- `positive_count = 0`
+- `production_tuning_allowed = false`
+- `status = awaiting_independent_labels`
+
+Existing 40 control dates remain diagnostic only because they were already observed before preregistration and are not independent human-reviewed labels.
+
+Pilot source queue exists at `references/real_case_calibration/day_level_holdout_v3_pilot_source_queue_2026_07_19.json`.
+
+Boundary: the queue contains public-source candidates for Steve Jobs, Barack Obama, and Albert Einstein. It is not a holdout manifest and must not be used for timing evaluation until independent adjudication converts rows into frozen annotations.
+
+## Optimization needed
+
+1. Collect independent human-labeled non-event intervals for the same subjects/domains.
+2. Freeze labels before scoring.
+3. Run candidate day/month ranking over positive and negative windows together.
+4. Promote timing claims only if positive windows rank above negative windows under frozen rules.
+
+Until then, precise day/month output must stay:
+
+- `timing_precision = candidate_day_window`
+- `claim_status = exploratory_unvalidated`
+- `production_tuning_allowed = false`
+
+Allowed UX: ranked candidate windows w/ evidence and confidence caps.
+
+Forbidden UX: packaging candidate dates as verified event promises.

docs/research/shadbala_av_component_provenance_report_2026_07_19.md

@@ -0,0 +1,48 @@
+# Shadbala / AV component provenance report — 2026-07-19
+
+Source registry: `references/oracle/shadbala_av_component_provenance_registry_2026_07_19.json`
+
+Status: `classified_unresolved`
+
+Truth policy: `method_variant_not_majority_vote`
+
+Production tuning: `false`
+
+## Component families
+
+| Category | Rows | Component family | Allowed claim |
+|---|---:|---|---|
+| `shadbala_formula_variant` | 35 | Shadbala six-force components | `component_method_variant` |
+| `derived_total_from_component_variants` | 7 | Shadbala total | `derived_total_blocked_until_components_close` |
+| `ashtakavarga_table_or_contributor_variant` | 8 | Ashtakavarga tables | `table_variant` |
+| `endpoint_or_varga_semantics` | 10 | Varga endpoint semantics | `current_target_observation_only` |
+
+## Unit / source obligations
+
+- Sthana, Dig, Kala, Chesta, Naisargika, and Drik Bala each require formula source, unit, cap/floor, and worked example.
+- Total Rupa/Virupa cannot be arbitrated until component units close.
+- Ashtakavarga BAV/SAV requires contributor table, shodhana state, Lagna inclusion, and row/column schema.
+- VedAstro varga endpoint rows require explicit endpoint/method semantics before truth arbitration.
+
+## Current claim boundary
+
+Allowed:
+
+- current target observations;
+- named method variants;
+- component-level unresolved status;
+- user-safe confidence caps.
+
+Forbidden:
+
+- global Shadbala/AV truth;
+- production tuning;
+- majority-vote truth;
+- copying raw research debt into runtime.
+
+## Next source-evidence queue
+
+1. Map 35 Shadbala component rows to `sthana/dig/kala/chesta/naisargika/drik`.
+2. Attach VP Jain / Xalen / jyotishganit / PyJHora observation source per component.
+3. Mark each component as `source_explicit`, `method_variant`, or `insufficient_evidence`.
+4. Recompute totals only after component status closes.

docs/research/shadbala_av_normative_benchmark_plan_2026_07_19.md

@@ -0,0 +1,75 @@
+# Shadbala / Ashtakavarga normative benchmark plan — 2026-07-19
+
+## Current status
+
+Current Shadbala target set is closed, but global tuning is not allowed.
+
+- current target set: `external_verified`
+- `can_claim_shadbala_absolute_closure = true`
+- `production_tuning_allowed = false`
+- three-engine mismatch report: 60 mismatches, 60 classified, 0 unclassified
+- Shadbala formula/component variants: 35 component rows + 7 derived-total rows
+- Ashtakavarga table/contributor variants: 8 rows
+
+## What this means
+
+The research repo can claim closure for the current curated Shadbala target package. It must not claim universal Shadbala or AV truth across all schools/software.
+
+## Required benchmark ladder
+
+1. Source provenance
+   - VP Jain: page/edition/source hash or explicit retrieval gap.
+   - Xalen: source commit, package hash, executable hash if available, method list.
+   - PyJHora/JHora: isolated AGPL oracle only; no copied implementation.
+   - jyotishganit: permissive observation adapter where license permits.
+
+2. Component normalization
+   - `sthana`
+   - `dig`
+   - `kala`
+   - `chesta`
+   - `naisargika`
+   - `drik`
+   - `total_rupa`
+
+3. Unit contract
+   - Virupa vs Rupa must be explicit.
+   - Totals cannot be arbitrated before components.
+   - Component caps/floors must be named.
+
+4. Formula variant registry
+   - legitimate school variants become `method_variant`;
+   - unresolved variants stay `classified_unresolved`;
+   - no majority vote.
+
+5. Independent ephemeris mode
+   - same raw input mode isolates formula layer;
+   - independent ephemeris mode checks longitude/ayanamsa layer;
+   - both must be reported separately.
+
+## Commercial sync rule
+
+Commercial may receive:
+
+- readiness status;
+- user-safe confidence cap;
+- claim boundary;
+- supported component list.
+
+Commercial must not receive:
+
+- unresolved raw research debt;
+- forced absolute Virupa truth;
+- AGPL implementation code;
+- production tuning flag while `production_tuning_allowed = false`.
+
+## Next implementation task
+
+Create a component provenance registry that maps each Shadbala/AV mismatch category to:
+
+- source artifact;
+- component;
+- unit;
+- likely reason;
+- allowed claim;
+- next evidence required.

docs/research/three_engine_mismatch_arbitration_2026_07_19.md

@@ -0,0 +1,27 @@
+# Three-engine mismatch arbitration
+
+manifest: `references/oracle/three_engine_parity_replay_manifest.json`
+status: `classified_unresolved`
+truth_policy: `no_majority_vote`
+commercial_sync: `status_and_claim_boundary_only`
+mismatch_count: `60`
+classified_count: `60`
+unclassified_count: `0`
+
+Do not copy raw research debt into commercial runtime. Commercial receives readiness, claim boundary, and user-safe status only.
+
+## Category counts
+
+| category | count |
+|---|---:|
+| `ashtakavarga_table_or_contributor_variant` | 8 |
+| `derived_total_from_component_variants` | 7 |
+| `endpoint_or_varga_semantics` | 10 |
+| `shadbala_formula_variant` | 35 |
+
+## Closure requirements
+
+- `endpoint_or_varga_semantics`: Confirm VedAstro endpoint returns the requested varga under the same ayanamsa/node/method contract.
+- `ashtakavarga_table_or_contributor_variant`: Compare contributor tables, Lagna inclusion, shodhana state, and BAV/SAV row semantics.
+- `derived_total_from_component_variants`: Do not arbitrate totals until all six component variants and Virupa/Rupa units are aligned.
+- `shadbala_formula_variant`: Compare component formula, units, local solar context, aspect model, and Chesta lineage before totals.

docs/research/vedastro_identity_closure_plan_2026_07_19.md

@@ -0,0 +1,61 @@
+# VedAstro identity closure plan — 2026-07-19
+
+## Current status
+
+VedAstro hosted API remains observation-only.
+
+Reason: hosted output can be replayed, but build identity, method semantics, and deployment version are not archived. Stable mismatch replay proves the conflict is not random transport noise; it does not prove which side is true.
+
+## Acceptable closure paths
+
+### Path A — hosted metadata
+
+Required from upstream:
+
+- hosted build version;
+- source commit or release tag;
+- method semantic contract for each endpoint used;
+- ayanamsa/node/timezone interpretation;
+- deployment timestamp or immutable build ID.
+
+### Path B — pinned self-hosted version
+
+Required archive:
+
+- source commit;
+- NuGet package hash;
+- DLL SHA-256;
+- assembly version;
+- public method inventory;
+- container image digest or reproducible local runner hash.
+
+`scripts/vedastro_identity_archive.py` now records the NuGet identity and a `required_self_host_evidence` checklist. Missing fields keep truth upgrade blocked.
+
+## Claim boundary
+
+Allowed:
+
+- use VedAstro as external observation;
+- report stable conflicts;
+- compare raw response hashes and normalized fields;
+- use pinned self-hosted evidence if all required identity fields are present.
+
+Forbidden:
+
+- tune production predictions from hosted output with unknown build identity;
+- call hosted mismatch arbitration a global truth decision;
+- silently prefer VedAstro or local output by majority vote.
+
+## Commercial sync rule
+
+Commercial may receive:
+
+- `VedAstro: observation_only`;
+- endpoint status;
+- claim boundary text.
+
+Commercial must not receive:
+
+- raw hosted credentials;
+- hosted output as truth;
+- production tuning permission while `truth_upgrade_gate` is blocked.