Thereabouts command and store contract¶
This is the normative grammar for the Rust CLI and the Node command tree. The console entry and python -m thereabouts invoke the same Rust run(argv, io) function. Both hosts use the JSON command description in grammar.json through its shared argument parser, help renderer and diagnostic policy; WASM exports the description verbatim. Native clap provides typed dispatch after shared validation. Node calls thereabouts-cli-core through WASM for batch parsing, rendering, field projection and lookup exit policy, and owns filesystem and HTTP operations. Native argv includes its program name; Io owns standard streams, environment and TTY detection. Python supplies the optional MCP host. See status.md for qualification and measurements.
Commands¶
No verb guesses the input domain. Options shown below belong to their command; global options may appear before or after a command.
| Command | Arguments and options | Result |
|---|---|---|
| reverse | --lat LAT --lon LON | Geographic context at a coordinate |
| reverse | FILE or -; --lat-col COLUMN --lon-col COLUMN | CSV/NDJSON stream |
| h3 | CELL | Stored ancestor at resolutions zero through eight |
| geocode | TEXT; --country CC --subdivision CODE --limit N --prefer population | Towns and cities |
| postal | CODE --country CC | Postal-code context; country is required |
| airport | CODE; --scheme iata|icao|gps|local|ident --country CC | Airport context |
| locode | CODE; --country CC | Five-character code or country plus three-character location |
| ip | ADDRESS | IPv4 or IPv6 literal |
| phone | NUMBER; --country CC | Telephone prefix context |
| plate | TEXT; --country CC --series NAME | Registration format context |
| data install | PACK…; --version V --from URL|DIR --yes | Explicit install transaction |
| data install dataset | --version V --from URL|DIR | Restore the Parquet dataset to dataset/ |
| data list | --remote | Local inventory or available releases |
| data verify | --full | Sizes; hashes with --full |
| data remove | PACK; --yes | Remove the named family |
| data path | none | Resolved data directory |
| data update | --check | Compare active version with the release index |
| info | none | Installed data identities and capabilities |
| mcp | none | Optional read-only Python MCP server on stdio |
PACK is core, postal, airports, locode, phone, ip or plates. Names are part of core. Reverse coordinates and batch input are mutually exclusive; both coordinate flags are required. Negative coordinates are values.
The first line of geocode help is: “Finds towns and cities by name. Street addresses are not supported.” Country/subdivision are hard filters, limit bounds candidates, and population preference explicitly chooses the population-ranked winner. Airport without a scheme searches IATA/ICAO according to the core's ambiguity policy. Schemes are case-insensitive. Airport --country supplies required local-code context. LOCODE country context is validated even for a full five-character code. Plate --series selects a published series, such as historic-geographic. Phone requires international E.164 input; --country narrows matching countries and does not infer a national dialing plan. Geocode limit defaults to 5 and must be between 1 and 100. These context flags mirror library semantics.
Global options¶
| Flag | Meaning |
|---|---|
| --data-dir PATH | Override environment and platform discovery |
| --format table|json|ndjson|csv | Explicit output encoding |
| --json | Shorthand for --format json |
| --csv | Shorthand for --format csv |
| --fields a,b.c | Select named result fields, including dotted paths |
| --fields | List available result fields without opening data |
| --evidence | Include source evidence in results |
| --quiet | Suppress progress diagnostics, preserving result output and errors |
| --no-input | Never prompt; destructive commands require --yes |
| --strict | Exit 1 for a completed lookup with no match |
| --version | Print client version without opening data |
| --help | Print command-specific help without opening data |
Conflicting output selectors are usage errors. Unknown commands, flags or field paths are usage errors. No lookup invokes installation or release checks. Use thereabouts --fields to list result paths without query arguments. Available paths are status, kind, match, country (code, code3, name), state (code, name), city (id, name, name_en, kind, population, point.lat, point.lon), timezone, point (lat, lon), cell, distance_band (greater_than_km, at_most_km), candidates, rank_basis, hint and evidence. Container paths, including city.point, are also selectable. Selections use literal dotted keys in output, for example "city.name". Named field selection and evidence apply to lookup results. Data/info output retains its documented structure. --version works at every command except data install, where --version V selects the dataset.
Install is explicit consent to transfer; --yes is accepted for automation and does not change this behavior. There is currently no progress output, so --quiet preserves results and error diagnostics while producing no progress text.
Output and batch input¶
TTY output defaults to a human table. Piped output defaults to NDJSON, one object per result. --json produces one pretty JSON object. Result keys and nulls are the exact snake_case public result contract in the design and ../dataset/pack-format.md. NO_COLOR disables terminal colour; plain tables need no colour to convey status. The implementation emits no ANSI colour sequences in any mode, including with NO_COLOR. Table cells replace control characters with spaces and truncate values with … only when the terminal budget requires it. Each place occupies one line; candidates appear as indented lines beneath the query. The header appears once. A table page spans the invocation: all rows and candidates are measured using a temporary row spool before output. Natural column widths have no fixed cap; the widest columns shrink first to fit the terminal. Invalid-row hints follow their row and wrap to the terminal width. Default scalar columns are status, country, state, city, timezone, point, match, omitting fields absent from the result and its candidates. Batches keep all seven summary fields to support rows with differing coverage. --fields uses exactly the requested column order. Evidence is never printed in tables; use --json --evidence.
Scalar JSON/NDJSON is one result object. Batch --json streams one object with a results array; it does not retain the whole batch. CSV preserves input header order, then appends thereabouts_* columns in public result order (or --fields order). Scalar CSV uses that same result order; object/array values are compact JSON in quoted CSV cells, null is an empty cell, and quoting follows RFC 4180. Scalar JSON/NDJSON uses public result field order, or --fields order. Batch structured rows preserve their input key/header order before the appended result fields. Nested object order is not a contract; consumers address keys by name.
Management outputs are objects: data path returns {"path": ...}; data list
returns {"packs": [...]} with family, data_version, path, active and
format_minor; data install returns {"installed":
reverse FILE reads a file; reverse - reads stdin. CSV has a header. Automatic coordinate header names are exactly lat/latitude and lon/longitude/lng, case-sensitive. Any other names require --lat-col and --lon-col. Multiple eligible coordinate columns require explicit selection. NDJSON objects use lat and lon. Input columns pass through, and result columns are appended with the prefix thereabouts_. Bad rows emit invalid_input and processing continues in input order. CSV quoting preserves commas, quotes and embedded newlines. CSV header errors (duplicates, empty names, ambiguous coordinates) are usage errors. Input names beginning thereabouts_ are reserved and rejected. JSON numeric lat/lon must be numbers, not strings or booleans; CSV fields parse as floating-point numbers. Out-of-range coordinates produce invalid_input. Malformed NDJSON records retain their raw text in an input field.
Input encoding is independent of --format, which selects output. Files ending in .ndjson or .jsonl (case-insensitive) use NDJSON; otherwise the first nonblank line beginning with { or [ selects NDJSON. Other input uses comma-separated CSV. Single-column and semicolon-separated input produces a usage error explaining CSV headers and NDJSON objects. Empty input emits no rows (or {"results": []} with --json).
NDJSON-to-CSV/table needs the union of input keys, in first-seen order, before writing a header. It spools input to an automatically removed temporary file, retaining at most 4,096 keys and 1 MiB of key names. Disk exhaustion during spooling reports “not enough disk” (exit 2). JSON/NDJSON and CSV output stream directly; table output also spools the result page to measure every row. Missing input fields become null tabular cells. Batch hint is always present (nullable), and evidence is nullable when requested, so failed rows cannot change the CSV result schema.
Single-query examples:
thereabouts reverse --lat 48.8566 --lon 2.3522 --json
thereabouts h3 881fb46625fffff
thereabouts geocode "Springfield" --country US --prefer population
thereabouts postal 75001 --country FR --fields city.name,country.code,status
thereabouts airport CDG --scheme iata
thereabouts locode BEANR
thereabouts ip 8.8.8.8
thereabouts phone "+32 2 555 1234"
thereabouts plate "AB-123-CD" --country FR
Batch and management examples:
thereabouts reverse points.csv --csv
thereabouts reverse - --format ndjson
thereabouts reverse points.csv --lat-col north --lon-col east
thereabouts --data-dir ./store data install core postal --from ./release --yes
thereabouts data list
thereabouts data verify --full
thereabouts data update --check
thereabouts data remove postal --yes
thereabouts data path
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | Success, including an ordinary miss without --strict |
| 1 | No match with --strict |
| 2 | Usage, input-shape or environment/stream IO error |
| 3 | Required data is not installed |
| 4 | Incompatible/corrupt data or transfer/store integrity failure |
| 5 | One or more batch rows failed; remaining rows were processed |
| 6 | Resource limit: the process ran out of file descriptors (EMFILE/ENFILE) |
| 70 | Internal error: a library invariant failed (for example a poisoned lock); a bug to report, never pack damage |
Missing-data diagnostics are the exact command
thereabouts data install core, or the required forward family name. Human
prompts and diagnostics go to stderr. Result output goes to stdout. An
interactive removal asks for confirmation; non-interactive removal requires
--yes. --no-input never implies consent. A declined prompt exits 2. Remove
deletes all versions of the named family under the install lock; a missing
family is harmless. Missing data, corrupt data and usage errors are not hidden
by --quiet. A broken stdout pipe exits 0 without a traceback. Other stream/OS IO failures
exit 2 without suggesting pack repair. Descriptor exhaustion exits 6 with a
message naming the open-file limit (ulimit -n); it is never reported as
corrupt data and never suggests reinstalling (Python and Node raise
ResourceLimitError). Internal errors (exit 70, InternalError) and invalid
input (exit 2, InvalidInputError) likewise carry no repair advice. One Rust
table (thereabouts_core::error::KINDS) gives every failure code its exit
status and binding class; Python maps through it and Node is tested against it. Both Node sinks write all UTF-8 bytes,
retrying partial writes, EINTR and EAGAIN while a slow reader drains the pipe.
An invalid scalar query emits its result and exits 2; invalid command arguments emit a diagnostic without result JSON. Unsupported granularity also exits 2. In batches, row failures take precedence over strict misses: exit 5 if any row failed, otherwise 1 if --strict found a not_found result. Ambiguous is not not_found and does not itself trigger --strict.
Data store¶
Resolution is --data-dir, THEREABOUTS_DATA, then the platform user-data path. Python and native discovery use the same pin validation. The native path policy is tested against the platformdirs implementation bundled with the existing setuptools development dependency.
| Platform | Default |
|---|---|
| macOS | ~/Library/Application Support/Thereabouts |
| Linux/Unix | $XDG_DATA_HOME/thereabouts, otherwise ~/.local/share/thereabouts |
| Windows | %LOCALAPPDATA%/Thereabouts |
The installed layout is:
<data-dir>/
active.json
.lock
.downloads/<archive-sha256>.part
.staging/<archive-sha256>/
packs/<family>/<dataset-version>/
manifest.json
.archive.json
<inventoried artifacts>
Versions are portable components of up to 128 ASCII letters/digits, dot, underscore or hyphen, cannot start/end with a dot, and cannot use Windows reserved device names. Family names are enumerated. Pack-relative paths reject traversal, absolute paths, backslashes, colons and symlinks. The installed manifest's family and data_version must agree with the selection.
active.json contains:
{
"data_version": "2026.10",
"packs": {
"core": {
"path": "packs/core/2026.10",
"manifest_sha256": "<64 lowercase hexadecimal characters>"
}
}
}
The active pointer is authoritative when present: omitted families are uninstalled for discovery even if another version remains on disk. The manifest hash is checked before reading each selected identity. All entries share one dataset version. Installing another version requires all active families in the request; installing more families at the active version retains the existing pin entries.
Without active.json, discovery accepts the existing
packs/
Install/remove operations acquire <data-dir>/.lock with exclusive file creation
(O_EXCL/create_new). Its immutable JSON record is {pid, created_ms, token}:
a positive OS PID, Unix milliseconds and a unique 32-hex-character incarnation.
Both hosts use the same Rust wire validation and recovery-name policy. No port
or network access is involved. Contention reports “Another install is running;
retry after it finishes” and exits 2. A corrupt/unsafe lock path exits 4.
A live owner never expires by age. A dead PID permits immediate takeover;
permission failures count as live. An incomplete record has a 30-second creation
grace period, measured against file mtime; backwards clock movement defers
recovery. Reads are capped at 1 KiB. Takeovers acquire a per-incarnation sibling
.lock-reap-<sha256> lease, reread/recheck the old record, then unlink it and
retry exclusive creation. This serializes competing reapers so they cannot
unlink a successor. The same protocol recovers dead reapers, bounded to eight
nested recoveries; exhausted contention exits 2. Normal release removes only
its own token. Completed recovery leases are removed on scope exit.
Release index and install transaction¶
A reused PID can make a dead installer's lease appear live. This deliberately
fails closed: inspect <data-dir>/.lock and the named process, confirm that no
install is running and that the process is unrelated, then remove that .lock
file and retry. Do not remove a lease while its installer is running.
The source is a directory containing index.json and archives, or a base URL.
The default (DEFAULT_RELEASE_URL, defined once in
thereabouts-cli-core::transport and exported to Python as
_core.DEFAULT_RELEASE_URL and to Node through WASM) is
https://github.com/brightertiger/thereabouts/releases/latest/download/, which
GitHub redirects to the newest published release's assets;
.../releases/download/v<version>/ reads one release. THEREABOUTS_RELEASE_URL configures the
source for install, remote list and update --check; it may also be a local
directory. --from overrides it for install. URLs are HTTP(S) base URLs;
index.json is appended. An archive URL may be absolute or base-relative,
with slashes (2026.10/core.tar.zst). Local indexes use relative artifact paths.
A directory holding a downloaded GitHub release is a source too: absolute URLs
in its index name files by their last path segment. Clients use these download
routes, not GitHub's REST releases/latest endpoint, whose unauthenticated
limit is 60 requests an hour per address.
The release index (format 3) is:
{
"format": 3,
"datasets": {
"2026.10": {
"packs": {
"core": {
"url": "2026.10/core.tar.zst",
"size": 523456789,
"sha256": "<64 lowercase hexadecimal characters of the archive>",
"unpacked_size": 2812345856,
"format_minor": 2
},
"postal": {
"url": "2026.10/postal.tar.zst",
"size": 23456789,
"sha256": "<64 lowercase hexadecimal characters of the archive>",
"unpacked_size": 78901248,
"format_minor": 2
}
}
}
}
}
size and sha256 describe the compressed archive exactly as downloaded;
unpacked_size is the exact length of its decompressed ustar stream. The
pipeline publishes one index per version (packs/<version>/index.json, URLs
relative to that directory) and merges every published version into the
aggregate packs/index.json (URLs <version>/<family>.tar.zst), which is the
base clients use for install, remote list and data update --check.
Releases published to GitHub use absolute urls
(https://github.com/<owner>/<repo>/releases/download/v<version>/<asset>) and add
asset_id and api_url
(https://api.github.com/repos/<owner>/<repo>/releases/assets/<id>) to each
pack, plus a dataset entry per version naming the dataset install manifest
(url, size, sha256, asset_id, api_url; at most 16 MiB). Each GitHub
release's index.json lists every version published so far, so
releases/latest/download/index.json is the newest aggregate. A patch to an
older version published after a newer one (say 2026.09.1 after 2026.10) is
listed by its own release's index, not by latest's, until a newer release is
published. Clients that predate these fields ignore them.
Index JSON is limited to 16 MiB. The transport caps are defined once in
thereabouts-cli-core::transport and shared by the CLI, Python
(_core.MAX_ARCHIVE_BYTES, _core.MAX_UNPACKED_BYTES), Node (through WASM)
and the release pipeline: size is positive and at most 2 GiB, and
unpacked_size is positive and at most 16 GiB. A world core is about 2.8 GB
unpacked and well under 1 GiB compressed. Unknown fields are ignored at every
level of the index so it can grow without a client release; required fields
are still validated, and another format fails with incompatible_data
naming the found and supported formats. The default release is the newest
whose requested families exist and have supported format minors: minor 2 for
every family. Dotted numeric version components compare numerically; other
components compare bytewise. Explicit unavailable/incompatible versions fail.
Archives (<family>.tar.zst) are one zstd frame holding a POSIX ustar stream
written deterministically: entries sorted by path, mode 0644, zero owner and
modification time, a fixed compression level and single-threaded encoding, so
an unchanged pack gives identical archive bytes. manifest.json and its
inventoried artifacts are at the archive root. One Rust implementation
(thereabouts-cli-core::archive) creates archives for the pipeline and
extracts them in the CLI, Python and Node (through WASM, pure-Rust zstd).
Extraction streams download → decompress → untar into staging. It accepts only
regular files and directories and rejects absolute, .., empty-component,
backslash or colon paths, duplicates, links, devices and other special
entries, invalid header checksums, malformed lengths, missing two-block
terminators, nonzero trailing payload and data after the zstd frame. It stops
as soon as the stream exceeds the declared unpacked_size (or the 16 GiB
cap), so a decompression bomb never fills the disk, and the final length must
equal unpacked_size exactly. Archives cannot supply the reserved installer
.archive.json receipt, and the extracted files must be exactly the pack
manifest's inventory plus manifest.json.
Before download the installer reserves, per requested family, the archive
size plus its unpacked_size (which bounds the extracted files), plus a
64 MiB bookkeeping margin. Insufficient space is an environment error
(exit 2); there is no fixed free-space floor in the product. Partial
downloads remain in .downloads and resume at their exact byte offset. The native HTTP
host uses ureq with rustls and certificate verification enabled. Node uses
fetch with undici environment-proxy support and normal TLS verification. Initial
transfers require HTTP 200; resumes send Range: bytes=N- and require HTTP 206
with Content-Range: bytes N-(total-1)/total. If supplied, Content-Length must
equal the remaining advertised length. Ignored/mismatched ranges fail and
retain the partial file for retry. No bytes are appended before these checks.
Requests use Accept-Encoding: identity; encoded responses are rejected.
Redirects are followed by the client, at most five: HTTPS anywhere, plain HTTP
only from loopback to loopback (tests), never HTTPS to HTTP. Every hop repeats
the Range and Accept-Encoding headers. A hop carries the release token only while
it stays on the GitHub API origin, so a redirect to GitHub's object host never
does; without a token no hop carries credentials. An archive URL under an HTTPS
index must itself be HTTPS.
HTTPS_PROXY/HTTP_PROXY/ALL_PROXY and NO_PROXY use native ureq environment semantics.
Node honors HTTPS_PROXY/HTTP_PROXY and NO_PROXY through undici; ALL_PROXY is
used as a fallback when HTTP_PROXY/HTTPS_PROXY are absent. Connections and headers
have 30-second deadlines; each transport read has a fresh 60-second stall limit.
There is no total download timeout. Failures retain verified-offset partial bytes
for the next explicit install to resume. Tests use only loopback HTTP and local directories.
The full archive length and SHA-256 are checked before extraction; a partial or mismatched download is never decompressed. Then every pack checksum and structure is verified, and family, dataset version and minor format are checked against the index. The pack is renamed from staging into its immutable destination on the same filesystem. A receipt records archive identity; a repeated install cannot change that identity for an existing version.
active.json is written and synced to a temporary sibling, then replaced atomically only after all requested packs verify. A failed transaction keeps the previous pin. Already verified, unactivated directories may remain for a retry; failed extraction staging is removed. Archive hash failures discard their partial archive. No lookup contacts the index or any transfer source.
Private GitHub releases and tokens¶
A token in THEREABOUTS_RELEASE_TOKEN, else GITHUB_TOKEN, is used only when the
release URL has GitHub's shape (<host>/<owner>/<repo>/releases/latest/download/
or .../releases/download/<tag>/). Private repositories serve no public download
route, so the client then reads GET /repos/<owner>/<repo>/releases/latest (or
/releases/tags/<tag>), finds the index.json asset in the release or on its
asset pages, and downloads it and every file through
GET /repos/<owner>/<repo>/releases/assets/<id> with
Accept: application/octet-stream, using each entry's api_url. The token is
sent as Authorization: Bearer only to the API origin: https://api.github.com,
or THEREABOUTS_GITHUB_API_URL (HTTPS, or plain HTTP on loopback, for GitHub
Enterprise and tests). An api_url on any other origin is ignored, and GitHub's
redirect to its object host never carries the token. A fine-grained token with
Contents: Read on the repository is enough; authenticated requests count
against the token's 5,000-an-hour limit. Without a token, or for any other
release URL, no credential is sent.
Dataset install¶
thereabouts data install dataset [--version V] [--from URL|DIR] restores the
Parquet dataset to <data-dir>/dataset/<version>/. The CLI, the Python console
and Node share this contract, and dataset is installed on its own. The newest
version (or V) whose index entry has dataset is selected. Its
dataset-manifest.json (format 1, _core.DATASET_MANIFEST) lists archives
(name, table, size, sha256, unpacked_size, url, asset_id,
api_url, and files with each member's path, size and sha256) and
files (the top-level documents, each with path, size, sha256, url,
asset_id and api_url). Each table ships as dataset-<table>.zip, split into
dataset-<table>-001.zip, -002… when one zip would exceed GitHub's 2 GiB
asset limit. The zips are stored (Parquet is already compressed), without zip64,
data descriptors, extra fields or comments. One Rust reader
(thereabouts-cli-core::zip) extracts them in every client: the pack path
rules, CRC-32 and SHA-256 per entry, the declared unpacked size as a bound, and
only the exact layout the pipeline writes; anything else is an integrity
failure (exit 4). Downloads resume in .downloads, and each file is checked by
size and SHA-256 before use. Space for every zip plus its unpacked size is
reserved first. The tree is assembled in staging, checked file by file against
the manifest (exact inventory, sizes and digests) and renamed into place only
when complete. An existing version is verified, never replaced.
MCP¶
The current optional server is available with:
thereabouts --data-dir ./store mcp
# Equivalent direct Python host:
THEREABOUTS_DATA=./store python -m thereabouts.mcp_service.server
It provides reverse, h3, geocode, postal, airport, locode, phone, ip and plate, returning the same result JSON as Python, including evidence when requested. There are no install or arbitrary-path tools. The optional thereabouts[mcp] extra is imported only for mcp; startup without it exits 2 with an explicit installation hint. No banner is printed on the MCP protocol stream. The old Python CLI and catalogue MCP modules have been retired. The public console delegates directly to the native Rust command tree.
Conformance boundaries¶
The current bundle has 411 vectors. The real console runs 405; six of these invalid grammar cases assert exit 2 without a result object. Five NUL-containing cases run through _core.run_cli because operating systems forbid NUL in argv. One integer-type postal input is asserted through the typed API and rejected by the run_cli argument conversion: OS arguments cannot preserve integer types. The 19 legacy forward cases retain their original assertions and explicit migration allowances: 18 run through the console, and one integer-type rejection remains at the typed API boundary. No expected snapshots are replaced with the new CLI's output.
Optional core enrichment for forward packs¶
Forward format 2.2 pins the core dataset version, catalogue digest and place
count. Installing core alongside a forward family enables canonical city,
state/country metadata and catalogue timezone projection. The active release
must agree and the catalogue digest must match; otherwise lookup exits 4.
Forward lookup never installs core implicitly. With only the forward pack
installed it still returns its keys, source points and published country/state
context; city detail and timezone are null. A partial core sample supplies
only the places it contains. Python explicit paths select enrichment with
Geocoder(packs={"core": core_path, "postal": postal_path}); a lone forward
Geocoder(path) is deliberately standalone. Names lookups continue to use core.
Bounded fuzzy search¶
Exact and prefix name lookup remain exhaustive. The fuzzy fallback uses the pack-wide key/row budgets documented in ../dataset/pack-format.md. On large name indexes, otherwise eligible fuzzy cities may be omitted; population ranks the admitted candidates. Country and subdivision filters remain hard constraints on every returned result.
A dataset version change must include every active family in the install transaction. Otherwise installation exits 2 before downloading, preserves the active pointer and prints the complete install command with --version. Installing another family at the current version retains all other active families.
Until a release service is published, the default placeholder fails locally with exit 2 and instructions to set --from DIR|URL or THEREABOUTS_RELEASE_URL; it never performs DNS or HTTP. Missing input files are usage/environment errors (exit 2) naming the path. Unusable installed packs report their path, family, thereabouts data verify --full, and remove/reinstall commands (exit 4).
Missing data exits 3 with a short sentence on stderr followed by the exact install command alone on the last line. Library exception messages remain the exact command.
Bare invocation writes help to stderr and exits 2. Explicit --help writes to stdout and exits 0. Reverse help shows coordinate and FILE|- forms separately. Python and Node discovery delegate directory selection to the same portable store policy (native and WASM respectively); macOS, Linux and Windows rules are compared with platformdirs in tests.
The Rust thereabouts-cli-core crate owns batch detection/parsing, result-field selection, table/JSON/NDJSON/CSV rendering and the exit-code policy. It builds for wasm32-unknown-unknown and has no clap, HTTP or filesystem dependency. Hosts supply input/output streams, terminal columns and seekable temporary storage; table width is measured in terminal cells (including wide Unicode text). The native crate owns clap, files, temporary-file lifetimes, process environment and downloads. The Node binding uses this same portable policy through WASM.
Node implementation¶
The ESM package supports Node 22 and 24. Scalar library methods are async and return the same snake_case result objects. reverseMany is an async iterable. The host supplies stable file descriptors, sizes and exact positioned reads; the WASM module owns every pack decoder and lookup. There is no native addon.
Build the ignored pkg/ artifact with npm run build (Rust 1.99, wasm32-unknown-unknown and wasm-bindgen-cli 0.2.129). npm prepack invokes this reproducible build and includes the result; no generated WASM is committed. The package contains no data and makes no implicit downloads.
Node mcp delegates stdio to python3 -m thereabouts.mcp_service.server; THEREABOUTS_PYTHON can select the Python executable. The optional Python MCP installation remains required. JS command help describes the same flags; text wrapping need not match clap. Node scalar invalid values and CLI batch errors use the shared Rust result and exit mapping.
Node library conformance asserts all current and synthetic vectors and all 54 original legacy mappings. The actual bin asserts every representable query; NUL values use the same JS runner and typed non-string values remain library assertions. Coordinate comparison uses the shared 1e-9 degree absolute tolerance for target-specific transcendental arithmetic in H3 cell centres (see below); every other field compares exactly. No expected geography, statuses or candidate ordering is changed for Node.
Building a local release¶
The pipeline release packs command produces packs/<family>.tar.zst archive per family, after all requested
packs verify. Pass that version directory to data install --from; after
publication, the aggregate packs/ directory serves every version. Core must be included when
building forward packs so their catalogue pins have a concrete dependency.
See ../pipeline/README.md for prepared-dataset commands and
release.md for package artifact workflows.
Interrupted transfers (including connection resets, short EOF and per-read stalls) retain partial archives and exit 2 with “Download interrupted; run the same data install again to resume”. A retry validates the exact Range response before appending. Checksum and protocol identity failures still exit 4.
Terminal width and numeric equality¶
Tables use COLUMNS when it is a positive integer (at most 10,000), otherwise the stdout terminal's width (ioctl on native hosts), otherwise 80 columns. Column widths reflect every row and candidate in the rendered page, with no fixed character cap. The page is spooled to host-owned temporary storage so width measurement uses bounded memory. The widest columns shrink first until the table fits; headers remain readable. Batch table result headers omit the thereabouts_ prefix; JSON/NDJSON/CSV keep it. Separators compact to two spaces when needed. Very wide input schemas that cannot retain readable headers require --fields or --json. A stream keeps one header and fixed column widths; values exceeding their allocated width use …, including Unicode.
Results are semantically equal across native and WASM hosts and across CPU
architectures. H3-derived cell centres can differ in the last floating-point
digits because target math implementations differ (x86_64 and ARM differ by up
to about 1.4e-14 degrees). Conformance compares every lat/lon value with
absolute tolerance 1e-9 degrees (about 0.1 mm), not byte-identical JSON or
CSV text, in Python, Node and Rust alike. Stored coordinate
values, IDs, statuses, ordering and other fields retain exact conformance.
No extra output rounding is applied.
User-selected batch files may be regular files, named pipes or process substitution paths; they are sequential streams, not pack artifacts. Pack artifacts still require immutable regular files and positioned reads. Version-switch refusal prints commands retaining --from and --data-dir, both for switching all active families and for adding a family at the active version. Resume requests always send Accept-Encoding: identity. Node fetch adds this header for Range requests itself; the host sets it for other requests to avoid a duplicated wire value. Loopback tests assert the actual resumed header. Repository npm config and the Node benchmark keep cache/log files under .cache and scratch under .tmp.