# VS Code + Augment Code Implementation Instructions

This document is intended to be pasted into Augment Code as a single task description.

## Goal

Implement non-normative Meridian EUID validators in:

1. Python (reference language)
2. TypeScript (secondary)

Both implementations MUST:

- Validate production and sandbox EUIDs per `SPEC.md`.
- Compute and verify Luhn-style MOD 32 check characters (Crockford Base32), per SPEC.md §7.5.
- Enforce canonical form (uppercase, no whitespace).
- MUST NOT perform visual substitutions (no I/L/O normalization).
- Refuse to infer semantics or auto-correct malformed input.
- Drive unit tests from the shared JSON test vectors in `test-vectors/v2.json`.

## Repository constraints

- Treat `SPEC.md` as the only normative source.
- Treat `reference-implementations/` as non-normative.
- Keep dependencies minimal.

## Step-by-step plan for Augment

### Step 1: Python reference implementation

1. Create a package at `reference-implementations/python/meridian_euid`.
2. Implement:
   - `validate(euid: str, *, environment: Literal['production','sandbox'], allowed_sandbox_prefixes: Optional[Set[str]] = None) -> str`
     - Returns the input unchanged if valid.
     - Raises a typed exception if invalid.
   - `is_valid(...) -> bool`
   - `compute_check_character(payload: str) -> str`
     - Payload is the checksum input string with hyphen removed and without the check character.
3. Enforce validation order: regex, checksum, then sandbox-prefix allowlist check (if provided).
4. Accept lowercase input but normalize to uppercase canonical form.
5. Add tests at `reference-implementations/python/tests/test_vectors.py`:
   - Load `test-vectors/v2.json`.
   - Assert that all `valid_*` vectors validate.
   - Assert that all invalid vectors fail in their specified validation context.

### Step 2: TypeScript implementation

1. Create a small library under `reference-implementations/typescript`.
2. Match Python behavior as closely as possible:
   - `validate(euid: string, options: { environment: 'production'|'sandbox', allowedSandboxPrefixes?: Set<string> }) : string`
   - `isValid(...) : boolean`
   - `computeCheckCharacter(payload: string) : string`
3. Enforce the same error conditions (no normalization, no auto-correction).
4. Add a Node.js unit test at `reference-implementations/typescript/test/vectors.test.js`:
   - Load `test-vectors/v2.json`.
   - Run the same assertions as the Python tests.

### Step 3: Cross-language consistency

1. Ensure both languages implement identical checksum mapping and algorithm.
2. Ensure both treat regex failure as distinct from checksum mismatch.

## Done criteria

- `pytest` passes under `reference-implementations/python`.
- `npm test` passes under `reference-implementations/typescript`.
- Both implementations use the shared test vectors without duplicating them.
