leangeo 3.0.0__tar.gz

leangeo-3.0.0/.cargo/config.toml

@@ -0,0 +1,7 @@
+# Align loop starts to 32 bytes on x86_64: a hot loop of up to 32 bytes then never
+# straddles a 64-byte line. Without it, where each loop landed was luck of the build, and
+# a straddling loop (UTF-8 validation, roaring intersections) ran 10-20% slower on Zen 2
+# (measured with perf, HISTORY.md 2026-10-22). Cargo applies this to the release wheels
+# too (maturin runs cargo in this directory).
+[target.'cfg(target_arch = "x86_64")']
+rustflags = ["-C", "llvm-args=-align-loops=32"]

leangeo-3.0.0/.gitignore

@@ -0,0 +1,39 @@
+/target
+**/*.rs.bk
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.mmap
+*.db
+.venv/
+venv/
+
+# test/debug artifacts
+datetest/
+*.commit
+*.wal
+*.lock
+*.epoch
+*.base
+*.dels*.mmap
+*.ids*.mmap
+.pytest_cache/
+!Cargo.lock
+*.from2x

leangeo-3.0.0/CLIENT.md

@@ -0,0 +1,398 @@
+# LeanGeo API and Client Guide
+
+LeanGeo can run as a network service over **gRPC** or **REST** (HTTP/JSON). Both servers
+and a Python gRPC client ship in the wheel, in the `leangeo_server` package:
+
+- gRPC server: `leangeo_server.serve_grpc` (command `leangeo-grpc`), service defined in
+  `leangeo_server/leangeo.proto`
+- REST server: `leangeo_server.serve` (command `leangeo-serve`), FastAPI on uvicorn
+- Python client: `leangeo_server.client.LeanGeoClient`
+
+`import leangeo_engine` never imports any of this. In a source checkout, the root-level
+`serve.py`, `serve_grpc.py`, `serve_guardrails.py`, `client.py`, `leangeo_pb2.py` and
+`leangeo_pb2_grpc.py` are aliases of the packaged modules, so `uvicorn serve:app`,
+`python serve_grpc.py` and `from client import LeanGeoClient` still work from the
+repository root. The proto moved from `proto/leangeo.proto` to `leangeo_server/leangeo.proto`.
+
+**Polygon vertex order changed meaning in 3.0 — read [Polygons](#polygons) if you used
+the 2.x servers.**
+
+---
+
+## 1. Install
+
+The engine has no server dependencies. Install the extras into the environment where
+`leangeo` is installed:
+
+```bash
+pip install "leangeo[server]"    # REST server: fastapi, uvicorn[standard], pydantic>=2.8, orjson
+pip install "leangeo[grpc]"      # gRPC server and client: grpcio>=1.82.1, protobuf>=7.35,<8
+```
+
+The generated stubs (`leangeo_pb2.py`, `leangeo_pb2_grpc.py`) ship in the wheel, so
+`grpcio-tools` is only needed to regenerate them (section 9).
+
+---
+
+## 2. Run a server
+
+```bash
+leangeo-serve --path /data/geo     # REST, default 127.0.0.1:8003
+leangeo-grpc  --path /data/geo     # gRPC, default 127.0.0.1:50053
+```
+
+Equivalent forms: `LEANGEO_PATH=/data/geo python -m leangeo_server.serve_grpc`, and
+`LEANGEO_PATH=/data/geo uvicorn leangeo_server.serve:app --workers 1` for REST (uvicorn
+binds 127.0.0.1 unless you pass `--host`; see section 3 for what a non-loopback `--host`
+requires).
+
+Command-line flags only set the environment variables below, so flags and environment
+configure the same thing. `leangeo-serve` takes `--path --capacity --host --port
+--threads --allow-insecure`; `leangeo-grpc` takes `--path --capacity --host --port
+--workers --tls-cert --tls-key --allow-insecure`. The bearer token is read from
+`LEANGEO_API_TOKEN` only, so it never shows up in `ps`.
+
+Each server opens one `LeanGeoEngine` for its lifetime and runs every request on a worker
+thread (the gRPC `ThreadPoolExecutor`; FastAPI's threadpool for the REST endpoints, so no
+engine call runs on the event loop). The native core releases the GIL, so reads run in
+parallel; writes to one collection serialize. Run one process per data directory; the
+engine is also safe across processes if you run several.
+
+### Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `LEANGEO_PATH` | `leangeo_data` | Data directory (one set of files per collection) |
+| `LEANGEO_CAPACITY` | `100000` | Initial capacity hint for a new collection's files |
+| `LEANGEO_HOST` / `LEANGEO_PORT` | `127.0.0.1` / `8003` | REST bind address (`HOST`/`PORT` are read when these are unset) |
+| `LEANGEO_GRPC_HOST` / `LEANGEO_GRPC_PORT` | `127.0.0.1` / `50053` | gRPC bind address (`GRPC_HOST`/`GRPC_PORT` are read when these are unset) |
+| `LEANGEO_THREADS` | `min(64, 2 x CPUs)` | REST worker threads |
+| `LEANGEO_GRPC_WORKERS` | `min(64, 2 x CPUs)` | gRPC worker threads |
+| `LEANGEO_API_TOKEN` | unset | Bearer token required on every endpoint/RPC except health |
+| `LEANGEO_ALLOW_INSECURE` | unset | `1` permits non-loopback access without authentication |
+| `LEANGEO_GRPC_TLS_CERT` / `LEANGEO_GRPC_TLS_KEY` | unset | PEM certificate chain and key; gRPC serves TLS when both are set |
+| `LEANGEO_GRPC_MAX_CONCURRENT_RPCS` | unset (unbounded) | Running + queued RPCs; past it gRPC answers `RESOURCE_EXHAUSTED` immediately. Must be >= 1 |
+| `LEANGEO_GRPC_KEEPALIVE_TIME_MS` / `..._TIMEOUT_MS` | `60000` / `20000` | gRPC keepalive pings; a peer that stops answering is dropped and its RPCs cancelled |
+| `LEANGEO_WAL_SYNC_INTERVAL_MS` | unset | Unset: every acknowledged write is fsynced before the reply. N > 0: fsync within N ms (a crash may lose the last N ms) |
+
+Guardrail variables are listed in section 7.
+
+### Shutdown
+
+On SIGTERM or SIGINT both servers stop accepting work, let in-flight requests finish, and
+close the engine, which checkpoints every collection (the WAL is folded into the data
+files and emptied). The gRPC server waits up to 5 s for in-flight RPCs; REST waits up to
+30 s. From the moment shutdown begins, gRPC `Health` reports `ready: false` and other
+RPCs answer `UNAVAILABLE`; REST `/health` reports `"ready": false` and other endpoints
+answer 503.
+
+---
+
+## 3. Trust boundary, authentication, TLS
+
+The API can read, delete and clear every collection and has no per-collection
+authorization. Both servers therefore bind `127.0.0.1` by default, and the console
+scripts refuse to start on any other address (exit with a message) unless one of these
+holds:
+
+- REST: `LEANGEO_API_TOKEN` is set. Every endpoint except `GET /health` then requires
+  `Authorization: Bearer <token>`; a missing or wrong token is 401. Tokens are compared
+  in constant time.
+- gRPC: `LEANGEO_GRPC_TLS_CERT`, `LEANGEO_GRPC_TLS_KEY` **and** `LEANGEO_API_TOKEN` are all
+  set. Every RPC except `Health` then requires `authorization: Bearer <token>` metadata
+  (unary and streaming handlers alike); a missing or wrong token is `UNAUTHENTICATED`.
+  A token without TLS, or TLS without a token, is refused on a non-loopback address.
+- `LEANGEO_ALLOW_INSECURE=1`: you state that the network is already trusted (for example,
+  an authenticating reverse proxy in front of a private listener).
+
+The REST server also enforces this per request, on the address each connection actually
+reached, because an ASGI app cannot see how it was bound: when started directly with
+`uvicorn leangeo_server.serve:app --host 0.0.0.0` (or any non-loopback `--host`) and no
+token, every request that arrives on a non-loopback address is refused with 403, except
+`GET /health`; requests through `127.0.0.1` are served. Set `LEANGEO_API_TOKEN` (or
+`LEANGEO_ALLOW_INSECURE=1`) to serve other addresses. A reverse proxy on the same host
+that connects to `127.0.0.1` is served without a token.
+
+The token also works on loopback: setting `LEANGEO_API_TOKEN` always enables the check.
+IPv6 binds work for both servers (`LEANGEO_GRPC_HOST=::1`; the address is bracketed for
+gRPC).
+
+---
+
+## 4. REST API
+
+All bodies are JSON. Request models reject unknown fields with 422 (a misspelled
+`filter` must not run a query unfiltered), and so are unknown query parameters
+(`GET /count?colection=x` is 422, not a count of `default`). Every `collection` defaults
+to `"default"`. Collection names are letters, digits, `-`, `_` and `.`, not starting with
+`.` (the engine enforces this; anything else is 400).
+
+| Method and path | Body / query | Response |
+|---|---|---|
+| `GET /health` | | `{"status": "ok", "ready": bool, "limits": {...}}` |
+| `GET /count` | `?collection=` | `{"count": int}` |
+| `GET /collections` | | `{"collections": [str, ...]}` |
+| `POST /insert` | `{"latitude", "longitude", "metadata"?, "collection"?}` | `{"id": int}` |
+| `POST /insert_batch` | `[{"latitude", "longitude", "metadata"?, "collection"?}, ...]` or `{"items": [...], "collection"?}` | `{"ids": [int, ...], "count": int}` |
+| `POST /query` | `{"filter"?, "limit"?, "collection"?}` | `{"results": [...], "truncated": bool}` |
+| `POST /query_radius` | `{"center_lat", "center_lon", "radius_meters", "filter"?, "limit"?, "collection"?}` | same |
+| `POST /query_bbox` | `{"min_lat", "min_lon", "max_lat", "max_lon", "filter"?, "limit"?, "collection"?}` | same |
+| `POST /query_polygon` | `{"coordinates": [[lon, lat], ...], "filter"?, "limit"?, "collection"?}` | same |
+| `POST /exists` | `{"filter"?, "collection"?}` | `{"exists": bool}` |
+| `POST /delete` | `{"filter", "collection"?}` (filter required) | `{"deleted": int}` |
+| `POST /clear` | `{"collection", "confirm": true}` (both required) | `{"deleted": int}` |
+| `POST /compact` | `{"collection"?}` | `{"reclaimed": int}` |
+| `POST /persist` | none | `{"status": "ok"}` |
+| `GET /verify` | `?collection=&flush=false` | `{"ok": bool, "errors": [str, ...]}` |
+
+Result rows are `{"id": int, "latitude": float, "longitude": float, "metadata": {...}}`,
+the same dicts the library returns, in the same order.
+
+Notes:
+
+- **Ids** are integers per collection, stable, and never reused.
+- **`/insert_batch`** is atomic per collection: it makes one `engine.insert_batch` call
+  (one durable WAL record) per collection in the request, so one invalid point means none
+  of the batch is written. The 2.x server inserted point by point (one fsync each, and a
+  bad point left the earlier ones written). A batch that spans several collections is
+  validated in full (names, coordinates) before the first collection is written; after
+  that each collection commits on its own, so only a storage failure between two
+  collections can leave the earlier ones written. In the `{"items": ...}` form, an item
+  without its own `collection` uses the batch's.
+- **`limit`** is optional on every read. Omitted means "everything, up to the server
+  cap"; `0` returns no rows (as in the library, after validating the filter); negative
+  is 400. See section 7 for `truncated`.
+- **`collection`** defaults to `"default"` when omitted; an explicit `""` is refused with
+  400, as the library refuses it.
+- **`/query_bbox`** with `min_lon > max_lon` crosses the antimeridian.
+- **`/delete`** refuses (400, nothing deleted) a filter that matches every point by its
+  shape (`{}`, `{"f": {"$nin": []}}`, ...) or because it tests a field no point has (a
+  misspelled name). `/clear` is the explicit wipe and needs `"confirm": true`.
+- **`/compact`** reclaims the slots of deleted points now (it also runs in the background).
+  Ids do not change.
+- **`/persist`** checkpoints every open collection; a failure is 500 with the detail.
+- **`/verify`** recomputes the checksum of every committed region; `flush=true` checkpoints
+  first.
+
+Example:
+
+```bash
+curl -s localhost:8003/insert_batch -H 'content-type: application/json' -d '[
+  {"latitude": -23.55, "longitude": -46.63, "metadata": {"city": "SP"}},
+  {"latitude": -22.91, "longitude": -43.17, "metadata": {"city": "RJ"}}]'
+curl -s localhost:8003/query_radius -H 'content-type: application/json' \
+  -d '{"center_lat": -23.0, "center_lon": -45.0, "radius_meters": 500000, "filter": {"city": "RJ"}}'
+```
+
+### Filters
+
+Filters are the MongoDB-style contract shared by the Lean* engines (top-level metadata
+fields; equality, `$eq $ne $gt $gte $lt $lte $in $nin $exists`, `$and $or $nor $not`, and
+array membership). The engine validates them; an unknown operator, a
+malformed shape, or a NaN/infinite number is 400 (`INVALID_ARGUMENT`), never silently
+treated as "match all" or "match null". Over REST, `null` or an omitted `filter` means no
+filter on reads.
+
+---
+
+## 5. Polygons
+
+Polygon vertices are **(longitude, latitude)** pairs, GeoJSON order, everywhere in 3.0:
+
+- library: `engine.query_polygon([(lon, lat), ...])`
+- REST: `"coordinates": [[lon, lat], ...]`; objects `{"latitude": .., "longitude": ..}`
+  are accepted too and are unambiguous
+- gRPC: `repeated LatLon coordinates`, a message with named `latitude` and `longitude`
+  fields; the server hands the engine `(longitude, latitude)`
+- Python client: `query_polygon([(lon, lat), ...])`, or dicts with `"latitude"` and
+  `"longitude"` keys
+
+**Migration from 2.x.** The 2.x `CLIENT.md` and `client.py` documented `(lat, lon)`
+tuples, and the 2.x gRPC server built `(latitude, longitude)` tuples from `LatLon`
+messages, which swapped the axes relative to the library. A 2.x Python caller that
+passed `(lat, lon)` tuples to `LeanGeoClient.query_polygon` must swap them (or pass dicts).
+A raw gRPC caller that filled `LatLon` by field name needs no change: those messages now
+mean what their field names say. Containment is planar; split a polygon that crosses
+the antimeridian yourself. Fewer than 3 vertices matches nothing. The vertex count is
+capped (section 7).
+
+---
+
+## 6. gRPC API and the Python client
+
+Service `leangeo.LeanGeo` (`leangeo_server/leangeo.proto`). Metadata, filters and result
+rows travel as JSON strings (`metadata_json`, `filter_json`, `results_json`) so their JSON
+types survive; coordinates are doubles. An empty `filter_json` means no filter on reads.
+`collection` and `limit` are proto3 `optional` fields: unset `collection` means
+`"default"` and an explicit `""` is `INVALID_ARGUMENT` (as in the library and REST);
+unset `limit` means no limit of your own (the server cap still applies) and `limit = 0`
+returns no rows after validating the request. All 2.x field numbers are unchanged and the
+encoding is the same (a 2.x client never sends `""` or `0`, so its requests keep their
+2.x meaning); 3.0 only adds fields and RPCs.
+
+| RPC | Request | Reply |
+|---|---|---|
+| `Health` | | `ready`, `limits_json` |
+| `Count` | `collection` | `count` |
+| `ListCollections` (3.0) | | `collections` |
+| `Insert` | `point {latitude, longitude, metadata_json, collection}` | `id` |
+| `InsertBatch` | `repeated Point points` | `repeated ids` (atomic per collection, as REST) |
+| `Query` | `filter_json, limit, collection` | `results_json, truncated` |
+| `QueryRadius` | `center_lat, center_lon, radius_meters, filter_json, collection, limit` | same |
+| `QueryBbox` | `min_lat, min_lon, max_lat, max_lon, filter_json, collection, limit` | same |
+| `QueryPolygon` | `repeated LatLon coordinates, filter_json, collection, limit` | same |
+| `Exists` (3.0) | `filter_json, collection` | `exists` |
+| `Delete` | `filter_json` (required), `collection` | `deleted` |
+| `Clear` (3.0) | `collection, confirm` (must be true) | `deleted` |
+| `Compact` (3.0) | `collection` | `reclaimed` |
+| `Persist` | | `status` |
+| `Verify` | `collection, flush` | `json` (`{"ok", "errors"}`) |
+
+A `filter_json` or `metadata_json` that is not a JSON object (`[]`, `0`, `"x"`) is
+`INVALID_ARGUMENT`.
+
+### LeanGeoClient
+
+```python
+from leangeo_server.client import LeanGeoClient
+
+with LeanGeoClient("localhost:50053", timeout=30) as c:
+    c.wait_ready()
+    pid = c.insert(-23.55, -46.63, {"city": "SP"})
+    ids = c.insert_batch([{"latitude": -22.91, "longitude": -43.17, "metadata": {"city": "RJ"}},
+                          {"latitude": 40.71, "longitude": -74.0, "collection": "us"}])
+    near = c.query_radius(-23.0, -45.0, 500_000, filter={"city": "RJ"})
+    box = c.query_bbox(-40, -80, 10, -30, limit=100)
+    inside = c.query_polygon([(-50, -30), (-40, -30), (-40, -20), (-50, -20)])  # (lon, lat)
+    rows, truncated = c.query({"city": {"$in": ["SP", "RJ"]}}, with_truncated=True)
+    c.delete({"city": "SP"})
+    c.clear("us", confirm=True)
+    c.compact(); c.persist(); print(c.verify(), c.count(), c.list_collections(), c.limits())
+```
+
+Constructor: `LeanGeoClient(target="localhost:50053", *, timeout=None, channel=None,
+options=None, token=None, tls=False, allow_insecure_token=False)`.
+
+- `token` defaults to `LEANGEO_API_TOKEN` from the environment and is sent as
+  `authorization: Bearer <token>`.
+- `tls=True` uses the system roots; `tls=<PEM bytes>` trusts that root certificate (for a
+  self-signed server). The client refuses to send a token over a plaintext channel unless
+  `allow_insecure_token=True`.
+- The channel is thread-safe and multiplexes concurrent RPCs: share one client across
+  threads.
+
+Methods: `health()`, `limits()`, `count(collection)`, `list_collections()`,
+`insert(lat, lon, metadata, collection)`, `insert_batch(points, collection)`,
+`query(filter, limit, collection)`, `query_radius(center_lat, center_lon, radius_meters,
+filter, collection, limit)`, `query_bbox(min_lat, min_lon, max_lat, max_lon, filter,
+collection, limit)`, `query_polygon(coordinates, filter, collection, limit)`,
+`exists(filter, collection)`, `delete(filter, collection)`, `clear(collection, *,
+confirm)`, `compact(collection)`, `persist()`, `verify(collection, flush)`. The read
+methods take `with_truncated=True` to return `(rows, truncated)`. Every method takes a
+keyword `timeout` that overrides the default deadline.
+
+Errors surface as `grpc.RpcError`:
+
+```python
+import grpc
+try:
+    c.delete({})
+except grpc.RpcError as e:
+    print(e.code(), e.details())     # StatusCode.INVALID_ARGUMENT, "delete_by_metadata requires ..."
+```
+
+---
+
+## 7. Limits and guardrails
+
+Static caps reject oversized requests before they reach the engine. They can be set
+through the environment, but **only lowered**: a value above the default (or one that does
+not parse) leaves the default in place.
+
+| Variable | Default | Bounds |
+|---|---|---|
+| `LEANGEO_MAX_BODY_BYTES` | 128 MiB | One REST body (413 past it); the gRPC send/receive message size |
+| `LEANGEO_MAX_BATCH` | 100000 | Points per `insert_batch` (429) |
+| `LEANGEO_MAX_POLYGON_VERTICES` | 100000 | Vertices per polygon query (429) |
+| `LEANGEO_HARD_MAX_K` | 1000000 | Absolute ceiling on rows per read reply |
+| `LEANGEO_MIN_K` | 1000 | Floor of the dynamic cap while memory allows it |
+| `LEANGEO_MEM_FRACTION` | 0.5 | Share of available RAM that read replies may use (0 < f <= 1) |
+| `LEANGEO_BODY_MEM_FRACTION` | `LEANGEO_MEM_FRACTION` | Share of available RAM that request bodies being parsed may use |
+| `LEANGEO_PER_RESULT_BYTES` | 4096 | Memory estimate per returned row |
+| `LEANGEO_MEM_REFRESH_SECS` | 1.0 | How often the memory figures are re-read |
+| `LEANGEO_MAX_OPEN_COLLECTIONS` | (soft fd limit - 256) / 8, at most 4096 | Collections held open at once; past it the least recently used idle ones are closed (checkpointed) and reopen on their next use |
+
+**Dynamic result cap.** The rows one reply may hold are
+`clamp(available_RAM * MEM_FRACTION / workers / PER_RESULT_BYTES)` between `MIN_K` and
+`HARD_MAX_K`, where available RAM is the smaller of `MemAvailable` and the remaining
+allowance of this process's cgroup (v1 or v2). Every read passes a limit to the engine,
+so rows are bounded before they are materialized: when your `limit` is within the cap
+it is used as is; otherwise the server asks the engine for `cap + 1` rows, returns
+`cap`, and sets `truncated: true` if the extra row existed. The serialized rows must also
+fit a byte budget (the same memory share, at most 8 x `MAX_BODY_BYTES`; for gRPC also at
+most the message cap, `MAX_BODY_BYTES`); serialization stops at the first row that would
+pass it and `truncated` is set. The byte budget is also passed to the engine, which stops
+building rows once it is reached, so rows with large metadata never materialize the
+whole row cap. `truncated: false` means you got every row
+you asked for. To read more than the cap, narrow the query (a smaller box or radius, a
+filter) or partition it. The current figures are in `GET /health` (`limits`) and gRPC
+`Health.limits_json`.
+
+**Body admission (REST).** A declared `Content-Length` past `MAX_BODY_BYTES` is refused
+with 413 before any byte is read. A chunked body, or any body sent with
+`Transfer-Encoding`, is counted as it arrives and refused once it passes the cap. Every
+nonempty body also reserves its estimated parse memory (about 4x its size, more for
+token-dense JSON such as `[0,0,0,...]`) against a budget the bodies in flight share; a
+body that does not fit the memory free right now is refused with 429 and `Retry-After: 1`
+before it is parsed. Refusals close the connection. Authentication runs before
+admission.
+
+**gRPC.** Messages larger than `MAX_BODY_BYTES` are refused by gRPC itself
+(`RESOURCE_EXHAUSTED`). The JSON strings in a request (filters, metadata) reserve their
+estimated parse memory from the same kind of budget while the RPC runs; one that does not
+fit is `RESOURCE_EXHAUSTED`. `LEANGEO_GRPC_MAX_CONCURRENT_RPCS` optionally bounds running
+plus queued RPCs.
+
+**Open collections.** Each open collection holds about 6 to 8 file descriptors. At start
+the servers raise the soft `RLIMIT_NOFILE` to the hard limit (at most 65536), and they keep
+at most `LEANGEO_MAX_OPEN_COLLECTIONS` collections open, closing the least recently used
+idle ones; a collection a request is using is never closed under it. Running out of
+descriptors anyway is reported as 503 / `UNAVAILABLE`, not as corruption.
+
+---
+
+## 8. Errors
+
+| Condition | REST | gRPC | Retry? |
+|---|---|---|---|
+| Bad input: coordinates out of range or non-finite, bad filter, bad collection name, `InvalidInputError`, `ValueError`, `TypeError`; guarded delete; `clear` without confirmation | 400 | `INVALID_ARGUMENT` | no |
+| Missing or wrong bearer token | 401 | `UNAUTHENTICATED` | no |
+| No token configured and the request reached a non-loopback address (REST, section 3) | 403 | n/a (the server refuses to start) | no |
+| Unknown route, or the engine reports a missing item (`KeyError`) | 404 | `NOT_FOUND` | no |
+| Body past `LEANGEO_MAX_BODY_BYTES` (also an invalid `Content-Length`: 400) | 413 | `RESOURCE_EXHAUSTED` | no |
+| Unknown body field or query parameter, wrong JSON types | 422 | n/a | no |
+| Over a guardrail (batch size, vertices, memory for parsing, `LEANGEO_GRPC_MAX_CONCURRENT_RPCS`) | 429 + `Retry-After: 1` | `RESOURCE_EXHAUSTED` | later |
+| `StorageError` (I/O failure, corruption, a poisoned collection), or any unexpected error | 500 | `INTERNAL` | no, needs an operator |
+| Engine not open, closed (`ClosedError`), or shutting down; out of file descriptors (EMFILE/ENFILE) | 503 + `Retry-After: 1` | `UNAVAILABLE` | yes |
+
+Error details are bounded to 512 characters. REST 422 bodies list the location and
+message of at most 16 validation errors and do not echo the submitted values.
+
+---
+
+## 9. Regenerating the gRPC stubs
+
+Only needed after editing `leangeo_server/leangeo.proto` in a source checkout:
+
+```bash
+pip install "grpcio-tools==1.82.1"         # in a throwaway environment
+python scripts/gen_grpc.py                 # rewrite leangeo_server/leangeo_pb2*.py
+python scripts/gen_grpc.py --check         # exit 1 if the checked-in stubs are stale
+```
+
+The script refuses any other grpcio-tools version: newer tools stamp a newer minimum
+runtime into the stubs. It compiles with the proto's own directory as the include root
+(descriptor `leangeo.proto`, package `leangeo`), so the wire protocol does not depend on
+where the package lives, and rewrites the generated `import leangeo_pb2` into a relative
+import. `tests/test_server_packaging_lifecycle.py` runs the `--check` when grpcio-tools
+1.82.1 is importable or `LEANGEO_GRPC_TOOLS_PYTHON` points at a Python that has it.