Add comprehensive audit report and improve code quality

[amavashev]

Summary

This PR adds a comprehensive audit report documenting full protocol conformance with Cycles Protocol v0.1.23, and makes targeted code quality improvements across the codebase.

Key Changes

Documentation & Audit

• AUDIT.md: Added comprehensive 169-line audit report verifying:
  • All 9 endpoints match spec (paths, HTTP methods, parameters)
  • All 6 request schemas and 10 response schemas match spec JSON keys
  • All 5 enum types and nested object schemas are protocol-conformant
  • Auth headers, idempotency handling, subject validation, and lifecycle orchestration all follow spec normative rules
  • Verdict: Client is fully protocol-conformant with zero open issues

Code Quality & Linting

• Import organization: Moved Callable from typing to collections.abc (Python 3.10+ best practice) across decorator.py and lifecycle.py
• Line length compliance: Reformatted long lines to respect 120-character limit in:
  • decorator.py: Function signatures and docstrings
  • lifecycle.py: Function signatures and validation calls
  • client.py: Error message formatting
  • retry.py: Logger calls
  • _validation.py: Error messages
• Import cleanup: Removed unused imports in:
  • test_client.py: Removed unused json
  • test_lifecycle.py: Reordered mock imports alphabetically
  • test_retry.py: Reordered mock imports alphabetically
  • config.py & context.py: Removed unused field from dataclass imports
  • examples/: Removed trailing blank lines
• Ruff configuration: Added explicit lint rules (E, F, I, UP) to pyproject.toml

Validation & Testing

• New validation function: Added validate_extend_by_ms() in _validation.py to enforce spec bounds (1–86400000 ms)
• Lifecycle integration: Integrated validate_extend_by_ms() into _build_extend_body() in lifecycle.py
• Test coverage: Added comprehensive test class TestValidateExtendByMs in test_validation.py with 6 test cases

Decorator & Lifecycle Optimization

• Lifecycle caching: Refactored @cycles decorator to cache lifecycle instances at decoration time (deferred client resolution on first call) rather than recreating on every invocation
  • Extracted _build_default_subject() helper function
  • Sync and async paths now use _cached_sync and _cached_async lists to store singleton lifecycle instances
  • Reduces overhead for repeated decorated function calls
• Exception handling: Simplified bare except Exception as ex: to except Exception: in CyclesLifecycle.execute() (unused variable)

CI/CD

• .github/workflows/ci.yml: Added GitHub Actions workflow running:
  • Ruff linting
  • MyPy type checking (strict mode)
  • Pytest test suite
  • On Python 3.10 and 3.12 for all pushes and PRs

Documentation

• README.md: Added "Development" section documenting setup, linting, type checking, and testing commands

Notable Implementation Details

• All changes maintain backward compatibility; no public API modifications
• Lifecycle caching is transparent to users—behavior is identical but more efficient
• Validation of extend_by_ms now happens at both request-building time (lifecycle) and Pydantic model level (for typed requests)
• Audit report serves as living documentation of protocol conformance and can be regenerated as spec evolves

https://claude.ai/code/session_01HXikxwPuurjunotYpbmsE7