# Intentrail integration guide

Intentrail records a bounded synthetic grid mission, its deterministic trace, and its local validation result. The public assets are static and require no account or hosted mission service.

## Published assets

- `schemas/mission-manifest.schema.json`
- `schemas/mission-run-receipt.schema.json`
- `schemas/mission-anchor-envelope.schema.json`
- `examples/mission-manifest.example.json`
- `examples/mission-run-receipt.example.json`
- `examples/mission-run-collision.example.json`
- `examples/mission-run-out-of-bounds.example.json`
- `examples/mission-run-tampered.example.json`
- `examples/mission-anchor-envelope.example.json`
- `examples/mission-trace.example.csv`
- `core.mjs`
- `chain-read.mjs`
- `verify-intentrail.mjs`

All example missions are synthetic. They are not robot telemetry or evidence of physical execution.

## Verify a downloaded record

Download `core.mjs`, `verify-intentrail.mjs`, and the record into one directory, then run:

```sh
node verify-intentrail.mjs mission-run-receipt.example.json
```

Exit code `0` means the record passed the published verifier. Exit code `1` means a digest, replay, guarded field, or record boundary did not match. Exit code `2` means no input path was supplied.

Verification establishes agreement with the declared deterministic rules and selected canonical bytes. It does not establish identity, trusted time, sensor truth, hardware safety, physical execution, or public anchoring.

## Use the core as ESM

```js
import {
  createMissionManifest,
  createRunReceipt,
  verifyRunReceipt
} from "./core.mjs";

const manifest = await createMissionManifest({
  mode: "local",
  missionId: "EXAMPLE-01",
  title: "Synthetic relay",
  width: 5,
  height: 4,
  start: { x: 0, y: 3 },
  goal: { x: 4, y: 0 },
  checkpoints: [{ id: "check-a", x: 2, y: 2 }],
  obstacles: [{ x: 1, y: 2 }],
  maxSteps: 12,
  commands: ["E", "E", "N", "N", "E", "E", "N"]
});

const receipt = await createRunReceipt(manifest);
const check = await verifyRunReceipt(receipt);
if (!check.valid) throw new Error("The local receipt did not verify.");
```

## Trace CSV fields

| Field | Meaning |
| --- | --- |
| `step` | One-based command index. |
| `command` | `N`, `E`, `S`, `W`, or `WAIT`. |
| `from_x`, `from_y` | Position before the command. |
| `attempted_x`, `attempted_y` | Requested position, including blocked or out-of-grid attempts. |
| `to_x`, `to_y` | Position after deterministic rules are applied. |
| `event` | Movement, wait, checkpoint, goal, collision, or boundary event. |
| `checkpoint_id` | Checkpoint reached on that step, otherwise empty. |
| `checkpoint_visited` | Number of ordered checkpoints reached by this step. |
| `checkpoint_total` | Total ordered checkpoints declared by the mission. |
| `checkpoint_percent` | Integer completion percentage after this step. |

The JSON receipt is authoritative. Its explicit `validator` object identifies the deterministic rules version used for replay. CSV is a portable trace view and does not include every receipt field.

## Wallet boundary

`chain-read.mjs` limits provider access to public read methods. Connecting a wallet is separate from receipt creation, local points, the optional review, and envelope export. No signing, approval, network switch, payment, or broadcast method is part of the release.