universal_storage_sync library
Universal Storage Sync - A cross-platform Dart package for unified file storage operations
Classes
- AuthorInfo
- Information about a commit author.
- CloudKitConfig
- Configuration for the CloudKit storage provider.
- CommitInfo
- Information about a version control commit.
- DecisionStore
- Persistence interface for kernel decision states.
- FileDiff
- Represents changes to a file between two commits.
- FileEntry
- Represents an entry in a directory listing.
- FileOperationResult
- Unified result for file operations (create/update/delete).
- FileSystemConfig
- Configuration for the file system storage provider.
- GitHubApiConfig
- InMemoryDecisionStore
- Default in-memory decision state store.
- InMemoryStorageProfileResolver
- In-memory resolver for profile-based routing.
- InMemorySyncQueueStore
- In-memory queue persistence.
- LocalDbStorageConfig
- Configuration for the local database storage provider.
- LocalEngine
- Marker interface for local storage engines.
- MigrationEndpoint
- Optional migration endpoint capability for providers/bridges.
- MigrationExecutionResult
- Result of migration execution.
- MigrationPlan
- Immutable migration plan descriptor.
- MigrationPreparationResult
- Result of the preflight phase before applying migration.
- OfflineGitConfig
- RemoteEngine
- Remote storage engine with capability declaration.
- StorageCapabilities
- Provider capability set used for profile negotiation.
- StorageCompatibilityEvidence
- Compatibility evidence from versioned tests.
- StorageCompatibilityPolicy
- Compatibility policy for profile and migration schemas.
- StorageConfig
- Base class for all storage configurations.
- StorageDebugBundleCollector
- Collects storage observations into a debug bundle and observability summary.
- StorageDecision
- User-facing decision item for complex mode conflict/migration resolution.
- StorageDeprecationItem
- Deprecation schedule item with owner/date.
- StorageKernel
- Profile-aware storage kernel.
- StorageKernelContract
- Profile-aware kernel contract.
- StorageNamespace
- Logical namespace used to separate storage domains.
- StorageNamespaceProfile
- Per-namespace profile binding for local/remote engines and policies.
- StorageObjectId
- Stable logical object id independent from backend-specific paths.
- StorageObservabilityEvidence
- Observability readiness evidence.
- StorageObservationEvent
- Observation event emitted by kernel operations.
- StorageOperationResult
- Generic operation result used by kernel workflows.
- StoragePerformanceBudgets
- Performance thresholds enforced by Gate G6.
- StoragePerformanceEvidence
- Collected benchmark evidence for release candidate validation.
- StorageProfile
- Profile describing namespace routing and policy for one application/workspace.
- StorageProfileLoader
- Loads StorageProfile payloads and wires them into StorageKernel.
- StorageProfileLoadResult
- Result of loading a profile into a ready StorageKernel.
- StorageProfileMigrationEndpoint
-
Adapter that exposes migration management as a
MigrationEndpoint. - StorageProfileMigrationManager
- Runtime that migrates data from one profile/kernel to another with checkpoints and optional rollback.
- StorageProfileResolver
- Resolves profile namespaces to configured storage services.
- StorageProvider
- Provider-agnostic contract for storage operations.
- StorageProviderRegistry
-
Registry for provider factories keyed by
StorageConfigtype. - StorageReleaseChecklistItem
- Release checklist item with owner accountability.
- StorageReleaseGateEvaluator
- Evaluates hardening evidence and returns Gate G6 pass/fail status.
- StorageReleaseGateFinding
- Structured gate finding for CI and release pipelines.
- StorageReleaseGateInput
- All inputs required to evaluate Gate G6.
- StorageReleaseGateReport
- Gate G6 evaluation output.
- StorageReliabilityCriteria
- Reliability thresholds for soak and recovery validation.
- StorageReliabilityEvidence
- Measured reliability evidence from hardening runs.
- StorageRollbackDrillRecord
- Rollback rehearsal record.
- StorageSecurityControl
- Security checklist entry required by Gate G6.
- StorageService
- A service class providing a unified API for file storage operations using a configured StorageProvider.
- StorageServiceDecisionStore
- Storage-backed decision store for durable conflict history.
- StorageServiceKernelAdapter
-
Compatibility adapter exposing
StorageService-like API on top of profile-aware StorageKernel. - StorageServiceSyncQueueStore
- Storage-backed queue store that survives process restarts.
- StorageStructuredLogEntry
- Structured log representation for storage observations.
- SyncConflictEntry
- Staged conflict item bound to one outbox entry.
- SyncEngine
- Optional sync orchestrator that can be plugged into kernel.
- SyncOutboxEntry
- Durable outbox entry used for optimistic replay.
- SyncQueuePolicy
- Retry/backoff policy for namespace outbox replay.
- SyncQueueState
- Queue state persisted per namespace.
- SyncQueueStore
- Durable persistence API for namespace sync queues.
- VcBranch
- VcBranchName
- VcCreateRepositoryRequest
- VcRepository
- VcRepositoryName
- VcRepositoryOwner
- VcRepositorySlug
- VcUrl
- VersionControlCapabilities
- Capability set for provider-specific version control features.
- VersionControlService
- WorkingDirectoryStatus
- Status of the working directory in version control.
Enums
- CloudKitDatabaseScope
- CloudKit database scope for v1 provider surface.
- CloudKitDataMode
- CloudKit data mode for universal storage behavior.
- CloudKitEnvironment
- CloudKit runtime environment.
- ConflictResolutionStrategy
- Conflict resolution strategies for sync operations.
- DecisionState
- Decision lifecycle for sync/migration operations.
- FileChangeType
- Types of changes that can occur to a file.
- MigrationDecisionAction
- Explicit per-operation migration action used by complex conflict workflows.
- MigrationStatus
- Runtime status of a migration plan execution.
- ProviderType
- Enumeration of supported storage provider types.
- StorageDeprecationStage
- Deprecation stage for a legacy API/path.
- StorageObservationType
- Event kind emitted by StorageKernelContract.observe.
- StorageOperationOrigin
- Event source origin.
- StoragePolicy
- Namespace sync/write behavior policy.
- StorageReleaseGateSeverity
- Severity for gate findings.
- StorageReleaseGateStatus
- Final status for Gate G6 hardening/release checks.
- StorageSecurityControlStatus
- Status for one security control item.
- SyncInteractionLevel
- Interaction layer for sync and migration decisions.
- SyncQueueOperationType
- Local operation type staged in namespace outbox.
- SyncStatus
- Represents the synchronization status between local and remote repositories.
Mixins
- AuthenticatedProvider
- Mixin providing common authentication functionality for storage providers. Reduces code duplication for authentication checks and token management.
- PathNormalizer
- Utility class for normalizing file paths across different storage providers. Each provider may have different path requirements and conventions.
- RemoteSyncCapable
- Mixin for storage providers that support remote synchronization. Provides standardized sync operations and conflict resolution.
- RetryableOperation
- Utility class for executing operations with retry logic. Provides exponential backoff and custom retry conditions.
- StorageFactory
- Factory class for creating configured storage services. Automatically determines the provider type based on configuration and returns a ready-to-use StorageService.
- VersionControlCapable
- Mixin for storage providers that support version control operations. Provides standardized version control functionality like commits, history, and branching.
Extension Types
- FileExtension
- Extension type that represents a file extension with type safety.
- FilePath
- Extension type that wraps a file system path string.
- FilePathConfig
- Extension type that represents the workspace path configuration.
- MacOSBookmark
- A security-scoped bookmark for a file or directory on macOS.
Functions
-
fileNormalizedSha256Hex(
StorageService storage, String path) → Future< String> -
Read a file via
storageand return normalized SHA-256 hex. Returns empty string if file doesn't exist. -
migrationDecisionActionFromString(
Object? value) → MigrationDecisionAction? -
normalizeContent(
String input) → String - Normalize content by trimming trailing whitespace and collapsing CRLF.
-
normalizedSha256Hex(
String input) → String - Compute normalized SHA-256 (hex) for string content.
-
sha256Hex(
String input) → String - Lightweight hashing helpers for sync workflows. Pure functions suitable for extraction into a shared utils package. Compute SHA-256 hash (hex) for a string.
Typedefs
-
ConflictDecisionHook
= FutureOr<
DecisionState> Function(SyncConflictEntry conflict) - Optional callback for custom conflict decision routing.
-
NamespaceCapabilitiesFactory
= Future<
StorageCapabilities> Function(StorageNamespaceProfile namespaceProfile, StorageService service) - Optional function resolving runtime capabilities for a namespace service.
-
NamespaceServiceFactory
= Future<
StorageService> Function(StorageNamespaceProfile namespaceProfile) - Factory function that builds a storage service for one namespace profile.
Exceptions / Errors
- AuthenticationException
- Authentication-related error.
- AuthenticationFailedException
- CapabilityMismatchException
- Requested capability is not available for current backend/profile.
- ConfigurationException
- DecisionRequiredException
- Operation requires explicit user decision (complex mode flow).
- FileAlreadyExistsException
- File exists error.
- FileNotFoundException
- File not found error.
- GitConflictException
- Git conflict error.
- GitHubApiException
- GitHub API specific exceptions
- GitHubRateLimitException
- MergeConflictException
- MigrationException
- Base migration exception.
- MigrationExecutionException
- MigrationPreparationException
- MigrationRollbackException
- NetworkException
- Network error.
- NetworkTimeoutException
- RemoteAccessDeniedException
- RemoteNotFoundException
- Remote operation exceptions
- RepositoryCreationException
- StorageException
- Base exception for all storage-related errors.
- SyncConflictException
- Sync conflict error.
- UnsupportedOperationException
- Operation not supported error.