# Test Vectors

Machine-readable test cases for validating Meridian EUID implementations.

## Purpose

Test vectors ensure consistent behavior across all implementations. Both the [Python](../reference-implementations/python/) and [TypeScript](../reference-implementations/typescript/) reference implementations use these vectors in their test suites.

## File Format

### v2.json (current)

```json
{
  "meta": {
    "id": "meridian-euid-test-vectors-v2",
    "generated_on": "2026-02-08",
    "spec_version": "0.1.0pre",
    "checksum_system": "Luhn-style MOD 32 (Crockford Base32), per SPEC.md §7.5"
  },
  "valid_production": [...],
  "valid_sandbox": [...],
  "invalid": [...]
}
```

### v1.json (legacy)

`v1.json` has been removed. The repository uses `v2.json` as the shared contract for all reference implementations.

### Sections

| Section | Description |
|---------|-------------|
| `meta` | Version and generation metadata |
| `valid_production` | EUIDs that MUST validate in production context |
| `valid_sandbox` | EUIDs that MUST validate in sandbox context with specified prefixes |
| `invalid` | Inputs that MUST be rejected, with context and reason |

### Constraints (0.1.0pre)

- **CATEGORY**: 2–3 uppercase Crockford letters (minimum changed from 1 to 2)
- **Sandbox prefixes A–G**: reserved; 15 available: `H,J,K,M,N,P,Q,R,S,T,V,W,X,Y,Z`
- **Uppercase only**: lowercase input MUST be rejected (no normalization)

### Valid Production Entry

```json
{
  "euid": "TX-1C",
  "integer": 1
}
```

### Valid Sandbox Entry

```json
{
  "euid": "X:TAP-3VX",
  "allowed_sandbox_prefixes": ["X"],
  "integer": 123
}
```

### Invalid Entry

```json
{
  "euid": "TX-1D",
  "context": {
    "environment": "production"
  },
  "reason": "checksum mismatch (correct checksum is C)"
}
```

The `context` object specifies the validation environment and optional `allowed_sandbox_prefixes`.

## Usage in Tests

### Python

```python
import json
from pathlib import Path

vectors = json.loads(Path("test-vectors/v2.json").read_text())

for case in vectors["valid_production"]:
    assert is_valid(case["euid"], environment="production")
```

### TypeScript

```javascript
const vectors = require('../../test-vectors/v2.json');

for (const { euid } of vectors.valid_production) {
  assert(isValid(euid, { environment: 'production' }));
}
```

## Related Documentation

- [SPEC.md](../SPEC.md) — Normative specification
- [Python Tests](../reference-implementations/python/tests/)
- [TypeScript Tests](../reference-implementations/typescript/test/)
