didactic 0.3.1__tar.gz → 0.3.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: didactic
-Version: 0.3.1
+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.1 → didactic-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "didactic"
-version = "0.3.1"
+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.1 → didactic-0.3.2}/src/didactic/_self_describing.py

@@ -31,9 +31,6 @@ 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, cast
@@ -195,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.1 → 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.1"
+__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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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()
 
 

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/migrations/_fingerprint.py

@@ -2,7 +2,6 @@
 # back into ``JsonObject`` (``dict[str, JsonValue]``); the dict
 # invariance bites. ``_default`` narrowing on tuple inputs is
 # pyright-flagged as redundant. Tracked in panproto/didactic#1.
-# pyright: reportReturnType=false, reportArgumentType=false, reportUnnecessaryIsInstance=false
 """Stable fingerprints for didactic Theory specs.
 
 didactic stores migration registry entries by a fingerprint that is
@@ -45,12 +44,11 @@ from __future__ import annotations
 
 import hashlib
 import json
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
     from didactic.theory._theory import TheorySpec
-    from didactic.types._typing import JsonObject, JsonValue
-
+    from didactic.types._typing import JsonObject, JsonValue, Opaque
 
 # canonical placeholder for the model's own display name; chosen to be
 # unambiguous and unlikely to clash with any user-supplied identifier
@@ -89,7 +87,7 @@ def canonical_json_bytes(spec: JsonValue) -> bytes:
     ).encode("utf-8")
 
 
-def _default(obj: tuple[JsonValue, ...]) -> JsonValue:
+def _default(obj: Opaque) -> JsonValue:
     """Fallback encoder for tuples (json default would already accept them).
 
     The callback runs on every non-JSON-native value ``json.dumps``
@@ -99,7 +97,7 @@ def _default(obj: tuple[JsonValue, ...]) -> JsonValue:
     raises so the spec author sees it immediately.
     """
     if isinstance(obj, tuple):
-        return list(obj)
+        return list(cast("tuple[JsonValue, ...]", obj))
     msg = f"non-JSON-encodable value in didactic spec: {type(obj).__name__}"
     raise TypeError(msg)
 
@@ -163,7 +161,11 @@ def structural_spec(spec: JsonObject) -> JsonObject:
     if not isinstance(name, str):
         msg = "structural_spec(): spec['name'] must be a string"
         raise TypeError(msg)
-    return _replace_model_name(spec, name)
+    rewritten = _replace_model_name(spec, name)
+    if not isinstance(rewritten, dict):
+        msg = "structural_spec(): top-level rewrite must remain a dict"
+        raise TypeError(msg)
+    return rewritten
 
 
 def _replace_model_name(value: JsonValue, name: str) -> JsonValue:
@@ -209,7 +211,7 @@ def structural_fingerprint(spec: TheorySpec) -> str:
     structurally-identical Models should share one entry regardless of
     their class names.
     """
-    return fingerprint(structural_spec(spec))
+    return fingerprint(structural_spec(cast("JsonObject", spec)))
 
 
 __all__ = [

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/migrations/_synthesis.py

@@ -27,15 +27,10 @@ didactic.register_migration : the manual-authoring counterpart.
 panproto.auto_generate_lens : the runtime call.
 """
 
-# panproto's ``auto_generate_lens`` returns ``tuple[..., dict[str, object]]``
-# and we re-emit as ``tuple[JsonObject, ...]``; dict invariance bites.
-# Tracked in panproto/didactic#1.
-# pyright: reportArgumentType=false
-
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
     from didactic.models._model import Model
@@ -125,10 +120,12 @@ def synthesise_migration(
         )
 
     lens, score, proposals = result
+    # ``proposals`` comes back from panproto as ``list[dict[str, object]]``;
+    # narrow at the boundary to didactic's stricter ``JsonObject`` shape.
     return SynthesisResult(
         lens=lens,
         score=float(score),
-        proposals=tuple(proposals),
+        proposals=cast("tuple[JsonObject, ...]", tuple(proposals)),
     )
 
 

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/models/_config.py

@@ -96,7 +96,6 @@ class ModelConfig:
 DEFAULT_CONFIG = ModelConfig()
 """The configuration applied to a Model that does not specify one."""
 
-
 __all__ = [
     "DEFAULT_CONFIG",
     "ExtraPolicy",

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/models/_meta.py

@@ -5,7 +5,6 @@
 # accepts string forward refs and TypeVar instances), but pyright
 # can't follow the case split through the dataclass_transform
 # layer. Tracked in panproto/didactic#1.
-# pyright: reportArgumentType=false, reportReturnType=false, reportCallIssue=false
 """The ``ModelMeta`` metaclass: class-as-Theory derivation.
 
 ``ModelMeta`` runs at class-creation time. It reads each annotated field,
@@ -33,7 +32,7 @@ from __future__ import annotations
 import annotationlib
 import contextlib
 import sys
-from typing import TYPE_CHECKING, ForwardRef, TypeVar, dataclass_transform
+from typing import TYPE_CHECKING, ForwardRef, TypeVar, cast, dataclass_transform
 
 from didactic.axioms._axioms import collect_class_axioms
 from didactic.fields._computed import computed_field_names
@@ -44,10 +43,12 @@ from didactic.fields._fields import (
     field,
     read_annotated_metadata,
 )
-from didactic.models._config import DEFAULT_CONFIG, ModelConfig
-from didactic.types._types import classify
+from didactic.models._config import DEFAULT_CONFIG, ExtraPolicy, ModelConfig
+from didactic.types._types import TypeForm, classify
 
 if TYPE_CHECKING:
+    from collections.abc import Mapping
+
     import panproto
 
     from didactic.axioms._axioms import Axiom
@@ -222,8 +223,14 @@ def _build_field_spec(
             default=raw_default if not isinstance(raw_default, Field) else MISSING,
             usage_mode="readwrite",
         )
-    translation = classify(annotation)
-    annotated_meta = read_annotated_metadata(annotation)
+    # Above branches return for ``TypeVar`` / ``ForwardRef`` cases; the
+    # remaining annotation is a real ``TypeForm`` (a class, ``UnionType``,
+    # ``TypeAliasType``, ``GenericAlias``, or an ``Annotated`` form). Cast
+    # to drop the residual ``TypeVar | ForwardRef`` arms from pyright's
+    # view.
+    type_form = cast("TypeForm", annotation)
+    translation = classify(type_form)
+    annotated_meta = read_annotated_metadata(type_form)
 
     # default & metadata sourced from a Field instance, if present
     if isinstance(raw_default, Field):
@@ -307,11 +314,13 @@ class ModelMeta(type):
             [build_theory][didactic.theory._theory.build_theory]; cached
             thereafter. Subsequent accesses return the same object.
         """
-        if cls.__dict__.get("__theory_cache__") is None:
+        cached = cls.__dict__.get("__theory_cache__")
+        if cached is None:
             from didactic.theory._theory import build_theory  # noqa: PLC0415
 
-            cls.__theory_cache__ = build_theory(cls)
-        return cls.__theory_cache__
+            cached = build_theory(cls)
+            cls.__theory_cache__ = cached
+        return cached
 
     # config keys we accept on the class header.
     # e.g. ``class Foo(dx.Model, extra="forbid"): ...``
@@ -368,7 +377,7 @@ class ModelMeta(type):
 
     @staticmethod
     def _resolve_config(
-        target: type, header_overrides: dict[str, JsonValue]
+        target: type, header_overrides: Mapping[str, Opaque]
     ) -> ModelConfig:
         """Pick the ModelConfig for a class.
 
@@ -413,16 +422,22 @@ class ModelMeta(type):
         if not header_overrides:
             return explicit
 
-        # apply overrides via dataclasses.replace-shaped construction
-        merged_kwargs = {
-            "extra": explicit.extra,
-            "strict": explicit.strict,
-            "populate_by_name": explicit.populate_by_name,
-            "title": explicit.title,
-            "description": explicit.description,
-        }
-        merged_kwargs.update(header_overrides)
-        return ModelConfig(**merged_kwargs)
+        # apply overrides via dataclasses.replace-shaped construction. The
+        # ``header_overrides`` mapping is keyed on a known small set
+        # (``_CONFIG_HEADER_KEYS``); each value is taken at face value and
+        # validated by ``ModelConfig.__post_init__`` rather than statically.
+        def _pick(key: str, fallback: Opaque) -> Opaque:
+            return header_overrides.get(key, fallback)
+
+        return ModelConfig(
+            extra=cast("ExtraPolicy", _pick("extra", explicit.extra)),
+            strict=cast("bool", _pick("strict", explicit.strict)),
+            populate_by_name=cast(
+                "bool", _pick("populate_by_name", explicit.populate_by_name)
+            ),
+            title=cast("str | None", _pick("title", explicit.title)),
+            description=cast("str | None", _pick("description", explicit.description)),
+        )
 
     @staticmethod
     def collect_field_specs(target: type) -> dict[str, FieldSpec]:

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/models/_model.py

@@ -23,9 +23,6 @@ didactic.models._storage : the pluggable storage backend.
 
 # ``__init__(**kwargs: FieldValue | JsonValue)`` accepts JSON-shape
 # dicts but pyright doesn't carry the union through ``_encode_field``.
-# Tracked in panproto/didactic#1.
-# pyright: reportArgumentType=false
-
 from __future__ import annotations
 
 import json
@@ -136,7 +133,7 @@ class Model(metaclass=ModelMeta):
                 value = default
 
             try:
-                encoded_value = _encode_field(spec, value)
+                encoded_value = _encode_field(spec, cast("FieldValue", value))
             except (TypeError, ValueError) as exc:
                 errors.append(
                     ValidationErrorEntry(

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/models/_root.py

@@ -27,12 +27,9 @@ Examples
 
 # ``TypeAdapter`` round-trips a generic ``T`` through the field
 # translation layer; pyright doesn't bind ``T`` to ``FieldValue``.
-# Tracked in panproto/didactic#1.
-# pyright: reportArgumentType=false
-
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from didactic.models._model import Model
 
@@ -109,13 +106,16 @@ class TypeAdapter[T]:
             If the value cannot be coerced to the target type.
         """
         encoded = self._translation.encode(value)
-        return self._translation.decode(encoded)  # type: ignore[no-any-return]
+        return cast("T", self._translation.decode(encoded))
 
     def dump_json(self, value: T) -> str:
         """Encode ``value`` to a JSON string."""
         import json  # noqa: PLC0415
 
-        return json.dumps(self._translation.encode(value))
+        # ``T`` is unconstrained at the API surface; the translation
+        # accepts any ``FieldValue`` shape at runtime, so we cast at the
+        # boundary rather than constrain ``T``.
+        return json.dumps(self._translation.encode(cast("FieldValue", value)))
 
 
 __all__ = [

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/theory/_theory.py

@@ -1,10 +1,3 @@
-# panproto 0.43's ``_native.pyi`` stub for ``create_theory``/``colimit_theories``
-# disagrees with the runtime: ``create_theory`` declares ``dict[str, object]``
-# (rejecting our ``TheorySpec`` TypedDict, which IS a dict at runtime), and
-# ``colimit_theories`` is stubbed as ``(Sequence[Theory], /)`` while the
-# runtime is ``(t1, t2, shared)``. Tracked in panproto/didactic#1; will be
-# removed once panproto ships corrected stubs.
-# pyright: reportArgumentType=false, reportCallIssue=false, reportUnknownVariableType=false
 """Bridge between didactic FieldSpecs and ``panproto.Theory``.
 
 This module is the seam where the didactic-side metaclass output
@@ -35,8 +28,6 @@ didactic.fields._fields.FieldSpec : the per-field record consumed here.
 
 # ``_class_axiom_eq`` is a stub for the eqs-emission path that's
 # registered later; the local symbol is referenced by its qualname.
-# Tracked in panproto/didactic#1.
-# pyright: reportUnusedFunction=false
 
 from __future__ import annotations
 
@@ -45,7 +36,6 @@ from typing import TYPE_CHECKING, TypedDict, cast
 if TYPE_CHECKING:
     import panproto
 
-    from didactic.axioms._axioms import Axiom
     from didactic.fields._fields import FieldSpec
     from didactic.models._model import Model
     from didactic.types._typing import JsonValue
@@ -257,36 +247,6 @@ def _edge_accessor(
     }
 
 
-def _class_axiom_eq(ax: Axiom, schema_kind: str, idx: int) -> dict[str, JsonValue]:
-    """Build an Equation dict for a class-level axiom.
-
-    Parameters
-    ----------
-    ax
-        An [Axiom][didactic.axioms._axioms.Axiom] instance.
-    schema_kind
-        The model's primary sort name; used as a default name prefix.
-    idx
-        Zero-based position within the class's ``__axioms__`` list.
-
-    Returns
-    -------
-    dict
-        An equation dict with name + the raw expression text. The
-        panproto-side parser will translate the expression once the
-        runtime hookup lands; for now we carry the surface form
-        verbatim under an ``expr`` key.
-    """
-    name = ax.name or f"{schema_kind}_axiom_{idx}"
-    body: dict[str, JsonValue] = {
-        "name": name,
-        "expr": ax.expr,
-    }
-    if ax.message:
-        body["message"] = ax.message
-    return body
-
-
 def _embed_accessor(
     field_name: str, parent_sort: str, target_sort: str
 ) -> dict[str, JsonValue]:
@@ -472,24 +432,23 @@ def _build_colimit_theory(cls: type, parents: list[type]) -> panproto.Theory:
     """
     import panproto  # noqa: PLC0415
 
-    create_theory = panproto.create_theory
-    colimit_theories = panproto.colimit_theories
-
-    accumulator = create_theory(build_theory_spec(parents[0]))
+    accumulator = panproto.create_theory(build_theory_spec(parents[0]))
     accumulator_cls: type = parents[0]
 
     for parent in parents[1:]:
         ancestor = _lowest_common_model_ancestor([accumulator_cls, parent])
-        ancestor_theory = create_theory(build_theory_spec(ancestor))
-        next_theory = create_theory(build_theory_spec(parent))
-        accumulator = colimit_theories(accumulator, next_theory, ancestor_theory)
+        ancestor_theory = panproto.create_theory(build_theory_spec(ancestor))
+        next_theory = panproto.create_theory(build_theory_spec(parent))
+        accumulator = panproto.colimit_theories(
+            accumulator, next_theory, ancestor_theory
+        )
         accumulator_cls = parent
 
     # finally fold in any cls-only fields by colimiting against the
     # immediate spec of cls; the shared ancestor is the accumulated
     # theory we just built
-    cls_theory = create_theory(build_theory_spec(cls))
-    return colimit_theories(accumulator, cls_theory, accumulator)
+    cls_theory = panproto.create_theory(build_theory_spec(cls))
+    return panproto.colimit_theories(accumulator, cls_theory, accumulator)
 
 
 __all__ = [

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/types/_types.py

@@ -28,9 +28,6 @@ didactic.models._meta : the metaclass that orchestrates field translation.
 
 # An ``items()`` over an ``Annotated``-stripped value whose type
 # narrows to the wider ``object`` carve-out branch.
-# Tracked in panproto/didactic#1.
-# pyright: reportUnknownArgumentType=false
-
 from __future__ import annotations
 
 import json
@@ -38,7 +35,7 @@ from dataclasses import dataclass, field
 from datetime import date, datetime, time
 from decimal import Decimal
 from functools import reduce
-from types import EllipsisType, NoneType, UnionType
+from types import EllipsisType, GenericAlias, NoneType, UnionType
 from typing import (
     TYPE_CHECKING,
     Annotated,
@@ -64,13 +61,13 @@ type SpecRecord = dict[str, "JsonValue"]
 
 # The widest annotation form ``classify`` accepts. Includes the nominal
 # ``type`` (covering bare classes and pyright's special-cased parameterised
-# generics like ``tuple[int, ...]`` and ``dict[str, int]``) plus PEP 604
+# generics like ``tuple[int, ...]`` and ``dict[str, int]``), PEP 604
 # ``UnionType`` (``int | None``), which pyright does *not* narrow to
-# ``type``. Other typing special forms (``typing.Union[...]``,
-# ``Annotated[...]``, PEP 695 type aliases) are accepted at runtime but
-# fall outside this static union; callers that pass them rely on pyright's
-# legacy structural acceptance of those forms.
-TypeForm = type | UnionType
+# ``type``, and PEP 695 ``TypeAliasType`` instances. ``typing.Annotated``
+# values and ``typing.Union[...]`` are also accepted at runtime; callers
+# that pass them rely on pyright's legacy structural acceptance of those
+# forms or use ``cast`` at the boundary.
+TypeForm = type | UnionType | TypeAliasType | GenericAlias
 
 # ---------------------------------------------------------------------------
 # Public types
@@ -983,8 +980,9 @@ def _alias_sum_translation(alias: TypeAliasType) -> TypeTranslation:
             }
             return {f"{alias_name}_dict": inner_obj}
         msg = (
-            f"value of type {type(value).__name__} does not match any arm of "
-            f"alias {alias_name!r}; expected one of {sorted(table)}."
+            f"value of type {type(cast('Opaque', value)).__name__} does not "
+            f"match any arm of alias {alias_name!r}; expected one of "
+            f"{sorted(table)}."
         )
         raise TypeError(msg)
 
@@ -1289,6 +1287,13 @@ def _expand_type_alias(typ: TypeForm) -> TypeForm:
     return cast("TypeForm", substitution.get(value, value))
 
 
+# Public re-export under a non-underscored name, intended for tests and
+# tooling that need to introspect a PEP 695 alias substitution. The
+# underscored ``_expand_type_alias`` name is retained for backwards
+# compatibility within this module.
+expand_type_alias = _expand_type_alias
+
+
 def unwrap_annotated(typ: TypeForm) -> tuple[TypeForm, tuple[Opaque, ...]]:
     """Split ``Annotated[T, x, y, z]`` into ``(T, (x, y, z))``.
 
@@ -1782,7 +1787,7 @@ def _embed_translation(base: TypeForm, metadata: tuple[Opaque, ...]) -> TypeTran
                 f"got {type(items).__name__}"
             )
             raise TypeError(msg)
-        return target_cls.from_storage_dict(items)
+        return target_cls.from_storage_dict(cast("dict[str, str]", items))
 
     def from_json(v: JsonValue) -> FieldValue:
         # the JSON form is the model_dump dict (decoded values), not

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/types/_typing.py

@@ -19,9 +19,6 @@ didactic.types._types : the translation layer that consumes these aliases.
 
 # References ``_Missing`` (the sentinel singleton class) by name in
 # the ``DefaultOrMissing`` alias; the ``_`` is conventional.
-# Tracked in panproto/didactic#1.
-# pyright: reportPrivateUsage=false
-
 from __future__ import annotations
 
 from datetime import date, datetime, time
@@ -30,10 +27,9 @@ from typing import TYPE_CHECKING, ForwardRef, Protocol, runtime_checkable
 from uuid import UUID
 
 if TYPE_CHECKING:
-    from didactic.fields._fields import _Missing
+    from didactic.fields._fields import MissingType
     from didactic.models._model import Model
 
-
 # ---------------------------------------------------------------------------
 # Structural "anything" Protocol
 # ---------------------------------------------------------------------------
@@ -70,7 +66,6 @@ type JsonValue = (
 #: Convenience alias for an object-shaped JsonValue (``dict[str, JsonValue]``).
 type JsonObject = dict[str, JsonValue]
 
-
 # ---------------------------------------------------------------------------
 # Field-space values
 # ---------------------------------------------------------------------------
@@ -95,7 +90,6 @@ type FieldValue = (
     | Model
 )
 
-
 # ---------------------------------------------------------------------------
 # Encoded / storage values
 # ---------------------------------------------------------------------------
@@ -105,7 +99,6 @@ type FieldValue = (
 #: where "this is the encoded representation, not arbitrary text" matters.
 type Encoded = str
 
-
 # ---------------------------------------------------------------------------
 # Class / forward-reference targets
 # ---------------------------------------------------------------------------
@@ -115,15 +108,13 @@ type Encoded = str
 #: ``typing.ForwardRef`` proxy.
 type ClassTarget = type | str | ForwardRef
 
-
 # ---------------------------------------------------------------------------
 # Field default sentinel
 # ---------------------------------------------------------------------------
 
 #: A field default may be either a real value or the
 #: [MISSING][didactic.fields._fields.MISSING] sentinel.
-type DefaultOrMissing = FieldValue | _Missing
-
+type DefaultOrMissing = FieldValue | MissingType
 
 __all__ = [
     "ClassTarget",

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/vcs/_backref.py

@@ -2,7 +2,6 @@
 # type; pyright wants generics to bind multiple sites. The runtime
 # uses ``A`` for the call-site type binding documentation. Tracked
 # in panproto/didactic#1.
-# pyright: reportInvalidTypeVarUse=false
 """In-memory Backref resolution.
 
 [Backref][didactic.api.Backref] is the inverse of [Ref][didactic.api.Ref]: if
@@ -37,7 +36,7 @@ didactic.Repository : the eventual Repository-backed resolution path.
 from __future__ import annotations
 
 from collections import defaultdict
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
@@ -45,8 +44,8 @@ if TYPE_CHECKING:
     from didactic.models._model import Model
 
 
-def resolve_backrefs[A: Model, B: Model](
-    target: A,
+def resolve_backrefs[B: Model](
+    target: Model,
     candidates: Iterable[B],
     *,
     via: str,
@@ -178,11 +177,13 @@ class ModelPool:
             instances are stored under their own concrete class, not
             under ``cls``). Order is registration order.
         """
-        return list(self._by_class.get(cls, []))  # type: ignore[arg-type]
+        # ``_by_class`` is keyed on ``type[Model]``; ``cls`` narrows
+        # the value type to ``list[M]`` only at the call site.
+        return cast("list[M]", list(self._by_class.get(cls, [])))
 
-    def backrefs[A: Model, B: Model](
+    def backrefs[B: Model](
         self,
-        target: A,
+        target: Model,
         candidate_cls: type[B],
         *,
         via: str,

{didactic-0.3.1 → didactic-0.3.2}/src/didactic/vcs/_repo.py

@@ -1,9 +1,3 @@
-# Wraps panproto's ``Repository`` whose method signatures
-# (``log() -> list[dict[str, object]]``, ``resolve_ref() -> str | None``,
-# ``add(target: Schema)``) don't line up exactly with didactic's
-# narrower public surface. The runtime contract is honoured; the
-# stub-side narrowing is deferred. Tracked in panproto/didactic#1.
-# pyright: reportReturnType=false, reportArgumentType=false
 """Filesystem-backed VCS for panproto schemas.
 
 Wraps ``panproto.Repository`` with a didactic-shaped public surface.
@@ -36,7 +30,7 @@ panproto.Repository : the wrapped runtime type.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
     from os import PathLike
@@ -199,7 +193,7 @@ class Repository:
             The exact shape is panproto-defined; callers that depend
             on specific keys should consult panproto's documentation.
         """
-        return list(self._inner.log())
+        return cast("list[JsonObject]", list(self._inner.log()))
 
     def resolve_ref(self, ref: str) -> str:
         """Resolve a ref expression to a commit id.
@@ -217,9 +211,15 @@ class Repository:
         Raises
         ------
         panproto.VcsError
-            If ``ref`` does not resolve to a commit.
+            If ``ref`` does not resolve to a commit, or returns ``None``.
         """
-        return self._inner.resolve_ref(ref)
+        result = self._inner.resolve_ref(ref)
+        if result is None:
+            import panproto  # noqa: PLC0415
+
+            msg = f"ref {ref!r} did not resolve to a commit"
+            raise panproto.VcsError(msg)
+        return result
 
     # mutation ------------------------------------------------------
 
@@ -244,7 +244,9 @@ class Repository:
         if isinstance(target, type) and issubclass(target, Model):
             self._inner.add(schema_from_model(target))
             return
-        self._inner.add(target)
+        # already-narrowed by the isinstance branch above; only the
+        # ``Schema`` arm of the union is left.
+        self._inner.add(cast("panproto.Schema", target))
 
     def commit(
         self,