Valid recursive PEP 695 JsonValue alias rejected as circular

[rayliverified]

Basilisk 0.38.0 rejects a valid directly-recursive PEP 695 JsonValue alias as generics_syntax_scoping / circular. Full repro, command output, and comparator results are in the comment below.

[rayliverified]

Repro details:

from typing import cast

type JsonValue = dict[str, JsonValue] | list[JsonValue] | str | int | float | bool | None

def coerce(value: object) -> JsonValue:
    result: JsonValue = cast(JsonValue, value)
    return result

Basilisk 0.38.0 reports:

error[generics_syntax_scoping]: Circular type alias definition: `JsonValue` references itself
  --> verified_recursive_pep695_jsonvalue_issue.py:3:6
  |
3 | type JsonValue = dict[str, JsonValue] | list[JsonValue] | str | int | float | bool | None
  |      ^^^^^^^^^
  |
   = help: Recursive type aliases must reference themselves with the same type parameters

Found 1 diagnostic (1 error).

Environment: Windows 10.0.26200 x64; Python 3.12.12; Basilisk 0.38.0; Typeshed pin 866b5466c43a66135c0ef98a4eecf9586db0636d; ty 0.0.65; mypy 2.3.0.

Comparators accepted it:

python: OK
ty: All checks passed!
mypy: Success: no issues found in 1 source file

Expected: Basilisk should accept this recursive PEP 695 alias, matching Python 3.12, ty, and mypy.

Reduction note: a non-recursive PEP 695 typing.cast(JsonValue, value) case no longer reproduces a names_undefined diagnostic for me on Basilisk 0.38.0, with or without the pinned current Typeshed source.

[MelbourneDeveloper]

Still reproduces on a clean cargo build --release of main @ 5b756d3 (CLI, not just the playground). While triaging a batch of X-reported typing puzzles I narrowed the boundary, and it is considerably wider than the JsonValue case in the title.

The rule is inverted: it is the non-generic recursive alias that is rejected

type J = list[J]                    # FALSE POSITIVE
type J = int | list[J]              # FALSE POSITIVE
type J = dict[str, J]               # FALSE POSITIVE
type JsonValue = None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]
                                    # FALSE POSITIVE  (the reported case)

type J[T] = T | list[J[T]]          # accepted
type R[T] = set[R[T]]               # accepted

Every non-generic PEP 695 type alias that mentions its own name is reported as:

error[generics_syntax_scoping]: Circular type alias definition: `J` references itself

The generic forms — which are strictly harder to check — are accepted. So this is not "recursion detection is too eager in one shape"; the alias is flagged precisely when it has no type parameters.

The legacy spelling is unaffected

from typing import TypeAlias
J: TypeAlias = "int | list[J]"      # clean

This matters because it is the workaround users will find, and because it explains the conformance result below.

Why the conformance gate did not catch it

conformance/tests/aliases_recursive.py contains zero PEP 695 type statements:

$ grep -c '^type ' conformance/tests/aliases_recursive.py
0

Every recursive case upstream is written in the legacy form (Json = Union[None, int, str, float, list["Json"], dict[str, "Json"]], RecursiveTuple = str | int | tuple["RecursiveTuple", ...], RecursiveMapping = ...), which Basilisk handles correctly. So a 100% score and this false positive coexist happily — the suite simply never exercises the affected syntax, even though the file's own header says "PEP 695 formally mandates that recursive type aliases work."

That is worth recording independently of the fix: this is a blind spot in our coverage, not just a bug. A regression test using the PEP 695 spelling of each upstream case belongs in our own suite.

Severity

Recursive aliases are the canonical way to type JSON, tree nodes, and nested config, and type X = ... is the spelling the language now steers everyone toward. Under our own standard — a false positive on spec-valid code is the cardinal sin — this reads as showstopper-grade rather than ordinary priority.

Related

The neighbouring wording/rule-code problem (non-terminating recursion such as type R[T] = set[R[T | R[T]]] being reported as "circular" under generics_syntax_scoping) is filed separately as #383. The two want opposite fixes and should not share a code: ordinary recursion must produce no diagnostic at all, while non-regular recursion — if we keep rejecting it — belongs in its own opt-in house rule.

[MelbourneDeveloper]

Refs #371 — fixed on bidirectionaltype-inference.

Root cause: the circular-alias check in generics_syntax_scoping flagged any parameterless type alias whose RHS mentioned its own name anywhere (a textual scan), so guarded recursion like type JsonValue = int | list[JsonValue] was rejected while the equivalent generic spelling was accepted.

Fix: the textual scan is replaced by the type-level engine's static acceptance conditions (tyeval::accept::classify — GHC Paterson/Coverage analogues):

• Accepted: self-references beneath a type constructor with non-growing arguments — type J = list[J], type J = int | list[J], type J = dict[str, J], both JsonValue orderings from this issue, and the tuple["RecursiveTuple", ...] forward-ref spelling.
• Still rejected: unguarded self-reference (type X = X, type X = int | X — union arms do not guard, matching upstream conformance), non-regular growing self-applications, transparent Union[...]/Optional[...]/Annotated[...] spellings of the same, and mutual bare-name cycles.

Verification (all run today, green):

• Pins in tests/checker/generics_syntax_scoping_tests.rs (13 tests: guarded accepted, unguarded rejected, transparent spellings, mutual cycles, exactly-one-diagnostic).
• New in tests/checker/aliases_recursive_tests.rs: PEP 695 type-statement counterparts of every recursive definition in upstream aliases_recursive.py (Json/Json2, RecursiveTuple, RecursiveMapping, both generic aliases + specialization) pinned clean, and both upstream # E: cyclical cases pinned firing — the upstream file has zero type statements, which is how this FP survived a 100% score.
• End-to-end: the new torture scoreboard case benchmarks/torture/cases/recursive_aliases.py (JsonValue + Tree[T] + required errors on type R3 = R3 / type R4[T] = T | R4[str]) passes against a release binary built from HEAD (benchmarks/torture/status/torture.csv).

The branch has not had a PR CI run yet; the fresh-clone conformance gate re-certifies there. Nothing else remains for this defect.