didactic 0.3.0__tar.gz → 0.3.2__tar.gz

{didactic-0.3.0 → didactic-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: didactic
-Version: 0.3.0
+Version: 0.3.2
 Summary: Pydantic-class API on top of panproto: GATs, lenses, and VCS.
 Project-URL: Homepage, https://github.com/panproto/didactic
 Project-URL: Repository, https://github.com/panproto/didactic
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.14
 Requires-Dist: annotated-types>=0.7
-Requires-Dist: panproto>=0.43
+Requires-Dist: panproto>=0.43.1
 Description-Content-Type: text/markdown
 
 # didactic

{didactic-0.3.0 → didactic-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "didactic"
-version = "0.3.0"
+version = "0.3.2"
 description = "Pydantic-class API on top of panproto: GATs, lenses, and VCS."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -22,7 +22,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "panproto>=0.43",
+    "panproto>=0.43.1",
     "annotated-types>=0.7",
 ]
 

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/_self_describing.py

@@ -31,12 +31,9 @@ didactic.migrations._fingerprint.structural_fingerprint : the underlying address
 
 # Cross-translation between ``FieldValue`` and ``JsonValue`` shapes
 # in the schema-URI registry layer.
-# Tracked in panproto/didactic#1.
-# pyright: reportArgumentType=false, reportReturnType=false
-
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
     from didactic.models._model import Model
@@ -67,7 +64,7 @@ def schema_uri(cls: type[Model]) -> str:
 
 
 def embed_schema_uri(instance: Model) -> JsonObject:
-    """Return ``instance.model_dump()`` with a ``$schema`` URI prepended.
+    """Return the JSON-shape dump of ``instance`` with a ``$schema`` URI prepended.
 
     Parameters
     ----------
@@ -77,16 +74,23 @@ def embed_schema_uri(instance: Model) -> JsonObject:
     Returns
     -------
     dict
-        The dump dict, with ``"$schema"`` set to the Model's
+        The JSON-safe dump dict, with ``"$schema"`` set to the Model's
         canonical URI as the first key.
 
     Notes
     -----
+    Routes through ``model_dump_json`` (not the bare ``model_dump``)
+    so any nested ``tuple[Embed[T], ...]`` or ``dict[str, Embed[T]]``
+    fields get the JSON-safe walk; the returned dict is always
+    serialisable with ``json.dumps``.
+
     A consumer that knows how to resolve ``didactic://v1/<fp>`` URIs
     can fetch the Theory by fingerprint and validate the payload
     without knowing the original Python class.
     """
-    payload = instance.model_dump()
+    import json  # noqa: PLC0415
+
+    payload = cast("JsonObject", json.loads(instance.model_dump_json()))
     return {"$schema": schema_uri(type(instance)), **payload}
 
 
@@ -188,6 +192,9 @@ def validate_with_uri_lookup(
         raise KeyError(msg)
 
     uri = payload["$schema"]
+    if not isinstance(uri, str):
+        msg = "validate_with_uri_lookup: $schema value must be a string"
+        raise TypeError(msg)
     cls = registry.lookup(uri)
     if cls is None:
         msg = f"validate_with_uri_lookup: no registered model for URI {uri!r}"

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/api.py

@@ -68,14 +68,13 @@ from didactic.types import _types_lib as types
 from didactic.vcs._backref import ModelPool, resolve_backrefs
 from didactic.vcs._repo import Repository
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"
 
 #: Conventional namespace for lens utilities (`dx.lens.identity(...)`,
 #: `dx.lens.Lens`, etc.). The ``lens`` name doubles as a decorator
 #: (``@dx.lens(A, B)``) and as a module-style namespace. The attributes
 #: are bound by ``_LensNamespace.__init__`` in :mod:`didactic.lenses._lens`.
 
-
 __all__ = [
     "DEFAULT_CONFIG",
     "Axiom",

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/axioms/_axiom_enforcement.py

@@ -26,7 +26,6 @@ if TYPE_CHECKING:
     from didactic.axioms._axioms import Axiom
     from didactic.types._typing import FieldValue, JsonValue
 
-
 # A panproto Expr ``to_dict()`` AST node is one of any JsonValue-shaped
 # payload — at the leaves of dispatch we narrow with ``match`` /
 # ``isinstance``. Using ``JsonValue`` (rather than the narrower

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/cli/_cli.py

@@ -2,7 +2,6 @@
 # ``.breaking`` shape is a ``JsonValue`` union; pyright can't narrow
 # the iteration target without per-branch ``isinstance``. Tracked in
 # panproto/didactic#1.
-# pyright: reportGeneralTypeIssues=false, reportOptionalIterable=false, reportUnknownVariableType=false
 """``didactic`` CLI front-end.
 
 Subcommands
@@ -117,6 +116,11 @@ def _resolve_model(spec: str) -> type[Model]:
     return cls
 
 
+# Public re-export so tests can introspect the resolver without tripping
+# pyright's reportPrivateUsage.
+resolve_model = _resolve_model
+
+
 def _cmd_schema_show(args: argparse.Namespace) -> int:
     cls = _resolve_model(args.model)
     from didactic.migrations._fingerprint import structural_fingerprint  # noqa: PLC0415
@@ -190,8 +194,10 @@ def _cmd_check_breaking(args: argparse.Namespace) -> int:
         print(f"compatible: {args.old} -> {args.new}")
         return 0
     print(f"BREAKING: {args.old} -> {args.new}")
-    for change in report.get("breaking", []):
-        print(f"  {change}")
+    breaking = report.get("breaking")
+    if isinstance(breaking, list):
+        for change in breaking:
+            print(f"  {change}")
     return 2
 
 
@@ -235,7 +241,6 @@ _SUBCOMMANDS = {
     "version": _cmd_version,
 }
 
-
 __all__ = [
     "main",
 ]

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/codegen/_json_schema.py

@@ -1,7 +1,6 @@
 # ``annotated_metadata`` lives on ``spec.extras`` as ``Opaque`` and
 # the per-marker iteration takes the marker as an opaque value to
 # duck-type. Tracked in panproto/didactic#1.
-# pyright: reportUnknownVariableType=false, reportUnknownArgumentType=false
 """JSON Schema (Draft 2020-12) generation from a Model class.
 
 The single user-facing entry point is
@@ -147,7 +146,13 @@ def _schema_for_field(spec: FieldSpec) -> JsonSchemaProperty:
     annotation = spec.annotation
     out: dict[str, JsonValue] = {}
 
-    type_str, format_str = _PRIMITIVE_TYPE_MAP.get(annotation, ("string", None))
+    # The map is keyed on bare ``type`` instances (``str``, ``int``,
+    # etc.); ``TypeVar`` / ``ForwardRef`` annotations fall through to
+    # the ``("string", None)`` default.
+    if isinstance(annotation, type):
+        type_str, format_str = _PRIMITIVE_TYPE_MAP.get(annotation, ("string", None))
+    else:
+        type_str, format_str = "string", None
     out["type"] = type_str
     if format_str is not None:
         out["format"] = format_str
@@ -174,7 +179,7 @@ def _schema_for_field(spec: FieldSpec) -> JsonSchemaProperty:
     # as ``Opaque`` (a marker Protocol); we narrow with isinstance.
     metadata = extras.get("annotated_metadata", ()) or ()
     if isinstance(metadata, (tuple, list)):
-        for entry in metadata:
+        for entry in cast("tuple[Opaque, ...] | list[Opaque]", metadata):
             _apply_annotated_constraint(out, entry)
 
     return cast("JsonSchemaProperty", out)

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/codegen/_write.py

@@ -17,9 +17,6 @@ Examples
 
 # Defensive ``isinstance(payload, bytes)`` on a parameter pyright
 # narrows to ``bytes`` already; runtime callers may bypass.
-# Tracked in panproto/didactic#1.
-# pyright: reportUnnecessaryIsInstance=false
-
 from __future__ import annotations
 
 from pathlib import Path
@@ -96,11 +93,8 @@ def write(
                 ext=ext,
             )
             path = out_path / filename_str
-            payload = model.emit_as(target)  # type: ignore[attr-defined]
-            payload_bytes = (
-                payload if isinstance(payload, bytes) else str(payload).encode("utf-8")
-            )
-            path.write_bytes(payload_bytes)
+            payload = model.emit_as(target)
+            path.write_bytes(payload)
             written[f"{target}/{model.__name__}"] = path.resolve()
     return written
 

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/codegen/source.py

@@ -29,14 +29,9 @@ didactic.codegen.io : instance-level codecs.
 didactic.Model.emit_as : the unified entry point.
 """
 
-# ``schema: object`` (panproto handle carve-out) handed back to
-# panproto's ``emit(schema: Schema)``.
-# Tracked in panproto/didactic#1.
-# pyright: reportArgumentType=false
-
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -112,7 +107,10 @@ def emit(schema: object, *, protocol: str) -> bytes:
     import panproto  # noqa: PLC0415
 
     registry = panproto.AstParserRegistry()
-    return registry.emit(protocol, schema)
+    # ``schema`` is typed ``object`` in the public signature (carve-out
+    # for the opaque panproto handle); the runtime contract is that it
+    # came from a previous ``parse`` call and is a real ``Schema``.
+    return registry.emit(protocol, cast("panproto.Schema", schema))
 
 
 def parse(source: bytes, *, protocol: str, file_path: str = "<source>") -> object:

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/fields/_computed.py

@@ -35,7 +35,6 @@ if TYPE_CHECKING:
 
     from didactic.types._typing import FieldValue
 
-
 _COMPUTED_MARKER_ATTR = "__didactic_computed__"
 
 

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/fields/_derived.py

@@ -47,7 +47,6 @@ didactic.computed : evaluated every read; not cached.
 # ``_`` prefix is conventional for "implementation detail of the
 # Model layer"; the derived-decorator integration is part of that
 # layer. Tracked in panproto/didactic#1.
-# pyright: reportPrivateUsage=false
 
 from __future__ import annotations
 
@@ -90,18 +89,25 @@ def derived(fn: Callable[..., FieldValue]) -> property:
     >>> Box(w=3, h=4).area
     12
     """
-    fn.__didactic_derived__ = True  # type: ignore[attr-defined]
+    # ``__didactic_derived__`` is a marker attribute consumed by
+    # ``derived_field_names`` to discover wrapped derived methods. The
+    # function-object protocol allows arbitrary attribute writes at
+    # runtime; pyright models ``Callable`` as opaque so we set through
+    # ``setattr`` to keep the boundary explicit.
+    setattr(fn, "__didactic_derived__", True)  # noqa: B010
     name = fn.__name__
 
     def _getter(self: Model) -> FieldValue:
-        cache = self._derived_cache
+        cache = cast("dict[str, FieldValue]", getattr(self, "_derived_cache"))  # noqa: B009
         if name not in cache:
             cache[name] = fn(self)
-        return cast("FieldValue", cache[name])
+        return cache[name]
 
     prop = property(_getter)
-    prop.fget.__didactic_derived__ = True  # type: ignore[union-attr]
-    prop.fget.__wrapped_name__ = name  # type: ignore[union-attr]
+    fget = prop.fget
+    if fget is not None:
+        setattr(fget, "__didactic_derived__", True)  # noqa: B010
+        setattr(fget, "__wrapped_name__", name)  # noqa: B010
     return prop
 
 

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/fields/_fields.py

@@ -29,11 +29,14 @@ didactic.types._types : the translation primitives FieldSpec uses.
 didactic.models._meta : the metaclass that consumes FieldSpec.
 """
 
-# ``extras`` is the project's ``Mapping[str, Opaque]`` and pyright
-# doesn't carry the value-type through ``dict(extras)``.
-# Tracked in panproto/didactic#1.
-# pyright: reportUnknownVariableType=false
-
+# ``field()`` uses the field-specifier overload pattern from
+# ``CONTRIBUTING.md`` carve-out 1: typed overloads return ``T`` so
+# call sites like ``email: str = dx.field(description="...")`` type-check,
+# while the implementation returns ``Field``. Pyright in strict mode
+# rejects this inconsistency between the unconstrained-``T`` overload
+# returns and the concrete ``Field`` impl return; no structural fix
+# preserves the surface ergonomics. Confined to this file.
+# pyright: reportInconsistentOverload=false
 from __future__ import annotations
 
 from dataclasses import dataclass
@@ -43,8 +46,11 @@ from typing import (
     Annotated,
     Any,
     Final,
+    ForwardRef,
     Literal,
     Self,
+    TypeVar,
+    cast,
     get_args,
     get_origin,
     overload,
@@ -53,7 +59,7 @@ from typing import (
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
 
-    from didactic.types._types import TypeTranslation
+    from didactic.types._types import TypeForm, TypeTranslation
     from didactic.types._typing import (
         DefaultOrMissing,
         FieldValue,
@@ -110,7 +116,6 @@ MISSING: Final[_Missing] = _Missing()
 #: ``isinstance(value, MissingType)`` without crossing a private boundary.
 MissingType = _Missing
 
-
 # ---------------------------------------------------------------------------
 # The Field descriptor class
 # ---------------------------------------------------------------------------
@@ -235,9 +240,9 @@ def field(
     usage_mode: Literal["readwrite", "computed", "materialised"] = ...,
     extras: Mapping[str, Opaque] | None = ...,
 ) -> Any: ...  # documented escape hatch for required-with-metadata fields
-def field(  # pyright: ignore[reportInconsistentOverload]
+def field(
     *,
-    default: DefaultOrMissing = MISSING,
+    default: FieldValue | _Missing = MISSING,
     default_factory: Callable[[], FieldValue] | None = None,
     converter: Callable[[FieldValue], FieldValue] | None = None,
     alias: str | None = None,
@@ -370,7 +375,7 @@ class FieldSpec:
     """
 
     name: str
-    annotation: type
+    annotation: TypeForm | TypeVar | ForwardRef
     translation: TypeTranslation
     default: DefaultOrMissing = MISSING
     default_factory: Callable[[], FieldValue] | None = None
@@ -382,7 +387,9 @@ class FieldSpec:
     nominal: bool = False
     usage_mode: Literal["readwrite", "computed", "materialised"] = "readwrite"
     axioms: tuple[str, ...] = ()
-    extras: Mapping[str, Opaque] = _dc_field(default_factory=dict)
+    extras: Mapping[str, Opaque] = _dc_field(
+        default_factory=lambda: cast("dict[str, Opaque]", {})
+    )
 
     @property
     def is_required(self) -> bool:

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/fields/_unions.py

@@ -2,7 +2,6 @@
 # narrower payload type; the runtime accepts the base shape too. The
 # ``Literal[...]`` discriminator extraction goes through annotation
 # walking that pyright can't follow. Tracked in panproto/didactic#1.
-# pyright: reportArgumentType=false, reportIncompatibleMethodOverride=false, reportUnnecessaryIsInstance=false
 """Tagged (discriminated) unions over [Model][didactic.api.Model] subclasses.
 
 Pydantic-shaped discriminated unions: declare a base class with a
@@ -49,13 +48,15 @@ didactic.models._meta.ModelMeta : the metaclass; unchanged.
 from __future__ import annotations
 
 import annotationlib
-from typing import TYPE_CHECKING, ClassVar, Literal, Self, get_args, get_origin
+from typing import TYPE_CHECKING, ClassVar, Literal, Self, cast, get_args, get_origin
 
 from didactic.fields._validators import ValidationError, ValidationErrorEntry
 from didactic.models._model import Model
 
 if TYPE_CHECKING:
-    from didactic.types._typing import FieldValue, JsonObject, Opaque
+    from collections.abc import Mapping
+
+    from didactic.types._typing import FieldValue, JsonValue, Opaque
 
 
 class TaggedUnion(Model):
@@ -173,7 +174,7 @@ class TaggedUnion(Model):
             root.__variants__[value] = cls
 
     @classmethod
-    def model_validate(cls, payload: JsonObject) -> Self:
+    def model_validate(cls, payload: Mapping[str, FieldValue | JsonValue]) -> Self:
         """Dispatch on the discriminator and validate as the matched variant.
 
         Parameters
@@ -212,7 +213,10 @@ class TaggedUnion(Model):
             )
             raise ValidationError(entries=(entry,), model=cls)
 
-        value = payload[disc]
+        # ``payload`` is widened to ``Mapping[str, FieldValue | JsonValue]``
+        # to match the base ``model_validate`` signature; the discriminator
+        # value is recorded in ``__variants__`` under a ``FieldValue`` key.
+        value = cast("FieldValue", payload[disc])
         variant = cls.__variants__.get(value)
         if variant is None:
             entry = ValidationErrorEntry(
@@ -225,22 +229,24 @@ class TaggedUnion(Model):
             )
             raise ValidationError(entries=(entry,), model=cls)
 
-        return variant.model_validate(payload)  # type: ignore[return-value]
+        # ``variant`` is a concrete subclass of ``cls``; the return type
+        # is bound to ``Self`` of the union root by design (the dispatch
+        # contract is "give me a value of *some* variant").
+        return cast("Self", variant.model_validate(payload))
 
 
 def _find_union_root(cls: type[TaggedUnion]) -> type[TaggedUnion] | None:
     """Walk MRO to find the nearest ancestor with a non-None ``__discriminator__``."""
     for klass in cls.__mro__[1:]:
         if (
-            isinstance(klass, type)
-            and issubclass(klass, TaggedUnion)
+            issubclass(klass, TaggedUnion)
             and klass.__dict__.get("__discriminator__") is not None
         ):
             return klass
     return None
 
 
-def _literal_values(annotation: type) -> tuple[FieldValue, ...]:
+def _literal_values(annotation: Opaque) -> tuple[FieldValue, ...]:
     """Extract the values from a ``Literal[...]`` annotation.
 
     Returns an empty tuple when the annotation isn't a Literal.

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/fields/_validators.py

@@ -22,9 +22,6 @@ didactic.models._meta : the metaclass that records validators on the class.
 
 # Stamps ``__didactic_validator__`` onto a function; pyright won't
 # let arbitrary attribute assignment on a ``FunctionType``.
-# Tracked in panproto/didactic#1.
-# pyright: reportFunctionMemberAccess=false
-
 from __future__ import annotations
 
 from dataclasses import dataclass, field
@@ -150,8 +147,14 @@ def validates(
     def decorator(
         fn: Callable[..., FieldValue],
     ) -> Callable[..., FieldValue]:
-        # mark the function so the metaclass can find it
-        fn.__didactic_validator__ = {"fields": field_names, "mode": mode}
+        # Mark the function so the metaclass can find it. ``setattr``
+        # writes through the function-object's ``__dict__`` without
+        # tripping pyright's narrowed FunctionType view.
+        setattr(  # noqa: B010
+            fn,
+            "__didactic_validator__",
+            {"fields": field_names, "mode": mode},
+        )
         return fn
 
     return decorator

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/lenses/_dependent_lens.py

@@ -42,14 +42,9 @@ didactic.Lens : the schema-fixed lens type.
 didactic.Iso : the isomorphism subcase.
 """
 
-# ``ProtolensChain.instantiate(src, tgt)`` accepts the project's
-# ``Schema`` Protocol; pyright sees the panproto stub class instead.
-# Tracked in panproto/didactic#1.
-# pyright: reportArgumentType=false
-
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
     import panproto
@@ -280,7 +275,12 @@ class DependentLens:
         panproto.LensError
             If the chain cannot be instantiated against ``schema``.
         """
-        return self._inner.instantiate(schema, protocol)
+        # ``ProtolensChain.instantiate``'s shipped stub claims
+        # ``(src: Schema, tgt: Schema)``; the runtime is
+        # ``(schema, protocol)`` with the second arg being a
+        # ``panproto.Protocol``. Cast at the boundary so we type-match
+        # the stub while passing the runtime's expected value.
+        return self._inner.instantiate(schema, cast("panproto.Schema", protocol))
 
     # serialisation -------------------------------------------------
 

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/lenses/_lens.py

@@ -51,9 +51,6 @@ didactic.theory._theory : the bridge that will compile lenses to panproto.Lens.
 
 # ``lens`` doubles as a callable and a namespace (``dx.lens.identity``);
 # the namespace attributes are stamped on the function object.
-# Tracked in panproto/didactic#1.
-# pyright: reportAttributeAccessIssue=false
-
 from __future__ import annotations
 
 import functools
@@ -70,7 +67,6 @@ from didactic.types._typing import Opaque
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-
 # ---------------------------------------------------------------------------
 # Mapping (one-way)
 # ---------------------------------------------------------------------------
@@ -377,11 +373,18 @@ class _LensNamespace:
     ``dx.lens.Lens``, ``dx.lens.Iso``, ``dx.lens.Mapping``).
     """
 
+    identity: Callable[..., Iso[Opaque, Opaque]]
+    Lens: type[Lens[Opaque, Opaque, Opaque]]
+    Iso: type[Iso[Opaque, Opaque]]
+    Mapping: type[Mapping[Opaque, Opaque]]
+
     def __init__(self) -> None:
-        self.identity: Callable[..., Iso[Opaque, Opaque]] = identity
-        self.Lens: type[Lens[Opaque, Opaque, Opaque]] = Lens
-        self.Iso: type[Iso[Opaque, Opaque]] = Iso
-        self.Mapping: type[Mapping[Opaque, Opaque]] = Mapping
+        # ``identity`` is parameterised on ``A``; the namespace exposes the
+        # erased ``Opaque, Opaque`` shape since callers re-bind on use.
+        self.identity = cast("Callable[..., Iso[Opaque, Opaque]]", identity)
+        self.Lens = Lens
+        self.Iso = Iso
+        self.Mapping = Mapping
 
     def __call__[A, B](
         self, source: type[A], target: type[B]
@@ -434,7 +437,6 @@ class _LensNamespace:
 
 lens = _LensNamespace()
 
-
 __all__ = [
     "Iso",
     "Lens",

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/lenses/_testing.py

@@ -102,8 +102,8 @@ def verify_iso[A](
     _check()
 
 
-def check_lens_laws[A, B](
-    lens: Lens[A, B],
+def check_lens_laws[A, B, C](
+    lens: Lens[A, B, C],
     strategy: SearchStrategy[A],
     *,
     max_examples: int = 100,

{didactic-0.3.0 → didactic-0.3.2}/src/didactic/migrations/_diff.py

@@ -1,7 +1,6 @@
 # ``diff_and_classify`` returns a ``CompatReport`` whose ``.to_dict()``
 # we re-emit as ``JsonObject``; pyright's stub doesn't narrow the
 # panproto-side types tightly enough. Tracked in panproto/didactic#1.
-# pyright: reportReturnType=false, reportUnknownVariableType=false, reportUnknownMemberType=false, reportCallIssue=false
 """Schema diff and breaking-change detection.
 
 Two thin functions over panproto's ``diff_schemas`` and
@@ -22,9 +21,11 @@ panproto.diff_schemas : the runtime call.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol, cast
 
 if TYPE_CHECKING:
+    import panproto
+
     from didactic.models._model import Model
     from didactic.types._typing import JsonObject
 
@@ -65,7 +66,7 @@ def diff(old: type[Model], new: type[Model]) -> JsonObject:
     old_schema = schema_from_model(old)
     new_schema = schema_from_model(new)
     schema_diff = panproto.diff_schemas(old_schema, new_schema)
-    return schema_diff.to_dict()
+    return cast("JsonObject", schema_diff.to_dict())
 
 
 def classify_change(old: type[Model], new: type[Model]) -> JsonObject:
@@ -111,7 +112,24 @@ def classify_change(old: type[Model], new: type[Model]) -> JsonObject:
         schema_theory=build_theory(new),
         obj_kinds=["object"],
     )
-    compat = panproto.diff_and_classify(old_schema, new_schema, protocol)
+
+    # ``panproto.diff_and_classify`` accepts a third positional ``protocol``
+    # argument at runtime; the upstream stub still lists only two. Cast
+    # to a Protocol that exposes the runtime arity and return shape.
+    class _CompatReportLike(Protocol):
+        def to_dict(self) -> JsonObject: ...
+
+    class _DiffAndClassifyLike(Protocol):
+        def __call__(
+            self,
+            old: panproto.Schema,
+            new: panproto.Schema,
+            protocol: panproto.Protocol,
+            /,
+        ) -> _CompatReportLike: ...
+
+    diff_and_classify = cast("_DiffAndClassifyLike", panproto.diff_and_classify)
+    compat = diff_and_classify(old_schema, new_schema, protocol)
     return compat.to_dict()