# Diagnostics [#diagnostics]

Diagnostics explain calculation health and metadata quality. They are part of
the public calculation model, not private debug output.

## When this matters [#when-this-matters]

Use diagnostics when you need to show validation issues, inspect graph health
or test that a calculator ran without metadata problems.

## How it works [#how-it-works]

`CalculatorRunResponse` includes a `diagnostics` field beside the calculator
metadata and report:

This excerpt assumes `client`, `calculatorId` and `payload` are already checked
application values. It returns an Effect for your application host to run.

```ts
import { CalculationQuery } from "@taxkit/calculators/schemas";
import { Effect, Option } from "effect";

const issueCount = client.calculatorApi
  .calculate({
    params: { calculatorId },
    payload,
    query: CalculationQuery.make({
      help: Option.some(Option.some("errors")),
    }),
  })
  .pipe(Effect.map((response) => response.diagnostics.graphIssues.length));
```

Expected output for the current take-home pay success fixture is:

```txt
0
```

## Trace and graph data [#trace-and-graph-data]

Trace data records which rule ran, what it used, what it produced and which
sources support it. Graph data exposes dependency edges and validation issues
through the calculator graph endpoint.

## Related concepts [#related-concepts]

* [Reports](/concepts/reports)
* [Rules](/concepts/rules)
* [Graph, trace and ledgers architecture](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/docs/architecture/graph-trace-ledgers.md)