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

# Environment Validation

> Catching a broken environment before you run an agent against it

`silo env validate` checks an environment without running anything in it — the resources line up, and the TypeScript compiles.

```bash theme={null}
npx @burn0/silo env validate --env demo
```

```
OK  demo  data=9 tasks=6 tools=42 verifiers=6
```

Machine-readable output for CI:

```bash theme={null}
npx @burn0/silo env validate --env demo --json
```

```json theme={null}
{
  "environment": "demo",
  "ok": true,
  "findings": [],
  "counts": {
    "data": 9,
    "tasks": 6,
    "tools": 42,
    "verifiers": 6
  }
}
```

## It runs a real compile

This is the part that matters more than it sounds. Validation does not just check that files exist — it builds a TypeScript program over the environment and reports the diagnostics.

Type-only imports are erased before execution, so an environment can **load and run perfectly while being uncompilable**. "It ran" is not evidence that it is correct.

```
ERROR  typecheck  state.ts:354:7 Type 'string' is not assignable to type 'number'.
FAILED demo  data=9 tasks=6 tools=43 verifiers=7
```

The compiler settings come from `.silo/tsconfig.json`, written by `silo init` and never overwritten if you already have one. The validator and `tsc -p .silo/tsconfig.json` always agree, so there is no second source of truth about whether your environment is sound.

## What it checks

Beyond compilation, validation catches the wiring mistakes that only show up mid-run:

| Finding                  | Meaning                                                                           |
| ------------------------ | --------------------------------------------------------------------------------- |
| `typecheck`              | A TypeScript diagnostic, with file, line and column                               |
| `verifier_task_mismatch` | Two verifiers claim the same task, or a verifier names a task that does not exist |
| `task_verifier_missing`  | A task names a `verifierId` nothing provides                                      |
| `environment_not_found`  | No environment by that name                                                       |

A real example — scaffolding `VER-007` against a task that already has a grader:

```
ERROR  verifier_task_mismatch  Verifier "VER-007" claims task "TASK-001", but that task is graded by "VER-001".
FAILED demo  data=9 tasks=6 tools=43 verifiers=7
```

Note the counts still print on failure. They are a quick sanity check in their own right: if you added three tools and the number did not move, they are not registered in the barrel.

## Validate before you conclude anything

Make this the stopping condition when building an environment, rather than "the run worked":

```bash theme={null}
npx @burn0/silo env validate --env demo && \
npx @burn0/silo run --env demo --task TASK-001
```

A passing run tells you one path through the environment executed. Validation tells you the whole thing is consistent — including the tools that task never called and the verifiers that task never used.

This is especially true when a coding agent is building the environment for you. "It ran" is the easiest possible thing to satisfy and the weakest possible evidence.

## In the SDK

```typescript theme={null}
const report = await env.validate();

if (!report.ok) {
  for (const finding of report.findings) {
    console.error(`${finding.level} ${finding.code} ${finding.message}`);
  }
}
```

Same shape as `--json`, same checks. The CLI and the SDK are two interfaces over one implementation.

## Exit codes

`env validate` exits non-zero when validation fails, so it drops straight into a pipeline:

```yaml theme={null}
- run: npx @burn0/silo env validate --env demo --json
```

Pair it with a recorded run baseline for the stronger gate. Validation proves the environment is *sound*; a baseline proves its behaviour has not *changed*. Neither substitutes for the other.