@terrascale/sdk 0.0.2 → 0.0.3

package/src/database-codec.js

@@ -1,3 +1,5 @@
+import { requireId as requireDatabaseId } from "./ids.js";
+export { requireId as requireDatabaseId } from "./ids.js";
 /**
  * @import {
  *   DatabaseAuthority, DatabaseCommit, DatabaseCommitReceipt, DatabaseCondition, DatabaseEvent,
@@ -20,18 +22,6 @@ const maximumBodyBytes = 4 * 1024 * 1024;
 const maximumValueBytes = 1024 * 1024;
 const scalarTypes = new Set(["bool", "i64", "utf8", "bytes"]);
 
-/**
- * @param {unknown} value
- * @param {string} [name]
- * @returns {string}
- */
-export function requireDatabaseUuid(value, name = "UUID") {
-  if (typeof value !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(value)) {
-    throw new TypeError(`${name} must be a canonical lowercase UUID.`);
-  }
-  return value;
-}
-
 /**
  * @param {unknown} value
  * @param {string} [name]
@@ -295,7 +285,7 @@ function observedToWire(entries) {
   let previous = "";
   return array(entries).map(raw => {
     const entry = object(raw, ["replica", "incarnation", "sequence"]);
-    const replica = requireDatabaseUuid(entry.replica, "replica");
+    const replica = requireDatabaseId(entry.replica, "replica");
     const incarnation = hex(entry.incarnation, 16, "incarnation");
     const order = replica + incarnation;
     if (order <= previous) throw new TypeError("Observed origins must be strictly increasing.");
@@ -311,7 +301,7 @@ function observedToWire(entries) {
 function observedFromWire(raw) {
   const entries = array(raw).map(value => {
     const entry = object(value, ["replica", "incarnation", "sequence"]);
-    return { replica: requireDatabaseUuid(entry.replica, "replica"), incarnation: hex(entry.incarnation, 16, "incarnation"), sequence: decimal(entry.sequence, "sequence", true) };
+    return { replica: requireDatabaseId(entry.replica, "replica"), incarnation: hex(entry.incarnation, 16, "incarnation"), sequence: decimal(entry.sequence, "sequence", true) };
   });
   observedToWire(entries);
   return entries;
@@ -324,8 +314,8 @@ function observedFromWire(raw) {
 function eventFromWire(raw) {
   const entry = object(raw, ["database", "shard", "replica", "incarnation", "sequence"]);
   return {
-    database: requireDatabaseUuid(entry.database, "database"), shard: decimal(entry.shard, "shard"),
-    replica: requireDatabaseUuid(entry.replica, "replica"), incarnation: hex(entry.incarnation, 16, "incarnation"),
+    database: requireDatabaseId(entry.database, "database"), shard: decimal(entry.shard, "shard"),
+    replica: requireDatabaseId(entry.replica, "replica"), incarnation: hex(entry.incarnation, 16, "incarnation"),
     sequence: decimal(entry.sequence, "sequence", true),
   };
 }
@@ -430,7 +420,7 @@ function rowsFromWire(raw) {
   let previous = "";
   return array(raw, 128).map(rawRow => {
     const entry = object(rawRow, ["document", "point"]);
-    const document = requireDatabaseUuid(entry.document, "document");
+    const document = requireDatabaseId(entry.document, "document");
     if (document <= previous) throw new TypeError("Query documents must be strictly increasing.");
     previous = document;
     return { document, point: decodeDatabasePoint(entry.point) };
@@ -486,7 +476,7 @@ export function decodeDatabaseSubscription(raw) {
     previous = sequence;
     return { sequence, effects: array(group.effects, 128).map(rawEffect => {
       const effect = object(rawEffect, ["document", "point"]);
-      return { document: requireDatabaseUuid(effect.document, "document"), point: effect.point === null ? null : decodeDatabasePoint(effect.point) };
+      return { document: requireDatabaseId(effect.document, "document"), point: effect.point === null ? null : decodeDatabasePoint(effect.point) };
     }) };
   });
   return { version: 1, phase: "poll", groups, poll_cursor: cursor(entry.poll_cursor) };
@@ -501,7 +491,7 @@ export function encodeDatabaseAuthority(authority) {
   object(authority, ["mode", "generation", "writer"]);
   if (authority.mode !== "single_writer") throw new TypeError("Unsupported authority mode.");
   const writer = object(authority.writer, ["replica", "incarnation"]);
-  return { mode: "single_writer", generation: requireDatabaseU64(authority.generation, "authority generation", true).toString(), writer: { replica: requireDatabaseUuid(writer.replica, "writer"), incarnation: hex(writer.incarnation, 16, "incarnation") } };
+  return { mode: "single_writer", generation: requireDatabaseU64(authority.generation, "authority generation", true).toString(), writer: { replica: requireDatabaseId(writer.replica, "writer"), incarnation: hex(writer.incarnation, 16, "incarnation") } };
 }
 
 /**
@@ -514,7 +504,7 @@ export function decodeDatabaseAuthority(raw) {
   const entry = object(raw, ["mode", "generation", "writer"]);
   if (entry.mode !== "single_writer") throw new TypeError("Unsupported authority mode.");
   const writer = object(entry.writer, ["replica", "incarnation"]);
-  return { mode: "single_writer", generation: decimal(entry.generation, "authority generation", true), writer: { replica: requireDatabaseUuid(writer.replica, "writer"), incarnation: hex(writer.incarnation, 16, "incarnation") } };
+  return { mode: "single_writer", generation: decimal(entry.generation, "authority generation", true), writer: { replica: requireDatabaseId(writer.replica, "writer"), incarnation: hex(writer.incarnation, 16, "incarnation") } };
 }
 
 /**
@@ -569,7 +559,7 @@ function writeToWire(write, authority) {
     : (object(write.value, ["kind", "fields"]), { kind: "live", fields: fieldsToWire(write.value.fields, 1, { nodes: 0 }) });
   if (write.value.kind !== "live" && write.value.kind !== "tombstone") throw new TypeError("Unsupported write kind.");
   if (value.kind === "live") validateNativeDocument(/** @type {readonly Json[]} */ (value.fields));
-  return { collection: requireDatabaseUuid(write.collection, "collection"), document: requireDatabaseUuid(write.document, "document"), schema_generation: requireDatabaseU64(write.schema_generation, "schema generation", true).toString(), schema_digest: hex(write.schema_digest, 32, "schema digest"), condition: conditionToWire(write.condition), observed: observedToWire(write.observed), value };
+  return { collection: requireDatabaseId(write.collection, "collection"), document: requireDatabaseId(write.document, "document"), schema_generation: requireDatabaseU64(write.schema_generation, "schema generation", true).toString(), schema_digest: hex(write.schema_digest, 32, "schema digest"), condition: conditionToWire(write.condition), observed: observedToWire(write.observed), value };
 }
 
 class Bytes {
@@ -603,7 +593,12 @@ class Bytes {
    * @param {string} value
    * @returns {void}
    */
-  uuid(value) { this.hex(value.replaceAll("-", "")); }
+  id(value) {
+    const alphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+    let bits = 0n;
+    for (const char of requireDatabaseId(value)) bits = (bits << 5n) | BigInt(alphabet.indexOf(char));
+    this.hex(bits.toString(16).padStart(32, "0"));
+  }
   /** @returns {Uint8Array} */
   finish() { const bytes = new Uint8Array(this.length); let offset = 0; for (const chunk of this.chunks) { bytes.set(chunk, offset); offset += chunk.length; } return bytes; }
 }
@@ -667,22 +662,22 @@ function validateNativeDocument(fields) {
 function effectBytes(scope, authority, writes) {
   const bytes = new Bytes();
   bytes.put(encoder.encode("TB-DOC-EFFECT-v1\0"));
-  bytes.uuid(requireDatabaseUuid(scope.tenant, "tenant")); bytes.uuid(requireDatabaseUuid(scope.database, "database")); bytes.integer(requireDatabaseU64(scope.shard, "shard"), 8);
+  bytes.id(requireDatabaseId(scope.tenant, "tenant")); bytes.id(requireDatabaseId(scope.database, "database")); bytes.integer(requireDatabaseU64(scope.shard, "shard"), 8);
   const singleWriter = authority.mode === "single_writer";
   bytes.integer(singleWriter ? 1n : 0n, 1);
   if (singleWriter) {
     const writer = object(authority.writer, ["replica", "incarnation"]);
-    bytes.integer(BigInt(/** @type {string} */ (authority.generation)), 8); bytes.uuid(/** @type {string} */ (writer.replica)); bytes.hex(/** @type {string} */ (writer.incarnation));
+    bytes.integer(BigInt(/** @type {string} */ (authority.generation)), 8); bytes.id(/** @type {string} */ (writer.replica)); bytes.hex(/** @type {string} */ (writer.incarnation));
   }
   bytes.integer(BigInt(writes.length), 8);
   for (const write of writes) {
-    bytes.uuid(/** @type {string} */ (write.collection)); bytes.uuid(/** @type {string} */ (write.document)); bytes.integer(BigInt(/** @type {string} */ (write.schema_generation)), 8); bytes.hex(/** @type {string} */ (write.schema_digest));
+    bytes.id(/** @type {string} */ (write.collection)); bytes.id(/** @type {string} */ (write.document)); bytes.integer(BigInt(/** @type {string} */ (write.schema_generation)), 8); bytes.hex(/** @type {string} */ (write.schema_digest));
     const condition = object(write.condition, ["kind"], ["version"]);
     bytes.integer(condition.kind === "none" ? 0n : condition.kind === "absent" ? 1n : 2n, 1);
     if (condition.kind === "version") bytes.hex(/** @type {string} */ (condition.version));
     const observed = array(write.observed);
     bytes.integer(BigInt(observed.length), 8);
-    for (const raw of observed) { const entry = object(raw, ["replica", "incarnation", "sequence"]); bytes.uuid(/** @type {string} */ (entry.replica)); bytes.hex(/** @type {string} */ (entry.incarnation)); bytes.integer(BigInt(/** @type {string} */ (entry.sequence)), 8); }
+    for (const raw of observed) { const entry = object(raw, ["replica", "incarnation", "sequence"]); bytes.id(/** @type {string} */ (entry.replica)); bytes.hex(/** @type {string} */ (entry.incarnation)); bytes.integer(BigInt(/** @type {string} */ (entry.sequence)), 8); }
     const value = object(write.value, ["kind"], ["fields"]);
     bytes.integer(value.kind === "tombstone" ? 0n : 1n, 1);
     if (value.kind === "live") {

package/src/database-types.js

@@ -1,20 +1,20 @@
 /**
- * The current TerraBase document protocol uses canonical UUID entity IDs.
- * @typedef {string} CanonicalUuid
+ * Entity identities are canonical uppercase ULIDs, including explicit local development.
+ * @typedef {import("./ids.js").EntityId} EntityId
  */
 
 /**
  * All 64-bit quantities stay bigint in JavaScript and decimal strings on the wire.
  * @typedef {{
- *   readonly tenant: CanonicalUuid;
- *   readonly database: CanonicalUuid;
+ *   readonly tenant: EntityId;
+ *   readonly database: EntityId;
  *   readonly shard: bigint;
  * }} DatabaseScope
  */
 
 /**
  * @typedef {{
- *   readonly collection: CanonicalUuid;
+ *   readonly collection: EntityId;
  *   readonly schema_generation: bigint;
  *   readonly schema_digest: string;
  * }} CollectionBinding
@@ -39,7 +39,7 @@
 
 /**
  * @typedef {{
- *   readonly replica: CanonicalUuid;
+ *   readonly replica: EntityId;
  *   readonly incarnation: string;
  *   readonly sequence: bigint;
  * }} DatabaseObserved
@@ -47,7 +47,7 @@
 
 /**
  * @typedef {DatabaseObserved & {
- *   readonly database: CanonicalUuid;
+ *   readonly database: EntityId;
  *   readonly shard: bigint;
  * }} DatabaseEvent
  */
@@ -58,7 +58,7 @@
  *   | {
  *     readonly mode: "single_writer";
  *     readonly generation: bigint;
- *     readonly writer: { readonly replica: CanonicalUuid; readonly incarnation: string };
+ *     readonly writer: { readonly replica: EntityId; readonly incarnation: string };
  *   }
  * )} DatabaseAuthority
  */
@@ -80,7 +80,7 @@
 
 /**
  * @typedef {CollectionBinding & {
- *   readonly document: CanonicalUuid;
+ *   readonly document: EntityId;
  *   readonly condition: DatabaseCondition;
  *   readonly observed: readonly DatabaseObserved[];
  *   readonly value: DatabaseWriteValue;
@@ -135,7 +135,7 @@
  * }} DatabaseQuery
  */
 
-/** @typedef {{ readonly document: CanonicalUuid; readonly point: DatabasePoint }} DatabaseQueryRow */
+/** @typedef {{ readonly document: EntityId; readonly point: DatabasePoint }} DatabaseQueryRow */
 
 /**
  * @typedef {{
@@ -202,7 +202,7 @@
  * )} DatabaseSubscriptionRequest
  */
 
-/** @typedef {{ readonly document: CanonicalUuid; readonly point: DatabasePoint | null }} DatabaseSubscriptionEffect */
+/** @typedef {{ readonly document: EntityId; readonly point: DatabasePoint | null }} DatabaseSubscriptionEffect */
 
 /**
  * @typedef {{

package/src/database-view.js

@@ -1,4 +1,4 @@
-import { encodeDatabaseSubscription, requireDatabaseUuid, requireDatabaseU64 } from "./database-codec.js";
+import { encodeDatabaseSubscription, requireDatabaseId, requireDatabaseU64 } from "./database-codec.js";
 /**
  * @import { TerraBaseClient } from "./local/legacy-client.js"
  * @import {
@@ -213,14 +213,14 @@ export class DatabaseSubscriptionView {
    */
   constructor(scope, options) {
     const capturedScope = Object.freeze({
-      tenant: requireDatabaseUuid(scope.tenant, "tenant"),
-      database: requireDatabaseUuid(scope.database, "database"),
+      tenant: requireDatabaseId(scope.tenant, "tenant"),
+      database: requireDatabaseId(scope.database, "database"),
       shard: requireDatabaseU64(scope.shard, "shard"),
     });
     const predicate = predicateCopy(options.predicate);
     const limit = boundedInteger(options.limit, 128, 128, "Snapshot page size");
     encodeDatabaseSubscription({ phase: "snapshot", predicate, limit });
-    this.binding = Object.freeze({ scope: capturedScope, collection: requireDatabaseUuid(options.collection, "collection"), predicate, limit });
+    this.binding = Object.freeze({ scope: capturedScope, collection: requireDatabaseId(options.collection, "collection"), predicate, limit });
     this.#maximumRows = boundedInteger(options.maximumRows, 10_000, 1_000_000, "Maximum rows");
   }
 
@@ -258,7 +258,7 @@ export class DatabaseSubscriptionView {
       if (response.rows.length > this.binding.limit) throw new DatabaseSubscriptionError("page_limit_exceeded");
       let previous = this.#snapshotRows.at(-1)?.document ?? "";
       const page = response.rows.map(row => {
-        const document = requireDatabaseUuid(row.document, "document");
+        const document = requireDatabaseId(row.document, "document");
         if (document <= previous) throw new DatabaseSubscriptionError("snapshot_order_invalid");
         previous = document;
         return Object.freeze({ document, point: pointCopy(row.point, this.binding.scope) });
@@ -293,7 +293,7 @@ export class DatabaseSubscriptionView {
       /** @type {Set<string>} */
       const documents = new Set();
       for (const effect of group.effects) {
-        const document = requireDatabaseUuid(effect.document, "document");
+        const document = requireDatabaseId(effect.document, "document");
         if (documents.has(document)) throw new DatabaseSubscriptionError("duplicate_group_document");
         documents.add(document);
         if (effect.point === null) rows.delete(document);

package/src/http.js

@@ -5,6 +5,7 @@ import {
   TsAuthEndpointDiscovery,
 } from "./ts-auth-discovery.js";
 import { parseDatabaseJson } from "./database-codec.js";
+import { validateTsAuthIds } from "./ts-auth-ids.js";
 /** @import { ResolvedTsAuthRuntimeConfig, TsAuthRuntimeConfig, FetchLike } from "./config.js" */
 /** @import { TerraScaleError, TerraScaleErrorCategory, TerraScaleResult, TerraScaleValidationIssue } from "./result.js" */
 
@@ -227,6 +228,15 @@ export class TsAuthHttp {
                 response.status,
                 response.headers,
               );
+            try {
+              validateTsAuthIds(parsed.value, options.routeName);
+            } catch {
+              return err(options.routeName, {
+                kind: "invalid-response", code: "invalid_response",
+                message: "ts-auth returned a noncanonical entity ID.", status: response.status,
+                requestId: requestIdFrom(response.headers),
+              }, response.status, response.headers);
+            }
             return ok(
               options.routeName,
               response.status,

package/src/ids.js

@@ -0,0 +1,22 @@
+import { isValid, monotonicFactory } from "ulid";
+
+/** A plain 26-character, uppercase Crockford ULID. @typedef {string} EntityId */
+
+const nextId = monotonicFactory();
+
+/** @returns {EntityId} Monotonic within a millisecond, including clock rollback. */
+export function generateId() {
+  return nextId();
+}
+
+/** @param {unknown} value @returns {value is EntityId} */
+export function isValidId(value) {
+  // The library also accepts lowercase and 130-bit overflow; the public contract does not.
+  return typeof value === "string" && isValid(value) && value === value.toUpperCase() && /^[0-7]/u.test(value);
+}
+
+/** @param {unknown} value @param {string} [name] @returns {EntityId} */
+export function requireId(value, name = "Entity ID") {
+  if (!isValidId(value)) throw new TypeError(`${name} must be a plain 26-character canonical uppercase Crockford ULID.`);
+  return value;
+}

package/src/index.js

@@ -19,7 +19,8 @@ export {
   isTerraBaseV1Error,
 } from "./v1/errors.js";
 export { v1Filter } from "./v1/filter.js";
-export { documentIdFor } from "./v1/ids.js";
+export { generateId, isValidId, requireId } from "./ids.js";
+/** @typedef {import("./ids.js").EntityId} EntityId */
 export { ExactDecimal } from "./v1/json.js";
 
 /** @typedef {import("./v1/transport.js").TerraBaseV1ClientConfig} TerraBaseV1ClientConfig */

package/src/local/better-auth.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { generateId, requireId } from "../ids.js";
 import { createAdapterFactory } from "@better-auth/core/db/adapter";
 /** @import { CleanedWhere, CustomAdapter, DBAdapter, JoinConfig } from "@better-auth/core/db/adapter" */
 /** @import { BetterAuthOptions } from "@better-auth/core" */
@@ -29,6 +29,8 @@ export function createLocalBetterAuthAdapter(store) {
    * @returns {DBAdapter<BetterAuthOptions>}
    */
   function make(options, scoped) {
+    if (options.advanced?.database?.generateId === "uuid")
+      throw new TypeError("Better Auth entity IDs must be ULIDs; UUID generation is unavailable.");
     /** @type {ReturnType<typeof createAdapterFactory<BetterAuthOptions>>} */
     const factory = createAdapterFactory({
       config: {
@@ -38,7 +40,7 @@ export function createLocalBetterAuthAdapter(store) {
         supportsArrays: true,
         supportsBooleans: true,
         supportsNumericIds: false,
-        supportsUUIDs: true,
+        customIdGenerator: generateId,
         transaction: async (callback) => {
           if (scoped)
             throw new Error("Nested local auth transactions are unavailable.");
@@ -65,7 +67,8 @@ function customAdapter(store, config, scoped) {
    * @param {string} model
    * @returns {Row[]}
    */
-  const rows = (model) => store.list("local-auth", model);
+  const rows = (model) => store.listEntries("local-auth", model)
+    .map(entry => ({ .../** @type {Row} */ (entry.value), id: requireId(entry.id) }));
   /**
    * @param {string} model
    * @param {readonly CleanedWhere[]} clauses
@@ -150,13 +153,21 @@ function customAdapter(store, config, scoped) {
    */
   const save = (model, input, creating = false) => {
     const row = jsonRow(input);
-    const id =
-      typeof row.id === "string" && row.id.length > 0 ? row.id : randomUUID();
+    const id = row.id === undefined ? generateId() : requireId(row.id);
+    for (const [logical, table] of Object.entries(config.schema)) {
+      if (config.getModelName(logical) !== model) continue;
+      for (const [field, schema] of Object.entries(table.fields)) {
+        if (schema.references?.field !== "id") continue;
+        const value = row[config.getFieldName({ model: logical, field })];
+        if (value !== undefined && value !== null) requireId(value, field);
+      }
+    }
     const candidate = { ...row, id };
     if (creating && store.get("local-auth", model, id) !== undefined)
       throw new LocalAuthConstraintError();
     ensureUnique(model, candidate);
-    store.put("local-auth", model, id, candidate);
+    delete row.id;
+    store.put("local-auth", model, id, row);
     return candidate;
   };
   /**

package/src/local/index.js

@@ -1,5 +1,5 @@
+import { generateId } from "../ids.js";
 import { isAbsolute } from "node:path";
-import { randomUUID } from "node:crypto";
 import { createTerraBaseClient } from "./legacy-client.js";
 import { normalizeLocalBearerToken } from "./authentication.js";
 import { assertLocalSqliteEnvironment } from "./environment.js";
@@ -86,7 +86,7 @@ export class TerraScaleSqliteRuntime {
       const scope =
         options.scope ??
         (stored === undefined
-          ? { tenant: randomUUID(), database: randomUUID(), shard: 0n }
+          ? { tenant: generateId(), database: generateId(), shard: 0n }
           : { ...stored, shard: BigInt(stored.shard) });
       this.#router = new TerraScaleLocalRouter(this.#store, scope, {
         authentication,

package/src/local/legacy-client.js

@@ -2,7 +2,7 @@
 import {
   decodeDatabaseCommitReceipt, decodeDatabasePoint, decodeDatabaseQueryPage,
   decodeDatabaseSubscription, decodeDatabaseStatus, encodeDatabaseStatus, encodeDatabaseCommit, encodeDatabaseQuery,
-  encodeDatabaseSubscription, encodeDatabaseAuthority, parseDatabaseJson, requireDatabaseU64, requireDatabaseUuid,
+  encodeDatabaseSubscription, encodeDatabaseAuthority, parseDatabaseJson, requireDatabaseU64, requireDatabaseId,
 } from "../database-codec.js";
 /**
  * @import {
@@ -61,7 +61,7 @@ function identityAuthority(authority) {
  * @returns {string}
  */
 function scopePath(scope) {
-  return `/v1/tenants/${requireDatabaseUuid(scope.tenant, "tenant")}/databases/${requireDatabaseUuid(scope.database, "database")}/shards/${requireDatabaseU64(scope.shard, "shard")}`;
+  return `/v1/tenants/${requireDatabaseId(scope.tenant, "tenant")}/databases/${requireDatabaseId(scope.database, "database")}/shards/${requireDatabaseU64(scope.shard, "shard")}`;
 }
 
 /**
@@ -195,7 +195,7 @@ export class TerraBaseClient {
 
   /** @param {TerraBaseClientConfig} config */
   constructor(config) {
-    this.#scope = Object.freeze({ tenant: requireDatabaseUuid(config.tenant, "tenant"), database: requireDatabaseUuid(config.database, "database"), shard: requireDatabaseU64(config.shard, "shard") });
+    this.#scope = Object.freeze({ tenant: requireDatabaseId(config.tenant, "tenant"), database: requireDatabaseId(config.database, "database"), shard: requireDatabaseU64(config.shard, "shard") });
     this.#config = { ...config };
     this.#fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.#path = scopePath(this.#scope);
@@ -214,7 +214,7 @@ export class TerraBaseClient {
    * @returns {Promise<DatabaseResult<DatabasePoint>>}
    */
   read(collection, document, options = {}) {
-    const path = `${this.#collectionPath(collection)}/documents/${requireDatabaseUuid(document, "document")}`;
+    const path = `${this.#collectionPath(collection)}/documents/${requireDatabaseId(document, "document")}`;
     return this.#request(path, "GET", undefined, raw => this.#scopedPoint(decodeDatabasePoint(raw)), options);
   }
 
@@ -312,7 +312,7 @@ export class TerraBaseClient {
    * @param {string} collection
    * @returns {string}
    */
-  #collectionPath(collection) { return `${this.#path}/collections/${requireDatabaseUuid(collection, "collection")}`; }
+  #collectionPath(collection) { return `${this.#path}/collections/${requireDatabaseId(collection, "collection")}`; }
 
   /**
    * @param {DatabasePoint} point

package/src/local/router.js

@@ -1,8 +1,8 @@
+import { generateId } from "../ids.js";
 import {
   createHash,
   createHmac,
   randomBytes,
-  randomUUID,
   timingSafeEqual,
 } from "node:crypto";
 import {
@@ -18,7 +18,7 @@ import {
   encodeDatabaseValue,
   parseDatabaseJson,
   requireDatabaseU64,
-  requireDatabaseUuid,
+  requireDatabaseId,
 } from "../database-codec.js";
 import { matchesLocalBearerAuthorization } from "./authentication.js";
 import { jsonResponse, problemResponse } from "./context.js";
@@ -101,8 +101,8 @@ export class TerraScaleLocalRouter {
   constructor(store, scope, options) {
     this.#store = store;
     this.#scope = Object.freeze({
-      tenant: requireDatabaseUuid(scope.tenant),
-      database: requireDatabaseUuid(scope.database),
+      tenant: requireDatabaseId(scope.tenant),
+      database: requireDatabaseId(scope.database),
       shard: requireDatabaseU64(scope.shard),
     });
     this.#scopeKey = `${scope.tenant}/${scope.database}/${scope.shard}`;
@@ -112,7 +112,7 @@ export class TerraScaleLocalRouter {
     const writer = /** @type {{ readonly replica: string; readonly incarnation: string } | undefined} */ (
       store.getMeta(`native-writer:${this.#scopeKey}`)
     ) ?? {
-      replica: randomUUID(),
+      replica: generateId(),
       incarnation: randomBytes(16).toString("hex"),
     };
     this.#writer = Object.freeze(writer);
@@ -131,7 +131,7 @@ export class TerraScaleLocalRouter {
    * @returns {void}
    */
   bindCollection(binding) {
-    requireDatabaseUuid(binding.collection);
+    requireDatabaseId(binding.collection);
     requireDatabaseU64(binding.schema_generation, "schema generation", true);
     if (!/^[0-9a-f]{64}$/u.test(binding.schema_digest))
       throw new TypeError("Schema digest must be lowercase SHA256.");
@@ -170,8 +170,8 @@ export class TerraScaleLocalRouter {
           suffix,
         );
         if (match === null) return problemResponse(404, "unknown_route");
-        const collection = requireDatabaseUuid(match[1]);
-        const document = requireDatabaseUuid(match[2]);
+        const collection = requireDatabaseId(match[1]);
+        const document = requireDatabaseId(match[2]);
         return await this.#store.exclusive(() => {
           this.#binding(collection);
           return jsonResponse(this.#point(collection, document));
@@ -246,7 +246,7 @@ export class TerraScaleLocalRouter {
           suffix,
         );
       if (match === null) return problemResponse(404, "unknown_route");
-      const collection = requireDatabaseUuid(match[1]);
+      const collection = requireDatabaseId(match[1]);
       return await this.#store.exclusive(() => {
         this.#binding(collection);
         return this.#query(collection, match[2] === "subscriptions", raw);
@@ -599,7 +599,7 @@ export class TerraScaleLocalRouter {
     let id;
     let offset = 0;
     if (cursorValue === undefined) {
-      id = randomUUID();
+      id = generateId();
       const rows = /** @type {readonly { readonly scope: string; readonly id: string; readonly value: WirePoint }[]} */ (
         this.#store.listNamespace("native-points")
       )
@@ -812,10 +812,10 @@ function decodeCommit(raw) {
       if (!Array.isArray(write.observed))
         throw new TypeError("Invalid observed.");
       return {
-        collection: requireDatabaseUuid(write.collection),
+        collection: requireDatabaseId(write.collection),
         schema_generation: decimal(write.schema_generation),
         schema_digest: text(write.schema_digest),
-        document: requireDatabaseUuid(write.document),
+        document: requireDatabaseId(write.document),
         condition: /** @type {DatabaseCondition} */ (parsedCondition),
         observed: write.observed.map((rawObserved) => {
           const observed = object(rawObserved);

package/src/local/store.js

@@ -2,7 +2,7 @@ import { mkdirSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { dirname, isAbsolute } from "node:path";
 
-const SCHEMA_VERSION = 1;
+const FORMAT_VERSION = 2;
 
 /**
  * A small synchronous JSON record store for Node local adapters.
@@ -55,7 +55,7 @@ export class TerraScaleSqliteStore {
       if (databasePath !== ":memory:") {
         this.#database.exec("PRAGMA journal_mode = WAL;");
       }
-      this.#migrate();
+      this.#initialize();
     } catch (error) {
       this.#database.close();
       this.#closed = true;
@@ -128,6 +128,25 @@ export class TerraScaleSqliteStore {
     return rows.map((row) => /** @type {T} */ (parseJson(row.value, "record")));
   }
 
+  /**
+   * @template T
+   * @param {string} namespace
+   * @param {string} scope
+   * @returns {readonly { readonly id: string; readonly value: T }[]}
+   */
+  listEntries(namespace, scope) {
+    this.#assertOpen();
+    assertKey(namespace, "namespace");
+    assertKey(scope, "scope");
+    const rows = this.#database
+      .prepare("SELECT id, value FROM records WHERE namespace = ? AND scope = ? ORDER BY id ASC")
+      .all(namespace, scope);
+    return rows.map(row => ({
+      id: String(row.id),
+      value: /** @type {T} */ (parseJson(row.value, "record")),
+    }));
+  }
+
   /**
    * @template T
    * @param {string} namespace
@@ -339,32 +358,18 @@ export class TerraScaleSqliteStore {
   }
 
   /** @returns {void} */
-  #migrate() {
+  #initialize() {
     this.#database.exec("BEGIN IMMEDIATE;");
     try {
-      this.#database.exec(`
-        CREATE TABLE IF NOT EXISTS schema_migrations (
-          version INTEGER NOT NULL PRIMARY KEY,
-          applied_at TEXT NOT NULL
-        ) WITHOUT ROWID;
-      `);
-
-      const row = this.#database
-        .prepare(
-          "SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1",
-        )
-        .get();
-      const version = row?.version;
-      if (version !== undefined && typeof version !== "number") {
-        throw new Error("Invalid schema migration version.");
-      }
-      if (version !== undefined && version > SCHEMA_VERSION) {
+      const version = this.#database.prepare("PRAGMA user_version").get()?.user_version;
+      const table = this.#database.prepare("SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get();
+      if (version !== FORMAT_VERSION && !(version === 0 && table === undefined)) {
         throw new Error(
-          `Database schema version ${version} is newer than supported version ${SCHEMA_VERSION}.`,
+          `TS-754: unsupported local SQLite format. Stop the local runtime, delete ${this.databasePath} and its -wal/-shm files, then restart with fresh ULID storage.`,
         );
       }
 
-      if (version === undefined) {
+      if (version === 0) {
         this.#database.exec(`
           CREATE TABLE records (
             namespace TEXT NOT NULL,
@@ -379,11 +384,7 @@ export class TerraScaleSqliteStore {
             value TEXT NOT NULL CHECK (json_valid(value) = 1)
           ) WITHOUT ROWID;
         `);
-        this.#database
-          .prepare(
-            "INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)",
-          )
-          .run(SCHEMA_VERSION, new Date().toISOString());
+        this.#database.exec(`PRAGMA user_version = ${FORMAT_VERSION}`);
       }
       this.#database.exec("COMMIT;");
     } catch (error) {
@@ -406,7 +407,7 @@ export class TerraScaleSqliteStore {
         );
       }
     } catch {
-      // Preserve the original work/migration exception. SQLite will normally
+      // Preserve the original operation exception. SQLite will normally
       // have already rolled back a failed transaction automatically.
     }
   }

package/src/local/test-environment.js

@@ -1,3 +1,4 @@
+import { generateId } from "../ids.js";
 import { assertLocalSqliteEnvironment } from "./environment.js";
 /** Local development tests never relax CI/deployment/qualification guards. */
 export const localSqliteUnitTestsAllowed = (() => {
@@ -11,7 +12,7 @@ export const localSqliteUnitTestsAllowed = (() => {
 import { mkdtemp, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { randomBytes, randomUUID } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { createTerraScaleSqliteRuntime } from "./index.js";
 /** @import { TerraScaleSqliteRuntimeOptions } from "./index.js" */
 /** @import { DatabaseCommit, DatabaseField, DatabasePoint } from "../database-types.js" */
@@ -25,7 +26,7 @@ export async function localFixture(options = {}) {
     ...options,
     sqlite: { enabled: true, databasePath },
   });
-  const collection = randomUUID();
+  const collection = generateId();
   const binding = {
     collection,
     schema_generation: 1n,