docs: sync oracle claim boundaries

2026-07-19 08:37:24 +08:00
parent 05948cde7f
commit 5298b49a89
8 changed files with 1792 additions and 0 deletions
@@ -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.
@@ -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.
@@ -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.