> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heretic.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# How Heretic measures

> Follow the browser-to-edge request sequence, the six evidence families, settlement, identity, concealment, and sensor reporting.

Heretic joins connection evidence observed by the edge with values returned by browser code. It then applies a versioned rule catalogue to that session.

Browser declarations are claims. They can provide one side of a contradiction, but they are not ground truth. The rules use explicit constraints and cross-checks rather than treating a population corpus as truth for one session.

## Collection sequence

The collector performs this sequence against a Heretic edge:

1. Resolve a POP and its paired TCP and QUIC origins.
2. Send `GET /n` to `tcp.<pop>.probe.heretic.tech`. This origin never advertises HTTP/3, so repeat visits still expose the TCP handshake.
3. Send two nonce-bearing health requests to `quic.<pop>.probe.heretic.tech`. The first response supplies Alt-Svc when the origin is fresh. The next request can join over HTTP/3.
4. Run timed probes, optional fixed rendering, and declared-surface collection.
5. Send the payload to `/c` or `/z` on the TCP origin.

Default requests use `credentials: 'omit'`.

The browser must connect directly to the measurement edge. A CDN, reverse proxy, or load balancer in front of that endpoint replaces the browser-facing TCP and TLS connection with its own. The edge would measure the intermediary. You can still serve the JavaScript file through your normal asset path.

## Evidence inputs

The edge can join:

* TCP and IP handshake properties
* TLS ClientHello construction
* HTTP/2 framing
* UDP, QUIC, and HTTP/3 observations
* round-trip timing
* browser work outputs such as compute, GPU, parallel, frame, canvas, and audio measurements
* browser declarations such as user agent, platform, logical cores, display, timezone, WebGL, and the optional broader surface

What joined varies by session. Family coverage records which inputs the current rules could use.

## Evidence families

Every full assessment contains one report for each family.

| Family                   | Evidence considered                                                             |
| ------------------------ | ------------------------------------------------------------------------------- |
| `network-geometry`       | Edge coordinates, TCP handshake RTT, and the client's timezone claim            |
| `transport-stack`        | TCP and IP properties observed by the packet sensor                             |
| `transport-reachability` | The advertised HTTP/3 path and observed UDP or QUIC attempt                     |
| `tls-construction`       | TLS ClientHello construction and supported cross-transport comparisons          |
| `http-construction`      | HTTP framing, headers, browser declarations, and collector submission structure |
| `compute`                | Timed work and hardware-related measurements returned by the collector          |

The families are distinct groups in the ruling algebra. Heretic does not claim that they are statistically independent.

A family report contains:

```json theme={null}
{
  "family": "transport-stack",
  "status": "contradicted",
  "coverage": { "state": "measured" },
  "highest_tier": "composite",
  "signals": ["stack.os-contradiction"]
}
```

The tenant API projects the report without its internal `signals` list. The top-level projected findings still include each finding's family.

## Separate report axes

The full assessment also contains identity, concealment, and sensor reports. They do not add evidence-family weight.

### Identity

Identity version `2` derives up to two IDs from normalized components:

* `machine` requires logical cores, display, and timezone. Platform participates when present.
* `instance` requires at least one canvas, fixed WebGL raster, or audio anchor.

For a session with an accepted public site key, the trimmed key participates in the ID scope. Rotating that key changes both IDs. A session without an accepted key uses the unscoped fallback. The IDs describe matching normalized component sets, not people. They do not establish global uniqueness, anonymity, irreversibility, collision freedom, or continuity through every software and hardware change.

`render: false` removes the fixed rendering section. It does not disable identity. The base measured payload can still provide canvas or audio anchors, and a machine ID does not require rendering.

### Concealment

The full concealment report contains a network class, observed indicators, and checks that could not run. Network class is one of `hosting`, `access`, `institutional`, or `unknown`.

Concealment does not change the verdict. The tenant API omits the full report and projects only limited network context, including classification.

### Sensor admissions

Sensor admissions disclose faults in the packet observation path. Stable kinds are:

* `shed-flow`
* `blind`
* `stalled`
* `quiet`
* `lossy`

An admission can annotate a finding and identify findings whose packet evidence it bears on. The full sensor report also records whether removing all affected findings would remove conclusiveness. The evaluator leaves the original findings and verdict in place.

The tenant API omits the sensor report and per-finding admissions.

## Settlement and projection

After ordinary completion, the package exposes `{ ok: true, requestId }`. ZDR exposes `{ ok: true }`. Failures use `{ ok: false, reason }`.

The first valid ordinary `POST /c` closes the evidence window. The edge freezes the session evidence and assessment, builds the tenant projection from that assessment, and waits for D1 to acknowledge a tenant-visible commit. Later reads, wall-clock passage, sensor changes, local settlement, and late QUIC traffic do not amend the frozen evidence.

Only after that acknowledgement does the edge return the raw request ID. Projection failure makes collection fail. Local NDJSON persistence uses the same frozen session and assessment on its separate 60-second settlement schedule.

With `zdr: true`, the edge uses the same temporary flow, session, assessment, and identity path. Settlement skips normal edge NDJSON and control-plane ingest.

## Provenance

The current assessment uses schema `10`, ruleset revision `6`, and compute probe version `2`. Every assessment carries:

```json theme={null}
{
  "schema": 10,
  "build": "0.0.1+f19fb27",
  "ruleset_revision": 6,
  "compute_probe_version": 2
}
```

Compare provenance when records came from different builds. Do not infer a rule version from prose.

Continue with [Verdicts and coverage](/concepts/verdicts-and-coverage) for the exact ruling algebra.


## Related topics

- [Verdicts and coverage](/concepts/verdicts-and-coverage.md)
- [Heretic documentation](/index.md)
- [Collector reference](/integration/collector.md)
- [Troubleshooting](/troubleshooting.md)
- [Quickstart](/quickstart.md)