# Android Compatibility Contract

This document defines the cross-language contract for Android/Kotlin integrations that implement `geohash-kit` behavior without importing this TypeScript package directly.

## Goal

- Keep TS and Kotlin implementations aligned for core geohash and Nostr helper outputs.
- Use checked test vectors as the source of truth for parity.

## Contract Sources

- Vector schema: `vectors/schema.json`
- Versioned vectors:
  - `vectors/core.encode.v1.json`
  - `vectors/core.decode.v1.json`
  - `vectors/core.neighbours.v1.json`
  - `vectors/nostr.createGTagLadder.v1.json`
  - `vectors/nostr.nearbyFilter.v1.json`

## Behavioral Rules To Match

### `core.encode(lat, lon, precision?)`

- Latitude must be finite and in `[-90, 90]`.
- Longitude must be finite and in `[-180, 180]`.
- Precision must be finite, rounded to nearest integer, min `1`, max `12`.
- Invalid input throws `RangeError`.

### `core.decode(hash)`

- Empty hash throws `TypeError`.
- Non-base32 characters throw `TypeError`.
- Returns center point and half-cell error:
  - `{ lat, lon, error: { lat, lon } }`

### `core.neighbours(hash)`

- Returns eight directions as keys: `n ne e se s sw w nw`.
- Longitude wraps across the antimeridian (`>180` wraps to `-180+`, `<-180` wraps to `180-`).
- Latitude does not wrap; it is clamped to `[-89.99999, 89.99999]`.

### `nostr.createGTagLadder(geohash, minPrecision?)`

- Emits `["g", prefix]` for each precision from `max(1, minPrecision)` to `geohash.length`.
- Empty geohash returns `[]`.

### `nostr.nearbyFilter(lat, lon, options?)`

- Defaults: `precision=5`, `rings=1`.
- Produces `{ "#g": string[] }` from center hash plus ring expansion.
- Output is de-duplicated while preserving insertion order.

## CI and Change Control

- `npm run vectors:check` validates stored vectors against current implementation.
- CI runs this check and fails on output drift.
- If drift is intentional:
  - update affected vector file(s),
  - add a `CHANGELOG.md` note describing the compatibility-impacting change.