Public API¶

class AddOp(OperationSchema):
    """RFC 6902 add operation."""

    model_config = ConfigDict(
        title="Add operation",
        json_schema_extra={"description": "RFC 6902 add operation."},
    )

    op: Literal["add"] = "add"
    path: JSONPointer[JSONValue]
    value: JSONValue

    @override
    def apply(self, doc: JSONValue) -> JSONValue:
        return self.path.add(doc, self.value)

class CopyOp(OperationSchema):
    """RFC 6902 copy operation."""

    model_config = ConfigDict(
        title="Copy operation",
        json_schema_extra={"description": "RFC 6902 copy operation."},
    )

    op: Literal["copy"] = "copy"
    from_: JSONPointer[JSONValue] = Field(alias="from")
    path: JSONPointer[JSONValue]

    @override
    def apply(self, doc: JSONValue) -> JSONValue:
        value = self.from_.get(doc)
        duplicate = copy.deepcopy(value)
        return AddOp(path=self.path, value=duplicate).apply(doc)

class DEFAULT_POINTER_CLS:
    """
    Default JSON Pointer backend powered by `jsonpointer.JsonPointer`.

    This implementation parses RFC 6901 pointer strings, exposes unescaped
    parts, reconstructs canonical pointers from parts, and resolves pointers
    against JSON documents.
    """

    __slots__ = ("_parts", "_pointer")

    @override
    def __init__(self, pointer: str) -> None:
        """Parse an RFC 6901 pointer string and cache its unescaped parts.

        Arguments:
            pointer: RFC 6901 pointer string to parse.
        """
        self._pointer = _FixedJsonPointer(pointer)
        self._parts = cast(Sequence[str], self._pointer.parts)

    @property
    def parts(self) -> Sequence[str]:
        """Return the pointer's unescaped RFC 6901 reference tokens.

        Returns:
            The pointer's unescaped reference tokens.
        """
        return self._parts

    @classmethod
    def from_parts(cls, parts: Iterable[str]) -> Self:
        """Build a canonical RFC 6901 pointer from unescaped reference tokens.

        Arguments:
            parts: Unescaped RFC 6901 reference tokens.

        Returns:
            A canonical RFC 6901 pointer for those tokens.
        """
        canonical = _FixedJsonPointer.from_parts(parts)
        return cls(str(canonical))

    def resolve(self, doc: JSONValue) -> JSONValue:
        """Resolve this pointer against a JSON document.

        Arguments:
            doc: JSON document to resolve against.

        Returns:
            The value targeted by this pointer.
        """
        return cast(JSONValue, self._pointer.resolve(doc))

    @override
    def __str__(self) -> str:
        """Return the canonical RFC 6901 string form.

        Returns:
            The canonical RFC 6901 string representation.
        """
        return str(self._pointer)

    @override
    def __repr__(self) -> str:
        """Return a debugging representation of this backend instance.

        Returns:
            A representation showing the backend name and source pointer.
        """
        return "JsonPointerRFC6901(" + repr(self._pointer.path) + ")"

class DEFAULT_SELECTOR_CLS:
    """
    Default JSONPath selector backend powered by `python-jsonpath`.

    This implementation compiles JSONPath expressions with the shared strict
    environment and yields exact pointer locations for each match.

    Disclaimer:
        This backend follows RFC 9535 path syntax and semantics, except on
        Python 3.14 and later where regex-related behavior falls back to
        Python's built-in `re` module because the upstream `iregexp-check`
        dependency is not yet compatible with free-threaded Python.
    """

    __slots__ = ("_path", "_selector")

    def __init__(self, selector: str) -> None:
        """Compile a JSONPath selector string with the built-in strict environment.

        Arguments:
            selector: JSONPath selector string to compile.
        """
        self._path = selector
        self._selector = _DEFAULT_SELECTOR_ENV.compile(selector)

    def pointers(self, doc: JSONValue) -> Iterable[DEFAULT_POINTER_CLS]:
        """Yield canonical RFC 6901 pointers for each matched location.

        Arguments:
            doc: JSON document to evaluate against.

        Returns:
            An iterable of canonical RFC 6901 pointers for each match.
        """
        for match in self._selector.finditer(doc):
            yield DEFAULT_POINTER_CLS.from_parts((str(part) for part in match.parts))

    @override
    def __str__(self) -> str:
        """Return the selector's original source string.

        Returns:
            The original selector source string.
        """
        return self._path

    @override
    def __repr__(self) -> str:
        """Return a debugging representation of this backend instance.

        Returns:
            A representation showing the backend name and source selector.
        """
        return "JsonPathRFC9535(" + repr(self._path) + ")"

class InvalidJSONPointer(PatchInputError):
    """
    A JSON Pointer definition or instance is invalid.

    Examples:
        - Pointer string is malformed or uses an incompatible backend.
        - Pointer backend class fails protocol checks.

    Typical HTTP mapping:
        422 Unprocessable Entity for request input.
    """

class InvalidJSONSelector(PatchInputError):
    """
    A JSON selector definition or instance is invalid.

    Examples:
        - Selector string is malformed or uses an incompatible backend.
        - Selector backend class fails protocol checks.

    Typical HTTP mapping:
        422 Unprocessable Entity for request input.
    """

class InvalidOperationDefinition(PatchError):
    """
    An OperationSchema definition is invalid (developer error).

    Examples:
        - `op` is missing or not declared as `Literal[...]`.
        - `op` is declared as a ClassVar, so it is not a model field.
    """

class InvalidOperationRegistry(PatchError):
    """
    An OperationRegistry has incompatible OperationSchemas (developer error).

    Examples:
        - Duplicate `op` identifiers across schemas.
        - Non-OperationSchema classes provided to the registry.
    """

@final
class JSONPointer(str, Generic[T_co, P_co]):
    """
    A typed RFC 6901 JSON Pointer with Pydantic integration.

    `JSONPointer[T]` (or `JSONPointer[T, Backend]`) is a string-like value (subclasses `str`)
    that additionally:

    - stores a parsed pointer backend (see `PointerBackend`),
    - tracks a covariant type parameter `T` used to validate resolved targets,
    - provides convenience methods used by patch operations: `get`, `add`, `remove`.

    ## Important design semantics (intentional)

    **Typed pointers are enforced at runtime.**
    The type parameter `T` is not “just typing”; it is enforced whenever a value is read
    through the pointer.

    - `get(doc)` always validates the resolved value against `T`.
    - `add(doc, value)` optionally validates the written value against `T` (default: True).
    - `remove(doc)` is intentionally *type-gated*: it first “reads” the target through the pointer,
      so removal can fail if the current value is not of type `T`.

    This makes patch semantics explicit:
    - `JSONPointer[JSONValue]` is permissive (“remove anything JSON”).
    - `JSONPointer[JSONBoolean]` is restrictive (“remove only if it is currently a boolean”).
    - If you want to remove regardless of the current type, use a wider pointer type (e.g. `JSONValue`)
      or define a dedicated permissive remove operation.

    **Pointer covariance is intentional.**
    `JSONPointer` is covariant in `T`. In practice this means you can often reuse a pointer instance
    (including across composed operations) and preserve stricter guarantees.
    Examples: if a custom op carries a `JSONPointer[JSONBoolean]`, composing that op internally
    using `AddOp` should keep the boolean-specific enforcement at runtime.

    ## Backend semantics (advanced)

    - Default backend: `jsonpointer.JsonPointer`.
    - Custom backend: bound directly via `JSONPointer[T, Backend]`.
    - Invalid pointer strings raise `InvalidJSONPointer`.
    - Backend traversal failures in `get`/`add`/`remove` are normalized into
      `PatchConflictError`.

    Mutation semantics:
    - `add` and `remove` may mutate the document object they are given (or containers reachable
      from it). The root pointer `""` is the exception: setting the root returns a new document
      value rather than mutating an existing container. Removing the root returns
      `MISSING` to represent document deletion rather than a JSON `null` value.
      A missing root document is handled as its own state: root `get` and root `remove`
      fail, while root `add` recreates the document.
      If you want to forbid root removal, it's easy to make a custom op!
    - Whether these mutations affect the original caller-owned document is determined by the patch
      engine (see `_apply_ops(..., inplace=...)`), which may deep-copy the input document.

    `JSONPointer` values are intended to be created by Pydantic validation. Direct instantiation
    is not permitted (except when running as `__main__` for debugging).
    """

    # Choice: JSONPointer is str subclass, as opposed to Annotated[str, StringConstraints(...)].
    # Why: Cache adapters and pointers where possible, and provide simple primitives like get/add
    #      out-of-the-box, owned by the field, so path.get(doc) just works. Most users don't need
    #      more advanced functionality, so don't require them to reason about the PointerBackend API.
    # Considered: From a mutation point of view, consider reversing ownership to something like doc.get(path).
    #             Downside would be maintaining a JSONDocument wrapper around JSONValues, and taking power
    #             away from the PointerBackend implementation, which should really own the mutation logic.
    # Also considered: Performance drawback (https://docs.pydantic.dev/latest/concepts/performance/?utm_source=chatgpt.com#avoid-extra-information-via-subclasses-of-primitives).
    #                  I may replace str inheritance with a str property that derives from str(self._ptr).
    #                  But I like the idea that users think of JSONPointer[T] as the path string with extra abilities.

    __slots__ = ("_ptr", "_type")

    _ptr: P_co
    _type: TypeForm[T_co]

    @property
    def ptr(self) -> P_co:
        """
        The underlying pointer backend instance.

        This is exposed for advanced users who provide a custom PointerBackend with additional APIs.
        The patch engine relies only on the `PointerBackend` protocol.
        """
        # TODO: Somehow 'Any' to the actual JSON Pointer class they pass in.
        # Choice: expose ptr as the user's custom PointerBackend for stronger type inferencing.
        # Why: This library only needs the PointerBackend Protocol, if some users want a custom
        #      PointerBackend, then expose that richer API to those users at type-checker time.
        return self._ptr

    @property
    def parts(self) -> Sequence[str]:
        """A sequence of RFC6901-unescaped pointer components."""
        return self._ptr.parts

    @property
    def type_param(self) -> TypeForm[T_co]:
        """The expected type parameter `T` used to validate resolved targets."""
        return self._type

    @property
    def _adapter(self) -> TypeAdapter[T_co]:
        """Return the cached Pydantic adapter used for strict `T` validation."""
        return _cached_adapter(self._type)

    @property
    def parent_ptr(self) -> P_co:  # NOTE: add parent property for JSONPointer of parent
        """Return the backend pointer for this pointer's parent path."""
        return _parent_ptr_of(self._ptr)

    def is_root(self, doc: JSONValue) -> bool:
        """Check whether this JSONPointer's target is the root."""
        return _is_root_ptr(self._ptr, doc)

    @classmethod
    def _validator(
        cls,
        path: str | PointerBackend,
        *,
        type_param: TypeForm[Any],
        concrete_backend: type[PointerBackend] | TypeVar,
    ) -> Self:
        """
        Normalize a raw pointer input into a validated `JSONPointer`.

        Arguments:
            path: Pointer string, parsed `JSONPointer`, or backend pointer
                instance supplied by Pydantic validation.
            type_param: Already-validated runtime type parameter `T`.
            concrete_backend: Already-validated backend parameter.

        Returns:
            A `JSONPointer` bound to the resolved backend and type parameter.

        Raises:
            InvalidJSONPointer: If an existing pointer/backend instance cannot
                be rebound to the required backend.
        """
        resolved_backend = cls._resolve_runtime_backend_param(concrete_backend)
        ptr: PointerBackend
        if isinstance(path, JSONPointer):
            path_str = str(path)
            if resolved_backend is DEFAULT_POINTER_CLS:
                ptr = path._ptr
            elif isinstance(path._ptr, resolved_backend):
                ptr = path._ptr
            else:
                ptr = _pointer_backend_instance(path_str, pointer_cls=resolved_backend)
        elif isinstance(path, str):
            path_str = path
            ptr = _pointer_backend_instance(
                path_str,
                pointer_cls=resolved_backend,
            )
        elif isinstance(path, PointerBackend):
            if isinstance(path, resolved_backend):
                path_str = str(path)
                ptr = path
            else:
                raise InvalidJSONPointer(
                    "JSONPointer backend mismatch: "
                    f"required backend is {resolved_backend.__name__} but field uses "
                    f"{path.__class__.__name__}"
                )
        else:  # pragma: no cover
            assert_never(path)

        # Build it
        obj: Self = str.__new__(cls, path_str)

        # Try to reuse the type parameters (type checkers already enforce covariance)
        if isinstance(path, JSONPointer):
            obj._type = path._type
        else:
            obj._type = type_param

        # Reuse pointer backends when provided directly or via JSONPointer.
        obj._ptr = cast(P_co, ptr)

        return obj

    @classmethod
    def __get_pydantic_core_schema__(
        cls, source_type: type[Self], handler: GetCoreSchemaHandler
    ) -> cs.CoreSchema:
        type_param, concrete_backend = cls._parse_pointer_type_args(
            *get_args(source_type)
        )
        validator_function = partial(
            cls._validator,
            type_param=type_param,
            concrete_backend=concrete_backend,
        )
        return cs.no_info_after_validator_function(
            function=validator_function,
            schema=cs.union_schema(
                [
                    cs.is_instance_schema(JSONPointer),
                    cs.str_schema(strict=True),
                    cs.is_instance_schema(PointerBackend),
                ]
            ),
            metadata={  # wire to the json_schema
                "type_param": type_param,
                "pointer_backend_param": concrete_backend,  # NOTE: enable customization
            },
        )

    @classmethod
    def __get_pydantic_json_schema__(
        cls, schema: cs.CoreSchema, handler: GetJsonSchemaHandler
    ) -> JsonSchemaValue:

        pointer_backend: type[PointerBackend]
        pointer_backend_param = schema.get("metadata", {}).get("pointer_backend_param")
        if isinstance(pointer_backend_param, TypeVar):
            pointer_backend = cls._resolve_runtime_backend_param(pointer_backend_param)
        else:
            pointer_backend = pointer_backend_param

        if pointer_backend is DEFAULT_POINTER_CLS:
            pointer_format = "json-pointer"
            pointer_description = "JSON Pointer (RFC 6901) string"
        else:
            pointer_format = "x-json-pointer"
            pointer_description = "JSON Pointer string (custom backend syntax)"

        json_schema = handler(schema)
        json_schema.update(
            {
                "type": "string",
                "format": pointer_format,
                "description": pointer_description,  # NOTE: let it be overridable
            }
        )

        # enrich with json schema of type param
        type_param = schema.get("metadata", {}).get("type_param")
        json_schema["x-pointer-type-schema"] = _cached_adapter(type_param).json_schema()
        return json_schema

    @classmethod
    def _parse_pointer_type_args(
        cls, *args: TypeForm[Any]
    ) -> tuple[TypeForm[Any], type[PointerBackend] | TypeVar]:
        """Validate the JSONPointer's parameter tuple, e.g. `(JSONValue, DotPointer)` for `JSONPointer[JSONValue, DotPointer]`."""
        if not args:
            raise TypeError(f"{cls} requires at least one type parameter")
        unverified_typeform = args[0]
        unverified_bound_backend = args[1] if len(args) > 1 else DEFAULT_POINTER_CLS

        backend_param = cls._resolve_backend_type_param(unverified_bound_backend)
        type_param = _validate_typeform(unverified_typeform, InvalidJSONPointer)

        return type_param, backend_param

    @staticmethod
    def _resolve_backend_type_param(
        backend_param: object,
    ) -> type[PointerBackend] | TypeVar:
        """
        Validate the backend generic argument before runtime resolution.

        Arguments:
            backend_param: Raw second generic argument from
                `JSONPointer[T, Backend]`.

        Returns:
            A backend class or unresolved `TypeVar`.

        Raises:
            InvalidJSONPointer: If the backend argument is neither a class nor
                a `TypeVar`.
        """
        if isinstance(backend_param, TypeVar):
            return backend_param
        if not isinstance(backend_param, type):
            raise InvalidJSONPointer(
                f"JSONPointer backend parameter {backend_param!r} must be a class or TypeVar"
            )
        return cast(type[PointerBackend], backend_param)

    @classmethod
    def _resolve_runtime_backend_param(
        cls,
        backend_param: type[PointerBackend] | TypeVar,
    ) -> type[PointerBackend]:
        """
        Resolve a backend parameter to a concrete runtime backend class.

        Arguments:
            backend_param: Backend class or backend `TypeVar`.

        Returns:
            A concrete `PointerBackend` class.

        Raises:
            InvalidJSONPointer: If an unspecialized backend `TypeVar` cannot be
                resolved to a concrete default backend.
        """
        if not isinstance(backend_param, TypeVar):
            return backend_param
        return cls._resolve_runtime_backend_typevar(backend_param)

    @classmethod
    def _resolve_runtime_backend_typevar(
        cls,
        backend_typevar: TypeVar,
    ) -> type[PointerBackend]:
        """
        Resolve an unspecialized backend `TypeVar` using its default.

        Arguments:
            backend_typevar: Backend `TypeVar` from the generic parameter list.

        Returns:
            A concrete `PointerBackend` class.

        Raises:
            InvalidJSONPointer: If the `TypeVar` has no usable default backend.
        """
        # Only TypeVar defaults are used for unspecialized backend TypeVars.
        try:
            has_default = backend_typevar.has_default()
        except AttributeError:  # Py3.12
            has_default = False
        if has_default:
            default_candidate = getattr(backend_typevar, "__default__")
            default_backend = cls._coerce_runtime_backend_candidate(default_candidate)
            if default_backend is not None:
                return default_backend

        raise InvalidJSONPointer(
            "JSONPointer backend TypeVar must define a default backend "
            "or be specialized with a concrete backend type"
        )

    @classmethod
    def _coerce_runtime_backend_candidate(
        cls,
        candidate: object,
    ) -> type[PointerBackend] | None:
        """
        Coerce a potential default backend candidate into a usable class.

        Arguments:
            candidate: Runtime object drawn from a backend `TypeVar` default.

        Returns:
            A concrete `PointerBackend` class, or `None` if the candidate is
            not usable as a runtime backend.
        """
        if isinstance(candidate, TypeVar):
            return cls._resolve_runtime_backend_typevar(candidate)
        if not isinstance(candidate, type):
            return None
        if candidate is PointerBackend or isabstract(candidate):
            return None
        return candidate

    def _validate_target(self, target: object) -> T_co:
        """
        Validate a resolved or replacement value against this pointer's type.

        Arguments:
            target: Candidate value to validate strictly against `T`.

        Returns:
            The validated value, typed as `T`.

        Raises:
            PatchConflictError: If `target` does not conform to `T`.
        """
        try:
            return self._adapter.validate_python(target, strict=True)
        except ValidationError as e:
            raise PatchConflictError(
                f"expected target type {self.type_param} for pointer {str(self)!r}, got: {type(target)}"
            ) from e

    def _validate_replacement(self, value: object) -> JSONValue:
        """
        Validate a replacement value for pointer-backed mutation.

        Arguments:
            value: Candidate value to write at this pointer.

        Returns:
            A strictly validated JSON value.

        Raises:
            PatchConflictError: If `value` does not conform to this pointer's
                type parameter or is not a valid `JSONValue`.
        """
        value_T = self._validate_target(target=value)
        try:
            return _validate_JSONValue(value_T)
        except ValidationError as e:
            raise PatchConflictError(f"value {value!r} is not a valid JSONValue") from e

    # Constructor - for convenience

    @overload
    @classmethod
    def parse(
        cls,
        path: str | Self | PointerBackend,
        *,
        backend: type[P_parse] | None = None,
    ) -> "JSONPointer[JSONValue, P_parse]": ...

    @overload
    @classmethod
    def parse(
        cls,
        path: str | Self | PointerBackend,
        *,
        type_param: TypeForm[T_parse],
        backend: type[P_parse] | None = None,
    ) -> "JSONPointer[T_parse, P_parse]": ...

    @classmethod
    def parse(
        cls,
        path: str | Self | PointerBackend,
        *,
        type_param: TypeForm[Any] | object = _Nothing,
        backend: type[PointerBackend] | None = None,
    ) -> "JSONPointer[Any, PointerBackend]":
        """
        Parse a pointer string or instance using Pydantic validation.

        Arguments:
            path: Pointer string, parsed pointer, or pointer backend instance.
            type_param: Type enforced when the pointer is exercised.
            backend: Optional concrete backend class. When omitted, the built-in
                RFC 6901 backend is used.

        Returns:
            A validated `JSONPointer` instance.

        Raises:
            InvalidJSONPointer: If the pointer string, backend, or generic
                parameters are invalid.

        Notes:
            `type_param` technically places the covariant `T` parameter in an
            input position, which would normally be an unsound public API
            shape. That tradeoff is intentional here because `parse()` is only
            a convenience constructor around Pydantic validation. Normal
            construction happens through Pydantic on an already-specialized
            `JSONPointer[...]` type, so callers are not meant to treat
            `parse()` as the primary semantic surface for consuming `T`.
        """
        resolved_type_param = (
            JSONValue if type_param is _Nothing else cast(TypeForm[Any], type_param)
        )

        pointer_args: tuple[TypeForm[Any], ...]
        if backend is None:
            pointer_args = (resolved_type_param,)
        else:
            pointer_args = (resolved_type_param, backend)
        validated_type, validated_backend = cls._parse_pointer_type_args(*pointer_args)

        if backend is None:
            adapter = _cached_adapter(
                JSONPointer[validated_type]  # type: ignore[valid-type]
            )
        else:
            adapter = _cached_adapter(
                JSONPointer[validated_type, validated_backend]  # type: ignore[valid-type]
            )
        return adapter.validate_python(path)

    # Parse-time helpers

    def is_parent_of(self, other: str) -> bool:
        """
        Check whether this pointer is a strict parent of `other`.

        `other` may be a JSONPointer or a pointer string; strings are parsed using this pointer's syntax.

        Root is treated as a parent of all paths except itself.

        Raises InvalidJSONPointer if comparison is called with an `other` pointer with different or invalid syntax.
        """
        if isinstance(other, JSONPointer) and not isinstance(
            other._ptr, type(self._ptr)
        ):
            raise InvalidJSONPointer(
                f"Other pointer {other._ptr!r} has incompatible syntax with {self!r}"
            )
        other_ptr = _pointer_backend_instance(other, pointer_cls=self._ptr.__class__)

        # Strict parentage only
        if self == str(other_ptr):
            return False

        return other_ptr.parts[: len(self.parts)] == self.parts

    def is_child_of(self, other: str) -> bool:
        """
        Check whether this pointer is a strict child of `other`.

        `other` may be a JSONPointer or a pointer string; strings are parsed using this pointer's syntax.

        Root is treated as a parent of all paths except itself.

        Raises InvalidJSONPointer if comparison is called with an `other` pointer with different or invalid syntax.
        """
        # NOTE: Document which of these public helper methods work only with RFC6901
        if isinstance(other, JSONPointer) and not isinstance(
            other._ptr, type(self._ptr)
        ):
            raise InvalidJSONPointer(
                f"Other pointer {other._ptr!r} has incompatible syntax with {self!r}"
            )
        other_ptr = _pointer_backend_instance(other, pointer_cls=self._ptr.__class__)

        # Strict parentage only
        if self == str(other_ptr):
            return False

        return self.parts[: len(other_ptr.parts)] == other_ptr.parts

    # Runtime helpers

    def is_valid_type(self, target: object) -> bool:
        """
        Return `True` if `target` conforms to this pointer's type.

        Arguments:
            target: Candidate value to validate.

        Returns:
            `True` when `target` validates strictly against `T`,
            otherwise `False`.
        """
        try:
            self._adapter.validate_python(target, strict=True)
            return True
        except ValidationError:
            return False

    def get(self, doc: JSONValue) -> T_co:
        """
        Resolve this pointer against `doc` and return the target value (type-gated).

        Arguments:
            doc: Target JSON document.

        Returns:
            The resolved value, validated against `T`.

        Raises:
            PatchConflictError: If the target does not exist, or it is not type `T`.
        """
        if classify_state(self._ptr, doc) is TargetState.MISSING:
            raise PatchConflictError(f"target {str(self)!r} does not exist")

        # Choice: always defer to the PointerBackend implementation for pointer resolution.
        # Why: Don't reinvent the wheel (and maintain it). Plus, give more power to custom PointerBackends.
        try:
            target = self._ptr.resolve(doc)
        except Exception as e:
            raise PatchConflictError(f"path {str(self)!r} not found: {e}") from e
        val = self._validate_target(target)
        return val

    def is_gettable(self, doc: JSONValue) -> bool:
        """
        Return `True` if `get(doc)` would succeed.

        Arguments:
            doc: Target JSON document.

        Returns:
            `True` if the pointer resolves to an existing value of type
            `T`, otherwise `False`.
        """
        try:
            self.get(doc)
        except PatchConflictError:
            return False
        else:
            return True

    def add(self, doc: JSONValue, value: object) -> JSONValue:
        """
        RFC 6902 add (type-gated).

        Arguments:
            doc: Target JSON document.
            value: Value to add at this path, validated against `T`.

        Returns:
            The updated document.

        Raises:
            PatchConflictError: If the target does not exist, if the target is not type `T`,
                or if the value being added is not type `T`.
        """
        target = self._validate_replacement(value)

        match classify_state(self._ptr, doc):
            case TargetState.MISSING:
                return target
            case TargetState.ROOT:
                self._validate_target(doc)
                return target
            case TargetState.PARENT_NOT_FOUND:
                raise PatchConflictError(
                    f"cannot add value at {str(self)!r} because parent does not exist"
                )
            case TargetState.PARENT_NOT_CONTAINER:
                raise PatchConflictError(
                    f"cannot add value at {str(self)!r} because parent is not a container"
                )
            case TargetState.ARRAY_INDEX_APPEND | TargetState.ARRAY_INDEX_AT_END:
                array = cast(JSONArray[JSONValue], self.parent_ptr.resolve(doc))
                array.append(target)
                return doc
            case TargetState.ARRAY_INDEX_OUT_OF_RANGE:
                raise PatchConflictError(
                    f"cannot add value at {str(self)!r} because array index {self.parts[-1]!r} is out of range"
                )
            case TargetState.OBJECT_KEY_MISSING:
                object = cast(JSONObject[JSONValue], self.parent_ptr.resolve(doc))
                key = self.parts[-1]
                object[key] = target
                return doc
            case (
                TargetState.ARRAY_KEY_INVALID
                | TargetState.VALUE_PRESENT_AT_NEGATIVE_ARRAY_INDEX
            ):
                raise PatchConflictError(
                    f"cannot add value at {str(self)!r} because key {self.parts[-1]!r} is an invalid array index"
                )
            case TargetState.VALUE_PRESENT:
                container = cast(JSONContainer[JSONValue], self.parent_ptr.resolve(doc))
                token = self.parts[-1]
                if _is_object(container):
                    self._validate_target(container[token])
                    container[token] = target
                    return doc
                else:
                    container.insert(int(token), target)
                    return doc
            case _ as unreachable:
                assert_never(unreachable)

    def is_addable(
        self,
        doc: JSONValue,
        value: object = _Nothing,
    ) -> bool:
        """
        Return `True` if RFC 6902 `add` would succeed for this document.

        Arguments:
            doc: Target JSON document.
            value: Optional value that would be written at this pointer. When
                provided, it must conform to `T` and to `JSONValue`.

        Returns:
            `True` if add semantics would succeed, otherwise `False`.
        """
        if value is not _Nothing:
            try:
                self._validate_replacement(value)
            except PatchConflictError:
                return False

        match classify_state(self._ptr, doc):
            case TargetState.MISSING:
                return True
            case TargetState.ROOT:
                return self.is_valid_type(doc)
            case TargetState.VALUE_PRESENT:
                container = cast(JSONContainer[JSONValue], self.parent_ptr.resolve(doc))
                token = self.parts[-1]
                if _is_object(container):
                    return self.is_valid_type(container[token])
                return True  # list insert always valid
            case (
                TargetState.ARRAY_INDEX_APPEND
                | TargetState.ARRAY_INDEX_AT_END
                | TargetState.OBJECT_KEY_MISSING
            ):
                return True
            case _:
                return False

    def remove(self, doc: JSONValue) -> JSONValue:
        """
        RFC 6902 remove (type-gated). Removal of the root returns `MISSING`.

        Arguments:
            doc: Target JSON document.

        Returns:
            The updated document.

        Raises:
            PatchConflictError: If the target does not exist, or it is not type `T`.
        """
        match classify_state(self._ptr, doc):
            case TargetState.MISSING:
                raise PatchConflictError(f"target {str(self)!r} does not exist")
            case TargetState.ROOT:
                # Choice: Removal of root returns MISSING.
                # Why: Root removal is document deletion, not replacement with JSON null.
                self._validate_target(doc)
                return cast(JSONValue, MISSING)
            case TargetState.PARENT_NOT_FOUND:
                raise PatchConflictError(
                    f"cannot remove value at {str(self)!r} because parent does not exist"
                )
            case TargetState.PARENT_NOT_CONTAINER:
                raise PatchConflictError(
                    f"cannot remove value at {str(self)!r} because parent is not a container"
                )
            case TargetState.ARRAY_INDEX_APPEND:
                raise PatchConflictError(
                    f"cannot remove value at {str(self)!r} because '-' indicates append position"
                )
            case TargetState.ARRAY_INDEX_OUT_OF_RANGE | TargetState.ARRAY_INDEX_AT_END:
                raise PatchConflictError(
                    f"cannot remove value at {str(self)!r} because array index {self.parts[-1]!r} is out of range"
                )
            case TargetState.OBJECT_KEY_MISSING:
                raise PatchConflictError(
                    f"cannot remove value at {str(self)!r} because key {self.parts[-1]!r} is missing from object"
                )
            case (
                TargetState.ARRAY_KEY_INVALID
                | TargetState.VALUE_PRESENT_AT_NEGATIVE_ARRAY_INDEX
            ):
                raise PatchConflictError(
                    f"cannot remove value at {str(self)!r} because key {self.parts[-1]!r} is an invalid array index"
                )
            case TargetState.VALUE_PRESENT:
                container = cast(JSONContainer[JSONValue], self.parent_ptr.resolve(doc))
                token = self.parts[-1]
                key = int(token) if _is_array(container) else token
                self._validate_target(container[key])  # type: ignore[index]
                del container[key]  # type: ignore[arg-type]
                return doc
            case _ as unreachable:
                assert_never(unreachable)

    def is_removable(self, doc: JSONValue) -> bool:
        """
        Return `True` if RFC 6902 `remove` would succeed for this document.

        Arguments:
            doc: Target JSON document.

        Returns:
            `True` if remove semantics would succeed, otherwise `False`.
        """
        return self.is_gettable(doc)

    @override
    def __repr__(self) -> str:
        type_repr = (
            self._type.__name__ if isinstance(self._type, type) else repr(self._type)
        )
        return f"{self.__class__.__name__}[{type_repr}]({str(self)!r})"