baseh 1.1.0__tar.gz

baseh-1.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: baseh
+Version: 1.1.0
+Summary: baseH codec: checksumed, optionally permuted human-readable identifiers
+License: AGPL-3.0-only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# baseh
+
+Python implementation of the baseH codec. Encodes an internal integer ID as
+a checksummed, optionally permuted human-readable reference code. Implements
+the normative spec in `../spec/IMPLEMENTATION_CODEC.md` and passes the
+frozen cross-language vectors in `../vectors/`.
+
+Zero runtime dependencies. HMAC-SHA-256 comes from the standard library.
+
+## Install
+
+```bash
+pip install ./python
+```
+
+Or run in place without installing:
+
+```bash
+PYTHONPATH=python/src python3 -c "import baseh"
+```
+
+## Usage
+
+```python
+from baseh import Baseh, BasehError, baseh_medium_v1
+
+codec = Baseh(baseh_medium_v1())
+
+code = codec.encode(123456789)
+print(code)                       # fixed-length, checksummed code
+
+result = codec.decode(code.lower())  # case-insensitive
+print(result.id)                  # 123456789
+print(result.canonical_code)      # canonical rendering
+print(result.corrected)           # False (input differed only in case)
+
+# Assisted correction over spoken-confusion pairs (B/D, P/T, ...):
+fixed = codec.decode(
+    code,
+    try_correction=True,
+    confusion_profile="light",
+)
+
+# Non-throwing validation for user input:
+check = codec.validate("0000000")
+print(check)                      # {"valid": False, "reason": "INVALID_CHECKSUM"}
+
+print(codec.capacity())           # 481890304
+```
+
+Errors raise `BasehError` with a `.code` attribute, one of:
+`INVALID_PROFILE`, `OUT_OF_RANGE`, `PERMUTATION_FAILURE`, `INVALID_LENGTH`,
+`INVALID_CHARACTER`, `INVALID_CHECKSUM`, `AMBIGUOUS_INPUT`,
+`TOO_MANY_CANDIDATES`, `BLOCKED_CODE`.
+
+## Frozen tiers
+
+Four frozen profiles, each 6 body symbols and case-insensitive, built from
+the full alphanumeric set with cumulative visual and spoken strips:
+
+| Tier | Helper | Symbols | Checksum | Capacity |
+|------|--------|---------|----------|----------|
+| Minimum | `baseh_minimum_v1()` | 36 | none | 2,176,782,336 |
+| Light | `baseh_light_v1()` | 31 | 1 | 887,503,681 |
+| Medium | `baseh_medium_v1()` | 28 | 1 | 481,890,304 |
+| Heavy | `baseh_heavy_v1()` | 26 | 1 | 308,915,776 |
+
+Medium is the default. All four keep the typed O/I/L aliases where possible
+and run the default profanity blocklist. Minimum also uses a hyphen
+delimiter (`XXX-XXX`); the rest have none.
+
+Each helper returns a freshly-built mutable profile dict on every call, so
+callers can load a default and modify it:
+
+```python
+profile = baseh_medium_v1()
+profile["checksumLength"] = 2
+codec = Baseh(profile)
+```
+
+### Permuted variants
+
+The `_p` variants are identical to their tier but enable feistel-v1
+permutation and require caller-supplied key material:
+
+```python
+from baseh import Baseh, baseh_medium_p_v1
+
+key = bytes.fromhex("746573742d6f6e6c792d6b65792d6d6174657269616c2d30303031")
+codec = Baseh(baseh_medium_p_v1(key, key_id="my-app-01"))  # rounds defaults to 8
+```
+
+Available as `baseh_minimum_p_v1`, `baseh_light_p_v1`, `baseh_medium_p_v1`
+and `baseh_heavy_p_v1`.
+
+## Profanity safety (spec 18)
+
+All frozen tiers run the default blocklist. Profiles accept a `profanity`
+field to change that:
+
+```python
+# Block specific words (substrings of the raw code) at encode time:
+profile = baseh_medium_v1()
+profile["profanity"] = {"mode": "blocklist", "extraWords": ["QQQQ"]}
+codec = Baseh(profile)
+# codec.encode(id) raises BasehError(code="BLOCKED_CODE") on a match.
+
+# Or remove vowels from both alphabets entirely:
+profile["profanity"] = {"mode": "no-vowels"}
+```
+
+## Tests
+
+```bash
+cd python
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```

baseh-1.1.0/README.md

@@ -0,0 +1,117 @@
+# baseh
+
+Python implementation of the baseH codec. Encodes an internal integer ID as
+a checksummed, optionally permuted human-readable reference code. Implements
+the normative spec in `../spec/IMPLEMENTATION_CODEC.md` and passes the
+frozen cross-language vectors in `../vectors/`.
+
+Zero runtime dependencies. HMAC-SHA-256 comes from the standard library.
+
+## Install
+
+```bash
+pip install ./python
+```
+
+Or run in place without installing:
+
+```bash
+PYTHONPATH=python/src python3 -c "import baseh"
+```
+
+## Usage
+
+```python
+from baseh import Baseh, BasehError, baseh_medium_v1
+
+codec = Baseh(baseh_medium_v1())
+
+code = codec.encode(123456789)
+print(code)                       # fixed-length, checksummed code
+
+result = codec.decode(code.lower())  # case-insensitive
+print(result.id)                  # 123456789
+print(result.canonical_code)      # canonical rendering
+print(result.corrected)           # False (input differed only in case)
+
+# Assisted correction over spoken-confusion pairs (B/D, P/T, ...):
+fixed = codec.decode(
+    code,
+    try_correction=True,
+    confusion_profile="light",
+)
+
+# Non-throwing validation for user input:
+check = codec.validate("0000000")
+print(check)                      # {"valid": False, "reason": "INVALID_CHECKSUM"}
+
+print(codec.capacity())           # 481890304
+```
+
+Errors raise `BasehError` with a `.code` attribute, one of:
+`INVALID_PROFILE`, `OUT_OF_RANGE`, `PERMUTATION_FAILURE`, `INVALID_LENGTH`,
+`INVALID_CHARACTER`, `INVALID_CHECKSUM`, `AMBIGUOUS_INPUT`,
+`TOO_MANY_CANDIDATES`, `BLOCKED_CODE`.
+
+## Frozen tiers
+
+Four frozen profiles, each 6 body symbols and case-insensitive, built from
+the full alphanumeric set with cumulative visual and spoken strips:
+
+| Tier | Helper | Symbols | Checksum | Capacity |
+|------|--------|---------|----------|----------|
+| Minimum | `baseh_minimum_v1()` | 36 | none | 2,176,782,336 |
+| Light | `baseh_light_v1()` | 31 | 1 | 887,503,681 |
+| Medium | `baseh_medium_v1()` | 28 | 1 | 481,890,304 |
+| Heavy | `baseh_heavy_v1()` | 26 | 1 | 308,915,776 |
+
+Medium is the default. All four keep the typed O/I/L aliases where possible
+and run the default profanity blocklist. Minimum also uses a hyphen
+delimiter (`XXX-XXX`); the rest have none.
+
+Each helper returns a freshly-built mutable profile dict on every call, so
+callers can load a default and modify it:
+
+```python
+profile = baseh_medium_v1()
+profile["checksumLength"] = 2
+codec = Baseh(profile)
+```
+
+### Permuted variants
+
+The `_p` variants are identical to their tier but enable feistel-v1
+permutation and require caller-supplied key material:
+
+```python
+from baseh import Baseh, baseh_medium_p_v1
+
+key = bytes.fromhex("746573742d6f6e6c792d6b65792d6d6174657269616c2d30303031")
+codec = Baseh(baseh_medium_p_v1(key, key_id="my-app-01"))  # rounds defaults to 8
+```
+
+Available as `baseh_minimum_p_v1`, `baseh_light_p_v1`, `baseh_medium_p_v1`
+and `baseh_heavy_p_v1`.
+
+## Profanity safety (spec 18)
+
+All frozen tiers run the default blocklist. Profiles accept a `profanity`
+field to change that:
+
+```python
+# Block specific words (substrings of the raw code) at encode time:
+profile = baseh_medium_v1()
+profile["profanity"] = {"mode": "blocklist", "extraWords": ["QQQQ"]}
+codec = Baseh(profile)
+# codec.encode(id) raises BasehError(code="BLOCKED_CODE") on a match.
+
+# Or remove vowels from both alphabets entirely:
+profile["profanity"] = {"mode": "no-vowels"}
+```
+
+## Tests
+
+```bash
+cd python
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```

baseh-1.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "baseh"
+version = "1.1.0"
+description = "baseH codec: checksumed, optionally permuted human-readable identifiers"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "AGPL-3.0-only" }
+dependencies = []
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

baseh-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

baseh-1.1.0/src/baseh/__init__.py

@@ -0,0 +1,62 @@
+"""baseH codec, Python implementation.
+
+Public API mirrors spec section 12: the Baseh codec class, BasehError with a
+stable .code attribute and the frozen profile tier helpers (baseh_medium_v1
+is the default tier; the _p variants enable feistel-v1 permutation).
+"""
+
+from .blocklist import DEFAULT_BLOCKLIST
+from .codec import CONFUSION_MAPS, Baseh, DecodeResult, generate_candidates
+from .errors import (
+    AMBIGUOUS_INPUT,
+    BLOCKED_CODE,
+    INVALID_CHARACTER,
+    INVALID_CHECKSUM,
+    INVALID_LENGTH,
+    INVALID_PROFILE,
+    OUT_OF_RANGE,
+    PERMUTATION_FAILURE,
+    TOO_MANY_CANDIDATES,
+    BasehError,
+)
+from .profiles import (
+    baseh_heavy_p_v1,
+    baseh_heavy_v1,
+    baseh_light_p_v1,
+    baseh_light_v1,
+    baseh_medium_p_v1,
+    baseh_medium_v1,
+    baseh_minimum_p_v1,
+    baseh_minimum_v1,
+)
+from .zero import from_code, to_code
+
+__all__ = [
+    "Baseh",
+    "BasehError",
+    "DecodeResult",
+    "CONFUSION_MAPS",
+    "DEFAULT_BLOCKLIST",
+    "generate_candidates",
+    "baseh_minimum_v1",
+    "baseh_minimum_p_v1",
+    "baseh_light_v1",
+    "baseh_light_p_v1",
+    "baseh_medium_v1",
+    "baseh_medium_p_v1",
+    "baseh_heavy_v1",
+    "baseh_heavy_p_v1",
+    "INVALID_PROFILE",
+    "OUT_OF_RANGE",
+    "PERMUTATION_FAILURE",
+    "INVALID_LENGTH",
+    "INVALID_CHARACTER",
+    "INVALID_CHECKSUM",
+    "AMBIGUOUS_INPUT",
+    "TOO_MANY_CANDIDATES",
+    "BLOCKED_CODE",
+    "to_code",
+    "from_code",
+]
+
+__version__ = "1.0.0"

baseh-1.1.0/src/baseh/basen.py

@@ -0,0 +1,36 @@
+"""Fixed-length base-N encode and decode, spec sections 5.1 through 5.3."""
+
+from __future__ import annotations
+
+from .errors import INVALID_CHARACTER, OUT_OF_RANGE, BasehError
+
+
+def alphabet_index(alphabet: str) -> dict:
+    return {ch: i for i, ch in enumerate(alphabet)}
+
+
+def encode_base_n(value: int, alphabet: str, length: int) -> str:
+    """Fixed-length base-N encode, most significant digit first."""
+    base = len(alphabet)
+    capacity = base ** length
+    if value < 0 or value >= capacity:
+        raise BasehError(OUT_OF_RANGE, "value is outside the fixed-length capacity")
+    out = [""] * length
+    v = value
+    for pos in range(length - 1, -1, -1):
+        out[pos] = alphabet[v % base]
+        v //= base
+    return "".join(out)
+
+
+def decode_base_n(text: str, alphabet: str, index: dict | None = None) -> int:
+    base = len(alphabet)
+    if index is None:
+        index = alphabet_index(alphabet)
+    value = 0
+    for ch in text:
+        digit = index.get(ch)
+        if digit is None:
+            raise BasehError(INVALID_CHARACTER, f"Symbol {ch!r} is not in the alphabet")
+        value = value * base + digit
+    return value

baseh-1.1.0/src/baseh/blocklist.py

@@ -0,0 +1,41 @@
+"""Profanity safety primitives, spec section 18."""
+
+from __future__ import annotations
+
+import re
+
+from .errors import INVALID_PROFILE, BasehError
+
+# Spec 18.2 default list. Deliberately small; applications extend it.
+DEFAULT_BLOCKLIST = (
+    "CRAP", "TWAT", "SHAG", "DAMN", "FCK", "FUC",
+    "SHT", "CNT", "TWT", "DCK", "AZZ", "BCH",
+)
+
+_WORD = re.compile(r"^[A-Za-z]{2,32}$")
+_VOWELS = frozenset("AEIOU")
+
+
+def effective_blocklist(profanity: dict) -> list:
+    """Spec 18.2: replacement semantics, then augmentation, uppercased and
+    deduplicated. Raises BasehError INVALID_PROFILE on a malformed entry."""
+    base = list(profanity["words"]) if "words" in profanity else list(DEFAULT_BLOCKLIST)
+    words = base + list(profanity.get("extraWords") or [])
+    out: list = []
+    for word in words:
+        if not isinstance(word, str) or not _WORD.match(word):
+            raise BasehError(
+                INVALID_PROFILE,
+                "Invalid baseH profile: blocklist entries must be 2 through 32 ASCII letters",
+                False,
+            )
+        upper = word.upper()
+        if upper not in out:
+            out.append(upper)
+    return out
+
+
+def strip_vowels(alphabet_norm: str) -> str:
+    """Spec 18.1: vowels removed for no-vowels mode, applied after case
+    normalization."""
+    return "".join(ch for ch in alphabet_norm if ch not in _VOWELS)

baseh-1.1.0/src/baseh/checksum.py

@@ -0,0 +1,36 @@
+"""Version 1 rolling polynomial checksum, spec section 6.2."""
+
+from __future__ import annotations
+
+from .basen import alphabet_index, encode_base_n
+from .errors import INVALID_CHARACTER, BasehError
+from .profile import PreparedProfile
+
+_INITIAL_STATE = 17
+_MULTIPLIER = 37
+
+
+def checksum_value(profile: PreparedProfile, body: str, body_index: dict) -> int:
+    """Return the checksum value in [0, modulus)."""
+    modulus = profile.checksum_modulus
+    state = _INITIAL_STATE
+    for byte in profile.profile_id.encode("ascii"):
+        state = (state * _MULTIPLIER + byte + 1) % modulus
+    state = (state * _MULTIPLIER) % modulus
+    for pos, ch in enumerate(body):
+        value = body_index.get(ch)
+        if value is None:
+            raise BasehError(
+                INVALID_CHARACTER, f"Symbol {ch!r} is not in the body alphabet"
+            )
+        state = (state * _MULTIPLIER + value + pos + 1) % modulus
+    return state
+
+
+def calculate_checksum(profile: PreparedProfile, body: str) -> str:
+    """Compute the expected checksum string for a normalized body."""
+    if profile.checksum_length == 0:
+        return ""
+    index = alphabet_index(profile.body_alphabet_norm)
+    value = checksum_value(profile, body, index)
+    return encode_base_n(value, profile.checksum_alphabet_norm, profile.checksum_length)

baseh-1.1.0/src/baseh/codec.py

@@ -0,0 +1,242 @@
+"""Full encode and decode flows, spec sections 8, 9, 10, 11 and 12."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .basen import alphabet_index, decode_base_n, encode_base_n
+from .checksum import calculate_checksum
+from .errors import (
+    AMBIGUOUS_INPUT,
+    BLOCKED_CODE,
+    INVALID_CHARACTER,
+    INVALID_CHECKSUM,
+    INVALID_LENGTH,
+    OUT_OF_RANGE,
+    TOO_MANY_CANDIDATES,
+    BasehError,
+)
+from .feistel import FeistelKey, inverse_permute, permute
+from .profile import PreparedProfile, prepare_profile
+
+# Built-in spoken-confusion candidate maps, spec 3.3. Body symbols only.
+CONFUSION_MAPS = {
+    "light": {"B": ["D"], "D": ["B"], "P": ["T"], "T": ["P"]},
+    "medium": {
+        "B": ["D"], "D": ["B"], "P": ["T"], "T": ["P"],
+        "M": ["N"], "N": ["M"], "V": ["W"], "W": ["V"],
+    },
+    "heavy": {
+        "B": ["D"], "D": ["B"], "P": ["T"], "T": ["P"],
+        "M": ["N"], "N": ["M"], "V": ["W"], "W": ["V"],
+        "F": ["S"], "S": ["F"], "C": ["G"], "G": ["C"],
+    },
+}
+
+_ASCII_WS = "\t\n\v\f\r "
+_MAX_CANDIDATES = 64
+
+
+@dataclass(frozen=True)
+class DecodeResult:
+    id: int
+    canonical_code: str
+    corrected: bool
+
+
+def normalize(input: str, profile: PreparedProfile, accept_spaces: bool = False) -> str:
+    """Spec 3.1 normalization, steps 1-7. Returns the raw unformatted string."""
+    if not isinstance(input, str):
+        raise BasehError(INVALID_CHARACTER, "input must be a string")
+    s = input.strip(_ASCII_WS)
+    if profile.separator:
+        s = s.replace(profile.separator, "")
+    if accept_spaces:
+        s = s.replace(" ", "")
+    if not profile.case_sensitive:
+        s = s.upper()
+    if profile.aliases_norm:
+        s = "".join(profile.aliases_norm.get(ch, ch) for ch in s)
+    allowed = set(profile.body_alphabet_norm) | set(profile.checksum_alphabet_norm)
+    for ch in s:
+        if ch not in allowed:
+            raise BasehError(INVALID_CHARACTER, f"Symbol {ch!r} is not accepted")
+    expected = profile.body_length + profile.checksum_length
+    # Spec 3.4: a code that lost leading zero body symbols is re-padded with
+    # the body zero symbol. The checksum symbols always remain, so the split
+    # point is unambiguous. A fully stripped no-checksum code would be empty
+    # and stays a length error.
+    if len(s) < expected and len(s) >= max(profile.checksum_length, 1):
+        zero = profile.body_alphabet_norm[0]
+        s = zero * (expected - len(s)) + s
+    if len(s) != expected:
+        raise BasehError(INVALID_LENGTH, f"Expected {expected} symbols, got {len(s)}")
+    return s
+
+
+def format_raw(raw: str, profile: PreparedProfile) -> str:
+    if not profile.separator:
+        return raw
+    parts = []
+    offset = 0
+    for size in profile.grouping:
+        parts.append(raw[offset : offset + size])
+        offset += size
+    return profile.separator.join(parts)
+
+
+def generate_candidates(body: str, confusion_map: dict, max_edits: int = 1) -> list:
+    """Spec 10. Substitution-only candidate generation, capped and deduplicated."""
+    if max_edits == 0:
+        return []
+    results: set = set()
+    for pos, source in enumerate(body):
+        for replacement in confusion_map.get(source, ()):
+            candidate = body[:pos] + replacement + body[pos + 1 :]
+            results.add(candidate)
+            if len(results) > _MAX_CANDIDATES:
+                raise BasehError(
+                    TOO_MANY_CANDIDATES,
+                    "Candidate generation exceeded 64 entries",
+                    False,
+                )
+    return list(results)
+
+
+class Baseh:
+    """Codec bound to one validated profile. The profile is validated once at
+    construction per spec 2.2, never per encode or decode."""
+
+    def __init__(self, profile: dict) -> None:
+        if isinstance(profile, PreparedProfile):
+            self._profile = profile
+        else:
+            self._profile = prepare_profile(profile)
+        self._body_index = alphabet_index(self._profile.body_alphabet_norm)
+
+    @property
+    def profile(self) -> PreparedProfile:
+        return self._profile
+
+    def capacity(self) -> int:
+        return self._profile.capacity
+
+    def _feistel_key(self) -> FeistelKey:
+        perm = self._profile.permutation
+        return FeistelKey(
+            profile_id=self._profile.profile_id,
+            key_bytes=perm.key_bytes,
+            rounds=perm.rounds,
+        )
+
+    def encode(self, id: int) -> str:
+        """Spec 8, including the section 18.2 blocked-substring scan."""
+        if isinstance(id, bool) or not isinstance(id, int):
+            raise BasehError(OUT_OF_RANGE, "id must be an integer")
+        value = id
+        if value < 0 or value >= self._profile.capacity:
+            raise BasehError(OUT_OF_RANGE, f"ID {value} is outside the profile capacity")
+        if self._profile.permutation.enabled:
+            value = permute(value, self._profile.capacity, self._feistel_key())
+        body = encode_base_n(
+            value, self._profile.body_alphabet_norm, self._profile.body_length
+        )
+        checksum = calculate_checksum(self._profile, body)
+        raw = body + checksum
+        # Spec 18.2: case-insensitive substring scan over the raw code.
+        if self._profile.blocklist:
+            upper = raw.upper()
+            if any(word in upper for word in self._profile.blocklist):
+                raise BasehError(
+                    BLOCKED_CODE,
+                    "The generated reference contains a blocked substring",
+                    False,
+                )
+        return format_raw(raw, self._profile)
+
+    def decode(
+        self,
+        input: str,
+        *,
+        accept_spaces: bool = False,
+        try_correction: bool = False,
+        confusion_profile: str = "none",
+        max_corrections: int = 1,
+    ) -> DecodeResult:
+        """Spec 9."""
+        raw = normalize(input, self._profile, accept_spaces)
+        body = raw[: self._profile.body_length]
+        supplied_checksum = raw[self._profile.body_length :]
+
+        # Spec 3.1 validates union membership before the split. There is no
+        # per-region membership check: a checksum-region symbol outside the
+        # checksum alphabet fails as INVALID_CHECKSUM and a body symbol
+        # outside the body alphabet fails in the checksum or base-N work as
+        # INVALID_CHARACTER.
+
+        if calculate_checksum(self._profile, body) != supplied_checksum:
+            if not try_correction or max_corrections == 0:
+                raise BasehError(
+                    INVALID_CHECKSUM, "The reference code did not pass validation"
+                )
+            if confusion_profile == "none":
+                raw_map: dict = {}
+            elif confusion_profile in CONFUSION_MAPS:
+                raw_map = CONFUSION_MAPS[confusion_profile]
+            else:
+                raise ValueError(
+                    f"unknown confusion profile: {confusion_profile!r}"
+                )
+            # Spec 10: replacements that are not body alphabet symbols are
+            # dropped before candidate generation. A suggested symbol the
+            # alphabet cannot contain (say a spoken drop on a stripped-alphabet
+            # profile) could never validate; generating it anyway would raise
+            # INVALID_CHARACTER from the checksum step instead of reporting an
+            # honest INVALID_CHECKSUM.
+            body_set = set(self._profile.body_alphabet_norm)
+            confusion_map = {}
+            for source, replacements in raw_map.items():
+                kept = [r for r in replacements if r in body_set]
+                if kept:
+                    confusion_map[source] = kept
+            valid: set = set()
+            for candidate in generate_candidates(body, confusion_map, max_corrections):
+                if calculate_checksum(self._profile, candidate) == supplied_checksum:
+                    valid.add(candidate)
+            if not valid:
+                raise BasehError(
+                    INVALID_CHECKSUM, "The reference code did not pass validation"
+                )
+            if len(valid) > 1:
+                raise BasehError(
+                    AMBIGUOUS_INPUT,
+                    "The reference code matches more than one record",
+                    False,
+                )
+            body = next(iter(valid))
+
+        value = decode_base_n(
+            body, self._profile.body_alphabet_norm, self._body_index
+        )
+        if self._profile.permutation.enabled:
+            value = inverse_permute(
+                value, self._profile.capacity, self._feistel_key()
+            )
+        canonical_code = self.encode(value)
+        if self._profile.separator:
+            canonical_raw = canonical_code.replace(self._profile.separator, "")
+        else:
+            canonical_raw = canonical_code
+        return DecodeResult(
+            id=value,
+            canonical_code=canonical_code,
+            corrected=(raw != canonical_raw),
+        )
+
+    def validate(self, input: str, **options) -> dict:
+        """Spec 12.4. Never raises on user input."""
+        try:
+            result = self.decode(input, **options)
+            return {"valid": True, "canonical_code": result.canonical_code}
+        except BasehError as err:
+            return {"valid": False, "reason": err.code}