Skip to content

v1.0.0

Choose a tag to compare

@github-actions github-actions released this 16 Nov 10:07
· 60 commits to main since this release

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) returns Population { people, source }; every place result has the
    nullable columns population and population_kind in every language, and tgd, the HTTP
    server and MCP print population and population_kind. extract::merge keeps every
    component of COMPONENTS. Both WebAssembly packages build extra (feature of
    teigeodata-wasm); every binding's parity suite checks both columns.
  • teigeodata-engine feature fuzz: 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 by cargo test (D-331); teigeodata_format::fuzz::edit_section builds such
    packs, and the edited sections' full check runs too.
  • teigeodata_sync::fuzz::trust (feature fuzz, now with repo): the TUF update chain and
    the catalog on a repository with one role attacked, nightly as the trust target (D-331).
  • teigeodata_ffi::fuzz::abi (feature fuzz): every engine function of the C ABI with fuzzed
    arguments, nightly as the ffi target; teigeodata_server::fuzz::mcp (features fuzz and
    mcp): every MCP tool with arguments from its own input schema, and resource reads, nightly
    as the mcp target (D-331).
  • The weekly fuzzing campaign (fuzz-campaign.yml): every target for 3 hours with coverage
    reports, and its gate cargo xtask fuzz-coverage, which fails unless every section kind's
    decoder is reached (D-331).
  • teigeodata_server::http::Config gains header_timeout, max_connections and
    max_in_flight, and tgd serve gains --max-connections and --max-in-flight (D-334).
  • cargo xtask unsafe-audit: the inventory of every unsafe in 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::extensions lists them. COMPONENTS IDs are 1
    to 127. teigeodata_format::fuzz::{bodies, write_again} rebuild a pack from its sections.
  • A result Reader of 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 gains Has, Column and Records, Python's has, column,
    records and iteration, .NET's BlobReader Has, Numbers, Column, Records and
    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 by cargo xtask bindings, the servers' from teigeodata_server::http::ENDPOINTS
    (a route table a test holds to the parser) and mcp::tool_definitions and
    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, and bearing_deg in the
    language API and every binding, with parity values checked in each (D-324).
    teigeodata_engine::Outline::write_geojson and write_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, and site/scripts/check-playground.mjs
    runs it in Chromium in the docs workflow (D-328).
  • --record on package-wasm, sizes and load, and cargo 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, to site/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's profile and scaling examples (D-338).
  • cargo xtask accuracy <cc> <pack>: a shipped pack scored against the blind labels of
    tests/golden/<cc>-places.csv and its second pass, written as the generated
    data/countries/<cc>/ACCURACY.md (D-339).
  • Suite C, the competitive report: tools/competitive and competitive.yml ask teigeodata,
    tgd serve, Nominatim, Photon, GeoNames' own points and tzf-rs the same questions (D-340).

Changed

  • teigeodata_format::Sorted::find interpolates in u64 and uses u128 only 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_m calls the engine's meters_between instead of a second haversine of its own
    (D-324).

  • cargo xtask load names each pack in bold and right-aligns its figures, so its tables read
    as Markdown (D-326).

  • cargo xtask load: a load test of tgd serve and its /mcp on real packs with oha,
    gated by tools/load/budget.toml (requests per second, p99, footprint and its growth)
    (D-320); cargo xtask sizes --tgd reports 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 and SHA256SUMS;
    gh attestation verify <file> --repo teispace/teigeodata checks one.

  • The crates teigeodata-core, -blob, -format, -names, -sync, -engine, -api,
    -server and -cli are publishable to crates.io (D-303, D-310).

  • teigeodata-server, the request core both servers and tgd share (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 (feature serve, on by default) and teigeodata_server::http (feature http):
    every query as a GET route under /v1/, /packs and /health, on axum; bound to
    127.0.0.1, CORS off unless configured, a 4 KiB query string, a request timeout, a panic
    answered internal; follows the store's journal every 5 s (D-312).

  • tgd serve answers Nominatim's /search, /reverse and /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 (feature mcp, on by default) and teigeodata_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, the boundary tool links the outline as the resource
    teigeodata://boundary/{id}?lod= (D-317).

  • /v1/coverage?lat=&lon=&radius_m= and the MCP tool coverage, on a server over the store:
    the countries at a point with the catalog's packs for it and their state, as tgd locate
    answers, read from the stored catalog without opening the store (D-318).
    teigeodata_sync::client::catalog_at reads it so; PackState::of.

  • MCP install and install_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 with install_status, from one job registry. The size is
    confirmed by the person first (MRTR elicitation in 2026-07-28, elicitation/create for a
    2025-11-25 client on stdio), else the download must fit max_bytes (100 MB by default). On
    for tgd mcp (--no-install leaves it out), opt-in for tgd serve (--allow-install)
    (D-318).

  • The official MCP conformance suite runs in CI against tgd serve for 2025-11-25 and
    2026-07-28 clients, every check gated against a reasoned baseline (D-319). It found, now
    fixed: /mcp on loopback accepts the server's own origin; prompts/list and
    completion/complete answer method not found (neither is declared); a missing resource's
    error carries data.uri (SEP-2164).

  • tgd serve answers MCP at /mcp (stateless Streamable HTTP), refusing a foreign Host
    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:teigeodata and com.teispace:teigeodata-android.

  • The parity gate (D-300): cargo xtask parity-mutants plants each value of
    bindings/parity.json and requires every language's parity suite to fail on it; C and C++
    read the values from the generated bindings/c/parity_data.h. The suites check the values
    the gate found unchecked (column names, get's longitude, dst, error codes).

  • bindings/bench.sh measures 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), SafeHandle handles,
    …Async forms of the blocking store calls, Job.ProgressAsync and a cancellable
    ResultAsync, BlobReader for blobs and TeiGeodataException with 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 with CGO_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); Reader for blobs; *Error with 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/teigeodata with 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 by cargo 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, the Engine over pack bytes, built and size-checked by
    cargo xtask package-wasm (D-293).

  • components() in every binding: the components the build answers. teigeodata-api has a
    Cargo feature per pack component, all in components (default); a build without one keeps
    every function and answers as a layer installed without it (D-291).

  • teigeodata-blob format 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), and u8, i16, u16 columns. v0 blobs
    still read.

  • The Engine handle in every binding (C, Python, Node, JVM, Swift, Dart): open packs from a
    file or bytes (each answers its layer ID; remove takes it), then get, 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) and Corrupt (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)
    and Engine::search_with use them in every binding; leaving the options out (C NULL)
    means the defaults.

  • IDL format 4: enums (D-277), each its language's own enum. OpenOptions (priority,
    Verify lazy/eager/trusted, Load map/read, outline level and tolerance) with
    Engine::open_file_with and open_bytes_with in every binding.

  • IDL format 5: text fields in records (String, empty by default). OpenOptions gains
    components (point,names,search; what they need is added) and languages (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 was InvalidArgument.

  • The Store and Job handles in every binding (D-279, research note store-api): create,
    open, catalog, status, pin, remove, engine (an engine over the installed packs),
    find and locate (the catalog's packs for a name or a point, over any engine, offline),
    and refresh, install (with InstallOptions: components, languages, outline, pin),
    update and repair as jobs on a thread of their own, with wait_progress, seq,
    done_bytes, total_bytes, is_ended, cancel and result. A cancelled install leaves
    the store as it was.

  • Error codes Network (7) and Refused (8) (D-279).

  • Node: every call that blocks (the store's, a job's waitProgress and result) has a
    …Async form returning a Promise (D-280); the IDL marks such calls blocks from a
    # Blocks documentation section.

  • Store::install_pass in 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 of Refused (D-282).

  • IDL: an options record must be the last parameter, so every language can default it.

  • Python wheels (D-290): bindings/python/pyproject.toml builds 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-check runs the example app's
    integration test on the desktop, an iOS simulator or a device; flutter.yml covers macOS,
    iOS, Linux, Windows and Android.

  • The JVM binding's packages (D-288): cargo xtask package-jvm makes the Android AAR (arm64-v8a,
    armeabi-v7a, x86_64; minSdk 24; 64-bit libraries checked for 16 KB pages) and the desktop JAR,
    whose NativeLoader extracts its platform's library when java.library.path has none;
    parity runs from the JAR and on an Android emulator; jvm.yml builds six desktop platforms.

  • The Swift package's XCFramework (D-287): cargo xtask package-swift [--test] builds a
    static CTeiGeodata.xcframework (iOS, the iOS simulators, macOS) and tests the Swift
    binding against it on macOS and an iOS simulator; a privacy manifest; Package.swift gains
    an XCFramework mode (TEIGEODATA_XCFRAMEWORK=1) and the parity checks a Swift Testing test.

  • The C library as it ships (D-286): libteigeodata (crate teigeodata-c) with an
    @rpath install 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
    from c-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_start and tz_version; parity on a rules-only fixture.

  • A job's idioms in each language, from the IDL's # Job contract (IDL format 7): a
    progress stream (Swift progress, JVM onProgress, Node progress(), Dart progress(),
    Python teigeodata.aio.progress), and cancel through the language's own cancellation
    (Swift task cancellation, JVM future.cancel, Node AbortSignal, Python task
    cancellation via teigeodata.aio.result) (D-283).

  • Swift, the JVM and Dart: the same …Async forms, as an async throws function, a
    CompletableFuture and a Future run on a helper isolate; in Dart a handle closed during
    one is freed when it ends. Python awaits them with asyncio.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. The store feature (on by default) of
    teigeodata-api, teigeodata-ffi and 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 GeoJSON attribution and Nominatim licence name 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 (the http transport 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
    NativeCleaner instead of java.lang.ref.Cleaner (Android API 33), so the classes load on
    older devices; NativeLoader uses java.io (java.nio.file is 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 http transport verifies TLS with Mozilla's roots (webpki-roots), as it always did:
    the unused rustls-platform-verifier is 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 into teigeodata_sync::client
    (feature client), for the bindings to share; tgd formats its results. tgd install
    now prints its lines when the whole install ends.

  • teigeodata_sync::watch: a Watch (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::expect passes
    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.Records would 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 bearing is 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's openBytes only).

  • tgd verify --deep and teigeodata_format::check::sections now run the TZ_RULES section'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::serve sets 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 and Retry-After (D-334).

  • bindings/fixtures/outline.tgd stored its hole counter-clockwise, against the format's rule
    (Polygons::check refused 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::open checks every grid, model and threshold (O(grids)) and the three readers
    refuse a count with no room for its end boundary. Found by the new engine fuzz target
    (D-331).

  • tz_at and every answer's tz column named no zone in a world timezone area (tz was 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, whatever PLACE_TZ holds for its row (D-327).

  • The MCP search tool said strict keeps 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.

  • /packs and MCP's packs gave a pack's length in bytes as its places; they give its
    number of places.

  • The HTTP server's failures and /packs end with a newline, as every other answer does.

  • Java and Kotlin: new Engine() (or Store, 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 on TeiGeodata first. Every handle class now loads it
    (D-322).

  • @teispace/teigeodata-wasm on Node.js loaded its browser entry: the package exports
    conditions were written sorted, default before node (D-322).

  • Shared::follow (and Engine::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_radius takes radius_m, not meters, as every
    other distance parameter ends in _m (and tgd serve calls it radius_m); in Swift the
    label is radiusM:, in Python the keyword radius_m, in .NET the named argument radiusM. Engine::postal_prefix takes
    prefix, not input. Positional calls are unchanged.
  • 27 public enums are #[non_exhaustive] (D-337): errors such as ErrorCode, ClientError
    and StoreError; modes such as Verify, Load and the server's Ask; vocabularies such
    as PlaceKind, Component, HeightSource and CodeKind. A match on one outside its
    crate needs a _ arm. New: CodeKind::name and Health::name.
  • The pack format is 1.0 (D-336): packs written now have format_major and
    min_reader_major 1, so a reader before this release refuses them. This release reads
    every pack of earlier releases. FORMAT_MAJOR, READER_MAJOR and FORMAT_MINOR are 1, 1
    and 0. A client no longer downloads a pack whose catalog entry needs a newer reader.
  • fold can fail: in a build without the search component 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, not bytes (bytes(blob) copies); the reader teigeodata.blob.Blob is now
    teigeodata.blob.Reader and reads any buffer; CPython 3.11 is the oldest supported (3.10
    is past its end of life) (D-290).
  • Dart: the bindings are @Native functions of the package's code asset (D-289).
    TeiGeodata.open(path) is gone; use TeiGeodata(). The SDK floor is Dart 3.10.
  • Blobs start with the magic TGB1 instead of TGB0. A binding or caller that checks the
    magic compares with TGB1 (or accepts both); the layout of the v0 types is unchanged.