# meridian-euid

[![Python CI](https://github.com/lsmc-bio/meridian-euid/actions/workflows/python-ci.yml/badge.svg)](https://github.com/lsmc-bio/meridian-euid/actions/workflows/python-ci.yml)
[![Tag](https://img.shields.io/badge/tag-0.2.0pre-blue?style=flat-square)](https://github.com/lsmc-bio/meridian-euid/tags)
[![Spec](https://img.shields.io/badge/spec-0.2.0pre-blue?style=flat-square)](SPEC.md)
[![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](LICENSE-SPEC)

Meridian defines a compact **Enterprise Unique Identifier (EUID)** format suitable for printed labels and barcodes. The format is designed to be:

- **Opaque** — no embedded metadata or semantics
- **Immutable** — never reused or reassigned
- **Robust** — checksum detects transcription and scanning errors
- **Environment-aware** — strict separation between production and sandbox namespaces

## Quick Start

### Python

```bash
cd reference-implementations/python
pip install -e .

# Validate a production EUID
meridian-euid validate TX-1C --env production
# Output: VALID: TX-1C

# Encode an integer as a production EUID
meridian-euid encode 12345 DNA
# Output: DNA-C1SJ

# Parse an EUID into components
meridian-euid parse TX-1C
# Output: {"sandbox": null, "category": "TX", "body": "1", "checksum": "C", "integer": 1}

# Compute check character for a checksum payload
meridian-euid compute-check TX1
# Output: C
```

### TypeScript

```bash
cd reference-implementations/typescript
npm install && npm run build

# See reference-implementations/typescript/README.md for API examples
```

## Documentation

| Document | Description |
|----------|-------------|
| [SPEC.md](SPEC.md) | **Normative specification** — defines syntax, validation, and checksum algorithm |
| [CHANGELOG.md](CHANGELOG.md) | Version history and release notes |
| [test-vectors/](test-vectors/) | Machine-readable test cases ([README](test-vectors/README.md)) |
| [Python README](reference-implementations/python/README.md) | Python implementation with CLI |
| [TypeScript README](reference-implementations/typescript/README.md) | TypeScript/Node.js implementation |

## Repository Structure

```
meridian-euid/
├── SPEC.md                      # Normative specification
├── CHANGELOG.md                 # Version history
├── LICENSE-SPEC                 # CC BY 4.0 for specification
├── test-vectors/
│   ├── README.md
│   └── v2.json                  # Shared test vectors
├── reference-implementations/
│   ├── python/                  # Python package with CLI
│   │   ├── meridian_euid/
│   │   ├── tests/
│   │   └── README.md
│   └── typescript/              # TypeScript/Node.js library
│       ├── src/
│       ├── test/
│       └── README.md
└── docs/                        # Additional documentation
```

## EUID Format

| Type | Format | Example |
|------|--------|---------|
| Production | `<CATEGORY>-<BODY><CHECKSUM>` | `TX-1C`, `DNA-C1SJ` |
| Sandbox | `<SANDBOX>:<CATEGORY>-<BODY><CHECKSUM>` | `X:TAP-3VX`, `H:DNA-E8E` |

- **SANDBOX**: optional single letter — 15 available: `H,J,K,M,N,P,Q,R,S,T,V,W,X,Y,Z` (A–G reserved)
- **CATEGORY**: 2–3 uppercase letters, Crockford alphabet (no I/L/O/U)
- **BODY**: Crockford Base32-encoded integer (no leading zeros; MUST NOT start with `0`)
- **CHECKSUM**: 1 Crockford Base32 character via Luhn-style MOD 32 (SPEC.md §7.5)
- **Uppercase only**: lowercase input MUST be rejected (no normalization)

See [SPEC.md](SPEC.md) for complete syntax and validation rules.

## License

- **Specification** ([SPEC.md](SPEC.md), [test-vectors/](test-vectors/)): [CC BY 4.0](LICENSE-SPEC)
- **Reference implementations**: See individual implementation directories

## Contributing

Contributions are welcome. Please:

1. Open an issue to discuss proposed changes
2. Follow existing code style and conventions
3. Ensure all tests pass before submitting a PR
4. Update documentation as needed

For specification changes, note that any modification to regexes, checksum algorithm, or environment rules requires a major version bump per [SPEC.md §14](SPEC.md#14-change-control).

<!-- release-sweep: 2026-03-10 -->
 
