PE-9132: Turbo free-tier support — allowance-aware upload UX and typed payment failures

docs/implementation_plan_turbo_free_tier.md

@@ -0,0 +1,148 @@
+# Turbo Free-Tier Restriction — ArDrive Client Implementation Plan
+
+## Policy (PE-9132)
+
+- Each wallet receives a **10 MiB free pool**.
+- An upload is free-eligible only when the data item is **≤ 105 KiB (107,520 bytes)** AND the pool has remaining room. Eligible items draw down the pool by their size. ArFS metadata items (~1–2 KiB: renames, moves, creates, hides, pins, license assertions, bulk-import entries, thumbnails metadata) draw from the same pool.
+- When the pool is exhausted, **every** upload is paid — including metadata operations. Purchasing credits does **not** replenish the pool; free and credits are independent.
+- Reset cadence (monthly vs lifetime) is server policy; the client must treat remaining-free as **server-reported state**, never a client-side computation.
+
+## Current client reality (verified inventory, July 2026)
+
+"Free" today is a client-side guess: anything under `allowedDataItemSizeForTurbo`
+(100,000 bytes; `assets/config/*.json:12`) is posted to `POST /v1/tx` with **no
+cost check, no payment header, no quota awareness** (`lib/turbo/services/upload_service.dart:59-106`).
+
+**Fifteen operation paths post silently on this assumption** (all wallet-signed,
+none has payment UI):
+
+| Op | Post site |
+|---|---|
+| File/folder rename | `lib/blocs/fs_entry_rename/fs_entry_rename_cubit.dart:176/:101` |
+| Drive rename | `lib/blocs/drive_rename/drive_rename_cubit.dart:71` |
+| Move (per item!) | `lib/blocs/fs_entry_move/fs_entry_move_bloc.dart:275` |
+| Hide/unhide | `lib/blocs/hide/hide_bloc.dart:330` |
+| Folder create | `lib/blocs/folder_create/folder_create_cubit.dart:85` |
+| Drive create (+root folder) | `lib/blocs/drive_create/drive_create_cubit.dart:134` |
+| Pin file | `lib/blocs/pin_file/pin_file_bloc.dart:337` |
+| License assertion (2/file×rev) | `lib/blocs/fs_entry_license/fs_entry_license_bloc.dart:320` |
+| Ghost fixer | `lib/blocs/ghost_fixer/ghost_fixer_cubit.dart:141` |
+| ArNS name revision | `lib/arns/domain/arns_repository.dart:196` |
+| Thumbnail metadata | `lib/drive_explorer/thumbnail/repository/thumbnail_repository.dart:210` |
+| Private-drive migration | `lib/shared/blocs/private_drive_migration/private_drive_migration_bloc.dart:134` |
+| Bulk import folder meta (per folder) | `lib/core/arfs/use_cases/upload_folder_metadata.dart:81` |
+| Bulk import file meta (per file) | `lib/core/arfs/use_cases/upload_file_metadata.dart:80` |
+| Snapshot create (has payment UI already) | `lib/blocs/create_snapshot/create_snapshot_cubit.dart:693` |
+
+**Known failure behavior on payment rejection today** (nothing decodes 402/429):
+
+- Rename: progress dialog never dismisses (`fs_entry_rename_form.dart:76-137` has no failure case).
+- Move: no failure state at all (`fs_entry_move_state.dart`), progress dialog hangs; **DB commits BEFORE the network post** (`fs_entry_move_bloc.dart:261-279`) → local state diverges from chain on rejection.
+- Chunked uploader retries any failure **8×** including payment rejections (`packages/ardrive_uploader/lib/src/turbo_upload_service.dart:28,99-100`).
+- App-side `TurboUploadService._handleException` special-cases only 408 (`upload_service.dart:108-129`); everything else becomes a generic `Exception`.
+- No quota/allowance API is consumed anywhere; balance response (`payment_service.dart:77`) has no free-tier fields today.
+
+## Budget math (why per-op UX must be silent)
+
+- Metadata op ≈ 2 KiB → the 10 MiB pool covers ~5,000 metadata operations.
+- A single 105 KiB file consumes ~50 metadata-ops worth of pool; ~97 max-size files exhaust the pool.
+- Bulk import of a 1,000-file manifest ≈ 2 MiB of pool in one click. Folder
+  uploads of many small files can exhaust the pool in one action.
+- Conclusion: prompting per metadata op is unacceptable (dust); prompting per
+  BURST (bulk import, folder upload) with a pool-aware preflight is required.
+
+## Phase 1 — Failure honesty (policy-independent; build first, no server dependency)
+
+1. **Typed payment errors.** In both TurboUploadServices: decode HTTP 402 (and
+   distinguish free-exhausted vs insufficient-credits when the server provides a
+   reason code) into `TurboPaymentRequiredException`; decode 429 into a typed
+   rate-limit error. Exclude both from blind retry (`retryIf`).
+2. **Fix the stuck dialogs.** Add failure states + dialog handling for Rename
+   (both file/folder) and Move; generic message now, payment-specific once
+   Phase 2 lands.
+3. **Move: post-then-commit.** Reorder `fs_entry_move_bloc` so network posts
+   succeed before DB writes commit (or wrap in a rollback) — fixes the
+   divergence bug independent of any free-tier change.
+4. **Tests:** unit tests for error decoding; bloc tests for rename/move failure
+   states; regression test that a 402 is not retried.
+
+## DECISION (2026-07-15, after review with Turbo team)
+
+Phase 1 green-lit. The balance-endpoint remaining-free dependency and the
+dynamic pool meter are DROPPED: no pool tracking client-side. Instead:
+- **Static free-tier messaging** — when a post is rejected with 402, show a
+  static explanation ("free allowance is used up — add Credits") with the
+  top-up path. No live "X MiB remaining" anywhere.
+- **`maxItemBytes` from `GET /v1/info`** is kept as the server-driven
+  per-item eligibility threshold (implemented:
+  `TurboUploadService.maxFreeItemSizeBytes`, fetched once at construction,
+  config value as fallback). Follow-up: consume it in
+  `UploadPaymentEvaluator` in place of `allowedDataItemSizeForTurbo`.
+- Typed-402 handling everywhere (Phase 1) is the backbone of the UX.
+
+The original Phase 2/3 below is retained for reference but is NOT the
+current plan; only the pieces named above survive.
+
+## Phase 2 — Pool-aware eligibility (SUPERSEDED by decision above)
+
+**Server asks (blockers for this phase, not Phase 1):**
+- Remaining-free bytes (+ reset timestamp if any) on the existing balance
+  endpoint (`GET /v1/account/balance/arweave`) — client already polls it.
+- Deterministic 402 with machine-readable reason: `free_exhausted` |
+  `insufficient_credits`.
+- Confirm per-item eligibility threshold (105 KiB) is queryable or stable.
+
+**Client work:**
+1. **`TurboConditionsService`** (new, `lib/turbo/`): caches
+   `{creditBalance, freeRemainingBytes, freeItemLimit=107520}`; refreshed on
+   login, after every upload, and immediately on any 402. Single source of
+   truth; all "is this free?" questions go here.
+2. **Retire the client-side constant as authority.** `allowedDataItemSizeForTurbo`
+   (100 KB) becomes the fallback for the item-size gate only (bump to 107,520);
+   eligibility = size-gate AND `freeRemainingBytes >= itemSize`.
+3. **Decision ladder for every post** (file uploads AND all 15 metadata paths):
+   - free-covered → post silently (pool decremented server-side; client
+     decrements optimistically, reconciles on next balance poll)
+   - credits cover it → post silently for dust-sized metadata; show cost line
+     for user-perceivable sizes (uploads keep existing payment UI)
+   - neither → pre-flight prompt with top-up flow (replaces today's hang)
+   - server 402 anyway (stale cache) → typed error → refresh conditions → one
+     honest dialog, never blind retry
+4. **Payment evaluator changes** (`lib/core/upload/uploader.dart:379-382,
+   :464-476, :534-564`; `upload_payment_method_bloc.dart:111-137`):
+   `isFreeUploadPossibleUsingTurbo` must consult the conditions service, not
+   just size. Multi-file: free only if the whole plan fits remaining pool;
+   otherwise split display (N free / M paid) or fall to paid entirely
+   (simpler v1: all-or-nothing per upload plan).
+5. **Burst preflight.** Bulk import (`bulk_import_files.dart`) and folder
+   uploads estimate total bytes against the pool up front: "This import needs
+   2.1 MiB; you have 0.8 MiB free — the rest uses ~0.0004 credits
+   [Continue] [Top up]". On mid-burst exhaustion: pause-and-resume, not
+   fail-halfway (bulk import's failure tracking is the foundation).
+
+## Phase 3 — Surfacing (UX)
+
+- FREE badge (`upload_form.dart:1937-1948`, `create_snapshot_dialog.dart:431`)
+  becomes dynamic: "Free — X MiB left" / absent when exhausted.
+- Pool meter + low-pool nudge in the profile card next to credits
+  (`profile_card.dart:568-592` area); "free used up — everything now uses
+  credits" one-time notice on the free→paid transition.
+- Onboarding guard: drive-create is a new wallet's first action (~2 KiB). With
+  a fresh 10 MiB pool this always succeeds; the dead-end only exists for
+  exhausted wallets — those get the pre-flight prompt, never a hang.
+
+## Explicit non-goals / accepted
+
+- No client-side enforcement (abusers bypass the app; enforcement is Turbo's).
+  Client goals: honest UX for legitimate users + never amplifying rejected
+  load (no 402 retries).
+- No hardcoded reset cadence; display whatever the server reports.
+- L1 (direct Arweave) fallback for metadata ops remains available where it
+  exists today (rows 1–10, 13–14) for users who prefer paying AR — unchanged.
+
+## Sequencing
+
+Phase 1 is unblocked today and ships value regardless of policy timing.
+Phase 2 blocks on the two server asks. Phase 3 rides Phase 2. Estimated:
+Phase 1 ≈ 2–4 days incl. tests; Phase 2 ≈ 1 week client-side once the API
+contract exists; Phase 3 ≈ 2–3 days.

lib/arns/presentation/assign_name_bloc/assign_name_bloc.dart

@@ -1,4 +1,5 @@
 import 'package:ardrive/arns/domain/arns_repository.dart';
+import 'package:ardrive/turbo/services/upload_service.dart';
 import 'package:ardrive/arns/utils/arns_address_utils.dart';
 import 'package:ardrive/authentication/ardrive_auth.dart';
 import 'package:ardrive/pages/drive_detail/models/data_table_item.dart';
@@ -187,7 +188,7 @@ class AssignNameBloc extends Bloc<AssignNameEvent, AssignNameState> {
         ));
       } catch (e, stackTrace) {
         logger.e('Failed to confirm ArNS name assignment', e, stackTrace);
-        emit(SelectionFailed());
+        emit(SelectionFailed(isPaymentError: isTurboPaymentError(e)));
       }
     });
 

lib/arns/presentation/assign_name_bloc/assign_name_state.dart

@@ -91,7 +91,13 @@ final class SelectionConfirmed extends AssignNameState {
 
 final class LoadingUndernames extends AssignNameState {}
 
-class SelectionFailed extends AssignNameState {}
+class SelectionFailed extends AssignNameState {
+  final bool isPaymentError;
+  const SelectionFailed({this.isPaymentError = false});
+
+  @override
+  List<Object?> get props => [isPaymentError];
+}
 
 final class LoadingNamesFailed extends AssignNameState {}
 

lib/arns/presentation/assign_name_modal.dart

@@ -1,6 +1,8 @@
 // ignore_for_file: unnecessary_string_escapes, unused_element
 
 import 'package:ardrive/arns/domain/arns_repository.dart';
+import 'package:ardrive/utils/app_localizations_wrapper.dart';
+import 'package:ardrive/components/turbo_payment_required_dialog.dart';
 import 'package:ardrive/arns/presentation/assign_name_bloc/assign_name_bloc.dart';
 import 'package:ardrive/arns/presentation/create_undername.dart';
 import 'package:ardrive/authentication/ardrive_auth.dart';
@@ -124,6 +126,9 @@ class _AssignArNSNameModalState extends State<_AssignArNSNameModal> {
 
     return BlocConsumer<AssignNameBloc, AssignNameState>(
       listener: (previous, current) {
+        if (current is SelectionFailed && current.isPaymentError) {
+          showTurboPaymentRequiredDialog(context);
+        }
         if (current is NameAssignedWithSuccess) {
           showArDriveDialog(
             context,
@@ -345,7 +350,10 @@ class _AssignArNSNameModalState extends State<_AssignArNSNameModal> {
                     ArDriveTheme.of(context).themeData.colorTokens;
                 return Center(
                   child: Text(
-                    'Error assigning ArNS name. Please try again later',
+                    state.isPaymentError
+                        ? appLocalizationsOf(context)
+                            .freeAllowanceUsedUpDescription
+                        : 'Error assigning ArNS name. Please try again later',
                     style: typography.paragraphLarge(
                       color: colorTokens.textMid,
                     ),

lib/blocs/bulk_import/bulk_import_bloc.dart

@@ -1,6 +1,7 @@
 import 'dart:async';
 
 import 'package:ardrive/authentication/ardrive_auth.dart';
+import 'package:ardrive/turbo/services/upload_service.dart';
 import 'package:ardrive/blocs/bulk_import/bulk_import_event.dart';
 import 'package:ardrive/blocs/bulk_import/bulk_import_state.dart';
 import 'package:ardrive/core/arfs/use_cases/bulk_import_files.dart';
@@ -128,9 +129,15 @@ class BulkImportBloc extends Bloc<BulkImportEvent, BulkImportState> {
       return;
     } catch (e) {
       logger.e('Error during bulk import', e);
+      final paymentError = _isBulkImportPaymentError(e);
       emit(BulkImportError(
-        'An unexpected error occurred during the import process. Please try again.',
+        paymentError
+            ? 'Your free upload allowance has been used up. Add Credits to '
+                'continue importing.'
+            : 'An unexpected error occurred during the import process. '
+                'Please try again.',
         e,
+        paymentError,
       ));
     }
   }
@@ -182,6 +189,8 @@ class BulkImportBloc extends Bloc<BulkImportEvent, BulkImportState> {
   }) async {
     var processedFiles = 0;
     final failedPaths = <String>[];
+    Object? lastImportError;
+    BulkImportResult? importResult;
 
     try {
       emit(BulkImportInProgress(
@@ -201,7 +210,7 @@ class BulkImportBloc extends Bloc<BulkImportEvent, BulkImportState> {
         return;
       }
 
-      await _bulkImportFiles(
+      importResult = await _bulkImportFiles(
         driveId: driveId,
         parentFolderId: parentFolderId,
         files: files,
@@ -244,15 +253,26 @@ class BulkImportBloc extends Bloc<BulkImportEvent, BulkImportState> {
     } catch (e) {
       failedPaths.add(files.first.path);
       logger.e('Failed to import file: ${files.first.path}', e);
+      lastImportError = e;
     }
 
     final totalFiles = files.length;
     final successfulFiles = processedFiles;
     final failedFiles = failedPaths;
 
     if (successfulFiles == 0) {
-      emit(const BulkImportError(
-        'Failed to import any files. Please check the manifest and try again.',
+      final paymentError = _isBulkImportPaymentError(lastImportError) ||
+          (importResult?.failures.any(
+                  (f) => _isBulkImportPaymentError(f.originalError)) ??
+              false);
+      emit(BulkImportError(
+        paymentError
+            ? 'Your free upload allowance has been used up. Add Credits to '
+                'continue importing.'
+            : 'Failed to import any files. Please check the manifest and '
+                'try again.',
+        lastImportError,
+        paymentError,
       ));
     } else {
       emit(BulkImportSuccess(
@@ -289,3 +309,16 @@ class BulkImportBloc extends Bloc<BulkImportEvent, BulkImportState> {
     emit(const BulkImportInitial());
   }
 }
+
+/// Detects a Turbo payment rejection inside bulk-import failures. Metadata
+/// upload use-cases wrap the original exception in
+/// FileMetadataUploadException/FolderMetadataUploadException.
+bool _isBulkImportPaymentError(Object? error) {
+  if (isTurboPaymentError(error)) return true;
+  try {
+    final dynamic e = error;
+    return isTurboPaymentError(e.originalError);
+  } catch (_) {
+    return false;
+  }
+}

lib/blocs/bulk_import/bulk_import_state.dart

@@ -117,11 +117,12 @@ class BulkImportSuccess extends BulkImportState {
 class BulkImportError extends BulkImportState {
   final String message;
   final Object? error;
+  final bool isPaymentError;
 
-  const BulkImportError(this.message, [this.error]);
+  const BulkImportError(this.message, [this.error, this.isPaymentError = false]);
 
   @override
-  List<Object?> get props => [message, error];
+  List<Object?> get props => [message, error, isPaymentError];
 }
 
 class BulkImportResolvingPaths extends BulkImportState {

lib/blocs/create_manifest/create_manifest_cubit.dart

@@ -1,6 +1,9 @@
 import 'dart:async';
 
 import 'package:ardrive/arns/domain/arns_repository.dart';
+import 'package:ardrive/manifest/domain/exceptions.dart';
+import 'package:ardrive/turbo/models/free_upload_status.dart';
+import 'package:ardrive/turbo/services/upload_service.dart';
 import 'package:ardrive/authentication/ardrive_auth.dart';
 import 'package:ardrive/blocs/blocs.dart';
 import 'package:ardrive/blocs/upload/models/payment_method_info.dart';
@@ -110,7 +113,7 @@ class CreateManifestCubit extends Cubit<CreateManifestState> {
         (state as CreateManifestUploadReview).copyWith(
           uploadMethod: method,
           canUpload: canUpload,
-          freeUpload: info.isFreeThanksToTurbo,
+          freeStatus: info.freeStatus,
           assignedName: (state as CreateManifestUploadReview).assignedName,
           fallbackTxId: (state as CreateManifestUploadReview).fallbackTxId,
         ),
@@ -493,7 +496,8 @@ class CreateManifestCubit extends Cubit<CreateManifestState> {
   @override
   void onError(Object error, StackTrace stackTrace) {
     logger.e('Failed to create manifest', error, stackTrace);
-    emit(CreateManifestFailure());
+    final wrapped = error is ManifestCreationException ? error.error : error;
+    emit(CreateManifestFailure(isPaymentError: isTurboPaymentError(wrapped)));
     super.onError(error, stackTrace);
   }
 }