stratus-db 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1 +1,77 @@
-# stratus-db (placeholder)
+# stratus-db
+
+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, {asOf})` (and `asOf: t` in a query: the database as it stood after t), `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),
+  `setHistoryRetention(id, days)` (history kept 30 to 36500 days, or `null` for forever).
+- 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 +1,11 @@
-{"name":"stratus-db","version":"0.0.1","description":"Placeholder: the stratus-db client is published from 0.1.0."}
+{
+  "name": "stratus-db",
+  "version": "0.2.0",
+  "description": "The stratus-db service from JavaScript: typed JSON over fetch, no dependencies.",
+  "homepage": "https://stratus-db.com",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": "./stratus-db.js",
+  "files": ["stratus-db.js"],
+  "engines": { "node": ">=20" }
+}

package/stratus-db.js

@@ -0,0 +1,834 @@
+// 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.2.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 = {}) {
+    const { asOf, ...rest } = q;
+    return Client.ok(await this.callDb(id, "POST", "/query", asOf === undefined ? rest : { ...rest, "as-of": asOf }));
+  }
+
+  /** 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); { asOf: t } reads them as
+   * they stood after transaction t.
+   */
+  async pull(id, pks, { asOf } = {}) {
+    return (Client.ok(await this.callDb(id, "POST", "/pull", asOf === undefined ? { pks } : { pks, "as-of": asOf }))).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));
+  }
+
+  /**
+   * Sets how long database id keeps its history: days (whole days, 30 to 36500), or null to keep
+   * it forever. History past the window is dropped at the database's next checkpoints:
+   * { days, t }.
+   */
+  async setHistoryRetention(id, days) {
+    return Client.ok(await this.callDb(id, "PUT", "/history-retention", { days: days ?? null }));
+  }
+
+  /** 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)}`);
+}