stratus-db 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# stratus-db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The stratus service from JavaScript: typed JSON over `fetch` (docs/json.md), no dependencies.
+Node 20+ or a browser.
+
+The client is one ES module, `stratus-db.js`. Install it from npm (`npm install stratus-db`: the
+package holds only that file, this README and a `package.json` with no scripts, published from
+this repository's release workflow), or copy the file into your project. To pin it, use your
+lockfile's integrity hash, or compare the file's sha256 with the one published beside it.
+
+```js
+import { connect, kw, squuid, decimal, instant, localDate } from "stratus-db";
+
+const s = connect({ url: "https://api.stratus-db.com", apiKey: process.env.STRATUS_KEY });
+const { id } = await s.createDb({ name: "invoices", primaryKey: "invoice/id" });
+
+await s.transact(id, { tx: [{
+  "invoice/id": squuid(),                    // every row carries its key
+  "invoice/total": decimal("1234.50"),       // exact, scale kept
+  "invoice/due": localDate("2026-11-01"),
+  "invoice/sent": instant(new Date()),
+  "invoice/status": kw("status/sent"),       // a keyword, not the string "status/sent"
+}], txId: "import-42" });                    // a retry with the same id applies once
+
+await s.requestIndex(id, "invoice/status");
+await s.awaitIndex(id, "invoice/status");
+const { rows, next } = await s.query(id, { where: ["=", "invoice/status", kw("status/sent")], limit: 100 });
+for await (const row of s.queryAll(id, { where: ["range", "invoice/due", localDate("2026-11-01"), null] })) { /* ... */ }
+```
+
+## Values
+
+| stratus | JavaScript |
+|---|---|
+| string, boolean, nil | string, boolean, `null` |
+| long | `number` within ±2^53, else `bigint` (write either) |
+| double | `number` (an integral one is written as a long: `double(1)` keeps a double) |
+| BigDecimal | `Decimal` (its text; no arithmetic) |
+| BigInteger, ratio | `BigInteger`, `Ratio` |
+| keyword, symbol, char | `Keyword` (`kw("a/b")`, interned), `Sym`, `Char` |
+| UUID | `Uuid` (`uuid("...")`, `squuid()`; interned) |
+| instant | `Instant` (nanoseconds; `instant(date or ISO)`, `.toDate()`); a `Date` writes as one |
+| local date | `LocalDate` (`localDate("2026-10-09")`) |
+| bytes | `Uint8Array` |
+| vector, list, set | `Array`, `List` (`list(1, 2)`), `Set` |
+| map | a plain object (keys are attribute names); `Map` when keys aren't keywords |
+
+A UUID, instant or keyword passed as a plain string is stored as a string and matches nothing
+of the intended type.
+
+## API
+
+All methods return promises; failures reject with `StratusError` (`status`, `error` - e.g.
+`"invalid-query"`, `"conflict"` -, `message`). 429s are retried with backoff (`retries`).
+
+- Catalog: `listDbs({deleted})`, `dbByName(name)`, `dbRecord(id)`, `createDb({name, primaryKey})`,
+  `renameDb(id, name)`, `deleteDb(id)`.
+- A database: `status(id)`, `transact(id, {tx, retract, delete, txId, match})`, `query(id, q)`,
+  `queryAll(id, q)` (async iterator), `pull(id, pks)`, `requestIndex(id, att)`,
+  `awaitIndex(id, att)`, `dropIndex(id, att)`, `history(id, {from, limit})`, `historyAll`,
+  `fork(id, {t, name})` (hosted: a new database, this one as of t), `excise(id, {rows,
+  attributes})` (erasure: rows and {pk, att} out of the state, indexes, history and forks).
+- Keys (hosted, with a key reaching every database): `listKeys()`, `createKey({name, scope})`,
+  `revokeKey(keyId)`.
+- Codec: `encode`, `decode` (typed-JSON text), `toJSONValue`, `fromJSONValue`.
+
+Queries: docs/query.md ("JSON"). Addressing: `"hosted"` (default: `<url>/v1/dbs/<id>/...`,
+`Authorization: Bearer <apiKey>`) or `"function-urls"` (the internal service's Function URLs,
+resolved through its catalog; `caller` for a local service).
+
+## Tests
+
+`node --test test/ejson.test.js` (the codec: velojity's own output in
+`clients/fixtures/velojity-ejson.json`, which stratus's client-fixtures-test keeps current), and
+`scripts/test-js-client` from the repo root: the codec, then the client against the local
+service.

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "stratus-db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The stratus-db service from JavaScript: typed JSON over fetch, no dependencies.",
+  "homepage": "https://stratus-db.com",
+  "type": "module",
+  "exports": "./stratus-db.js",
+  "files": ["stratus-db.js"],
+  "engines": { "node": ">=20" }
+}

package/stratus-db.js

@@ -0,0 +1,821 @@
+// stratus-db: the stratus-db service from JavaScript (Node 20+, browsers), typed JSON over
+// fetch. No dependencies, and one file: the same file is on npm and at
+// stratus-db.com/clients/, with its sha256.
+//
+// The stratus client: typed JSON over fetch (docs/json.md), 429s retried with backoff, pages
+// followed. Every method returns a promise; failures reject with a StratusError.
+//
+//   import { connect, kw, squuid } from "stratus-db";
+//   const s = connect({ url: "https://api.stratus-db.com", apiKey: process.env.STRATUS_KEY });
+//   const { id } = await s.createDb({ name: "orders", primaryKey: "order/id" });
+//   await s.transact(id, { tx: [{ "order/id": squuid(), "order/status": kw("status/new") }] });
+//   const { rows } = await s.query(id, { where: ["=", "order/status", kw("status/new")] });
+//
+// 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 resolveMs, and again when one answers 403 or 404); for testing
+// against a local service, opts.caller names the caller (x-stratus-caller).
+
+/** The client's version: package.json's, which release-js.yml checks against it. */
+export const VERSION = "0.1.0";
+
+const USER_AGENT = `stratus-db-js/${VERSION}`;
+const IN_NODE = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
+
+// ------------------------------------------------------------------ Values
+// The value types stratus stores that JavaScript has no exact equivalent for. Each is what a
+// typed-JSON tag reads as (docs/json.md), and writes as that tag again.
+//
+// Strings stay strings: a UUID, an instant or a keyword must be one of these, or it is stored
+// as a string and matches nothing of the intended type.
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+const uuids = new Map();
+// a collected UUID's entry goes too
+const uuidCleanup = new FinalizationRegistry((t) => { if (uuids.get(t)?.deref() === undefined) uuids.delete(t); });
+
+/** A UUID. Interned: equal UUIDs are the same object, so === and Set membership work. */
+export class Uuid {
+  /** @param {string} text */
+  constructor(text) {
+    this.text = text;
+    Object.freeze(this);
+  }
+
+  /** The UUID of text (any case; written lowercase). */
+  static of(text) {
+    const t = String(text).toLowerCase();
+    if (!UUID_RE.test(t)) throw new TypeError(`Not a UUID: ${text}`);
+    let u = uuids.get(t)?.deref();
+    if (u === undefined) {
+      u = new Uuid(t);
+      uuids.set(t, new WeakRef(u));
+      uuidCleanup.register(u, t);
+    }
+    return u;
+  }
+
+  toString() { return this.text; }
+  toJSON() { return this.text; }
+}
+
+const keywords = new Map();
+
+/** A keyword (:status/sent). Interned: equal keywords are the same object. */
+export class Keyword {
+  constructor(namespace, name) {
+    this.namespace = namespace;
+    this.name = name;
+    Object.freeze(this);
+  }
+
+  /** The keyword named "ns/name" (or "name"). A leading ":" is dropped. */
+  static of(text) {
+    let t = String(text);
+    if (t.startsWith(":")) t = t.slice(1);
+    if (t === "") throw new TypeError("A keyword has a name");
+    let k = keywords.get(t);
+    if (k === undefined) {
+      const i = t.indexOf("/");
+      k = i <= 0 || t.length === 1 ? new Keyword(null, t) : new Keyword(t.slice(0, i), t.slice(i + 1));
+      keywords.set(t, k);
+    }
+    return k;
+  }
+
+  /** "ns/name", or "name". */
+  get fullName() { return this.namespace === null ? this.name : `${this.namespace}/${this.name}`; }
+  toString() { return `:${this.fullName}`; }
+}
+
+/** A symbol (rare in data; kept so values read and written round-trip). */
+export class Sym {
+  constructor(fullName) { this.fullName = String(fullName); Object.freeze(this); }
+  toString() { return this.fullName; }
+}
+
+/** A single character. */
+export class Char {
+  constructor(c) {
+    const s = String(c);
+    if ([...s].length !== 1) throw new TypeError(`A char is one character: ${c}`);
+    this.value = s;
+    Object.freeze(this);
+  }
+  toString() { return this.value; }
+}
+
+/**
+ * An exact decimal (java.math.BigDecimal), kept as its text so its scale survives: 1.10 stays
+ * "1.10". No arithmetic: convert with a decimal library of your choice.
+ */
+export class Decimal {
+  constructor(text) {
+    const t = String(text);
+    if (!/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(t)) throw new TypeError(`Not a decimal: ${text}`);
+    this.text = t;
+    Object.freeze(this);
+  }
+  toString() { return this.text; }
+  toNumber() { return Number(this.text); }
+}
+
+/** An arbitrary-size integer (java.math.BigInteger), distinct from a long. */
+export class BigInteger {
+  /** @param {bigint|string|number} v */
+  constructor(v) { this.value = BigInt(v); Object.freeze(this); }
+  toString() { return this.value.toString(); }
+}
+
+/** An exact ratio of two integers (1/3). */
+export class Ratio {
+  constructor(numerator, denominator) {
+    this.numerator = BigInt(numerator);
+    this.denominator = BigInt(denominator);
+    if (this.denominator === 0n) throw new RangeError("A ratio's denominator isn't 0");
+    Object.freeze(this);
+  }
+  toString() { return `${this.numerator}/${this.denominator}`; }
+}
+
+/**
+ * A double whose value is integral (1.0). JavaScript's numbers can't say long or double, and
+ * an integral number is written as a long; wrap it to store a double.
+ */
+export class Double {
+  constructor(v) { this.value = Number(v); Object.freeze(this); }
+  valueOf() { return this.value; }
+}
+
+/** A list (as opposed to a vector, which is an Array). */
+export class List extends Array {
+  /** A List of the items of iterable. */
+  static from(iterable) {
+    const l = new List();
+    for (const x of iterable) l.push(x);
+    return l;
+  }
+}
+
+const ISO_INSTANT = /^([+-]\d{4,}|\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$/;
+
+function pad(n, width) { return String(n).padStart(width, "0"); }
+
+function yearText(y) {
+  if (y >= 0 && y <= 9999) return pad(y, 4);
+  return (y < 0 ? "-" : "+") + pad(Math.abs(y), 4);
+}
+
+function parseYear(s) { return Number(s); }
+
+/**
+ * A point in time with nanosecond precision (java.time.Instant): epochSecond and nano.
+ * JavaScript's Date keeps milliseconds; toDate() truncates to them.
+ */
+export class Instant {
+  constructor(epochSecond, nano = 0) {
+    if (!Number.isSafeInteger(epochSecond)) throw new RangeError(`epochSecond: ${epochSecond}`);
+    if (!Number.isInteger(nano) || nano < 0 || nano > 999999999) throw new RangeError(`nano: ${nano}`);
+    this.epochSecond = epochSecond;
+    this.nano = nano;
+    Object.freeze(this);
+  }
+
+  /** The instant of a Date (millisecond precision). */
+  static fromDate(d) {
+    const ms = d.getTime();
+    if (Number.isNaN(ms)) throw new RangeError("An invalid Date");
+    const s = Math.floor(ms / 1000);
+    return new Instant(s, (ms - s * 1000) * 1000000);
+  }
+
+  /** The instant of ISO-8601 UTC text, as Java writes it ("2026-10-09T14:23:05.123456Z"). */
+  static parse(text) {
+    const m = ISO_INSTANT.exec(text);
+    if (m === null) throw new RangeError(`Not an ISO instant: ${text}`);
+    const [, y, mo, d, h, mi, s, frac] = m;
+    // Date.UTC maps years 0-99 to 1900-1999: start in a leap year, then set the real date
+    const date = new Date(Date.UTC(2000, 0, 1, Number(h), Number(mi), Number(s)));
+    date.setUTCFullYear(parseYear(y), Number(mo) - 1, Number(d));
+    if (date.getUTCMonth() !== Number(mo) - 1 || date.getUTCDate() !== Number(d))
+      throw new RangeError(`Not an ISO instant: ${text}`);
+    const sec = date.getTime() / 1000;
+    return new Instant(sec, frac === undefined ? 0 : Number(frac.padEnd(9, "0")));
+  }
+
+  /** The instant now (millisecond precision). */
+  static now() { return Instant.fromDate(new Date()); }
+
+  /** A Date (truncated to milliseconds). */
+  toDate() { return new Date(this.epochSecond * 1000 + Math.floor(this.nano / 1000000)); }
+
+  /** ISO-8601 UTC, as Java's Instant writes it: a fraction of 3, 6 or 9 digits, or none. */
+  toString() {
+    const d = new Date(this.epochSecond * 1000);
+    let frac = "";
+    if (this.nano !== 0) {
+      const n = pad(this.nano, 9);
+      frac = "." + (this.nano % 1000000 === 0 ? n.slice(0, 3) : this.nano % 1000 === 0 ? n.slice(0, 6) : n);
+    }
+    return `${yearText(d.getUTCFullYear())}-${pad(d.getUTCMonth() + 1, 2)}-${pad(d.getUTCDate(), 2)}T` +
+      `${pad(d.getUTCHours(), 2)}:${pad(d.getUTCMinutes(), 2)}:${pad(d.getUTCSeconds(), 2)}${frac}Z`;
+  }
+
+  /** Whether other is the same instant. */
+  equals(other) {
+    return other instanceof Instant && other.epochSecond === this.epochSecond && other.nano === this.nano;
+  }
+}
+
+const ISO_DATE = /^([+-]\d{4,}|\d{4})-(\d{2})-(\d{2})$/;
+
+/** A date without a time or zone (java.time.LocalDate). */
+export class LocalDate {
+  constructor(year, month, day) {
+    const d = new Date(0);
+    d.setUTCFullYear(year, month - 1, day);
+    if (d.getUTCFullYear() !== year || d.getUTCMonth() !== month - 1 || d.getUTCDate() !== day)
+      throw new RangeError(`Not a date: ${year}-${month}-${day}`);
+    this.year = year;
+    this.month = month;
+    this.day = day;
+    Object.freeze(this);
+  }
+
+  /** The date of ISO text ("2026-10-09", "+10000-01-01"). */
+  static parse(text) {
+    const m = ISO_DATE.exec(text);
+    if (m === null) throw new RangeError(`Not an ISO date: ${text}`);
+    return new LocalDate(parseYear(m[1]), Number(m[2]), Number(m[3]));
+  }
+
+  toString() { return `${yearText(this.year)}-${pad(this.month, 2)}-${pad(this.day, 2)}`; }
+
+  equals(other) {
+    return other instanceof LocalDate && other.year === this.year && other.month === this.month && other.day === this.day;
+  }
+}
+
+/** A typed-JSON tag this client doesn't know, kept as it came: { tag: "$oid", rep }. */
+export class Tagged {
+  constructor(tag, rep) { this.tag = tag; this.rep = rep; Object.freeze(this); }
+}
+
+/** Shorthands. */
+export const uuid = (text) => Uuid.of(text);
+export const kw = (text) => Keyword.of(text);
+export const decimal = (text) => new Decimal(text);
+export const instant = (x) => (x instanceof Date ? Instant.fromDate(x) : Instant.parse(x));
+export const localDate = (text) => LocalDate.parse(text);
+export const double = (v) => new Double(v);
+export const list = (...items) => List.from(items);
+
+// ------------------------------------------------------------------ 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. encode/decode work on JSON text;
+// toJSONValue/fromJSONValue on the parsed tree.
+//
+// JavaScript to stratus:
+//   string, boolean, null           themselves
+//   number                          an integer within ±2^53 is a long; anything else a double
+//                                   (NaN, the infinities, -0 and integers past 2^53 as
+//                                   $numberDouble). An integral double needs Double(1).
+//   bigint                          a long ($numberLong past ±2^53), past 64 bits $bigint
+//   Uuid Keyword Sym Char Decimal BigInteger Ratio Instant LocalDate Double List Tagged
+//                                   their tags (types.js); a Date is an Instant (ms)
+//   Uint8Array                      $binary (subtype 00)
+//   Array                           a vector; a List a list
+//   Set                             $set
+//   plain object                    a map: its keys are keywords ("resource/id"); undefined
+//                                   values are left out
+//   Map                             $map: its keys are values (a string key stays a string)
+// stratus to JavaScript: the same, backwards; a long past ±2^53 is a bigint, an unknown tag a
+// Tagged (or an error, with { strict: true }).
+
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+
+function tag(t, rep) { return { [t]: rep }; }
+
+function base64(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(s);
+}
+
+function unbase64(text) {
+  const s = atob(text);
+  const b = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) b[i] = s.charCodeAt(i);
+  return b;
+}
+
+function doubleText(n) {
+  if (Number.isNaN(n)) return "NaN";
+  if (n === Infinity) return "Infinity";
+  if (n === -Infinity) return "-Infinity";
+  if (Object.is(n, -0)) return "-0.0";
+  return String(n);
+}
+
+function isPlainObject(x) {
+  const p = Object.getPrototypeOf(x);
+  return p === Object.prototype || p === null;
+}
+
+function encodeNumber(n) {
+  if (Number.isSafeInteger(n) && !Object.is(n, -0)) return n;
+  if (Number.isFinite(n) && !Number.isInteger(n)) return n;
+  return tag("$numberDouble", doubleText(n));
+}
+
+function encodeBigInt(b) {
+  if (b >= -MAX_SAFE && b <= MAX_SAFE) return Number(b);
+  if (b >= INT64_MIN && b <= INT64_MAX) return tag("$numberLong", b.toString());
+  return tag("$bigint", b.toString());
+}
+
+/** The JSON tree of value x (JSON.stringify writes it). */
+export function toJSONValue(x) {
+  switch (typeof x) {
+    case "string":
+    case "boolean":
+      return x;
+    case "number":
+      return encodeNumber(x);
+    case "bigint":
+      return encodeBigInt(x);
+    case "undefined":
+      throw new TypeError("undefined has no typed-JSON encoding (use null)");
+    case "object":
+      break;
+    default:
+      throw new TypeError(`No typed-JSON encoding for a ${typeof x}`);
+  }
+  if (x === null) return null;
+  if (x instanceof Uuid) return tag("$uuid", x.text);
+  if (x instanceof Keyword) return tag("$kw", x.fullName);
+  if (x instanceof Instant) return tag("$inst", x.toString());
+  if (x instanceof Date) return tag("$inst", Instant.fromDate(x).toString());
+  if (x instanceof LocalDate) return tag("$localDate", x.toString());
+  if (x instanceof Decimal) return tag("$numberDecimal", x.text);
+  if (x instanceof Double) {
+    return Number.isFinite(x.value) && !Number.isInteger(x.value) ? x.value : tag("$numberDouble", doubleText(x.value));
+  }
+  if (x instanceof BigInteger) return tag("$bigint", x.value.toString());
+  if (x instanceof Ratio) return tag("$ratio", x.toString());
+  if (x instanceof Sym) return tag("$sym", x.fullName);
+  if (x instanceof Char) return tag("$char", x.value);
+  if (x instanceof Tagged) return tag(x.tag, toJSONValue(x.rep));
+  if (x instanceof Uint8Array) return tag("$binary", { base64: base64(x), subType: "00" });
+  if (x instanceof List) return tag("$list", Array.from(x, toJSONValue));
+  if (Array.isArray(x)) return x.map(toJSONValue);
+  if (x instanceof Set) return tag("$set", Array.from(x, toJSONValue));
+  if (x instanceof Map) return tag("$map", Array.from(x, ([k, v]) => [toJSONValue(k), toJSONValue(v)]));
+  if (isPlainObject(x)) {
+    const keys = Object.keys(x).filter((k) => x[k] !== undefined);
+    // a lone key starting with $ would read as a tag: such a map goes as $map
+    if (keys.length === 1 && keys[0].startsWith("$"))
+      return tag("$map", [[tag("$kw", keys[0]), toJSONValue(x[keys[0]])]]);
+    const out = {};
+    for (const k of keys) out[k] = toJSONValue(x[k]);
+    return out;
+  }
+  throw new TypeError(`No typed-JSON encoding for ${x.constructor?.name ?? "this object"}`);
+}
+
+/** x as typed-JSON text. */
+export function encode(x) {
+  return JSON.stringify(toJSONValue(x));
+}
+
+function bad(msg) { return new TypeError(msg); }
+
+function text(t, rep) {
+  if (typeof rep !== "string") throw bad(`${t} takes a string`);
+  return rep;
+}
+
+function array(t, rep) {
+  if (!Array.isArray(rep)) throw bad(`${t} takes an array`);
+  return rep;
+}
+
+function parseLong(t, s) {
+  if (!/^[+-]?\d+$/.test(s)) throw bad(`${t} isn't an integer: ${s}`);
+  const b = BigInt(s);
+  if (b < INT64_MIN || b > INT64_MAX) throw bad(`${t} isn't a 64-bit integer: ${s}`);
+  return b >= -MAX_SAFE && b <= MAX_SAFE ? Number(b) : b;
+}
+
+function parseDouble(s) {
+  switch (s) {
+    case "NaN": return NaN;
+    case "Infinity": return Infinity;
+    case "-Infinity": return -Infinity;
+    default: {
+      if (!/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(s)) throw bad(`$numberDouble isn't a number: ${s}`);
+      return Number(s);
+    }
+  }
+}
+
+function uuidOfBytes(b) {
+  if (b.length !== 16) throw bad("A $binary UUID (subtype 04) has 16 bytes");
+  const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+  return Uuid.of(`${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`);
+}
+
+function decodeTag(t, rep, opts) {
+  switch (t) {
+    case "$numberLong": return parseLong(t, text(t, rep));
+    case "$numberInt": return parseLong(t, text(t, rep));
+    case "$numberDouble": return parseDouble(text(t, rep));
+    case "$numberDecimal": return new Decimal(text(t, rep));
+    case "$bigint": {
+      const s = text(t, rep);
+      if (!/^[+-]?\d+$/.test(s)) throw bad(`$bigint isn't an integer: ${s}`);
+      return new BigInteger(s);
+    }
+    case "$ratio": {
+      const m = /^([+-]?\d+)\/(\d+)$/.exec(text(t, rep));
+      if (m === null) throw bad(`$ratio is n/d: ${rep}`);
+      return new Ratio(m[1], m[2]);
+    }
+    case "$kw": return Keyword.of(text(t, rep));
+    case "$sym": return new Sym(text(t, rep));
+    case "$char": return new Char(text(t, rep));
+    case "$uuid": return Uuid.of(text(t, rep));
+    case "$inst": return Instant.parse(text(t, rep));
+    case "$date": {
+      if (typeof rep === "string") return Instant.fromDate(new Date(rep));
+      if (rep !== null && typeof rep === "object" && typeof rep.$numberLong === "string") {
+        const ms = Number(rep.$numberLong);
+        const s = Math.floor(ms / 1000);
+        return new Instant(s, (ms - s * 1000) * 1000000);
+      }
+      throw bad("$date takes an ISO string or {$numberLong: millis}");
+    }
+    case "$localDate": return LocalDate.parse(text(t, rep));
+    case "$binary": {
+      if (rep === null || typeof rep !== "object") throw bad("$binary takes {base64, subType}");
+      const b = unbase64(text("$binary's base64", rep.base64));
+      const sub = text("$binary's subType", rep.subType);
+      return sub === "04" || sub === "4" ? uuidOfBytes(b) : b;
+    }
+    case "$set": return new Set(array(t, rep).map((x) => fromJSONValue(x, opts)));
+    case "$list": return List.from(array(t, rep).map((x) => fromJSONValue(x, opts)));
+    case "$map": {
+      const m = new Map();
+      for (const p of array(t, rep)) {
+        if (!Array.isArray(p) || p.length !== 2) throw bad("A $map entry is [k, v]");
+        m.set(fromJSONValue(p[0], opts), fromJSONValue(p[1], opts));
+      }
+      // keys all keywords (a lone $-named key, escaped): a plain object, whose keys are keywords
+      if (m.size > 0 && Array.from(m.keys()).every((k) => k instanceof Keyword)) {
+        const o = {};
+        for (const [k, v] of m) o[k.fullName] = v;
+        return o;
+      }
+      return m;
+    }
+    default:
+      if (opts?.strict) throw bad(`Unknown typed-JSON tag ${t}`);
+      return new Tagged(t, fromJSONValue(rep, opts));
+  }
+}
+
+/** The value of a parsed JSON tree. opts.strict: an unknown tag throws. */
+export function fromJSONValue(x, opts) {
+  if (Array.isArray(x)) return x.map((y) => fromJSONValue(y, opts));
+  if (x !== null && typeof x === "object") {
+    const keys = Object.keys(x);
+    if (keys.length === 1 && keys[0].startsWith("$")) return decodeTag(keys[0], x[keys[0]], opts);
+    const out = {};
+    for (const k of keys) out[k] = fromJSONValue(x[k], opts);
+    return out;
+  }
+  return x;
+}
+
+/** The value of typed-JSON text. opts.strict: an unknown tag throws. */
+export function decode(text, opts) {
+  return fromJSONValue(JSON.parse(text), opts);
+}
+
+// ------------------------------------------------------------------ The client
+
+/** A request that failed: its HTTP status, the error's kind ("invalid-query") and message. */
+export class StratusError extends Error {
+  constructor(status, error, message, body) {
+    super(`HTTP ${status}${error ? ` ${error}` : ""}: ${message ?? ""}`);
+    this.name = "StratusError";
+    this.status = status;
+    this.error = error ?? null;
+    this.body = body;
+  }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function trimSlash(u) { return u.endsWith("/") ? u.slice(0, -1) : u; }
+
+function queryString(params) {
+  const p = new URLSearchParams();
+  for (const [k, v] of Object.entries(params ?? {})) if (v !== undefined && v !== null) p.set(k, String(v));
+  const s = p.toString();
+  return s === "" ? "" : `?${s}`;
+}
+
+function attName(att) { return att instanceof Keyword ? att.fullName : String(att).replace(/^:/, ""); }
+
+/** A client of the stratus service at opts.url (see the module's comment for opts). */
+export function connect(opts) {
+  return new Client(opts);
+}
+
+export class Client {
+  /**
+   * @param {object} opts
+   * @param {string} opts.url            the service's base URL (hosted), or the catalog's URL (function-urls)
+   * @param {string} [opts.apiKey]       sent as "Authorization: Bearer <key>"
+   * @param {"hosted"|"function-urls"} [opts.addressing]
+   * @param {string} [opts.caller]       x-stratus-caller, for a local service
+   * @param {number} [opts.retries]      attempts after a 429 (default 10)
+   * @param {number} [opts.resolveMs]    function-urls: how long a database's URL is cached (5 minutes)
+   * @param {typeof fetch} [opts.fetch]  default globalThis.fetch
+   */
+  constructor(opts) {
+    if (!opts?.url) throw new TypeError("connect needs { url }");
+    this.url = trimSlash(opts.url);
+    this.addressing = opts.addressing ?? "hosted";
+    if (!["hosted", "function-urls"].includes(this.addressing)) throw new TypeError(`addressing: ${this.addressing}`);
+    this.apiKey = opts.apiKey;
+    this.caller = opts.caller;
+    this.retries = opts.retries ?? 10;
+    this.resolveMs = opts.resolveMs ?? 300000;
+    this.fetch = opts.fetch ?? globalThis.fetch;
+    this.urls = { at: 0, byId: new Map() };
+  }
+
+  // -- requests
+
+  async send(url, method, body) {
+    const headers = { accept: "application/json" };
+    // Node's fetch sends ours (so old copies can be seen); a browser sends its own
+    if (IN_NODE) headers["user-agent"] = USER_AGENT;
+    if (body !== undefined) headers["content-type"] = "application/json";
+    if (this.apiKey) headers.authorization = `Bearer ${this.apiKey}`;
+    if (this.caller) headers["x-stratus-caller"] = this.caller;
+    for (let attempt = 0; ; attempt++) {
+      const r = await this.fetch(url, { method, headers, body: body === undefined ? undefined : encode(body) });
+      const textBody = await r.text();
+      if (r.status === 429 && attempt < this.retries) {
+        // full jitter: up to 50 ms x 2^attempt, at most 5 s
+        await sleep(Math.random() * Math.min(5000, 50 * 2 ** attempt));
+        continue;
+      }
+      const ct = r.headers.get("content-type") ?? "";
+      let value = textBody;
+      if (ct.startsWith("application/json") && textBody !== "") {
+        try { value = decode(textBody); } catch { value = textBody; }
+      }
+      return { status: r.status, body: value };
+    }
+  }
+
+  static ok(r) {
+    if (r.status >= 200 && r.status < 300) return r.body;
+    const b = r.body;
+    const isObj = b !== null && typeof b === "object";
+    throw new StratusError(r.status, isObj ? b.error : null, isObj ? b.message : String(b ?? ""), b);
+  }
+
+  catalogUrl(path) {
+    return this.addressing === "hosted" ? `${this.url}/v1${path}` : `${this.url}${path}`;
+  }
+
+  /** method path body to the catalog: { status, body }. */
+  callCatalog(method, path, body) {
+    return this.send(this.catalogUrl(path), method, body);
+  }
+
+  async resolve() {
+    const recs = Client.ok(await this.callCatalog("GET", "/dbs"));
+    const byId = new Map();
+    for (const r of recs) if (r.url) byId.set(String(r.id), r.url);
+    this.urls = { at: Date.now(), byId };
+    return byId;
+  }
+
+  async dbBase(id) {
+    const key = String(id);
+    if (this.addressing === "hosted") return `${this.url}/v1/dbs/${encodeURIComponent(key)}`;
+    const { at, byId } = this.urls;
+    if (byId.has(key) && Date.now() - at < this.resolveMs) return trimSlash(byId.get(key));
+    const u = (await this.resolve()).get(key);
+    return u === undefined ? null : trimSlash(u);
+  }
+
+  /** method path body to database id: { status, body }. */
+  async callDb(id, method, path, body) {
+    const base = await this.dbBase(id);
+    if (base === null) return { status: 404, body: { error: "no-database", message: `No database ${id}` } };
+    const r = await this.send(base + path, method, body);
+    if (this.addressing === "function-urls" && (r.status === 403 || r.status === 404)) {
+      const again = (await this.resolve()).get(String(id));
+      if (again !== undefined && trimSlash(again) !== base) return this.send(trimSlash(again) + path, method, body);
+    }
+    return r;
+  }
+
+  // -- the catalog
+
+  /** The live databases' records ({ deleted: true } for deleted ones too). */
+  async listDbs(opts) {
+    return Client.ok(await this.callCatalog("GET", `/dbs${queryString({ deleted: opts?.deleted ? "true" : undefined })}`));
+  }
+
+  /** The live database named name's record. */
+  async dbByName(name) {
+    return Client.ok(await this.callCatalog("GET", `/dbs${queryString({ name })}`));
+  }
+
+  /** Database id's record. */
+  async dbRecord(id) {
+    return Client.ok(await this.callCatalog("GET", `/dbs/${encodeURIComponent(String(id))}`));
+  }
+
+  /** Creates a database: { id, url }. primaryKey is fixed for its life ("order/id"). */
+  async createDb({ name, primaryKey }) {
+    const body = { "primary-key": Keyword.of(attName(primaryKey)) };
+    if (name !== undefined) body.name = name;
+    return Client.ok(await this.callCatalog("POST", "/dbs", body));
+  }
+
+  async renameDb(id, name) {
+    return Client.ok(await this.callCatalog("PATCH", `/dbs/${encodeURIComponent(String(id))}`, { name }));
+  }
+
+  async deleteDb(id) {
+    return Client.ok(await this.callCatalog("DELETE", `/dbs/${encodeURIComponent(String(id))}`));
+  }
+
+  // -- keys (hosted: an account's keys, managed with a key whose scope is every database)
+
+  /** The account's keys' records (no secrets). */
+  async listKeys() {
+    return Client.ok(await this.callCatalog("GET", "/keys"));
+  }
+
+  /** A new key: { key (shown once), record }. scope: database ids it may reach (default all). */
+  async createKey({ name, scope } = {}) {
+    const body = {};
+    if (name !== undefined) body.name = name;
+    if (scope !== undefined) body.scope = scope.map(String);
+    return Client.ok(await this.callCatalog("POST", "/keys", body));
+  }
+
+  /** Revokes key keyId: its record. */
+  async revokeKey(keyId) {
+    return Client.ok(await this.callCatalog("DELETE", `/keys/${encodeURIComponent(keyId)}`));
+  }
+
+  // -- a database
+
+  /** The database's state: { id, "primary-key", t, "checkpoint-t", indexes, "index-errors", status }. */
+  async status(id) {
+    return Client.ok(await this.callDb(id, "GET", this.addressing === "hosted" ? "/status" : "/"));
+  }
+
+  /**
+   * Transacts: { t, pks, duplicate? }. tx: rows (each with its primary key: squuid()),
+   * retract: rows of attributes to remove, delete: primary keys, txId: makes a retry safe,
+   * match: rows whose attributes must hold those values now (else a 409 "conflict").
+   */
+  async transact(id, { tx, retract, delete: del, txId, match }) {
+    const body = {};
+    if (tx !== undefined) body.tx = tx;
+    if (retract !== undefined) body.retract = retract;
+    if (del !== undefined) body.delete = del;
+    if (txId !== undefined) body["tx-id"] = txId;
+    if (match !== undefined) body.match = match;
+    return Client.ok(await this.callDb(id, "POST", "/transact", body));
+  }
+
+  /** One page of query q (docs/query.md, "JSON"): { rows, next, t }. */
+  async query(id, q = {}) {
+    return Client.ok(await this.callDb(id, "POST", "/query", q));
+  }
+
+  /** Every row of query q, page after page. */
+  async *queryAll(id, q = {}) {
+    let after = q.after;
+    for (;;) {
+      const page = await this.query(id, after === undefined ? q : { ...q, after });
+      yield* page.rows;
+      if (page.next === null || page.next === undefined) return;
+      after = page.next;
+    }
+  }
+
+  /** The rows of primary keys pks, in order (null where there is none). */
+  async pull(id, pks) {
+    return (Client.ok(await this.callDb(id, "POST", "/pull", { pks }))).rows;
+  }
+
+  /** Requests a value index on att: { att, state } ("building" until a checkpoint builds it). */
+  async requestIndex(id, att) {
+    return Client.ok(await this.callDb(id, "POST", "/indexes", { att: attName(att) }));
+  }
+
+  async dropIndex(id, att) {
+    return Client.ok(await this.callDb(id, "DELETE", `/indexes/${attName(att).split("/").map(encodeURIComponent).join("/")}`));
+  }
+
+  /** Waits until att's index is ready (rejects if it failed, or after timeoutMs). */
+  async awaitIndex(id, att, { timeoutMs = 60000, intervalMs = 200 } = {}) {
+    const name = attName(att);
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const s = await this.status(id);
+      const state = s.indexes?.[name];
+      if (state === "ready") return s;
+      if (state === "failed") throw new StratusError(409, "index-failed", s["index-errors"]?.[name] ?? `${name} failed`, s);
+      if (Date.now() > deadline) throw new StratusError(408, "timeout", `${name} isn't ready (${state})`, s);
+      await sleep(intervalMs);
+    }
+  }
+
+  /**
+   * 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 }, ... }).
+   */
+  async fork(id, { t, name } = {}) {
+    const body = {};
+    if (t !== undefined) body.t = t;
+    if (name !== undefined) body.name = name;
+    return Client.ok(await this.callDb(id, "POST", "/fork", body));
+  }
+
+  /**
+   * Excises rows (primary keys) and attributes ({ pk, att }) - erasure: gone from the current
+   * state, its indexes and history (and, hosted, the database's forks): { t, rows, attributes }.
+   */
+  async excise(id, { rows, attributes } = {}) {
+    const body = {};
+    if (rows !== undefined) body.rows = rows;
+    if (attributes !== undefined) body.attributes = attributes.map(({ pk, att }) => ({ pk, att: attName(att) }));
+    return Client.ok(await this.callDb(id, "POST", "/excise", body));
+  }
+
+  /** One page of the database's history from t: { entries, next }. */
+  async history(id, { from = 1, limit } = {}) {
+    return Client.ok(await this.callDb(id, "GET", `/history${queryString({ from, limit })}`));
+  }
+
+  /** Every history entry from t on, page after page. */
+  async *historyAll(id, { from = 1, limit } = {}) {
+    let t = from;
+    for (;;) {
+      const page = await this.history(id, { from: t, limit });
+      yield* page.entries;
+      if (page.next === null || page.next === undefined) 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.
+
+let squuidMs = 0;
+let squuidSeq = 0;
+
+const hex = (n, width) => n.toString(16).padStart(width, "0");
+
+/** A sequential UUID. */
+export function squuid() {
+  const now = Date.now();
+  if (now > squuidMs) {
+    squuidMs = now;
+    squuidSeq = 0;
+  } else if (squuidSeq < 0xfff) {
+    squuidSeq += 1;
+  } else {
+    squuidMs += 1;
+    squuidSeq = 0;
+  }
+  const r = new Uint8Array(8);
+  globalThis.crypto.getRandomValues(r);
+  r[0] = 0x80 | (r[0] & 0x3f);
+  const rh = Array.from(r, (b) => hex(b, 2)).join("");
+  const mh = hex(squuidMs, 12);
+  return Uuid.of(`${mh.slice(0, 8)}-${mh.slice(8, 12)}-7${hex(squuidSeq, 3)}-${rh.slice(0, 4)}-${rh.slice(4, 16)}`);
+}