[The-PatientZero]

Description

Closes #47.

Locus.location.query(...) now filters, sorts and pages on the native side, so a limited query returns only the selected page to Dart instead of loading the whole table.

• Channel. A new private queryLocations method-channel call carries UTC epoch-microsecond bounds and every current predicate (time range, accuracy, moving state, bounding box). Native code applies all of them before LIMIT/OFFSET. getLocations is unchanged.
• Version mismatch. When the Dart and native sides come from different versions, the query fails with UNSUPPORTED_NATIVE_QUERY and asks for a host rebuild. It never falls back to fetching all history.
• Android. Queries are pushed into SQL with normalized columns and run on a single background thread.
• iOS.
  • Queries use a separate read-only connection, so they never delay location writes.
  • Time windows and paging use the indexed timestamp column. Rows whose stored timestamp is not canonical are parsed on the fly.
  • A record that cannot be read is logged and excluded before paging instead of failing the query.
  • Releasing the last storage reference no longer dispatches synchronously onto its own database queue.
• Example app. The Stored Locations demo card gains filters, fixed-window paging, input validation and retry states.
• Docs. New guide doc/guides/querying-history.md, plus updates to the error-code reference and the testing guide.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Chore / Documentation / Refactor

Native Changes

• Android (Java/Gradle)
• iOS (Swift/Podspec)
• Dart/Flutter only

Testing Checklist

• flutter analyze passes
• flutter test passes (Unit Tests)
• cd example && flutter build apk --debug (Android Build)
• cd example && flutter build ios --no-codesign --debug (iOS Build)
• Verified on physical device (required for background/geolocation testing)

Also run:

• Android. Unit tests and lint pass. ConfigSnapshotInstrumentation passes 10 of 10 checks on an API 36 emulator, including real-SQLite history checks for filtering before paging, sort order, inclusive edges, timestamp rounding and unbounded ranges.
• iOS. All 75 Swift tests pass under both the Locus and locus module names.
• Dart. 807 Dart tests and 8 example widget tests pass.
• Manual iOS timing on 100,000 records. Newest page: 148 ms. A 1,000-second window: 92 ms. A moving-state filter over the whole history: about 1.5 s. A write issued during a long query: 2 ms.

Screenshots / Diagnostics

N/A

Checklist

• I have followed the Contributing Guidelines.
• My code follows the style guidelines of this project.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• Any dependent changes have been merged and published in downstream modules.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!