Changelog¶

The current CHANGELOG.md is maintained at the workspace root. This page mirrors its content for the docs site.

Changelog¶

All notable changes to this project will be documented in this file.

The format follows Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]¶

[0.9.0] - 2026-06-17¶

Added¶

• CommittedDataset carries a key: the identifier recorded for the dataset, surfaced by data_at. Repository.add_data takes an optional key so a downstream that versions one record per dataset can tag each with its own identifier (for example an AT-URI) and map a committed dataset back to it; when omitted the key defaults to the source path. This completes the committed-data round trip and lets a downstream build a per-record, revision-to-revision diff from data_at alone. (#54)

Changed¶

• Minimum panproto version raised from 0.54.0 to 0.56.0, which records the per-dataset key behind add_data / data_at and lets a commit carry staged data forward without a schema change (a data-only commit no longer raises nothing staged while has_staged reports data staged).

[0.8.0] - 2026-06-17¶

Added¶

• Repository.add_data(path) stages a data file for the next commit, the write-side counterpart to data_at. It binds the file to the staged schema, or to HEAD's schema when none is staged, and the committed bytes are then readable at that revision through data_at. A downstream that versions record values can stage and read them entirely through the documented surface instead of reaching the inner panproto handle. (#54)

[0.7.8] - 2026-06-17¶

Added¶

• Repository.data_at(ref) reads the datasets committed at a revision without touching HEAD or the working tree, returning one CommittedDataset (schema_id / data / record_count) per committed dataset. This is the data-side counterpart to panproto's committed-schema lookup, so a downstream can reconstruct the record set at an arbitrary revision (for example to diff two revisions) without checking it out. CommittedDataset is exported from didactic.api. (#50)

Changed¶

• Minimum panproto version raised from 0.53.0 to 0.54.0, which adds the data_at committed-data accessor behind the new Repository.data_at and corrects the create_annotated_tag binding stub (return type and message / author argument order).
• Repository.create_annotated_tag returns the created annotated-tag object id (the id the tag ref resolves to). It previously returned None to sidestep the panproto stub, now fixed upstream.

Fixed¶

• The runtime __version__ constant in each distribution (didactic.api, didactic.pydantic, didactic.settings, didactic.fastapi) is bumped in lockstep with the packaging version; the four had drifted to 0.7.6. A test_version guard now fails if a runtime constant and its packaged version diverge.

[0.7.7] - 2026-06-16¶

Added¶

• Repository exposes tag management: create_tag(name, target, *, force=False) for a lightweight tag, create_annotated_tag(name, target, *, message, tagger) for an annotated-tag object, and delete_tag(name). The three are thin pass-throughs to the underlying panproto handle, mirroring how commit, create_branch, and list_tags are already wrapped, so a downstream that tags a revision through the documented surface no longer has to reach the private inner handle. (#49)

[0.7.6] - 2026-06-16¶

Changed¶

• Minimum panproto version raised from 0.52.1 to 0.53.0. The release adds a Python entry point for lexicon parsing (parse_atproto_lexicon / parse_schema_document / Schema.from_atproto_lexicon) and the Schema-to-Theory bridge (theory_of / Schema.theory), and bumps its build to pyo3 0.29 for two RUSTSEC advisories. The GAT theory vocabulary (ValueKind / Operation / Sort) is unchanged, so didactic's forward and inbound theory paths, including closed-sum-sort synthesis, are unaffected.

[0.7.5] - 2026-06-16¶

Added¶

• The inbound synthesiser (didactic.synthesis: model_from_spec, models_from_specs, model_from_theory) reconstructs closed sum sorts. A dx.TaggedUnion field rebuilds into a union root with one variant subclass per constructor (keyed by the discriminator value recovered from the constructor name), and a Model-ref recursive alias rebuilds into an equivalent type alias. A model carrying either shape now round-trips through the synthesiser at the Theory-spec level. Variant and arm Model payloads resolve through the shared registry (so an edge elsewhere binds the same class), and models_from_specs orders sum-arm dependencies ahead of their dependents so a forward-referenced arm resolves to the real class rather than a fieldless stub. (#45)

Notes¶

• Three lossiness limitations of the synthesiser (scalar value kinds collapsing to str, Ref indistinguishable from Embed, and per-field defaults / metadata being absent) are inherent to the GAT theory vocabulary rather than the synthesiser: a panproto Operation carries no containment marker or metadata slot, and ValueKind has no temporal / decimal / uuid variant. These are tracked upstream for a representation didactic can adopt without smuggling private data through ignored spec keys.

[0.7.4] - 2026-06-10¶

Changed¶

• Minimum panproto version raised from 0.52.0 to 0.52.1. The release resyncs the _native.pyi stubs to the runtime (diff_and_classify takes a third protocol argument; ProtolensChain.instantiate takes (schema, protocol); Instance.root / node_count / arc_count are int properties and Instance.validate() returns the error list). It also tightens by-construction source emit for Rust and Julia (line comments no longer absorb the following items, opaque token trees emit verbatim, Julia parenthesised macro calls keep their arguments), which flows through didactic.codegen.source.emit_pretty and Model.emit_as.

Removed¶

• The two boundary casts that worked around the pre-0.52.1 stub drift are gone: classify_change calls panproto.diff_and_classify with its three runtime arguments directly, and DependentLens.instantiate passes the Protocol through without re-casting it to Schema. Behaviour is unchanged; the call sites now type-check against the corrected stubs.

[0.7.3] - 2026-06-07¶

Added¶

• find_correspondences, best_correspondence, and the Correspondence record wrap panproto's hom search (find_morphisms / find_best_morphism). Given two panproto Schemas, the search enumerates structure-preserving vertex maps, scored by alignment quality, with anchors to pin known pairings and monic / epic / iso to constrain the map's shape. A discovered Correspondence.vertex_map has exactly the dict[str, str] shape that DependentLens.auto_generate_with_hints takes as hints, so the two compose into a discover-then-derive pipeline (documented in the lenses guide). The search is informative on multi-vertex schemas (hand-built protocol schemas, parse-recovered source schemas); the single-vertex schemas didactic builds from Model classes degenerate to the root pairing.

Changed¶

• Minimum panproto version raised from 0.48.3 to 0.52.0. The bump pulls in, with direct effect on didactic's surface:

• The hom-search bindings (find_morphisms, find_best_morphism, TheoryMorphism, SchemaMorphism, FoundMorphism) that back the new correspondence API.

• The emit_pretty rewrite (grammar-derived token roles, role-pair spacing, structural bracket detection) and the emit-coverage sweep that corpus-verifies the emit fixed-point law (emit(parse(emit(s))) == emit(s)), covering every grammar the panproto wheel ships. This is the engine behind didactic.codegen.source.emit_pretty and Model.emit_as.
• get_builtin_protocol resolving tree-sitter grammar protocols (get_builtin_protocol("python") succeeds instead of raising KeyError).
• IdGenerator disambiguation of repeated names at the same scope, which unblocks parsing any Python source that uses @typing.overload through didactic.codegen.source.parse.
• Resynced _native.pyi stubs. didactic's typing follows: DependentLens.auto_generate_with_hints declares hints: dict[str, str] (was object), and the TheorySpec handoff to panproto.create_theory narrows through a documented boundary cast (a TypedDict is assignable to Mapping[str, object] and to no narrower mapping, while the resynced stub takes Mapping[str, JsonValue]).

Fixed¶

• __version__ strings match the released distribution version across all four packages. The core didactic.api.__version__ and the three sibling __init__ modules lagged behind their pyproject.toml versions, so didactic version under-reported.

[0.7.2] - 2026-05-19¶

Changed¶

• Minimum panproto version raised from 0.43.1 to 0.48.3. The bump pulls in the panproto-parse emit_pretty fixes that affect didactic.codegen.source.emit_pretty directly: every iteration of FIELD(REPEAT(...)) and FIELD(SEQ(SYMBOL, REPEAT(SEQ(',', SYMBOL)))) is now rendered (the prior wheel dropped all but the first), abstract-schema edge order is preserved through pretty_with_protocol (children of the same parent no longer re-fuse by kind), and indent-based grammars open and close indent scopes on _indent / _dedent external tokens. A regression test in tests/test_codegen.py covers the comma-separated argument case end-to-end.

Added¶

• DependentLens.from_dsl_json, DependentLens.from_dsl_yaml, DependentLens.from_dsl_nickel, and DependentLens.from_dsl_path compile a panproto-lens-dsl document into a chain. Each loader takes the document source (or a path; from_dsl_path dispatches on extension) plus the entry vertex of the source schema the chain is being authored against.

[0.7.1] - 2026-05-07¶

Fixed¶

• model_validate_json no longer crashes for Models that carry an opaque field. The null placeholder model_dump_json writes is dropped during JSON-payload conversion (the opaque translation's from_json would otherwise raise, by design); the field falls back to its declared default. A required opaque field with no default surfaces a clean missing_required ValidationError on round-trip instead of a bare TypeError. docs/guide/fields.md updated to spell out this behaviour precisely.

[0.7.0] - 2026-05-07¶

Added¶

• tuple[Model, ...] (and dict[str, Model], plain inner: Model) now classifies any dx.Model subclass used directly as a field type. The classification routes through the same Embed-shaped translation that Embed[T] would have built, so the wire format and runtime semantics are identical and callers no longer need a single-variant TaggedUnion wrapper to collect heterogeneous record tuples. Models that are TaggedUnion roots or variants stay on the discriminated path. (#38)
• dx.field(opaque=True) declares a field that holds any Python value by reference and skips the type-classification pipeline entirely. The runtime stores the value on a per-instance _opaque_storage side table; attribute access returns it identity-equal; with_(...) updates it without re-classification. JSON output writes null for opaque fields, and model_validate_json does not reconstruct the value: opaque fields explicitly do not round-trip through serialisation. Useful for fields that carry a runtime-only handle (a typeclass instance, a callback, a foreign object) where panproto schema integration is not the goal. (#39)

Changed¶

• The documentation site uses the cinder theme. The previous Material configuration is replaced by theme: name: cinder plus a small docs/css/ palette covering pygments token colours and mkdocstrings layout. CI no longer needs the NO_MKDOCS_2_WARNING workaround; the same env var has been removed from ci.yml / docs.yml / release.yml and from the README's local-build snippet.

[0.6.2] - 2026-05-06¶

Fixed¶

• FieldValue's recursive mapping arm uses Mapping[str, FieldValue] (covariant in its value type) instead of the invariant dict[str, FieldValue]. dict is invariant in V, so any concrete dict[str, X] (where X is a structural subset of FieldValue) was rejected by type checkers at every Model.with_(field=value) call site, forcing callers to insert cast("dict[str, FieldValue]", ...) boilerplate. The runtime contract is unchanged: every dict is also a Mapping, and the encoder pipeline's isinstance(v, dict) checks keep matching real dict payloads. (#36)

[0.6.1] - 2026-05-06¶

Fixed¶

• ModelMeta's @dataclass_transform now declares kw_only_default=True (it previously declared kw_only_default=False). Without this, type checkers in strict mode rejected every subclass that added a non-default field after a parent's default-bearing field with "Fields without default values cannot appear after fields with default values" (reportGeneralTypeIssues). The runtime Model.__init__ already accepted only keyword arguments, so the flag flip just aligns the static contract with the runtime behaviour. The natural shape (Base carries auto-id / timestamps with defaults; Subclass adds domain fields) now passes pyright's strict-mode analysis without per-line suppressions. (#34)

[0.6.0] - 2026-05-06¶

Added¶

• Field annotations of the form A | B where both A and B are TaggedUnion roots are now classified as a multi-root discriminated union. The two arms must share the same discriminator field name (checked at class-creation time) and their discriminator-value sets must be disjoint (checked lazily, only on encode/decode of an actually colliding value, so a model whose union-typed field is never encoded with a colliding variant remains usable). Encode and decode both consult the live merged variant registry, so variants registered after the field's parent class is classified participate fully. (#30)
• @dx.model_validator(mode="after") decorates a class method as a class-level validator that receives the constructed instance and runs after every per-field validator and every __axioms__ check. raise ValueError / raise TypeError from the body surfaces as a ValidationError entry with type="validator_error" and empty loc. Multiple model validators on one class collect into a single error. Subclass inheritance and the silent-shadow override-without-marker policy work the same as for @validates. Use this for cross-field invariants that aren't expressible in the __axioms__ surface syntax. The shape mirrors Pydantic v2's @model_validator(mode="after"). (#31)

Fixed¶

• The axiom evaluator now resolves length xs (panproto's long-form length builtin) the same as len xs. Both compile to Python len(...). (#31)
• isNone / isNull / isSome / isJust builtins resolve to the obvious value is None / value is not None predicates in axiom expressions. The Python-friendly is null / is not null preprocessor rules from v0.5.1 already covered the most common spelling; these add the explicit-call form for axioms that prefer it. (#31)

Changed¶

• docs/guide/unions.md documents the union-of-TaggedUnion-roots shape with the disjoint-values requirement spelled out.
• docs/guide/validators.md documents @dx.model_validator and the cross-field-invariants decision tree (axiom for surface-syntax expressible, model_validator for Python-needed).

[0.5.2] - 2026-05-05¶

Fixed¶

• Embed[Root] where Root is a TaggedUnion no longer downcasts variant instances to the root class. The Embed encoder always wrote the variant's full storage dict (including the variant-specific fields), but the decoder reconstructed the value via Root.from_storage_dict -- the root has no field specs of its own, so the variant fields became unreachable on the recovered instance. The Embed translation now inspects the stored discriminator value at decode time and dispatches to the matching variant in Root.__variants__, mirroring the live-registry fix used elsewhere in the TaggedUnion path. tuple[Embed[Root], ...], dict[str, Embed[Root]], and bare Embed[Root] fields all preserve the variant subclass identity through construction, storage round-trip, and JSON round-trip. Plain Embed[T] (no TaggedUnion) keeps the legacy single-class path unchanged. (#27)

[0.5.1] - 2026-05-05¶

Fixed¶

• __axioms__ can now reference Optional fields. The previous evaluator only handled bare comparison and arithmetic; a == null parsed but failed at evaluation, and a != null failed even at parse time. The expression-language pipeline now does two things: a Python-friendly preprocessor rewrites != -> /=, and/or -> &&/||, null/None -> Nothing, and X is null / X is not null -> the corresponding Nothing comparison; the evaluator handles the full panproto Expr surface (Just/Nothing, App-style builtins including min/max/abs/elem/len, if/then/else (Match), let bindings, lambdas in map/filter, list literals [1, 2, 3], field access a.b, and the ++ (Concat) operator). The preprocessor respects string literals: substitutions never fire inside "..." or '...'. (#26)

Changed¶

• docs/guide/axioms.md documents the full surface (operators, Python-friendly synonyms, an Optional-field worked example) and narrows the "what axioms cannot do" section to the truly missing constructs (forall/exists, multi-arm case, graph-traversal builtins).

[0.5.0] - 2026-05-05¶

Added¶

• pathlib.Path (and any PurePath subclass: PurePosixPath, PureWindowsPath, etc.) is a first-class scalar field type. Wire format is str(path); decoding restores the same PurePath subclass. (#21)
• enum.StrEnum and enum.IntEnum are first-class scalar field types. String-valued and int-valued plain enum.Enum subclasses also work; mixed-value enums raise TypeNotSupportedError. The encoder accepts either an enum member or its raw value, so M.model_validate({"color": "red"}) works the same as M(color=Color.RED). (#23)

Fixed¶

• TaggedUnion-typed fields now JSON-round-trip correctly when the variant is itself a TaggedUnion. model_validate_json walks each nested {"kind": "...", ...} payload through the discriminator registry, instead of handing the dict straight to the variant-encoder (which expected a fully-constructed instance). Direct construction with a dict child works too: BinOp(left={"kind": "lit", "value": 1}, ...) dispatches the same way. (#22)
• TaggedUnion-typed fields consult cls.__variants__ live at encode and decode time, not snapshotted at field-classify time. Variants registered after a parent variant's field was classified (the canonical case is mutually recursive AST shapes: BinaryOp -> ListLiteral and ListLiteral -> BinaryOp) participate fully, in either definition order. (#24)

Changed¶

• docs/guide/types.md documents the Path family and the StrEnum / IntEnum / value-typed Enum branches alongside a worked StrEnum example.
• docs/guide/unions.md documents recursive and mutually recursive variants, dict-dispatch on construction, and the JSON round-trip contract.

[0.4.3] - 2026-05-05¶

Fixed¶

• dx.TaggedUnion variant discriminator now accepts every spelling of Literal[...]: bare Literal["x"], qualified typing.Literal["x"], and aliased imports (from typing import Literal as L). Under from __future__ import annotations the discriminator annotation arrives as a string; the variant check now evaluates that string in the class's defining module before applying the get_origin(...) is Literal check, instead of pattern-matching on the source text. Useful when the variant Model has a class also named Literal (e.g. an AST module exporting Literal, Variable, BinaryOp from a discriminator-tagged ASTNode union root) so the user can keep the public API name. (#18)

[0.4.2] - 2026-05-05¶

Fixed¶

• @dx.validates is no longer a silent no-op. The metaclass now walks target.__mro__ for methods carrying the __didactic_validator__ marker and stores them on the class as __field_validators__; Model.__init__ and Model.with_(...) invoke them in the right order: dx.field(converter=...) first, then mode="before" validators on the raw value, then the encoder, then mode="after" validators on the canonical decoded value (re-encoded if the validator returned a different value). Validators may raise ValueError / raise TypeError to reject the input; failures surface as ValidationError entries with type="validator_error" and loc=(field_name,). Instance, @classmethod, and @staticmethod shapes all work. Subclasses inherit a parent's validators; a subclass override that re-applies @validates replaces the inherited method, and a subclass that shadows the method without @validates deliberately disables validation for that field. (#17)

Changed¶

• docs/guide/validators.md was rewritten to document the raise ValueError / return-value-replaces-stored-value contract (the previous draft described a return bool shape that the runtime never implemented), and to cover mode="before", multi-field validators, multiple-validator chaining, inheritance semantics, and the three method shapes.

[0.4.1] - 2026-05-05¶

Fixed¶

• tuple[T, ...]-typed fields now coerce list input to tuple at the encoder boundary instead of raising a bare AssertionError. Mirrors Pydantic's affordance so call sites migrating across don't have to rewrite every indices=[0, 1, 2] literal. Non-iterable input still fails, but as a dx.ValidationError carrying the field name and a type_error entry, not as an AssertionError from inside the encoder. (#15)
• frozenset[T]-typed fields coerce list, set, and tuple input the same way. Bare strings are still rejected (they would otherwise silently explode into frozenset({"a", "b", "c"})).

[0.4.0] - 2026-05-05¶

Added¶

• ModelConfig.extra="ignore" is honoured: keyword arguments at construction (and dict keys at model_validate) that don't match a declared field are silently dropped. with_() stays strict regardless; an unknown kwarg there is always a programming error. (#11)
• Generic Models auto-parameterise on subscript. Both PEP 695 syntax (class Range[T: int | float](dx.Model): ...) and the legacy Generic[T] mixin form work. Range[int](min=0, max=10) returns an instance of a synthesised concrete subclass; the subclass is cached per type-arg tuple on the generic parent so repeated subscripts return the same class object and its Theory is built once. Substitution walks through nested generic shapes: tuple[T, ...], dict[str, T], T | None, Annotated[T, *meta], Embed[T], Ref[T], and unions of these are all rewritten correctly. Class-level defaults (min: T = 0) and dx.field(...) metadata (default, default_factory, description, alias, examples, deprecated, nominal, usage_mode, extras, converter) propagate from the generic parent onto the synthesised subclass. (#12)
• read_class_annotations is part of the public surface (lifted from the underscore-prefixed _read_class_annotations) and the metaclass's annotation-reader return type is dict[str, type | TypeVar | ForwardRef] to reflect what the PEP 695 generic-parameter path produces.

Fixed¶

• Inherited field defaults survive on subclass. Child(Base) where Base declares id: str = "default-id" constructs cleanly with the inherited default. ModelMeta.collect_field_specs walks ancestor classes by copying their already-finalised FieldSpec; it only re-runs _build_field_spec for the target class's own annotations. (Reading __dict__ for ancestor classes lost their defaults because the metaclass strips field defaults from the class dict at the end of each Model's class-creation step.) (#13)
• The deferred-TypeVar branch in _build_field_spec carries through every Field attribute (default, default_factory, converter, alias, description, examples, deprecated, nominal, usage_mode, extras), so a generic with value: T = dx.field(default=42, description="...") keeps that metadata available for parameterisation.

Removed¶

• The leftover # Tracked in panproto/didactic#1. comment blocks from the v0.3.2 suppression unwind are stripped from every file in the workspace. They documented suppressions that no longer exist.

[0.3.2] - 2026-05-04¶

Changed¶

• panproto pin bumped to >=0.43.1. panproto 0.43.1 ships corrected _native.pyi stubs for create_theory (Mapping[str, object]) and colimit_theories ((t1, t2, shared)), so didactic now calls these directly again. Tracking issue panproto/panproto#72 closed upstream.

Fixed¶

• All strategic per-file pyright suppressions tracked under (#1) are now removed and the underlying issues are fixed structurally. uv run pyright reports 0 errors with no per-file # pyright: report*=false directives outside the documented CONTRIBUTING.md carve-out (the field() overload pattern, which pyright in strict mode cannot reconcile with the ergonomics that drive the carve-out's existence).
• The fixes touch every package: typed cast boundaries where panproto returns wider types than didactic's narrower public surface, isinstance narrowing on model_dump results in tests, Model.model_validate({...}) swaps for negative tests passing wrong-typed kwargs, public re-exports of underscore-prefixed names that tests already reach for, and a handful of small refactors (a typed kwargs dict in _resolve_config, a structured cast at the metaclass annotation boundary, __provenance__ gated behind TYPE_CHECKING so the metaclass does not register it as a Model field).
• TypeForm widened to include TypeAliasType and GenericAlias. The static type now matches what classify / unwrap_annotated accept at runtime.
• FieldSpec.annotation widened to TypeForm | TypeVar | ForwardRef. The metaclass walks generic-parameter and forward-string annotations as a real path; the type now reflects it.
• Repository.resolve_ref raises panproto.VcsError when the underlying call returns None instead of silently violating its -> str return type.
• Removed an unused _class_axiom_eq helper from theory/_theory.py. The helper was a stub for a future eqs-emission path; it lives in the git history and will return when the panproto-Expr parser hookup lands.
• Lens[A, B] is now Lens[A, B, C] in check_lens_laws so the complement type carries through to dx.testing.check_lens_laws; tests parameterise as dx.Lens[User, User, str].
• Settings package: replaced # type: ignore directives by routing yaml through importlib.import_module, adding a real fetch method to the _Source base, casting at the Opaque -> JsonValue loader boundary, splitting the argparse.Namespace vs Mapping branches, and gating __provenance__ behind TYPE_CHECKING so the metaclass does not register it as a Model field.

[0.3.1] - 2026-05-01¶

Fixed¶

• Sum-sort encoders (closed Model-ref recursive aliases and TaggedUnion field types) now route the chosen variant through model_dump_json instead of bare model_dump, so any nested tuple[Embed[T], ...] / dict[str, Embed[T]] / arbitrary Model-containing structure inside the variant gets the JSON-safe walk. Previously such payloads raised Object of type X is not JSON serializable from json.dumps. (#7)
• Embed[Inner] round-trip via model_dump_json / model_validate_json no longer asserts when Inner has a tuple[T, ...] (or any from_json-coerced) field. The embed translation now routes inner JSON payloads through model_validate_json so per-field from_json runs at every level (e.g. JSON list to tuple coercion). (#8)
• model_dump evaluates inner_kind == "sum" before the isinstance(value, Model) branch, so a Model variant of a sum-sort field is dumped with its constructor tag instead of collapsing to the variant's record dict. Previously a recursive alias whose Model arm was the current value lost its dispatch info on the dump side; the JSON round-trip then raised unknown constructor on decode.
• embed_schema_uri walks nested Model-containing fields via model_dump_json so the returned dict is always serialisable; previously failed with TypeError when the source instance had a tuple[Embed[T], ...] field.

Changed¶

• Recursive Model-ref alias encoders prefer the tuple constructor over the list constructor when both arms are declared, even for Python list input. This keeps the encoded storage form canonical: round-tripping a Python list and re-encoding produces the same constructor name and the same storage string, restoring Model equality across the round-trip.

[0.3.0] - 2026-05-01¶

Added¶

• Recursive type aliases whose arms include dx.Model subclasses now translate to a panproto-native closed sum sort. The motivating shape is a Component alias mixing primitives, Models, and JSON-compatible containers; the alias name becomes the panproto sort, with one Operation per arm declared as a constructor and the sort's SortClosure set to Closed against that constructor list. Wire format for an arm value is a single-key JSON object whose key is the constructor name (matches panproto's term-of-closed-sort encoding). Lists round-trip as tuples to satisfy the tuple-based FieldValue invariant. Cycles in the value graph raise ValueError rather than recurse. (#2)
• dx.TaggedUnion subclasses are now usable directly as a field value type. dict[str, Parameter], tuple[Parameter, ...], and a bare param: Parameter annotation all work, with dispatch via the variant's discriminator field. The translation contributes a closed sum sort and per-variant constructor ops to the parent Model's Theory; the on-wire format is the variant's natural model_dump (no envelope, since the discriminator is already in the payload). (#5)
• TypeTranslation gains optional auxiliary_sorts and auxiliary_ops tuples that let a translation contribute extra panproto sort and operation declarations to the parent Model's Theory. Currently produced by the recursive Model-ref alias and TaggedUnion translations; build_theory_spec walks them and dedupes by name. Empty for every other translation.
• inner_kind = "sum" joins the documented set of TypeTranslation inner-kind values. model_dump routes sum-sort fields through their encoder so the constructor-tag dispatch survives JSON round-trip.

Notes¶

• Recursive aliases that aren't pure JSON-shape and aren't Model-ref-shape (e.g. one admitting bytes, Decimal, or a non-Model class) continue to raise TypeNotSupportedError with a clear message.
• Panproto's Theory.sorts and Theory.ops attributes are list-typed at runtime, contrary to the shipped _native.pyi stub which marks them as methods. Tests that introspect a built Theory treat them as data.

[0.2.0] - 2026-05-01¶

Added¶

• Bare PEP 695 type aliases now translate transparently. type Kind = Literal["a", "b", "c"] is accepted as a Model field annotation; the classifier unwraps the alias before dispatching. (#2)
• Union of primitive scalars is a translatable field type. int | str, float | str, int | float | str, and the same unions inside dict[str, V] and T | None are accepted. The synthesised panproto sort name is "Union <a> <b> ..." in canonical order; the encoder JSON-encodes the value, and the decoder dispatches on the resulting Python type. (#2, #3)
• JSON-shaped recursive type aliases translate to a single opaque panproto sort named after the alias. The motivating shape is the canonical JsonValue alias (str | int | float | bool | None | list[X] | tuple[X, ...] | dict[str, X] with X self-referential). The encoded form is json.dumps(value); the decoder parses and recursively coerces lists to tuples to satisfy didactic's tuple-based FieldValue type. Recursive aliases that are not JSON-shaped (e.g. one admitting bytes) raise TypeNotSupportedError with a clear message rather than failing silently. (#2)

[0.1.0] - 2026-05-01¶

Added¶

• dx.Model and dx.BaseModel with frozen, immutable instances backed by a panproto Theory built lazily on first __theory__ access.
• dx.field(...) descriptor with default, default_factory, alias, description, examples, deprecated flag, nominal-id flag, custom converters (PEP 712), and pass-through extras.
• dx.ModelConfig for class-level configuration.
• dx.Ref[T] non-owning cross-vertex references.
• dx.Embed[T] owned sub-vertex composition.
• dx.TaggedUnion discriminated unions with subclass dispatch.
• dx.Lens[A, B], dx.Iso[A, B], dx.Mapping[A, B] lens classes with composition, identity, and inverse() for Iso chains.
• @dx.computed derived attributes for serialisation.
• dx.axiom("...") class-level axioms collected on cls.__class_axioms__.
• @dx.validates(field_name) Python-side validators.
• JSON / pickle serialisation with per-field re-coercion.
• dx.register_migration(...) / dx.migrate(...): schema migrations as registered lenses keyed by structural fingerprint of the Theory spec, robust to class renames and re-imports.
• dx.save_registry(path) / dx.load_registry(path): human-readable registry dumps for diagnostic and audit purposes.
• dx.Repository.init(...) / Repository.open(...): filesystem-backed panproto repository wrapper. add accepts either a panproto Schema or a dx.Model class (synthesised via Protocol.from_theories). Branches, refs, tags, and log all exposed.
• dx.DependentLens: schema-parametric lens family wrapping panproto.ProtolensChain (auto-generation, JSON round-trip, composition, fusion, instantiation).
• dx.resolve_backrefs(target, candidates, *, via) plus dx.ModelPool for in-memory backref resolution.
• Theory colimit on multiple inheritance: class D(B, C) builds the panproto pushout over the lowest common Model ancestor.
• dx.testing.verify_iso(iso, strategy) for property-test law checks.
• didactic-pydantic.from_pydantic(...): structural conversion of a Pydantic v2 BaseModel to a dx.Model subclass.
• didactic-pydantic.to_pydantic(...): the inverse direction, for FastAPI / OpenAPI consumers.
• mkdocs documentation site with narrative guides and a full API reference, validated in CI under --strict mode.
• Runnable examples in examples/.

Known issues¶

• A handful of files carry per-file pyright suppressions for noise that the strict-mode checker cannot resolve without a deeper refactor. Each suppression is inline-commented with the rule list and the reason. Tracked in issue #1; the suppressions will be replaced with the real fixes in a v0.1.x patch release.

Notes¶

• Targets Python 3.14 and panproto 0.40+.
• The structural fingerprint normalises a Model's display name in the spec before hashing, so two structurally identical Models share a registry entry.