chore(repo): repository preparation prerequisites

[gabriel-sisjr]

Summary

This PR is a round of repository hardening that lands before feature work begins. It restores green iOS CI, aligns the Android retry-jitter implementation with the JS and iOS engines, tightens tooling/DX, makes CI the sole publisher of the package, and refreshes the documentation that drifted from the current codebase.

No public API change. This is library-internal repo prep. The public TypeScript/JS API surface (src/index.tsx facade — 19 functions, 2 listener helpers, 7 hooks, the SyncProvider context, and SyncErrorCode) is unchanged. The only consumer-facing change is a platform requirement: the iOS deployment floor moves from 13.0 to 15.0 (see Reviewer notes / risk).

What & Why

iOS build / CI correctness

• Demote Core Data entities to internal. SyncItemEntity / SyncResultEntity were declared public, so they leaked into the generated Swift bridging header and broke Obj-C translation units (Cannot find interface declaration for NSManagedObject), failing the iOS CI build. They (and their members) are now internal — implementation-only, no public-API impact. The example AppDelegate was updated to call the renamed HybridSyncProvider.handleBackgroundURLSessionEvents.
• Raise the minimum deployment target to iOS 15.0. ios/HTTP/SyncDispatcher.swift already uses URLSession.data(for:) (iOS 15+). The old 13.0 podspec floor only compiled because the example app overrode IPHONEOS_DEPLOYMENT_TARGET; consumers honoring the declared 13.0 floor would hit an availability compile error. The podspec floor (both s.platforms and test_spec.platforms) is now 15.0, and the now-always-true #available(iOS 13.0) / @available(iOS 13.0) guards in SyncDispatcher.swift and BackgroundSyncManager.swift were removed as dead code.

Android retry-jitter correctness

• Align Android jitter to equal-jitter [0.75, 1.25). The Android RetryPolicyEvaluator previously applied full jitter over [0, capped] and capped before jittering, collapsing delays toward 0 and diverging from the other two engines. It now jitters the raw delay (raw * (0.75 + random.nextDouble() * 0.5)) and caps afterwards, matching JS (src/utils/retryBackoff.ts) and iOS (ios/Retry/RetryPolicyEvaluator.swift). The RetryPolicy TSDoc in src/types/sync.ts was aligned and seeded-Random unit tests were added.

Tooling / DX

• Tighten lint/tsc/turbo config. ESLint now ignores nitrogen/, website/build/, website/.docusaurus/, and coverage/. tsconfig.json enables incremental + tsBuildInfoFile (faster pre-commit tsc), while tsconfig.build.json keeps incremental: false. The unused test task was removed from turbo.json.

Release / CI pipeline

• Make CI the sole publisher. package.json release-it now sets npm.publish: false, so local yarn release only bumps/tags/pushes — CI performs the actual publish (with --provenance), and the version-diff guard works correctly. publish.yml runs yarn lint + yarn typecheck after nitrogen and before the build (fail-fast), and ci.yml adds a report-only npm pack --dry-run package-size summary after yarn prepare.

Documentation

• Correct stale Nitro facade comments. src/SyncProvider.nitro.ts header now states the JS facade lives wholly in src/index.tsx (no per-method .native.tsx/.tsx split; entry-level web split via the browser exports condition) and that the iOS impl class is HybridSyncProvider (not SyncProvider).
• Document the iOS 15 floor and add a pre-merge checklist. CHANGELOG.md gains an [Unreleased] section (Changed / Fixed / Internal); BREAKING_CHANGES.md gains an [Unreleased] entry for the iOS 13→15 floor with migration steps; README.md platform tables now read iOS 15; CONTRIBUTING.md adds a V-JS / V-AND / V-IOS pre-merge checklist and corrects the Nitro-method lifecycle (facade lives in src/index.tsx).

How

A few decisions worth a reviewer's attention:

• Why entities went internal: Nitro's Swift↔C++ interop emits a bridging header; public Core Data subclasses of NSManagedObject forced Obj-C translation units to resolve NSManagedObject, which they cannot. Demoting to internal keeps them out of the header while leaving runtime behaviour identical (they were never part of the public API).
• Why npm.publish: false: Splitting "version + tag + push" (local, via yarn release) from "publish" (CI only) makes CI the single source of truth for what ships, lets us publish with --provenance, and keeps the version-diff guard reliable — a local accidental publish can no longer race CI.
• Why remove the #available guards: With the floor at iOS 15, the iOS 13.0 checks are statically always-true; leaving them in implies a 13.0 path that no longer exists.
• Jitter ordering: capping after jitter (not before) is the load-bearing fix — it preserves the spread of the backoff distribution instead of clamping it toward zero.

Testing

V-JS gate — run locally, green ✅

• yarn typecheck — PASS
• yarn lint — PASS (0 errors; 25 pre-existing warnings in untouched hooks/contexts/website)
• yarn test — 13 suites / 71 tests pass
• JSON / YAML files structurally validated
• release-it.npm.publish === false confirmed
• Android jitter parity confirmed directly against JS (retryBackoff.ts) and iOS (RetryPolicyEvaluator.swift)