ci: evaluate pyrefly as mypy alternative (faster, Pydantic-aware)

[prakashUXtech]

Context

Pyrefly is Meta's Rust-based Python type checker, pyrefly.org. Hit 1.0.0 on 2026-05-12 — powers Instagram's 20M-line Python codebase. MIT-licensed, pip install pyrefly. Claims 15× faster than mypy on PyTorch with sub-10ms IDE rechecks and native Pydantic + Django support.

soul-protocol currently uses mypy>=1.8 and is Pydantic-heavy across runtime/, spec/, eval/, and optimize/. This issue is a planning placeholder to decide whether to swap.

Why bother

• Pydantic-first checking. soul-protocol's core types (identity, journal, retrieval, memory tiers) are Pydantic models. A native-Pydantic checker should produce fewer false positives than mypy + the pydantic.mypy plugin.
• Smaller codebase than pocketpaw — easier to try end-to-end without a partial-adoption seam. A clean cutover here is also a useful data point before any larger rollout.

Concerns to address

• Not a drop-in for mypy. pyrefly init exists; expect adjustments.
• Monthly minor versions ship breaking changes per Meta's own docs. Pin and upgrade deliberately.
• Supply-chain age rule. Workspace policy is 7-day minimum release age. 1.0.0 (2026-05-12) clears around 2026-05-19.

Suggested approach

1. Wait until 2026-05-19 (release age threshold).
2. Add pyrefly alongside mypy in pyproject.toml, pinned. Run both in CI for one PR cycle.
3. pyrefly init + pyrefly check. Triage diagnostics, fix or suppress.
4. If clean, remove mypy in a follow-up PR. CI runs pyrefly only.

Sizing (rough)

• Install + init: ~½ hour
• Triage diagnostics + fixes: 1–3 hours depending on what surfaces
• CI swap: ~½ hour
• Tests: existing suite is the contract

Best guess: S task. ~2–4 agent-hours wall-clock.

Out of scope

• Adopting pyrefly's LSP in the team IDE config
• Cross-repo rollout (pocketpaw tracked separately)

References

• pyrefly.org
• facebook/pyrefly — Rust 79.5% / Python 15.6%, MIT
• Pyrefly in the Agentic Loop — ships its own SKILL.md for Claude Code
• Sister issue: pocketpaw/pocketpaw#1113

[Karman580]

Hi @prakashUXtech , this looks like an interesting and impactful migration task, especially with soul-protocol’s heavy Pydantic usage and the CI implications around type-checking workflows.

I’d love to work on evaluating and integrating pyrefly alongside mypy, including CI setup, diagnostics triage, and documenting any compatibility considerations during the transition phase.

If possible, could you please assign this issue to me? Thanks