Repository navigation
v1.0.0
The first stable release. Every public surface now has its promise and its gate
(what 1.0 promises); the pack format is 1.0 and older packs
stay readable; every public enum that may grow is #[non_exhaustive]; the 1.0 API review
renamed the last parameters that broke the naming rule (see Breaking).
Added
- Each place's population (D-351): packs carry it in COMPONENTS (component 1, a count and
whether a source stated it or a population grid modelled it);Engine::population(feature
extra, on by default) returnsPopulation { people, source }; every place result has the
nullable columnspopulationandpopulation_kindin every language, andtgd, the HTTP
server and MCP printpopulationandpopulation_kind.extract::mergekeeps every
component of COMPONENTS. Both WebAssembly packages buildextra(feature of
teigeodata-wasm); every binding's parity suite checks both columns. teigeodata-enginefeaturefuzz:fuzz::engine, every query on a pack with edited
sections whose hashes hold, run nightly by libFuzzer (fuzz/fuzz_targets/engine.rs) and on
seeded inputs bycargo test(D-331);teigeodata_format::fuzz::edit_sectionbuilds such
packs, and the edited sections' full check runs too.teigeodata_sync::fuzz::trust(featurefuzz, now withrepo): the TUF update chain and
the catalog on a repository with one role attacked, nightly as thetrusttarget (D-331).teigeodata_ffi::fuzz::abi(featurefuzz): every engine function of the C ABI with fuzzed
arguments, nightly as theffitarget;teigeodata_server::fuzz::mcp(featuresfuzzand
mcp): every MCP tool with arguments from its own input schema, and resource reads, nightly
as themcptarget (D-331).- The weekly fuzzing campaign (
fuzz-campaign.yml): every target for 3 hours with coverage
reports, and its gatecargo xtask fuzz-coverage, which fails unless every section kind's
decoder is reached (D-331). teigeodata_server::http::Configgainsheader_timeout,max_connectionsand
max_in_flight, andtgd servegains--max-connectionsand--max-in-flight(D-334).cargo xtask unsafe-audit: the inventory of everyunsafein shipped code with its argument
and the tests that reach it (docs/06-engineering/unsafe-inventory.md), and the
threat model (D-333).teigeodata_format::check::sections_where: the full check of the sections a caller selects.- CodeQL code scanning (
codeql.yml) and the OpenSSF Scorecard (scorecard.yml), weekly. - Extension columns (D-335): a column-table column with an ID from
0x8000
(teigeodata_core::table::EXTENSION) is skipped by a reader that does not know it, so a
format minor can add optional columns;Table::extensionslists them. COMPONENTS IDs are 1
to 127.teigeodata_format::fuzz::{bodies, write_again}rebuild a pack from its sections. - A result
Readerof one shape in every language (D-322): new in Node.js, WebAssembly,
Swift, Dart, Java (Kotlin), C (teigeodata_reader.h) and C++ (teigeodata_reader.hpp),
both header-only and in the C package (rows,columns,has,numbers,strings,nulls,column,
records, iteration); Go's gainsHas,ColumnandRecords, Python'shas,column,
recordsand iteration, .NET'sBlobReaderHas,Numbers,Column,Recordsand
iteration. cargo xtask docs-examples: runs every language's example program on the pinned public pack
and checks its output (D-322).- The API, HTTP and MCP reference of the site, generated: the API's from each binding's own
declaration macros bycargo xtask bindings, the servers' fromteigeodata_server::http::ENDPOINTS
(a route table a test holds to the parser) andmcp::tool_definitionsand
mcp::resource_templates(D-323). Engine::boundary(id, lod)(an outline as a GeoJSON Feature, with its level, tolerance and
vertex count),Engine::distance(from, to)between two places, andbearing_degin the
language API and every binding, with parity values checked in each (D-324).
teigeodata_engine::Outline::write_geojsonandwrite_point_geojson: the GeoJSON writer the
servers used, now one writer for the servers and the bindings.cargo xtask data-pages: the site's coverage, country and measured pages, generated from the
pinned pack,data/countries/and the gates' records, with--check(D-325, D-326).- The site's playground (
/playground): the WebAssembly engine and the pinned pack in the
browser, MapLibre drawing the pack's own outlines, every answer with its code and timing;
cargo xtask playground [--fetch]writes its files, andsite/scripts/check-playground.mjs
runs it in Chromium in the docs workflow (D-328). --recordonpackage-wasm,sizesandload, andcargo xtask phone <layer.tgd> [--record](the phone-class bench with the example's own features): each writes its table,
stamped with the day, commit, machine and load average, tosite/data/measured/(D-326).cargo xtask profile <pack>… [--suite] [--secs]: each query suite under Instruments' Time
Profiler, one suite per process, with the largest frames by self time and under our own
frames;cargo xtask scaling <pack> [--record]: one shared engine at 1, 2, 4 and 8 threads,
failing under 1.5× at four; the engine'sprofileandscalingexamples (D-338).cargo xtask accuracy <cc> <pack>: a shipped pack scored against the blind labels of
tests/golden/<cc>-places.csvand its second pass, written as the generated
data/countries/<cc>/ACCURACY.md(D-339).- Suite C, the competitive report:
tools/competitiveandcompetitive.ymlask teigeodata,
tgd serve, Nominatim, Photon, GeoNames' own points andtzf-rsthe same questions (D-340).
Changed
-
teigeodata_format::Sorted::findinterpolates inu64and usesu128only when the
product overflows:get−6% on Nepal lite, −4% on the world baseline.teigeodata_core::bitpack::Packed::parse
checks a column's block directory as independent steps that vectorise: opening a pack −14%
and −17% (D-338). -
distance_mcalls the engine'smeters_betweeninstead of a second haversine of its own
(D-324). -
cargo xtask loadnames each pack in bold and right-aligns its figures, so its tables read
as Markdown (D-326). -
cargo xtask load: a load test oftgd serveand its/mcpon real packs withoha,
gated bytools/load/budget.toml(requests per second, p99, footprint and its growth)
(D-320);cargo xtask sizes --tgdreports the binary with and without its servers. -
The Dart package runs on the web, compiled by dart2js or dart2wasm, over the WebAssembly
module, with the classes it has natively (D-307).TeiGeodata.init()loads the module once
on the web and returns at once natively; the web opens packs from their bytes. -
Engine::open_file_range(path, offset, length)(and_with) in every language but
WebAssembly: opens a pack stored whole inside another file, such as an uncompressed asset of
an Android APK (noCompress), mapped in place (D-306). -
Releases are built, attested and published by one workflow,
release.yml(D-302): every
file with build provenance through Sigstore, a CycloneDX SBOM per crate andSHA256SUMS;
gh attestation verify <file> --repo teispace/teigeodatachecks one. -
The crates
teigeodata-core,-blob,-format,-names,-sync,-engine,-api,
-serverand-cliare publishable to crates.io (D-303, D-310). -
teigeodata-server, the request core both servers andtgdshare (D-310, D-311): the
native, GeoJSON and Nominatim-compatible outputs moved there from the CLI;query, every
place, elevation and postal query with its bounds (Limits::SERVER: 256 bytes of text, 50
results, 1,000 km) and stable error codes (Code, each with its HTTP status);packs, the
pack set over files and the store, following the store's journal while it answers; and
seams, who is asking, may they and how much they used, open by default (ADR-0025). -
tgd serve(featureserve, on by default) andteigeodata_server::http(featurehttp):
every query as aGETroute under/v1/,/packsand/health, on axum; bound to
127.0.0.1, CORS off unless configured, a 4 KiB query string, a request timeout, a panic
answeredinternal; follows the store's journal every 5 s (D-312). -
tgd serveanswers Nominatim's/search,/reverseand/lookup(json,jsonv2,
geojson) with the parameters geopy and Leaflet Control Geocoder send, so an app switches
by changing its URL; fields we cannot fill are left out (D-314). -
tgd mcp(featuremcp, on by default) andteigeodata_server::mcp: the MCP server on
standard input and output, for revisions 2026-07-28 and 2025-11-25; fourteen read-only tools
(search,reverse,nearby,get_place,lookup,admin_at,hierarchy,children,
timezone,elevation,postal,boundary,distance,packs) with input and output schemas, structured
answers with their attribution, signed cursors for pages, and packs and places as resources
(D-315). -
/v1/hierarchy?id=(a place's ancestors) and/v1/children?id=&limit=(D-315). -
/v1/boundary?id=&lod=: a place's outline as GeoJSON, at the finest level of detail within
20,000 vertices unless one is asked;/v1/distance?from=&to=: metres and bearing between
places or points. In MCP, theboundarytool links the outline as the resource
teigeodata://boundary/{id}?lod=(D-317). -
/v1/coverage?lat=&lon=&radius_m=and the MCP toolcoverage, on a server over the store:
the countries at a point with the catalog's packs for it and their state, astgd locate
answers, read from the stored catalog without opening the store (D-318).
teigeodata_sync::client::catalog_atreads it so;PackState::of. -
MCP
installandinstall_status, on a server over the store: catalog packs installed into
the store and served, as a task (tasks/get,tasks/cancel) for a client with the tasks
extension or a handle polled withinstall_status, from one job registry. The size is
confirmed by the person first (MRTR elicitation in 2026-07-28,elicitation/createfor a
2025-11-25 client on stdio), else the download must fitmax_bytes(100 MB by default). On
fortgd mcp(--no-installleaves it out), opt-in fortgd serve(--allow-install)
(D-318). -
The official MCP conformance suite runs in CI against
tgd servefor 2025-11-25 and
2026-07-28 clients, every check gated against a reasoned baseline (D-319). It found, now
fixed:/mcpon loopback accepts the server's own origin;prompts/listand
completion/completeanswer method not found (neither is declared); a missing resource's
error carriesdata.uri(SEP-2164). -
tgd serveanswers MCP at/mcp(stateless Streamable HTTP), refusing a foreignHost
on loopback and any browser origin not configured with--cors-origin(D-316). -
Store::read_packs: the packs the journal lists, read without opening the store, so a reader
beside an install never recovers or removes its files (D-311). -
Each release carries the C library alone for every target the Dart hook and the Go loader
download, Android and iOS included, its SHA-256 pinned in both (D-304); the Dart package is
publishable to pub.dev, and the JVM binding is bundled for Maven Central as
com.teispace:teigeodataandcom.teispace:teigeodata-android. -
The parity gate (D-300):
cargo xtask parity-mutantsplants each value of
bindings/parity.jsonand requires every language's parity suite to fail on it; C and C++
read the values from the generatedbindings/c/parity_data.h. The suites check the values
the gate found unchecked (column names,get's longitude,dst, error codes). -
bindings/bench.shmeasures a 1,000-row query decoded in every language (D-301). -
The .NET binding, NuGet package
Teispace.TeiGeodata(net10.0, D-298): the whole API as
source-generated, blittable P/Invoke (NativeAOT and trimming safe),SafeHandlehandles,
…Asyncforms of the blocking store calls,Job.ProgressAsyncand a cancellable
ResultAsync,BlobReaderfor blobs andTeiGeodataExceptionwith the stable codes. -
The Go binding,
github.com/teispace/teigeodata/bindings/go(Go 1.26+, D-297): the whole
API through cgo, or through purego withCGO_ENABLED=0, over the C library loaded at run
time (LoadLibrary,TEIGEODATA_LIB, a pinned prebuilt in the user cache filled by
fetch, or the system path);Readerfor blobs;*Errorwith the stable codes. -
teigeodata.hpp, a header-only C++17 wrapper of the C library, in the C package
(D-295): owning handles,Blob, exceptions with the stable error codes. -
The C package for Linux musl (x64 and arm64).
-
The Node.js packages:
@teispace/teigeodatawith a prebuilt addon per platform
(@teispace/teigeodata-<platform>, macOS, Linux glibc and musl, Windows, x64 and arm64), npm
installing only the one a machine needs; CommonJS and ES module entries; Node.js 22 and later;
assembled bycargo xtask package-node(D-294). -
The WebAssembly packages
@teispace/teigeodata-wasm(every component) and
@teispace/teigeodata-wasm-lookup(no search): one ES module for browsers, Deno, Bun,
Node.js and Workers, theEngineover pack bytes, built and size-checked by
cargo xtask package-wasm(D-293). -
components()in every binding: the components the build answers.teigeodata-apihas a
Cargo feature per pack component, all incomponents(default); a build without one keeps
every function and answers as a layer installed without it (D-291). -
teigeodata-blobformat v1 (D-275, spike S2): a null bitmap per column
(Column::Nullable,Reader::nulls), dictionary-encoded strings (Column::Dict, read as
View::Dict: each distinct string stored once), andu8,i16,u16columns. v0 blobs
still read. -
The
Enginehandle in every binding (C, Python, Node, JVM, Swift, Dart): open packs from a
file or bytes (each answers its layer ID;removetakes it), thenget,search,reverse,admin_at,parent,ancestors,
children,nearby,within_radius,tz_at,by_iso,elevation_at, and postal codes
(postal_lookup,postal_prefix,postal_codes_of,postal_at), each answering a blob. One
engine is safe from many threads at once (D-274). -
Error codes
Io(4) andCorrupt(5). -
IDL format 2: handles with methods,
&[u8]parameters, handle parameters and results. -
IDL format 3: options records (D-276), plain structs of scalar and optional scalar fields
whose defaults are their zero values.SearchOptions(a focus point and scale,strict)
andEngine::search_withuse them in every binding; leaving the options out (CNULL)
means the defaults. -
IDL format 4: enums (D-277), each its language's own enum.
OpenOptions(priority,
Verifylazy/eager/trusted,Loadmap/read, outline level and tolerance) with
Engine::open_file_withandopen_bytes_within every binding. -
IDL format 5: text fields in records (
String, empty by default).OpenOptionsgains
components(point,names,search; what they need is added) andlanguages(en,ne, at
most 8), for packs installed in part or read in some languages only. -
Error code
MissingComponent(6, D-278): a query needs a component the pack was opened
without; before, this wasInvalidArgument. -
The
StoreandJobhandles in every binding (D-279, research note store-api):create,
open,catalog,status,pin,remove,engine(an engine over the installed packs),
findandlocate(the catalog's packs for a name or a point, over any engine, offline),
andrefresh,install(withInstallOptions: components, languages, outline, pin),
updateandrepairas jobs on a thread of their own, withwait_progress,seq,
done_bytes,total_bytes,is_ended,cancelandresult. A cancelled install leaves
the store as it was. -
Error codes
Network(7) andRefused(8) (D-279). -
Node: every call that blocks (the store's, a job's
waitProgressandresult) has a
…Asyncform returning aPromise(D-280); the IDL marks such callsblocksfrom a
# Blocksdocumentation section. -
Store::install_passin every language: one pass of an install whose bytes a platform's
download service fetches; its result lists each missing range and the file to save it as
(D-282). -
An install whose catalog refresh fails, when the stored catalog lacks the pack, fails with
Network(the cause) instead ofRefused(D-282). -
IDL: an options record must be the last parameter, so every language can default it.
-
Python wheels (D-290):
bindings/python/pyproject.tomlbuilds with maturin; cibuildwheel
makes a cp311-abi3 wheel (CPython 3.11 and later), a cp315-abi3t wheel (3.15 and later,
free-threaded included) and a cp314t wheel per platform (python.yml). A threads test
checks one engine from many threads and that the GIL stays off. -
The Dart package's build hook (D-289): Dart and Flutter apps get the native library with no
manual step, built from a checkout (hooks.user_defines.teigeodata.source, or in the
repository) or downloaded from the release and checked against its pinned SHA-256; a given
file (library:) overrides both.cargo xtask flutter-checkruns the example app's
integration test on the desktop, an iOS simulator or a device;flutter.ymlcovers macOS,
iOS, Linux, Windows and Android. -
The JVM binding's packages (D-288):
cargo xtask package-jvmmakes the Android AAR (arm64-v8a,
armeabi-v7a, x86_64; minSdk 24; 64-bit libraries checked for 16 KB pages) and the desktop JAR,
whoseNativeLoaderextracts its platform's library whenjava.library.pathhas none;
parity runs from the JAR and on an Android emulator;jvm.ymlbuilds six desktop platforms. -
The Swift package's XCFramework (D-287):
cargo xtask package-swift [--test]builds a
staticCTeiGeodata.xcframework(iOS, the iOS simulators, macOS) and tests the Swift
binding against it on macOS and an iOS simulator; a privacy manifest;Package.swiftgains
an XCFramework mode (TEIGEODATA_XCFRAMEWORK=1) and the parity checks a Swift Testing test. -
The C library as it ships (D-286):
libteigeodata(crateteigeodata-c) with an
@rpathinstall name and a versioned soname,cargo xtask package-c(header, shared and
static libraries, pkg-config, CMake, smoke-tested), full and lite archives for six targets
fromc-package.yml; the header guards the store's declarations with
TEIGEODATA_FEATURE_STORE. -
cargo xtask abi(D-285): the C ABI's compatibility with the last release and the symbols
the built library exports, on the full and the lite library in CI. -
The zone rules in every language (D-284):
Engine::tz_offset_at(offset, DST flag and
abbreviation at an instant),tz_local(a civil time's offsets: unique, a gap or an
overlap),tz_zones,tz_rules_startandtz_version; parity on a rules-only fixture. -
A job's idioms in each language, from the IDL's
# Jobcontract (IDL format 7): a
progress stream (Swiftprogress, JVMonProgress, Nodeprogress(), Dartprogress(),
Pythonteigeodata.aio.progress), and cancel through the language's own cancellation
(Swift task cancellation, JVMfuture.cancel, NodeAbortSignal, Python task
cancellation viateigeodata.aio.result) (D-283). -
Swift, the JVM and Dart: the same
…Asyncforms, as anasync throwsfunction, a
CompletableFutureand aFuturerun on a helper isolate; in Dart a handle closed during
one is freed when it ends. Python awaits them withasyncio.to_thread(D-281). -
teigeodata_sync::fetch::Ureq::with_timeouts, and a 30 s timeout for a response's head:
a host that accepts and never answers no longer holds a download forever (D-280). -
IDL format 6: a handle, record or function may carry
#[cfg(feature = "…")]; every
generated Rust layer gates it the same way. Thestorefeature (on by default) of
teigeodata-api,teigeodata-ffiand the Python, Node and JVM crates holds the store;
without it the C library is 949 KB instead of 3.1 MB (D-279). -
tgd's GeoJSONattributionand Nominatimlicencename the packs the places came from,
not every pack given, and are absent when nothing was found (D-311).tgd near --radius
refuses a radius that is not positive and finite. -
A cancel stops a metadata download at its next chunk, and its bytes count as progress:
Transport::fetch_streamed(thehttptransport reads in 16 KiB chunks); before, a slow
host held a refresh until its body ended (D-283). -
The C library's Apple builds leave header room for a rewritten install name
(-headerpad_max_install_names), as Dart, Flutter and other packagers rewrite it (D-289). -
The JVM binding keeps to Android API 24: handles are freed by a hand-written
NativeCleanerinstead ofjava.lang.ref.Cleaner(Android API 33), so the classes load on
older devices;NativeLoaderusesjava.io(java.nio.fileis API 26); parity runs on API
24 and API 35 emulators (D-288). -
Dart: calls that block are no longer leaf calls; a leaf call blocking in a helper isolate
kept every isolate of the group from a safepoint and stalled them (D-283). -
The
httptransport verifies TLS with Mozilla's roots (webpki-roots), as it always did:
the unusedrustls-platform-verifieris dropped (D-279 amends D-168). -
The store's policy (init, refresh, install with dependencies and selections, update,
remove, pin, repair, status) moved from the command line intoteigeodata_sync::client
(featureclient), for the bindings to share;tgdformats its results.tgd install
now prints its lines when the whole install ends. -
teigeodata_sync::watch: aWatch(progress in bytes, a sequence to wait on, cancel) and
Watched, a transport that reports to it and stops at the next request or chunk once
cancelled (FetchError::Cancelled,ClientError::Cancelled).Transport::expectpasses
the catalog's size of the work to come.
Fixed
-
Every result-blob reader refuses a blob with no column (D-349). Such a header could name billions of rows that no column bounds, and Go's
Reader.Recordswould build a record for each until memory ran out. Found by the Go reader's fuzzer; no valid blob is affected. -
The documentation, read against the code for 1.0 (D-343): a reverse answer's
bearingis from
the place to the point, several--packs follow the layer rule rather than their order, the
Nominatim routes' supported parameters and differences are listed, and each language's guide
names its own API (Rust's the typed engine, WebAssembly'sopenBytesonly). -
tgd verify --deepandteigeodata_format::check::sectionsnow run theTZ_RULESsection's
full check; it was skipped (D-335). -
tgd serve(http::serve) never timed out a slow request head or an idle connection, since
axum::servesets no hyper timer, and did not cap connections or requests in flight. It now
bounds all four, and sheds requests past the cap with 503 andRetry-After(D-334). -
bindings/fixtures/outline.tgdstored its hole counter-clockwise, against the format's rule
(Polygons::checkrefused it; queries re-orient, so no answer changes): the hole's arcs are
now reversed. Found when the fuzz seeds were held to the full check. -
A pack whose DEM, ARCS or POLYGONS states an item count near 2^64, or whose DEM has a grid
with an invalid tile side, step, datum, source, model or threshold, no longer panics a
query:Dem::openchecks every grid, model and threshold (O(grids)) and the three readers
refuse a count with no room for its end boundary. Found by the newenginefuzz target
(D-331). -
tz_atand every answer'stzcolumn named no zone in a world timezone area (tzwas null
at New York or Shanghai, set only where a country's pack recorded its own area): a timezone
area is now its own zone, whateverPLACE_TZholds for its row (D-327). -
The MCP
searchtool saidstrictkeeps every word in order; it ranks by how well the name
matched first, as everywhere else. The place fields of every tool's output schema now say
what each holds. -
/packsand MCP'spacksgave a pack's length in bytes as itsplaces; they give its
number of places. -
The HTTP server's failures and
/packsend with a newline, as every other answer does. -
Java and Kotlin:
new Engine()(orStore,Job) as a program's first call threw
UnsatisfiedLinkError: a nested class is initialized without its outer class, so the native
library was loaded only by a call onTeiGeodatafirst. Every handle class now loads it
(D-322). -
@teispace/teigeodata-wasmon Node.js loaded its browser entry: the packageexports
conditions were written sorted,defaultbeforenode(D-322). -
Shared::follow(andEngine::follow) opens a store pack with the parts it was installed
with (D-251); before, a pack of some parts was opened as whole, its parts not installed read
as holes (D-311).
Breaking
- The 1.0 API review (D-341):
Engine::within_radiustakesradius_m, notmeters, as every
other distance parameter ends in_m(andtgd servecalls itradius_m); in Swift the
label isradiusM:, in Python the keywordradius_m, in .NET the named argumentradiusM.Engine::postal_prefixtakes
prefix, notinput. Positional calls are unchanged. - 27 public enums are
#[non_exhaustive](D-337): errors such asErrorCode,ClientError
andStoreError; modes such asVerify,Loadand the server'sAsk; vocabularies such
asPlaceKind,Component,HeightSourceandCodeKind. Amatchon one outside its
crate needs a_arm. New:CodeKind::nameandHealth::name. - The pack format is 1.0 (D-336): packs written now have
format_majorand
min_reader_major1, so a reader before this release refuses them. This release reads
every pack of earlier releases.FORMAT_MAJOR,READER_MAJORandFORMAT_MINORare 1, 1
and 0. A client no longer downloads a pack whose catalog entry needs a newer reader. foldcan fail: in a build without thesearchcomponent it throws (returns)
MissingComponent, as its Unicode tables belong to search (D-292). Swift calls it with
try; the other languages throw unchecked, as from any other fallible call.- Python: blob results are
teigeodata.Blob, lent without a copy through the buffer
protocol, notbytes(bytes(blob)copies); the readerteigeodata.blob.Blobis now
teigeodata.blob.Readerand reads any buffer; CPython 3.11 is the oldest supported (3.10
is past its end of life) (D-290). - Dart: the bindings are
@Nativefunctions of the package's code asset (D-289).
TeiGeodata.open(path)is gone; useTeiGeodata(). The SDK floor is Dart 3.10. - Blobs start with the magic
TGB1instead ofTGB0. A binding or caller that checks the
magic compares withTGB1(or accepts both); the layout of the v0 types is unchanged.