@terrascale/sdk 0.0.2 → 0.0.3

package/src/v1/decode.js

@@ -1,5 +1,5 @@
 // Typed decoding of TerraBase v1 response bodies.
-import { parseU64, requireVersion } from "./ids.js";
+import { parseU64, requireDocumentId, requireVersion } from "./ids.js";
 import { isJsonObject } from "./json.js";
 /** @import { JsonObject, JsonValue } from "./json.js" */
 
@@ -8,17 +8,17 @@ import { isJsonObject } from "./json.js";
  * `document` is the value, or the LWW winner when a causal read answers `"conflict"` with `siblings`.
  * Unknown future states pass through.
  * @typedef {object} V1Document
- * @property {string} id
+ * @property {import("../ids.js").EntityId} id
  * @property {string} version
  * @property {"value" | "conflict" | (string & {})} state
  * @property {JsonObject} document
- * @property {readonly JsonValue[]} [siblings] Every live version, on a causal read with several.
+ * @property {readonly JsonValue[]} [siblings] Live versions and tombstones on a causal conflict.
  */
 
 /**
  * The result of a document write.
  * @typedef {object} V1WriteResult
- * @property {string} id
+ * @property {import("../ids.js").EntityId} id
  * @property {string} version For a delete, the tombstone's version.
  * @property {string} offset The database commit offset (decimal u64), usable with shape `waitFor`.
  * @property {V1Durability} durability
@@ -43,6 +43,13 @@ export function object(value, what) {
   return isJsonObject(value) ? value : malformed(what);
 }
 
+/** @param {JsonValue | undefined} value @returns {JsonObject} */
+export function documentObject(value) {
+  const document = object(value, "document body");
+  if (Object.hasOwn(document, "id")) malformed("document body: the entity ID belongs in the document key");
+  return document;
+}
+
 /**
  * @param {JsonValue | undefined} value
  * @param {string} what
@@ -93,12 +100,17 @@ export function durability(value) {
  */
 export function decodeDocument(value) {
   const raw = object(value, "document");
-  const id = string(raw.id, "document id");
+  const id = requireDocumentId(raw.id);
   const version = requireVersion(raw.version);
   const state = string(raw.state, "document state");
-  const document = object(raw.document, "document body");
+  const document = documentObject(raw.document);
   if (raw.siblings === undefined) return Object.freeze({ id, version, state, document });
-  return Object.freeze({ id, version, state, document, siblings: Object.freeze(array(raw.siblings, "document siblings")) });
+  const siblings = array(raw.siblings, "document siblings");
+  for (const sibling of siblings) {
+    const entry = object(sibling, "document sibling");
+    if (entry.deleted !== true || entry.document !== undefined) documentObject(entry.document);
+  }
+  return Object.freeze({ id, version, state, document, siblings: Object.freeze(siblings) });
 }
 
 /**
@@ -108,7 +120,7 @@ export function decodeDocument(value) {
 export function decodeWrite(response) {
   const raw = object(response.value, "write result");
   return Object.freeze({
-    id: string(raw.id, "write id"),
+    id: requireDocumentId(raw.id),
     version: requireVersion(raw.version),
     offset: u64(raw.offset, "write offset"),
     durability: durability(raw.durability),

package/src/v1/ids.js

@@ -1,4 +1,5 @@
-// Identifiers for the TerraBase v1 Documents API (api-v1.md).
+// Identifiers for the TerraBase v1 Documents API.
+import { requireId } from "../ids.js";
 
 const namePattern = /^[a-z][a-z0-9_-]{0,62}$/u;
 // Version tokens are opaque (tbv1-<32 hex>, tbv2-...): only RFC 9110 opaque-tag characters, safe to quote in If-Match.
@@ -6,12 +7,6 @@ const versionPattern = /^[\x21\x23-\x7e]{1,256}$/u;
 const offsetPattern = /^(?:0|[1-9]\d{0,19})$/u;
 const maximumU64 = (1n << 64n) - 1n;
 
-/** RFC 9562 NAMESPACE_URL, 6ba7b811-9dad-11d1-80b4-00c04fd430c8. */
-const namespaceUrl = Uint8Array.of(
-  0x6b, 0xa7, 0xb8, 0x11, 0x9d, 0xad, 0x11, 0xd1,
-  0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
-);
-
 /**
  * @param {"database" | "collection"} kind
  * @param {unknown} name
@@ -24,24 +19,17 @@ export function requireName(kind, name) {
 }
 
 /**
- * The producer resolves this opaque catalog project id (normally a UUID), not its display name.
+ * The catalog project ID is a canonical ULID; database and collection routes use names.
  * @param {unknown} project
- * @returns {string}
+ * @returns {import("../ids.js").EntityId}
  */
 export function requireProject(project) {
-  if (typeof project !== "string" || project === "" || project === "." || project === ".." || /[\p{Cc}\uD800-\uDFFF]/u.test(project))
-    throw new TypeError("project must be a non-empty catalog project ID without control characters or dot path segments.");
-  return project;
+  return requireId(project);
 }
 
-/**
- * @param {unknown} id
- * @returns {string}
- */
+/** @param {unknown} id @returns {import("../ids.js").EntityId} */
 export function requireDocumentId(id) {
-  if (typeof id !== "string" || id.length < 1 || id.length > 256 || /[\p{Cc}]/u.test(id) || /[\uD800-\uDFFF]/u.test(id) || id === "." || id === "..")
-    throw new TypeError("Document IDs must be 1-256 characters without control characters or dot path segments; new IDs must be lowercase UUIDs.");
-  return id;
+  return requireId(id);
 }
 
 /**
@@ -76,44 +64,3 @@ export function requireU64(value, what) {
   if (parsed === undefined) throw new TypeError(`${what} must be a u64: a canonical decimal string or bigint.`);
   return parsed;
 }
-
-/**
- * @param {Uint8Array} namespace
- * @param {string} name
- * @returns {Promise<Uint8Array>}
- */
-async function uuidV5(namespace, name) {
-  const encoded = new TextEncoder().encode(name);
-  const input = new Uint8Array(namespace.length + encoded.length);
-  input.set(namespace);
-  input.set(encoded, namespace.length);
-  const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-1", input));
-  const uuid = digest.slice(0, 16);
-  uuid[6] = ((uuid[6] ?? 0) & 0x0f) | 0x50;
-  uuid[8] = ((uuid[8] ?? 0) & 0x3f) | 0x80;
-  return uuid;
-}
-
-/**
- * @param {Uint8Array} bytes
- * @returns {string}
- */
-function formatUuid(bytes) {
-  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-
-/**
- * The deterministic document ID for a natural key in a collection:
- * `uuidv5(uuidv5(NAMESPACE_URL, "terrabase:collection:" + collection), key)`.
- * Uses WebCrypto, so it works in Node.js, browsers and workers.
- * @param {string} collection
- * @param {string} key
- * @returns {Promise<string>}
- */
-export async function documentIdFor(collection, key) {
-  requireName("collection", collection);
-  if (typeof key !== "string") throw new TypeError("The natural key must be a string.");
-  const namespace = await uuidV5(namespaceUrl, `terrabase:collection:${collection}`);
-  return formatUuid(await uuidV5(namespace, key));
-}

package/src/v1/routes.js

@@ -1,4 +1,4 @@
-// Routes owned by the C# Documents API at 0248ad3 (decision 0004 and shape-reads.md).
+// Routes owned by the C# Documents API at 6cb9745 (decision 0004 and shape-reads.md).
 /** @typedef {"getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape"} V1Operation */
 /**
  * @typedef {object} V1Route
@@ -20,11 +20,11 @@ const collection = `${collections}/{collection}`;
 const documents = `${collection}/documents`;
 /** @type {readonly V1Route[]} */
 export const v1Routes = Object.freeze(/** @type {V1Route[]} */ ([
-  { operation: "getDocument", method: "GET", pathTemplate: `${documents}/{id}`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
-  { operation: "putDocument", method: "PUT", pathTemplate: `${documents}/{id}`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [200, 201] },
+  { operation: "getDocument", method: "GET", pathTemplate: `${documents}/by-key`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "putDocument", method: "PUT", pathTemplate: `${documents}/by-key`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [200, 201] },
   { operation: "createDocument", method: "POST", pathTemplate: documents, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
-  { operation: "patchDocument", method: "PATCH", pathTemplate: `${documents}/{id}`, permission: "documents:write", requestMediaTypes: ["application/merge-patch+json", "application/vnd.terrabase.ops+json"], successStatuses: [200] },
-  { operation: "deleteDocument", method: "DELETE", pathTemplate: `${documents}/{id}`, permission: "documents:write", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "patchDocument", method: "PATCH", pathTemplate: `${documents}/by-key`, permission: "documents:write", requestMediaTypes: ["application/merge-patch+json", "application/vnd.terrabase.ops+json"], successStatuses: [200] },
+  { operation: "deleteDocument", method: "DELETE", pathTemplate: `${documents}/by-key`, permission: "documents:write", requestMediaTypes: [], successStatuses: [200] },
   { operation: "commitTransaction", method: "POST", pathTemplate: `${database}/transactions`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [200] },
   { operation: "queryDocuments", method: "POST", pathTemplate: `${collection}/query`, permission: "documents:read", requestMediaTypes: ["application/json"], successStatuses: [200] },
   { operation: "createCollection", method: "POST", pathTemplate: collections, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [201] },

package/src/v1/shapes.js

@@ -1,7 +1,7 @@
 // Current C# GET collection/shape contract (docs/shape-reads.md).
-import { array, boolean, malformed, object, string, u64 } from "./decode.js";
+import { array, boolean, documentObject, malformed, object, string, u64 } from "./decode.js";
 import { requireFilter } from "./filter.js";
-import { parseU64, requireVersion } from "./ids.js";
+import { parseU64, requireDocumentId, requireVersion } from "./ids.js";
 import { stringifyExactJson } from "./json.js";
 /**
  * @import { JsonObject, JsonValue } from "./json.js"
@@ -16,7 +16,7 @@ import { stringifyExactJson } from "./json.js";
  * @property {boolean | undefined} [live] True only for log positions; waits up to 20 seconds.
  * @property {string | undefined} [cursor] Previous live response's TB-Shape-Cursor.
  */
-/** @typedef {{ readonly op: "upsert"; readonly id: string; readonly version: string; readonly document: JsonObject } | { readonly op: "delete"; readonly id: string }} V1ShapeOp */
+/** @typedef {{ readonly op: "upsert"; readonly id: import("../ids.js").EntityId; readonly version: string; readonly document: JsonObject } | { readonly op: "delete"; readonly id: import("../ids.js").EntityId }} V1ShapeOp */
 /** @typedef {{ readonly offset: string; readonly ops: readonly V1ShapeOp[] }} V1ShapeChange */
 /**
  * One snapshot page or log chunk. Only a fresh open tail/live response can report upToDate.
@@ -53,7 +53,7 @@ export function requireShapeOffset(value) {
       const bytes = Uint8Array.from(atob(encoded.replace(/-/gu, "+").replace(/_/gu, "/")), c => c.charCodeAt(0));
       const id = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
       const canonical = btoa(String.fromCharCode(...new TextEncoder().encode(id))).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/u, "");
-      if (canonical === encoded) return value;
+      if (canonical === encoded) { requireDocumentId(id); return value; }
     } catch { /* Invalid base64url or UTF-8. */ }
   }
   throw new TypeError("A shape offset is -1, a signed-64-bit decimal log position, or snap.<head>.<canonical-base64url-id>.");
@@ -102,11 +102,10 @@ export function decodeShapePage(value, headers) {
       const change = object(value, "shape change");
       return Object.freeze({ offset: u64(change.offset, "shape change offset"), ops: Object.freeze(array(change.ops, "shape operations").map(value => {
         const op = object(value, "shape operation");
-        // Shape snapshots can include stored legacy ids beyond the HTTP point-id limit.
-        const id = string(op.id, "shape document id");
+        const id = requireDocumentId(op.id);
         if (op.op === "delete") return Object.freeze({ op: /** @type {const} */ ("delete"), id });
         if (op.op !== "upsert") malformed("shape operation kind");
-        return Object.freeze({ op: /** @type {const} */ ("upsert"), id, version: requireVersion(op.version), document: object(op.document, "shape document") });
+        return Object.freeze({ op: /** @type {const} */ ("upsert"), id, version: requireVersion(op.version), document: documentObject(op.document) });
       })) });
     })),
   });

package/src/v1/terrabase-v1.js

@@ -94,6 +94,8 @@ function pointer(path) {
  */
 function patchOp(op) {
   if (typeof op !== "object" || op === null || Array.isArray(op)) throw new TypeError("A patch op is an object.");
+  if (op.path === "/id" || op.path?.startsWith("/id/")) throw new TypeError("The document key is the entity ID; payloads must not contain an id field.");
+  if (op.path === "" && op.op === "set") assertNoPayloadId(op.value);
   let allowed = ["op", "path", "value"];
   switch (op.op) {
     case "unset": allowed = ["op", "path"]; break;
@@ -133,6 +135,7 @@ function normalizePatch(patch) {
   if (hasMerge) {
     const merge = /** @type {{ readonly merge: JsonInputObject }} */ (patch).merge;
     assertJsonObject(merge, "merge patch");
+    assertNoPayloadId(merge);
     return { merge };
   }
   const ops = /** @type {{ readonly ops: readonly V1PatchOp[] }} */ (patch).ops;
@@ -228,11 +231,18 @@ function rejectIdempotency(options) {
 /** @param {JsonInputObject} document @returns {string} */
 function encodeDocument(document) {
   assertJsonObject(document, "document");
+  assertNoPayloadId(document);
   const body = stringifyExactJson(document, "document");
   if (new TextEncoder().encode(body).byteLength > 1024 * 1024) throw new TypeError("A document is at most 1 MiB.");
   return body;
 }
 
+/** @param {unknown} document @returns {void} */
+function assertNoPayloadId(document) {
+  if (typeof document === "object" && document !== null && Object.hasOwn(document, "id"))
+    throw new TypeError("The document key is the entity ID; payloads must not contain an id field.");
+}
+
 /** A collection handle by name. It performs no I/O until an operation runs. */
 export class V1Collection {
   /** @type {V1Transport} */
@@ -258,11 +268,12 @@ export class V1Collection {
   }
 
   /**
+   * The by-key route takes the raw document ID in the query, not the path.
    * @param {string} id
-   * @returns {Readonly<Record<string, string>>}
+   * @returns {URLSearchParams}
    */
-  #document(id) {
-    return { ...this.#params, id: requireDocumentId(id) };
+  #documentKey(id) {
+    return new URLSearchParams({ id: requireDocumentId(id) });
   }
 
   /**
@@ -276,7 +287,7 @@ export class V1Collection {
     /** @type {Record<string, string>} */
     const headers = {};
     if (options.ifNoneMatch !== undefined) headers["if-none-match"] = `"${requireVersion(options.ifNoneMatch)}"`;
-    const response = await this.#transport.call("getDocument", this.#document(id), { headers, signal: options.signal });
+    const response = await this.#transport.call("getDocument", this.#params, { query: this.#documentKey(id), headers, signal: options.signal });
     return decodeDocument(response.value);
   }
 
@@ -288,15 +299,14 @@ export class V1Collection {
    * @returns {Promise<V1WriteResult>}
    */
   async put(id, document, options = {}) {
-    const params = this.#document(id);
     const headers = preconditionHeaders(options, true);
-    return decodeWrite(await this.#transport.call("putDocument", params, {
-      body: encodeDocument(document), headers, signal: options.signal,
+    return decodeWrite(await this.#transport.call("putDocument", this.#params, {
+      query: this.#documentKey(id), body: encodeDocument(document), headers, signal: options.signal,
     }));
   }
 
   /**
-   * Creates a document under a server-generated UUIDv7.
+   * Creates a document under a server-generated ULID.
    * @param {JsonInputObject} document
    * @param {V1CreateOptions} [options]
    * @returns {Promise<V1WriteResult>}
@@ -315,14 +325,13 @@ export class V1Collection {
    * @returns {Promise<V1WriteResult>}
    */
   async patch(id, patch, options = {}) {
-    const params = this.#document(id);
     const headers = preconditionHeaders(options, false);
     const normalized = normalizePatch(patch);
     const [contentType, body] = "merge" in normalized
       ? ["application/merge-patch+json", stringifyExactJson(normalized.merge, "merge patch")]
       : ["application/vnd.terrabase.ops+json", stringifyExactJson({ ops: normalized.ops }, "patch ops")];
-    return decodeWrite(await this.#transport.call("patchDocument", params, {
-      body, contentType, headers,
+    return decodeWrite(await this.#transport.call("patchDocument", this.#params, {
+      query: this.#documentKey(id), body, contentType, headers,
       signal: options.signal,
     }));
   }
@@ -334,10 +343,9 @@ export class V1Collection {
    * @returns {Promise<V1WriteResult>}
    */
   async delete(id, options = {}) {
-    const params = this.#document(id);
     const headers = preconditionHeaders(options, false);
-    return decodeWrite(await this.#transport.call("deleteDocument", params, {
-      headers, signal: options.signal,
+    return decodeWrite(await this.#transport.call("deleteDocument", this.#params, {
+      query: this.#documentKey(id), headers, signal: options.signal,
     }));
   }
 
@@ -459,7 +467,7 @@ export class V1Transaction {
 
   /**
    * Adds a create (a put requiring absence). Omit `id` to have the server
-   * generate a UUIDv7, returned in the op's result.
+   * generate a ULID, returned in the op's result.
    * @param {string} collection
    * @param {JsonInputObject} document
    * @param {string} [id]
@@ -690,7 +698,7 @@ export class V1Database {
 }
 
 /**
- * A TerraBase v1 data-plane client for one project and `tb_` API key. The key is held
+ * A TerraBase v1 data-plane client for one project and access token. The token is held
  * privately; it is never serialized, logged or forwarded to redirects.
  */
 export class TerraBaseV1Client {

package/src/v1/transport.js

@@ -15,7 +15,9 @@ import { v1Route, v1RoutePath } from "./routes.js";
 export const maximumRequestBytes = 4 * 1024 * 1024;
 // Query budgets count stored JSON before wrappers and serializer escaping.
 const defaultMaximumResponseBytes = 64 * 1024 * 1024;
-const tokenPattern = /^tb_[A-Za-z0-9_-]{43}$/u;
+// Validate header-safe credential syntax only; the producer validates JWT claims/signatures.
+// Retain C# keys while the published TS-589 JWT contract awaits a producer release.
+const tokenPattern = /^(?!tbk1\.)(?:[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+|tb_[A-Za-z0-9_-]{43})$/u;
 /**
  * Resolver input contains no credential. A successful URL is cached for this client/database.
  * @typedef {{ readonly project: string; readonly database: string; readonly signal?: AbortSignal | undefined }} V1EndpointContext
@@ -26,7 +28,7 @@ const tokenPattern = /^tb_[A-Za-z0-9_-]{43}$/u;
  * URLs must use HTTPS or loopback HTTP. Mutations are never automatically replayed.
  * @typedef {object} TerraBaseV1ClientConfig
  * @property {string} project
- * @property {string} token A tb_ API key; held privately.
+ * @property {string} token A ts-auth project access JWT (or a legacy C# tb_ key); held privately.
  * @property {string | undefined} [baseUrl]
  * @property {V1EndpointResolver | undefined} [endpointResolver]
  * @property {FetchLike | undefined} [fetch]
@@ -123,7 +125,7 @@ export class BodyTransportError extends Error {
   }
 }
 
-/** Internal transport bound to one data key. */
+/** Internal transport bound to one project credential. */
 export class V1Transport {
   /** @type {string} */
   #project;
@@ -148,7 +150,7 @@ export class V1Transport {
       throw new TypeError("endpointResolver must be a function.");
     this.#resolver = config.endpointResolver ?? staticBaseUrlResolver(/** @type {string} */ (config.baseUrl));
     if (typeof config.token !== "string" || !tokenPattern.test(config.token))
-      throw new TypeError("token must be a tb_ API key with 43 base64url characters.");
+      throw new TypeError("token must be a compact access JWT or a legacy C# tb_ API key.");
     if ("autoIdempotencyKey" in config || "maxRetries" in config || "resolver" in config)
       throw new TypeError("Unsupported client configuration member.");
     const fetchHandler = config.fetch ?? globalThis.fetch?.bind(globalThis);

package/types/database-codec.d.ts

@@ -1,9 +1,3 @@
-/**
- * @param {unknown} value
- * @param {string} [name]
- * @returns {string}
- */
-export function requireDatabaseUuid(value: unknown, name?: string): string;
 /**
  * @param {unknown} value
  * @param {string} [name]
@@ -88,6 +82,7 @@ export function encodeDatabaseCommit(scope: DatabaseScope, commit: DatabaseCommi
     readonly body: string;
     readonly effect_digest: string;
 }>;
+export { requireId as requireDatabaseId } from "./ids.js";
 export type Budget = {
     nodes: number;
 };

package/types/database-types.d.ts

@@ -1,17 +1,17 @@
 /**
- * The current TerraBase document protocol uses canonical UUID entity IDs.
+ * Entity identities are canonical uppercase ULIDs, including explicit local development.
  */
-export type CanonicalUuid = string;
+export type EntityId = import("./ids.js").EntityId;
 /**
  * All 64-bit quantities stay bigint in JavaScript and decimal strings on the wire.
  */
 export type DatabaseScope = {
-    readonly tenant: CanonicalUuid;
-    readonly database: CanonicalUuid;
+    readonly tenant: EntityId;
+    readonly database: EntityId;
     readonly shard: bigint;
 };
 export type CollectionBinding = {
-    readonly collection: CanonicalUuid;
+    readonly collection: EntityId;
     readonly schema_generation: bigint;
     readonly schema_digest: string;
 };
@@ -44,12 +44,12 @@ export type DatabaseField = {
     readonly value: DatabaseValue;
 };
 export type DatabaseObserved = {
-    readonly replica: CanonicalUuid;
+    readonly replica: EntityId;
     readonly incarnation: string;
     readonly sequence: bigint;
 };
 export type DatabaseEvent = DatabaseObserved & {
-    readonly database: CanonicalUuid;
+    readonly database: EntityId;
     readonly shard: bigint;
 };
 export type DatabaseAuthority = ({
@@ -58,7 +58,7 @@ export type DatabaseAuthority = ({
     readonly mode: "single_writer";
     readonly generation: bigint;
     readonly writer: {
-        readonly replica: CanonicalUuid;
+        readonly replica: EntityId;
         readonly incarnation: string;
     };
 });
@@ -77,7 +77,7 @@ export type DatabaseWriteValue = ({
     readonly kind: "tombstone";
 });
 export type DatabaseWrite = CollectionBinding & {
-    readonly document: CanonicalUuid;
+    readonly document: EntityId;
     readonly condition: DatabaseCondition;
     readonly observed: readonly DatabaseObserved[];
     readonly value: DatabaseWriteValue;
@@ -121,7 +121,7 @@ export type DatabaseQuery = {
     readonly cursor?: string;
 };
 export type DatabaseQueryRow = {
-    readonly document: CanonicalUuid;
+    readonly document: EntityId;
     readonly point: DatabasePoint;
 };
 export type DatabaseQueryPage = {
@@ -188,7 +188,7 @@ export type DatabaseSubscriptionRequest = ({
     readonly poll_cursor: string;
 });
 export type DatabaseSubscriptionEffect = {
-    readonly document: CanonicalUuid;
+    readonly document: EntityId;
     readonly point: DatabasePoint | null;
 };
 export type DatabaseSubscriptionGroup = {

package/types/ids.d.ts

@@ -0,0 +1,10 @@
+/** @returns {EntityId} Monotonic within a millisecond, including clock rollback. */
+export function generateId(): EntityId;
+/** @param {unknown} value @returns {value is EntityId} */
+export function isValidId(value: unknown): value is EntityId;
+/** @param {unknown} value @param {string} [name] @returns {EntityId} */
+export function requireId(value: unknown, name?: string): EntityId;
+/**
+ * A plain 26-character, uppercase Crockford ULID.
+ */
+export type EntityId = string;

package/types/index.d.ts

@@ -1,7 +1,7 @@
 export { v1Filter } from "./v1/filter.js";
-export { documentIdFor } from "./v1/ids.js";
 export { ExactDecimal } from "./v1/json.js";
 export { staticBaseUrlResolver } from "./v1/transport.js";
+export type EntityId = import("./ids.js").EntityId;
 export type TerraBaseV1ClientConfig = import("./v1/transport.js").TerraBaseV1ClientConfig;
 export type V1RequestOptions = import("./v1/terrabase-v1.js").V1RequestOptions;
 export type V1ReadOptions = import("./v1/terrabase-v1.js").V1ReadOptions;
@@ -41,3 +41,4 @@ export type V1ShapePage = import("./v1/shapes.js").V1ShapePage;
 export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient, createTerraBaseV1Client, TerraBaseV1Client, V1Database, V1Collection, V1Collections, V1Transaction } from "./v1/terrabase-v1.js";
 export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
 export { TerraBaseV1Error, V1PreconditionFailedError, V1InvalidKeyError, V1ForbiddenScopeError, V1NotFoundError, V1ErrorCode, isTerraBaseV1Error } from "./v1/errors.js";
+export { generateId, isValidId, requireId } from "./ids.js";

package/types/local/store.d.ts

@@ -34,6 +34,16 @@ export class TerraScaleSqliteStore {
      * @returns {T[]}
      */
     list<T>(namespace: string, scope: string): T[];
+    /**
+     * @template T
+     * @param {string} namespace
+     * @param {string} scope
+     * @returns {readonly { readonly id: string; readonly value: T }[]}
+     */
+    listEntries<T>(namespace: string, scope: string): readonly {
+        readonly id: string;
+        readonly value: T;
+    }[];
     /**
      * @template T
      * @param {string} namespace

package/types/local/test-environment.d.ts

@@ -6,9 +6,9 @@
 export function localFixture(options?: Omit<TerraScaleSqliteRuntimeOptions, "sqlite">): Promise<{
     runtime: import("./index.js").TerraScaleSqliteRuntime;
     client: import("./legacy-client.js").TerraBaseClient;
-    collection: `${string}-${string}-${string}-${string}-${string}`;
+    collection: string;
     binding: {
-        collection: `${string}-${string}-${string}-${string}-${string}`;
+        collection: string;
         schema_generation: bigint;
         schema_digest: string;
     };

package/types/postgres.d.ts

@@ -25,8 +25,8 @@ export function postgresQuery(statement: string, parameters?: readonly unknown[]
  *   readonly port: number;
  *   readonly tlsServerName: string;
  *   readonly caCertificatePem: string;
- *   readonly database: string;
- *   readonly keyId: string;
+ *   readonly database: import("./ids.js").EntityId;
+ *   readonly keyId: import("./ids.js").EntityId;
  *   readonly password: string;
  *   readonly connectTimeoutMs?: number;
  * }} PostgresConfig
@@ -107,8 +107,8 @@ export type PostgresConfig = {
     readonly port: number;
     readonly tlsServerName: string;
     readonly caCertificatePem: string;
-    readonly database: string;
-    readonly keyId: string;
+    readonly database: import("./ids.js").EntityId;
+    readonly keyId: import("./ids.js").EntityId;
     readonly password: string;
     readonly connectTimeoutMs?: number;
 };

package/types/ts-auth-ids.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Validate the documented endpointId:eventId delivery selector.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function requireDeadLetterId(value: unknown): string;
+/**
+ * Validate identity fields in the hosted-auth DTOs without inspecting customer metadata.
+ * @param {unknown} value
+ * @param {string} route
+ * @param {boolean} [entity]
+ * @returns {void}
+ */
+export function validateTsAuthIds(value: unknown, route: string, entity?: boolean): void;