Om/logic correction

[Omprakash-48]

Summary

Brings om/logic_correction up to date with the offline-first work. This PR
bundles four threads of work that landed together on this branch:

1. A dedup refactor that extracts repeated patterns into shared helpers
   (no behavior change).
2. Initial-sync hardening — closes a schema-creation gap and makes boot
   sync resilient and observable.
3. New host-facing extension points (payload transform, validation
   callback, retry/error surfaces).
4. Offline-sync correctness fixes for issues A4: Push/pull race on same doctype (asymmetric guard) #43, A12: Push-only sync mode on SyncController #47, S3: Persist initial-sync cursor position to SQLite to enable resumable pull after app termination #64, and A7: Use /syncDetails pre-flight to skip no-op doctype pulls #49.

Plus a logging cleanup (print() → sdkLog).

Net: 83 files, +2635 / −1365, 18 test files added/changed.

---

1. Refactor — shared helpers (no behavior change)

Consolidates repeated patterns into single sources of truth:

• utils/date_helpers.dart — parseDateTime / parseTime /
  formatDurationSeconds shared by date/datetime/duration fields and the
  form-builder patch normaliser.
• utils/frappe_json_utils.dart — parseBool: canonical 0/1/'true'/bool
  coercion for every model fromJson.
• utils/sql_row_utils.dart — retryCountFrom, lastAttemptAtFrom,
  utcMillisFrom, parseEnumByName for sqflite row factories.
• ui/widgets/fields/field_helpers.dart — requiredValidator,
  baseFieldDecoration, fieldErrorText shared by every Form*Field.
• ui/widgets/screen_helpers.dart — showStatusSnackBar + showConfirmDialog
  replace ad-hoc SnackBar/Dialog construction.
• database/schema/system_columns.dart — systemSyncMetadataColumnNames +
  linkCompanionColumnDDL consumed by PayloadAssembler/Serializer and the
  schema builders so strip rules can't diverge.
• query_result.dart — QueryResult.ofRows derives hasMore/returnedCount
  for online/offline parity in UnifiedResolver.

2. Initial-sync hardening + schema-gap fix

• _runUpgradeClosurePull now calls ensureSchemaForClosure before the
  closure pull, closing the "no such table" hole that previously forced SNF's
  runSnfPostSdkSync to re-pull.
• Boot pull is bracketed with isInitialSync=true so host UI subscribed to
  state$ can render a syncing indicator (reset on every exit path).
• Boot failures surfaced via SyncStateNotifier.lastError
  (code: 'network' | 'permissions'); added retryInitialMetaAndDataSync();
  lastError cleared on logout.
• Parent/child schema DDL uses CREATE TABLE/INDEX IF NOT EXISTS so eager pull
  and SNF's belt-and-suspenders reconcile can re-enter safely after a partial
  failure.
• PullEngine stall guard scoped to incremental (complete=true);
  initial sync uses limit_start offset pagination, which always advances.
• Boot/splash probes can fast-fail: RestHelper.get/getPublic expose per-call
  timeout / maxRetries overrides instead of burning the default 30s × 3.
• MobileHomeScreen suppresses the full-screen spinner on background
  syncComplete$ reloads — only shown on first paint when the list is empty.

3. New host-facing extension points

• PushEngine — optional PayloadTransformerFn between assembly and HTTP
  dispatch (e.g. host auto-submit on sync); exception-safe. Exported from the
  barrel.
• FrappeFormBuilder.onValidationFailed — lets parents stop loading
  indicators when a submit is rejected.
• FrappeFormBuilder ??=-injects linkOptionService / linkFieldCoordinator
  on a host-supplied customFieldFactory so Link pickers aren't
  half-configured.
• PullEngine — optional SchemaReconcilerFn wired to
  OfflineRepository.reconcileParentTableForMeta so ALTER ADD COLUMN runs
  before applying a page (closes the meta-cache race).

4. Offline-sync correctness fixes

• A4: Push/pull race on same doctype (asymmetric guard) #43 (push/pull race): PullApply matches a pulled parent by
  mobile_uuid when server_name isn't stamped locally yet, preventing
  duplicate rows during an in-flight push INSERT (reconcile, no false conflict).
  The hasActivePushFor defer is extended to SyncService pull paths via
  SyncStatus.deferredActivePush (parity with PullEngine).
• A12: Push-only sync mode on SyncController #47 (sync modes): SyncMode {full, pushOnly, pullOnly} on
  SyncController.syncNow (default full = existing behavior).
• S3: Persist initial-sync cursor position to SQLite to enable resumable pull after app termination #64 (resumable pull): PullEngine checkpoints its cursor
  (complete:false) after every applied page, so an app-kill mid initial-sync
  resumes from the last page instead of page 0.
• A7: Use /syncDetails pre-flight to skip no-op doctype pulls #49 (pre-flight manifest): DoctypeService.getSyncDetails + pure
  doctypesToSkip, wired into _runUpgradeClosurePull to skip unchanged
  INCREMENTAL doctypes, with graceful full-pull fallback on any failure.

5. Logging cleanup

Routes stray print() diagnostics through sdkLog (a no-op in release builds)
and drops the // ignore: avoid_print suppressions. No behavioral change.

---

Testing

• flutter analyze — clean.
• flutter test — 1333 passing.
• New coverage includes: sync_details (client + doctypesToSkip), SyncMode,
  active-push defer, pull_apply mobile_uuid matching, cursor resume,
  payload-transform, validation-failed callback, reserved-word column DDL, and
  field-style defaults.

Notes for reviewers

• The refactor (section 1) and logging (section 5) are behavior-neutral and can
  be skimmed; review attention is best spent on sections 2–4.
• This branch was merged with om/offline_improvement and develop multiple
  times; conflict resolutions favored the refactored single-source helpers
  while preserving the offline correctness fixes (deadlock retry, DDL
  identifier quoting, schema healing).