EP-0145: Type Safety & Contract Hardening¶

Abstract¶

The Grand Council Assessment (Golem) identified type annotation compatibility risks across Python 3.10–3.14, inconsistent semiring parameter contracts (instance vs. class factory), and a flawed collision branch in flat_to_nested. This proposal hardens type safety and explicit contracts.

Motivation¶

algebrax achieves pristine functional purity and zero mutable state — a rare quality. However, three contract-level issues create subtle correctness risks: recursive TypeAlias forward references may fail runtime introspection on Python 3.10–3.11, semiring parameters accept either instances or class types inconsistently across modules, and flat_to_nested silently corrupts on mixed-depth key collisions.

Specification¶

1. Forward-Compatible Type Annotations (algebrax/typing.py)¶

Added from __future__ import annotations to ensure the recursive SparseTensor TypeAlias:

SparseTensor: TypeAlias = Mapping[K, 'SparseTensor[K, V] | V']

evaluates correctly under typing.get_type_hints() across Python 3.10–3.14.

2. Semiring Parameter Normalization¶

Created private helper _normalize_semiring() and applied across modules:

def _normalize_semiring(s: Semiring[V] | type[Semiring[V]] | None) -> Semiring[V]:
    """Normalize semiring argument to an instance, handling class factories and None."""
    if s is None:
        return StandardSemiring()
    return s() if isinstance(s, type) else s

Applied in: - semiring/_base.py and exported in semiring/__init__.py - analysis.py: verify_nilpotency, hodge_laplacian, SparseChainComplex - category.py: kleisli_compose, kan_extension_left - homology.py: SparseChainComplex

3. Fix flat_to_nested Collision Handling (converters.py)¶

Replaced flawed fallback branch with explicit validation:

if key not in current:
    current[key] = {}
elif not isinstance(current[key], dict):
    raise ValueError(
        f"Key collision: cannot nest dict under existing non-dict leaf at {keys[: i + 1]}"
    )

4. Enforce Parameterized Generic Types¶

Audited and updated all unparameterized usages of SparseMatrix and SparseVector across homology.py, category.py, converters.py, and analysis.py.

Falsifiable Invariants¶

• typing.get_type_hints(algebrax.typing) resolves without errors on Python 3.10–3.14.
• _normalize_semiring(TropicalSemiring) and _normalize_semiring(TropicalSemiring()) both return a valid TropicalSemiring instance.
• flat_to_nested({(1,): 'a', (1, 2): 'b'}) raises ValueError instead of silent corruption.
• All 306 unit tests pass.

Backwards Compatibility¶

• _normalize_semiring is private (no public API change).
• flat_to_nested now raises ValueError on previously-undefined collision behavior — this is a correctness fix, not a breaking change.
• Type annotation changes are non-behavioral.

Change Log¶

• 2026-08-02: Initial Draft from Grand Council Assessment (Golem).
• 2026-08-05: Fully implemented from __future__ import annotations in typing.py, _normalize_semiring helper in _base.py, explicit ValueError in flat_to_nested(), parameterized types across homology.py and category.py, and added test suite test_type_safety.py. Status → Final.