<!-- Generated by scripts/ax-docs.mts from the JSDoc in registry/ouro/ax/. Do not edit; run `pnpm run docs`. -->

# ax-xray

The Ouro AX conformance checker: it calls a CLI, an HTTP API or an MCP server the way an agent would, and reports which claims hold on which surface, with the fix where a claim does not hold. It checks from outside, never by importing the interface's code. Reads run freely; what other people see is called only on paths that must refuse (a made-up target, no `--why`) or that act on nothing (`--dry-run`), and only against a target that proves it is a mock.

```sh
node xray.ts --cli "<command>" [--http <url> --routes <manifest.json>] [--mcp "<command>"] [options]
```

```sh
npx shadcn@latest add ourostack/ouro-ui/ax-xray#v1.3.10
```

It installs `lib/ouro/ax/xray.ts`, with `ax-checks`, `ax-claims`, `ax-component`, `ax-dev-commands`, `ax-outcome`, `ax-precise-copy`, `ax-terminal`, `ax-wait`, `ax-work-event`. Its tests are `ax-xray-tests`. Every item runs on Node 22.18 or later as it is copied: the files import each other as `./<file>.ts`. The [Ouro AX guide](ax.md) shows how they fit together.

## Exports

### `audienceWho`

An outcome's `audience.who`, or an empty string.

```ts
function audienceWho(value: unknown): string
```

### `CheckResult`

```ts
interface CheckResult {
  claim: string;
  surface: string;
  verdict: Verdict;
  note: string;
}
```

### `checkSafety`

Whether the X-ray may call what other people see, failing closed: every address it can see is loopback, the home is isolated, the target proves it is a mock (`--mock "<url> <key>=<value>"`, or the adopter's `--guard`, which already passed), and no credential is passed to it. Any missing proof refuses those checks and says why.

```ts
function checkSafety(opts: XrayOptions, guardPassed: boolean): Promise<Safety>
```

### `claimSetHash`

The SHA-256 of the claim set's canonical JSON: a report pins the exact standard it checked.

```ts
function claimSetHash(): string
```

### `compareInventory`

Compares what the X-ray covered with the inventory: missing, unknown and listed twice on either side.

```ts
function compareInventory(expected: readonly string[], covered: readonly string[]): InventoryCompare
```

### `harvest`

Collects sample refs from a JSON answer: the first `ref` (else `id`) of each array, keyed by its name, singular.

```ts
function harvest(value: unknown, samples: Record<string, string>, key?: string | null): Record<string, string>
```

### `Inventory`

The surfaces an adopter generates from its own registration: CLI command names, HTTP `METHOD /path` routes, MCP tool names, and its components' bound reads and actions (`ui`, the entries `bindAx` returns), whose twins it checks.

```ts
interface Inventory {
  cli?: string[];
  http?: string[];
  mcp?: string[];
  ui?: UiEntry[];
}
```

### `InventoryCompare`

```ts
interface InventoryCompare {
  expected: number;
  covered: number;
  missing: string[];
  unknown: string[];
  duplicate: string[];
}
```

### `main`

The command: parses argv, runs, writes the reports; resolves the exit code.

```ts
function main(argv: readonly string[], io?: Io): Promise<number>
```

### `misspell`

Drops one inner letter: --limit becomes --limt.

```ts
function misspell(flag: string): string
```

### `parseArgs`

```ts
function parseArgs(argv: readonly string[]): XrayOptions
```

### `refsOf`

The refs that a JSON answer's list items carry, as a read's text should show them (`cli.text-refs`).

```ts
function refsOf(value: unknown, out?: string[]): string[]
```

### `refusalVerdict`

A refusal's footprint: nothing, or only records that say they were refused.

```ts
function refusalVerdict(delta: { same: boolean; added: string[]; removed: string[]; }): { ok: boolean; note: string; }
```

### `renderHtml`

```ts
function renderHtml(report: Report): string
```

### `renderMarkdown`

```ts
function renderMarkdown(report: Report): string
```

### `renderText`

```ts
function renderText(report: Report, max?: number): string
```

### `Report`

```ts
interface Report {
  tool: "ax-xray";
  checker: { version: string };
  claimSet: { version: string; hash: string };
  at: string;
  target: { commit: string | null; cli?: { name: string; calls: number; commands: number }; http?: { origin: string; routes: number; requests: number }; mcp?: { tools: number } };
  safety: Safety;
  inventory: { given: boolean; surfaces: ClaimSurface[] };
  effects: { surface: string; note: string }[];
  conformant: boolean;
  summary: { claims: number; holding: number; must: number; mustHolding: number; mustSkipped: number; checks: { pass: number; fail: number; skip: number }; score: number | null };
  claims: ClaimSummary[];
  results: CheckResult[];
}
```

### `requiredWords`

Removes `[...]` groups (nested) from a usage line and splits it into words.

```ts
function requiredWords(usage: string): string[]
```

### `Safety`

```ts
interface Safety {
  ok: boolean;
  checks: { name: string; ok: boolean; note: string }[];
}
```

### `splitCommand`

Splits a command line into words, honouring single and double quotes.

```ts
function splitCommand(line: string): string[]
```

### `stateDelta`

What changed between two state snapshots, element by element: arrays compare by their members.

```ts
function stateDelta(before: readonly string[], after: readonly string[]): { same: boolean; added: string[]; removed: string[]; }
```

### `summarize`

The report from the results: per claim, how many surfaces hold it; overall, whether the interface conforms.

```ts
function summarize(results: readonly CheckResult[], parts: Pick<Report, "target" | "safety" | "inventory" | "effects">, at?: string): Report
```

### `usageWords`

Splits a usage line into words, keeping a placeholder with spaces (`<message id>`) in one word.

```ts
function usageWords(usage: string): string[]
```

### `Verdict`

```ts
type Verdict = "pass" | "fail" | "skip";
```

### `xray`

Runs the X-ray: the guard, the safety proof, then the surfaces given; returns the report.

```ts
function xray(opts: XrayOptions): Promise<Report>
```

### `XRAY_VERSION`

The Ouro AX conformance checker: it calls a CLI, an HTTP API or an MCP server the way an agent would, and reports which claims hold on which surface, with the fix where a claim does not hold. It checks from outside, never by importing the interface's code. Reads run freely; what other people see is called only on paths that must refuse (a made-up target, no `--why`) or that act on nothing (`--dry-run`), and only against a target that proves it is a mock.

```sh
node xray.ts --cli "<command>" [--http <url> --routes <manifest.json>] [--mcp "<command>"] [options]
```

```ts
const XRAY_VERSION: "1.5.0"
```

### `XrayOptions`

```ts
interface XrayOptions {
  cli?: string | undefined;
  http?: string | undefined;
  routes?: string | undefined;
  mcp?: string | undefined;
  name?: string | undefined;
  env: Record<string, string>;
  guard?: string | undefined;
  mock?: string | undefined;
  home?: string | undefined;
  inventory?: string | undefined;
  events?: string | undefined;
  commit?: string | undefined;
  failureCopyAllow?: string | undefined;
  conformance: boolean;
  state: string[];
  volatile: string[];
  samples: Record<string, string>;
  width: number;
  timeoutMs: number;
  json: boolean;
  md?: string | undefined;
  html?: string | undefined;
  command: "claims" | "help" | null;
}
```