@hraness/oh 0.2.3

package/spec/v1/storage.md

@@ -0,0 +1,88 @@
+# SQLite storage V1
+
+SQLite schema version `2` is the local authority for an Oh space. The default
+CLI database is `.oh/oh.sqlite`; callers may select another path or use an
+in-memory database.
+
+## Connection policy
+
+The Bun SQLite driver opens in strict mode and applies:
+
+```sql
+PRAGMA foreign_keys = ON;
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = NORMAL;
+PRAGMA busy_timeout = 5000;
+PRAGMA trusted_schema = OFF;
+```
+
+Each migration and committed operation runs inside `BEGIN IMMEDIATE`. Failure
+rolls back the transaction and preserves the original error.
+
+## Tables
+
+| Table | Role |
+| --- | --- |
+| `oh_migrations` | Applied migration version, immutable name, SQL digest, and timestamp. |
+| `oh_contracts` | Exact contract manifest and digest accepted by the store. |
+| `oh_spaces` | Current compare-and-swap head for each logical space. |
+| `oh_operations` | Append-only canonical operation chain. |
+| `oh_operation_records` | Ordered record changes for each operation. |
+| `oh_records` | Current canonical record materialization. |
+| `oh_dependencies` | Current explicit dependency edges. |
+| `oh_sync_outbox` | Local operations eligible for sync. |
+| `oh_sync_state` | Last settled state for a named remote. |
+| `oh_search_documents` | Derived keyword text bound to a record digest. |
+| `oh_search_fts` | Derived FTS5 index. |
+| `oh_space_bindings` | Host-selected realm, lifecycle profile, capabilities, and application-profile digest for a supported store port. |
+| `oh_space_purges` | Minimal receipt that permanently reserves the identifier of a purged working space. |
+
+The first migration is named `0001_oh_core`; its released bytes remain
+unchanged. Schema version 2 adds `0002_store_realms`. An implementation MUST
+store and check the exact SHA-256 digest of applied migration SQL. It MUST
+refuse to run when the same migration version or name has different bytes.
+
+## Realm profiles and purge
+
+A promise-based store port MAY bind one space to one host-selected realm and
+profile. The binding includes the exact Oh contract digest, an optional
+application-profile digest, and declared capabilities. A supported runtime
+MUST reject a later attempt to open the same space under different binding
+bytes. A working profile disables operation replication and enables only
+host-controlled whole-space purge. A canonical profile cannot be purged by
+that API.
+
+Purge deletes the space head, complete operation history, current records,
+dependency and operation materializations, sync state, and derived keyword
+rows in one immediate transaction. It leaves only a content-free receipt with
+the prior head, binding digest, purge instant, and receipt digest. The purged
+space identifier cannot be reopened in the same database. A host that deletes
+an entire database file MUST retain any required deletion evidence in its own
+control plane.
+
+Realm and profile binding is additive store control metadata. V1 operation
+digest preimages do not contain the binding. It therefore protects supported
+opens and operations but is not a portable cryptographic claim about a V1
+history. Such a claim requires a new wire contract rather than a change to V1
+operation bytes.
+
+## Authority and derivation
+
+`oh_operations`, `oh_spaces`, and the canonical current records define state.
+The dependency and operation-record tables are checked materializations. Search
+documents, FTS rows, and the separate QMD cache are derived and rebuildable.
+
+Deleting an embedding or FTS index MUST NOT delete authored records or
+operations. A search result MUST be rejoined to a current record and digest
+before it is returned as current.
+
+## Replay verification
+
+`oh verify` runs SQLite `integrity_check`, parses every canonical operation,
+replays the operation chain from an empty graph, recomputes record-set and graph
+revision digests, checks dependencies, compares the materialized records, and
+requires the reconstructed head to equal the stored head.
+
+Backup and restore procedures SHOULD preserve the database and WAL atomically.
+An application SHOULD run replay verification after an untrusted transfer or
+restore before treating the space as authoritative.

package/spec/v1/store.md

@@ -0,0 +1,131 @@
+# Store ports, profiles, and direct libSQL authority
+
+The graph and operation contract remains V1. This document defines additive
+host APIs that preserve those bytes across local SQLite and direct libSQL
+authorities.
+
+## Promise-based store port
+
+`@hraness/oh/store` has no dependency on `bun:sqlite`. Its methods return
+promises and expose:
+
+- the current exact head;
+- a current or historical snapshot at an exact sequence and operation digest;
+- a bounded contiguous change page through a pinned head;
+- compare-and-swap commit;
+- dependency-closure export;
+- replay and materialization verification; and
+- close.
+
+A historical read MUST fail if its sequence is absent or identifies a
+different operation digest. A change page MUST name its source cursor, pinned
+through-head, returned cursor, and whether more operations remain.
+
+## Semantic bundle ingress
+
+Model-facing code SHOULD use `OhSemanticBundleIngressV1` instead of generic
+record puts. The ingress seals its codec registry, requires a registered codec
+for every put kind, parses all values, creates canonical record envelopes, and
+submits all puts and tombstones as one compare-and-swap operation. Missing
+codecs, invalid values, duplicate keys, stale heads, and incomplete dependency
+closures fail before the authority head moves.
+
+## Profiles and host control
+
+A binding combines one exact contract, application profile, lifecycle profile,
+realm, and space. The built-in canonical profile permits operation replication
+and forbids whole-space purge. The built-in working profile forbids operation
+replication and permits purge.
+
+Creating an authority returns separate `store` and `host` objects. The ordinary
+store never has a purge method. Trusted control-plane code retains the host
+object and does not pass it to an agent tool or model. This is an API and
+custody boundary, not protection from code that already holds raw database
+credentials or direct filesystem access.
+
+## Dependency-closure capsules
+
+A closure export pins the source binding and exact head, sorts unique roots,
+and includes exactly the records reachable through declared dependencies. The
+capsule digest binds all of those fields. Verification rejects a missing
+dependency, an extra unrelated record, a changed record digest, reordered
+roots or records, and a false capsule digest. V1 bounds a capsule to 1,024
+roots, 8,192 records, and 67,108,864 canonical UTF-8 bytes.
+
+A closure is content evidence for a later reviewed adoption. It does not copy
+source authority, review state, credentials, or operation history into a
+destination.
+
+## Direct libSQL authority
+
+`@hraness/oh/libsql` accepts the `execute` and transactional `batch` shape of
+`@libsql/client`. It is Node 24 and serverless compatible and does not import
+`bun:sqlite`. Unlike the V1 sync transport, it treats libSQL as the current
+record and operation authority.
+
+`bootstrapOhLibSqlAuthorityV1` is the only API that creates schema objects.
+Run it in a deployment or migration step with a short-lived schema credential.
+`createOhLibSqlStoreAuthorityV1` is the runtime open: it only verifies the
+installed schema and contract before reading or creating a bound data space,
+so a runtime token does not need schema-change permission.
+
+`openExistingOhLibSqlStoreAuthorityV1` is the least-privilege open for a
+separately held reader or purge worker. It verifies the same exact schema,
+contract, space head, and binding using reads only. It rejects a missing,
+purged, or differently bound space and never inserts, updates, or deletes data
+during open. A provider credential can therefore omit space and binding
+creation while retaining only the data actions required by its later task.
+
+`purgeOhLibSqlWorkingSpaceV1` is the one-shot lifecycle-worker boundary. It
+purges an existing exact working binding or atomically writes an empty-head
+purge receipt when creation never completed. Creation and absent-space fencing
+race in the same authority transaction: whichever wins, the result converges
+to one complete purge receipt, and a delayed creator cannot resurrect the
+space. The credential still needs no permission to create spaces or bindings.
+
+Runtime open verifies the exact installed table, index, and trigger set, not
+only a schema marker. Every operation, binding, and purge receipt read parses
+its canonical JSON and cross-checks each duplicated SQL column. Current reads
+also prove contiguous operation coverage through the exact terminal head,
+record provenance puts, record digests, and dependency materialization.
+
+Its private implementation tables use the `oh_authority_` prefix:
+
+| Table | Role |
+| --- | --- |
+| `oh_authority_schemas` | Exact adapter schema name and digest. |
+| `oh_authority_contracts` | Exact Oh contract manifest. |
+| `oh_authority_spaces` | Current compare-and-swap heads. |
+| `oh_authority_operations` | Canonical append-only operations. |
+| `oh_authority_operation_records` | Ordered changes per operation. |
+| `oh_authority_records` | Current record materialization. |
+| `oh_authority_dependencies` | Current dependency edges. |
+| `oh_authority_bindings` | Realm and profile control metadata. |
+| `oh_authority_purges` | Minimal whole-space purge receipts. |
+| `oh_authority_commit_guards` | Empty constraint table used to abort a stale transactional batch. |
+
+A normal remote commit takes three atomic provider round trips: an idempotency,
+head, and purge preflight; one exact current-materialization read; and one
+guarded write batch. The final write guard aborts the complete transaction when
+compare-and-swap did not settle at the declared operation. Its write-batch
+readback must reproduce both the canonical operation and persisted head before
+the adapter returns success.
+
+Provider responses are bounded as part of the API. V1 accepts at most 64
+changes, 512 dependencies, and 512 KiB of canonical operation JSON per commit.
+A feed returns at most seven operations plus one checked sentinel and refuses a
+page whose conservative transport estimate exceeds 9,000,000 bytes. Historical
+replay is limited to 16,384 operations, 4 MiB of canonical operation JSON, and
+the same response estimate. Current snapshot and full-verification result sets
+are independently transport-estimated and SQL-gated before rows are returned.
+Sizing, rows, and the pinned head are read in the same transaction, so a
+concurrent append cannot grow an unchecked response between preflight and read.
+
+Remote purge similarly inserts a receipt only for the expected working head,
+deletes every payload and materialization row under that receipt in the same
+write batch, and aborts if either the receipt or deletion is incomplete. A
+later open returns the stored purge receipt instead of recreating the space.
+Operation-record deletion resolves ownership through the canonical operation;
+the purge postcondition also rejects any global orphan or cross-space owner
+mismatch. Purge receipts are immutable and intentionally retain only binding,
+prior-head, and purge-event evidence.

package/spec/v1/sync-bundle.schema.json

@@ -0,0 +1,51 @@
+{
+  "$defs": {
+    "safeCode": {
+      "maxLength": 128,
+      "pattern": "^[a-z][a-z0-9]*(?:[._:/-][a-z0-9]+)*$",
+      "type": "string"
+    },
+    "sha256": {
+      "pattern": "^[a-f0-9]{64}$",
+      "type": "string"
+    }
+  },
+  "$id": "https://oh.computer/spec/v1/sync-bundle.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Runtime conformance additionally requires one contiguous operation chain for the selected space and a recomputed bundleSha256.",
+  "additionalProperties": false,
+  "properties": {
+    "bundleSha256": {
+      "$ref": "#/$defs/sha256"
+    },
+    "contractSha256": {
+      "const": "e53ae573c2af417082be9f554d0f6f3e317f054daf745181f462608e3f622594"
+    },
+    "operations": {
+      "items": {
+        "$ref": "./operation.schema.json"
+      },
+      "maxItems": 1000,
+      "type": "array"
+    },
+    "protocol": {
+      "const": "oh.sync.v1"
+    },
+    "spaceId": {
+      "$ref": "#/$defs/safeCode"
+    },
+    "v": {
+      "const": 1
+    }
+  },
+  "required": [
+    "bundleSha256",
+    "contractSha256",
+    "operations",
+    "protocol",
+    "spaceId",
+    "v"
+  ],
+  "title": "Oh sync bundle V1",
+  "type": "object"
+}

package/spec/v1/sync.md

@@ -0,0 +1,67 @@
+# Operation sync V1
+
+The protocol identifier is `oh.sync.v1`. Sync exchanges canonical operations,
+not current-row snapshots or semantic indexes.
+
+## Handshake
+
+Before reading or writing a remote, a transport MUST compare the complete V1
+contract manifest. The current contract digest is
+`e53ae573c2af417082be9f554d0f6f3e317f054daf745181f462608e3f622594`.
+A different digest fails before operation exchange.
+
+A transport implements four bounded methods:
+
+```ts
+interface OhOperationSyncTransportV1 {
+  handshake(manifest: OhContractManifestV1): Promise<void>;
+  head(spaceId: string): Promise<OhSyncHeadV1>;
+  pull(spaceId: string, afterSequence: number, limit: number): Promise<OhSyncBundleV1>;
+  push(bundle: OhSyncBundleV1): Promise<OhSyncHeadV1>;
+}
+```
+
+## Bundle
+
+A bundle binds `oh.sync.v1`, the contract digest, one space ID, at most 1,000
+ordered operations, and its own digest. Operations MUST form one contiguous
+chain. An empty bundle is valid.
+
+Parsing recomputes every operation digest and the bundle digest. Import also
+requires the bundle space to equal the selected local space and each operation
+to extend the exact local head.
+
+## Settlement
+
+The synchronizer defaults to batches of 100 and at most 100 rounds. Each round
+compares heads:
+
+- Equal sequences and equal digests are settled.
+- A lower local sequence pulls a chain that begins at the exact local head.
+- A higher local sequence pushes a chain that begins at the exact remote head.
+- Equal sequences with different digests, or any non-extending chain, are a
+  conflict.
+
+The synchronizer never performs last-write-wins merging. Divergent append-only
+histories remain intact for an explicit domain merge. Remote acknowledgments
+must equal the final pushed operation.
+
+## libSQL and Turso seam
+
+The included adapter accepts a client with `execute` and transactional `batch`
+methods compatible with `@libsql/client`. It creates only:
+
+- `oh_sync_contracts`, containing exact contract manifests; and
+- `oh_sync_operations`, containing the ordered canonical operation log.
+
+The application supplies the client, credentials, endpoint, access policy,
+retry policy, and backups. The adapter parameterizes values and verifies
+canonical operation JSON on pull. Semantic documents and vectors never cross
+this seam.
+
+## Offline transfer
+
+`oh sync export --after <sequence> --limit <count>` emits one canonical bundle.
+`oh sync import --file <path>` verifies and applies a bundle idempotently. A
+transfer process SHOULD preserve the exact bytes and SHOULD run `oh verify`
+after the final import.

package/src/canonical.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+
+import { canonicalJson, canonicalSha256, parseCanonicalJson, sha256Hex } from "./canonical";
+
+describe("canonical JSON", () => {
+  test("sorts object keys recursively and hashes exact bytes", () => {
+    const left = { z: [{ b: 2, a: 1 }], a: "é" };
+    const right = { a: "é", z: [{ a: 1, b: 2 }] };
+    expect(canonicalJson(left)).toBe('{"a":"é","z":[{"a":1,"b":2}]}');
+    expect(canonicalJson(right)).toBe(canonicalJson(left));
+    expect(canonicalSha256(right)).toBe(canonicalSha256(left));
+    expect(canonicalSha256(left)).toBe(sha256Hex(canonicalJson(left)));
+  });
+
+  test("rejects ambiguous and non-JSON values", () => {
+    expect(() => canonicalJson(-0)).toThrow("negative zero");
+    expect(() => canonicalJson(Number.NaN)).toThrow("finite");
+    expect(() => canonicalJson({ value: undefined })).toThrow("cannot encode");
+    expect(() => canonicalJson("\ud800")).toThrow("unpaired surrogate");
+    const cyclic: { self?: unknown } = {};
+    cyclic.self = cyclic;
+    expect(() => canonicalJson(cyclic)).toThrow("cycle");
+    expect(() => canonicalJson(Array(1))).toThrow("holes");
+    const symbolObject = { value: 1, [Symbol("hidden")]: 2 };
+    expect(() => canonicalJson(symbolObject)).toThrow("symbol property");
+    const accessor = Object.defineProperty({}, "value", { enumerable: true, get: () => 1 });
+    expect(() => canonicalJson(accessor)).toThrow("data property");
+  });
+
+  test("accepts only byte-canonical JSON", () => {
+    expect(parseCanonicalJson('{"a":1,"b":2}')).toEqual({ a: 1, b: 2 });
+    expect(() => parseCanonicalJson('{ "a": 1 }')).toThrow("not canonical");
+    expect(() => parseCanonicalJson('{"b":2,"a":1}')).toThrow("not canonical");
+  });
+
+  test("is invariant to insertion order across generated objects", () => {
+    for (let seed = 1; seed <= 250; seed += 1) {
+      const keys = Array.from({ length: 12 }, (_, index) => `k${(seed * 17 + index * 31) % 97}`);
+      const first: Record<string, number> = {};
+      const second: Record<string, number> = {};
+      keys.forEach((key, index) => { first[key] = index; });
+      [...keys].reverse().forEach((key) => { second[key] = first[key] as number; });
+      expect(canonicalJson(first)).toBe(canonicalJson(second));
+    }
+  });
+});

package/src/canonical.ts

@@ -0,0 +1,203 @@
+import { createHash, randomBytes } from "node:crypto";
+
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | JsonObject;
+export type JsonObject = Readonly<{ [key: string]: JsonValue }>;
+
+declare const sha256HexBrand: unique symbol;
+export type Sha256Hex = string & { readonly [sha256HexBrand]: "Sha256Hex" };
+
+export class OhValidationError extends Error {
+  readonly code: string;
+  readonly path: string;
+
+  constructor(code: string, path: string, message: string) {
+    super(`${path}: ${message}`);
+    this.name = "OhValidationError";
+    this.code = code;
+    this.path = path;
+  }
+}
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const actual = Object.keys(value);
+  return actual.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function assertUnicodeScalarString(value: string, path: string): void {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) {
+        throw new OhValidationError("invalid-unicode", path, "contains an unpaired surrogate");
+      }
+      index += 1;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      throw new OhValidationError("invalid-unicode", path, "contains an unpaired surrogate");
+    }
+  }
+}
+
+function encodeCanonical(value: unknown, path: string, ancestors: Set<object>): string {
+  if (value === null || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "string") {
+    assertUnicodeScalarString(value, path);
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new OhValidationError("non-json-number", path, "must be finite");
+    }
+    if (Object.is(value, -0)) {
+      throw new OhValidationError("noncanonical-number", path, "negative zero is not canonical");
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value !== "object" || value === null) {
+    throw new OhValidationError("non-json-value", path, `cannot encode ${typeof value}`);
+  }
+  if (ancestors.has(value)) {
+    throw new OhValidationError("cycle", path, "contains a cycle");
+  }
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const encoded: string[] = [];
+      for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index)) {
+          throw new OhValidationError("sparse-array", `${path}[${index}]`, "must not contain holes");
+        }
+        encoded.push(encodeCanonical(value[index], `${path}[${index}]`, ancestors));
+      }
+      const extraKeys = Reflect.ownKeys(value).filter((key) => key !== "length"
+        && (typeof key !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(key) || Number(key) >= value.length));
+      if (extraKeys.length > 0) {
+        throw new OhValidationError("non-json-property", path, "array has non-index properties");
+      }
+      return `[${encoded.join(",")}]`;
+    }
+    if (!isPlainRecord(value)) {
+      throw new OhValidationError("non-plain-object", path, "must be a plain object");
+    }
+    const ownKeys = Reflect.ownKeys(value);
+    if (ownKeys.some((key) => typeof key !== "string")) {
+      throw new OhValidationError("non-json-property", path, "object has a symbol property");
+    }
+    const keys = ownKeys as string[];
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor === undefined || !descriptor.enumerable || descriptor.get !== undefined || descriptor.set !== undefined) {
+        throw new OhValidationError("non-json-property", `${path}.${key}`, "must be an enumerable data property");
+      }
+    }
+    keys.sort();
+    const entries = keys.map((key) => {
+      assertUnicodeScalarString(key, `${path}.<key>`);
+      return `${JSON.stringify(key)}:${encodeCanonical(value[key], `${path}.${key}`, ancestors)}`;
+    });
+    return `{${entries.join(",")}}`;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+/** RFC 8785-style canonical JSON for the JSON subset accepted by Oh. */
+export function canonicalJson(value: unknown): string {
+  return encodeCanonical(value, "$", new Set());
+}
+
+export function parseCanonicalJson(text: string, maximumBytes = 16 * 1024 * 1024): JsonValue {
+  if (utf8ByteLength(text) > maximumBytes) {
+    throw new OhValidationError("limit-exceeded", "$", "canonical JSON exceeds its byte limit");
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new OhValidationError("invalid-json", "$", "is not valid JSON");
+  }
+  if (canonicalJson(value) !== text) {
+    throw new OhValidationError("noncanonical-json", "$", "keys or values are not canonical");
+  }
+  return value as JsonValue;
+}
+
+export function utf8ByteLength(value: string): number {
+  return Buffer.byteLength(value, "utf8");
+}
+
+export function sha256Hex(value: string | Uint8Array): Sha256Hex {
+  return createHash("sha256").update(value).digest("hex") as Sha256Hex;
+}
+
+export function canonicalSha256(value: unknown): Sha256Hex {
+  return sha256Hex(canonicalJson(value));
+}
+
+export function parseSha256Hex(value: unknown): Sha256Hex | null {
+  return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value)
+    ? value as Sha256Hex
+    : null;
+}
+
+export function parseCanonicalInstantV1(value: unknown): string | null {
+  if (typeof value !== "string"
+    || !/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d\.\d{3}Z$/u.test(value)) {
+    return null;
+  }
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value ? value : null;
+}
+
+export function canonicalNow(): string {
+  return new Date().toISOString();
+}
+
+export function opaqueId(prefix: string): string {
+  if (!/^[a-z][a-z0-9_]{1,15}$/u.test(prefix)) {
+    throw new OhValidationError("invalid-prefix", "prefix", "must be a short lowercase code");
+  }
+  return `${prefix}${randomBytes(12).toString("hex")}`;
+}
+
+export function safeCode(value: unknown, maximumLength = 128): string | null {
+  return typeof value === "string" && value.length <= maximumLength
+      && /^[a-z][a-z0-9]*(?:[._:/-][a-z0-9]+)*$/u.test(value)
+    ? value
+    : null;
+}
+
+export function boundedText(value: unknown, maximumBytes = 64 * 1024): string | null {
+  if (typeof value !== "string" || value.length === 0 || value.normalize("NFC") !== value
+    || utf8ByteLength(value) > maximumBytes) return null;
+  try { assertUnicodeScalarString(value, "$text"); } catch { return null; }
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code <= 8 || (code >= 11 && code <= 12) || (code >= 14 && code <= 31)
+      || (code >= 127 && code <= 159)) return null;
+  }
+  return value;
+}
+
+export function orderedUnique<T>(values: readonly T[], key: (value: T) => string): boolean {
+  return values.every((value, index) => index === 0 || key(values[index - 1] as T) < key(value));
+}
+
+export function sortUnique<T>(values: readonly T[], key: (value: T) => string): readonly T[] {
+  const sorted = [...values].sort((left, right) => {
+    const leftKey = key(left);
+    const rightKey = key(right);
+    return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+  });
+  if (!orderedUnique(sorted, key)) {
+    throw new OhValidationError("duplicate", "$", "contains duplicate canonical values");
+  }
+  return sorted;
+}