ref-id 0.7.0__py3-none-any.whl

ref_id/__init__.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The `ref:` identifier scheme — a Python port held to `spec/ref-id.json`'s conformance vectors.
+
+Track 2 lands the embedded specification, its integrity check, the canonical serialisation and the set
+digest. Parse, serialise, build and the envelope are Track 3; relations are Track 4.
+"""
+from __future__ import annotations
+
+from .build import build
+from .canonical import canonicalise
+from .digest import digest
+from .envelope import validate_envelope
+from .errors import (
+    BuildError,
+    DigestError,
+    RefIdError,
+    SerialiseError,
+    SpecIntegrityError,
+    SpecVersionError,
+)
+from .parse import parse
+from .relations import covers, relate, same_identifier, same_package, verdict
+from .serialise import canonical_identifier, serialise
+from .spec import Spec, embedded_spec_text, load_spec, load_spec_from
+from .types import (
+    BuildParts,
+    EnvelopeResult,
+    Fragment,
+    NestedValue,
+    ParseResult,
+    QualifierRelation,
+    RelateResult,
+    VerdictDecidedBy,
+    VerdictResult,
+)
+
+__all__ = [
+    "BuildError",
+    "BuildParts",
+    "DigestError",
+    "EnvelopeResult",
+    "Fragment",
+    "NestedValue",
+    "ParseResult",
+    "QualifierRelation",
+    "RefIdError",
+    "RelateResult",
+    "SerialiseError",
+    "Spec",
+    "SpecIntegrityError",
+    "SpecVersionError",
+    "VerdictDecidedBy",
+    "VerdictResult",
+    "build",
+    "canonical_identifier",
+    "canonicalise",
+    "covers",
+    "digest",
+    "embedded_spec_text",
+    "load_spec",
+    "load_spec_from",
+    "parse",
+    "relate",
+    "same_identifier",
+    "same_package",
+    "serialise",
+    "validate_envelope",
+    "verdict",
+]

ref_id/build.py

@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Assembles a `ref:` identifier string from its parts. A part the grammar cannot carry is refused with
+`BuildError` naming it — the builder never emits a string that means something else, which is proven at
+the end by parsing what was built and comparing it with what was asked.
+
+Ported from `crates/ref-id/src/build.rs`.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .encoding import contains_any, encode, table_for
+from .errors import BuildError
+from .grammar import (
+    FIELD,
+    FRAGMENT_INTRODUCER,
+    LINE_BREAKS,
+    PAIR,
+    scheme_prefix,
+)
+from .parse import parse
+from .spec import Spec, load_spec
+from .types import BuildParts, Fragment, NestedValue
+from .validators import folds_type
+
+__all__ = ["build"]
+
+
+def _nesting_form(spec: Spec, key: str) -> dict[str, Any] | None:
+    declared = spec.get_object("qualifiers")
+    entry = declared.get(key) if declared is not None else None
+    if not isinstance(entry, dict):
+        return None
+    forms = spec.get_object("forms") or {}
+    for name in entry.get("forms", []):
+        if not isinstance(name, str):
+            continue
+        form = forms.get(name)
+        if isinstance(form, dict) and form.get("nested") is True:
+            return form
+    return None
+
+
+def _refuse(spec: Spec, part: str, why: str) -> BuildError:
+    return _refuse_at(spec.part(part), why)
+
+
+def _refuse_at(part: str, why: str) -> BuildError:
+    """The message names the refused part, so a caller reads what to change instead of guessing and
+    retrying. A part `parse` already reported is used verbatim: it may be a key the identifier carries
+    and the spec never declared."""
+    return BuildError(part, f"cannot build: {why} — refused at the {part}")
+
+
+def build(parts: BuildParts, /) -> str:
+    """Builds a `ref:` identifier string."""
+    spec = load_spec()
+    grammar = spec.grammar()
+    state_separator = spec.get_str("grammar", "state", "separator")
+    fragment_separator = spec.get_str("grammar", "fragment", "separator")
+    separators = state_separator + FRAGMENT_INTRODUCER + "".join(LINE_BREAKS)
+    fragment_reserved = fragment_separator + "".join(LINE_BREAKS)
+
+    locator = parts.locator
+    fold = f"{parts.type}{FIELD}"
+    if folds_type(spec, parts.type) and locator.startswith(fold):
+        locator = locator[len(fold) :]
+
+    if not locator or contains_any(locator, separators):
+        raise _refuse(spec, "locator", "a locator is handed to its validator verbatim and cannot carry a reserved character")
+
+    out = [f"{scheme_prefix(spec)}{parts.type}{FIELD}{locator}"]
+
+    if parts.qualifiers:
+        rendered = []
+        for pair in parts.qualifiers:
+            # `parts.qualifiers` is declared as a tuple of `(key, value)` pairs; a caller who hands a
+            # `dict` instead bypasses the type checker (as `BuildParts.from_json`'s own malformed-shape
+            # guard already does for the JSON entry point) and would otherwise unpack each dict *key*
+            # string into `key, value` — silently wrong for a two-character key, a bare `ValueError` for
+            # any other length. Checked and refused here the same way `from_json` refuses its own shape.
+            if not isinstance(pair, (tuple, list)) or len(pair) != 2 or not isinstance(pair[0], str):
+                raise _refuse(spec, "state", "a qualifier is a (key, value) pair with a string key")
+            key, value = pair
+            if isinstance(value, NestedValue):
+                if not isinstance(value.nested, str):
+                    raise _refuse(spec, key, "a qualifier value is a string or NestedValue holding a string")
+                form = _nesting_form(spec, key)
+                if form is None:
+                    raise _refuse(spec, key, "this qualifier declares no nesting form")
+                encoded = encode(value.nested, table_for(spec, form))
+            elif isinstance(value, str):
+                if value.startswith(scheme_prefix(spec)) or contains_any(value, separators):
+                    raise _refuse(spec, key, "a nested identifier is passed as Nested, never as a plain string")
+                encoded = value
+            else:
+                raise _refuse(spec, key, "a qualifier value is a string or NestedValue holding a string")
+            rendering = f"{key}{PAIR}{encoded}"
+            if grammar.state_pair.fullmatch(rendering) is None:
+                raise _refuse(spec, key, "the key does not fit the pair grammar")
+            rendered.append(rendering)
+        out.append(state_separator)
+        out.append(state_separator.join(rendered))
+
+    wanted_path: str | None = None
+    wanted_refinements: tuple[tuple[str, str], ...] = ()
+    if parts.fragment is not None:
+        if isinstance(parts.fragment, str):
+            path = parts.fragment
+        elif isinstance(parts.fragment, Fragment):
+            path = parts.fragment.path
+            wanted_refinements = parts.fragment.refinements
+        else:
+            raise _refuse(spec, "fragment", "a fragment is a string or Fragment")
+        if not path or contains_any(path, fragment_reserved):
+            raise _refuse(spec, "fragment", "a declared-name path cannot be empty or carry the refinement separator")
+        for key, value in wanted_refinements:
+            if contains_any(value, fragment_reserved):
+                raise _refuse(spec, key, "a refinement value cannot carry the separator")
+        out.append(FRAGMENT_INTRODUCER)
+        out.append(path)
+        if wanted_refinements:
+            out.append(fragment_separator)
+            out.append(fragment_separator.join(f"{key}{PAIR}{value}" for key, value in wanted_refinements))
+        wanted_path = path
+
+    assembled = "".join(out)
+
+    # The last word is the grammar's: what was built must decompose to exactly what was asked.
+    if grammar.top.fullmatch(assembled) is None:
+        raise _refuse(spec, "grammar", "the assembled string does not match the grammar")
+    check = parse(assembled)
+    if check.status == spec.status("malformed"):
+        refused = check.part if check.part is not None else spec.part("grammar")
+        raise _refuse_at(refused, "the assembled string is malformed")
+    if check.explicit_version or check.type != parts.type:
+        raise _refuse(spec, "type", "the type re-split into other parts")
+    if check.locator != locator:
+        raise _refuse(spec, "locator", "the locator re-split into other parts")
+    if len(check.qualifiers) != len(parts.qualifiers):
+        raise _refuse(spec, "state", "a qualifier re-split into other parts")
+    check_path = check.fragment.path if check.fragment is not None else None
+    check_refinements = len(check.fragment.refinements) if check.fragment is not None else 0
+    if check_path != wanted_path or check_refinements != len(wanted_refinements):
+        raise _refuse(spec, "fragment", "the fragment re-split into other parts")
+    return assembled

ref_id/canonical.py

@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The canonical serialisation `/canonicalisation` fixes: object keys sorted by UTF-16 code unit, no
+whitespace outside strings, strings escaped exactly as ECMAScript `JSON.stringify` does, integers only.
+
+Ported from `crates/ref-id/src/canonical.rs`. `json.dumps` is not used for string escaping: measured
+(2026-09-27), Python's own encoder writes a lone surrogate through unescaped, where `JSON.stringify`
+escapes it as `\\uXXXX` — the two implementations would then digest different bytes for the same
+member.
+"""
+from __future__ import annotations
+
+import json
+
+from .errors import SpecIntegrityError
+
+__all__ = ["canonicalise"]
+
+_maximum_cache: int | None = None
+
+
+def _maximum() -> int:
+    """`version.maximum`, read from the embedded specification rather than written as a literal here.
+    Deferred import: `spec.py` imports this module at its own top level to build `canonicalise`, so the
+    reverse read happens only inside this function body, by which time both modules are fully loaded —
+    and it reads the raw bytes rather than the validated `Spec`, because this is itself the function that
+    computes the digest `Spec` is validated against."""
+    global _maximum_cache
+    if _maximum_cache is None:
+        from .spec import embedded_spec_text
+
+        json_text, _sidecar_text = embedded_spec_text()
+        document = json.loads(json_text)
+        value = document.get("version", {}).get("maximum") if isinstance(document, dict) else None
+        if not isinstance(value, int) or isinstance(value, bool):
+            raise SpecIntegrityError("spec/ref-id.json does not declare version.maximum as an integer")
+        _maximum_cache = value
+    return _maximum_cache
+
+_ESCAPES = {
+    '"': '\\"',
+    "\\": "\\\\",
+    "\b": "\\b",
+    "\f": "\\f",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+
+
+def _escape(string: str) -> str:
+    out: list[str] = ['"']
+    index = 0
+    length = len(string)
+    while index < length:
+        char = string[index]
+        code = ord(char)
+        # A Python `str` may hold an unpaired surrogate half where JavaScript would already have joined
+        # it into one UTF-16 code unit pair naming a single character. Joining a high/low pair back into
+        # its codepoint before deciding how to write it keeps this port's output identical to
+        # `JSON.stringify`'s for a string built the way JavaScript itself would see it — two `str` halves
+        # from splitting an astral character must canonicalise the same as that one character.
+        if 0xD800 <= code <= 0xDBFF and index + 1 < length:
+            next_code = ord(string[index + 1])
+            if 0xDC00 <= next_code <= 0xDFFF:
+                combined = 0x10000 + (code - 0xD800) * 0x400 + (next_code - 0xDC00)
+                out.append(chr(combined))
+                index += 2
+                continue
+        if char in _ESCAPES:
+            out.append(_ESCAPES[char])
+        elif code < 0x20 or 0xD800 <= code <= 0xDFFF:
+            # A lone surrogate cannot be re-encoded as UTF-8 unescaped; `JSON.stringify` escapes it
+            # exactly like a control character, and this port must match that byte for byte.
+            out.append(f"\\u{code:04x}")
+        else:
+            out.append(char)
+        index += 1
+    out.append('"')
+    return "".join(out)
+
+
+def _sort_key(key: str) -> bytes:
+    # UTF-16 code unit order, per `/canonicalisation`. `surrogatepass` lets a key that is itself a lone
+    # surrogate (or carries one) still sort, rather than raising where the specification does not.
+    return key.encode("utf-16-be", "surrogatepass")
+
+
+# A depth this deep has no legitimate use in a specification document (the real one nests a handful of
+# levels); it exists so a pathologically deep or cyclic input is refused with `SpecIntegrityError` well
+# before it could exhaust CPython's own call stack (`RecursionError`) — Security review finding 5.
+_MAX_DEPTH = 500
+
+
+def _describe_int(value: int) -> str:
+    """A safe textual magnitude for an error message — `str()`/`repr()` on an integer long enough hits
+    CPython's own int-conversion digit-count guard, which would turn *reporting* the refusal into the
+    same crash this function exists to avoid."""
+    try:
+        return repr(value)
+    except ValueError:
+        sign = "-" if value < 0 else ""
+        return f"{sign}<integer of magnitude 2**{value.bit_length()}>"
+
+
+def _write(value: object, out: list[str], maximum: int, depth: int, seen: set[int]) -> None:
+    if depth > _MAX_DEPTH:
+        raise SpecIntegrityError(f"canonicalisation nests more than {_MAX_DEPTH} levels deep")
+    if value is None:
+        out.append("null")
+    elif isinstance(value, bool):
+        out.append("true" if value else "false")
+    elif isinstance(value, int):
+        if abs(value) > maximum:
+            raise SpecIntegrityError(f"canonicalisation covers magnitudes up to {maximum}, got {_describe_int(value)}")
+        out.append(str(value))
+    elif isinstance(value, float):
+        # A number is an integer whose magnitude is at most `version.maximum`, written as that integer;
+        # an integral value written with a fraction or an exponent (`json.loads` turns both into a
+        # `float`, e.g. `1.0` or `1e2`) is that integer; any other number is refused (`/canonicalisation`).
+        if not value.is_integer() or abs(value) > maximum:
+            raise SpecIntegrityError(f"canonicalisation covers integers only, got {value!r}")
+        out.append(str(int(value)))
+    elif isinstance(value, str):
+        out.append(_escape(value))
+    elif isinstance(value, (list, tuple)):
+        # `id(value)` marks a container as "on the path from the root to here" for the length of its own
+        # recursion (added on entry, discarded on exit) — a reference cycle (a container that reaches
+        # itself through its own descendants) is refused instead of recursing forever, while the same
+        # object appearing twice in separate, non-nested branches (aliasing, not a cycle) still
+        # canonicalises normally.
+        marker = id(value)
+        if marker in seen:
+            raise SpecIntegrityError("canonicalisation cannot serialise a cyclic structure")
+        seen.add(marker)
+        try:
+            out.append("[")
+            for i, item in enumerate(value):
+                if i > 0:
+                    out.append(",")
+                _write(item, out, maximum, depth + 1, seen)
+            out.append("]")
+        finally:
+            seen.discard(marker)
+    elif isinstance(value, dict):
+        marker = id(value)
+        if marker in seen:
+            raise SpecIntegrityError("canonicalisation cannot serialise a cyclic structure")
+        seen.add(marker)
+        try:
+            if any(not isinstance(key, str) for key in value):
+                raise SpecIntegrityError("canonicalisation covers string-keyed objects only")
+            keys = sorted(value.keys(), key=_sort_key)
+            out.append("{")
+            for i, key in enumerate(keys):
+                if i > 0:
+                    out.append(",")
+                out.append(_escape(key))
+                out.append(":")
+                _write(value[key], out, maximum, depth + 1, seen)
+            out.append("}")
+        finally:
+            seen.discard(marker)
+    else:
+        raise SpecIntegrityError(f"canonicalisation cannot serialise a value of type {type(value).__name__}")
+
+
+def canonicalise(value: object, /) -> str:
+    """The canonical serialisation the specification digest is computed over."""
+    out: list[str] = []
+    _write(value, out, _maximum(), 0, set())
+    return "".join(out)

ref_id/digest.py

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: Apache-2.0
+"""sha256 over the UTF-8 bytes of the joined identifier strings, per `spec.digest`: declared order, no
+deduplication, and a refusal for a member that carries the join character.
+
+Ported line for line from `crates/ref-id/src/digest.rs`.
+"""
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Sequence
+
+from .errors import DigestError, SpecVersionError
+from .grammar import FIELD
+from .spec import load_spec
+
+__all__ = ["digest"]
+
+
+def digest(members: Sequence[str], /) -> str:
+    """Digests an ordered, non-deduplicated sequence of identifier strings."""
+    spec = load_spec()
+    if not isinstance(members, (list, tuple)):
+        # A bare `str` satisfies `Sequence[str]` at the type level (of its own characters) but is not a
+        # sequence of members, and neither is a generator or a set — the TypeScript reference refuses
+        # anything that is not an array the same way (`packages/ref-id/src/digest.ts:15`).
+        raise DigestError(spec.part("member"), "members must be a list or tuple of strings")
+    # One snapshot, taken only after the shape refusal above, so a lazily-consumed iterable (were one
+    # ever accepted) cannot be re-read differently between validation and hashing.
+    snapshot = list(members)
+    join = spec.get_str("digest", "join")
+    for member in snapshot:
+        if not isinstance(member, str):
+            raise DigestError(spec.part("member"), "a member must be a string")
+        try:
+            member.encode("utf-8")
+        except UnicodeEncodeError as error:
+            raise DigestError(spec.part("member"), "a member must encode as UTF-8") from error
+        if join in member:
+            raise DigestError(spec.part("member"), "a member must be a string that does not carry the join character")
+    algorithm = spec.get_str("digest", "algorithm")
+    if algorithm != "sha256":
+        raise SpecVersionError(f"spec.digest.algorithm declares {algorithm}; this package implements sha256 only")
+    joined = join.join(snapshot)
+    hashed = hashlib.sha256(joined.encode("utf-8")).hexdigest()
+    return f"{algorithm}{FIELD}{hashed}"

ref_id/encoding.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Percent-encode/decode helpers driven by an `encoding.<name>.table` from the specification — never a
+hardcoded character list. Which table applies to a form is the form's own `encoding` field.
+
+Ported from `crates/ref-id/src/encoding.rs`.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .spec import Spec
+
+__all__: list[str] = []
+
+Table = list[tuple[str, str]]
+
+
+def table_for(spec: Spec, form: dict[str, Any]) -> Table:
+    """The encoding table a form declares, or an empty one when the form declares no encoding."""
+    name = form.get("encoding")
+    if not isinstance(name, str):
+        return []
+    return spec.get_table("encoding", name, "table")
+
+
+def contains_any(raw: str, characters: str) -> bool:
+    return any(char in characters for char in raw)
+
+
+def encode(raw: str, table: Table) -> str:
+    """One left-to-right pass over the source characters; a produced percent-form is never re-scanned."""
+    if not table:
+        return raw
+    out: list[str] = []
+    for char in raw:
+        form = next((value for key, value in table if len(key) == 1 and key == char), None)
+        out.append(form if form is not None else char)
+    return "".join(out)
+
+
+def decode(encoded: str, table: Table) -> str:
+    """One left-to-right pass over the encoded text; decoding `%2523` yields `%23`, never `#`.
+
+    Scans by index rather than slicing a fresh `rest` string every step: `rest = rest[1:]` (and the
+    matching `rest.startswith(form)`) copies the remaining text on every character, which is quadratic in
+    the input length. `str.startswith(form, i)` matches at an offset without copying anything."""
+    if not table:
+        return encoded
+    out: list[str] = []
+    length = len(encoded)
+    index = 0
+    while index < length:
+        match = next(((character, form) for character, form in table if encoded.startswith(form, index)), None)
+        if match is not None:
+            character, form = match
+            out.append(character)
+            index += len(form)
+        else:
+            out.append(encoded[index])
+            index += 1
+    return "".join(out)
+
+
+def strictly_encoded(value: str, table: Table) -> bool:
+    """True when every `%` in the value begins one of the table's percent-forms — the strict nested
+    encoding.
+
+    `value[at:]` builds a fresh substring at every `%` found, which is quadratic when `%` recurs densely
+    (`"%25" * n`, say); `value.startswith(form, at)` checks the same forms at that offset without copying
+    the tail."""
+    index = 0
+    while True:
+        at = value.find("%", index)
+        if at < 0:
+            return True
+        if not any(value.startswith(form, at) for _character, form in table):
+            return False
+        index = at + 1

ref_id/envelope.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The envelope invariant from `spec.envelope`: an identifier carrying a digest is admissible only with
+an object whose sets entry for that qualifier recomputes to it, served under its own id.
+
+Ported from `crates/ref-id/src/envelope.rs`.
+"""
+from __future__ import annotations
+
+from .digest import digest
+from .errors import DigestError, SpecVersionError
+from .parse import parse
+from .spec import load_spec
+from .types import EnvelopeResult
+
+__all__ = ["validate_envelope"]
+
+
+def _refused(reason: str) -> EnvelopeResult:
+    return EnvelopeResult(admissible=False, reason=reason)
+
+
+def validate_envelope(requested_id: str, envelope: object) -> EnvelopeResult:
+    """Refuses an envelope whose self-reference or recomputed digests do not hold."""
+    spec = load_spec()
+    self_reference = spec.get_str("envelope", "selfReference")
+    sets_field = spec.get_str("envelope", "setsField")
+
+    if not isinstance(envelope, dict):
+        return _refused("envelope is not an object")
+    if envelope.get(self_reference) != requested_id:
+        return _refused(f"envelope.{self_reference} does not match the requested identifier")
+
+    parsed = parse(requested_id)
+    if parsed.status in (spec.status("malformed"), spec.status("unsupported")):
+        return _refused(f"the requested identifier is {parsed.status}")
+
+    grammar = spec.grammar()
+    digest_patterns: list[str] = []
+    for name, form in (spec.get_object("forms") or {}).items():
+        if not isinstance(form, dict) or form.get("digest") is not True:
+            continue
+        pattern = form.get("pattern")
+        if not isinstance(pattern, str):
+            raise SpecVersionError(f"spec.forms.{name} declares digest: true without a pattern; this package cannot recognise it")
+        digest_patterns.append(pattern)
+
+    sets = envelope.get(sets_field)
+    sets = sets if isinstance(sets, dict) else None
+
+    for key, value in parsed.qualifiers:
+        is_digest = any(grammar.matches(spec, pattern, value) for pattern in digest_patterns)
+        if not is_digest:
+            continue
+        members = sets.get(key) if sets is not None else None
+        if not isinstance(members, list) or not all(isinstance(item, str) for item in members):
+            return _refused(f"{sets_field}.{key} is missing or is not an array of strings")
+        try:
+            recomputed = digest(members)
+        except DigestError as error:
+            return _refused(f"{sets_field}.{key} {error.message}")
+        if recomputed != value:
+            return _refused(f"{sets_field}.{key} does not recompute to the declared digest")
+
+    return EnvelopeResult(admissible=True)

ref_id/errors.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The error hierarchy every other module raises through.
+
+`RefIdError` is the base every kind subclasses; `BuildError`, `DigestError` and `SerialiseError` carry
+the refused `part`, `SpecIntegrityError` and `SpecVersionError` do not. `str(error)` follows the crate's
+`Display` (`crates/ref-id/src/types.rs:142`): ``"<Kind>Error at <part>: <message>"`` for the three with a
+part, ``"<Kind>Error: <message>"`` for the other two.
+"""
+from __future__ import annotations
+
+__all__ = [
+    "BuildError",
+    "DigestError",
+    "RefIdError",
+    "SerialiseError",
+    "SpecIntegrityError",
+    "SpecVersionError",
+]
+
+
+class RefIdError(ValueError):
+    """The base of every error this package raises. `parse` raises none for an identifier problem."""
+
+
+class BuildError(RefIdError):
+    """`build` was given a part the grammar cannot carry."""
+
+    def __init__(self, part: str, message: str) -> None:
+        super().__init__(f"BuildError at {part}: {message}")
+        self.part = part
+        self.message = message
+
+
+class DigestError(RefIdError):
+    """`digest` was given a member that is not one identifier string."""
+
+    def __init__(self, part: str, message: str) -> None:
+        super().__init__(f"DigestError at {part}: {message}")
+        self.part = part
+        self.message = message
+
+
+class SerialiseError(RefIdError):
+    """`serialise` was given a result that has no faithful string form."""
+
+    def __init__(self, part: str, message: str) -> None:
+        super().__init__(f"SerialiseError at {part}: {message}")
+        self.part = part
+        self.message = message
+
+
+class SpecIntegrityError(RefIdError):
+    """The embedded specification does not match its sidecar digest."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(f"SpecIntegrityError: {message}")
+        self.message = message
+
+
+class SpecVersionError(RefIdError):
+    """The embedded specification declares a version or vocabulary this package does not support."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(f"SpecVersionError: {message}")
+        self.message = message