stratus-db 0.1.0__py3-none-any.whl

stratus_db-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.1
+Name: stratus-db
+Version: 0.1.0
+Summary: The stratus-db service from Python: typed JSON over urllib, no dependencies.
+Project-URL: Homepage, https://stratus-db.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# stratus-db (Python)
+
+The stratus service from Python 3.9+: typed JSON over `urllib` (docs/json.md), no
+dependencies.
+
+The client is one file, `stratus_db.py`. Install it from PyPI (`pip install stratus-db`; a
+wheel only, published from this repository's release workflow with PyPI's attestations), or
+copy the file into your project. To pin it, use `pip install --require-hashes` with the wheel's
+hash, or compare the file's sha256 with the one published beside it.
+
+```python
+import datetime as dt, os
+from decimal import Decimal
+from stratus_db import connect, kw, squuid
+
+s = connect("https://api.stratus-db.com", api_key=os.environ["STRATUS_KEY"])
+db = s.create_db(primary_key="invoice/id", name="invoices")["id"]
+
+s.transact(db, tx=[{
+    "invoice/id": squuid(),                        # every row carries its key
+    "invoice/total": Decimal("1234.50"),           # exact, scale kept
+    "invoice/due": dt.date(2026, 11, 1),
+    "invoice/sent": dt.datetime.now(dt.timezone.utc),
+    "invoice/status": kw("status/sent"),           # a keyword, not the string "status/sent"
+}], tx_id="import-42")                             # a retry with the same id applies once
+
+s.request_index(db, "invoice/status")
+s.await_index(db, "invoice/status")
+page = s.query(db, where=["=", "invoice/status", kw("status/sent")], limit=100)
+for row in s.query_all(db, where=["range", "invoice/due", dt.date(2026, 11, 1), None]):
+    ...
+```
+
+## Values
+
+| stratus | Python |
+|---|---|
+| string, boolean, nil | `str`, `bool`, `None` |
+| long | `int` (exact at any size) |
+| double | `float` (`1.0` stays a double) |
+| BigDecimal | `decimal.Decimal` (scale kept) |
+| BigInteger, ratio | `BigInteger` (an `int`), `fractions.Fraction` |
+| keyword, symbol, char | `Keyword` (`kw("a/b")`, interned), `Sym`, `Char` |
+| UUID | `uuid.UUID` (`squuid()` for keys) |
+| instant | `datetime` with a timezone (naive ones are refused); reads as `Instant`, a UTC `datetime` with `.nanosecond` past its microseconds |
+| local date | `datetime.date` |
+| bytes | `bytes` |
+| vector, list | `list` or `tuple`, `List` |
+| set | `set`/`frozenset` (reads as `frozenset`; `SetOf` when its elements can't be hashed) |
+| map | `dict` (string keys are attribute names); `Map` when keys are values (a string key a string) |
+
+A date or instant outside years 1-9999 reads as a `Tagged`, which writes back unchanged. A
+UUID, instant or keyword passed as a plain string is stored as a string and matches nothing of
+the intended type.
+
+## API
+
+Failures raise `StratusError` (`status`, `error` - e.g. `"invalid-query"`, `"conflict"` -,
+`message`). 429s are retried with backoff (`retries`).
+
+- Catalog: `list_dbs(deleted=False)`, `db_by_name`, `db_record`, `create_db(primary_key, name=None)`,
+  `rename_db`, `delete_db`.
+- A database: `status`, `transact(db, tx=, retract=, delete=, tx_id=, match=)`,
+  `query(db, where=, select=, limit=, after=)`, `query_all` (a generator), `pull(db, pks)`,
+  `request_index`, `await_index`, `drop_index`, `history(db, start=1, limit=)`, `history_all`,
+  `fork(db, t=, name=)` (hosted: a new database, this one as of t), `excise(db, rows=,
+  attributes=)` (erasure: rows and (pk, att) out of the state, indexes, history and forks).
+- Keys (hosted, with a key reaching every database): `list_keys()`, `create_key(name=, scope=)`,
+  `revoke_key(key_id)`.
+- Codec: `encode`, `decode`, `to_json_value`, `from_json_value`.
+
+Addressing: `"hosted"` (default: `<url>/v1/dbs/<id>/...`, `Authorization: Bearer <api_key>`)
+or `"function-urls"` (the internal service's Function URLs, resolved through its catalog;
+`caller` for a local service).
+
+## Tests
+
+`python3 -m unittest tests.test_ejson` (the codec, over velojity's own output in
+`clients/fixtures/velojity-ejson.json`), and `scripts/test-python-client` from the repo root
+(`PYTHON=` picks the interpreter): the codec, then the client against the local service.

stratus_db-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+stratus_db.py,sha256=8a3pFwDcgwBs5H4k4_TyDBUe_zV5kJedfQQKtIBnysc,31420
+stratus_db-0.1.0.dist-info/METADATA,sha256=SbmtCwfHh99wzIxm6k3bgt-tO-2i6oFoWk0YL4A2Rbk,4237
+stratus_db-0.1.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+stratus_db-0.1.0.dist-info/top_level.txt,sha256=Zek6EF6TjIfVIN_fr6U7vxvm-vft4udFrtvcQUFWU8w,11
+stratus_db-0.1.0.dist-info/RECORD,,

stratus_db-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stratus_db-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+stratus_db

stratus_db.py

@@ -0,0 +1,801 @@
+"""stratus_db: the stratus-db service from Python (3.9+), typed JSON over urllib. No
+dependencies, and one file: the same file is on PyPI and at stratus-db.com/clients/, with its
+sha256. See README.md and docs/json.md.
+
+The stratus client: typed JSON over urllib (docs/json.md), 429s retried with backoff, pages
+followed. Failures raise StratusError.
+
+    from stratus_db import connect, kw, squuid
+    s = connect("https://api.stratus-db.com", api_key=os.environ["STRATUS_KEY"])
+    db = s.create_db(name="orders", primary_key="order/id")["id"]
+    s.transact(db, tx=[{"order/id": squuid(), "order/status": kw("status/new")}])
+    rows = s.query(db, where=["=", "order/status", kw("status/new")])["rows"]
+
+Addressing: "hosted" (the default) - the catalog at <url>/v1/dbs, a database at
+<url>/v1/dbs/<id>/..., the API key as "Authorization: Bearer <key>". "function-urls" - the
+internal service: the catalog at url, each database at the Function URL its catalog record
+names (looked up, cached for resolve_s, and again when one answers 403 or 404); caller names
+the caller (x-stratus-caller) for a local service.
+"""
+
+from __future__ import annotations
+
+import base64
+import datetime as _dt
+import gzip
+import json
+import math
+import os
+import random
+import re
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid as _uuid
+from decimal import Decimal, InvalidOperation
+from fractions import Fraction
+
+__version__ = "0.1.0"
+
+# sent with every request, so old copies can be seen (and their users warned)
+USER_AGENT = f"stratus-db-python/{__version__}"
+
+__all__ = [
+    "BigInteger", "Char", "Client", "Instant", "Keyword", "List", "Map", "SetOf", "StratusError", "Sym", "Tagged",
+    "connect", "decode", "encode", "from_json_value", "kw", "squuid", "to_json_value",
+]
+
+
+# ------------------------------------------------------------------ Values
+# The value types stratus stores that Python has no exact equivalent for.
+#
+# Python's own types cover most of stratus's: str, bool, None, int (a long), float (a double),
+# decimal.Decimal, fractions.Fraction, uuid.UUID, datetime (an instant), date (a local date),
+# bytes, list (a vector), set/frozenset, dict (a map with keyword keys). These add the rest:
+# keywords, symbols, chars, lists (as opposed to vectors), big integers (as opposed to longs),
+# instants past microseconds, maps keyed by values, and tags this client doesn't know.
+#
+# Strings stay strings: a UUID, an instant or a keyword must be one of these types, or it is
+# stored as a string and matches nothing of the intended type.
+
+class Keyword:
+    """A keyword (:status/sent). Interned: equal keywords are the same object."""
+
+    __slots__ = ("namespace", "name", "__weakref__")
+    _table: dict = {}
+    _lock = threading.Lock()
+
+    def __new__(cls, text: str):
+        t = str(text)
+        if t.startswith(":"):
+            t = t[1:]
+        if t == "":
+            raise ValueError("A keyword has a name")
+        k = cls._table.get(t)
+        if k is None:
+            with cls._lock:
+                k = cls._table.get(t)
+                if k is None:
+                    k = object.__new__(cls)
+                    i = t.find("/")
+                    if i <= 0 or len(t) == 1:
+                        object.__setattr__(k, "namespace", None)
+                        object.__setattr__(k, "name", t)
+                    else:
+                        object.__setattr__(k, "namespace", t[:i])
+                        object.__setattr__(k, "name", t[i + 1:])
+                    cls._table[t] = k
+        return k
+
+    def __setattr__(self, *_):
+        raise AttributeError("Keywords are immutable")
+
+    @property
+    def full_name(self) -> str:
+        return self.name if self.namespace is None else f"{self.namespace}/{self.name}"
+
+    def __repr__(self):
+        return f"kw({self.full_name!r})"
+
+    def __str__(self):
+        return ":" + self.full_name
+
+    def __reduce__(self):
+        return (Keyword, (self.full_name,))
+
+
+def kw(text: str) -> Keyword:
+    """The keyword named "ns/name" (or "name")."""
+    return Keyword(text)
+
+
+class Sym(str):
+    """A symbol (rare in data; kept so values read and written round-trip)."""
+
+    def __repr__(self):
+        return f"Sym({str.__repr__(self)})"
+
+
+class Char(str):
+    """A single character."""
+
+    def __new__(cls, c):
+        s = str.__new__(cls, c)
+        if len(s) != 1:
+            raise ValueError(f"A char is one character: {c!r}")
+        return s
+
+    def __repr__(self):
+        return f"Char({str.__repr__(self)})"
+
+
+class BigInteger(int):
+    """An arbitrary-size integer (java.math.BigInteger), as distinct from a long. An int: it
+    does arithmetic as one (the result a plain int)."""
+
+    def __repr__(self):
+        return f"BigInteger({int.__repr__(self)})"
+
+
+class List(list):
+    """A list (as opposed to a vector, which is a plain list or tuple)."""
+
+    def __repr__(self):
+        return f"List({list.__repr__(self)})"
+
+
+class Map(dict):
+    """A map whose keys are values (a string key is a string, a UUID a UUID), as opposed to a
+    plain dict, whose string keys are keywords (attribute names)."""
+
+    def __repr__(self):
+        return f"Map({dict.__repr__(self)})"
+
+
+class SetOf(list):
+    """A set whose elements Python can't hash (maps, vectors): its elements, as a list."""
+
+    def __repr__(self):
+        return f"SetOf({list.__repr__(self)})"
+
+
+class Instant(_dt.datetime):
+    """An instant with nanosecond precision: a UTC datetime plus nanosecond (0-999 past its
+    microsecond). Arithmetic gives plain datetimes."""
+
+    nanosecond: int = 0
+
+    @classmethod
+    def of(cls, d: _dt.datetime, nanosecond: int = 0) -> "Instant":
+        if d.tzinfo is None:
+            raise ValueError("A naive datetime isn't an instant: give it a timezone")
+        u = d.astimezone(_dt.timezone.utc)
+        i = cls(u.year, u.month, u.day, u.hour, u.minute, u.second, u.microsecond, tzinfo=_dt.timezone.utc)
+        if not 0 <= nanosecond <= 999:
+            raise ValueError(f"nanosecond: {nanosecond}")
+        i.nanosecond = nanosecond
+        return i
+
+    def __repr__(self):
+        return f"Instant({iso_instant(self)!r})"
+
+    def __eq__(self, other):
+        if isinstance(other, _dt.datetime):
+            return _dt.datetime.__eq__(self, other) and getattr(other, "nanosecond", 0) == self.nanosecond
+        return NotImplemented
+
+    def __ne__(self, other):
+        # datetime defines its own !=, which would ignore the nanoseconds
+        eq = self.__eq__(other)
+        return eq if eq is NotImplemented else not eq
+
+    def __hash__(self):
+        return hash((_dt.datetime.__hash__(self), self.nanosecond))
+
+
+def iso_instant(d: _dt.datetime) -> str:
+    """ISO-8601 UTC text, as Java's Instant writes it: a fraction of 3, 6 or 9 digits, or none."""
+    if d.tzinfo is None:
+        raise ValueError("A naive datetime isn't an instant: give it a timezone")
+    u = d.astimezone(_dt.timezone.utc)
+    nanos = u.microsecond * 1000 + getattr(d, "nanosecond", 0)
+    frac = ""
+    if nanos:
+        n = f"{nanos:09d}"
+        frac = "." + (n[:3] if nanos % 1000000 == 0 else n[:6] if nanos % 1000 == 0 else n)
+    return f"{u.year:04d}-{u.month:02d}-{u.day:02d}T{u.hour:02d}:{u.minute:02d}:{u.second:02d}{frac}Z"
+
+
+class Tagged:
+    """A typed-JSON tag this client doesn't know or Python can't hold (a date past year 9999),
+    kept as it came: it writes back as itself."""
+
+    __slots__ = ("tag", "rep")
+
+    def __init__(self, tag: str, rep):
+        self.tag = tag
+        self.rep = rep
+
+    def __eq__(self, other):
+        return isinstance(other, Tagged) and other.tag == self.tag and other.rep == self.rep
+
+    def __hash__(self):
+        return hash((self.tag, repr(self.rep)))
+
+    def __repr__(self):
+        return f"Tagged({self.tag!r}, {self.rep!r})"
+
+
+# ------------------------------------------------------------------ Typed JSON
+# Typed JSON (docs/json.md): stratus's encoding, MongoDB Extended JSON v2's tags where they
+# mean the same and stratus's own where it has none.
+#
+# Python to stratus:
+#   str, bool, None        themselves
+#   int                    a long (within ±2^53 plain, else $numberLong); past 64 bits $bigint;
+#                          a BigInteger always $bigint
+#   float                  a double (NaN and the infinities $numberDouble)
+#   Decimal, Fraction      $numberDecimal (scale kept), $ratio
+#   UUID                   $uuid
+#   datetime               $inst (timezone required; an Instant keeps its nanoseconds)
+#   date                   $localDate
+#   Keyword, Sym, Char     $kw, $sym, $char
+#   bytes, bytearray       $binary
+#   list, tuple            a vector; a List a list
+#   set, frozenset, SetOf  $set
+#   dict                   a map: its keys are keywords (str or Keyword); other keys - or a
+#                          Map - $map
+#   Tagged                 its tag
+# stratus to Python: the same, backwards. A local date or instant Python can't hold (past year
+# 9999, before year 1) reads as a Tagged, which writes back as it came.
+
+MAX_SAFE = 2 ** 53 - 1
+INT64_MIN = -(2 ** 63)
+INT64_MAX = 2 ** 63 - 1
+
+
+def _tag(t, rep):
+    return {t: rep}
+
+
+def _double_text(f: float) -> str:
+    if math.isnan(f):
+        return "NaN"
+    return "Infinity" if f > 0 else "-Infinity"
+
+
+def _key_name(k) -> str | None:
+    """A dict key's keyword name, or None when the key isn't a keyword."""
+    if isinstance(k, Keyword):
+        return k.full_name
+    if type(k) is str:
+        return k
+    return None
+
+
+def to_json_value(x):
+    """The JSON tree of value x (json.dumps writes it)."""
+    if x is None or isinstance(x, bool):
+        return x
+    if isinstance(x, (Sym, Char)):
+        return _tag("$sym" if isinstance(x, Sym) else "$char", str(x))
+    if isinstance(x, str):
+        return x
+    if isinstance(x, BigInteger):
+        return _tag("$bigint", str(int(x)))
+    if isinstance(x, int):
+        if -MAX_SAFE <= x <= MAX_SAFE:
+            return int(x)
+        if INT64_MIN <= x <= INT64_MAX:
+            return _tag("$numberLong", str(int(x)))
+        return _tag("$bigint", str(int(x)))
+    if isinstance(x, float):
+        return x if math.isfinite(x) else _tag("$numberDouble", _double_text(x))
+    if isinstance(x, Decimal):
+        if not x.is_finite():
+            raise ValueError(f"No typed-JSON encoding for the decimal {x}")
+        return _tag("$numberDecimal", str(x))
+    if isinstance(x, Fraction):
+        return _tag("$ratio", f"{x.numerator}/{x.denominator}")
+    if isinstance(x, _uuid.UUID):
+        return _tag("$uuid", str(x))
+    if isinstance(x, _dt.datetime):
+        return _tag("$inst", iso_instant(x))
+    if isinstance(x, _dt.date):
+        return _tag("$localDate", x.isoformat())
+    if isinstance(x, Keyword):
+        return _tag("$kw", x.full_name)
+    if isinstance(x, (bytes, bytearray)):
+        return _tag("$binary", {"base64": base64.b64encode(bytes(x)).decode("ascii"), "subType": "00"})
+    if isinstance(x, Tagged):
+        return _tag(x.tag, to_json_value(x.rep))
+    if isinstance(x, List):
+        return _tag("$list", [to_json_value(y) for y in x])
+    if isinstance(x, SetOf):
+        return _tag("$set", [to_json_value(y) for y in x])
+    if isinstance(x, (list, tuple)):
+        return [to_json_value(y) for y in x]
+    if isinstance(x, (set, frozenset)):
+        return _tag("$set", [to_json_value(y) for y in x])
+    if isinstance(x, dict):
+        names = None if isinstance(x, Map) else [_key_name(k) for k in x]
+        # a map of keyword keys is an object - unless its one key starts with $ (a tag)
+        if names is not None and None not in names and not (len(names) == 1 and names[0].startswith("$")):
+            return {n: to_json_value(v) for n, v in zip(names, x.values())}
+        return _tag("$map", [[to_json_value(Keyword(k) if type(k) is str and not isinstance(x, Map) else k),
+                              to_json_value(v)] for k, v in x.items()])
+    raise TypeError(f"No typed-JSON encoding for {type(x).__name__}")
+
+
+def encode(x) -> str:
+    """x as typed-JSON text."""
+    return json.dumps(to_json_value(x), separators=(",", ":"), ensure_ascii=False, allow_nan=False)
+
+
+def _text(t, rep) -> str:
+    if not isinstance(rep, str):
+        raise ValueError(f"{t} takes a string")
+    return rep
+
+
+def _array(t, rep) -> list:
+    if not isinstance(rep, list):
+        raise ValueError(f"{t} takes an array")
+    return rep
+
+
+_INT = re.compile(r"^[+-]?\d+$")
+_NUM = re.compile(r"^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$")
+_ISO_INSTANT = re.compile(r"^([+-]\d{4,}|\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$")
+_ISO_DATE = re.compile(r"^([+-]\d{4,}|\d{4})-(\d{2})-(\d{2})$")
+
+
+def _parse_long(t, s):
+    if not _INT.match(s):
+        raise ValueError(f"{t} isn't an integer: {s}")
+    n = int(s)
+    if not INT64_MIN <= n <= INT64_MAX:
+        raise ValueError(f"{t} isn't a 64-bit integer: {s}")
+    return n
+
+
+def _parse_double(s):
+    if s == "NaN":
+        return math.nan
+    if s == "Infinity":
+        return math.inf
+    if s == "-Infinity":
+        return -math.inf
+    if not _NUM.match(s):
+        raise ValueError(f"$numberDouble isn't a number: {s}")
+    return float(s)
+
+
+def _parse_instant(text):
+    m = _ISO_INSTANT.match(text)
+    if m is None:
+        raise ValueError(f"Not an ISO instant: {text}")
+    y, mo, d, h, mi, s, frac = m.groups()
+    year = int(y)
+    nanos = int(frac.ljust(9, "0")) if frac else 0
+    if not 1 <= year <= 9999:
+        _check_date_fields(year, int(mo), int(d), text)
+        return Tagged("$inst", text)
+    base = _dt.datetime(year, int(mo), int(d), int(h), int(mi), int(s), nanos // 1000, tzinfo=_dt.timezone.utc)
+    return Instant.of(base, nanos % 1000)
+
+
+def _check_date_fields(year, month, day, text):
+    # a year Python can't hold: check the month and day against a leap or common year like it
+    leap = year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
+    try:
+        _dt.date(2000 if leap else 2001, month, day)
+    except ValueError:
+        raise ValueError(f"Not a date: {text}") from None
+
+
+def _parse_date(text):
+    m = _ISO_DATE.match(text)
+    if m is None:
+        raise ValueError(f"Not an ISO date: {text}")
+    year, month, day = int(m.group(1)), int(m.group(2)), int(m.group(3))
+    if not 1 <= year <= 9999:
+        _check_date_fields(year, month, day, text)
+        return Tagged("$localDate", text)
+    return _dt.date(year, month, day)
+
+
+def _hashable(x):
+    """x as a hashable map key or set element (vectors as tuples), or raise TypeError."""
+    if isinstance(x, list) and not isinstance(x, (List, SetOf)):
+        return tuple(_hashable(y) for y in x)
+    hash(x)
+    return x
+
+
+def _decode_tag(t, rep, strict):
+    if t in ("$numberLong", "$numberInt"):
+        return _parse_long(t, _text(t, rep))
+    if t == "$numberDouble":
+        return _parse_double(_text(t, rep))
+    if t == "$numberDecimal":
+        s = _text(t, rep)
+        if not _NUM.match(s):
+            raise ValueError(f"$numberDecimal isn't a decimal: {s}")
+        return Decimal(s)
+    if t == "$bigint":
+        s = _text(t, rep)
+        if not _INT.match(s):
+            raise ValueError(f"$bigint isn't an integer: {s}")
+        return BigInteger(int(s))
+    if t == "$ratio":
+        m = re.match(r"^([+-]?\d+)/(\d+)$", _text(t, rep))
+        if m is None:
+            raise ValueError(f"$ratio is n/d: {rep}")
+        return Fraction(int(m.group(1)), int(m.group(2)))
+    if t == "$kw":
+        return Keyword(_text(t, rep))
+    if t == "$sym":
+        return Sym(_text(t, rep))
+    if t == "$char":
+        return Char(_text(t, rep))
+    if t == "$uuid":
+        return _uuid.UUID(_text(t, rep))
+    if t == "$inst":
+        return _parse_instant(_text(t, rep))
+    if t == "$date":
+        if isinstance(rep, str):
+            return Instant.of(_dt.datetime.fromisoformat(rep.replace("Z", "+00:00")))
+        if isinstance(rep, dict) and isinstance(rep.get("$numberLong"), str):
+            ms = _parse_long(t, rep["$numberLong"])
+            return Instant.of(_dt.datetime(1970, 1, 1, tzinfo=_dt.timezone.utc) + _dt.timedelta(milliseconds=ms))
+        raise ValueError("$date takes an ISO string or {$numberLong: millis}")
+    if t == "$localDate":
+        return _parse_date(_text(t, rep))
+    if t == "$binary":
+        if not isinstance(rep, dict):
+            raise ValueError("$binary takes {base64, subType}")
+        b = base64.b64decode(_text("$binary's base64", rep.get("base64")), validate=True)
+        sub = _text("$binary's subType", rep.get("subType"))
+        if sub in ("04", "4"):
+            if len(b) != 16:
+                raise ValueError("A $binary UUID (subtype 04) has 16 bytes")
+            return _uuid.UUID(bytes=b)
+        return b
+    if t == "$set":
+        items = [from_json_value(y, strict) for y in _array(t, rep)]
+        try:
+            return frozenset(_hashable(y) for y in items)
+        except TypeError:
+            return SetOf(items)
+    if t == "$list":
+        return List(from_json_value(y, strict) for y in _array(t, rep))
+    if t == "$map":
+        pairs = []
+        for p in _array(t, rep):
+            if not isinstance(p, list) or len(p) != 2:
+                raise ValueError("A $map entry is [k, v]")
+            pairs.append((from_json_value(p[0], strict), from_json_value(p[1], strict)))
+        # keys all keywords (a lone $-named key, escaped): a plain dict, whose keys are keywords
+        if pairs and all(isinstance(k, Keyword) for k, _ in pairs):
+            return {k.full_name: v for k, v in pairs}
+        return Map((_hashable(k), v) for k, v in pairs)
+    if strict:
+        raise ValueError(f"Unknown typed-JSON tag {t}")
+    return Tagged(t, from_json_value(rep, strict))
+
+
+def from_json_value(x, strict: bool = False):
+    """The value of a parsed JSON tree. strict: an unknown tag raises."""
+    if isinstance(x, list):
+        return [from_json_value(y, strict) for y in x]
+    if isinstance(x, dict):
+        if len(x) == 1:
+            (k, v), = x.items()
+            if k.startswith("$"):
+                return _decode_tag(k, v, strict)
+        return {k: from_json_value(v, strict) for k, v in x.items()}
+    return x
+
+
+def decode(text, strict: bool = False):
+    """The value of typed-JSON text (str or bytes). strict: an unknown tag raises."""
+    try:
+        return from_json_value(json.loads(text), strict)
+    except InvalidOperation as e:
+        raise ValueError(str(e)) from None
+
+
+# ------------------------------------------------------------------ The client
+
+class StratusError(Exception):
+    """A request that failed: its HTTP status, the error's kind ("invalid-query") and message."""
+
+    def __init__(self, status: int, error, message, body=None):
+        super().__init__(f"HTTP {status}{' ' + error if error else ''}: {message or ''}")
+        self.status = status
+        self.error = error
+        self.message = message
+        self.body = body
+
+
+def _att_name(att) -> str:
+    return att.full_name if isinstance(att, Keyword) else str(att).lstrip(":")
+
+
+def connect(url: str, **opts) -> "Client":
+    """A client of the stratus service at url (see Client)."""
+    return Client(url, **opts)
+
+
+class Client:
+    def __init__(self, url: str, api_key: str | None = None, addressing: str = "hosted",
+                 caller: str | None = None, retries: int = 10, resolve_s: float = 300.0,
+                 timeout: float = 30.0):
+        """url: the service's base URL (hosted) or the catalog's (function-urls). retries:
+        attempts after a 429. timeout: seconds a request may take."""
+        if addressing not in ("hosted", "function-urls"):
+            raise ValueError(f"addressing: {addressing}")
+        self.url = url.rstrip("/")
+        self.api_key = api_key
+        self.addressing = addressing
+        self.caller = caller
+        self.retries = retries
+        self.resolve_s = resolve_s
+        self.timeout = timeout
+        self._urls = (0.0, {})
+        self._lock = threading.Lock()
+
+    # -- requests
+
+    def send(self, url: str, method: str, body=None):
+        """method url body: (status, body read as typed JSON when it is JSON, else text)."""
+        headers = {"accept": "application/json", "accept-encoding": "gzip", "user-agent": USER_AGENT}
+        data = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            data = encode(body).encode("utf-8")
+        if self.api_key:
+            headers["authorization"] = f"Bearer {self.api_key}"
+        if self.caller:
+            headers["x-stratus-caller"] = self.caller
+        attempt = 0
+        while True:
+            req = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                    status, rh, raw = r.status, r.headers, r.read()
+            except urllib.error.HTTPError as e:
+                status, rh, raw = e.code, e.headers, e.read()
+            if status == 429 and attempt < self.retries:
+                # full jitter: up to 50 ms x 2^attempt, at most 5 s
+                time.sleep(random.random() * min(5.0, 0.05 * 2 ** attempt))
+                attempt += 1
+                continue
+            if (rh.get("content-encoding") or "").lower() == "gzip":
+                raw = gzip.decompress(raw)
+            text = raw.decode("utf-8")
+            value = text
+            if (rh.get("content-type") or "").startswith("application/json") and text:
+                try:
+                    value = decode(text)
+                except ValueError:
+                    value = text
+            return status, value
+
+    @staticmethod
+    def _ok(r):
+        status, body = r
+        if 200 <= status < 300:
+            return body
+        if isinstance(body, dict):
+            raise StratusError(status, body.get("error"), body.get("message"), body)
+        raise StratusError(status, None, str(body), body)
+
+    def _catalog_url(self, path: str) -> str:
+        return f"{self.url}/v1{path}" if self.addressing == "hosted" else f"{self.url}{path}"
+
+    def call_catalog(self, method: str, path: str, body=None):
+        """method path body to the catalog: (status, body)."""
+        return self.send(self._catalog_url(path), method, body)
+
+    def _resolve(self) -> dict:
+        recs = self._ok(self.call_catalog("GET", "/dbs"))
+        by_id = {str(r["id"]): r["url"] for r in recs if r.get("url")}
+        with self._lock:
+            self._urls = (time.monotonic(), by_id)
+        return by_id
+
+    def _db_base(self, id):
+        key = str(id)
+        if self.addressing == "hosted":
+            return f"{self.url}/v1/dbs/{urllib.parse.quote(key, safe='')}"
+        at, by_id = self._urls
+        if key in by_id and time.monotonic() - at < self.resolve_s:
+            return by_id[key].rstrip("/")
+        u = self._resolve().get(key)
+        return None if u is None else u.rstrip("/")
+
+    def call_db(self, id, method: str, path: str, body=None):
+        """method path body to database id: (status, body)."""
+        base = self._db_base(id)
+        if base is None:
+            return 404, {"error": "no-database", "message": f"No database {id}"}
+        r = self.send(base + path, method, body)
+        if self.addressing == "function-urls" and r[0] in (403, 404):
+            again = self._resolve().get(str(id))
+            if again is not None and again.rstrip("/") != base:
+                return self.send(again.rstrip("/") + path, method, body)
+        return r
+
+    # -- the catalog
+
+    def list_dbs(self, deleted: bool = False) -> list:
+        """The live databases' records (deleted=True: deleted ones too)."""
+        return self._ok(self.call_catalog("GET", "/dbs?deleted=true" if deleted else "/dbs"))
+
+    def db_by_name(self, name: str) -> dict:
+        return self._ok(self.call_catalog("GET", "/dbs?" + urllib.parse.urlencode({"name": name})))
+
+    def db_record(self, id) -> dict:
+        return self._ok(self.call_catalog("GET", f"/dbs/{urllib.parse.quote(str(id), safe='')}"))
+
+    def create_db(self, primary_key, name: str | None = None) -> dict:
+        """Creates a database: {"id", "url"}. primary_key is fixed for its life ("order/id")."""
+        body = {"primary-key": Keyword(_att_name(primary_key))}
+        if name is not None:
+            body["name"] = name
+        return self._ok(self.call_catalog("POST", "/dbs", body))
+
+    def rename_db(self, id, name: str) -> dict:
+        return self._ok(self.call_catalog("PATCH", f"/dbs/{urllib.parse.quote(str(id), safe='')}", {"name": name}))
+
+    def delete_db(self, id) -> dict:
+        return self._ok(self.call_catalog("DELETE", f"/dbs/{urllib.parse.quote(str(id), safe='')}"))
+
+    # -- keys (hosted: an account's keys, managed with a key whose scope is every database)
+
+    def list_keys(self) -> list:
+        """The account's keys' records (no secrets)."""
+        return self._ok(self.call_catalog("GET", "/keys"))
+
+    def create_key(self, name: str | None = None, scope=None) -> dict:
+        """A new key: {"key" (shown once), "record"}. scope: database ids it may reach (default all)."""
+        body = {}
+        if name is not None:
+            body["name"] = name
+        if scope is not None:
+            body["scope"] = [str(x) for x in scope]
+        return self._ok(self.call_catalog("POST", "/keys", body))
+
+    def revoke_key(self, key_id: str) -> dict:
+        """Revokes key key_id: its record."""
+        return self._ok(self.call_catalog("DELETE", f"/keys/{urllib.parse.quote(key_id, safe='')}"))
+
+    # -- a database
+
+    def status(self, id) -> dict:
+        """The database's state: id, primary-key, t, checkpoint-t, indexes, index-errors, status."""
+        return self._ok(self.call_db(id, "GET", "/status" if self.addressing == "hosted" else "/"))
+
+    def transact(self, id, tx=None, retract=None, delete=None, tx_id=None, match=None) -> dict:
+        """Transacts: {"t", "pks", "duplicate"?}. tx: rows (each with its primary key:
+        squuid()), retract: rows of attributes to remove, delete: primary keys, tx_id: makes a
+        retry safe, match: rows whose attributes must hold those values now (else a 409
+        "conflict")."""
+        body = {}
+        for k, v in (("tx", tx), ("retract", retract), ("delete", delete), ("tx-id", tx_id), ("match", match)):
+            if v is not None:
+                body[k] = v
+        return self._ok(self.call_db(id, "POST", "/transact", body))
+
+    def query(self, id, where=None, select=None, limit: int | None = None, after=None) -> dict:
+        """One page of a query (docs/query.md, "JSON"): {"rows", "next", "t"}."""
+        q = {}
+        for k, v in (("where", where), ("select", select), ("limit", limit), ("after", after)):
+            if v is not None:
+                q[k] = v
+        return self._ok(self.call_db(id, "POST", "/query", q))
+
+    def query_all(self, id, where=None, select=None, limit: int | None = None, after=None):
+        """Every row of a query, page after page (a generator)."""
+        while True:
+            page = self.query(id, where=where, select=select, limit=limit, after=after)
+            yield from page["rows"]
+            if page.get("next") is None:
+                return
+            after = page["next"]
+
+    def pull(self, id, pks) -> list:
+        """The rows of primary keys pks, in order (None where there is none)."""
+        return self._ok(self.call_db(id, "POST", "/pull", {"pks": list(pks)}))["rows"]
+
+    def request_index(self, id, att) -> dict:
+        """Requests a value index on att: {"att", "state"} ("building" until a checkpoint)."""
+        return self._ok(self.call_db(id, "POST", "/indexes", {"att": _att_name(att)}))
+
+    def drop_index(self, id, att) -> dict:
+        path = "/".join(urllib.parse.quote(p, safe="") for p in _att_name(att).split("/"))
+        return self._ok(self.call_db(id, "DELETE", f"/indexes/{path}"))
+
+    def await_index(self, id, att, timeout_s: float = 60.0, interval_s: float = 0.2) -> dict:
+        """Waits until att's index is ready: the status (raises if it failed or timed out)."""
+        name = _att_name(att)
+        deadline = time.monotonic() + timeout_s
+        while True:
+            s = self.status(id)
+            state = (s.get("indexes") or {}).get(name)
+            if state == "ready":
+                return s
+            if state == "failed":
+                raise StratusError(409, "index-failed", (s.get("index-errors") or {}).get(name, f"{name} failed"), s)
+            if time.monotonic() > deadline:
+                raise StratusError(408, "timeout", f"{name} isn't ready ({state})", s)
+            time.sleep(interval_s)
+
+    def fork(self, id, t: int | None = None, name: str | None = None) -> dict:
+        """Forks database id (hosted): a new database, this one as of t (default its latest),
+        recorded in both logs. The fork's record ({"id", "fork-of": {"db", "t"}, ...})."""
+        body = {}
+        if t is not None:
+            body["t"] = t
+        if name is not None:
+            body["name"] = name
+        return self._ok(self.call_db(id, "POST", "/fork", body))
+
+    def excise(self, id, rows=None, attributes=None) -> dict:
+        """Excises rows (primary keys) and attributes ([(pk, att) ...]) - erasure: gone from the
+        current state, its indexes and history (and, hosted, the database's forks)."""
+        body = {}
+        if rows is not None:
+            body["rows"] = list(rows)
+        if attributes is not None:
+            body["attributes"] = [{"pk": pk, "att": _att_name(att)} for pk, att in attributes]
+        return self._ok(self.call_db(id, "POST", "/excise", body))
+
+    def history(self, id, start: int = 1, limit: int | None = None) -> dict:
+        """One page of the database's history from t = start: {"entries", "next"}."""
+        params = {"from": start}
+        if limit is not None:
+            params["limit"] = limit
+        return self._ok(self.call_db(id, "GET", "/history?" + urllib.parse.urlencode(params)))
+
+    def history_all(self, id, start: int = 1, limit: int | None = None):
+        """Every history entry from t = start, page after page (a generator)."""
+        t = start
+        while True:
+            page = self.history(id, start=t, limit=limit)
+            yield from page["entries"]
+            if page.get("next") is None:
+                return
+            t = page["next"]
+
+
+# Sequential UUIDs for primary keys: every transacted row carries its key (so a retried
+# transaction lands on the same rows), and squuids keep new rows at the right of the
+# database's tree. The server's layout (RFC 9562 version 7): 48 bits of Unix ms, the version,
+# a 12-bit sequence, the variant, 62 random bits. Later ones in this process sort after
+# earlier ones (the server's UUID order); across processes, to the millisecond.
+
+_squuid_lock = threading.Lock()
+_squuid_state = [0, 0]
+
+
+def squuid() -> _uuid.UUID:
+    """A sequential UUID."""
+    now = time.time_ns() // 1000000
+    with _squuid_lock:
+        ms, seq = _squuid_state
+        if now > ms:
+            ms, seq = now, 0
+        elif seq < 0xFFF:
+            seq += 1
+        else:
+            ms, seq = ms + 1, 0
+        _squuid_state[0], _squuid_state[1] = ms, seq
+    r = bytearray(os.urandom(8))
+    r[0] = 0x80 | (r[0] & 0x3F)
+    hi = (ms << 16) | (0x7 << 12) | seq
+    return _uuid.UUID(int=(hi << 64) | int.from_bytes(r, "big"))