# Conceptual Health™ — Independent Validator Program

We publish the Master Equation, its source code, its constants, its
sub-signal catalog, its action map, and a corpus of 50 golden vectors
that lock every implementation to the same numbers.  Anyone — a
university, a regulator, a journalist, an insurer, a competitor — can
verify that a given Conceptual Health™ score was computed from the
documented spec.

This directory is the public contract.

---

## What an independent validator does

An independent validator runs three checks and publishes a signed
report:

1. **Reproducibility check** — the validator computes CH from a known
   axis vector and confirms the value matches what our API returns to
   ≤ 0.05.
2. **Golden-vector check** — the validator runs every entry in
   `tests/golden-vectors.json` through their implementation and
   confirms 100 % match.
3. **Spec-pin check** — the validator fetches `/api/v1/master-equation/spec`,
   confirms the `calculator_sha256` matches the source they audited,
   and records that fingerprint in their report.

A validator passing all three may publish their findings under the
shared **CH-Validator** mark.

---

## What we publish

| Surface | URL | Purpose |
|---|---|---|
| Canonical JS | `https://conceptualhealth.com/ui_kits/master-equation/calculator.js` | The implementation everyone reads from. |
| Canonical Python | `https://github.com/.../master-equation/calculator.py` | Byte-equivalent port. |
| Golden vectors | `https://github.com/.../master-equation/tests/golden-vectors.json` | 50 input/output pairs. |
| Sub-signal YAML | `https://github.com/.../master-equation/sub-signals.yaml` | What each axis is made of. |
| Action map YAML | `https://github.com/.../master-equation/action-axis-map.yaml` | What every user action does. |
| Spec endpoint | `POST /api/v1/master-equation/spec` | Live SHA-256 of the calculator. |
| Reproduce endpoint | `POST /api/v1/master-equation/compute` | Given axes, returns CH. |

---

## Running the reference validator

```bash
# Pull this repo, then:
python3 master-equation/validators/run_validator.py \
    --api https://clinical.conceptualhealth.com \
    --report ./my-validator-report.json
```

The runner:

1. Loads the local `tests/golden-vectors.json`.
2. Runs every vector through the **local** Python implementation
   (`calculator.py`).
3. Runs every vector through the **remote** API
   (`POST /api/v1/master-equation/compute`).
4. Confirms all three numbers (local-py, JS-via-page-source, remote-API)
   agree to ≤ 0.05.
5. Pulls `/spec`, hashes the audited source files locally, and prints
   a signed JSON report.

A passing run produces output like:

```
Reproducibility    PASS   50/50 vectors, max |Δ| = 0.0000
Spec pin           PASS   calculator_sha256 matches local source
Golden vectors     PASS   50/50
Overall            PASS   eligible for CH-Validator mark
```

---

## Audit-report contract

A published validator report MUST be a JSON document conforming to
`audit-report.schema.json` in this directory, with these required top-
level fields:

| Field | Type | Description |
|---|---|---|
| `validator_id` | string | DNS-style id of the validating org. |
| `validated_at_iso` | string | ISO-8601 timestamp. |
| `api_root` | string | URL that was queried. |
| `calculator_sha256` | hex | SHA-256 of `calculator.py` audited. |
| `golden_vectors_sha256` | hex | SHA-256 of `golden-vectors.json`. |
| `vectors_total` | int | Number of golden vectors run. |
| `vectors_passed` | int | Number that matched within tolerance. |
| `max_abs_diff` | number | Largest |actual − expected| observed. |
| `tolerance` | number | Tolerance used (recommended: 0.05). |
| `result` | "PASS" \| "FAIL" | Aggregate verdict. |
| `signature` | string | Detached signature over the canonical JSON. |
| `signer_pubkey` | string | Public key (PEM or ed25519 hex). |

We publish a global registry of validator reports at
`https://hc.exchange/trust/validators` — submit yours via PR or via the
`POST /api/v1/master-equation/validators` endpoint (coming Phase 6.2).

---

## Bug-bounty

If you find a vector where the documented formula and any of our live
surfaces disagree, we pay a bounty per disagreement found.  Email
**security@conceptualhealth.com** with a reproducer that runs against
our public spec endpoint.  See `BOUNTY.md`.

---

## License & patent

The formula and methodology are covered by U.S. Provisional Patent
63/921,717 (filed 2025).  Independent reproduction for the purpose of
verification is expressly permitted; productizing your own competing
CH score from this spec is not.