npm package: @gkucmierz/geo-words
Description: Deterministic spatial string encoder mapping geographic HEALPix grids into 1-5 words sequences. Built on a flattened 2048-word BIP39 dictionary. Features mathematically guaranteed cascaded FNV-1a checksums providing mathematically bonded typo detection (~
Author: Grzegorz Kucmierz
Latest version: 1.0.0

# @gkucmierz/geo-words

Deterministic spatial string encoder mapping geographic HEALPix grids (BigInt) into 1 to 5 word sequences.

## Concept
Translating raw numeric IDs into spoken words is a major UI/UX improvement.
This package uses a strict **BIP39 English** dictionary of exactly 2048 words. Since $2^{11} = 2048$, each word encapsulates exactly **11 bits** of data.

To make the algorithm resistant to human typos and word-scrambling, the 11-bit capacity of each word is divided into:
- **10 bits** of actual spatial geographic payload.
- **1 bit** of cascading checksum parity. 

For 5 words, the system utilizes **50 bits** for spatial bounding (perfect for targeting ~0.60 m² street-level precision via `@gkucmierz/geo-number`) and **5 bits** for error detection, providing a ~96.8% immediate rejection rate on invalid inputs.

## Dictionary Structure
The `src/wordlist.js` dictionary is directly derived from the standard open-source **BIP39 English** specification. 
In this repository, it is stored as a flattened, fully expanded Javascript Array file. Flattening it drastically improves developer experience (DX)—scrolling through the asset allows a developer to instantly correlate a word to its 1-based index line number without parsing JSON, resolving linting issues, or calculating object offsets.

## Cascading FNV-1a Checksum
To prevent the user from accidentally swapping two valid words (which would otherwise produce a valid but wildly incorrect location), the 1-bit checksum for each word relies on the **sequence of all preceding words**.

This is achieved using a robust 32-bit **FNV-1a** hash algorithm mixed with an bitwise avalanche step:

```javascript
/**
 * Robust cascading hash for checksum bit generation.
 * Utilizes a 32-bit FNV-1a hash base, augmented with an avalanche
 * step to ensure that payload permutations (e.g. swapping word 1 and 2)
 * aggressively alter the resulting parity bit.
 */
function getChecksumBit(payloads) {
  let hash = 0x811c9dc5; // 32-bit FNV offset basis
  for (let i = 0; i < payloads.length; i++) {
    // Incorporate current chunk
    hash ^= Number(payloads[i]);
    // Multiply by FNV prime
    hash = Math.imul(hash, 0x01000193); 
  }
  
  // Avalanche mix for strong bit distribution
  hash ^= hash >>> 13;
  hash ^= hash >>> 16;
  
  // Return Least Significant Bit as 1-bit checksum
  return (hash >>> 0) & 1; 
}
```

By hashing the history of payloads, `words[2]` is mathematically fused with `words[1]` and `words[0]`. Any scrambling instantly breaks the cascade and throws a verification error.

## Installation
```bash
npm install @gkucmierz/geo-words
```

## Usage
```javascript
import { encode, decode } from '@gkucmierz/geo-words';

// Encode a HEALPix BigInt to 5 words
const words = encode(12345678n, 5); 

// Decode back to ID and Order
const { id, order } = decode(words);
```