syzygy_foundation_flutter 1.2.0

Foundational contracts, primitives, and shared types for the Syzygy Flutter ecosystem

Changelog

All notable changes to syzygy-foundation-flutter are documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

---

Unreleased

Added

Changed

Fixed

---

1.2.0 - 2026-09-18

Fixed

• Restored missing doc comment on NetworkClientProtocol
• Removed stray blank line in AuthProvider

Changed

• CI: Flutter channel pinned to stable, version 3.44.8

---

1.1.0 — 2026-09-03

Changed

• Ecosystem repositioned as AI-enabled cross-platform engineering framework for mobile, web and enterprise
• CI workflow refactored — inline release job removed, release now handled by org-level tag-push workflow
• Lint configuration migrated to Syzygy-Hub/.github/engineering/tooling/
• Lint step reordered to run before build and test
• README updated with ecosystem architecture, shared contracts documentation, and release process

Added

• syzygy.yml confirmed as canonical version source of truth
• Shared contracts section documenting NetworkClientProtocol, AuthProvider, StorageProvider, LoggerProtocol

---

1.0.0 - 2026-08-06

Added

Primitives

• SyzygyID<T> — generic typed identifier wrapping a UUID string; value equality; generate() factory
• SyzygyPage<T> — paginated result wrapper with hasNextPage, hasPreviousPage, isEmpty, totalPages
• PaginationRequest — page number, page size, optional cursor; defaults to page 1, size 20
• SyzygyTimestamp — immutable millisecond-precision Unix-epoch instant; Comparable; toDateTime(); now() factory
• SyzygyDuration — immutable millisecond-precision duration; .fromSeconds, .fromMinutes, .fromHours factories
• TimeProvider — abstract class for injectable clock abstraction
• ValidationResult — Valid / Invalid(messages) sealed class; isValid computed property; ValidationResultX extension
• ValidationRule<T> — abstract single-method validation contract

Contracts — Network

• NetworkMethod — get, post, put, patch, delete, head enum
• NetworkRequest — outgoing request value type; Uint8List body
• NetworkResponse — incoming response value type; isSuccess, isClientError, isServerError
• NetworkClientProtocol — abstract Future<NetworkResponse> execute(NetworkRequest) method

Contracts — Storage

• StorageKey<T> — typed key with identifier and optional defaultValue
• StorageProvider — abstract get/set/remove/clear with serializer/deserializer callbacks

Contracts — Auth

• AuthToken — access token, optional refresh token, optional expiry; isExpired computed property
• AuthState — sealed class: Unauthenticated, Authenticated, AuthExpired, Refreshing; AuthStateX extension
• AuthProvider — Stream<AuthState> + authenticate, refresh, signOut abstract methods

Contracts — Analytics

• AnalyticsEvent — named event with Map<String, Object?> properties and timestamp
• AnalyticsProvider — abstract track, identify, reset contract

Contracts — Logging

• LogLevel — debug, info, warning, error, critical enum
• LogEntry — structured entry with level, message, timestamp, Map<String, String> metadata, optional Exception
• LoggerProtocol — abstract log(entry) + debug, info, warning, error, critical convenience methods

Contracts — Connectivity

• ConnectivityState — connected, disconnected, unknown sealed class with isConnected
• ConnectivityProvider — abstract Stream<ConnectivityState> + isConnected snapshot

Shared Types

• SyzygyEnvironment — debug, staging, production sealed class; isDebug, isProduction
• SyzygyConfiguration — abstract top-level app configuration
• SyzygyBuildInfo — consumer-injected app metadata (name, bundle ID, build number, version)
• SyzygyVersion — semantic version value type; Comparable; SyzygyVersion.current = 1.0.0

Errors

• SyzygyErrorSeverity — info, warning, error, critical enum
• SyzygyErrorCode — typed error code; predefined: unknown, cancelled, timeout, unauthenticated, forbidden, notFound, serverError, networkUnavailable, decodingFailed, encodingFailed
• SyzygyError — abstract class implementing Exception; code, message, severity, underlyingError

Testing (syzygy_foundation_flutter_testing.dart — dev_dependencies only)

• MockLogger — records LogEntry instances; filterable by LogLevel; clear()
• MockConnectivityProvider — StreamController-backed; setState() for test control
• MockAuthProvider — tracks refreshCallCount, signOutCallCount; configurable refreshResult
• MockStorageProvider — in-memory map; accessible for direct assertions
• MockNetworkClient — FIFO response queue; requests list; configurable error
• SpyAnalyticsProvider — records trackedEvents, identifiedUsers, resetCallCount; eventsNamed filter
• FixtureProvider<T> — abstract fixture factory protocol
• FixedTimeProvider — deterministic TimeProvider with mutable fixedTime

Repository

• syzygy.yml manifest added

Changed

• CI lint step now fetches analysis_options.yaml from Syzygy-Hub/.github/main/engineering/tooling/flutter/
• CI coverage step added: flutter test --coverage + lcov line coverage summary written to GITHUB_STEP_SUMMARY
• README rewritten to Syzygy engineering standard